Embedded Flash Service

The Embedded Flash service provides functions for internal flash operations.

Macros
#define	GPNVM_NUM_MAX   2

Functions
static void	compute_address (Efc *p_efc, uint16_t us_page, uint16_t us_offset, uint32_t *pul_addr)
	Compute the address of a flash by the given page and offset. More...
static void	compute_lock_range (uint32_t ul_start, uint32_t ul_end, uint32_t *pul_actual_start, uint32_t *pul_actual_end)
	Compute the lock range associated with the given address range. More...
uint32_t	flash_clear_gpnvm (uint32_t ul_gpnvm)
	Clear the given GPNVM bit. More...
uint32_t	flash_enable_security_bit (void)
	Set security bit. More...
uint32_t	flash_erase_all (uint32_t ul_address)
	Erase the entire flash. More...
uint32_t	flash_get_descriptor (uint32_t ul_address, uint32_t *pul_flash_descriptor, uint32_t ul_size)
	Get flash descriptor. More...
uint32_t	flash_get_page_count (const uint32_t *pul_flash_descriptor)
	Get flash total page count for the specified bank. More...
uint32_t	flash_get_page_count_per_region (const uint32_t *pul_flash_descriptor)
	Get flash page count per region (plane) for the specified bank. More...
uint32_t	flash_get_region_count (const uint32_t *pul_flash_descriptor)
	Get flash region (plane) count for the specified bank. More...
uint32_t	flash_get_wait_state (uint32_t ul_address)
	Get flash wait state. More...
uint32_t	flash_init (uint32_t ul_mode, uint32_t ul_fws)
	Initialize the flash service. More...
uint32_t	flash_is_gpnvm_set (uint32_t ul_gpnvm)
	Check if the given GPNVM bit is set or not. More...
uint32_t	flash_is_locked (uint32_t ul_start, uint32_t ul_end)
	Get the number of locked regions inside the given address range. More...
uint32_t	flash_is_security_bit_enabled (void)
	Check if the security bit is set or not. More...
uint32_t	flash_lock (uint32_t ul_start, uint32_t ul_end, uint32_t *pul_actual_start, uint32_t *pul_actual_end)
	Lock all the regions in the given address range. More...
uint32_t	flash_read_unique_id (uint32_t *pul_data, uint32_t ul_size)
	Read the flash unique ID. More...
uint32_t	flash_set_gpnvm (uint32_t ul_gpnvm)
	Set the given GPNVM bit. More...
uint32_t	flash_set_wait_state (uint32_t ul_address, uint32_t ul_fws)
	Set flash wait state. More...
uint32_t	flash_set_wait_state_adaptively (uint32_t ul_address)
	Set flash wait state. More...
uint32_t	flash_unlock (uint32_t ul_start, uint32_t ul_end, uint32_t *pul_actual_start, uint32_t *pul_actual_end)
	Unlock all the regions in the given address range. More...
uint32_t	flash_write (uint32_t ul_address, const void *p_buffer, uint32_t ul_size, uint32_t ul_erase_flag)
	Write a data buffer on flash. More...
static void	translate_address (Efc **pp_efc, uint32_t ul_addr, uint16_t *pus_page, uint16_t *pus_offset)
	Translate the given flash address to page and offset values. More...

Variables
static uint32_t	gs_ul_page_buffer [IFLASH_PAGE_SIZE/sizeof(uint32_t)]

#define GPNVM_NUM_MAX   2

Referenced by flash_clear_gpnvm(), flash_is_gpnvm_set(), and flash_set_gpnvm().

static void compute_address ( Efc *  p_efc, uint16_t  us_page, uint16_t  us_offset, uint32_t *  pul_addr  )

static

Compute the address of a flash by the given page and offset.

Parameters

p_efc	Pointer to an EFC instance.
us_page	Page number.
us_offset	Byte offset inside page.
pul_addr	Computed address (optional).

References flash_is_gpnvm_set(), FLASH_RC_YES, and UNUSED.

Referenced by flash_write().

static void compute_lock_range ( uint32_t  ul_start, uint32_t  ul_end, uint32_t *  pul_actual_start, uint32_t *  pul_actual_end  )

static

Compute the lock range associated with the given address range.

Parameters

ul_start	Start address of lock range.
ul_end	End address of lock range.
pul_actual_start	Actual start address of lock range.
pul_actual_end	Actual end address of lock range.

Referenced by flash_lock(), and flash_unlock().

uint32_t flash_clear_gpnvm

(

uint32_t

ul_gpnvm

)

Clear the given GPNVM bit.

Parameters

ul_gpnvm

GPNVM bit index.

Returns

0 if successful; otherwise returns an error code.

