Detailed Description

Interface for the Flash Memory.

Summary

The Flash interface provides the ability to read, write, erase, and blank check the code flash and data flash regions.

Data Structures
struct	flash_block_info_t

struct	flash_regions_t

struct	flash_info_t

struct	flash_callback_args_t

struct	flash_cfg_t

struct	flash_api_t

struct	flash_instance_t

Typedefs
typedef void	flash_ctrl_t

Enumerations
enum	flash_result_t

enum	flash_startup_area_swap_t

enum	flash_event_t

enum	flash_id_code_mode_t

enum	flash_status_t

enum	flash_arc_t

Data Structure Documentation

◆ flash_block_info_t

struct flash_block_info_t

Flash block details stored in factory flash.

Data Fields
uint32_t	block_section_st_addr	Starting address for this block section (blocks of this size)
uint32_t	block_section_end_addr	Ending address for this block section (blocks of this size)
uint32_t	block_size	Flash erase block size.
uint32_t	block_size_write	Flash write block size.

◆ flash_regions_t

struct flash_regions_t

Flash block details

Data Fields
uint32_t	num_regions	Length of block info array.
flash_block_info_t const *	p_block_array	Block info array base address.

◆ flash_info_t

struct flash_info_t

Information about the flash blocks

Data Fields
flash_regions_t	code_flash	Information about the code flash regions.
flash_regions_t	data_flash	Information about the code flash regions.

◆ flash_callback_args_t

struct flash_callback_args_t

Callback function parameter data

Data Fields
flash_event_t	event	Event can be used to identify what caused the callback (flash ready or error).
void const *	p_context	Placeholder for user data. Set in flash_api_t::open function in::flash_cfg_t.

◆ flash_cfg_t

struct flash_cfg_t

FLASH Configuration

Data Fields
bool	data_flash_bgo
	True if BGO (Background Operation) is enabled for Data Flash.

void(*	p_callback )(flash_callback_args_t *p_args)
	Callback provided when a Flash interrupt ISR occurs.

void const *	p_extend
	FLASH hardware dependent configuration.

void const *	p_context
	Placeholder for user data. Passed to user callback in flash_callback_args_t.

uint8_t	ipl
	Flash ready interrupt priority.

IRQn_Type	irq
	Flash ready interrupt number.

uint8_t	err_ipl
	Flash error interrupt priority (unused in r_flash_lp)

IRQn_Type	err_irq
	Flash error interrupt number (unused in r_flash_lp)

◆ flash_api_t

struct flash_api_t

Shared Interface definition for FLASH

Data Fields
fsp_err_t(*	open )(flash_ctrl_t const p_ctrl, flash_cfg_t const const p_cfg)

fsp_err_t(*	write )(flash_ctrl_t *const p_ctrl, uint32_t const src_address, uint32_t const flash_address, uint32_t const num_bytes)

fsp_err_t(*	erase )(flash_ctrl_t *const p_ctrl, uint32_t const address, uint32_t const num_blocks)

fsp_err_t(*	blankCheck )(flash_ctrl_t const p_ctrl, uint32_t const address, uint32_t const num_bytes, flash_result_t const p_blank_check_result)

fsp_err_t(*	infoGet )(flash_ctrl_t const p_ctrl, flash_info_t const p_info)

fsp_err_t(*	close )(flash_ctrl_t *const p_ctrl)

fsp_err_t(*	statusGet )(flash_ctrl_t const p_ctrl, flash_status_t const p_status)

fsp_err_t(*	accessWindowSet )(flash_ctrl_t *const p_ctrl, uint32_t const start_addr, uint32_t const end_addr)

fsp_err_t(*	accessWindowClear )(flash_ctrl_t *const p_ctrl)

fsp_err_t(*	idCodeSet )(flash_ctrl_t const p_ctrl, uint8_t const const p_id_bytes, flash_id_code_mode_t mode)

fsp_err_t(*	reset )(flash_ctrl_t *const p_ctrl)

fsp_err_t(*	updateFlashClockFreq )(flash_ctrl_t *const p_ctrl)

fsp_err_t(*	startupAreaSelect )(flash_ctrl_t *const p_ctrl, flash_startup_area_swap_t swap_type, bool is_temporary)

fsp_err_t(*	bankSwap )(flash_ctrl_t *const p_ctrl)

fsp_err_t(*	callbackSet )(flash_ctrl_t const p_ctrl, void(p_callback)(flash_callback_args_t ), void const const p_context, flash_callback_args_t *const p_callback_memory)

fsp_err_t(*	antiRollbackCounterIncrement )(flash_ctrl_t *const p_ctrl, flash_arc_t counter)

fsp_err_t(*	antiRollbackCounterRefresh )(flash_ctrl_t *const p_ctrl, flash_arc_t counter)

