Flash_api

Functions
void	FlashDisable ()
long	FlashErase (unsigned long ulAddress)
void	FlashEraseNonBlocking (unsigned long ulAddress)
long	FlashMassErase ()
void	FlashMassEraseNonBlocking ()
long	FlashProgram (unsigned long *pulData, unsigned long ulAddress, unsigned long ulCount)
long	FlashProgramNonBlocking (unsigned long *pulData, unsigned long ulAddress, unsigned long ulCount)
tFlashProtection	FlashProtectGet (unsigned long ulAddress)
void	FlashIntRegister (void(*pfnHandler)(void))
void	FlashIntUnregister (void)
void	FlashIntEnable (unsigned long ulIntFlags)
void	FlashIntDisable (unsigned long ulIntFlags)
unsigned long	FlashIntStatus (tBoolean bMasked)
void	FlashIntClear (unsigned long ulIntFlags)

Detailed Description

Function Documentation

void FlashDisable

(

void

)

Flash Disable

This function Disables the internal Flash.

Returns

None.

long FlashErase

(

unsigned long

ulAddress

)

Erases a block of flash.

Parameters

ulAddress

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

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

This function will 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 FlashEraseNonBlocking

(

unsigned long

ulAddress

)

Erases a block of flash but does not wait for completion.

Parameters

ulAddress

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

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

This function will return immediately after commanding the erase operation. Applications making use of the function can determine completion state by using a flash interrupt handler or by polling FlashIntStatus.

Returns

None.

void FlashIntClear

(

unsigned long

ulIntFlags

)

Clears flash controller interrupt sources.

Parameters

ulIntFlags

is the bit mask of the interrupt sources to be cleared. Can be any of the FLASH_CTRL_PROGRAM or FLASH_CTRL_AMISC values.

The specified flash controller interrupt sources are cleared, so that they no longer assert. This must be done in the interrupt handler to keep it from being called again immediately upon exit.

Note

Because there is a write buffer in the Cortex-M3 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

(

unsigned long

ulIntFlags

)

Disables individual flash controller interrupt sources.

Parameters

ulIntFlags

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

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

(

unsigned long

ulIntFlags

)

Enables individual flash controller interrupt sources.

Parameters

ulIntFlags

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

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 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 will be automatically enabled when the handler is registered.

See also

IntRegister() for important information about registering interrupt handlers.

Returns

None.

unsigned long FlashIntStatus

(

tBoolean

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 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_CTRL_PROGRAM and FLASH_CTRL_ACCESS.

void FlashIntUnregister

(

void

)

Unregisters the interrupt handler for the flash interrupt.

This function will clear the handler to be called when the flash interrupt occurs. This will also mask 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.

long FlashMassErase

(

void

)

Erases a complele flash at shot.

This function erases a complele flash at shot

Returns

Returns 0 on success, or -1 if the block is write-protected.

void FlashMassEraseNonBlocking

(

void

)

Erases a complele flash at shot but does not wait for completion.

This function will not return until the Flash has been erased.

Returns

None.

long FlashProgram	(	unsigned long *	pulData,
		unsigned long	ulAddress,
		unsigned long	ulCount
	)

Programs flash.

Parameters

pulData	is a pointer to the data to be programmed.
ulAddress	is the starting address in flash to be programmed. Must be a multiple of four.
ulCount	is the number of bytes to be programmed. Must be a multiple of four.

This function will program 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 will result in an unpredictable value in that word of flash.

Since 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 will not return until the data has been programmed.

Returns

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

long FlashProgramNonBlocking	(	unsigned long *	pulData,
		unsigned long	ulAddress,
		unsigned long	ulCount
	)

Programs flash but does not poll for completion.

Parameters

pulData	is a pointer to the data to be programmed.
ulAddress	is the starting address in flash to be programmed. Must be a multiple of four.
ulCount	is the number of bytes to be programmed. Must be a multiple of four.

This function will start programming one or more words into the on-chip flash and return immediately. The number of words that can be programmed in a single call depends the part on which the function is running. For parts without support for a flash write buffer, only a single word may be programmed on each call to this function (ulCount must be 1). If a write buffer is present, up to 32 words may be programmed on condition that the block being programmed does not straddle a 32 word address boundary. For example, wherease 32 words can be programmed if the address passed is 0x100 (a multiple of 128 bytes or 32 words), only 31 words could be programmed at 0x104 since attempting to write 32 would cross the 32 word boundary at 0x180.

Since 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 will return immediately after commanding the erase operation. Applications making use of the function can determine completion state by using a flash interrupt handler or by polling FlashIntStatus.

Returns

0 if the write was started successfully, -1 if there was an error.

tFlashProtection FlashProtectGet

(

unsigned long

ulAddress

)

Gets the protection setting for a block of flash.

Parameters

ulAddress

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.