mFS：面向EEPROM的轻量级嵌入式文件系统

1. mFS 文件系统概述mFSmicro File System是一个专为串行 EEPROM 存储器芯片设计的轻量级嵌入式文件系统库。它不依赖于任何操作系统或硬件抽象层以纯 C 实现代码体积紧凑典型编译后 ROM 占用 4 KBRAM 消耗极低运行时仅需约 64–128 字节静态缓冲区适用于资源受限的 8/16/32 位 MCU 平台如 STM32F0/F1、NXP KL25Z、ESP32-C3、RISC-V GD32E230 等。与 FatFS、LittleFS 或 SPIFFS 等通用型 Flash 文件系统不同mFS 的设计哲学是面向 EEPROM 特性而生它不试图模拟块设备抽象而是直接建模 EEPROM 的物理行为——按字节寻址、页内随机写、页擦除不可逆、写寿命有限通常 10⁵–10⁶ 次、写操作需等待完成典型写周期 1–10 ms。因此mFS 放弃了传统文件系统的目录树、长文件名、时间戳、权限位等冗余特性转而聚焦于三个核心工程目标磨损均衡Wear Leveling在有限擦写次数约束下最大化 EEPROM 使用寿命断电安全Power-Fail Safety确保任意时刻掉电后已提交的数据不丢失、元数据不损坏确定性延迟Deterministic Latency所有 API 调用时间可预测无隐式阻塞或动态内存分配满足硬实时场景需求。这些目标决定了 mFS 的底层架构它采用日志结构 元数据影子页Shadow Page 写前日志Write-Ahead Logging, WAL三重机制协同工作。整个文件系统仅管理一个扁平命名空间下的若干“逻辑文件”每个文件由连续的逻辑块block组成块大小固定默认 32 字节可配置文件最大长度受 EEPROM 容量与元数据开销共同限制典型支持 1–255 个文件单文件最大 4–64 KB。mFS 不提供 POSIX 接口其 API 设计遵循嵌入式开发惯例所有函数返回int类型错误码MFS_OK 0负值为错误如MFS_ERR_FULL -1、MFS_ERR_CORRUPT -2无全局状态变量全部上下文通过mfs_t*句柄传递天然支持多实例例如同时挂载两片不同 I²C 地址的 AT24C512。2. 硬件接口与驱动集成mFS 本身不包含硬件驱动而是通过一组可移植的底层函数指针与用户驱动解耦。开发者必须实现以下 5 个基础 I/O 回调并在初始化时注入mfs_t结构体回调函数签名作用说明典型实现要点int (*read)(void *ctx, uint32_t addr, void *buf, uint32_t len)从 EEPROM 地址addr读取len字节到buf需处理 I²C/SPI 传输分包如 AT24C512 单次最多读 128 字节、地址跨页page boundary自动递增int (*write)(void *ctx, uint32_t addr, const void *buf, uint32_t len)向 EEPROM 地址addr写入len字节必须阻塞等待写完成调用while(!is_write_complete())或延时 tWR如 AT24C02 为 10 ms禁止在中断中调用int (*erase_page)(void *ctx, uint32_t page_addr)擦除起始地址为page_addr的整页页大小由芯片决定如 16/32/64 字节对 EEPROM 实为“无效化”操作向页内所有字节写0xFF需确保页对齐uint32_t (*get_page_size)(void *ctx)返回硬件页大小字节从芯片手册获取如 24LC256 为 64AT24C01 为 8uint32_t (*get_size)(void *ctx)返回 EEPROM 总容量字节如 24LC512 为 65536关键工程实践write回调的可靠性直接决定文件系统健壮性。以 STM32 HAL 库为例I²C 写操作必须使用HAL_I2C_Master_Transmit()并检查返回值且严禁省略写完成轮询// 示例AT24C512 (I²C) write 回调实现 static int eeprom_write(void *ctx, uint32_t addr, const void *buf, uint32_t len) { I2C_HandleTypeDef *hi2c (I2C_HandleTypeDef*)ctx; uint8_t cmd[2] {(uint8_t)(addr 8), (uint8_t)addr}; // 16-bit address HAL_StatusTypeDef ret; // 1. 发送地址命令 ret HAL_I2C_Master_Transmit(hi2c, 0xA0, cmd, 2, HAL_MAX_DELAY); if (ret ! HAL_OK) return MFS_ERR_IO; // 2. 发送数据注意不能超过页边界 ret HAL_I2C_Master_Transmit(hi2c, 0xA0, (uint8_t*)buf, len, HAL_MAX_DELAY); if (ret ! HAL_OK) return MFS_ERR_IO; // 3. 等待写完成关键 uint32_t timeout 10000; // 10ms 1MHz SysTick while (timeout-- HAL_I2C_IsDeviceReady(hi2c, 0xA0, 1, 100) ! HAL_OK); if (timeout 0) return MFS_ERR_TIMEOUT; return MFS_OK; }mfs_t初始化示例static mfs_t g_mfs; static I2C_HandleTypeDef hi2c1; // 假设已 HAL_I2C_Init() void mfs_init(void) { g_mfs.read eeprom_read; g_mfs.write eeprom_write; g_mfs.erase_page eeprom_erase_page; g_mfs.get_page_size eeprom_get_page_size; g_mfs.get_size eeprom_get_size; g_mfs.ctx hi2c1; // 传递驱动上下文 // 格式化首次使用必调用 int err mfs_format(g_mfs); if (err ! MFS_OK) { // 处理格式化失败可能是硬件故障或驱动错误 } }3. 核心数据结构与存储布局mFS 将 EEPROM 划分为三个逻辑区域其布局由mfs_format()在首次调用时固化后续所有操作均严格遵守该布局区域起始地址大小内容说明元数据区Metadata Area0x0000固定 2 页如 128 字节存储文件系统超级块superblock和文件索引表file table采用双影子页primary/backup实现原子更新日志区Log Area紧接元数据区后动态分配最小 1 页循环缓冲区记录所有文件写操作的“事务日志”每条日志含文件 ID、偏移、数据长度、CRC16数据区Data Area日志区末尾起剩余全部空间存储实际文件内容按固定块block组织块间可非连续磨损均衡基础3.1 超级块Superblock结构位于元数据区首页开头定义文件系统全局参数typedef struct { uint32_t magic; // 固定值 0x4D465300 (MFS\0)用于校验 uint16_t version; // 格式版本号当前为 1 uint16_t nfiles; // 当前文件总数0–255 uint32_t log_start; // 日志区起始地址相对于 EEPROM 起始 uint32_t log_end; // 日志区结束地址 uint32_t data_start; // 数据区起始地址 uint16_t block_size; // 逻辑块大小字节默认 32 uint16_t crc16; // 本结构体 CRC16覆盖 magic 至 block_size } mfs_super_t;工程要点magic和crc16是检测介质损坏的关键。mfs_mount()会读取主/备超级块并校验若两者均失效则返回MFS_ERR_CORRUPT此时需调用mfs_format()重建。3.2 文件索引表File Table紧随超级块之后每个表项描述一个文件typedef struct { uint8_t used; // 1有效文件0空闲槽位 uint8_t name_len; // 文件名长度1–15 字节 char name[15]; // ASCII 文件名不以 \0 结尾 uint32_t size; // 当前文件字节数≤ 2^24 uint32_t head_block; // 数据区中第一个逻辑块的地址物理地址 uint32_t nblocks; // 已分配的逻辑块总数 uint16_t crc16; // 本表项 CRC16 } mfs_file_t;关键设计head_block指向的是数据区中的物理地址而非逻辑块号。mFS 不维护链表或 FAT 表文件数据块在物理上是连续存储的由nblocks × block_size决定长度这极大简化了读写逻辑但要求mfs_write()在文件增长时能分配新的连续块——这正是磨损均衡算法的核心挑战。3.3 日志区Log Area格式日志区为循环缓冲区每条日志记录log entry结构如下typedef struct { uint8_t file_id; // 关联的文件索引表下标0–254 uint32_t offset; // 在文件内的字节偏移必须对齐到 block_size uint16_t len; // 写入字节数≤ block_size uint8_t data[32]; // 实际数据长度由 len 决定不足补 0xFF uint16_t crc16; // 本日志项 CRC16 } mfs_log_entry_t;断电安全机制当mfs_write()被调用时mFS 不直接修改数据区而是先将日志项写入日志区原子操作再更新文件索引表中的size和nblocks。系统启动时mfs_mount()会回放replay所有有效日志将数据从日志区“提交”到数据区并清理日志。即使掉电发生在日志写入后、数据提交前重启后回放仍能恢复一致状态。4. 主要 API 接口详解mFS 提供 7 个核心 API全部为同步、无锁、无动态内存分配API原型作用典型调用场景mfs_format()int mfs_format(mfs_t *fs)格式化整个 EEPROM创建初始元数据区设备首次上电、恢复出厂设置mfs_mount()int mfs_mount(mfs_t *fs)挂载文件系统校验元数据并回放日志系统初始化完成后mfs_open()int mfs_open(mfs_t *fs, const char *name, uint8_t flags)打开/创建文件返回文件句柄int fd读取配置、记录日志前mfs_read()int mfs_read(mfs_t *fs, int fd, void *buf, uint32_t len)从文件当前位置读取len字节加载固件参数、读取传感器校准值mfs_write()int mfs_write(mfs_t *fs, int fd, const void *buf, uint32_t len)向文件当前位置写入len字节保存用户设置、追加事件日志mfs_seek()int mfs_seek(mfs_t *fs, int fd, int32_t offset, int whence)移动文件读写位置随机访问配置项、覆盖写特定字段mfs_close()int mfs_close(mfs_t *fs, int fd)关闭文件触发元数据持久化操作完成后必须调用4.1mfs_open()与文件生命周期flags参数仅支持两个标志位组合MFS_O_RDONLY0x01只读打开文件必须存在MFS_O_CREAT0x02若不存在则创建需配合MFS_O_WRONLYMFS_O_WRONLY0x04只写打开创建或截断MFS_O_APPEND0x08写入时自动定位到文件末尾。文件创建流程在文件索引表中查找首个used 0的空闲槽位分配数据区中一块连续空间大小 block_size填充mfs_file_t表项name,size0,head_block,nblocks1将表项写入元数据区双影子页更新保证原子性返回文件句柄即槽位索引。注意mFS 不支持O_TRUNC单独使用。若需清空文件应open(..., MFS_O_WRONLY | MFS_O_CREAT)此时会重置size0并复用原有块不释放空间或显式调用mfs_unlink()。4.2mfs_write()的磨损均衡实现这是 mFS 最精妙的算法。当向一个已存在的文件写入新数据时mFS 不直接覆写原位置避免局部磨损而是计算所需新块数new_blocks ceil((offset len) / block_size)若new_blocks file-nblocks则分配new_blocks - file-nblocks个全新连续块从数据区未使用部分分配将旧数据offset之前 新数据 旧数据offsetlen之后按块粒度复制到新块中更新文件索引表head_block指向新块首地址nblocks new_blocks异步触发旧块擦除在mfs_close()或后台任务中将原head_block所在页标记为“待擦除”并在下次分配时优先选择此类页。该策略确保写操作均匀分散到整个 EEPROM实测可将 AT24C021K×8的寿命从理论 10⁵ 次提升至 5×10⁶ 次有效写入。4.3mfs_seek()的定位语义whence参数定义基准位置MFS_SEEK_SET从文件开头offset 为绝对位置MFS_SEEK_CUR从当前位置offset 为相对偏移MFS_SEEK_END从文件末尾offset 为负值如-4表示倒数第 4 字节。重要限制由于 mFS 无缓存seek操作本身不触发 I/O仅更新文件句柄内部的pos字段。真正的读写效率取决于pos是否对齐到block_size——对齐时可整块读写非对齐时需读取包含pos的完整块修改其中字节再整块写回增加一次读操作。5. 典型应用示例与工程实践5.1 配置参数存储推荐模式在 STM32F103 上使用 AT24C25632KB存储 Wi-Fi 配置typedef struct { char ssid[33]; char password[65]; uint8_t channel; uint8_t dhcp; uint32_t ip; } wifi_cfg_t; wifi_cfg_t g_cfg; void load_wifi_config(void) { int fd mfs_open(g_mfs, wifi.cfg, MFS_O_RDONLY); if (fd 0) { mfs_read(g_mfs, fd, g_cfg, sizeof(g_cfg)); mfs_close(g_mfs, fd); } else { // 默认配置 memset(g_cfg, 0, sizeof(g_cfg)); strcpy(g_cfg.ssid, MyAP); strcpy(g_cfg.password, 12345678); } } void save_wifi_config(void) { int fd mfs_open(g_mfs, wifi.cfg, MFS_O_WRONLY | MFS_O_CREAT); if (fd 0) { mfs_write(g_mfs, fd, g_cfg, sizeof(g_cfg)); mfs_close(g_mfs, fd); } }优势相比直接裸写 EEPROM此方案自动处理磨损均衡且save_wifi_config()调用后立即掉电重启仍能读到完整配置日志回放保证。5.2 循环事件日志带时间戳扩展为支持时间戳可在日志结构前添加 4 字节 Unix 时间戳typedef struct { uint32_t timestamp; // 由 RTC 获取 uint16_t event_id; uint8_t payload[26]; // 保持总长 ≤ 32 字节 } event_log_t; void log_event(uint16_t id, const void *data, uint8_t len) { event_log_t log; log.timestamp get_rtc_timestamp(); log.event_id id; memcpy(log.payload, data, len); // 填充剩余字节为 0xFFmFS 写入时自动填充 int fd mfs_open(g_mfs, events.log, MFS_O_WRONLY | MFS_O_APPEND); if (fd 0) { mfs_write(g_mfs, fd, log, sizeof(log)); mfs_close(g_mfs, fd); } }注意事项events.log文件会持续增长需定期mfs_unlink()并重建或实现应用层滚动逻辑。5.3 与 FreeRTOS 集成在多任务环境中需确保 mFS 调用的线程安全性。由于 mFS 无全局状态只需保护mfs_t句柄的并发访问static SemaphoreHandle_t g_mfs_mutex; void mfs_rtos_init(void) { g_mfs_mutex xSemaphoreCreateMutex(); } int mfs_rtos_open(mfs_t *fs, const char *name, uint8_t flags) { xSemaphoreTake(g_mfs_mutex, portMAX_DELAY); int ret mfs_open(fs, name, flags); xSemaphoreGive(g_mfs_mutex); return ret; } // 其他 API 同理封装...关键点互斥锁仅保护 mFS 内部元数据操作如文件索引表更新EEPROM 硬件驱动本身必须是可重入的如 HAL_I2C 是线程安全的。6. 故障诊断与调试技巧6.1 常见错误码与对策错误码含义排查步骤MFS_ERR_IO(-3)底层read/write回调返回失败检查 I²C/SPI 硬件连接、上拉电阻、地址是否正确、write是否遗漏写完成等待MFS_ERR_FULL(-1)文件系统满无空闲文件槽或数据区耗尽调用mfs_stat()查看剩余空间删除不用文件增大 EEPROM 容量MFS_ERR_CORRUPT(-2)元数据 CRC 校验失败确认magic值检查read回调是否读错地址尝试mfs_format()重建MFS_ERR_INVAL(-4)无效参数如name为空、len为 0检查 API 调用参数合法性6.2 调试辅助函数mFS 提供非公开但高度实用的调试接口需在mfs.h中取消注释#define MFS_DEBUGmfs_dump_super()打印超级块内容mfs_dump_file_table()列出所有文件及其属性mfs_dump_log()显示日志区当前内容mfs_stat()返回mfs_stat_t结构含total_bytes,used_bytes,free_files,max_file_size。这些函数在开发阶段可直接通过 UART 输出快速定位问题。6.3 硬件级验证方法写周期验证用逻辑分析仪抓取 I²C 波形确认write回调发出的地址帧、数据帧正确且两次写操作间隔 ≥tWR擦除效果验证用万用表测量 EEPROM VCC 引脚在erase_page调用期间观察电流尖峰典型 1–3 mA确认擦除电路工作断电测试在mfs_write()调用后 1 ms 内强制断电重启后验证数据一致性。7. 性能与资源占用实测数据基于 STM32F072CBT648 MHz AT24C512I²C400 kHz平台实测操作平均耗时最大耗时说明mfs_mount()18 ms25 ms主要消耗在日志回放读取整个日志区mfs_open()存在文件0.12 ms0.15 ms仅查表mfs_read()32 字节对齐1.8 ms2.1 ms1 次 I²C 读传输mfs_write()32 字节对齐12.5 ms15.2 ms含写完成等待AT24C512tWR10msmfs_format()320 ms350 ms擦除全部元数据区和日志区资源占用ARM GCC -OsFlash3.7 KB含 CRC16 算法RAMmfs_t结构体 48 字节 静态缓冲区 32 字节用于日志项暂存 80 字节栈深度最深路径mfs_write()约 128 字节无递归。该数据证实 mFS 完全满足 Cortex-M0/M3 的严苛资源约束且所有操作时间边界清晰可纳入实时调度分析。8. 与同类方案对比及选型建议特性mFSFatFSEEPROM 模式LittleFSSPIFFS设计目标EEPROM 原生优化通用块设备模拟NAND/NOR FlashSPI NOR Flash磨损均衡✅ 页级动态均衡❌需外部实现✅LFS2✅哈希断电安全✅WAL 影子页⚠️需f_sync显式调用✅Copy-on-write⚠️部分场景丢失RAM 占用80 B1–3 KB2–5 KB1–2 KBFlash 占用3.7 KB12–18 KB15–25 KB8–12 KB文件名长度≤15 字节≤12 字节8.3≤255 字节≤32 字节目录支持❌扁平命名空间✅✅❌适用场景配置存储、小型日志、固件参数需兼容 SD 卡的混合系统需目录结构的 OTA 升级ESP8266/ESP32 传统方案选型结论若项目仅需存储几十字节到几 KB 的配置、校准值、简单日志且 MCU RAM 2 KBmFS 是最优解若需支持子目录、长文件名、或未来可能迁移到 SPI Flash应评估 LittleFSFatFS 在 EEPROM 上性能差、寿命短仅在已有 FatFS 代码库且不愿重构时考虑SPIFFS 已停止维护不推荐新项目。mFS 的价值不在于功能丰富而在于以最小的资源代价为 EEPROM 提供了工业级的可靠性保障——这正是嵌入式底层开发最稀缺的品质。