References EFC_FCMD_CGPB, efc_perform_command(), EFC_RC_OK, flash_is_gpnvm_set(), FLASH_RC_ERROR, FLASH_RC_INVALID, FLASH_RC_NO, FLASH_RC_OK, and GPNVM_NUM_MAX.

uint32_t flash_enable_security_bit

(

void

)

Set security bit.

Returns

0 if successful; otherwise returns an error code.

References flash_set_gpnvm().

uint32_t flash_erase_all

(

uint32_t

ul_address

)

Erase the entire flash.

Note

Only the flash bank including ul_address will be erased. If there are two flash banks, we need to call this function twice with each bank start address.

Parameters

ul_address

Flash bank start address.

Returns

0 if successful; otherwise returns an error code.

References EFC_FCMD_EA, efc_perform_command(), EFC_RC_OK, FLASH_RC_ERROR, FLASH_RC_OK, and translate_address().

uint32_t flash_get_descriptor	(	uint32_t	ul_address,
		uint32_t *	pul_flash_descriptor,
		uint32_t	ul_size
	)

Get flash descriptor.

Parameters

ul_address	Flash bank start address.
pul_flash_descriptor	Pointer to a data buffer to store flash descriptor.
ul_size	Data buffer size in DWORD.

Returns

The actual descriptor length.

References EFC_FCMD_GETD, efc_get_result(), efc_perform_command(), FLASH_RC_OK, and translate_address().

uint32_t flash_get_page_count

(

const uint32_t *

pul_flash_descriptor

)

Get flash total page count for the specified bank.

Note

The flash descriptor must be fetched from flash_get_descriptor function first.

Parameters

pul_flash_descriptor

Pointer to a flash descriptor.

Returns

The flash total page count.

uint32_t flash_get_page_count_per_region

(

const uint32_t *

pul_flash_descriptor

)

Get flash page count per region (plane) for the specified bank.

Note

The flash descriptor must be fetched from flash_get_descriptor function first.

Parameters

pul_flash_descriptor

Pointer to a flash descriptor.

Returns

The flash page count per region (plane).

uint32_t flash_get_region_count

(

const uint32_t *

pul_flash_descriptor

)

Get flash region (plane) count for the specified bank.

Note

The flash descriptor must be fetched from flash_get_descriptor function first.

Parameters

pul_flash_descriptor

Pointer to a flash descriptor.

Returns

The flash region (plane) count.

uint32_t flash_get_wait_state

(

uint32_t

ul_address

)

Get flash wait state.

Parameters

ul_address

Flash bank start address.

Returns

The number of wait states in cycle (no shift).

References efc_get_wait_state(), and translate_address().

uint32_t flash_init	(	uint32_t	ul_mode,
		uint32_t	ul_fws
	)

Initialize the flash service.

Parameters

ul_mode	FLASH_ACCESS_MODE_128 or FLASH_ACCESS_MODE_64.
ul_fws	The number of wait states in cycle (no shift).

Returns

0 if successful; otherwise returns an error code.

References efc_init(), and FLASH_RC_OK.

Referenced by main().

uint32_t flash_is_gpnvm_set

(

uint32_t

ul_gpnvm

)

Check if the given GPNVM bit is set or not.

Parameters

ul_gpnvm

GPNVM bit index.

Return values

1	If the given GPNVM bit is currently set.
0	If the given GPNVM bit is currently cleared. otherwise returns an error code.

References EFC_FCMD_GGPB, efc_get_result(), efc_perform_command(), EFC_RC_OK, FLASH_RC_ERROR, FLASH_RC_INVALID, FLASH_RC_NO, FLASH_RC_YES, and GPNVM_NUM_MAX.

Referenced by compute_address(), flash_clear_gpnvm(), flash_is_security_bit_enabled(), flash_set_gpnvm(), and translate_address().

uint32_t flash_is_locked	(	uint32_t	ul_start,
		uint32_t	ul_end
	)

Get the number of locked regions inside the given address range.

Parameters

ul_start	Start address of range
ul_end	End address of range.

Returns

The number of locked regions inside the given address range.

References Assert, EFC_FCMD_GLB, efc_get_result(), efc_perform_command(), translate_address(), and UNUSED.

uint32_t flash_is_security_bit_enabled

(

void

)

Check if the security bit is set or not.

Return values

1	If the security bit is currently set.
0	If the security bit is currently cleared. otherwise returns an error code.

References flash_is_gpnvm_set().

uint32_t flash_lock	(	uint32_t	ul_start,
		uint32_t	ul_end,
		uint32_t *	pul_actual_start,
		uint32_t *	pul_actual_end
	)

Lock all the regions in the given address range.

