SPRUJE7A January   2025  – July 2025 F29H850TU , F29H859TU-Q1

 

  1.   1
  2.   Abstract
  3.   Trademarks
  4. 1Introduction
    1. 1.1 Differences From C28x
    2. 1.2 Function Listing Format
  5. 2F29H85x Flash API Overview
    1. 2.1 Introduction
    2. 2.2 API Overview
    3. 2.3 Using API
      1. 2.3.1 Initialization Flow
        1. 2.3.1.1 After Device Power Up
        2. 2.3.1.2 On System Frequency Change
      2. 2.3.2 Building With the API
        1. 2.3.2.1 Object Library Files
        2. 2.3.2.2 Distribution Files
      3. 2.3.3 Key Facts for Flash API Usage
  6. 3API Functions
    1. 3.1 Initialization Functions
      1. 3.1.1 Fapi_initializeAPI()
    2. 3.2 Flash State Machine Functions
      1. 3.2.1  Fapi_setActiveFlashBank()
      2. 3.2.2  Fapi_setupBankSectorEnable()
      3. 3.2.3  Fapi_issueAsyncCommandWithAddress()
      4. 3.2.4  Fapi_issueBankEraseCommand()
      5. 3.2.5  Fapi_issueProgrammingCommand()
      6. 3.2.6  Fapi_issueAutoEcc512ProgrammingCommand()
      7. 3.2.7  Fapi_issueDataAndEcc512ProgrammingCommand()
      8. 3.2.8  Fapi_issueDataOnly512ProgrammingCommand()
      9. 3.2.9  Fapi_issueEccOnly64ProgrammingCommand()
      10. 3.2.10 Fapi_issueAsyncCommand()
      11. 3.2.11 Fapi_checkFsmForReady()
      12. 3.2.12 Fapi_getFsmStatus()
    3. 3.3 Read Functions
      1. 3.3.1 Fapi_doBlankCheck()
      2. 3.3.2 Fapi_doVerify()
      3. 3.3.3 Fapi_doVerifyByByte()
    4. 3.4 Informational Functions
      1. 3.4.1 Fapi_getLibraryInfo()
    5. 3.5 Utility Functions
      1. 3.5.1 Fapi_flushPipeline()
      2. 3.5.2 Fapi_calculateEcc()
      3. 3.5.3 Fapi_isAddressEcc()
      4. 3.5.4 Fapi_getUserConfiguration()
      5. 3.5.5 Fapi_setFlashCPUConfiguration()
      6. 3.5.6 Fapi_issueProgBankMode()
  7. 4SECCFG and BANKMGMT Programming Using the Flash API
    1. 4.1 BANKMGMT Programming
    2. 4.2 SECCFG Programming
  8. 5Allowed Programming Ranges for All Modes
  9. 6Recommended FSM Flows
    1. 6.1 New Devices From Factory
    2. 6.2 Recommended Erase Flow
    3. 6.3 Recommended Bank Erase Flow
    4. 6.4 Recommended Program Flow
  10. 7References
  11.   A Flash State Machine Commands
  12.   B Typedefs, Defines, Enumerations and Structure
    1.     B.1 Type Definitions
    2.     B.2 Defines
    3.     B.3 Enumerations
      1.      B.3.1 Fapi_FlashProgrammingCommandsType
      2.      B.3.2 Fapi_FlashBankType
      3.      B.3.3 Fapi_FlashStateCommandsType
      4.      B.3.4 Fapi_StatusType
      5.      B.3.5 Fapi_ApiProductionStatusType
      6.      B.3.6 Fapi_BankID
      7.      B.3.7 Fapi_FLCID
      8.      B.3.8 Fapi_BankMode
      9.      B.3.9 Fapi_CPU1BankSwap
      10.      B.3.10 Fapi_CPU3BankSwap
      11.      B.3.11 Fapi_FOTAStatus
      12.      B.3.12 Fapi_SECVALID
      13.      B.3.13 Fapi_BankMgmtAddress
    4.     B.4 Structures
      1.      B.4.1 Fapi_FlashStatusWordType
      2.      B.4.2 Fapi_LibraryInfoType
  13.   Revision History

