大家好，我是痞子衡，是正经搞技术的痞子。今天给大家带来的是痞子衡的个人小项目 - kFlashFile。
痞子衡最近在参与一个基于 i.MXRT1170 的项目，项目有个需求，需要在 Flash 里实时保存一些关键数据（初步设 512 bytes），掉电能恢复。这些数据在访问方式上要友好，最好是很简单的 API 接口，上层无需操心关键这些数据在 Flash 里是如何存储以及具体存储在什么位置，只需在意关键数据保存和读取的操作即可（就像在 RAM 里动态存取那样）。
根据上述需求，痞子衡做了一个参考设计，命名为 kFlashFile，当前是 v1.0 版本。痞子衡写了比较详细的设计文档，特地分享给大家，如果大家有更好的建议和想法，欢迎在文章下面留言。
kFlashFile
一、简介
kFlashFile 是一个基于 NOR Flash 的轻量级文件数据存储方案，用于需要断电数据保存的项目。
kFlashFile 主要为 i.MXRT 系列设计，但其分层框架设计使其也可轻松移植到其他 MCU 平台。
kFlashFile 从设计上分为三层：
- 最底层是Driver层：即Low-level驱动，这层是MCU相关的，对于i.MXRT来说，就是FlexSPI模块的驱动。
- 中间是Adapter层：主要用于适配底层Driver，不同MCU其Driver接口函数可能不同，因此会在这一层做到接口统一。
- 最顶层是API层：纯软件逻辑设计来实现文件数据存储，提供了四个非常简易的API。
二、设计
2.1 API定义
kFlashFile 是一个文件数据存储的设计，file_read()、file_save()是两个必备的 API，此外也提供业界通用 API 接口file_init()、file_deinit()。
- kflash_file_init(): 用于初次分配Flash空间来存储文件数据，并且指定文件长度。如果当前指定的Flash空间里存在有效文件数据，那么继续复用。
- kflash_file_read(): 用于获取当前有效存储的文件数据，文件数据可以部分读取。
- kflash_file_save(): 用于实时写入最新的文件数据，文件数据可以部分更新。
- kflash_file_deinit(): 用于清除当前分配的Flash空间里的文件数据，以便下次重新分配。
status_t kflash_file_init(kflash_file_t *flashFile, uint32_t memStart, uint32_t memSize, uint32_t fileSize);
status_t kflash_file_read(kflash_file_t *flashFile, uint32_t offset, uint8_t *data, uint32_t size);
status_t kflash_file_save(kflash_file_t *flashFile, uint32_t offset, uint8_t *data, uint32_t size);
status_t kflash_file_deinit(kflash_file_t *flashFile);
2.2 空间分配
kFlashFile 将分配的 Flash 空间分成两个部分，前面是文件数据区（Data Sectors），后面是文件头区（Header Sectors）。
文件数据区：从区内起始地址开始按序存放一份份文件数据，只要文件数据出现无法覆盖的更新（即 Flash 无法改写的特性），便会在下一个新地址重新存储。如果数据区满了，便擦除区内起始地址处的历史文件数据，继续循环存储。
文件头区：区内 Sector 起始地址放一个 Magic 值（4字节），用于标识文件头。然后开始按序记录一份份文件数据在文件数据区里的位置信息（默认用 2byte 去记录一份文件数据的位置）。如果当前 Header Sector 存储满了，便换到下一个 Header Sector 继续记录。
2.3 API主参数
kFlashFile 设计上使用 kflash_file_t 型作为 API 主参数，这个参数原型定义如下：
typedef struct {
uint32_t managedStart;
uint32_t managedSize;
uint32_t activedStart;
uint32_t activedSize;
uint32_t recordedIdx;
uint32_t recordedPos;
uint8_t buffer[KFLASH_MAX_FILE_SIZE];
} kflash_file_t;
- managedStart： 表示文件存储区映射首地址，即 kflash_file_init() 调用时的 memStart 值加上 Flash 在内存里映射首地址，managedStart 需要以 Flash Sector 大小对齐。
- managedSize： 表示文件存储区总大小，即 kflash_file_init() 调用时的 memSize 值，需要是 Flash Sector 大小的整数倍。
- activedStart： 表示当前有效文件数据存储的映射首地址，需要以 Flash Page 大小对齐。
- activedSize： 表示当前有效文件数据长度，需要是 Flash Page 大小的整数倍。
- recordedIdx： 表示当前有效文件头所在的 Header Sector 索引。
- recordedPos： 表示 Header Sector 中用于存储当前有效文件数据位置信息的区域偏移。
- buffer[]： 当前有效的文件数据暂存区。
三、实现
3.1 Driver层
在 i.MXRT 系列上，kFlashFile 的 Driver 层即 FlexSPI NOR 驱动，这个驱动既可以采用 MCU SDK 版本，也可以采用 BootROM 版本。
此处推荐 BootROM 版本的 FlexSPI NOR 驱动，因为这个驱动历经多个 MCU ROM 的洗礼，已经相当成熟稳定。这里简单讲下其中 Flash 操作的函数：
- flexspi_nor_flash_erase(uint32_t instance, flexspi_nor_config_t *config, uint32_t start, uint32_t length)：这个函数实现Flash擦除，虽然形参里是任意设定的start, address，但实际擦除还是以Sector对齐的，函数内部会对start和address做自动对齐。
- flexspi_nor_flash_page_program(uint32_t instance, flexspi_nor_config_t *config, uint32_t dstAddr, const uint32_t *src)：这个函数实现Flash编程，一次固定写一整个Page大小的数据，即使dstAddr不是以Page对齐，实际写入的Page数据也不会跨物理Page（会自动跳回同一个物理Page首地址，这是Flash自身特性）。
因为 flexspi_nor_flash_page_program() 每次都要固定编程整个 Page 数据，不够灵活，因此我新写了一个 flexspi_nor_flash_program() 函数，这个函数支持编程用户自定义长度的数据，并且支持跨物理 Page 去写：
- flexspi_nor_flash_program(uint32_t instance, flexspi_nor_config_t *config, uint32_t dstAddr, const uint32_t *src, uint32_t length)：
需要特别注意，对于 SDR 模式的 Flash，最小编程长度可以是 1Byte；而 DDR 模式的 Flash，最小编程长度应是 2Bytes（如果这 2Bytes 地址上有一个 Byte 内容是 0xFF，该 Byte 依旧可以被再次编程）。
此外 flexspi_nor_flash_program() 函数有一个限制，即传入的 src 源数据首地址必须 4 字节对齐，哪怕你只想写入 2 个字节，这是 FlexSPI 模块底层对驱动的要求。
3.2 Adapter层
kFlashFile 的 Adapter 层是对 Driver 层做了一层封装，用于屏蔽硬件相关特性。该层与 MCU 以及板载 Flash 型号息息相关。下面的宏定义适用 i.MXRT1170 芯片以及连接在 FlexSPI1 上的 Octal Flash（MX25UM51345）：
// 表示 Flash 连接的是 FlexSPI1
#define KFLASH_INSTANCE (1)
// BootROM FlexSPI 驱动对 Octal Flash 支持的简易配置值
#define KFLASH_CONFIG_OPTION (0xc0403007)
// FlexSPI1 在系统内存中的映射首地址
#define KFLASH_BASE_ADDRESS (0x30000000)
// 默认的 Flash Sector/Page 大小（如果 Flash 里有 SFDP，则此处定义无效）
#define KFLASH_SECTOR_SIZE (0x1000)
#define KFLASH_PAGE_SIZE (256)
// FlexSPI 编程接口对传入的 src 源数据首地址必须 4 字节对齐
#define KFLASH_PROGRAM_ALIGNMENT (4)
// Flash SDR 模式为 1，DDR 模式为 2
#define KFLASH_PROGRAM_UNIT (2)
kFlashFile 的 Adapter 层接口函数如下，参数是硬件无关的，因此上层可以轻松基于这些接口函数做纯软件逻辑设计。
status_t kflash_drv_init(void);
uint32_t kflash_drv_get_info(kflash_mem_info_t flashInfo);
status_t kflash_drv_erase_region(uint32_t start, uint32_t length);
status_t kflash_drv_program_region(uint32_t dstAddr, const uint32_t *src, uint32_t length);
3.3 API层
kFlashFile 的 API 功能设计思路前面介绍过了，这里介绍具体代码实现，先来看几个关键的宏定义：
// 设置 Header Sector 的个数，至少是 2 个
#define KFLASH_HDR_SECTORS (2)
// 设置 Header Sector 中用于存储当前有效文件数据位置信息的区域存储类型
// uint16_t 最多可记录 65536 个位置，最大可支持的 Data 区域大小为 65536 * 文件数据长度
#define KFLASH_HDR_POS_TYPE uint16_t /* uint16_t or uint32_t */
// 设置总分配的 Flash 长度（Data+Header Sector 的个数），至少是 4 个
#define KFLASH_MIN_SECTORS (KFLASH_HDR_SECTORS + 2)
// 设置最大支持的文件数据长度，需是 Flash Page 的整数倍
#define KFLASH_MAX_FILE_SIZE (KFLASH_PAGE_SIZE * 2)
3.3.1 init()
kflash_file_init() 函数处理流程如下：
如果是首次指定 Flash 空间，那么直接将全部空间擦除干净，并在第一个 Header Sector 中写入初始文件头（Magic + 文件数据位置值 0），即最新有效文件数据在 Flash 空间文件数据区的首地址。
这里有一个特殊的设计，文件数据区其实并不是直接存储用户写入的文件数据，而是将用户文件数据全部按位取反之后再存储进 Flash。这里假定用户数据初始应该是全 0，然后更改主要是将 0 值改为其他值，取反之后，正好对应 Flash 里的 bit1 编程为 bit0（Flash 擦除后是全 0xFF），这样可以充分利用 Flash 覆盖操作以减少擦除次数。
函数中比较关键的步骤是找寻当前 Flash 空间中是否存在有效文件数据，方法是遍历 Header Sector，发现存在 Magic 便继续寻找最新文件数据位置信息存放的区域（默认 2 字节），按照前面的设计，只需要按序读取区域内容，直到遇到 0xFFFF 为止。
3.3.2 read()
kflash_file_read() 函数最简单了，直接从缓存区 buffer 里获取数据即可，因为每次更新文件数据操作完成之后都会将最新文件数据放在 buffer 里。
3.3.3 save()
kflash_file_save() 函数是最核心的函数了，这里逻辑比较复杂，涉及文件数据区全部满了之后的动作，以及文件头区某个 Sector 满了的动作。其处理流程如下：
当有一个新文件数据要求保存时，首先会判断这个文件能不能在 Flash 中直接覆盖存储，如果能，那就直接覆盖存储，文件头完全不需要更新，这种情况比较简单。
如果新文件数据无法直接覆盖存储，那么首先判断文件数据区是否满了，如果上一个文件数据已经存在了文件数据区的最后位置，此时需要擦除数据区第一个 Sector 从头开始存储。如果没有到最后位置，那就按序往下存储。
新文件数据已经保存到数据区之后，此时需要处理文件头，记录这个新文件数据的位置。如果文件头区已经记录到当前 Sector 的最后位置，需要切换到下一个 Sector 开始存储，切换存储完新位置后，将之前 Sector 擦除。如果没有，那就按序在当前 Sector 继续记录。
3.3.4 deinit()
kflash_file_deinit() 函数也比较简单，就是将文件头区域 Header Sectors 全部擦除即可，文件数据区内容可以不用管，下次重新分配 Flash 时会做擦除。
欢迎订阅
文章会同时发布到我的 博客园主页、CSDN主页、微信公众号 平台上。
微信搜索"痞子衡嵌入式"或者扫描下面二维码，就可以在手机上第一时间看了哦。
