跳至主要內容

Fls模块用户手册

大约 8 分钟约 2412 字2025/12/26

Fls模块用户手册

目录

1. 简介

本模块提供了对 FLS (Flash Memory) 的抽象接口，用于对微控制器的PFlash（程序闪存）和DFlash（数据闪存）进行读、写和擦除操作。

  • 初始化: 通过 HLI_Fls_Init 函数为驱动程序提供一个标准的初始化入口（当前为空实现）。
  • 数据操作:
    • Hli_Fls_Read: 从PFlash或DFlash的任意地址读取数据。
    • HLI_PFlash_WriteMinimumWriteableBytes / HLI_DFlash_WriteMinimumWriteableBytes: 以最小可操作单位向PFlash或DFlash写入数据。
    • HLI_PFlash_EraseSector / HLI_DFlash_EraseSector: 按扇区擦除PFlash或DFlash。
    • HLI_PFlash_EraseAndWriteSector / HLI_DFlash_EraseAndWriteSector: 执行先擦除后写入的原子操作。
  • 状态检查: Hli_Fls_GetSectorEmptyStatus 用于检查指定扇区是否为空。
  • 安全机制: 所有写和擦除操作都需要传入一个软件密钥 FLS_KEY 来解锁保护。
  • 系统支持: 在耗时较长的Flash操作期间，会自动调用弱定义的 HLI_Fls_FeedDog 函数来喂狗，防止系统复位。

注

扇区及最小可操作单元，不同型号可能有所差异，请参考对应芯片的用户手册。

1.1 支持的设备

当前软件适用于以下芯片:

  • KF32A158xxxSF

1.2 名词及缩写

缩写解释
MCU微控制器
ISR中断服务例程
FLSFlash存储通道

2. 文件结构

文件名称描述
kf32axxx_hli_fls.c此文件包含fls驱动程序的通用功能
kf32axxx_hli_fls.h此头文件输出fls驱动程序的宏、类型定义和函数原型
kf32axxx_hli_fls_cfg.h此文件包含Flash相关的静态配置宏定义

3. 数据结构

3.1 数据类型

3.1.1 宏定义

  1. Flash软件KEY

    宏定义解释
    FLS_KEYFlash软件KEY, 在调用函数时作为入参

3.1.2 枚举

  1. 函数执行结果 (HLI_Fls_StatusType)

    枚举值解释
    HLI_FLS_STATUS_OK函数执行成功
    HLI_FLS_STATUS_PARAM_ERR传入参数错误
    HLI_FLS_STATUS_ERRORFlash状态错误

3.1.3 类型定义

无。

3.2 配置项说明

  1. 静态配置

    静态配置在 kf32axxx_hli_fls_cfg.h 文件中通过宏定义完成。

    宏定义解释取值范围
    FLS_MIN_OPERABLE_ADDRESS可以操作闪存的最小地址（单位：字节），默认为1KB。小于该地址的擦写操作将直接返回错误。0 - Flash最大地址
    FLS_FEATURE_AB_SWAP_ENABLEAB分区特性使能。true/false

    注

    注意：使能AB分区特性后，可操作PFlash的范围可能发生变化。KF32A158xxxSF系列仅可操作备份区域的地址范围（512KB ~ 992KB）。

4. 驱动函数

4.1 函数接口

4.1.1 HLI_Fls_Init

NameDescription
函数名称HLI_Fls_Init
语法void HLI_Fls_Init(void)
同步/异步同步
重入性不可重入
形参(输入)
返回值无
描述初始化Fls驱动。
注意事项空函数, 仅为结构完整。

4.1.2 Hli_Fls_GetSectorEmptyStatus

NameDescription
函数名称Hli_Fls_GetSectorEmptyStatus
语法HLI_Fls_StatusType Hli_Fls_GetSectorEmptyStatus(uint32_t Addr)
同步/异步同步
重入性不可重入
形参(输入)Addr : 待检查扇区内的任意地址。
返回值HLI_FLS_STATUS_OK: 扇区为空
返回值HLI_FLS_STATUS_ERROR: 扇区非空
返回值HLI_FLS_STATUS_PARAM_ERR: 参数错误
描述判断指定地址所在的扇区是否为空（全为0xFF）。
注意事项

