ZHCUCQ7A January   2025  – July 2025 F29H850TU , F29H859TU-Q1

 

  1.   1
  2.   摘要
  3.   商标
  4. 1简介
    1. 1.1 与 C28x 的区别
    2. 1.2 函数清单格式
  5. 2F29H85x 闪存 API 概述
    1. 2.1 简介
    2. 2.2 API 概述
    3. 2.3 使用 API
      1. 2.3.1 初始化流程
        1. 2.3.1.1 器件上电后
        2. 2.3.1.2 关于系统频率变化
      2. 2.3.2 使用 API 进行构建
        1. 2.3.2.1 目标库文件
        2. 2.3.2.2 分布文件
      3. 2.3.3 闪存 API 使用的关键事实
  6. 3API 函数
    1. 3.1 初始化函数
      1. 3.1.1 Fapi_initializeAPI()
    2. 3.2 闪存状态机函数
      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 读取函数
      1. 3.3.1 Fapi_doBlankCheck()
      2. 3.3.2 Fapi_doVerify()
      3. 3.3.3 Fapi_doVerifyByByte()
    4. 3.4 信息函数
      1. 3.4.1 Fapi_getLibraryInfo()
    5. 3.5 实用功能
      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. 4使用闪存 API 对 SECCFG 和 BANKMGMT 编程
    1. 4.1 BANKMGMT 编程
    2. 4.2 SECCFG 编程
  8. 5所有模式允许的编程范围
  9. 6推荐的 FSM 流程
    1. 6.1 新出厂器件
    2. 6.2 推荐的擦除流程
    3. 6.3 推荐的存储组擦除流程
    4. 6.4 推荐的编程流程
  10. 7参考资料
  11.   A 闪存状态机命令
  12.   B typedef、定义、枚举和结构
    1.     B.1 类型定义
    2.     B.2 定义
    3.     B.3 枚举
      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 结构
      1.      B.4.1 Fapi_FlashStatusWordType
      2.      B.4.2 Fapi_LibraryInfoType
  13.   修订历史记录

3.2.5 Fapi_issueProgrammingCommand()

设置数据并向有效的闪存、BANKMGMT 和 SECCFG 内存地址发出编程命令

概要

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
                            );

参数

pu32StartAddress [in] 闪存中的起始地址，用于对数据和 ECC 进行编程。起始地址可以始终为偶数。
pu8DataBuffer [in] 指向数据缓冲区地址的指针。数据缓冲区可以为 64 位对齐。
u8DataBufferSizeInBytes [in] 数据缓冲区中的字节数
pu8EccBuffer [in] 指向 ECC 缓冲区地址的指针
u8EccBufferSizeInBytes [in] ECC 缓冲区中的字节数
oMode [in] ECC 模式
u32UserFlashConfig [in] 用户闪存配置位域
注： pu8EccBuffer 可以包含与 64 位对齐主阵列、BANKMGMT 或 SECCFG 地址的数据对应的 ECC。pu8EccBuffer 的 LSB 与主阵列的低 32 位相对应，pu8EccBuffer 的 MSB 与主阵列的高 32 位相对应。

说明

该函数根据提供的参数设置闪存状态机的编程寄存器，为用户提供了适用于不同场景的四种不同编程模式，如表 3-1 中所述。该函数根据提供的参数设置闪存状态机的编程寄存器，为用户提供了适用于不同场景的四种不同编程模式，如表 3-1 中所述。

表 3-1 不同编程模式的使用
编程模式 (oMode) 使用的参数 用途
Fapi_DataOnly pu32StartAddress、
pu8DataBuffer、
u8DataBufferSizeInWords		 当任何自定义编程实用程序或用户应用（嵌入/使用闪存 API）必须单独对数据和相应 ECC 进行编程时使用。使用 Fapi_DataOnly 模式对数据进行编程，然后使用 Fapi_EccOnly 模式对 ECC 进行编程。通常，大多数编程实用程序不会单独计算 ECC，而是使用 Fapi_AutoEccGeneration 模式。但是，某些安全应用程序可能需要在其闪存映像中插入有意的 ECC 错误（使用 Fapi_AutoEccGeneration 模式时无法实现），从而在运行时检查 SECDED（单错校正和双错检测）模块的运行状况。在这种情况下，ECC 是单独计算的（如果适用，使用 Fapi_calculateEcc() 函数）。应用程序可能希望根据需要在主阵列数据或 ECC 中插入错误。在这种情况下，在错误插入之后，可以使用 Fapi_DataOnly 模式和 Fapi_EccOnly 模式分别对数据和 ECC 进行编程。
Fapi_AutoEccGeneration pu32StartAddress、
pu8DataBuffer、
u8DataBufferSizeInBytes		 当任何自定义编程实用程序或用户应用（其在运行时嵌入/使用闪存 API 对闪存进行编程从而存储数据或进行固件更新）必须同时对数据和 ECC 进行编程而不插入任何有意错误时使用。该模式是常用的模式。
Fapi_DataAndEcc pu32StartAddress、
pu8DataBuffer、
u8DataBufferSizeInBytes、
pu8EccBuffer、
u8EccBufferSizeInBytes		 该模式的用途与同时使用 Fapi_DataOnly 和 Fapi_EccOnly 模式的用途没有什么不同。但是，当可以同时对数据和计算出的 ECC 进行编程时，该模式会很有用。
Fapi_EccOnly pu8EccBuffer、
u8EccBufferSizeInBytes		 请参阅 Fapi_DataOnly 模式的用途描述。

