Driver API for EFC (plib_efc.h) More...

Macros
#define	EFC_FLASH_PAGESIZE (IFLASH_PAGE_SIZE)
	Flash page size in bytes.

#define	EFC_FLASH_START_ADDRESS (IFLASH_ADDR)
	Flash start address.

#define	EFC_MAX_WAIT_STATES (EEFC_FMR_FWS_Msk >> EEFC_FMR_FWS_Pos)
	Maximum number of wait states, derived from the FWS field width.

#define	EFC_ERROR_NONE (0x00U)

#define	EFC_ERROR_CMD (0x01U)

#define	EFC_ERROR_LOCK (0x02U)

#define	EFC_ERROR_FLASH (0x04U)

#define	EFC_ERROR_ECC_SINGLE_LSB (0x08U)

#define	EFC_ERROR_ECC_MULTI_LSB (0x10U)

#define	EFC_ERROR_ECC_SINGLE_MSB (0x20U)

#define	EFC_ERROR_ECC_MULTI_MSB (0x40U)

Typedefs
typedef uint32_t	EFC_ERROR
	EFC error status bitmask type. Defined as uint32_t so values can be OR'd together using bitwise operators.

typedef void(*	EFC_CALLBACK) (EFC_ERROR error)
	EFC callback function type.

Functions
bool	EFC_ControllerIsBusy (void)
	Check if the EFC peripheral is busy with an operation. Reads EEFC_FSR.FRDY.

bool	EFC_Read (const uint32_t address, uint32_t *data, uint32_t length)
	Reads data from Flash memory.

bool	EFC_WritePage (const uint32_t *data, uint32_t address)
	Writes a page of data to Flash (WP command). Fills the internal latch buffer and issues the WP command. Non-blocking: returns immediately once the command is issued.

bool	EFC_WritePageBuffer (const uint32_t *data, uint32_t address, uint32_t length)
	Writes data to the internal page latch buffer without committing to Flash. Used for partial page programming. Multiple calls can fill different parts of the latch buffer before a single commit.

bool	EFC_CommitPageBuffer (uint32_t address)
	Commits the internal page latch buffer to Flash (WP command). Issues the WP command for the page containing the specified address. The latch buffer must be filled (via EFC_WritePageBuffer) before calling this. Non-blocking: returns immediately once the command is issued.

bool	EFC_EraseSector (uint32_t address)
	Erases the Flash sector containing the specified address (ES command). Non-blocking: returns immediately once the command is issued.

bool	EFC_ErasePage (uint32_t address, uint8_t page_count)
	Erases a contiguous range of pages starting at the specified address (EPA command). The start address must be aligned to a (page_count * page_size) boundary. Non-blocking: returns immediately once the command is issued.

EFC_ERROR	EFC_GetError (void)
	Gets the current error status flags from EEFC_FSR. Reading EEFC_FSR clears FCMDE, FLOCKE, and the ECC error flags. FLERR clears automatically when the next programming operation starts.

void	EFC_ClearErrorStatus (void)
	Clears the EFC error status flags by reading EEFC_FSR.

bool	EFC_SetWaitStates (uint8_t wait_states)
	Sets the number of Flash read wait states (FWS field).

void	EFC_EnableLoopOptimization (void)
	Enables code loop optimization (sets CLOE bit in EEFC_FMR).

void	EFC_DisableLoopOptimization (void)
	Disables code loop optimization (clears CLOE bit in EEFC_FMR).

void	EFC_EnableSequentialOptimization (void)
	Enables sequential code optimization (clears SCOD bit in EEFC_FMR).

void	EFC_DisableSequentialOptimization (void)
	Disables sequential code optimization (sets SCOD bit in EEFC_FMR).

void	EFC_LockRegion (uint32_t address)
	Locks the Flash region containing the specified address (SLB command).

void	EFC_UnlockRegion (uint32_t address)
	Unlocks the Flash region containing the specified address (CLB command).

bool	EFC_SetGPNVMBit (uint8_t bit_number)
	Sets the specified GPNVM bit (SGPB command).

bool	EFC_ClearGPNVMBit (uint8_t bit_number)
	Clears the specified GPNVM bit (CGPB command).

bool	EFC_GetGPNVMBit (uint8_t bit_number, bool *is_set)
	Gets the status of the specified GPNVM bit (GGPB command).

bool	EFC_ReadUniqueID (uint32_t *buffer)
	Reads the 128-bit device Unique Identifier (STUI / SPUI commands).

