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

1. mFS 文件系统概述

mFS（micro File System）是一个专为串行 EEPROM 存储器芯片设计的轻量级嵌入式文件系统库。它不依赖于任何操作系统或硬件抽象层，以纯 C 实现，代码体积紧凑（典型编译后 ROM 占用 < 4 KB），RAM 消耗极低（运行时仅需约 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结构体：

关键工程实践：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()在首次调用时固化，后续所有操作均严格遵守该布局：

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，全部为同步、无锁、无动态内存分配：

4.1mfs_open()与文件生命周期

flags参数仅支持两个标志位组合：

• MFS_O_RDONLY（0x01）：只读打开，文件必须存在；
• MFS_O_CREAT（0x02）：若不存在则创建（需配合MFS_O_WRONLY）；
• MFS_O_WRONLY（0x04）：只写打开（创建或截断）；
• MFS_O_APPEND（0x08）：写入时自动定位到文件末尾。

文件创建流程：

1. 在文件索引表中查找首个used == 0的空闲槽位；
2. 分配数据区中一块连续空间（大小 =block_size）；
3. 填充mfs_file_t表项（name,size=0,head_block,nblocks=1）；
4. 将表项写入元数据区（双影子页更新，保证原子性）；
5. 返回文件句柄（即槽位索引）。

注意：mFS 不支持O_TRUNC单独使用。若需清空文件，应open(..., MFS_O_WRONLY | MFS_O_CREAT)，此时会重置size=0并复用原有块（不释放空间），或显式调用mfs_unlink()。

4.2mfs_write()的磨损均衡实现

这是 mFS 最精妙的算法。当向一个已存在的文件写入新数据时，mFS 不直接覆写原位置（避免局部磨损），而是：

1. 计算所需新块数：new_blocks = ceil((offset + len) / block_size)；
2. 若new_blocks > file->nblocks，则分配new_blocks - file->nblocks个全新连续块（从数据区未使用部分分配）；
3. 将旧数据（offset之前）+ 新数据 + 旧数据（offset+len之后）按块粒度复制到新块中；
4. 更新文件索引表：head_block指向新块首地址，nblocks = new_blocks；
5. 异步触发旧块擦除：在mfs_close()或后台任务中，将原head_block所在页标记为“待擦除”，并在下次分配时优先选择此类页。

该策略确保写操作均匀分散到整个 EEPROM，实测可将 AT24C02（1K×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 上使用 AT24C256（32KB）存储 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); // 填充剩余字节为 0xFF（mFS 写入时自动填充） 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 常见错误码与对策

6.2 调试辅助函数

mFS 提供非公开但高度实用的调试接口（需在mfs.h中取消注释#define MFS_DEBUG）：

• mfs_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. 性能与资源占用实测数据

基于 STM32F072CBT6（48 MHz） + AT24C512（I²C@400 kHz）平台实测：

资源占用（ARM GCC -Os）：

• Flash：3.7 KB（含 CRC16 算法）；
• RAM：mfs_t结构体 48 字节 + 静态缓冲区 32 字节（用于日志项暂存） =80 字节；
• 栈深度：最深路径mfs_write()约 128 字节（无递归）。

该数据证实 mFS 完全满足 Cortex-M0+/M3 的严苛资源约束，且所有操作时间边界清晰，可纳入实时调度分析。

8. 与同类方案对比及选型建议

选型结论：

• 若项目仅需存储几十字节到几 KB 的配置、校准值、简单日志，且 MCU RAM < 2 KB，mFS 是最优解；
• 若需支持子目录、长文件名、或未来可能迁移到 SPI Flash，应评估 LittleFS；
• FatFS 在 EEPROM 上性能差、寿命短，仅在已有 FatFS 代码库且不愿重构时考虑；
• SPIFFS 已停止维护，不推荐新项目。

mFS 的价值不在于功能丰富，而在于以最小的资源代价，为 EEPROM 提供了工业级的可靠性保障——这正是嵌入式底层开发最稀缺的品质。