SPRUJB8 April   2024

 

  1.   1
  2.   Abstract
  3.   Trademarks
  4. 1Introduction
    1. 1.1 Reference Material
    2. 1.2 Function Listing Format
  5. 2TMS320F28P65x 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 Flash Wrapper and Bank Setup
        3. 2.3.1.3 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_issueProgrammingCommandForEccAddresses()
      7. 3.2.7  Fapi_issueAutoEcc512ProgrammingCommand()
      8. 3.2.8  Fapi_issueDataAndEcc512ProgrammingCommand()
      9. 3.2.9  Fapi_issueDataOnly512ProgrammingCommand()
      10. 3.2.10 Fapi_issueEccOnly64ProgrammingCommand()
      11. 3.2.11 Fapi_issueAsyncCommand()
      12. 3.2.12 Fapi_checkFsmForReady()
      13. 3.2.13 Fapi_getFsmStatus()
    3. 3.3 Read Functions
      1. 3.3.1 Fapi_doBlankCheck()
      2. 3.3.2 Fapi_doVerify()
    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_remapEccAddress()
      5. 3.5.5 Fapi_calculateFletcherChecksum()
  7. 4Recommended FSM Flows
    1. 4.1 New Devices From Factory
    2. 4.2 Recommended Erase Flow
    3. 4.3 Recommended Bank Erase Flow
    4. 4.4 Recommended Program Flow
  8.   A Flash State Machine Commands
  9.   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
    4.     B.4 Structures
      1.      B.4.1 Fapi_FlashStatusWordType
      2.      B.4.2 Fapi_LibraryInfoType
  10.   C Summary of Changes From v3.00.01 to v3.00.02

3.2.7 Fapi_issueAutoEcc512ProgrammingCommand()

Sets up data and issues 512-bit (32 16-bit words) AutoEcc generation mode program command to valid Flash or OTP memory addresses.

Synopsis

SECTIONS
 { 
 .text 		    : > FLASH, ALIGN(32)
 .cinit		    : > FLASH, ALIGN(32)
 .const 		   : > FLASH, ALIGN(32)
 .init_array	   : > FLASH, ALIGN(32)
 .switch		   : > FLASH, ALIGN(32)
 }

Parameters

pu32StartAddress [in] Start address in Flash for the data and ECC to be programmed.
pu16DataBuffer [in] Pointer to the Data buffer address. Address of the Data buffer should be 512-bit aligned.
u16DataBufferSizeInWords [in] Number of 16-bit words in the Data buffer. Max Databuffer size in words should not exceed 32.

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 will program 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 will collide with the previously programmed ECC value.

Note:

Fapi_issueAutoEcc512ProgrammingCommand() function will program the supplied data portion in Flash along with automatically generated ECC. The ECC is calculated for 512-bit 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 go to program the second section, you will not be 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, ALIGN(32) 
        .cinit : > FLASH, ALIGN(32) 
        .const : > FLASH, ALIGN(32) 
        .init_array : > FLASH, ALIGN(32) 
        .switch : > FLASH, ALIGN(32)
    }

If you do not align the sections in flash, you would need to track incomplete 512-bit words in a section and combine them with the words in other sections that complete the 512-bit word. This will be 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 (C2000Ware) or any custom Flash programming solution may assume that the incoming data stream is all 512-bit aligned and may not expect that a section might start on an unaligned address. Thus, it may 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.

Refer below Table 3-3 for allowed programming range for the function.

Table 3-3 Permitted programming range for Fapi_issueAutoEcc512ProgrammingCommand()
Flash API Main Array DCSM OTP ECC Link Pointer
Fapi_issueAutoEcc512ProgrammingCommand() Allowed Allowed Allowed Not allowed

Note:

The length of pu16DataBuffer cannot exceed 32.

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 should 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 should 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 should 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 32 16-bit word may only be programmed once per write or erase cycle.

  • 512-bit address range starting with link pointer address shall always be programmed using 128-bit 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 will be returned if Fapi_EccOnly mode is selected when programming the Bank0 DCSM OTP space)

  • Fapi_Error_FlashRegsNotWritable (failure: Flash register writes failed. The user should make sure that the API is executing from the same zone as that of the target address for flash operation OR the user should unlock before the flash operation.

  • 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 TMS320F28P65x Microcontrollers Data Manual.)

Sample Implementation

(Please refer to the flash programming example provided in C2000Ware at “C2000Ware_.....\driverlib\F28P65x\examples\....\flash\flashapi_512bit_programming\flashapi_cpu1_512bitprogramming.c”)