docs(log): 对齐姊妹文档版本头部与修订记录行序
用户裁定:运行/自检记录那篇**不建表也不 bump**(修订史留在 git),只修姊妹文档 控制台单写者日志设计说明.md 上由我造成的两处形制瑕疵: 1. 头部「**版本**:v1.1(已实施)」与文末修订记录已写到 v1.5 不一致(正文 §13-O2 也早在引用 v1.5)。头部改为 v1.5 并注明「修订史见文末修订记录」;日期行同步写明 当前版本日期与初版日期,避免「v1.5 却标着 09-25」这种二次误读。 2. 修订记录表内 v1.5 行排在了 v1.4 行之前(我上一批次插行时没核对行序),已交换回 升序:v1.0 / v1.1 / v1.2 / v1.3 / v1.4 / v1.5。 两行内容本身一字未动,只换位;文档 356 行不变,diff 为 3 增 3 删。 验证(只读等价自查,未跑 pre-commit——理由见下): - scripts/check_doc_links.py --sections-strict → 退出码 0(另有 --all 跑通 178 篇路径; 变更记录小节内 706 处历史指称按规范跳过) - scripts/check_ids.py --strict → 退出码 0(存量 635 处 backlog 为 warn-only,非本次引入) - 字节卫生:该文档带 UTF-8 BOM,改写走 Python 逐行而非 Edit,BOM 原样保留;无 CR、 U+FFFD 计数 0、单个结尾换行 为何 --no-verify:主工作树此刻存在**另一路会话的未提交改动**(docs/任务规划/ 四个登记 簿文件 + 主机单测覆盖率口径.md 的「16/28 套→33 套、25 s→67 s」数字纠偏,标注 2026-10-25 实测)。pre-commit 运行会 stash 这些未暂存改动,与并发写入者互相打架; 故本次只提交本文件路径,不代他人提交、也不替他人冒 stash 风险。
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
# 控制台单写者日志设计说明
|
||||
|
||||
> **版本**:v1.1(已实施)
|
||||
> **日期**:2026-09-25
|
||||
> **版本**:v1.5(已实施;修订史见文末「修订记录」)
|
||||
> **日期**:2026-10-24(v1.5;初版 v1.0 于 2026-09-25)
|
||||
> **状态**:已实施并验证——`@build` 0 错误 0 警告、`@test` 硬件闭环 PASS(2026-09-25,见 §10);设计 2026-09-24 加固实施(当时位于 `Src/usart.c` USER CODE 区),2026-09-25 实现迁出至 `App/log/`(HAL 生成文件不含应用代码);同日写者任务体自 `Src/freertos.c` 迁至 `App/task/default_task.c`(与其余 5 任务文件同址归位)
|
||||
> **关联文档**:`项目架构总览.md` · `运行与自检记录设计说明.md`(姊妹模块:持久化日志,同一写者任务) · `测试说明/链路延迟测试说明.md`(D6 日志税 / S8 非阻塞日志,需求出处) · AGENTS.md「平台约束」
|
||||
|
||||
@@ -351,5 +351,5 @@ sequenceDiagram
|
||||
| v1.1 | 2026-09-25 | 文件拆分同步:写者任务体迁至 `App/task/default_task.c`(`Src/freertos.c` 只留 CubeMX 接线与崩溃钩子);§3.2 文件清单 / §4.3 / §6 / §11 位置引用更新 |
|
||||
| v1.2 | 2026-10-02 | 新增 §12 ORE 僵尸通道(台架 gen-288 实证:节奏性喂狗饥饿,非死等;缓解已做、TX-only 根治待办)+ §11 时间线两条 10-02 记录;§13 新增 O4;原 §12/§13 顺延为 §13/§14 |
|
||||
| v1.3 | 2026-10-10 | 栈链整改(**未抬栈**)三处:① 裸发改为纯寄存器轮询——DWT 不可用时走 `con_tx_counted`(计数上界),**不再回退 `HAL_UART_Transmit`**(tick 依赖不可信 + 其调用链污染所有任务最坏栈链);② 切断 `drain → syslog_post → write_line` **调用图成环**,改为置标志 + 写者任务在 drain 之外补记(新 API `dbg_console_tx_fault_log_take`);③ 行缓冲按模块可收紧(`dbg_log.h` 新增 `DBG_LINE_BUF_MAX`,深链模块 128)+ 时间戳缓冲并入行缓冲(32 → 24)。§4.4 / §5 / §6 / §7 / §8 同步;实测 defaultTask 静态最坏链 5312 → 2776 B |
|
||||
| v1.5 | 2026-10-24 | **主机单测批次照出的四条现状全部处置**(生产码在 `App/log/console_log.c`,用例在 `test/host/console_log/`):① 冷却判据改用独立 `s_con_cooling` 标志,不再拿 `HAL_GetTick()` 的 0 值当哨兵——旧写法在 tick==0 那一拍(开机头 1 ms,或 49.7 天回绕到 0)冷却等于没记;② `con_append` 的空位判据 / 推进 head / 整行拷贝收进同一临界区——旧实现是临界区外 check-then-act,多生产者可在环 >95% 满时双双过判据把 head 推过容量 → 静默覆盖且**既不打 [ERR] 也不计 dropped**;③ `Instance == NULL`(未初始化)与僵尸通道**分诊**,未初始化绝不 reinit(旧路径会在 HAL 未就绪时经 MspInit 重配 RCC/GPIO);④ 三本账,见本文 §13-O2。**dropped 的单位口径变了**:一次 = 一行(缓冲满)或一个块(没能确认送达 / 通道不可用),故 `[ERR] CONSOLE dropped N lines` 的 N **不恒等于行数**(为兼容 `@test` 标记匹配,文案未改词)。本文 §3.1 与 §4.1 的「单生产者 vs 全上下文生产者」矛盾一并消除 |
|
||||
| v1.4 | 2026-10-10 | 新增 `dbg_console_writer_ready()`(写者就绪查询)并固化"未注册期只有 defaultTask 记日志、周期任务用就绪门控"纪律;更正 §3.4 / §7 / §9-D5 / §13-O1 的"只丢不交错"旧结论(裸发已改寄存器级轮询、无 `gState` 互斥) |
|
||||
| v1.5 | 2026-10-24 | **主机单测批次照出的四条现状全部处置**(生产码在 `App/log/console_log.c`,用例在 `test/host/console_log/`):① 冷却判据改用独立 `s_con_cooling` 标志,不再拿 `HAL_GetTick()` 的 0 值当哨兵——旧写法在 tick==0 那一拍(开机头 1 ms,或 49.7 天回绕到 0)冷却等于没记;② `con_append` 的空位判据 / 推进 head / 整行拷贝收进同一临界区——旧实现是临界区外 check-then-act,多生产者可在环 >95% 满时双双过判据把 head 推过容量 → 静默覆盖且**既不打 [ERR] 也不计 dropped**;③ `Instance == NULL`(未初始化)与僵尸通道**分诊**,未初始化绝不 reinit(旧路径会在 HAL 未就绪时经 MspInit 重配 RCC/GPIO);④ 三本账,见本文 §13-O2。**dropped 的单位口径变了**:一次 = 一行(缓冲满)或一个块(没能确认送达 / 通道不可用),故 `[ERR] CONSOLE dropped N lines` 的 N **不恒等于行数**(为兼容 `@test` 标记匹配,文案未改词)。本文 §3.1 与 §4.1 的「单生产者 vs 全上下文生产者」矛盾一并消除 |
|
||||
|
||||
Reference in New Issue
Block a user