Functions
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
ui32Addressis 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
pui32Datais a pointer to the data to be programmed.
ui32Addressis the starting address in flash to be programmed. Must be a multiple of four.
ui32Countis 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
ui32Addressis 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
ui32Addressis the start address of the flash block to be protected.
eProtectis 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
pui32User0is a pointer to the location to store USER Register 0.
pui32User1is 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
ui32User0is the value to store in USER Register 0.
ui32User1is 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
pui32User0is a pointer to the location to store USER Register 0.
pui32User1is a pointer to the location to store USER Register 1.
pui32User2is a pointer to the location to store USER Register 2.
pui32User3is 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
ui32User0is the value to store in USER Register 0.
ui32User1is the value to store in USER Register 1.
ui32User2is the value to store in USER Register 2.
ui32User3is 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
pfnHandleris 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
ui32IntFlagsis 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
ui32IntFlagsis 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
bMaskedis 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
ui32IntFlagsis 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.

Copyright 2017, Texas Instruments Incorporated