不能直接用 fwrite 写日志到 Flash，因其不支持字节级随机写、需先擦除且擦除粒度大；裸写会导致写失败、寿命骤降、断电数据错乱。
为什么不能直接用 fwrite 写日志到 Flash
嵌入式 Flash（尤其是 NOR/NAND）不支持字节级随机写，擦除粒度大（如 4KB 块），且写前必须先擦除。直接调用 fwrite 或裸写会导致：立即触发写失败、Flash 寿命骤降、断电后数据错乱甚至整个块变砖。日志模块不是“存下来就行”，而是“断电瞬间已提交的日志必须可恢复、未提交的必须被丢弃”。核心矛盾在于：Flash 的物理约束 vs 日志的原子性要求。
用环形日志区 + 状态标记实现断电安全
不依赖文件系统层，直接在 Flash 上划分固定区域（例如 64KB），按页（如 256B）组织为环形缓冲。每条日志前加 4 字节头：uint32_t len（有效负载长度）+ uint8_t flag（0x01=valid, 0xFF=invalid），末尾补 CRC8。写入时永远只写新页，从不覆盖旧页；写完 payload 后，再单独写 flag 字节 —— 这是关键：flag 是“提交开关”，断电若发生在 flag 写入前，该页自动被跳过；若 flag 已写，说明整条日志完整落盘。
- 初始化时扫描所有页，从第一个
flag == 0x01的页开始读取，直到遇到flag != 0x01 - 写入前检查当前页是否为空（全 0xFF），否则跳到下一页；避免误判已擦除页为“脏页”
- 每次写入必须按页对齐，且确保
len不超过页净载荷（如 256 − 5 = 251 字节） - 不要省略 CRC 校验：Flash 位翻转常见，CRC 能过滤掉因断电导致的半写损坏页
擦除策略必须延迟且受控
Flash 擦除是耗时操作（几十 ms），且有擦写次数限制（通常 10⁵ 次）。不能每次写满就擦，也不能等坏块堆积。推荐“懒擦除”：仅当环形区无空页可用时，才擦除最老的有效日志页所在块（需提前记录页→块映射）。擦除前，先将该块中其余有效页迁移至其他块（即“垃圾回收”），再整块擦除。实际中建议预留至少 2 个备用块，避免擦除时无处迁移。
- 擦除前必须确认目标块中所有页均已标记
flag != 0x01，或已迁移完毕 - 使用
HAL_FLASHEx_Erase（STM32）或对应 MCU 的底层擦除 API，勿用模拟 EEPROM 库——它们不保证原子性 - 擦除失败（如电压跌落）必须记录错误状态并停写，防止后续写入落到未擦净的页上
如何在 C++ 中封装成线程安全的轻量类
不依赖 STL 容器（std::vector 会动态分配）、不抛异常、不虚函数。定义 class LogWriter，成员全为 POD：指向 Flash 地址的 const uint8_t*、当前写入页索引 uint16_t m_write_idx、页大小 static constexpr size_t PAGE_SZ = 256。所有函数声明为 noexcept，写操作加临界区（__disable_irq() 或 RTOS 互斥量）。
立即学习“C++免费学习笔记（深入）”；
class LogWriter {
public:
bool write(const void* data, size_t len) noexcept;
size_t read(uint8_t* buf, size_t max_len) noexcept; // 返回实际读出字节数
private:
static constexpr size_t PAGE_SZ = 256;
const uint8_t* const m_flash_base;
uint16_t m_write_idx;
uint16_t m_read_idx;
};
重点：构造函数不执行任何 Flash 操作；首次 write() 前必须由用户调用 init() 扫描日志区并定位 m_read_idx。别忘了在 write() 内部做 len 校验和 CRC 计算 —— 这些都在 RAM 中完成，不碰 Flash。
最易忽略的是地址对齐与编译器优化：确保日志头结构体用 __attribute__((packed))，且所有 Flash 写操作前后加 __DSB(); __ISB(); 防止指令重排。否则 flag 字节可能比 len 先刷到 Flash 控制器队列里。
