Flash_api

Functions
int32_t	FlashErase (uint32_t ui32Address)
int32_t	FlashProgram (uint32_t *pui32Data, uint32_t ui32Address, uint32_t ui32Count)
tFlashProtection	FlashProtectGet (uint32_t ui32Address)
int32_t	FlashProtectSet (uint32_t ui32Address, tFlashProtection eProtect)
int32_t	FlashProtectSave (void)
int32_t	FlashUserGet (uint32_t *pui32User0, uint32_t *pui32User1)
int32_t	FlashUserSet (uint32_t ui32User0, uint32_t ui32User1)
int32_t	FlashAllUserRegisterGet (uint32_t *pui32User0, uint32_t *pui32User1, uint32_t *pui32User2, uint32_t *pui32User3)
int32_t	FlashAllUserRegisterSet (uint32_t ui32User0, uint32_t ui32User1, uint32_t ui32User2, uint32_t ui32User3)
int32_t	FlashUserSave (void)
int32_t	FlashAllUserRegisterSave (void)
void	FlashIntRegister (void(*pfnHandler)(void))
void	FlashIntUnregister (void)
void	FlashIntEnable (uint32_t ui32IntFlags)
void	FlashIntDisable (uint32_t ui32IntFlags)
uint32_t	FlashIntStatus (bool bMasked)
void	FlashIntClear (uint32_t ui32IntFlags)

Detailed Description

Function Documentation

FlashErase()

int32_t FlashErase

(

uint32_t

ui32Address

)

Erases a block of flash.

Parameters

ui32Address

is the start address of the flash block to be erased.

This function erases a block of the on-chip flash. After erasing, the block is filled with 0xFF bytes. Read-only and execute-only blocks cannot be erased.

The flash block size is 16-KB.

This function does not return until the block has been erased.

Returns

Returns 0 on success, or -1 if an invalid block address was specified or the block is write-protected.

References ASSERT, FLASH_ERASE_SIZE, FLASH_FCMISC, FLASH_FCMISC_AMISC, FLASH_FCMISC_ERMISC, FLASH_FCMISC_VOLTMISC, FLASH_FCRIS, FLASH_FCRIS_ARIS, FLASH_FCRIS_ERRIS, FLASH_FCRIS_VOLTRIS, FLASH_FMA, FLASH_FMC, FLASH_FMC_ERASE, FLASH_FMC_WRKEY, and HWREG.

FlashProgram()

int32_t FlashProgram	(	uint32_t *	pui32Data,
		uint32_t	ui32Address,
		uint32_t	ui32Count
	)

Programs flash.

Parameters

pui32Data	is a pointer to the data to be programmed.
ui32Address	is the starting address in flash to be programmed. Must be a multiple of four.
ui32Count	is the number of bytes to be programmed. Must be a multiple of four.

This function programs a sequence of words into the on-chip flash. Because the flash is programmed one word at a time, the starting address and byte count must both be multiples of four. It is up to the caller to verify the programmed contents, if such verification is required.

This function does not return until the data has been programmed.

Returns

Returns 0 on success, or -1 if a programming error is encountered.

References ASSERT, FLASH_FCMISC, FLASH_FCMISC_AMISC, FLASH_FCMISC_INVDMISC, FLASH_FCMISC_PROGMISC, FLASH_FCMISC_VOLTMISC, FLASH_FCRIS, FLASH_FCRIS_ARIS, FLASH_FCRIS_INVDRIS, FLASH_FCRIS_PROGRIS, FLASH_FCRIS_VOLTRIS, FLASH_FMA, FLASH_FMC2, FLASH_FMC2_WRBUF, FLASH_FMC2_WRKEY, FLASH_FWBN, FLASH_FWBVAL, and HWREG.

FlashProtectGet()

tFlashProtection FlashProtectGet

(

uint32_t

ui32Address

)

Gets the protection setting for a block of flash.

Parameters

ui32Address

