diff --git a/App/fs/vol_lock.c b/App/fs/vol_lock.c index 712eaa68..5a6b2701 100644 --- a/App/fs/vol_lock.c +++ b/App/fs/vol_lock.c @@ -6,7 +6,8 @@ * 创建日期：2026-10-02 * 修改记录： * v1.0 2026-10-02 王建锋 创建 - * v1.1 2026-10-26 DTU 项目组 道G task-17：① 新增 4 个观测计数（T-a/T2/T3/T4， + * v1.1 2026-10-26 DTU 项目组 道G task-17：① 新增 4 个观测计数（持锁 / try 超时 / + * 分片退让 / 零互斥 四态， * 共 16 B 静态）与 vol_lock_get_stats() 只读口 —— 不取锁、 * 零外部调用、零局部变量，13 处调用点一字未动； * ② 修 :38「返回值」注释与代码相反的错（fail-open 原被 @@ -34,10 +35,10 @@ static osMutexId_t s_lock; /* 卷串行化互斥锁（vol_lock_init 创建） * 并发：多个任务可同时自增同一个计数，竞态下少计不会多计（判据是"是否 > 0 / 是否还 * 在增长"，不是精确值），所以不为此上临界区 —— 上临界区反倒把观测做成了故障本身。 * volatile：跨任务读写且无锁保护，禁止把读侧重复读优化掉。 */ -static volatile uint32_t s_st_acquired; /* T-a 真取到互斥 */ -static volatile uint32_t s_st_try_timeout; /* T2 try（timeout=0）失败：卷被别人占住 */ -static volatile uint32_t s_st_blk_timeout; /* T3 分片等待超时：ftpTask 正常退让 */ -static volatile uint32_t s_st_failopen; /* T4 锁不存在却返 1：谎报成功那一态 */ +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，谎报成功那一态 */ /* 函数定义区 */ @@ -73,18 +74,18 @@ int vol_lock_wait(uint32_t timeout_ms) { if (s_lock == NULL) { (void)vol_lock_init(); if (s_lock == NULL) { - s_st_failopen++; /* T4：返 1 但零互斥 —— 谎报成功那一态 */ + s_st_failopen++; /* 零互斥态：返 1 但零互斥 —— 谎报成功那一态 */ return 1; /* 锁创建失败：fail-open（不阻塞，保持启动段可用） */ } } if (osMutexWait(s_lock, timeout_ms) == osOK) { - s_st_acquired++; /* T-a：真持锁 */ + s_st_acquired++; /* 持锁态：真持锁 */ return 1; } if (timeout_ms == 0u) { - s_st_try_timeout++; /* T2：压根没等（喂狗点/绘制路径只有这一态会发生） */ + s_st_try_timeout++; /* try 超时态：压根没等（喂狗点/绘制路径只有这一态会发生） */ } else { - s_st_blk_timeout++; /* T3：等了一会儿没等到（分片退让），语义与 T2 不同 */ + s_st_blk_timeout++; /* 分片退让态：等了一会儿没等到，与 try 超时态语义不同 */ } return 0; } diff --git a/App/fs/vol_lock.h b/App/fs/vol_lock.h index 47b3971b..8670d6fd 100644 --- a/App/fs/vol_lock.h +++ b/App/fs/vol_lock.h @@ -72,13 +72,14 @@ int vol_lock_wait(uint32_t timeout_ms); /* * 卷锁观测计数（道G task-17「卷锁 5 态可观测性」）。四个字段就是四态，语义**不得**合并： - * T-a `acquired` = 真取到互斥的次数 - * T2 `try_timeout` = timeout=0 的 try 失败次数（卷被别的任务占住；defaultTask/uiTask - * 的喂狗与绘制路径只有这一态会发生） - * T3 `blk_timeout` = timeout>0 的分片等待超时次数（ftpTask 100 ms 分片正常退让， - * 语义与 T2 不同：那是"等了一会儿没等到"，这是"压根没等"） - * T4 `failopen` = 锁不存在却返 1 的次数（**谎报成功**那一态，见 wait 的函数头） - * T1「从未调用过」不占计数：三个计数全 0 就说明这条路径没跑过——区分"没跑过"与 + * `acquired` 持锁态 = 真取到互斥的次数 + * `try_timeout` try 超时态 = timeout=0 的 try 失败次数（卷被别的任务占住； + * defaultTask/uiTask 的喂狗与绘制路径只有这一态会发生） + * `blk_timeout` 分片退让态 = timeout>0 的分片等待超时次数（ftpTask 100 ms 分片正常 + * 退让；与 try 超时态语义不同：那是"等了一会儿没等到"， + * 这是"压根没等"） + * `failopen` 零互斥态 = 锁不存在却返 1 的次数（**谎报成功**那一态，见 wait 函数头） + * 「未调用」这一态不占计数：三个计数全 0 就说明这条路径没跑过——区分"没跑过"与 * "跑了但一直忙"正是本卡的目的（此前两者在日志上完全一样）。 * ⚠ 本层**刻意不记时刻**：记时刻就得读 tick，等于给 defaultTask 的取锁链添一个 * callee 与几字节帧，而这条链的余量我们整天都在省着花（诊断不值那几个字节）。 diff --git a/docs/测试说明/卷锁单元测试说明.md b/docs/测试说明/卷锁单元测试说明.md index 2eeb8cce..3bb7048e 100644 --- a/docs/测试说明/卷锁单元测试说明.md +++ b/docs/测试说明/卷锁单元测试说明.md @@ -141,8 +141,8 @@ test/host/vol_lock/vol_lock_test.c | **TC-VOLLOCK-009** | fail-open 之后 `release` 无害：`osMutexRelease` **未被调用**（判空静默返回） | | **TC-VOLLOCK-010** | 已创建时多次 `wait` **不重复创建**（`osMutexNew` 恒 1 次）；每次 `wait` 各等待一次 | | **TC-VOLLOCK-015** | 成功路径只涨 `acquired`：`try_timeout` / `blk_timeout` / `failopen` 必须仍为 `0`（异常计数不得被正常路径污染） | -| **TC-VOLLOCK-016** | `timeout=0` 未取到 → 只进 `try_timeout`，且 `blk_timeout` 与 `acquired` 保持 `0`（T2：压根没等，卷被别人占住） | -| **TC-VOLLOCK-017** | `timeout=100` 未取到 → 只进 `blk_timeout`，且 `try_timeout` 保持 `0`（T3：等了没等到；**与 T2 互不冒领**是本卡唯一"语义合并"风险） | +| **TC-VOLLOCK-016** | `timeout=0` 未取到 → 只进 `try_timeout`，且 `blk_timeout` 与 `acquired` 保持 `0`（try 超时态：压根没等，卷被别人占住） | +| **TC-VOLLOCK-017** | `timeout=100` 未取到 → 只进 `blk_timeout`，且 `try_timeout` 保持 `0`（分片退让态：等了没等到；**与 try 超时态互不冒领**是本卡唯一"语义合并"风险）。四态定义只在 `App/fs/vol_lock.h` 一处，本表只描述断言不重定义 | | **TC-VOLLOCK-018** ⭐ | fail-open 仍返回 `1`（口径不变，同 TC-VOLLOCK-008），但 `failopen` 计数自增而 `acquired` 保持 `0`；连续两次 → `failopen == 2`（消费方按差值 latch，一个 episode 一条） | | **TC-VOLLOCK-019** | `vol_lock_get_stats(NULL)` 无害；重复读取**不消耗证据**（计数不因读而归零） | diff --git a/docs/门禁说明/id-check.md b/docs/门禁说明/id-check.md index 27866360..b69a873e 100644 --- a/docs/门禁说明/id-check.md +++ b/docs/门禁说明/id-check.md @@ -204,10 +204,23 @@ - 不要为了绿而往台账加 reason；确实该欠的债要写清楚原因（默认禁止顺手加）。 - 台账文件自身不是语料（见 §6 第 6 条），改动它之后要单跑一次确认没有自循环新账。 +### 6.10 「删裸形」不等于按出现次数还债（道G task-45 实测，2026-10-27） + +本仓第一次真正还第二根护栏的债（绝对数 1,162 → 1,156），**还掉的格数远少于删掉的裸形数**，机制值得写死： + +1. **只有落不进任何已登记族的裸形才计不可判定**。撞进已登记族的那些本来就记在**可判定**一侧，删它们分子 + 分母同缩、**可判定比例反而会上升**（实测 86.74% → 86.77%）。「清了一大片、绝对数只降几格」不是算错。 +2. 要真腾余量得挑**无族可归**的裸形态下手；撞族的删了只是稀释分母——与 §7.6 那根护栏防的稀释同源、方向相反。 +3. 更省事的正解是**写注释与文档时一开始就别用裸形**：改用语义短语，或写全号 + 紧邻属主文档名。同日还有一 + 次反向教训：为「省余量」把在册族的号改成散文，那才是真把护栏当敌人（见 §7.7）。 +4. 附带收益常比余量值钱：这次顺带消掉一个**同形两义**的撞号源（同一裸形既像自造状态号又撞已登记族）。 + + ## 9. 变更记录 | 日期 | 变更 | |---|---| +| 2026-10-27 | **本仓第一次真正「还」第二根护栏的债**（道G task-45）：卷锁观测计数旁自造的四位状态号（一字母+一数字的裸形写法）全量换成语义短语——`App/fs/vol_lock.c`、`App/fs/vol_lock.h`、`test/host/vol_lock/vol_lock_test.c`、`docs/测试说明/卷锁单元测试说明.md` 四处共 36 处出现清零，四态语义只留 `App/fs/vol_lock.h` 一处。改前实测不可判定绝对数 1,162（03:15），改后 1,156（03:22），余量从 4 格变 10 格；`--strict` exit 0、卷锁套件 45/45 未掉、未动 `undecidable_total_ceiling`。**顺带查清一件口径事，比这次还债本身更值得记**：绝对数只统计**落不进任何已登记族**的裸形；撞进已登记族的写法（台架/测试那一族的族模式只覆盖到该字母加一位数字的 0~3）本来就记在**可判定**一侧——于是这次 36 处里只有 6 处真正减了绝对数，另 23 处删掉是同时缩分子与分母（比值几乎不动：86.74% → 86.77%）。⇒ 「删裸形」不等于「按出现次数还债」；要腾余量得优先清**无族可归**的裸形态，而写文档时一开始就别用裸形才是正解。另注：写在模块头修改记录行里的第 7 处本来就被「变更记录行豁免」挡住不计数，所以账面是 6 不是 7。 | | 2026-10-27 | 新增 §7.7：实测拆解「不可判定绝对数」的构成（裸形盲区 834 + 噪声白名单 326 + 真·硬不可判定 2 = 1,162，精确闭合），并写入每批自证没吃余量的五项式做法（含「不得用 stash/checkout 回退别人在飞改动」与 --update-baseline 只下调）；同批撤回一条 Lead 错指令——「怕吃余量而把编号写成散文」恰好是 §7.6 这根护栏要防的稀释行为 | | 2026-10-26 | **方案 B（同日续批）**：登记簿系 `N-x`/`S-x`/`T-x`/`A-x` 与 UI 簇 `U1~U5` 共 20 个号停发、约 418 处引用转语义短语（字面量净减 443：8,946 → 8,503）；新增第二根护栏「不可判定引用绝对数上限」（`undecidable_total_ceiling`，只减不增），并把比例基线下调——理由与实测（比例跌、绝对数不涨）见 §7.6；`CHANGELOG_ROW` 补「版本号 + 日期」表头的变更记录行 | | 2026-10-26 | **清号批次**（用户裁定：字母+数字编号太多、没人认得）：全仓删除「属主已死 / 从未启用」的编号约 1,100 处，规范 §4.1 收成全活族 + §4.1.1 列已清除族，§4.2/§4.5/§7.1/§9 作废压缩。门禁口径不变（族仍登记，只拦新增引用）；扫描面 / 字面量总数 / 台账 / 比例基线按本批实跑重打（见 §3、§7）。新增 §7.5 讲清"比例上升 ≠ 卫生变好"的读法 | diff --git a/test/host/vol_lock/vol_lock_test.c b/test/host/vol_lock/vol_lock_test.c index 215f8af4..2e96b5b8 100644 --- a/test/host/vol_lock/vol_lock_test.c +++ b/test/host/vol_lock/vol_lock_test.c @@ -32,9 +32,9 @@ * TC-VOLLOCK-014 wait(0) 的 timeout 透传为 0（defaultTask 的 try 语义） * —— 观测计数（道G task-17「卷锁 5 态可观测性」）—— * TC-VOLLOCK-015 成功路径只涨 acquired，三个异常计数必须为 0 - * TC-VOLLOCK-016 timeout=0 未取到 -> 只进 try_timeout（T2，没等） - * TC-VOLLOCK-017 timeout=100 未取到 -> 只进 blk_timeout（T3，等了没等到）， - * 与 T2 互不冒领 + * TC-VOLLOCK-016 timeout=0 未取到 -> 只进 try_timeout（try 超时态，压根没等） + * TC-VOLLOCK-017 timeout=100 未取到 -> 只进 blk_timeout（分片退让态，等了没等到）， + * 与 try 超时态互不冒领 * TC-VOLLOCK-018 ⭐ fail-open 仍返 1（口径不变）但 failopen 计数自增并可累加 * —— 把"谎报成功"那一态变成事后可查的证据 * TC-VOLLOCK-019 观测口：NULL 无害、重复读取不消耗证据 @@ -222,8 +222,8 @@ static void tc_release(void) { /* ===================== TC-VOLLOCK-015..019：观测计数（道G task-17） ===================== * 这一组是"5 态可观测性"的机器证据： - * T-a acquired / T2 try_timeout / T3 blk_timeout / T4 failopen 各自独立自增， - * T2 与 T3 不许互相冒领（那是本卡唯一"语义合并"风险），T4 从"谎报成功"变成可查。 + * 四态 acquired / try_timeout / blk_timeout / failopen 各自独立自增（定义只在 vol_lock.h）， + * try 超时态与分片退让态不许互相冒领（本卡唯一"语义合并"风险）；零互斥态从"谎报成功"变成可查。 */ static void tc_stats(void) { vol_lock_stats_t st; @@ -237,7 +237,7 @@ static void tc_stats(void) { && (st.failopen == 0u), "TC-VOLLOCK-015b acquired only: a successful lock never inflates any anomaly counter"); - /* 016 T2：timeout=0 的 try 失败 -> 只进 try_timeout */ + /* 016 try 超时态：timeout=0 的 try 失败 -> 只进 try_timeout */ fakes_reset(); (void)vol_lock_init(); s_wait_ok = 0; @@ -246,7 +246,7 @@ static void tc_stats(void) { CHECK((st.try_timeout == 1u) && (st.blk_timeout == 0u) && (st.acquired == 0u), "TC-VOLLOCK-016b timeout=0 miss counts as try_timeout and NOT as blk_timeout (feed point never waited)"); - /* 017 T3：timeout>0 的分片等待超时 -> 只进 blk_timeout（与 T2 分道） */ + /* 017 分片退让态：timeout>0 的分片等待超时 -> 只进 blk_timeout（与 try 超时态分道） */ fakes_reset(); (void)vol_lock_init(); s_wait_ok = 0; @@ -255,7 +255,7 @@ static void tc_stats(void) { CHECK((st.blk_timeout == 1u) && (st.try_timeout == 0u), "TC-VOLLOCK-017b slice timeout counts as blk_timeout and NOT as try_timeout (waited-but-missed is a different fact)"); - /* 018 T4 核心：锁不存在时 wait 仍返 1（TC-VOLLOCK-008 的口径），但现在必须留下 + /* 018 零互斥态（本组核心）：锁不存在时 wait 仍返 1（TC-VOLLOCK-008 的口径），但现在必须留下 * 可查证据 —— 这一态此前被谎报成"取到锁"，整机没有任何地方能发现它 */ fakes_reset(); s_new_fail = 1;