表 3-2 展示了该函数允许的编程范围。

表 3-2 Fapi_issueProgrammingCommand() 的允许编程范围
闪存 API 主阵列 ECC BANKMGMT 和 SECCFG
Fapi_issueProgrammingCommand() 128 位，Fapi_AutoEccGeneration 模式 允许 允许 允许
Fapi_issueProgrammingCommand() 128 位，Fapi_DataOnly 模式 允许 不允许 允许
Fapi_issueProgrammingCommand() 128 位，Fapi_DataAndEcc 模式 允许 允许 允许
Fapi_issueProgrammingCommand() 128 位，Fapi_EccOnly 模式 不允许 允许 不允许
注： 由于 ECC 检查在上电时启用，用户必须始终为其闪存映像对 ECC 进行编程。BANKMGMT 和 SECCFG 扇区必须仅使用 AutoEccGeneration 进行编程。此外，不支持 BANKMGMT 和 SECCFG 扇区的 512 位编程（使用任何模式）。

编程模式：

Fapi_DataOnly — 该模式只对闪存中指定地址的数据部分进行编程。其编程范围从 1 位至 16 字节不等。但是，请注意该函数的限制条件中对闪存编程数据大小的限制。提供的编程起始地址加上数据缓冲区长度无法跨越 128 位对齐地址边界。使用该模式时将忽略参数 4 和 5。

Fapi_AutoEccGeneration – 该模式会对闪存中提供的数据以及自动生成的 ECC 进行编程。针对在 64 位存储器边界上对齐的每项 64 位数据计算 ECC。因此，在使用该模式时，可以针对给定的 64 位对齐存储器地址，同时对所有 64 位数据进行编程。未提供的数据全部视作 1 (0xFFFF)。针对 64 位数据计算 ECC 并对其进行编程后，即使在该 64 位数据中将位从 1 编程为 0，也无法对此类 64 位数据进行重新编程（除非扇区被擦除），因为新的 ECC 值会与先前编程的 ECC 值相冲突。使用该模式时，如果起始地址进行了 128 位对齐，则可以根据需要同时编程 16 或 8 个字节。如果起始地址进行了 64 位对齐而不是 128 位对齐，则一次只能编辑 8 个字节。该选项还存在 Fapi_DataOnly 的数据限制。忽略参数 4 和 5。

注： Fapi_AutoEccGeneration 模式会对闪存中提供的数据部分以及自动生成的 ECC 进行编程。针对 64 位对齐地址和相应的 64 位数据计算 ECC。未提供的任何数据将视作 0xFFFF。请注意，在编写自定义编程实用程序时，该实用程序在代码项目的输出文件中流式传输，并将各段一次编程到闪存中，这会产生实际影响。如果一个 64 位的字跨越多个段（即包含一段的末尾和另一段的开头），在对第一段进行编程时，无法针对 64 位字中缺失数据假设值为 0xFFFF。当您对第二段进行编程时，您无法对第一个 64 位字的 ECC 进行编程，因为它已经（错误地）使用假定的 0xFFFF 对缺失值进行了计算和编程。避免该问题的一种方法是在代码项目的链接器命令文件中的 64 位边界上对齐链接到闪存的所有段。

下面我们举例说明：

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

如果不在闪存中对齐这些段，则必须跟踪段中不完整的 64 位字，并将这些字与其他段中的字组合在一起，从而使 64 位字变得完整。这一点很难做到。因此，建议在 64 位边界上对段进行对齐。