3.2.5 Fapi_issueProgrammingCommand()

Sets up data and issues program command to valid Flash, BANKMGMT, and SECCFG memory addresses

Synopsis

Fapi_StatusType Fapi_issueProgrammingCommand(
                            uint32_t *pu32StartAddress,
                            uint8_t  *pu8DataBuffer,
                            uint8_t  u8DataBufferSizeInBytes,
                            uint8_t  *pu8EccBuffer,
                            uint8_t  u8EccBufferSizeInBytes,
                            Fapi_FlashProgrammingCommandsType oMode,
                            uint32_t  u32UserFlashConfig
                            );

Parameters

pu32StartAddress [in] Start address in Flash for the data and ECC to be programmed. The start address can always be even.
pu8DataBuffer [in] Pointer to the Data buffer address. Data buffer can be 64-bit aligned.
u8DataBufferSizeInBytes [in] Number of bytes in the Data buffer
pu8EccBuffer [in] Pointer to the ECC buffer address
u8EccBufferSizeInBytes [in] Number of bytes in the ECC buffer
oMode [in] ECC mode
u32UserFlashConfig [in] User flash configuration bitfield
Note: The pu8EccBuffer can contain ECC corresponding to the data at the 64-bit aligned main array, BANKMGMT, or SECCFG address. The LSB of the pu8EccBuffer corresponds to the lower 32 bits of the main array and the MSB of the pu8EccBuffer corresponds to the upper 32 bits of the main array.

Description

This function sets up the programming registers of the Flash State Machine based on the supplied parameters. It offers four different programming modes to the user for use in different scenarios as mentioned in Table 3-1. This function sets up the programming registers of the Flash State Machine based on the supplied parameters. It offers four different programming modes to the user for use in different scenarios as mentioned in Table 3-1.

Table 3-1 Uses of Different Programming Modes
Programming Mode (oMode) Arguments Used Usage Purpose
Fapi_DataOnly pu32StartAddress,
pu8DataBuffer,
u8DataBufferSizeInWords		 Used when any custom programming utility or an user application (that embed/use Flash API) has to program data and corresponding ECC separately. Data is programmed using Fapi_DataOnly mode and then the ECC is programmed using Fapi_EccOnly mode. Generally, most of the programming utilities do not calculate ECC separately and instead use Fapi_AutoEccGeneration mode. However, some Safety applications can require to insert intentional ECC errors in their Flash image (which is not possible when Fapi_AutoEccGeneration mode is used) to check the health of the SECDED (Single Error Correction and Double Error Detection) module at run time. In such case, ECC is calculated separately (using the Fapi_calculateEcc() function as applicable). Application can want to insert errors in either main array data or in the ECC as needed. In such scenarios, after the error insertion, Fapi_DataOnly mode and Fapi_EccOnly modes can be used to program the data and ECC respectively.
Fapi_AutoEccGeneration pu32StartAddress,
pu8DataBuffer,
u8DataBufferSizeInBytes		 Used when any custom programming utility or user application (that embed/use Flash API to program Flash at run time to store data or to do a firmware update) has to program data and ECC together without inserting any intentional errors. This is the most prominently used mode.
Fapi_DataAndEcc pu32StartAddress,
pu8DataBuffer,
u8DataBufferSizeInBytes,
pu8EccBuffer,
u8EccBufferSizeInBytes		 Purpose of this mode is not different than that of using Fapi_DataOnly and Fapi_EccOnly modes together. However, this mode is beneficial when both the data and the calculated ECC can be programmed at the same time.
Fapi_EccOnly pu8EccBuffer,
u8EccBufferSizeInBytes		 See the usage purpose given for Fapi_DataOnly mode.