fsp_err_t(*	antiRollbackCounterRead )(flash_ctrl_t const p_ctrl, flash_arc_t counter, uint32_t const p_count)

fsp_err_t(*	userLockableAreaWrite )(flash_ctrl_t *const p_ctrl, uint32_t const src_address, uint32_t const flash_address, uint32_t const num_bytes)

Field Documentation

◆ open

fsp_err_t(* flash_api_t::open) (flash_ctrl_t *const p_ctrl, flash_cfg_t const *const p_cfg)

Open FLASH device.

Parameters

[out]	p_ctrl	Pointer to FLASH device control. Must be declared by user. Value set here.
[in]	flash_cfg_t	Pointer to FLASH configuration structure. All elements of this structure must be set by the user.

◆ write

fsp_err_t(* flash_api_t::write) (flash_ctrl_t *const p_ctrl, uint32_t const src_address, uint32_t const flash_address, uint32_t const num_bytes)

Write FLASH device.

Parameters

[in]	p_ctrl	Control for the FLASH device context.
[in]	src_address	Address of the buffer containing the data to write to Flash.
[in]	flash_address	Code Flash or Data Flash address to write. The address must be on a programming line boundary.
[in]	num_bytes	The number of bytes to write. This number must be a multiple of the programming size. For Code Flash this is FLASH_MIN_PGM_SIZE_CF. For Data Flash this is FLASH_MIN_PGM_SIZE_DF.

Warning: Specifying a number that is not a multiple of the programming size will result in SF_FLASH_ERR_BYTES being returned and no data written.

◆ erase

fsp_err_t(* flash_api_t::erase) (flash_ctrl_t *const p_ctrl, uint32_t const address, uint32_t const num_blocks)

Erase FLASH device.

Parameters

[in]	p_ctrl	Control for the FLASH device.
[in]	address	The block containing this address is the first block erased.
[in]	num_blocks	Specifies the number of blocks to be erased, the starting block determined by the block_erase_address.

◆ blankCheck

fsp_err_t(* flash_api_t::blankCheck) (flash_ctrl_t *const p_ctrl, uint32_t const address, uint32_t const num_bytes, flash_result_t *const p_blank_check_result)

Blank check FLASH device.

Parameters

[in]	p_ctrl	Control for the FLASH device context.
[in]	address	The starting address of the Flash area to blank check.
[in]	num_bytes	Specifies the number of bytes that need to be checked. See the specific handler for details.
[out]	p_blank_check_result	Pointer that will be populated by the API with the results of the blank check operation in non-BGO (blocking) mode. In this case the blank check operation completes here and the result is returned. In Data Flash BGO mode the blank check operation is only started here and the result obtained later when the supplied callback routine is called. In this case FLASH_RESULT_BGO_ACTIVE will be returned in p_blank_check_result.

◆ infoGet

fsp_err_t(* flash_api_t::infoGet) (flash_ctrl_t *const p_ctrl, flash_info_t *const p_info)

Close FLASH device.

Parameters

[in]	p_ctrl	Pointer to FLASH device control.
[out]	p_info	Pointer to FLASH info structure.

◆ close

fsp_err_t(* flash_api_t::close) (flash_ctrl_t *const p_ctrl)

Close FLASH device.

Parameters

[in] p_ctrl Pointer to FLASH device control.

◆ statusGet

fsp_err_t(* flash_api_t::statusGet) (flash_ctrl_t *const p_ctrl, flash_status_t *const p_status)

Get Status for FLASH device.

Parameters

[in]	p_ctrl	Pointer to FLASH device control.
[out]	p_ctrl	Pointer to the current flash status.

◆ accessWindowSet

fsp_err_t(* flash_api_t::accessWindowSet) (flash_ctrl_t *const p_ctrl, uint32_t const start_addr, uint32_t const end_addr)

Set Access Window for FLASH device.

Parameters

[in]	p_ctrl	Pointer to FLASH device control.
[in]	start_addr	Determines the Starting block for the Code Flash access window.
[in]	end_addr	Determines the Ending block for the Code Flash access window. This address will not be within the access window.

◆ accessWindowClear

fsp_err_t(* flash_api_t::accessWindowClear) (flash_ctrl_t *const p_ctrl)

Clear any existing Code Flash access window for FLASH device.

Parameters

[in]	p_ctrl	Pointer to FLASH device control.
[in]	start_addr	Determines the Starting block for the Code Flash access window.
[in]	end_addr	Determines the Ending block for the Code Flash access window.

◆ idCodeSet

fsp_err_t(* flash_api_t::idCodeSet) (flash_ctrl_t *const p_ctrl, uint8_t const *const p_id_bytes, flash_id_code_mode_t mode)

