/* 互斥锁 —— HAL 的第五样东西，而且**只有两把**（需求 §10.3）。

   计划 §4.1 写着「HAL 只抽象四样：I²C / GPIO / PWM-定时 / 单调时钟，不要抽象得更多」。
   这里多出来的第五样是有理由的：§10.3 的五个任务共享的资源正好是两个
   —— I²C 总线（10 个器件在同一条上）和 74HC595 的 24 位链 —— 而「谁在用总线」
   这件事没法用前四样表达。

   为了不让它长成一个通用的锁库，这里**没有创建接口**：两把锁是枚举出来的，
   编译期就这么多，也不许再加第三把。要加第三把之前先回头看一眼 §10.3
   ——「共享资源只有两个」是架构结论，不是当时懒得数。

   ⚠️ **两把锁不许嵌套持有。** 595 那条链是纯 GPIO（SER/SRCLK/RCLK），
   和 I²C 没有任何交集，所以「拿着 A 去拿 B」这件事在这块板子上永远是写错了，
   而不是一个需要小心处理的情况。`hal_lock_take()` 直接把它判成 HAL_ERR_STATE
   —— 与其定一套加锁顺序然后指望后面每个人都记得，不如让它根本不可能发生。 */
#ifndef HAL_LOCK_H
#define HAL_LOCK_H

#include <stdbool.h>
#include <stdint.h>

#include "hal_err.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef enum {
    HAL_LOCK_I2C = 0,  /* I²C 总线：6×INA226 + 2×DAC63204 + PCA9555（+ 载板 LM75） */
    HAL_LOCK_SR595,    /* 74HC595 的 24 位链，全板共享（§10.6 的影子寄存器） */
    HAL_LOCK_COUNT,
} hal_lock_id_t;

/* 幂等。任何任务起来之前调一次；没 init 就 take 会返回 HAL_ERR_STATE
   （FreeRTOS 上那是个空句柄，不拦就是随机崩）。 */
hal_err_t hal_lock_init(void);

/* 拿锁。timeout_ms = HAL_LOCK_FOREVER 表示一直等。
     HAL_ERR_TIMEOUT —— 等超时了，**调用方必须自己处理**：巡检任务应当跳过这一周期
                        并计一次数，不要死等（死等的现象是 t_safety 整个停摆）。
     HAL_ERR_STATE   —— 没 init，或者违反了「不许嵌套持有两把锁」。
   同一个任务重复拿同一把锁也是 HAL_ERR_STATE：这两把都不是递归锁。 */
#define HAL_LOCK_FOREVER 0xFFFFFFFFu
hal_err_t hal_lock_take(hal_lock_id_t id, uint32_t timeout_ms);

/* 放锁。不是自己拿的、或者根本没人拿，都会 abort ——
   那是代码写错了，悄悄放掉会让下一个持有者莫名其妙地丢掉互斥。 */
void hal_lock_give(hal_lock_id_t id);

/* **当前任务**是不是正持着这把锁。给断言和 sim 的强制检查用，
   不要拿它做流程控制（「没拿就拿一下」正是双重加锁的写法）。 */
bool hal_lock_held(hal_lock_id_t id);

/* 累计等锁失败次数（超时）。遥测里报出去，用来看总线是不是排队了。 */
uint32_t hal_lock_timeouts(hal_lock_id_t id);

#ifdef __cplusplus
}
#endif

#endif /* HAL_LOCK_H */