SPRUJ27C November   2022  – November 2023 TMS320F280033 , TMS320F280034 , TMS320F280034-Q1 , TMS320F280036-Q1 , TMS320F280036C-Q1 , TMS320F280037 , TMS320F280037-Q1 , TMS320F280037C , TMS320F280037C-Q1 , TMS320F280038-Q1 , TMS320F280038C-Q1 , TMS320F280039 , TMS320F280039-Q1 , TMS320F280039C , TMS320F280039C-Q1

 

  1.   1
  2.   Trademarks
  3. 1Introduction
    1. 1.1 Reference Material
    2. 1.2 Function Listing Format
  4. 2TMS320F28003x 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 FMC 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
  5. 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_issueAsyncCommandWithAddress()
      3. 3.2.3 Fapi_issueBankEraseCommand()
      4. 3.2.4 Fapi_issueProgrammingCommand()
      5. 3.2.5 Fapi_issueProgrammingCommandForEccAddresses()
      6. 3.2.6 Fapi_issueFsmSuspendCommand()
      7. 3.2.7 Fapi_issueAsyncCommand()
      8. 3.2.8 Fapi_checkFsmForReady()
      9. 3.2.9 Fapi_getFsmStatus()
    3. 3.3 Read Functions
      1. 3.3.1 Fapi_doBlankCheck()
      2. 3.3.2 Fapi_doVerify()
      3. 3.3.3 Fapi_calculatePsa()
      4. 3.3.4 Fapi_doPsaVerify()
    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()
  6. 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
  7. 5Software Application Assumptions of Use Related to Safety
  8.   A Flash State Machine Commands
    1.     A.1 Flash State Machine Commands
  9.   B Compiler Version and Build Settings
  10.   C Object Library Function Information
    1.     C.1 TMS320F28003x Flash API Library
  11.   D Typedefs, Defines, Enumerations and Structures
    1.     D.1 Type Definitions
    2.     D.2 Defines
    3.     D.3 Enumerations
      1.      D.3.1 Fapi_FlashProgrammingCommandsType
      2.      D.3.2 Fapi_FlashBankType
      3.      D.3.3 Fapi_FlashStateCommandsType
      4.      D.3.4 Fapi_FlashReadMarginModeType
      5.      D.3.5 Fapi_StatusType
      6.      D.3.6 Fapi_ApiProductionStatusType
    4.     D.4 Structures
      1.      D.4.1 Fapi_FlashStatusWordType
      2.      D.4.2 Fapi_LibraryInfoType
  12.   E Parallel Signature Analysis (PSA) Algorithm
    1.     E.1 Function Details
  13.   F ECC Calculation Algorithm
    1.     F.1 Function Details
  14.   G Errata
  15.   Revision History

2.3.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).
  • 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. For more details, See the Fapi_Set ActiveFlashBank() function.
  • Flash API execution is interruptible. However, there should not be any read/fetch access from the Flash bank on which an erase/program operation is in progress. Therefore, the Flash API functions, the user application functions that call the Flash API functions, and any ISRs (Interrupt service routines,) must be executed from RAM, or from another flash bank on which the erase/program operations are not targeted. 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 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.
  • The DCSM OTP programming 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.
  • There is no pump semaphore in TMS320F28003x 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 will cause ECC errors in the application.
  • When using INTOSC as the clock source, a few SYSCLK frequency ranges need an extra waitstate to perform erase and program operations. After the operation is over, that extra waitstate is not needed. For more details, see the TMS320F28003x Microcontrollers Data Manual.
  • 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 TMS320F28003x Microcontrollers Technical Reference Manual.
  • 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.