Table 3-2 shows the allowed programming range for the function.

Table 3-2 Permitted Programming Range for Fapi_issueProgrammingCommand()
Flash API Main Array ECC BANKMGMT and SECCFG
Fapi_issueProgrammingCommand() 128bit, Fapi_AutoEccGeneration mode Allowed Allowed Allowed
Fapi_issueProgrammingCommand() 128bit, Fapi_DataOnly mode Allowed Not allowed Allowed
Fapi_issueProgrammingCommand() 128bit, Fapi_DataAndEcc mode Allowed Allowed Allowed
Fapi_issueProgrammingCommand() 128bit, Fapi_EccOnly mode Not allowed Allowed Not allowed
Note: Users must always program ECC for their flash image, as ECC check is enabled at power up. The BANKMGMT and SECCFG sectors must only be programmed using AutoEccGeneration. Additionally, 512-bit programming (with any mode) of the BANKMGMT and SECCFG sectors is not supported.

Programming modes:

Fapi_DataOnly – This mode only programs the data portion in Flash at the address specified. It can program from 1 bit up to 16 bytes. However, review the restrictions provided for this function to know the limitations of flash programming data size. The supplied starting address to program at plus the data buffer length cannot cross the 128-bit aligned address boundary. Arguments 4 and 5 are ignored when using this mode.

Fapi_AutoEccGeneration – This mode programs the supplied data in Flash along with automatically generated ECC. The ECC is calculated for every 64-bit data aligned on a 64-bit memory boundary. Hence, when using this mode, all the 64 bits of the data can be programmed at the same time for a given 64-bit aligned memory address. Data not supplied is treated as all 1s (0xFFFF). Once ECC is calculated and programmed for a 64-bit data, those 64 bits can not be reprogrammed (unless the sector is erased) even if it is programming a bit from 1 to 0 in that 64-bit data, since the new ECC value collides with the previously programmed ECC value. When using this mode, if the start address is 128-bit aligned, then either 16 or 8 bytes can be programmed at the same time as needed. If the start address is 64bit aligned but not 128-bit aligned, then only 8bytes can be programmed at the same time. The data restrictions for Fapi_DataOnly also exist for this option. Arguments 4 and 5 are ignored.

Note: Fapi_AutoEccGeneration mode programs the supplied data portion in Flash along with automatically generated ECC. The ECC is calculated for 64-bit aligned address and the corresponding 64-bit data. Any data not supplied is treated as 0xFFFF. Note that there are practical implications of this when writing a custom programming utility that streams in the output file of a code project and programs the individual sections one at a time into flash. If a 64-bit word spans more than one section (that is, contains the end of one section, and the start of another), values of 0xFFFF cannot be assumed for the missing data in the 64-bit word when programming the first section. When you go to program the second section, you are not able to program the ECC for the first 64-bit word since it was already (incorrectly) computed and programmed using assumed 0xFFFF for the missing values. One way to avoid this problem is to align all sections linked to flash on a 64-bit boundary in the linker command file for your code project.

Here is an example:

SECTIONS
 { 
 .text	 	 : > FLASH, palign(8)
 .cinit 		: > FLASH, palign(8)
 .const 		: > FLASH, palign(8)
 .init_array	: > FLASH, palign(8)
 .switch		: > FLASH, palign(8)
 }

If you do not align the sections in flash, you must track incomplete 64-bit words in a section and combine them with the words in other sections that complete the 64-bit word. This is difficult to do, so it is recommended to align your sections on 64-bit boundaries.

Some 3rd party Flash programming tools or TI Flash programming kernel examples, or any custom Flash programming solution can assume that the incoming data stream is all 128-bit aligned and can not expect that a section might start on an unaligned address. Thus, it can try to program the maximum possible (128 bits) words at a time assuming that the address provided is 128-bit aligned. This can result in a failure when the address is not aligned. So, it is suggested to align all the sections (mapped to Flash) on a 128-bit boundary.

