wandering1
04997e48aa
同族第二道：代码注释面。41 个 run_unit_test.py 文件头与引用行、common harness 与两份 README、4 个 *_test.c 文件头、App/** 14 处（含 BOM 文件 App/cfg/cfg_file.c）、 GD5F nand_ftl.c 1 处，共 73 站点 / 64 文件；措辞取「主机侧纯逻辑单元测试运行器 （纯标准库）」避免同行「主机侧」重复。 零行为改动（机器证据，不是口头）： - 17 个 .c/.h 剥掉注释后与 HEAD **逐字节相同**； - 42 个 .py 走 ast.dump 比较、仅归一 docstring（真实字符串字面量参与比较，故旗标或 输出文本被动过必然报红）→ 全部相等；behaviour_changed=0。 - py_compile 42/42；抽跑 watchdog 47/47、freq 46/46（动手前先取基线，改后同数）； CR 字节 0、EF BF BD 0、BOM 与 HEAD 逐一一致、check_bom_drift rc=0。 刻意未动：6 处字符串字面量（FTP 应答 "215 UNIX Type: L8"、lftpd_test.c SYST 断言、 console_log_test.c 的 "L1\r\n"、phasor_test.c 的 "L2-in ring" 文案与 printf 标题）—— 改了就是改测试输出/行为；UI 设计令牌层 L0（ui_tokens.h、ui_content_page.c）与 test/host/README.md 的算法层号是**另外的族**。 两条 SyntaxWarning（ftp_cfg / net_cfg 文件头 \S 转义）**HEAD 同样存在**，已对 HEAD 副本 复现证明非本次引入，未顺手改。
51 lines
2.5 KiB
C
51 lines
2.5 KiB
C
/*
|
||
* 模块名称：Volume Idle Sync（写回缓存空闲 flush）
|
||
* 模块功能：随 defaultTask 主循环周期轮询，在存储**空闲**时对 NAND FatFs 卷
|
||
* 补发一次 CTRL_SYNC（FatFs 幂等落盘语义 = FTL 单页写回缓存脏页刷入
|
||
* + dhara journal 待办收账，见 docs/架构设计/STM32F4-Base存储架构说明.md
|
||
* §5.5），作为写回缓存持久性的兜底网：
|
||
* - 正常写事务语义不变：f_close 内部 sync_fs 已同步，本模块零干预；
|
||
* - 价值在漏网兜底：任何"缓存留脏、之后再无调用触发 sync"的状态
|
||
* （异常路径中途放锁等）其掉电驻留窗从"无限期，直到下一笔写"
|
||
* 收敛为"不超过本模块周期"；
|
||
* - 卷不空闲（卷锁被持有：syslog 落盘 / 配置保存 / lftpd
|
||
* open...close 序列进行中）本轮跳过——不改变文件持有期（如 FTP
|
||
* STOR 进行中）的既有语义。
|
||
* clean 态零 NAND 触点（脏标志与 journal 双短路）；脏态成本与一次
|
||
* f_close 同型。周期 5 s（.c 内 VOL_IDLE_SYNC_PERIOD_MS）。
|
||
* ⚠ 边界（勿当成掉电保护）：本板无掉电检测硬件，"掉电前强制 flush"
|
||
* 不可行；"单次写事务进行中掉电"的丢失边界也不因本模块改变。
|
||
* 适用平台：STM32F407ZGTx + FreeRTOS（CMSIS-RTOS V2）；仅 MCU 端，
|
||
* 主机侧纯逻辑单测 test/host/vol_idle_sync/
|
||
* 作者：DTU 项目组
|
||
* 创建日期：2026-10-25（道F 批 2：写回缓存空闲 flush 收口）
|
||
* 修改记录：
|
||
* v1.0 2026-10-25 DTU 项目组 创建：STORAGE_READY 门控 + 周期节流 +
|
||
* 卷锁 try + disk_ioctl(CTRL_SYNC) + 失败边沿 latch
|
||
*/
|
||
|
||
#ifndef VOL_IDLE_SYNC_H
|
||
#define VOL_IDLE_SYNC_H
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/*
|
||
* 函数功能：存储空闲周期同步的轮询入口（内部自带就绪门控 / 节流 / 非阻塞
|
||
* try 锁 / clean 短路，调用点每轮无条件调用即可）
|
||
* 入口参数：无 void
|
||
* 返回值：无 void
|
||
* 限定条件：仅 defaultTask 主循环调用（存储属主任务；本函数内部绝不阻塞——
|
||
* defaultTask 是看门狗喂狗点，见 vol_lock.h 使用约定）；
|
||
* TEST_SUITE_STORAGE 构建下为空实现（卷由 testTask 独占，后台同步
|
||
* 必须彻底静默）
|
||
*/
|
||
void vol_idle_sync_poll(void);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* VOL_IDLE_SYNC_H */
|