66 lines
2.6 KiB
C
66 lines
2.6 KiB
C
/*
|
||
* 模块名称：Volume Lock（卷锁）
|
||
* 模块功能：NAND FatFs 卷的跨任务串行化锁——FatFs 卷状态（FS 窗口缓冲/FAT
|
||
* 缓存）与 FTL 核心状态（单页 RAM 缓存 + dhara journal）均非线程安全；
|
||
* defaultTask（syslog 落盘/配置引擎/存储 bring-up）与 ftpTask（lftpd
|
||
* 文件操作）对卷的访问必须在本锁下串行执行
|
||
* 适用平台：STM32F407ZGTx + FreeRTOS（CMSIS-RTOS V2）
|
||
* 作者：王建锋
|
||
* 创建日期：2026-10-02
|
||
* 修改记录：
|
||
* v1.0 2026-10-02 王建锋 创建（2026-10-02 台架实证：defaultTask 与
|
||
* ftpTask 并发 FTL 写 → dhara journal 竞争 →
|
||
* 长耗时恢复旋转饥饿 defaultTask 主循环（喂狗点）
|
||
* → IWDG 误复位；单写者卷属主假设在多任务 FatFs
|
||
* 调用下不成立，须显式串行化）
|
||
*
|
||
* 使用约定（铁律）：
|
||
* - 锁跨越"一次完整文件操作序列"（open...close / opendir...closedir /
|
||
* 单发 stat/unlink/原子写），不得只锁单个 f_read/f_write；
|
||
* - defaultTask 调用方一律用非阻塞 try（vol_lock_wait(0)）：defaultTask 是
|
||
* 看门狗喂狗点（task_wd_poll），阻塞等锁 = 主循环停摆 = 停喂 → IWDG 误复位；
|
||
* try 失败 = 本轮跳过（syslog 条目滞留队列/配置保存待下轮重试）；
|
||
* - ftpTask 调用方用 100ms 分片阻塞等待 + 每片心跳（lftpd_task_wd_beat），
|
||
* 防长等待导致 FTP 心跳位缺席误复位；
|
||
* - 锁在内核启动后由 defaultTask 存储 bring-up 创建（vol_lock_init 幂等）。
|
||
*/
|
||
|
||
#ifndef VOL_LOCK_H
|
||
#define VOL_LOCK_H
|
||
|
||
#include <stdint.h>
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/*
|
||
* 函数功能：创建卷锁（幂等）
|
||
* 入口参数：无
|
||
* 返回值：0 - 成功/已创建；-1 - 创建失败 int
|
||
* 限定条件：内核启动后调用（defaultTask 存储 bring-up 首行）
|
||
*/
|
||
int vol_lock_init(void);
|
||
|
||
/*
|
||
* 函数功能：获取卷锁
|
||
* 入口参数：timeout_ms - 等待超时（0 = 非阻塞 try） uint32_t
|
||
* 返回值：1 - 已获取；0 - 超时未获取（卷被占用） int
|
||
* 限定条件：见文件头使用约定（defaultTask 必须 timeout_ms=0）
|
||
*/
|
||
int vol_lock_wait(uint32_t timeout_ms);
|
||
|
||
/*
|
||
* 函数功能：释放卷锁（获取方任务释放）
|
||
* 入口参数：无
|
||
* 返回值：无
|
||
* 限定条件：必须与 vol_lock_wait 成对；未获取时调用无害（内部判空）
|
||
*/
|
||
void vol_lock_release(void);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* VOL_LOCK_H */
|