Set ID Code for FLASH device. Setting the ID code can restrict access to the device. The ID code will be required to connect to the device. Bits 126 and 127 are set based on the mode.

For example, uint8_t id_bytes[] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0x00}; with mode FLASH_ID_CODE_MODE_LOCKED_WITH_ALL_ERASE_SUPPORT will result in an ID code of 00112233445566778899aabbccddeec0

With mode FLASH_ID_CODE_MODE_LOCKED, it will result in an ID code of 00112233445566778899aabbccddee80

Parameters

[in]	p_ctrl	Pointer to FLASH device control.
[in]	p_id_bytes	Ponter to the ID Code to be written.
[in]	mode	Mode used for checking the ID code.

◆ reset

fsp_err_t(* flash_api_t::reset) (flash_ctrl_t *const p_ctrl)

Reset function for FLASH device.

Parameters

[in] p_ctrl Pointer to FLASH device control.

◆ updateFlashClockFreq

fsp_err_t(* flash_api_t::updateFlashClockFreq) (flash_ctrl_t *const p_ctrl)

Update Flash clock frequency (FCLK) and recalculate timeout values

Parameters

[in] p_ctrl Pointer to FLASH device control.

◆ startupAreaSelect

fsp_err_t(* flash_api_t::startupAreaSelect) (flash_ctrl_t *const p_ctrl, flash_startup_area_swap_t swap_type, bool is_temporary)

Select which block - Default (Block 0) or Alternate (Block 1) is used as the start-up area block.

Parameters

[in]	p_ctrl	Pointer to FLASH device control.
[in]	swap_type	FLASH_STARTUP_AREA_BLOCK0, FLASH_STARTUP_AREA_BLOCK1 or FLASH_STARTUP_AREA_BTFLG.
[in]	is_temporary	True or false. See table below.

swap_type	is_temporary	Operation
FLASH_STARTUP_AREA_BLOCK0	false	On next reset Startup area will be Block 0.
FLASH_STARTUP_AREA_BLOCK1	true	Startup area is immediately, but temporarily switched to Block 1.
FLASH_STARTUP_AREA_BTFLG	true	Startup area is immediately, but temporarily switched to the Block determined by the Configuration BTFLG.

◆ bankSwap

fsp_err_t(* flash_api_t::bankSwap) (flash_ctrl_t *const p_ctrl)

Swap the bank used as the startup area. On Flash HP, need to change into dual bank mode to use this feature.

Parameters

[in] p_ctrl Pointer to FLASH device control.

◆ callbackSet

fsp_err_t(* flash_api_t::callbackSet) (flash_ctrl_t *const p_ctrl, void(*p_callback)(flash_callback_args_t *), void const *const p_context, flash_callback_args_t *const p_callback_memory)

Specify callback function and optional context pointer and working memory pointer.

Parameters

[in]	p_ctrl	Pointer to FLASH device control.
[in]	p_callback	Callback function to register
[in]	p_context	Pointer to send to callback function
[in]	p_working_memory	Pointer to volatile memory where callback structure can be allocated. Callback arguments allocated here are only valid during the callback.

◆ antiRollbackCounterIncrement

fsp_err_t(* flash_api_t::antiRollbackCounterIncrement) (flash_ctrl_t *const p_ctrl, flash_arc_t counter)

Increment the selected anti-rollback counter.

Warning: Once incremented, the counter can never be decremented or reset, even with a debug probe.

Parameters

[in]	p_ctrl	Pointer to FLASH device control.
[in]	counter	The anti-rollback counter to increment

◆ antiRollbackCounterRefresh

fsp_err_t(* flash_api_t::antiRollbackCounterRefresh) (flash_ctrl_t *const p_ctrl, flash_arc_t counter)

Refresh the selected anti-rollback counter flash area.

Parameters

[in]	p_ctrl	Pointer to FLASH device control.
[in]	counter	The anti-rollback counter to refresh

◆ antiRollbackCounterRead

fsp_err_t(* flash_api_t::antiRollbackCounterRead) (flash_ctrl_t *const p_ctrl, flash_arc_t counter, uint32_t *const p_count)

Read current count value of the selected anti-rollback counter.

Parameters

[in]	p_ctrl	Pointer to FLASH device control.
[in]	counter	The anti-rollback counter to read
[out]	p_count	The current count value

◆ userLockableAreaWrite

fsp_err_t(* flash_api_t::userLockableAreaWrite) (flash_ctrl_t *const p_ctrl, uint32_t const src_address, uint32_t const flash_address, uint32_t const num_bytes)

Write to the user lockable area for the flash device

Warning: Data will not be written if any segment of the specified area is locked.

Parameters

[in]	p_ctrl	Pointer to FLASH device control.
[in]	src_address	Address of the buffer containing the data to write to flash.
[in]	flash_address	User lockable area flash address to write. The address must be on a programming line boundary.
[in]	num_bytes	The number of bytes to write. This number must be a multiple of the programming size.

