/*
 * 模块名称：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 */