bool	EFC_ReadUserSignature (uint32_t *buffer, uint32_t length)
	Reads data from the User Signature area (STUS / SPUS commands).

bool	EFC_WriteUserSignature (const uint32_t *data, uint32_t length)
	Writes data to the User Signature area (WUS command). The User Signature page must be erased before writing.

bool	EFC_EraseUserSignature (void)
	Erases the User Signature area (EUS command).

bool	EFC_GetCalibrationBits (uint32_t *calib_bits)
	Gets the Flash calibration bits (GCALB command).

bool	EFC_GetFlashDescriptor (uint32_t *descriptor_words, uint8_t word_count)
	Gets the Flash descriptor words (GETD command). Returns Flash organization information (FL_ID, FL_SIZE, FL_PAGE_SIZE, etc.).

bool	EFC_GetSectorSize (uint32_t *sector_size)
	Gets the Flash sector (lock region) size in bytes. Queries the Flash descriptor (GETD command) once and caches the result; subsequent calls return the cached value without issuing another command.

bool	EFC_GetSectorCount (uint32_t *sector_count)
	Gets the number of Flash sectors (lock regions). Shares the same cached Flash descriptor query as EFC_GetSectorSize().

void	EFC_EnableWriteProtect (void)
	Enables write protection of EEFC_FMR (sets WPEN in EEFC_WPMR). Once enabled, EEFC_FMR cannot be modified until protection is disabled.

void	EFC_DisableWriteProtect (void)
	Disables write protection of EEFC_FMR (clears WPEN in EEFC_WPMR).

void	EFC_EnableInterrupt (uint32_t source)
	Enables the specified EFC interrupt source.

void	EFC_DisableInterrupt (uint32_t source)
	Disables the specified EFC interrupt source.

void	EFC_SetCallbackHandler (EFC_CALLBACK callback)
	Registers a callback function for EFC interrupts.

Variables
volatile uint32_t	g_efc_stui_fence

Description

Driver API for EFC (plib_efc.h)

Macro Definition Documentation

◆ EFC_ERROR_CMD

#define EFC_ERROR_CMD (0x01U)

Command error (FCMDE: bad key/invalid command)

◆ EFC_ERROR_ECC_MULTI_LSB

#define EFC_ERROR_ECC_MULTI_LSB (0x10U)

Multi-bit ECC error on LSB half (uncorrected)

◆ EFC_ERROR_ECC_MULTI_MSB

#define EFC_ERROR_ECC_MULTI_MSB (0x40U)

Multi-bit ECC error on MSB half (uncorrected)

◆ EFC_ERROR_ECC_SINGLE_LSB

#define EFC_ERROR_ECC_SINGLE_LSB (0x08U)

Single-bit ECC error on LSB half (corrected)

◆ EFC_ERROR_ECC_SINGLE_MSB

#define EFC_ERROR_ECC_SINGLE_MSB (0x20U)

Single-bit ECC error on MSB half (corrected)

◆ EFC_ERROR_FLASH

#define EFC_ERROR_FLASH (0x04U)

Flash hardware verify failed (FLERR)

◆ EFC_ERROR_LOCK

#define EFC_ERROR_LOCK (0x02U)

Lock violation (FLOCKE)

◆ EFC_ERROR_NONE

#define EFC_ERROR_NONE (0x00U)

No error

◆ EFC_FLASH_PAGESIZE

#define EFC_FLASH_PAGESIZE (IFLASH_PAGE_SIZE)

Flash page size in bytes.

◆ EFC_FLASH_START_ADDRESS

#define EFC_FLASH_START_ADDRESS (IFLASH_ADDR)

Flash start address.

◆ EFC_MAX_WAIT_STATES

#define EFC_MAX_WAIT_STATES (EEFC_FMR_FWS_Msk >> EEFC_FMR_FWS_Pos)

Maximum number of wait states, derived from the FWS field width.

Typedef Documentation

◆ EFC_CALLBACK

typedef void(* EFC_CALLBACK) (EFC_ERROR error)

EFC callback function type.

Parameters

error Error status asserted at the time of the interrupt.

◆ EFC_ERROR

typedef uint32_t EFC_ERROR

EFC error status bitmask type. Defined as uint32_t so values can be OR'd together using bitwise operators.

Function Documentation

◆ EFC_ClearErrorStatus()

void EFC_ClearErrorStatus ( void )