◆ flash_instance_t

struct flash_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
flash_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
flash_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
flash_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

◆ flash_ctrl_t

typedef void flash_ctrl_t

Flash control block. Allocate an instance specific control block to pass into the flash API calls.

Enumeration Type Documentation

◆ flash_result_t

enum flash_result_t

Result type for certain operations

Enumerator
FLASH_RESULT_BLANK	Return status for Blank Check Function.
FLASH_RESULT_NOT_BLANK	Return status for Blank Check Function.
FLASH_RESULT_BGO_ACTIVE	Flash is configured for BGO mode. Result is returned in callback.

◆ flash_startup_area_swap_t

enum flash_startup_area_swap_t

Parameter for specifying the startup area swap being requested by startupAreaSelect()

Enumerator
FLASH_STARTUP_AREA_BTFLG	Startup area will be set based on the value of the BTFLG.
FLASH_STARTUP_AREA_BLOCK0	Startup area will be set to Block 0.
FLASH_STARTUP_AREA_BLOCK1	Startup area will be set to Block 1.

◆ flash_event_t

enum flash_event_t

Event types returned by the ISR callback when used in Data Flash BGO mode

Enumerator
FLASH_EVENT_ERASE_COMPLETE	Erase operation successfully completed.
FLASH_EVENT_WRITE_COMPLETE	Write operation successfully completed.
FLASH_EVENT_BLANK	Blank check operation successfully completed. Specified area is blank.
FLASH_EVENT_NOT_BLANK	Blank check operation successfully completed. Specified area is NOT blank.
FLASH_EVENT_ERR_DF_ACCESS	Data Flash operation failed. Can occur when writing an unerased section.
FLASH_EVENT_ERR_CF_ACCESS	Code Flash operation failed. Can occur when writing an unerased section.
FLASH_EVENT_ERR_CMD_LOCKED	Operation failed, FCU is in Locked state (often result of an illegal command)
FLASH_EVENT_ERR_FAILURE	Erase or Program Operation failed.
FLASH_EVENT_ERR_ONE_BIT	A 1-bit error has been corrected when reading the flash memory area by the sequencer.

◆ flash_id_code_mode_t

enum flash_id_code_mode_t

ID Code Modes for writing to ID code registers

Enumerator
FLASH_ID_CODE_MODE_UNLOCKED	ID code is ignored.
FLASH_ID_CODE_MODE_LOCKED_WITH_ALL_ERASE_SUPPORT	ID code is checked. All erase is available.
FLASH_ID_CODE_MODE_LOCKED	ID code is checked.

◆ flash_status_t

enum flash_status_t

Flash status

Enumerator
FLASH_STATUS_IDLE	The flash is idle.
FLASH_STATUS_BUSY	The flash is currently processing a command.

◆ flash_arc_t

enum flash_arc_t

Anti-rollback counter selection.

Enumerator
FLASH_ARC_SEC	Anti-Rollback Counter for the secure application.
FLASH_ARC_OEMBL	Anti-Rollback Counter for the OEM bootloader.
FLASH_ARC_NSEC_0	Anti-Rollback Counter for non-secure application 0 (use when a single non-secure counter is available or when multiple non-secure counters are available)
FLASH_ARC_NSEC_1	Anti-Rollback Counter for non-secure application 1 (use when multiple non-secure counters are available)
FLASH_ARC_NSEC_2	Anti-Rollback Counter for non-secure application 2 (use when multiple non-secure counters are available)
FLASH_ARC_NSEC_3	Anti-Rollback Counter for non-secure application 3 (use when multiple non-secure counters are available)

Detailed Description

Summary

Data Structures

Typedefs

Enumerations

Data Structure Documentation

◆ flash_block_info_t

◆ flash_regions_t

◆ flash_info_t

◆ flash_callback_args_t

◆ flash_cfg_t

Data Fields

◆ flash_api_t

Data Fields

Field Documentation

◆ open

◆ write

◆ erase

◆ blankCheck

◆ infoGet

◆ close

◆ statusGet

◆ accessWindowSet

◆ accessWindowClear

◆ idCodeSet

◆ reset

◆ updateFlashClockFreq

◆ startupAreaSelect

◆ bankSwap

◆ callbackSet

◆ antiRollbackCounterIncrement

◆ antiRollbackCounterRefresh

◆ antiRollbackCounterRead

◆ userLockableAreaWrite

◆ flash_instance_t

Typedef Documentation

◆ flash_ctrl_t

Enumeration Type Documentation

◆ flash_result_t

◆ flash_startup_area_swap_t

◆ flash_event_t

◆ flash_id_code_mode_t

◆ flash_status_t

◆ flash_arc_t