4.1.3 Hli_Fls_Read

NameDescription
函数名称Hli_Fls_Read
语法HLI_Fls_StatusType Hli_Fls_Read(uint32_t ReadAddr, uint32_t DataLength, uint8_t *Buffers)
同步/异步同步
重入性可重入
形参(输入)ReadAddr : 读取的起始地址。
形参(输入)DataLength : 读取的数据长度（单位：字节）。
形参(输出)Buffers : 存放读取数据的缓冲区指针。
返回值HLI_FLS_STATUS_OK: 读取成功
返回值HLI_FLS_STATUS_PARAM_ERR: 参数错误
描述从指定的Flash地址读取数据。
注意事项

4.1.4 HLI_PFlash_WriteMinimumWriteableBytes

NameDescription
函数名称HLI_PFlash_WriteMinimumWriteableBytes
语法HLI_Fls_StatusType HLI_PFlash_WriteMinimumWriteableBytes(uint32_t Key, uint32_t WriteAddr, uint32_t DataLength, uint8_t *Buffers)
同步/异步同步
重入性不可重入
形参(输入)Key: 软件密钥，必须为 FLS_KEY (0x5A5A6688U)。
形参(输入)WriteAddr : 写入的起始地址。
形参(输入)DataLength : 写入的数据长度。
形参(输入)Buffers : 指向待写入数据的指针。
返回值HLI_FLS_STATUS_OK: 写入成功
返回值HLI_FLS_STATUS_PARAM_ERR: 参数错误
返回值HLI_FLS_STATUS_ERROR: Flash状态错误
描述以最小可操作单元向PFlash写入数据。
注意事项写入的地址和长度必须是对齐最小可操作单元。

4.1.5 HLI_PFlash_EraseSector

NameDescription
函数名称HLI_PFlash_EraseSector
语法HLI_Fls_StatusType HLI_PFlash_EraseSector(uint32_t Key, uint32_t EraseAddr, uint32_t Length)
同步/异步同步
重入性不可重入
形参(输入)Key: 软件密钥，必须为 FLS_KEY (0x5A5A6688U)。
形参(输入)EraseAddr : 擦除的起始地址。
形参(输入)Length : 擦除的长度。
返回值HLI_FLS_STATUS_OK: 擦除成功
返回值HLI_FLS_STATUS_PARAM_ERR: 参数错误
返回值HLI_FLS_STATUS_ERROR: Flash状态错误
描述擦除PFlash的指定区域。
注意事项擦除的地址和长度必须按扇区对齐。

4.1.6 HLI_PFlash_EraseAndWriteSector

NameDescription
函数名称HLI_PFlash_EraseAndWriteSector
语法HLI_Fls_StatusType HLI_PFlash_EraseAndWriteSector(uint32_t Key, uint32_t Addr, uint32_t Length, uint8_t *Buffers)
同步/异步同步
重入性不可重入
形参(输入)Key: 软件密钥，必须为 FLS_KEY (0x5A5A6688U)。
形参(输入)Addr : 擦除和写入的起始地址。
形参(输入)Length : 操作的数据长度。
形参(输入)Buffers : 指向待写入数据的指针。
返回值HLI_FLS_STATUS_OK: 操作成功
返回值HLI_FLS_STATUS_PARAM_ERR: 参数错误
返回值HLI_FLS_STATUS_ERROR: Flash状态错误
描述原子操作：先擦除PFlash指定区域，然后写入新数据。
注意事项操作的地址和长度必须按扇区对齐。

4.1.7 HLI_DFlash_WriteMinimumWriteableBytes

