/*
 * 模块名称：Volume Lock（卷锁）— FreeRTOS 实现
 * 模块功能：osMutex 串行化 NAND FatFs 卷访问（设计/使用约定见 vol_lock.h）
 * 适用平台：STM32F407ZGTx + FreeRTOS
 * 作者：王建锋
 * 创建日期：2026-10-02
 * 修改记录：
 *     v1.0  2026-10-02  王建锋  创建
 *     v1.1  2026-10-26  DTU 项目组  道G task-17：① 新增 4 个观测计数（持锁 / try 超时 /
 *                              分片退让 / 零互斥 四态，
 *                              共 16 B 静态）与 vol_lock_get_stats() 只读口 —— 不取锁、
 *                              零外部调用、零局部变量，13 处调用点一字未动；
 *                              ② 修 :38「返回值」注释与代码相反的错（fail-open 原被
 *                              归给 0，实际返 1）；③ 刻意不记时刻：时刻要读 tick，
 *                              等于给 defaultTask 取锁链添帧，改由消费方观测并自盖
 *                              （命名 obs_first_ms/obs_last_ms，见 vol_lock.h 告诫 ②）
 */

/* 头文件包含区 */
#include "vol_lock.h"

#include "cmsis_os.h"

/* 静态变量定义区 */
static osMutexId_t s_lock;   /* 卷串行化互斥锁（vol_lock_init 创建） */

/* 观测计数（道G task-17「卷锁 5 态可观测性」）—— 本模块唯一的新增状态，共 16 B。
 * 为什么计数必须在锁层、而且只有计数没有别的：
 *   ① 13 处调用点各自 return、历史上零痕；在每个调用点各写一份 = 13 份真源。
 *   ② 不能在这里打日志或投记录：唯一能落盘的通道（/log/wdev.log、run.log）自己也要
 *      取这把卷锁，而卷锁**非递归** —— 被卷忙挡住时既写不出东西，还会自取死锁。
 *   ③ 也不读 tick 记时刻：那会给 defaultTask 的取锁链添一个 callee 与几字节帧，而
 *      这条链的栈余量正是要省着花的；"什么时候开始忙"交给消费方观测（口径见 vol_lock.h
 *      的告诫 ②：观测时刻不等于发生时刻，别写成首次发生）。
 * 并发：多个任务可同时自增同一个计数，竞态下少计不会多计（判据是"是否 > 0 / 是否还
 * 在增长"，不是精确值），所以不为此上临界区 —— 上临界区反倒把观测做成了故障本身。
 * volatile：跨任务读写且无锁保护，禁止把读侧重复读优化掉。 */
static volatile uint32_t s_st_acquired;     /* 持锁态：真取到互斥（四态定义见 vol_lock.h） */
static volatile uint32_t s_st_try_timeout;  /* try 超时态：timeout=0 没取到，卷被别人占住 */
static volatile uint32_t s_st_blk_timeout;  /* 分片退让态：分片等待超时，ftpTask 正常退让 */
static volatile uint32_t s_st_failopen;     /* 零互斥态：锁不存在却返 1，谎报成功那一态 */

/* 函数定义区 */

/*
 * 函数功能：创建卷串行化互斥锁（幂等，重复调用安全）
 * 入口参数：无  void
 * 返回值：0 - 成功（已创建或已存在）；-1 - osMutexNew 失败  int
 * 限定条件：可在内核启动后任意时刻调用；本实现不检查是否已启动调度器
 */
int vol_lock_init(void) {
    if (s_lock != NULL) {
        return 0;   /* 幂等 */
    }
    s_lock = osMutexNew(NULL);
    return (s_lock != NULL) ? 0 : -1;
}

/*
 * 函数功能：获取卷锁（首次调用自动 vol_lock_init）
 * 入口参数：timeout_ms - 等待上限（毫秒）；0 = try 语义（不阻塞）  uint32_t
 * 返回值：1 - 已取得互斥，**或锁不存在的 fail-open（返 1 但此刻并未串行化）**；
 *         0 - 未取得（timeout=0 的 try 失败，或 timeout>0 的分片等待超时）  int
 * 限定条件：返回 0 时调用方**不得** vol_lock_release；fail-open 是为保证
 *           看门狗喂狗点（defaultTask）绝不能因等锁而阻塞
 * 函数说明：⚠ 原 v1.0 这行「返回值」把 fail-open 归给 0，与本函数 :46 的代码和
 *          TC-VOLLOCK-008 都相反（道G task-17 修正）。"返 1"有两种成因，调用方
 *          无需各自分辨（它们只关心能不能干活），但整机的判据必须看
 *          vol_lock_get_stats().failopen —— 累计 > 0 = 本 boot 至少发生过一次
 *          "无互斥读写卷"。本函数只自增计数：不打日志、不投记录、不读 tick、
 *          不新增局部变量（理由见上面计数块）。
 */
int vol_lock_wait(uint32_t timeout_ms) {
    if (s_lock == NULL) {
        (void)vol_lock_init();
        if (s_lock == NULL) {
            s_st_failopen++;   /* 零互斥态：返 1 但零互斥 —— 谎报成功那一态 */
            return 1;   /* 锁创建失败：fail-open（不阻塞，保持启动段可用） */
        }
    }
    if (osMutexWait(s_lock, timeout_ms) == osOK) {
        s_st_acquired++;       /* 持锁态：真持锁 */
        return 1;
    }
    if (timeout_ms == 0u) {
        s_st_try_timeout++;    /* try 超时态：压根没等（喂狗点/绘制路径只有这一态会发生） */
    } else {
        s_st_blk_timeout++;    /* 分片退让态：等了一会儿没等到，与 try 超时态语义不同 */
    }
    return 0;
}

/*
 * 函数功能：释放卷锁
 * 入口参数：无  void
 * 返回值：无  void
 * 限定条件：仅在 vol_lock_wait() 返回 1 后调用；锁未创建时静默返回
 */
void vol_lock_release(void) {
    if (s_lock != NULL) {
        (void)osMutexRelease(s_lock);
    }
}

/*
 * 函数功能：读卷锁观测计数（契约与消费方告诫见 vol_lock.h 的函数头）
 * 入口参数：p_out - 输出缓冲；NULL 时无害返回  vol_lock_stats_t *
 * 返 回 值：无  void
 * 限定条件：不取卷锁、不关中断、不阻塞；**零外部调用、零局部变量**，因此不改变
 *          任何调用方的栈最坏链（这条是本卡选型的结论，不要"顺手优化"掉）
 * 函数说明：逐字段拷而非整体赋值 —— 每个字段都是某个真实值，不会读到半更新的字；
 *          四元组之间不保证同一瞬间（诊断够用，理由见 .h 的告诫 ①）
 */
void vol_lock_get_stats(vol_lock_stats_t *p_out) {
    if (p_out == NULL) {
        return;
    }
    p_out->acquired    = s_st_acquired;
    p_out->try_timeout = s_st_try_timeout;
    p_out->blk_timeout = s_st_blk_timeout;
    p_out->failopen    = s_st_failopen;
}