is the start address of the flash block to be queried.

This function gets the current protection for the specified block of flash. A block can be read/write, read-only, or execute-only. Read/write blocks can be read, executed, erased, and programmed. Read-only blocks can be read and executed. Execute-only blocks can only be executed; processor and debugger data reads are not allowed.

Returns

Returns the protection setting for this block. See FlashProtectSet() for possible values.

References ASSERT, FLASH_PROTECT_SIZE, and HWREG.

FlashProtectSet()

int32_t FlashProtectSet	(	uint32_t	ui32Address,
		tFlashProtection	eProtect
	)

Sets the protection setting for a block of flash.

Parameters

ui32Address	is the start address of the flash block to be protected.
eProtect	is the protection to be applied to the block. Can be one of FlashReadWrite, FlashReadOnly, or FlashExecuteOnly.

This function sets the protection for the specified block of flash. Blocks that are read/write can be made read-only or execute-only. Blocks that are read-only can be made execute-only. Blocks that are execute-only cannot have their protection modified. Attempts to make the block protection less stringent (that is, read-only to read/write) result in a failure (and are prevented by the hardware).

Changes to the flash protection are maintained only until the next reset. This protocol allows the application to be executed in the desired flash protection environment to check for inappropriate flash access (via the flash interrupt). To make the flash protection permanent, use the FlashProtectSave() function.

Returns

Returns 0 on success, or -1 if an invalid address or an invalid protection was specified.

References ASSERT, FLASH_PROTECT_SIZE, FlashExecuteOnly, FlashReadOnly, FlashReadWrite, and HWREG.

FlashProtectSave()

int32_t FlashProtectSave

(

void

)

Saves the flash protection settings.

This function makes the currently programmed flash protection settings permanent. This operation is non-reversible; a chip reset or power cycle does not change the flash protection.

This function does not return until the protection has been saved.

Returns

Returns 0 on success, or -1 if a hardware error is encountered.

References FLASH_FMA, FLASH_FMC, FLASH_FMC_COMT, FLASH_FMC_WRKEY, and HWREG.

FlashUserGet()

int32_t FlashUserGet	(	uint32_t *	pui32User0,
		uint32_t *	pui32User1
	)

Gets the user registers.

Parameters

pui32User0	is a pointer to the location to store USER Register 0.
pui32User1	is a pointer to the location to store USER Register 1.

This function reads the contents of user registers 0 and 1, and stores them in the specified locations.

Returns

Returns 0 on success, or -1 if a hardware error is encountered.

References ASSERT, FLASH_USERREG0, FLASH_USERREG1, and HWREG.

FlashUserSet()

int32_t FlashUserSet	(	uint32_t	ui32User0,
		uint32_t	ui32User1
	)

Sets the user registers.

Parameters

ui32User0	is the value to store in USER Register 0.
ui32User1	is the value to store in USER Register 1.

This function sets the contents of the user registers 0 and 1 to the specified values.

Returns

Returns 0 on success, or -1 if a hardware error is encountered.

References FLASH_USERREG0, FLASH_USERREG1, and HWREG.

FlashAllUserRegisterGet()

int32_t FlashAllUserRegisterGet	(	uint32_t *	pui32User0,
		uint32_t *	pui32User1,
		uint32_t *	pui32User2,
		uint32_t *	pui32User3
	)

Gets all the user registers.

Parameters

pui32User0	is a pointer to the location to store USER Register 0.
pui32User1	is a pointer to the location to store USER Register 1.
pui32User2	is a pointer to the location to store USER Register 2.
pui32User3	is a pointer to the location to store USER Register 3.

This function reads the contents of user registers 0, 1, 2 and 3, and stores them in the specified locations.

Returns

Returns 0 on success, or -1 if a hardware error is encountered.

References ASSERT, FLASH_USERREG0, FLASH_USERREG1, FLASH_USERREG2, FLASH_USERREG3, and HWREG.

FlashAllUserRegisterSet()

