SPRUJ96A November   2023  – April 2024 TMS320F2800152-Q1 , TMS320F2800153-Q1 , TMS320F2800154-Q1 , TMS320F2800155 , TMS320F2800155-Q1 , TMS320F2800156-Q1 , TMS320F2800157 , TMS320F2800157-Q1

 

  1.   1
  2.   Abstract
  3.   Trademarks
  4. 1Introduction
    1. 1.1 Reference Material
    2. 1.2 Function Listing Format
  5. 2TMS320F280013x/15x 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 Ojbects Library Files
        2. 2.3.2.2 Distribution Files
        3. 2.3.2.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. 5Software Application Assumptions of Use Related to Safety
  9.   A Flash State Machine Commands
  10.   B Typedefs, Defines, Enumerations and Structures
    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
  11.   C Summary of Changes for FAPI Library From v2.00.01 to v2.00.10
  12.   D Revision History

2.3.2.3 Key Facts For Flash API Usage

Here are some important facts about API usage:

  • Names of the Flash API functions start with a prefix “Fapi_”.
  • Flash API does not configure PLL. The user application should configure the PLL as needed and pass the configured CPUCLK value to Fapi_initializeAPI() function (details of this function are given later in this document). Note that the flash API library does not support flash erase/program operations when the system frequency is less than or equal to 20 MHz.
  • Flash API does not check the PLL configuration to confirm the user input frequency. This is up to the system integrator - TI suggests to use the DCC module to check the system frequency. For example implementation, see the C2000Ware driverlib clock configuration function.
  • Always configure waitstates as per the device-specific data manual before calling the Flash API functions. The Flash API will issue an error if the waitstate configured by the application is not appropriate for the operating frequency of the application.
  • Flash API execution is interruptible. However, there should not be any read/fetch access from the Flash bank when an erase/program operation is in progress. Therefore, the Flash API functions, the user application functions that call the Flash API functions, and any Interrupt service routines (ISRs) must be executed from RAM. For example, the above mentioned conditions apply to the entire code-snippet shown below in addition to the Flash API functions. The reason for this is because the Fapi_issueAsyncCommandWithAddress() function issues the erase command to the FSM, but it does not wait until the erase operation is over. As long as the FSM is busy with the current operation, the Flash bank being erased should not be accessed.
       //
   // Erase a Sector
   //
   oReturnCheck = Fapi_issueAsyncCommandWithAddress(Fapi_EraseSector,(uint32*)0x0080000);
   //
   // Wait until the erase operation is over
   //
   while (Fapi_checkFsmForReady() != Fapi_Status_FsmReady){}
  • Flash API does not configure (enable/disable) watchdog. The user application can configure watchdog and service it as needed. Hence, the Fapi_ServiceWatchdogTimer() function is no longer provided.
  • Flash API uses EALLOW and EDIS internally as needed to allow/disallow writes to protected registers.
  • The Main Array flash programming must be aligned to 64-bit address boundaries (alignment on 128-bit address boundary is suggested) and each 64-bit word may only be programmed once per write/erase cycle.
  • It is permissible to program the data and ECC separately. However, each 64-bit dataword and the corresponding ECC word may only be programmed once per write/erase cycle.
  • There is no pump semaphore in TMS320F280013x/15x devices.
  • ECC should not be programmed for link-pointer locations. The API skips programming the ECC when the start address provided for the program operation is any of the three link-pointer addresses. API will use Fapi_DataOnly mode for programming these locations even if the user passes Fapi_AutoEccGeneration or Fapi_DataAndEcc mode as the programming mode parameter. The Fapi_EccOnly mode is not supported for programming these locations. The user application should exercise caution here. Care should be taken to maintain a separate structure/section for link-pointer locations in the application. Do not mix these fields with other DCSM OTP settings. If other fields are mixed with link-pointers, API will skip programming ECC for the non-link-pointer locations as well. This causes ECC errors in the application.
  • When using 128-bit DCSM OTP programming, the DCSM OTP address must be aligned to 128-bit address boundaries and each 128-bit word may only be programmed once. The exceptions are:
    • The DCSM Zx-LINKPOINTER1 and Zx-LINKPOINTER2 values in the DCSM OTP should be programmed together, and may be programmed 1 bit at a time as required by the DCSM operation.
    • The DCSM Zx-LINKPOINTER3 values in the DCSM OTP may be programmed 1 bit at a time as required by the DCSM operation.
    • Users can program JLM_Enable separately if needed. If users want to program all the 64-bits together, users must read the link-pointer (ZxOTP_LINKPOINTER1, ZxOTP_LINKPOINTER2, ZxOTP_LINKPOINTER3) and program that value along with the JLM_Enable value.
    • 64-bits can be programmed in a given aligned 128-bit word when the other aligned 64-bits are reserved.
Note: Programing DCSM OTP is allowed in some 512-bit programming modes except for link-pointers range (0x00078000 to 0x00078008 and 0x00078200 to 0x00078208). For programing link pointer locations user should use Fapi_issueProgrammingCommand() with AutoECCGeneration mode. For more details, see the following table.
512-Bit Programming Functions Programing of DCSM OTP and Link Pointer Range
Fapi_issueAutoEcc512ProgrammingCommand() DCSM OTP allowed, link pointer not allowed
Fapi_issueDataAndEcc512ProgrammingCommand() DCSM OTP allowed, link pointer not allowed
Fapi_issueDataOnly512ProgrammingCommand() DCSM OTP and link pointer not allowed
Fapi_issueEccOnly64ProgrammingCommand() ECC DCSM OTP allowed, ECC link pointers not allowed
  • In order to avoid conflict between zone1 and zone2, a semaphore (FLSEM) is provided in the DCSM registers to configure Flash registers. The user application should configure this semaphore register before initializing the Flash and calling the Flash API functions. For more details on this register, see the TMS320F280013x Real-Time Microcontrollers Technical Reference Manual for TMS320F280013x. For more details on this register, see the TMS320F280015x Real-Time Microcontrollers Technical Reference Manual for TMS320F280015x.
  • Note that the Flash API functions do not configure any of the DCSM registers. The user application should be sure to configure the required DCSM settings. For example, if a zone is secured, then Flash API should be executed from the same zone in order to be able to erase or program the Flash sectors of that zone. Or the zone should be unlocked. If not, Flash API’s writes to Flash registers will not succeed. Flash API does not check whether the writes to the Flash registers are going through or not. It writes to them as required for the erase/program sequence and returns back assuming that the writes went through. This will cause the Flash API to return false success status. For example, Fapi_issueAsyncCommandWithAddress(Fapi_EraseSector, Address) when called, can return the success status but it does not mean that the sector erase is successful. Erase status should be checked using Fapi_getFSMStatus() and Fapi_doBlankCheck().
  • Note that there should not be any access to the Flash bank/OTP on which the Flash erase/program operation is in progress.