zhou yang和Claude Opus 5.5
b8ad69681f
2026-09-16 完成、当时未提交，这里补提交（原样，不含 09-27 上板的修改）。 - 器件层 / 拓扑层整体从 R1 换到 R2：TCA9548A 分通道、五路同址 INA226 0x40 + 输入侧 0x43、 刀片 PCA9555（VBUS_EN 挪到 P0.4）、CH224A 只读驱动、风扇闭环 t_thermal - 新增 i2cbus（mux 原子事务）、slot（刀片 I/O 门面）、host/qtest.sh - 74HC595 链退役（代码与测试保留） - 判据阈值与时间常量未动；19 个 ctest 全绿，idf.py build 通过 Co-Authored-By: Claude Opus 5.5 <[email protected]>
91 行
4.8 KiB
C
91 行
4.8 KiB
C
/* 互斥锁 —— 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 {
|
||
/* I²C 总线。**R2 之后这是全系统唯一还在用的一把锁**：
|
||
TCA9548A + 输入侧 INA226 + 2×DAC63204（主干）、五片刀片各自的
|
||
INA226 + PCA9555（mux 支路）。按键 / EDL / VBUS 也都在这条线上了。 */
|
||
HAL_LOCK_I2C = 0,
|
||
/* ⛔ **R2 已退役**（2026-09-16，方案 D9：74HC595 链换成刀片上的 PCA9555）。
|
||
枚举留着是因为 `sim_lock_*` 的那套「两把锁不许嵌套」的检查仍要有第二把锁
|
||
才测得动；生产代码里**没有任何一处再拿它**。
|
||
R2 只剩一把锁，于是「嵌套」在物理上不可能 —— 这是 D9 顺手带来的好处，
|
||
代价是执行器与巡检开始争用同一把锁（计划 §5.6）。 */
|
||
HAL_LOCK_SR595,
|
||
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);
|
||
|
||
/* ---- 临界区（A11）——**这不是第三把锁** ----------------------------------
|
||
|
||
事件环形缓冲的入队要在几条指令里改完两个下标，而入队方与出队方是
|
||
优先级两端的两个任务：`t_safety`（最高，而且是在**断电之后**调的）
|
||
与 `t_log`（最低）。这里不能用互斥锁，理由有两条，都不是风格问题：
|
||
|
||
· **不许阻塞。** t_safety.h 写着「接进来的东西不许阻塞」——
|
||
入队要是可能停在一把 t_log 持着的锁上，巡检的节拍就被最低优先级的任务
|
||
决定了。优先级继承能救回来，但那是「让阻塞变短」，不是「不阻塞」。
|
||
· **§10.3 的共享资源只有两个**（I²C 与 595 链），这条架构结论不该被
|
||
一个环形缓冲的下标改写。
|
||
|
||
所以给的是关中断的临界区：不阻塞、没有持有者、不参与「不许嵌套两把锁」
|
||
那条规则，也不出现在 `hal_lock_id_t` 里。
|
||
|
||
⚠️ **里面只许改内存。** 关着中断去等锁、睡、跑 I²C 事务，都是错的
|
||
—— sim 里 `sim_crit_blocking()` 会计数，`test_evlog.c` 拿它当断言。
|
||
可以嵌套（按层数计），但没有理由这么写。 */
|
||
void hal_crit_enter(void);
|
||
void hal_crit_exit(void);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* HAL_LOCK_H */
|