/*
 * 模块名称：Volume Lock（卷锁）— FreeRTOS 实现
 * 模块功能：osMutex 串行化 NAND FatFs 卷访问（设计/使用约定见 vol_lock.h）
 * 适用平台：STM32F407ZGTx + FreeRTOS
 * 作者：王建锋
 * 创建日期：2026-10-02
 * 修改记录：
 *     v1.0  2026-10-02  王建锋  创建
 */

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

#include "cmsis_os.h"

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

/* 函数定义区 */

/*
 * 函数功能：创建卷串行化互斥锁（幂等，重复调用安全）
 * 入口参数：无  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 - 已持锁；0 - 超时/未取得，或锁创建失败（fail-open）  int
 * 限定条件：返回 0 时调用方**不得** vol_lock_release；fail-open 是为保证
 *           看门狗喂狗点（defaultTask）绝不能因等锁而阻塞
 */
int vol_lock_wait(uint32_t timeout_ms) {
    if (s_lock == NULL) {
        (void)vol_lock_init();
        if (s_lock == NULL) {
            return 1;   /* 锁创建失败：fail-open（不阻塞，保持启动段可用） */
        }
    }
    return (osMutexWait(s_lock, timeout_ms) == osOK) ? 1 : 0;
}

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