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

Introduction

The flash API provides a set of functions for dealing with the on-chip flash. Functions are provided to program and erase the flash, configure the flash protection, and handle the flash interrupt.

The flash is organized as a set of blocks that can be individually erased. See the device data sheet to determine the size of the flash blocks on an MCU. Erasing a block causes the entire contents of the block to be reset to all ones. The blocks can be marked as read-only or execute-only, providing differing levels of code protection. Read-only blocks cannot be erased or programmed, protecting the contents of those blocks from being modified. Execute-only blocks cannot be erased or programmed, and can only be read by the processor instruction fetch mechanism, protecting the contents of those blocks from being read by either the processor or by debuggers. Refer to the device data sheet to determine the size of flash blocks that can be configured as read-only or execute-only.

The flash can be programmed on a word-by-word basis. Programming causes 1 bits to become 0 bits (where appropriate); because of this, a word can be repeatedly programmed so long as each programming operation only requires changing 1 bits to 0 bits.

The timing for the flash is automatically handled by the flash controller. On some devices, flash timing depends on the PLL frequency that is specified. For these devices, the SysCtlClockFreqSet() function properly configures the flash timing.

The flash controller has the ability to generate an interrupt when an invalid access is attempted (such as reading from execute-only flash). This capability can be used to validate the operation of a program as the interrupt ensures that invalid accesses are not silently ignored, hiding potential bugs. The flash protection can be applied without being permanently enabled, which allows the program to be debugged before the flash protection is permanently applied to the device (which is a non-reversible operation on some devices). An interrupt can also be generated when an erase or programming operation has completed.

Depending upon the member of the MSP432E4 family used, the amount of available flash is 8 KB, 16 KB, 32 KB, 64 KB, 96 KB, 128 KB, 256 KB, 512 KB, or 1 MB.

API Functions

The flash API is broken into three groups of functions: those that deal with programming the flash, those that deal with flash protection, and those that deal with interrupt handling.

Flash programming is managed with FlashErase(), FlashProgram(), FlashUsecGet(), and FlashUsecSet().

Flash protection is managed with FlashProtectGet(), FlashProtectSet(), and FlashProtectSave().

Interrupt handling is managed with FlashIntRegister(), FlashIntUnregister(), FlashIntEnable(), FlashIntDisable(), FlashIntGetStatus(), and FlashIntClear().

Programming Example

The following example shows how to use the flash API to erase a block of the flash and program a few words on a TM4C123x device.

uint32_t pui32Data[2];
//
// Erase a block of the flash.
//
FlashErase(0x800);
//
// Program some data into the newly erased block of the flash.
//
pui32Data[0] = 0x12345678;
pui32Data[1] = 0x56789abc;
FlashProgram(pui32Data, 0x800, sizeof(pui32Data));

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.