NameDescription
函数名称HLI_DFlash_WriteMinimumWriteableBytes
语法HLI_Fls_StatusType HLI_DFlash_WriteMinimumWriteableBytes(uint32_t Key, uint32_t WriteAddr, uint32_t DataLength, uint8_t *Buffers)
同步/异步同步
重入性不可重入
形参(输入)Key: 软件密钥，必须为 FLS_KEY (0x5A5A6688U)。
形参(输入)WriteAddr : 写入的起始地址。
形参(输入)DataLength : 写入的数据长度。
形参(输入)Buffers : 指向待写入数据的指针。
返回值HLI_FLS_STATUS_OK: 写入成功
返回值HLI_FLS_STATUS_PARAM_ERR: 参数错误
返回值HLI_FLS_STATUS_ERROR: Flash状态错误
描述以最小可操作单元向DFlash写入数据。
注意事项写入的地址和长度必须对齐最小可操作单元。

4.1.8 HLI_DFlash_EraseSector

NameDescription
函数名称HLI_DFlash_EraseSector
语法HLI_Fls_StatusType HLI_DFlash_EraseSector(uint32_t Key, uint32_t EraseAddr, uint32_t Length)
同步/异步同步
重入性不可重入
形参(输入)Key: 软件密钥，必须为 FLS_KEY (0x5A5A6688U)。
形参(输入)EraseAddr : 擦除的起始地址。
形参(输入)Length : 擦除的长度。
返回值HLI_FLS_STATUS_OK: 擦除成功
返回值HLI_FLS_STATUS_PARAM_ERR: 参数错误
返回值HLI_FLS_STATUS_ERROR: Flash状态错误
描述擦除DFlash的指定区域。
注意事项擦除的地址和长度必须按扇区对齐。

4.1.9 HLI_DFlash_EraseAndWriteSector

NameDescription
函数名称HLI_DFlash_EraseAndWriteSector
语法HLI_Fls_StatusType HLI_DFlash_EraseAndWriteSector(uint32_t Key, uint32_t Addr, uint32_t Length, uint8_t *Buffers)
同步/异步同步
重入性不可重入
形参(输入)Key: 软件密钥，必须为 FLS_KEY (0x5A5A6688U)。
形参(输入)Addr : 擦除和写入的起始地址。
形参(输入)Length : 操作的数据长度。
形参(输入)Buffers : 指向待写入数据的指针。
返回值HLI_FLS_STATUS_OK: 操作成功
返回值HLI_FLS_STATUS_PARAM_ERR: 参数错误
返回值HLI_FLS_STATUS_ERROR: Flash状态错误
描述原子操作：先擦除DFlash指定区域，然后写入新数据。
注意事项操作的地址和长度必须按扇区对齐。

4.1.10 HLI_Fls_FeedDog

NameDescription
函数名称HLI_Fls_FeedDog
语法void HLI_Fls_FeedDog(void)
同步/异步同步
重入性可重入
形参(输入)无
形参(输出)无
返回值无
描述喂狗函数。
注意事项本函数为弱定义函数，在Flash擦写等耗时操作中被调用。用户可重新定义本函数以实现自定义的喂狗逻辑（例如，当使用窗口看门狗时）。

4.2 中断回调

无。

5. 使用示例

注

示例中使用的参数仅用作示例演示，应用时以实际为准。

此示例展示了如何对PFlash进行“擦除后写入”的操作。

6. 限制与假设

  1. 地址对齐: 擦除和写入操作的地址和长度必须分别按扇区和最小可操作单元对齐。
  2. 地址范围: 操作的地址范围不能超过芯片实际的Flash大小。
  3. 密钥: 所有擦除和写入操作都必须提供正确的软件密钥。
  4. AB分区: 如果使能了AB分区功能，PFlash的可操作区域会受到限制。
  5. 在封装FLS接口时, 将第一个参数 Key 封装至应用层接口。

注

扇区及最小可操作单元，不同型号可能有所差异，请参考对应芯片的用户手册。

7. 变更记录

版本时间变更记录
v1.02025.11.20新增初版文档
最近更新
贡献者: 翟宇