某些第三方闪存编程工具或 TI 闪存编程内核示例或任何自定义闪存编程解决方案可能假定传入数据流全部为 128 位对齐，并且无法预想到某段可能从未对齐的地址开始。因此，假设提供的地址为 128 位对齐，则可能会尝试对最大可能的（128 位）字进行一次编程。当地址未对齐时，这可能会导致出现故障。因此，建议在 128 位边界上对齐所有段（映射到闪存）。

Fapi_DataAndEcc — 该模式会在指定地址的闪存中对提供的数据和 ECC 进行编程。提供的数据必须在 64 位存储器边界上对齐，并且数据长度必须与提供的 ECC 相关联。这意味着，如果数据缓冲区长度为 8 个字节，则 ECC 缓冲区必须为 1 字节。如果数据缓冲区长度为 16 个字节，则 ECC 缓冲区的长度必须为 2 字节。如果起始地址进行了 128 位对齐，可以根据需要同时编程 16 个或 8 个字节。如果起始地址进行了 64 位对齐而不是 128 位对齐，则一次只能编辑 8 个字节。

pu8EccBuffer 的 LSB 与主阵列的低 64 位相对应，pu8EccBuffer 的 MSB 与主阵列的高 64 位相对应。

Fapi_calculateEcc() 函数可用于计算给定 64 位对齐地址和相应数据的 ECC。

Fapi_EccOnly — 该模式仅在指定的地址处（可以为该函数提供闪存主阵列地址，而不是相应的 ECC 地址）对闪存 ECC 存储空间中的 ECC 部分进行编程。它可以对 2 字节（ECC 存储器中某一位置的 LSB 和 MSB）或 1 字节（ECC 存储器中某一位置的 LSB）编程。pu8EccBuffer 的 LSB 与主阵列的低 64 位相对应，pu8EccBuffer 的 MSB 与主阵列的高 64 位相对应。使用该模式时将忽略参数二和三。

注： pu8DataBuffer 和 pu8EccBuffer 的长度分别不可超过 16 和 2。
注： 该函数在发出编程命令后不检查 STATCMD。当 FSM 完成编程操作时，用户应用程序必须检查 STATCMD 值。STATCMD 指示编程操作期间是否有任何故障发生。用户应用程序可以使用 Fapi_getFsmStatus 函数来获取 STATCMD 值。
此外，用户应用程序可以使用 Fapi_doVerify() 函数来验证闪存是否已正确编程。

该函数不会等到编程操作结束；它只是发出命令并返回。用户应用程序必须等待闪存包装程序完成编程操作，然后才能返回到任何类型的闪存访问。Fapi_checkFsmForReady() 函数可用于监测已发出命令的状态。

限制

  • 如上所述，该函数一次最多只能对 128 位进行编程（鉴于提供的地址进行了 128 位对齐）。如果用户想对更多位进行编程，则可以循环调用该函数，从而一次对 128 位（或应用程序所需的 64 位）进行编程。
  • 主阵列闪存编程必须与 64 位地址边界对齐，并且每个 64 位字在每个写入或擦除周期只能编程一次。
  • 可以单独对数据和 ECC 进行编程。但是，每个 64 位数据字和相应的 ECC 字在每个写入或擦除周期中只能编程一次。

返回值

  • Fapi_Status_Success（成功）
  • Fapi_Status_FsmBusy（FSM 处于繁忙状态）
  • Fapi_Error_InvalidBaseRegCntlAddress（失败：用户提供的闪存控制寄存器基地址与预期地址不匹配）
  • Fapi_Error_AsyncIncorrectDataBufferLength（失败：指定的数据缓冲区大小不正确。此外，如果在对 BANKMGMT 或 SECCFG 空间进行编程时选择了 Fapi_EccOnly 模式，则也会返回该错误）
  • Fapi_Error_AsyncIncorrectEccBufferLength（失败：指定的 ECC 缓冲区大小不正确）
  • Fapi_Error_AsyncDataEccBufferLengthMismatch（失败：数据缓冲区大小不是 64 位对齐的，或者数据长度跨越了 128 位对齐的存储器边界）
  • Fapi_Error_FlashRegsNotWritable（失败：闪存寄存器写入失败。用户可以确保使用正确的 CPU 执行 API）。
  • Fapi_Error_FeatureNotAvailable（失败：用户传递了不受支持的模式）
  • Fapi_Error_InvalidAddress（失败：用户提供的地址无效。有关有效地址范围的信息，请参阅 F29H85x 和 F29P58x 实时微控制器数据表。）

实现示例

如要了解更多信息，请参阅 F29H85x SDK 中提供的闪存编程示例：“f29h85x-sdk > examples > driverlib > single_core > flash > flash_mode0_128_program”。