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.6 Fapi_issueAutoEcc512ProgrammingCommand()

Sets up data and issues 512-bit (64 bytes) AutoEcc generation mode program command to valid Flash, BANKMGMT, and SECCFG memory addresses.

Synopsis

Fapi_StatusType Fapi_issueAutoEcc512ProgrammingCommand(
                                            uint32_t *pu32StartAddress,
                                            uint8_t  *pu8DataBuffer,
                                            uint8_t  u8DataBufferSizeInWords,
                                            uint32_t  u32UserFlashConfig,
                                            uint8_t  u8Iterator
                                            );

Parameters

pu32StartAddress [in] 1024-bit aligned flash address to program the provided data and ECC.
pu8DataBuffer [in] Pointer to the Data buffer address. Address of the Data buffer can be 1024-bit aligned.
u8DataBufferSizeInWords [in] Number of bytes in the Data buffer. Max Databuffer size in words can not exceed 64.
u32UserFlashConfig [in] User flash configuration bitfield
uint8u8Iterator [in] Iterator for program and erase operations on interleaved banks.
0: Data Flash/non-interleaved
1: B0or B2(dependent on provided address)
2: B1 or B3 (dependent on provided address)

Description

This function automatically generates 8 bytes of ECC data for the user provided 512-bit data (second parameter) and programs the data and ECC together at the user provided 512-bit aligned flash address (first parameter). When this command is issued, the flash state machine programs all of the 512-bits along with ECC. Hence, when using this mode, data not supplied is treated as all 1s (0xFFFF). Once ECC is calculated and programmed for a 512-bit data, those 512-bits cannot be reprogrammed (unless the sector is erased) even if it is programming a bit from 1 to 0 in that 512-bit data, since the new ECC value collides with the previously programmed ECC value.

Note: 512bit programming programs to one interleaved bank at a time. As a result, it must be called twice, once with each iterator (for a total of 1024-bits of data), to have fully contiguous data. The pu32StartAddress for each of these calls must remain the same. If both interleaved banks are not programmed, data appears similar to the following:
Address Data
0x10000000 Data bytes 0-15
0x10000010 0xFFFF
0x10000020 Data bytes 16-31
0x10000030 0xFFFF

And so on. If the ordering of the data buffer is important, an example of how to properly format the buffer so that it maintains its order in flash can be found in this function's sample implementation. ("f29h85x-sdk > examples > driverlib > single_core > flash > flash_mode0_512_program").

Note: Fapi_issueAutoEcc512ProgrammingCommand() function programs the supplied data portion in Flash along with automatically generated ECC. The ECC is calculated for 512bit aligned address and the corresponding 512-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 512-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 program the second section, you are not able to program the ECC for the first 512-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 512-bit boundary in the linker command file for your code project.

Here is an example:

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

If you do not align the sections in flash, you must track incomplete 512-bit words in a section and combine them with the words in other sections that complete the 512-bit word. This is difficult to do. Hence, it is recommended to align your sections on 512-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 512-bit aligned and can not expect that a section might start on an unaligned address. Thus, it can try to program the maximum possible (512-bits) words at a time assuming that the address provided is 512-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 512-bit boundary.

For the allowed programming range for the function, see Table 3-3.

Table 3-3 Permitted Programming Range for Fapi_issueAutoEcc512ProgrammingCommand()
Flash API Main Array ECC BANKMGMT and SECCFG
Fapi_issueAutoEcc512ProgrammingCommand() Allowed Allowed Not allowed
Note: The length of pu8DataBuffer cannot exceed 64.
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 512 bits (given the address provided is 512-bit aligned) at a time. If the user wants to program more than that, this function can be called in a loop to program 512 bits at a time.
  • The Main Array flash programming must be aligned to 512-bit address boundaries and 64 bytes may only be programmed once per write or erase cycle.
  • 512-bit address range starting with a BANKMGMT or SECCFG address shall always be programmed using 128bit Fapi_issueProgrammingCommand().

Return Value

  • Fapi_Status_Success (success)
  • Fapi_Status_FsmBusy (FSM busy)
  • Fapi_Error_AsyncIncorrectDataBufferLength (failure: Data buffer size specified is incorrect. Also, this error is returned if Fapi_EccOnly mode is selected when programming to the BANKMGMT or SECCFG spaces,)
  • 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_512_program”)