int32_t FlashAllUserRegisterSet	(	uint32_t	ui32User0,
		uint32_t	ui32User1,
		uint32_t	ui32User2,
		uint32_t	ui32User3
	)

Sets the user registers 0 to 3

Parameters

ui32User0	is the value to store in USER Register 0.
ui32User1	is the value to store in USER Register 1.
ui32User2	is the value to store in USER Register 2.
ui32User3	is the value to store in USER Register 3.

This function sets the contents of the user registers 0, 1, 2 and 3 to the specified values.

Returns

Returns 0 on success, or -1 if a hardware error is encountered.

References FLASH_USERREG0, FLASH_USERREG1, FLASH_USERREG2, FLASH_USERREG3, and HWREG.

FlashUserSave()

int32_t FlashUserSave

(

void

)

Saves the user registers 0 and 1.

This function makes the currently programmed user register 0 and 1 settings permanent. This operation is non-reversible; a chip reset or power cycle does not change the flash protection.

This function does not return until the protection has been saved.

Returns

Returns 0 on success, or -1 if a hardware error is encountered.

References FLASH_FMA, FLASH_FMC, FLASH_FMC_COMT, FLASH_FMC_WRKEY, and HWREG.

FlashAllUserRegisterSave()

int32_t FlashAllUserRegisterSave

(

void

)

Saves the user registers.

This function makes the currently programmed user register 0, 1, 2 and 3 settings permanent. This operation is non-reversible; a chip reset or power cycle does not change the flash protection.

This function does not return until the protection has been saved.

Note

To ensure data integrity of the user registers, the commits should not be interrupted with a power loss.

Returns

Returns 0 on success, or -1 if a hardware error is encountered.

References FLASH_FMA, FLASH_FMC, FLASH_FMC_COMT, FLASH_FMC_WRKEY, and HWREG.

FlashIntRegister()

void FlashIntRegister

(

void(*)(void)

pfnHandler

)

Registers an interrupt handler for the flash interrupt.

Parameters

pfnHandler

is a pointer to the function to be called when the flash interrupt occurs.

This function sets the handler to be called when the flash interrupt occurs. The flash controller can generate an interrupt when an invalid flash access occurs, such as trying to program or erase a read-only block, or trying to read from an execute-only block. It can also generate an interrupt when a program or erase operation has completed. The interrupt is automatically enabled when the handler is registered.

See also

IntRegister() for important information about registering interrupt handlers.

Returns

None.

References INT_FLASH, IntEnable(), and IntRegister().

FlashIntUnregister()

void FlashIntUnregister

(

void

)

Unregisters the interrupt handler for the flash interrupt.

This function clears the handler to be called when the flash interrupt occurs. This function also masks off the interrupt in the interrupt controller so that the interrupt handler is no longer called.

See also

IntRegister() for important information about registering interrupt handlers.

Returns

None.

References INT_FLASH, IntDisable(), and IntUnregister().

FlashIntEnable()

void FlashIntEnable

(

uint32_t

ui32IntFlags

)

Enables individual flash controller interrupt sources.

Parameters

ui32IntFlags

is a bit mask of the interrupt sources to be enabled. The ui32IntFlags parameter can be the logical OR of any of the following values:

• FLASH_INT_ACCESS occurs when a program or erase action was attempted on a block of flash that is marked as read-only or execute-only.
• FLASH_INT_PROGRAM occurs when a programming or erase cycle completes.
• FLASH_INT_EEPROM occurs when an EEPROM interrupt occurs. The source of the EEPROM interrupt can be determined by reading the EEDONE register.
• FLASH_INT_VOLTAGE_ERR occurs when the voltage was out of spec during the flash operation and the operation was terminated.
• FLASH_INT_DATA_ERR occurs when an operation attempts to program a bit that contains a 0 to a 1.
• FLASH_INT_ERASE_ERR occurs when an erase operation fails.
• FLASH_INT_PROGRAM_ERR occurs when a program operation fails.