Clears the EFC error status flags by reading EEFC_FSR.

Returns: None

◆ EFC_ClearGPNVMBit()

bool EFC_ClearGPNVMBit ( uint8_t bit_number )

Clears the specified GPNVM bit (CGPB command).

Parameters

bit_number GPNVM bit number (0-8).

Returns: true on success, false on error.

◆ EFC_CommitPageBuffer()

bool EFC_CommitPageBuffer ( uint32_t address )

Commits the internal page latch buffer to Flash (WP command). Issues the WP command for the page containing the specified address. The latch buffer must be filled (via EFC_WritePageBuffer) before calling this. Non-blocking: returns immediately once the command is issued.

Note: true means the command was accepted, not that the commit succeeded. Check completion via EFC_ControllerIsBusy() followed by EFC_GetError() once busy clears, or via EFC_SetCallbackHandler(). See EFC_WritePage() for the Flash-access caveat while the command is in progress.

Parameters

address Any address within the target page.

Returns: true if the command was issued, false if busy.

◆ EFC_ControllerIsBusy()

bool EFC_ControllerIsBusy ( void )

Check if the EFC peripheral is busy with an operation. Reads EEFC_FSR.FRDY.

Returns: true if busy, false if ready to accept a new command.

◆ EFC_DisableInterrupt()

void EFC_DisableInterrupt ( uint32_t source )

Disables the specified EFC interrupt source.

Parameters

source Interrupt source mask to disable.

Returns: None

◆ EFC_DisableLoopOptimization()

void EFC_DisableLoopOptimization ( void )

Disables code loop optimization (clears CLOE bit in EEFC_FMR).

Returns: None

◆ EFC_DisableSequentialOptimization()

void EFC_DisableSequentialOptimization ( void )

Disables sequential code optimization (sets SCOD bit in EEFC_FMR).

Returns: None

◆ EFC_DisableWriteProtect()

void EFC_DisableWriteProtect ( void )

Disables write protection of EEFC_FMR (clears WPEN in EEFC_WPMR).

Returns: None

◆ EFC_EnableInterrupt()

void EFC_EnableInterrupt ( uint32_t source )

Enables the specified EFC interrupt source.

Note: This arms the interrupt for exactly one command completion — EFC_Handler() disables the source again as soon as it services the interrupt, so it must be re-enabled before each subsequent command whose completion should be observed through the registered callback.

Parameters

source Interrupt source mask to enable.

Returns: None

◆ EFC_EnableLoopOptimization()

void EFC_EnableLoopOptimization ( void )

Enables code loop optimization (sets CLOE bit in EEFC_FMR).

Returns: None

◆ EFC_EnableSequentialOptimization()

void EFC_EnableSequentialOptimization ( void )

Enables sequential code optimization (clears SCOD bit in EEFC_FMR).

Returns: None

◆ EFC_EnableWriteProtect()

void EFC_EnableWriteProtect ( void )

Enables write protection of EEFC_FMR (sets WPEN in EEFC_WPMR). Once enabled, EEFC_FMR cannot be modified until protection is disabled.

Returns: None

◆ EFC_ErasePage()

bool EFC_ErasePage	(	uint32_t	address,
		uint8_t	page_count )

Erases a contiguous range of pages starting at the specified address (EPA command). The start address must be aligned to a (page_count * page_size) boundary. Non-blocking: returns immediately once the command is issued.

Note: true means the command was accepted, not that the erase succeeded. Check completion via EFC_ControllerIsBusy() followed by EFC_GetError() once busy clears, or via EFC_SetCallbackHandler(). See EFC_WritePage() for the Flash-access caveat while the command is in progress.

Parameters

address	Start address of the page range to erase.
page_count	Number of pages to erase. Must be 4, 8, 16, or 32.

Returns: true if the command was issued, false if busy or page_count is invalid.

◆ EFC_EraseSector()

bool EFC_EraseSector ( uint32_t address )

Erases the Flash sector containing the specified address (ES command). Non-blocking: returns immediately once the command is issued.

Note: true means the command was accepted, not that the erase succeeded. Check completion via EFC_ControllerIsBusy() followed by EFC_GetError() once busy clears, or via EFC_SetCallbackHandler(). See EFC_WritePage() for the Flash-access caveat while the command is in progress.

Parameters

address Any address within the target sector.

Returns: true if the command was issued, false if busy.

◆ EFC_EraseUserSignature()

bool EFC_EraseUserSignature ( void )