Fapi_DataAndEcc – This mode programs both the supplied data and ECC in Flash at the address specified. The data supplied must be aligned on a 64-bit memory boundary and the length of data must correlate to the supplied ECC. That means, if the data buffer length is 8 bytes, the ECC buffer must be 1 byte. If the data buffer length is 16 bytes, the ECC buffer must be 2 bytes in length. If the start address is 128-bit aligned, then either 16 or 8 bytes can be programmed at the same time as needed. If the start address is 64-bit aligned but not 128-bit aligned, then only 8 bytes can be programmed at the same time.

The LSB of pu8EccBuffer corresponds to the lower 64 bits of the main array and the MSB of pu8EccBuffer corresponds to the upper 64 bits of the main array.

The Fapi_calculateEcc() function can be used to calculate ECC for a given 64-bit aligned address and the corresponding data.

Fapi_EccOnly – This mode programs only the ECC portion in Flash ECC memory space at the address (Flash main array address can be provided for this function and not the corresponding ECC address) specified. It can program either 2 bytes (both LSB and MSB at a location in ECC memory) or 1 byte (LSB at a location in ECC memory). The LSB of pu8EccBuffer corresponds to the lower 64 bits of the main array and the MSB of pu8EccBuffer corresponds to the upper 64bits of the main array. Arguments two and three are ignored when using this mode.

Note: The length of pu8DataBuffer and pu8EccBuffer cannot exceed 16 and 2, respectively.
Note: This function does not check STATCMD after issuing the program command. The user application must check the STATCMD value when FSM has completed the program operation. STATCMD indicates if there is any failure occurrence during the program operation. The user application can use the Fapi_getFsmStatus function to obtain the STATCMD value.
Also, the user application can use the Fapi_doVerify() function to verify that the Flash is programmed correctly.

This function does not wait until the program operation is over; it just issues the command and returns back. Hence, the user application must wait for the Flash Wrapper to complete the program operation before returning to any kind of Flash accesses. The Fapi_checkFsmForReady() function can be used to monitor the status of an issued command.

Restrictions

  • As described above, this function can program only a max of 128 bits (given the address provided is 128-bit aligned) at a time. If the user wants to program more than that, this function can be called in a loop to program 128 bits (or 64 bits as needed by application) at a time.
  • The Main Array flash programming must be aligned to 64-bit address boundaries and each 64-bit word can only be programmed once per write or erase cycle.
  • It is alright to program the data and ECC separately. However, each 64-bit dataword and the corresponding ECC word can only be programmed once per write or erase cycle.

Return Value

  • Fapi_Status_Success (success)
  • Fapi_Status_FsmBusy (FSM busy)
  • Fapi_Error_InvalidBaseRegCntlAddress (failure: Flash control register base address provided by user does not match the expected address)
  • Fapi_Error_AsyncIncorrectDataBufferLength (failure: Data buffer size specified is incorrect. This error is also be returned if Fapi_EccOnly mode is selected when programming to the BANKMGMT or SECCFG spaces)
  • Fapi_Error_AsyncIncorrectEccBufferLength (failure: ECC buffer size specified is incorrect)
  • Fapi_Error_AsyncDataEccBufferLengthMismatch (failure: Data buffer size either is not 64-bit aligned or data length crosses the 128-bit aligned memory boundary)
  • Fapi_Error_FlashRegsNotWritable (failure: Flash register writes failed. The user can make sure that the API is executing from the correct CPU).
  • Fapi_Error_FeatureNotAvailable (failure: User passed a mode that is not supported)
  • Fapi_Error_InvalidAddress (failure: User provided an invalid address. For the valid address range, see the F29H85x and F29P58x Real-Time Microcontrollers Data Sheet.)

Sample Implementation

For more information, see the flash programming example provided in the F29H85x SDK at: “f29h85x-sdk > examples > driverlib > single_core > flash > flash_mode0_128_program”.