The actual lock range is reported through two output parameters.

Parameters

ul_start	Start address of lock range.
ul_end	End address of lock range.
pul_actual_start	Start address of the actual lock range (optional).
pul_actual_end	End address of the actual lock range (optional).

Returns

0 if successful, otherwise returns an error code.

References compute_lock_range(), EFC_FCMD_SLB, efc_perform_command(), FLASH_RC_OK, and translate_address().

uint32_t flash_read_unique_id	(	uint32_t *	pul_data,
		uint32_t	ul_size
	)

Read the flash unique ID.

Parameters

pul_data	Pointer to a data buffer to store 128-bit unique ID.
ul_size	Data buffer size in DWORD.

Returns

0 if successful; otherwise returns an error code.

References EFC_FCMD_SPUI, EFC_FCMD_STUI, efc_perform_read_sequence(), FLASH_RC_ERROR, and FLASH_RC_OK.

uint32_t flash_set_gpnvm

(

uint32_t

ul_gpnvm

)

Set the given GPNVM bit.

Parameters

ul_gpnvm

GPNVM bit index.

Returns

0 if successful; otherwise returns an error code.

References EFC_FCMD_SGPB, efc_perform_command(), EFC_RC_OK, flash_is_gpnvm_set(), FLASH_RC_ERROR, FLASH_RC_INVALID, FLASH_RC_OK, FLASH_RC_YES, and GPNVM_NUM_MAX.

Referenced by flash_enable_security_bit().

uint32_t flash_set_wait_state	(	uint32_t	ul_address,
		uint32_t	ul_fws
	)

Set flash wait state.

Parameters

ul_address	Flash bank start address.
ul_fws	The number of wait states in cycle (no shift).

Returns

0 if successful; otherwise returns an error code.

References efc_set_wait_state(), FLASH_RC_OK, and translate_address().

uint32_t flash_set_wait_state_adaptively

(

uint32_t

ul_address

)

Set flash wait state.

Parameters

ul_address	Flash bank start address.
ul_fws	The number of wait states in cycle (no shift).

Returns

0 if successful; otherwise returns an error code.

References efc_set_wait_state(), sysclk_get_cpu_hz(), and translate_address().

uint32_t flash_unlock	(	uint32_t	ul_start,
		uint32_t	ul_end,
		uint32_t *	pul_actual_start,
		uint32_t *	pul_actual_end
	)

Unlock all the regions in the given address range.

The actual unlock range is reported through two output parameters.

Parameters

ul_start	Start address of unlock range.
ul_end	End address of unlock range.
pul_actual_start	Start address of the actual unlock range (optional).
pul_actual_end	End address of the actual unlock range (optional).

Returns

0 if successful, otherwise returns an error code.

References compute_lock_range(), EFC_FCMD_CLB, efc_perform_command(), FLASH_RC_OK, and translate_address().

Referenced by main().

uint32_t flash_write	(	uint32_t	ul_address,
		const void *	p_buffer,
		uint32_t	ul_size,
		uint32_t	ul_erase_flag
	)

Write a data buffer on flash.

Note

This function works in polling mode, and thus only returns when the data has been effectively written.

For dual bank flash, this function doesn't support cross write from bank 0 to bank 1. In this case, flash_write must be called twice (ie for each bank).

Parameters

ul_address	Write address.
p_buffer	Data buffer.
ul_size	Size of data buffer in bytes.
ul_erase_flag	Flag to set if erase first.

Returns

0 if successful, otherwise returns an error code.

References compute_address(), EFC_FCMD_EWP, EFC_FCMD_WP, efc_get_wait_state(), efc_perform_command(), efc_set_wait_state(), FLASH_RC_OK, gs_ul_page_buffer, Min, translate_address(), and UNUSED.

Referenced by main().

static void translate_address ( Efc **  pp_efc, uint32_t  ul_addr, uint16_t *  pus_page, uint16_t *  pus_offset  )

static

Translate the given flash address to page and offset values.

Note

pus_page and pus_offset must not be null in order to store the corresponding values.

Parameters

pp_efc	Pointer to an EFC pointer.
ul_addr	Address to translate.
pus_page	The first page accessed.
pus_offset	Byte offset in the first page.

References Assert, flash_is_gpnvm_set(), and FLASH_RC_YES.

Referenced by flash_erase_all(), flash_get_descriptor(), flash_get_wait_state(), flash_is_locked(), flash_lock(), flash_set_wait_state(), flash_set_wait_state_adaptively(), flash_unlock(), and flash_write().

uint32_t gs_ul_page_buffer[IFLASH_PAGE_SIZE/sizeof(uint32_t)]

static

Referenced by flash_write().