Erases the User Signature area (EUS command).

Returns: true on success, false on error.

◆ EFC_GetCalibrationBits()

bool EFC_GetCalibrationBits ( uint32_t * calib_bits )

Gets the Flash calibration bits (GCALB command).

Parameters

calib_bits Receives the calibration data word.

Returns: true on success, false on error.

◆ EFC_GetError()

EFC_ERROR EFC_GetError ( void )

Gets the current error status flags from EEFC_FSR. Reading EEFC_FSR clears FCMDE, FLOCKE, and the ECC error flags. FLERR clears automatically when the next programming operation starts.

Returns: EFC_ERROR bitmask indicating the last error condition(s).

◆ EFC_GetFlashDescriptor()

bool EFC_GetFlashDescriptor	(	uint32_t *	descriptor_words,
		uint8_t	word_count )

Gets the Flash descriptor words (GETD command). Returns Flash organization information (FL_ID, FL_SIZE, FL_PAGE_SIZE, etc.).

Parameters

descriptor_words	Destination buffer.
word_count	Number of descriptor words to read (typically 7).

Returns: true on success, false on error.

◆ EFC_GetGPNVMBit()

bool EFC_GetGPNVMBit	(	uint8_t	bit_number,
		bool *	is_set )

Gets the status of the specified GPNVM bit (GGPB command).

Parameters

bit_number	GPNVM bit number (0-8).
is_set	Receives the GPNVM bit status (`true` = set).

Returns: true on success, false on error.

◆ EFC_GetSectorCount()

bool EFC_GetSectorCount ( uint32_t * sector_count )

Gets the number of Flash sectors (lock regions). Shares the same cached Flash descriptor query as EFC_GetSectorSize().

Note: Returns false without altering *sector_count if a Flash command is already in progress and the value has not been cached yet — retry once EFC_ControllerIsBusy() clears.

Parameters

sector_count Receives the number of sectors.

Returns: true on success, false if sector_count is NULL, the controller is busy and the value isn't cached yet, or the descriptor is invalid.

◆ EFC_GetSectorSize()

bool EFC_GetSectorSize ( uint32_t * sector_size )

Gets the Flash sector (lock region) size in bytes. Queries the Flash descriptor (GETD command) once and caches the result; subsequent calls return the cached value without issuing another command.

Note: Returns false without altering *sector_size if a Flash command is already in progress and the value has not been cached yet — retry once EFC_ControllerIsBusy() clears.

Parameters

sector_size Receives the sector size in bytes.

Returns: true on success, false if sector_size is NULL, the controller is busy and the value isn't cached yet, or the descriptor is invalid.

◆ EFC_LockRegion()

void EFC_LockRegion ( uint32_t address )

Locks the Flash region containing the specified address (SLB command).

Parameters

address Any address within the target lock region.

Returns: None

◆ EFC_Read()

bool EFC_Read	(	const uint32_t	address,
		uint32_t *	data,
		uint32_t	length )

Reads data from Flash memory.

Parameters

address	Source Flash address to read from.
data	Pointer to destination buffer for read data.
length	Number of bytes to read.

Returns: true if read successful, false if invalid parameters.

◆ EFC_ReadUniqueID()

bool EFC_ReadUniqueID ( uint32_t * buffer )

Reads the 128-bit device Unique Identifier (STUI / SPUI commands).

Parameters

buffer Destination buffer; must hold at least 4 uint32_t words (128 bits).

Returns: true on success, false on error.

◆ EFC_ReadUserSignature()

bool EFC_ReadUserSignature	(	uint32_t *	buffer,
		uint32_t	length )

Reads data from the User Signature area (STUS / SPUS commands).

Parameters

buffer	Destination buffer.
length	Number of bytes to read (max 512 bytes).

Returns: true on success, false on error.

◆ EFC_SetCallbackHandler()

void EFC_SetCallbackHandler ( EFC_CALLBACK callback )

Registers a callback function for EFC interrupts.

Parameters

callback Pointer to the callback function. Pass NULL to unregister.

Returns: None

◆ EFC_SetGPNVMBit()

bool EFC_SetGPNVMBit ( uint8_t bit_number )

Sets the specified GPNVM bit (SGPB command).

Parameters

bit_number GPNVM bit number (0-8).

Returns: true on success, false on error.

◆ EFC_SetWaitStates()

bool EFC_SetWaitStates ( uint8_t wait_states )

Sets the number of Flash read wait states (FWS field).