This function enables the indicated flash controller interrupt sources. Only the sources that are enabled can be reflected to the processor interrupt; disabled sources have no effect on the processor.

Returns

None.

References FLASH_FCIM, and HWREG.

FlashIntDisable()

void FlashIntDisable

(

uint32_t

ui32IntFlags

)

Disables individual flash controller interrupt sources.

Parameters

ui32IntFlags

is a bit mask of the interrupt sources to be disabled. The ui32IntFlags parameter can be the logical OR of any of the following values:

• FLASH_INT_ACCESS occurs when a program or erase action was attempted on a block of flash that is marked as read-only or execute-only.
• FLASH_INT_PROGRAM occurs when a programming or erase cycle completes.
• FLASH_INT_EEPROM occurs when an EEPROM interrupt occurs. The source of the EEPROM interrupt can be determined by reading the EEDONE register.
• FLASH_INT_VOLTAGE_ERR occurs when the voltage was out of spec during the flash operation and the operation was terminated.
• FLASH_INT_DATA_ERR occurs when an operation attempts to program a bit that contains a 0 to a 1.
• FLASH_INT_ERASE_ERR occurs when an erase operation fails.
• FLASH_INT_PROGRAM_ERR occurs when a program operation fails.

This function disables the indicated flash controller interrupt sources. Only the sources that are enabled can be reflected to the processor interrupt; disabled sources have no effect on the processor.

Returns

None.

References FLASH_FCIM, and HWREG.

FlashIntStatus()

uint32_t FlashIntStatus

(

bool

bMasked

)

Gets the current interrupt status.

Parameters

bMasked

is false if the raw interrupt status is required and true if the masked interrupt status is required.

This function returns the interrupt status for the flash controller. Either the raw interrupt status or the status of interrupts that are allowed to reflect to the processor can be returned.

Returns

The current interrupt status, enumerated as a bit field of FLASH_INT_ACCESS, FLASH_INT_PROGRAM, FLASH_INT_EEPROM, FLASH_INT_VOLTAGE_ERR, FLASH_INT_DATA_ERR, FLASH_INT_ERASE_ERR, and FLASH_INT_PROGRAM_ERR.

References FLASH_FCMISC, FLASH_FCRIS, and HWREG.

FlashIntClear()

void FlashIntClear

(

uint32_t

ui32IntFlags

)

Clears flash controller interrupt sources.

Parameters

ui32IntFlags

is the bit mask of the interrupt sources to be cleared.

The specified flash controller interrupt sources are cleared, so that they no longer assert. The ui32IntFlags parameter can be the logical OR of any of the following values:

• FLASH_INT_ACCESS occurs when a program or erase action was attempted on a block of flash that is marked as read-only or execute-only.
• FLASH_INT_PROGRAM occurs when a programming or erase cycle completes.
• FLASH_INT_EEPROM occurs when an EEPROM interrupt occurs. The source of the EEPROM interrupt can be determined by reading the EEDONE register.
• FLASH_INT_VOLTAGE_ERR occurs when the voltage was out of spec during the flash operation and the operation was terminated.
• FLASH_INT_DATA_ERR occurs when an operation attempts to program a bit that contains a 0 to a 1.
• FLASH_INT_ERASE_ERR occurs when an erase operation fails.
• FLASH_INT_PROGRAM_ERR occurs when a program operation fails.

This function must be called in the interrupt handler to keep the interrupt from being triggered again immediately upon exit.

Note

Because there is a write buffer in the Cortex-M processor, it may take several clock cycles before the interrupt source is actually cleared. Therefore, it is recommended that the interrupt source be cleared early in the interrupt handler (as opposed to the very last action) to avoid returning from the interrupt handler before the interrupt source is actually cleared. Failure to do so may result in the interrupt handler being immediately reentered (because the interrupt controller still sees the interrupt source asserted).

Returns

None.

References FLASH_FCMISC, and HWREG.