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	FlashUserSave (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

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 1-kB block of the on-chip flash. After erasing, the block is filled with 0xFF bytes. Read-only and execute-only blocks cannot be erased.

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.

void FlashIntClear

(

uint32_t

ui32IntFlags

)

Clears flash controller interrupt sources.

Parameters

ui32IntFlags

is the bit mask of the interrupt sources to be cleared. Can be any of the FLASH_INT_PROGRAM or FLASH_INT_AMISC values.

The specified flash controller interrupt sources are cleared, so that they no longer assert. 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.

void FlashIntDisable

(

uint32_t

ui32IntFlags

)

Disables individual flash controller interrupt sources.

Parameters

ui32IntFlags

is a bit mask of the interrupt sources to be disabled. Can be any of the FLASH_INT_PROGRAM or FLASH_INT_ACCESS values.

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.

void FlashIntEnable

(

uint32_t

ui32IntFlags

)

Enables individual flash controller interrupt sources.

Parameters

ui32IntFlags

is a bit mask of the interrupt sources to be enabled. Can be any of the FLASH_INT_PROGRAM or FLASH_INT_ACCESS values.

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.

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.

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_PROGRAM and FLASH_INT_ACCESS.

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.

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. Each word in a page of flash can only be programmed one time between an erase of that page; programming a word multiple times results in an unpredictable value in that word of 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.

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 2-kB block of flash. Each 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.

int32_t FlashProtectSave

(

void

)

Saves the flash protection settings.

This function makes the currently programmed flash protection settings permanent. On some devices, 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.

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 2-kB 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.

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.

int32_t FlashUserSave

(

void

)

Saves the user registers.

This function makes the currently programmed user register settings permanent. On some devices, this operation is non-reversible; a chip reset or power cycle does not change this setting.

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

Returns

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

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.