Parameters

wait_states Number of wait states (0-15).

Returns: true if set, false if invalid.

◆ EFC_UnlockRegion()

void EFC_UnlockRegion ( uint32_t address )

Unlocks the Flash region containing the specified address (CLB command).

Parameters

address Any address within the target lock region.

Returns: None

◆ EFC_WritePage()

bool EFC_WritePage	(	const uint32_t *	data,
		uint32_t	address )

Writes a page of data to Flash (WP command). Fills the internal latch buffer and issues the WP command. Non-blocking: returns immediately once the command is issued.

Note: true means the command was accepted (not busy, valid parameters) — it does not mean the write succeeded. Check completion via EFC_ControllerIsBusy() followed by EFC_GetError() once busy clears, or via EFC_SetCallbackHandler(). Flash (including CPU code fetch) is unavailable while the command is in progress; a caller resuming in Flash-resident code immediately after this call will still stall on its next fetch — only RAM-resident code can make forward progress during that window.

Parameters

data	Page-sized source data buffer.
address	Destination Flash address (page-aligned).

Returns: true if the command was issued, false if busy or data is NULL.

◆ EFC_WritePageBuffer()

bool EFC_WritePageBuffer	(	const uint32_t *	data,
		uint32_t	address,
		uint32_t	length )

Writes data to the internal page latch buffer without committing to Flash. Used for partial page programming. Multiple calls can fill different parts of the latch buffer before a single commit.

Note: Returns false if a previous command is still in progress — writing to the Flash-mapped latch buffer while one is running is unsafe. See EFC_WritePage() for the Flash-access caveat while a command is active.

Parameters

data	Source data buffer.
address	Destination Flash address (determines position within the page latch).
length	Number of bytes to write into the latch buffer.

Returns: true on success, false if busy or invalid parameters.

◆ EFC_WriteUserSignature()

bool EFC_WriteUserSignature	(	const uint32_t *	data,
		uint32_t	length )

Writes data to the User Signature area (WUS command). The User Signature page must be erased before writing.

Parameters

data	Source data buffer.
length	Number of bytes to write (max 512 bytes).

Returns: true on success, false on error.

Variable Documentation

◆ g_efc_stui_fence

volatile uint32_t g_efc_stui_fence

extern

Macros

Typedefs

Functions

Variables

Description

Macro Definition Documentation

◆ EFC_ERROR_CMD

◆ EFC_ERROR_ECC_MULTI_LSB

◆ EFC_ERROR_ECC_MULTI_MSB

◆ EFC_ERROR_ECC_SINGLE_LSB

◆ EFC_ERROR_ECC_SINGLE_MSB

◆ EFC_ERROR_FLASH

◆ EFC_ERROR_LOCK

◆ EFC_ERROR_NONE

◆ EFC_FLASH_PAGESIZE

◆ EFC_FLASH_START_ADDRESS

◆ EFC_MAX_WAIT_STATES

Typedef Documentation

◆ EFC_CALLBACK

◆ EFC_ERROR

Function Documentation

◆ EFC_ClearErrorStatus()

◆ EFC_ClearGPNVMBit()

◆ EFC_CommitPageBuffer()

◆ EFC_ControllerIsBusy()

◆ EFC_DisableInterrupt()

◆ EFC_DisableLoopOptimization()

◆ EFC_DisableSequentialOptimization()

◆ EFC_DisableWriteProtect()

◆ EFC_EnableInterrupt()

◆ EFC_EnableLoopOptimization()

◆ EFC_EnableSequentialOptimization()

◆ EFC_EnableWriteProtect()

◆ EFC_ErasePage()

◆ EFC_EraseSector()

◆ EFC_EraseUserSignature()

◆ EFC_GetCalibrationBits()

◆ EFC_GetError()

◆ EFC_GetFlashDescriptor()

◆ EFC_GetGPNVMBit()

◆ EFC_GetSectorCount()

◆ EFC_GetSectorSize()

◆ EFC_LockRegion()

◆ EFC_Read()

◆ EFC_ReadUniqueID()

◆ EFC_ReadUserSignature()

◆ EFC_SetCallbackHandler()

◆ EFC_SetGPNVMBit()

◆ EFC_SetWaitStates()

◆ EFC_UnlockRegion()

◆ EFC_WritePage()

◆ EFC_WritePageBuffer()

◆ EFC_WriteUserSignature()

Variable Documentation

◆ g_efc_stui_fence