wandering1
dafcf8098b
B6 台架 @test 闭环复测（B4/B5 验收窗口）完成，DoD 全判据过。
门控修复（首跑 FAIL 实锤的 B5 遗留竞态）：
- 现象：protect task start 锚点行字节级交错损坏
（st[art: cycle=220ms elm=70，两次开机同形复现）
- 根因：启动行在控制台写者注册前打印走无锁裸发，与
defaultTask 启动日志交错——违反 2026-10-10 门控纪律
（控制台单写者日志设计说明.md §3.4，adcTask 同款先例）
- 修复：启动锚点行改 dbg_console_writer_ready() 首拍补打
台架与工具：
- .serialtest/config.json：Required 增 protect task start /
i104 listening on 2404 / [STACK] protect|iec104|heap
- test/host/iec104_master.py：纯标准库 104 主站客户端
（STARTDT→总召四组+actterm→C_SE 两段写触发 YX15/16 变位
COT=3→恢复复归→YK11 两段正答→C_RD 读回），往返 18/18
PASS（d3107f3 与 B7+fix 两版固件）
- 复测 @test PASS：锚点完好 +577ms、9/9 Required、零 [ERR]、
回读一致；protect free_min 1220（59%）、iec104 2136（83%）、
新 56KB 堆 min_ever=10000（N-33 抬栈背书就绪）
证据与文档回填：
- boot_log_data 四份快照（含缺陷复现 MISS 件）+ README 登记
- 保护规划 §7 B6 行（B5 台架遗留闭环）；控制台单写者 §3.4
纪律示例 + §11 变更记录；IEC104 §7/§8 主站工具就绪；
W1 卡 B6 ✅ + N-33 背书 + B7 台架腿注；登记簿 N-33
- 内存台账：+16 B 构建后 ram_baseline/check_mem_numbers 回填
验证：@build 0 错 0 警（Code=205516）；ci_local 全绿
（L0 30 钩子 + L0.5 13 套件 826 断言）。
355 lines
32 KiB
Markdown
355 lines
32 KiB
Markdown
# 控制台单写者日志设计说明
|
||
|
||
> **版本**：v1.1（已实施）
|
||
> **日期**：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「平台约束」
|
||
|
||
## 1. 背景：实测故障与根因
|
||
|
||
### 1.1 实测故障（2026-09-24，双证据）
|
||
|
||
| # | 症状 | 实测证据 | 后果 |
|
||
|---|------|---------|------|
|
||
| F1 | 日志行字符级交错 | 崩溃前两行日志逐字符交错：`"[2026-[2026-0909-24 15:2-24 15:27:37:39]…"` | @test 必检标记可能假性丢失、日志不可读 |
|
||
| F2 | HardFault（脏指针直接进入 UART） | BFAR=0x10010000（恰为 CCM 末尾+1），PC 落在 `HAL_UART_Transmit` 的缓冲读取处 | 崩溃上报路径自身再崩；被破坏的字符串指针被 UART 逐字节读取 |
|
||
|
||
前兆：2026-09-22 链路延迟测试实测**开机连续丢行**（多任务并发 `printf` → 非重入 `fputc`/`HAL_UART_Transmit` 丢整行，~2s 自恢复；`链路延迟测试说明.md` §9.2）——同类竞态的温和形态，当时列为 S8 待办（日志非阻塞化）。
|
||
|
||
### 1.2 根因分析（旧路径：`DBG_*` → `printf` → `fputc`）
|
||
|
||
| # | 根因 | 机理 | 对应故障 |
|
||
|---|------|------|---------|
|
||
| C1 | 逐字符发送 | `fputc` 每字符一次 `HAL_UART_Transmit(1 字节)`；两次调用之间可发生任务切换 | F1 交错 |
|
||
| C2 | 调用方缓冲直达 UART | `HAL_UART_Transmit` 的缓冲指针是调用方（可能已被破坏）的指针 | F2 HardFault |
|
||
| C3 | 多任务并发直触 UART | 轮询 Transmit 的并发保护是 `gState` 状态标志（§3.4）：竞争失败方**立即**返回 `HAL_BUSY`（不等待、不重试），返回值被忽略 → 静默丢数据 | 09-22 丢行 |
|
||
|
||
HAL 并发语义（本仓库实现实测，`stm32f4xx_hal_uart.c:1135`）：轮询版 `HAL_UART_Transmit` **不加** `__HAL_LOCK`（`huart->Lock` 标志仅 IT/DMA 路径使用，`stm32f4xx_hal_def.h:93`）；入函数检查 `gState==READY`，全程保持 `BUSY_TX` 直到发完 —— **单次调用是原子的，但调用之间没有排队机制**：并发调用方立即拿到 `HAL_BUSY`。逐字符路径下（C1）"单次调用 = 单字节"，原子性退化为字节级（→ F1）；整行路径下竞争失败方整行丢失（→ C3）。
|
||
|
||
## 2. 设计目标与约束
|
||
|
||
### 2.1 目标
|
||
|
||
| # | 目标 | 达成方式 |
|
||
|---|------|---------|
|
||
| G1 | 行级原子：不同行不再逐字符交错 | 整行一次性入环形缓冲；唯一写者发出（UART 全局只有一个发送调用点） |
|
||
| G2 | 指针可控：进入 `HAL_UART_Transmit` 的缓冲恒受本模块控制 | 调用方指针只经拷贝入环、到不了 UART；写者发出的缓冲恒为环形缓冲或模块本地静态缓冲 |
|
||
| G3 | 不新增任务、不用 C 库堆、不新增内核对象 | 复用既有 defaultTask 作写者；环形缓冲 = 4KB 静态 BSS；复用 `sys_evt` 事件标志位 |
|
||
| G4 | 内核启动前 / 写者未注册 / ISR / 异常钩子路径不降级 | 回退：有界直发（`dbg_console_write_raw`，≤256B 截断、不等待、不死锁、零内核对象） |
|
||
| G5 | 缓冲满丢行必须可观测 | 丢弃计数 + 写者刷出 `[ERR] CONSOLE dropped N lines` —— 含 `[ERR]` 模式，`@test` Forbidden 判 FAIL，丢失永不静默 |
|
||
|
||
### 2.2 约束
|
||
|
||
| # | 约束 | 出处 |
|
||
|---|------|------|
|
||
| K1 | 内核启动前禁止创建/使用任何 FreeRTOS/CMSIS-RTOS 对象 | AGENTS.md 平台约束（2026-09-20 启动失败实证根因）→ 本模块内核前纯 BSS/寄存器机制 |
|
||
| K2 | 禁止 `malloc/calloc/realloc`（C 堆仅 512B） | AGENTS.md 平台约束（禁 C 库堆分配条）→ 全部状态静态 BSS |
|
||
| K3 | HAL 生成文件（`Src/`、`Inc/`）不含应用代码 | 2026-09-25 迁移动机 → 实现位于 `App/log/` |
|
||
| K4 | 生产者阻塞时间有界 | 最多 `DBG_CON_WAIT_MS`(200ms)，日志不得阻塞业务 |
|
||
| K5 | RAM 预算紧张，新增静态内存必须核算 | §8 |
|
||
|
||
## 3. 总体架构
|
||
|
||
### 3.1 单写者模型
|
||
|
||
| 角色 | 实体 | 职责 |
|
||
|------|------|------|
|
||
| 生产者 | 全部任务 + 内核前主线程 + ISR | 调用点格式化整行（库 `snprintf`）→ `dbg_console_write_line()` |
|
||
| 写者 | **defaultTask（唯一）** | 进主循环前 `dbg_console_writer_attach()` 注册为唯一发送者；循环内周期 `dbg_console_drain()` |
|
||
| 物理通道 | USART1（PA9 TX / PA10 RX，115200，8N1） | 轮询发送（`HAL_UART_Transmit`）；CubeMX 配置的 DMA TX（DMA2_Stream7）未使用 |
|
||
| 唤醒 | `SYS_EVT_CONSOLE_TX`（`sys_evt` bit 6） | **消费型命令位**（`osFlagsWaitAny` 默认消费，与 AGENTS.md 事件位语义一致；区别于就绪位必须 `osFlagsNoClear`） |
|
||
|
||
**与其他日志子系统的关系**（同一"单写者纪律"，同一属主任务）：
|
||
|
||
| 子系统 | 通道 | 写者 | 持久化 |
|
||
|--------|------|------|--------|
|
||
| 控制台单写者（本文档） | USART1 串口 | defaultTask | 无（易失，复位丢失）——实时调试流 |
|
||
| sys_log 运行/自检记录 | FatFS `/log/*.log` | defaultTask（同一任务） | 是（定长 64B 记录，`运行与自检记录设计说明.md`） |
|
||
| 配置引擎 | FatFS `/config.ini` | defaultTask（同一任务） | 是 |
|
||
|
||
defaultTask 主循环按序处理：控制台排空 → 配置保存执行 → 2s 配置轮询 → LED 心跳 → syslog 落盘 → 栈水位观测——同一任务串行化三类 I/O，任务间零竞争。
|
||
|
||
### 3.2 文件清单
|
||
|
||
| 文件 | 端 | 角色 |
|
||
|------|-----|------|
|
||
| `App/log/console_log.h` | MCU | API 声明：5 个控制台函数 + `fputc` retarget + `DBG_CON_LINE_MAX` |
|
||
| `App/log/console_log.c` | MCU | 实现：环形缓冲 / 生产者 / 写者 / 裸发 / `fputc` |
|
||
| `Drivers/BSP/dbg_log.h` | 共享 | `#include "console_log.h"`；`DBG_PRINT` 宏绑定 `dbg_console_write_line`（整行一次入环） |
|
||
| `simulator/dbg_log.h` | 模拟器 | `printf` stub——模拟器不编译本模块（宿主 `printf` 天然串行，无需单写者） |
|
||
| `App/task/default_task.c` | MCU | 写者任务体：`dbg_console_writer_attach()` 注册 + 主循环 `dbg_console_drain()`；含存储 bring-up / 配置引擎 / syslog 落盘 / LED / 栈水位（2026-09-25 自 `Src/freertos.c` 迁出） |
|
||
| `Src/freertos.c` | MCU | CubeMX 接线：6 任务创建 + netMsgQueue + sys_evt；栈溢出/堆失败钩子裸发（任务名先范围校验再拷入本地缓冲） |
|
||
| `Src/usart.c` | MCU | 纯 CubeMX 生成（UART 初始化 / MspInit / 句柄声明）——零应用代码 |
|
||
|
||
### 3.3 拓扑
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph P["生产者（任意上下文）"]
|
||
P1["netTask / ftpTask / uiTask / timeSync / testTask"]
|
||
P2["内核前主线程<br/>(MX init / app_main_init)"]
|
||
P3["ISR / 异常钩子"]
|
||
end
|
||
R["环形缓冲 4KB<br/>BSS（SRAM1）<br/>head/tail 16 位回绕"]
|
||
E["sys_evt bit6<br/>SYS_EVT_CONSOLE_TX"]
|
||
W["写者 = defaultTask<br/>dbg_console_drain()"]
|
||
U["USART1 115200<br/>(PA9/PA10, 轮询)"]
|
||
|
||
P1 -- "dbg_console_write_line(整行 ≤192B)" --> R
|
||
R --> E --> W
|
||
W -- "HAL_UART_Transmit(块 ≤256B)" --> U
|
||
P2 -- "写者未注册：整行直发" --> U
|
||
P3 -- "有界直发 ≤256B" --> U
|
||
```
|
||
|
||
### 3.4 并发语义与本设计的配合（实现实测）
|
||
|
||
写者**已注册**后（稳态）：任务上下文唯一调用者 = 写者（`defaultTask`），零竞争；残余窗口 = ISR 直发撞写者发送中（丢失、不挂死，§7）。
|
||
|
||
写者**未注册**期（内核启动 → `defaultTask` `attach`，时长取决于存储 bring-up，通常秒级）：`con_append` 走 `dbg_console_write_raw` → `con_tx_bounded`（**寄存器级轮询 TXE/TC，无 `gState` 锁**，见 §4.4）。⚠ **2026-10-10 起此路径无互斥**——旧实现走 `HAL_UART_Transmit`，其 `gState` 检查跨整行保持、竞争失败方立即 `HAL_BUSY`，故当时"只丢不交错"；改为寄存器级轮询后该保证**不再成立**：两个任务同时裸发会**逐字节交错**（2026-10-10 台架实测：`adcTask` 首帧日志与 `defaultTask` 的 `[NAND_FTL]` 初始化行交错）。
|
||
|
||
| 区间 | 发送者构成 | 并发行为 |
|
||
|------|-----------|---------|
|
||
| 内核启动前 | 仅主线程（单线程） | 无并发，直发安全 |
|
||
| 写者未注册（内核启动 → attach） | **约定只有 `defaultTask` 记日志** | 遵守约定 → 无并发；**其他任务此时记日志 → 逐字节交错**（裸发无互斥） |
|
||
| 写者已注册（稳态） | 任务上下文唯一调用者 = 写者 | 任务上下文零竞争；残余窗口 = ISR 直发撞写者发送中（丢失、不挂死，§7） |
|
||
|
||
**纪律（2026-10-10 固化）**：周期 / 常驻任务**不得**在写者注册前记日志——用 `dbg_console_writer_ready()`（§5）门控自身日志（`adcTask` 的首帧与 10 s 心跳、`protectTask` 的启动锚点行即按此门控——后者 2026-10-12 B6 台架实证：B5 接线时启动行未门控，注册前裸发被交错损坏致 `@test` 锚点 MISS，见 §11 变更记录）。内核前代码仍可直接裸发（单线程，无并发）。
|
||
|
||
## 4. 详细设计
|
||
|
||
### 4.1 环形缓冲
|
||
|
||
| 参数 | 值 | 理由 |
|
||
|------|-----|------|
|
||
| 容量 `DBG_CON_RING_SIZE` | 4096B | 2 的幂 → `&(SIZE-1)` 回绕免除法；≈21 整行（192B/行）余量 |
|
||
| head/tail | `uint16` + `volatile`，单生产者/单写者 | head = 生产者写位置，tail = 写者读位置 |
|
||
| 已用字节 | `(head - tail) & (SIZE-1)` | 无符号差自然回绕，免锁可读 |
|
||
| 单行可接收上限 | `SIZE/2 = 2048B` | 保证"一行恒可入环"；正常路径受 `DBG_CON_LINE_MAX=192B` 约束，不触发 |
|
||
| 位置 | BSS（SRAM1，非 CCM） | CCM = FreeRTOS 堆，放 BSS 不占堆；轮询发送不依赖 DMA 可达性（CCM 的 DMA 不可达约束不适用） |
|
||
|
||
### 4.2 生产者路径（`con_append`）
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["dbg_console_write_line / fputc"] --> B{"写者已注册?<br/>(writer_up)"}
|
||
B -- "否（内核前 / 未 attach）" --> R["write_raw 整行直发<br/>(≤256B 截断, 不等待)"]
|
||
B -- 是 --> C{"中断/异常上下文?<br/>(__get_IPSR() ≠ 0)"}
|
||
C -- 是 --> R
|
||
C -- 否 --> D{"当前任务 == 写者?"}
|
||
D -- 是 --> E["先 dbg_console_drain()<br/>(腾空环形缓冲, 避免自等)"]
|
||
D -- 否 --> F{"环内空间 ≥ 行长?"}
|
||
E --> F
|
||
F -- 是 --> G["临界区：整行拷贝<br/>(head→环尾 + 回绕两段) + 推进 head"]
|
||
F -- 否 --> H["vTaskDelay(1) 等待<br/>最多 200ms (200 tick)"]
|
||
H -- 出现空间 --> G
|
||
H -- 超时 --> I["丢弃：s_con_drop++<br/>(写者随后刷 [ERR] CONSOLE dropped N lines)"]
|
||
G --> J["osEventFlagsSet(SYS_EVT_CONSOLE_TX)<br/>唤醒写者（句柄 NULL 保护）"]
|
||
```
|
||
|
||
关键机制：
|
||
|
||
- **整行原子入环**：拷贝与 head 推进在同一次 `taskENTER_CRITICAL` 内完成 → 写者永不见"半行"；临界区时长有界（≤192B 拷贝，微秒级）。
|
||
- **自等待规避**：写者自身记录日志时先 `drain` 腾空（否则"等写者腾出的空间"会等自己，死锁）；腾空后入环必立即成功。
|
||
- **丢弃可观测**：丢弃累计 `s_con_drop`，写者每次 drain 后把累计值刷成 `[ERR]` 行（§4.3）——`[ERR]` 触发 `@test` Forbidden 判定，丢行永不静默。
|
||
- **唤醒**：入环后置 `SYS_EVT_CONSOLE_TX` 命令位 → 写者立即被唤醒（零时延）；写者循环另有 50ms 超时兜底（事件位异常也不滞留日志）。
|
||
|
||
### 4.3 写者路径（`attach` / `drain`）
|
||
|
||
```c
|
||
/* 注册（defaultTask 进主循环前一次，App/task/default_task.c） */
|
||
dbg_console_writer_attach(); /* 记录任务句柄 + writer_up=1 */
|
||
|
||
/* 写者主循环（事件唤醒 / 50ms 兜底） */
|
||
osEventFlagsWait(sys_evtHandle, SYS_EVT_CFG_SAVE | SYS_EVT_CONSOLE_TX,
|
||
osFlagsWaitAny, 50u);
|
||
dbg_console_drain();
|
||
```
|
||
|
||
`drain` 算法（仅写者任务调用）：
|
||
|
||
1. 循环 `while (used != 0)`：取连续段 `tail → 环尾`，截断至 `DBG_CON_CHUNK_MAX`(256B) → `HAL_UART_Transmit(&huart1, &s_con_ring[tail], n, 0xFFFFu)` → **临界区内推进 `tail`**（交给 UART 的缓冲指针恒为环形缓冲——G2）；
|
||
2. 刷丢弃计数：`s_con_drop != 0` → 组帧 `"\r\n[ERR] CONSOLE dropped N lines\r\n"` → **`write_raw` 直发**（不经环：写者自身输出若走环会 `con_append` → `drain` 重入当前 `drain`，无限递归）。
|
||
|
||
稳态时序：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant P as 生产者任务（netTask 等）
|
||
participant R as 环形缓冲 4KB（BSS）
|
||
participant E as sys_evt 事件标志
|
||
participant W as 写者 defaultTask
|
||
participant U as USART1（115200）
|
||
|
||
P->>R: dbg_console_write_line(整行 ≤192B)
|
||
Note over P,R: 临界区：整行拷贝 + 推进 head
|
||
P->>E: osEventFlagsSet(SYS_EVT_CONSOLE_TX)
|
||
E-->>W: 唤醒（50ms 超时兜底）
|
||
loop 直到 used == 0
|
||
W->>R: dbg_console_drain()：取连续段 ≤256B
|
||
W->>U: HAL_UART_Transmit(块)
|
||
Note over W,R: 临界区：推进 tail
|
||
end
|
||
opt s_con_drop != 0
|
||
W->>U: "[ERR] CONSOLE dropped N lines"（直发）
|
||
end
|
||
```
|
||
|
||
### 4.4 裸发（`dbg_console_write_raw`）
|
||
|
||
- 有界：`len > 256 → 256`（截尾）；发送走 `con_tx_bounded`（**寄存器级轮询 TXE/TC**，超时判据 = DWT `CYCCNT`，`CON_TX_TIMEOUT_CYC` = 100 ms 对应周期数），不持临界区、不等待状态；
|
||
- **2026-10-10：DWT 不可用时改走 `con_tx_counted`（指令计数上界 `CON_TX_GUARD_MAX`），不再回退 `HAL_UART_Transmit`**。两个理由：① HAL 的超时判据是 `HAL_GetTick`——断言/停摆现场 tick 未必在走；② `HAL_UART_Transmit → UART_WaitOnFlagUntilTimeout` 这条尾巴会被 armlink 挂进**每个**碰日志的任务的最坏栈链（`configASSERT` 在 FreeRTOS 内部可达 → 三个内核钩子都在链尾），实测每条链多背 64 B；
|
||
- 适用：内核前 / 未注册期、ISR、异常钩子（栈溢出 / 堆失败）、崩溃上报；
|
||
- **调用方纪律（2026-10-10 补充）**：`con_tx_bounded` **无互斥**（寄存器级轮询，无 `HAL` 的 `gState` 锁）→ 写者注册前**只允许 `defaultTask`**（存储 bring-up 阶段）走此路径；其他常驻任务须用 `dbg_console_writer_ready()` 门控日志（见 §3.4）。
|
||
- 调用方纪律：**只交已知合法的缓冲**——钩子侧先做指针范围校验（Flash / SRAM / CCM 窗口）并拷入本地缓冲再发，TCB 指针不接触 UART（`Src/freertos.c vApplicationStackOverflowHook`，2026-09-24 加固；指针不可信时发占位文本，"上报崩溃的代码不能再崩一次"）。2026-10-10 补充：钩子里的 `name[49]/num[16]` 改**函数级 static**（终点路径、打印完即复位，无并发）——放栈上会让这 81 B 出现在每个任务的最坏链上；行号转换改原地反转，去掉 `HAL_Delay`（`con_tx_bounded` 已等 TC）。
|
||
|
||
### 4.5 `fputc` 重定向（MicroLIB `printf`）
|
||
|
||
`fputc(ch, f)` → `con_append(&b, 1)`：库内部 / 遗留 `printf` 调用同样收敛到单写者路径（注册期逐字节入环；一条完整 `printf` 行 = 环内连续字节，写者按块发出 → 仍行级原子）。
|
||
|
||
**`printf` 是遗留路径**：逐字节 = 一次临界区 + 一次事件置位；新代码一律用 `DBG_*` 宏（调用点格式化整行、一次入环、一次事件）。两路行为一致，仅效率差异。
|
||
|
||
### 4.6 时间参数（实测 / 推导）
|
||
|
||
| 参数 | 值 | 推导 |
|
||
|------|-----|------|
|
||
| 字节率 @115200 8N1 | 86.8 µs/B（10 bit/字节） | 115200 / 10 |
|
||
| 单块 256B | ≈22 ms | 写者单次 `HAL_UART_Transmit` 上限 |
|
||
| 单行 192B（最坏） | ≈17 ms | `DBG_CON_LINE_MAX` |
|
||
| 生产者最长等待 | 200 ms（200 × 1ms tick） | ≈9 个发送块的时间，稳态下环恒被及时排空 |
|
||
| 写者兜底周期 | 50 ms | 事件位失效时日志滞留上限 |
|
||
| 实测日志时延 | 事件唤醒级（无丢失） | 2026-09-25 @test：67 行开机日志完整、无交错、无丢行告警 |
|
||
|
||
## 5. API 参考
|
||
|
||
全部声明位于 `App/log/console_log.h`（仅 MCU 端；模拟器无对应实现，共享代码勿调用）：
|
||
|
||
| 函数 | 签名 | 调用上下文 | 语义 | 备注 |
|
||
|------|------|-----------|------|------|
|
||
| `dbg_console_write_line` | `int (const char *line, unsigned len)` | 生产者（任务上下文） | 整行入环 / 直发；0 = 写入字节数，-1 = 参数非法 / 被丢弃 | 截断 ≤192B（保行首时间戳/标记信息） |
|
||
| `dbg_console_write_raw` | `void (const char *buf, unsigned len)` | **任意**（ISR / 钩子 / 内核前） | 有界直发 ≤256B，不等待、不加锁 | 缓冲须已知合法 |
|
||
| `dbg_console_writer_attach` | `void (void)` | 写者任务、主循环前 | 注册唯一写者 | 仅一次（defaultTask） |
|
||
| `dbg_console_writer_ready` | `uint8_t (void)` | 任意（常驻任务） | 写者是否已注册（1=已注册） | 2026-10-10 加：周期任务据此门控日志，避免写者注册前裸发交错（§3.4） |
|
||
| `dbg_console_drain` | `void (void)` | **仅写者任务** | 排空环并发出 + 刷丢弃计数 | defaultTask 主循环周期调用 |
|
||
| `dbg_console_dropped` | `uint32_t (void)` | 任意 | 诊断：累计丢弃行数 | 外部读取 |
|
||
| `dbg_console_tx_fault_log_take` | `uint8_t (void)` | **仅写者任务** | 取并清"TX 故障待上报"标志 | 2026-10-10 加：drain 内**不得**调 `syslog_post`（会成环），由 defaultTask 在 drain 之外补记 run.log |
|
||
| `fputc` | `int (int ch, FILE *f)` | `printf` 调用点 | MicroLIB retarget 钩子 → 逐字节 `con_append` | 须为全局符号（C 库链接） |
|
||
|
||
## 6. 常量
|
||
|
||
| 常量 | 值 | 定义处 | 含义 |
|
||
|------|-----|--------|------|
|
||
| `DBG_CON_LINE_MAX` | 192 | `console_log.h` | 单行文本上限（含结尾 `'\0'`）；环形缓冲/入环截断上限；超限截断 |
|
||
| `DBG_LINE_BUF_MAX` | = `DBG_CON_LINE_MAX`（深链模块设 **128**） | `dbg_log.h` | **调用点栈上行缓冲尺寸**（2026-10-10 加）。已收紧：`nand_ftl`/`gd5f2gq5ue`/`cfg_file`/`net_cfg`/`net_socket`/`ch395f`/`time_sync`/`default_task`。取值须 ≥ 该模块最长日志行，否则该行被截断 |
|
||
| `DBG_TS_BUF_MAX` | 24 | `dbg_log.h` | 时间戳文本缓冲（`sys_clock_get_str` 恒写 19 字符 + `'\0'`）；与行缓冲**共用一个数组** |
|
||
| `DBG_CON_RING_SIZE` | 4096 | `console_log.c` | 环形缓冲字节数（必须为 2 的幂） |
|
||
| `DBG_CON_CHUNK_MAX` | 256 | `console_log.c` | 写者单次发送上限 = 裸发上限 |
|
||
| `DBG_CON_WAIT_MS` | 200 | `console_log.c` | 缓冲满时生产者最长等待（1ms/轮，仍满 → 丢弃 + 计数） |
|
||
| `CON_TX_TIMEOUT_CYC` | `SystemCoreClock/10` | `console_log.c` | 裸发硬上界 = 100 ms 对应 DWT 周期数 |
|
||
| `CON_TX_GUARD_MAX` | 20000 | `console_log.c` | DWT 不可用时的**计数**上界（每字节 / TC 各数一次；115200 下一字节约需 3000 次轮询，留 6 倍余量） |
|
||
| 写者循环超时 | 50 ms | `App/task/default_task.c` | `osEventFlagsWait` 兜底周期 |
|
||
|
||
## 7. 失效模式与可观测性
|
||
|
||
| 失效 | 行为 | 可观测性 | 残余风险 |
|
||
|------|------|---------|---------|
|
||
| 缓冲满（日志突发 / 写者卡滞） | 生产者等 200ms 后丢行 | `s_con_drop` 累计 → 写者刷 `[ERR] CONSOLE dropped N lines`（@test FAIL，永不静默） | — |
|
||
| 写者未注册（内核前） | 单线程直发 | — | 无（无并发） |
|
||
| 未注册期其他任务直发 | **逐字节交错**（`con_tx_bounded` 无互斥，非旧 `HAL_BUSY`） | 交错行可致 `@test` 标记失配（2026-10-10 台架实证） | 已固化纪律：周期任务用 `dbg_console_writer_ready()` 门控（§3.4 / §9-D5） |
|
||
| ISR 直发撞写者发送中 | 与写者发送竞争 → 丢失，不挂死 | 未计数 | ISR 日志频率极低，best-effort 语义 |
|
||
| 内核状态损坏（栈溢出 / 堆耗尽） | 钩子裸发固定文本 → 复位（栈溢出）/ 仅告警（堆） | `[ERR] STACK OVERFLOW task=…` / `[ERR] MALLOC FAILED …`；任务名范围校验 + 本地拷贝，TCB 指针不入 UART | — |
|
||
| 调用方指针损坏（脏指针） | 无法进入 UART（缓冲恒为环 / 模块本地） | 2026-09-24 HardFault 路径结构性消除 | — |
|
||
| UART 物理失效（发送卡死 / 超时） | `con_tx_bounded` 在 DWT 上界内返回 `HAL_TIMEOUT` → 该块丢弃 + **UART 重初始化**（僵尸通道自愈，§12） | 2026-10-10 起：drain 内**只置标志** `s_con_tx_fault_log`，由 defaultTask 在 drain 之外 `syslog_post(SYSLOG_RUN, "console tx fault, uart reinit")` 补记 run.log（旧实现直接在 drain 里调 `syslog_post` → `write_line → con_append → drain → syslog_post → write_line` **调用图成环**，静态栈在每个任务上多叠一条日志尾巴） | 已知缺口：丢弃计数与故障计数不分离 |
|
||
| `sys_evt` 对象缺失（句柄 NULL） | 唤醒空操作，50ms 兜底 | 至多 50ms 时延 | — |
|
||
|
||
## 8. 内存预算
|
||
|
||
| 项 | 大小 | 位置 |
|
||
|----|------|------|
|
||
| `s_con_ring` | 4096 B | BSS（SRAM1，非 CCM） |
|
||
| `s_con_head/tail/drop/writer_up/writer_task` | ≈14 B | BSS |
|
||
| 生产者行缓冲 `__con_line`（`DBG_EMIT` 宏局部） | 默认 192 B + 时间戳 24 B；**深链模块 128 + 24 B**/调用 | 调用者任务栈（入环后即释放，峰值非累积） |
|
||
|
||
**结论：静态 +4.1KB（SRAM1）；FreeRTOS 堆零增量、无新任务/栈、无新内核对象。** 2026-09-25 实测：`heap free=8776B, min_ever=4816B`（CCM 堆不受影响）；`__con_line` 192B 峰值在各任务既有栈预算内（任务栈按 2026-09-21 实测峰值 ×1.5 + 1KB ISR 余量定档，见 AGENTS.md 任务栈表；当日栈水位复测 6 任务全 PASS）。
|
||
|
||
> ⚠️ **2026-10-10 修正"行缓冲不贵"的结论**：行缓冲是**每个日志调用点**在栈上内联的一份数组，会进 armlink 最坏调用链。实测 defaultTask 那条最深链上 **9 个帧各含一份**（192 + 32 B）→ **约 1.5 KB 纯粹是日志行缓冲**，是该项目静态栈链的第一大项。处置 = `dbg_log.h` 新增 `DBG_LINE_BUF_MAX`（深链模块收到 128）+ 时间戳缓冲并入行缓冲（32 → 24），**未抬栈**即把该链 5312 → 2776 B。核算与前后对比见 `docs/内存管理/RAM使用分析与优化方案.md`"2026-10-10 复测"。
|
||
|
||
## 9. 设计决策与否决的替代方案
|
||
|
||
| # | 替代方案 | 否决 / 采纳理由 |
|
||
|---|---------|----------------|
|
||
| D1 | 逐字符 `fputc` + `gState` 检查（旧方案） | 原子性退化为字节级 → 字符交错（F1）；调用方脏指针直达 UART（F2）；并发立即 `HAL_BUSY` → 静默丢行（C3） |
|
||
| D2 | 整行 `HAL_UART_Transmit` + `gState` 检查 | 消除交错，但不解决脏指针（调用方缓冲仍入 UART）；竞争失败方无等待/重试，整行静默丢；调用方阻塞时长不受控（等 UART 物理速率） |
|
||
| D3 | 专用日志任务 | 违反 G3（RAM 紧张不新增任务/栈）；defaultTask 本就是存储子系统唯一写者，单写者纪律收敛到同一任务，且主循环已是 50ms 事件驱动 |
|
||
| D4 | TX DMA / 中断驱动发送 | 发送率低（115200、日志行稀疏），收益不足；不解决 G2（DMA 同样读调用方缓冲）；DMA 缓冲可达性 / 所有权 / 双缓冲复杂度不值 |
|
||
| D5 | 环 + 直发双路径（**采纳**） | 注册稳态走环（零丢失、有计数）；内核前 / ISR / 钩子走有界直发（G4：不等待、不死锁、零内核对象）；未注册期此路径**无互斥**（2026-10-10 起为寄存器级轮询，无 `HAL` `gState`）→ 约定**只有 defaultTask** 记日志，其他常驻任务用 `dbg_console_writer_ready()` 门控（§3.4） |
|
||
| D6 | 每生产者 SPSC 无锁队列 | 多生产者仍需 MPMC；单环 + 临界区整行拷贝更简，生产者临界区 ≤192B 微秒级；事件位复用免新增内核对象 |
|
||
| D7 | `printf` 保为主路径 | MicroLIB 逐字符回调开销 + 遗留语义；`DBG_*` 宏调用点格式化整行一次入环（一次入环、一次事件） |
|
||
|
||
## 10. 验证记录
|
||
|
||
| 日期 | 验证 | 结果 |
|
||
|------|------|------|
|
||
| 2026-09-24 | HardFault 定位：BFAR=0x10010000（=CCM 末尾+1），PC 在 `HAL_UART_Transmit` 缓冲读取处；崩溃前交错行留证 | 根因确认（F1/F2）→ 单写者加固实施 |
|
||
| 2026-09-25 | `@build`（Keil MDK v5 / ARMCC C99） | **0 Error, 0 Warning**（`console_log.c` 注册于 App 组） |
|
||
| 2026-09-25 | `@test` 硬件闭环（烧录 → 开机日志采集 → 标记校验） | **PASS**：Required 3/3（`App init OK` / `Network Init` / `net init: OK`）；Forbidden 5/5 缺席（`FAIL`/`ERROR`/`HardFault`/`assert`/`[ERR]`，大小写不敏感）；67 行开机日志完整、无交错、无丢行 |
|
||
| 2026-09-25 | 静态门禁：C 代码规范 V1.0 + U+FFFD 乱码 + cppcheck（warning, performance, portability, style） | 0 违规 |
|
||
| 2026-09-25 | 迁移验收：实现迁出 `Src/usart.c`（该文件恢复 478 行纯 CubeMX 形态），双端行为不变 | `@build` 0/0 + `@test` 复测 PASS；引用关系图重生成 |
|
||
|
||
## 11. 实施时间线
|
||
|
||
| 日期 | 事件 |
|
||
|------|------|
|
||
| 2026-09-22 | 链路延迟测试：开机并发 `printf` 丢行（连续 4 行）实证 → S8 非阻塞日志立项（`链路延迟测试说明.md` §10.2） |
|
||
| 2026-09-24 | 字符交错 + HardFault 实证 → 单写者加固实施（4KB 环 + defaultTask 唯一发送 + 裸发回退 + `fputc` 收敛）；当时位于 `Src/usart.c` USER CODE 区 |
|
||
| 2026-09-25 | 迁出至 `App/log/console_log.{h,c}`（HAL 生成文件不含应用代码）；`dbg_log.h` 改 `#include "console_log.h"`；Keil 工程 App 组注册；`@build` 0/0、`@test` PASS、引用关系图与本文档同步 |
|
||
| 2026-09-25 | 写者任务体迁出：`Src/freertos.c` 的 `StartDefaultTask` 任务体（存储 bring-up / 配置引擎 / 控制台 attach+drain / syslog / LED / 栈水位）整体移入 `App/task/default_task.c`（`default_task_func()`，与其余 5 任务文件同址）；`freertos.c` 恢复"接线 + 崩溃钩子"的 CubeMX 形态（719→361 行）；行为零变化，`@build` 0/0 + `@test` PASS 复验 |
|
||
| 2026-10-02 | **ORE 僵尸通道喂狗节奏保护**（台架 gen-288）：round-3 的"单次 drain 预算 250ms"只限单次调用——ORE 锁存在外设软复位后**毫秒级重锁**（PA10 悬空 + RX 使能），背靠背 drain 每轮再耗 100ms 块超时 → 主循环周期拉到 450~500ms → 100ms 节流的喂狗抽样间隙超过 IWDG 最坏容限 1.7s → 停喂 → 误复位（且心跳位全员健康、无 stall 日志，纯**节奏性饥饿**，非死等）。修复：发送故障后立即结束本轮 drain 并进入 300ms 发送冷却（冷却期内 drain 直接让位主循环），保证喂狗节奏 ≤ ~300ms |
|
||
| 2026-10-02 | **round 8b 加固**：发送超时判据改用 DWT `CYCCNT`（时间源无关）。原 `HAL_UART_Transmit` 的 `HAL_GetTick() - Tickstart` 依赖 TIM7 的 `uwTick`，TIM7 一旦停摆超时永不成立 → 写者死等 TXE → 唯一喂狗者停摆 → IWDG 复位。裸发送与缓冲满等待两处均换成 DWT 周期计数硬上界（DWT 使能失败时退回旧 HAL 行为）；另加 `huart1.Instance == NULL` 短路，防早期/断言路径解引用 NULL |
|
||
| 2026-10-10 | **新增 `dbg_console_writer_ready()` + 未注册期纪律固化**：裸发为寄存器级轮询（无 `gState`）→ 未注册期多任务并发**逐字节交错**（台架 `adcTask` 首帧日志与 `[NAND_FTL]` 行交错实证）。新增 `dbg_console_writer_ready()` 供周期任务门控；`adcTask` 首帧/心跳日志据此门控（§3.4 / §4.4） |
|
||
| 2026-10-12 | **纪律盲区台架实证（B6）**：`protectTask`（B5 接线，台架腿当时未跑）启动锚点行在写者注册前裸发 → 与 defaultTask 启动日志**逐字节交错**（`st[art: cycle=220ms elm=70`，两次开机同形复现 = 启动调度确定性的竞态，非 USB 噪声）→ `@test` 锚点 MISS。修复 = 启动行改 `dbg_console_writer_ready()` 首拍补打（adcTask 首帧同款），`@build` 0/0 + `@test` PASS 复验（锚点完好 +577 ms）。§3.4 纪律示例更新 |
|
||
|
||
## 12. ORE 僵尸通道（2026-10-02 台架实证）
|
||
|
||
**机理**：USART1 使能了 RX（PA10 悬空、无上拉）→ 线上噪声持续产生帧错误/溢出 →
|
||
**ORE（Overrun Error）置位** → HAL 发送路径卡在错误状态。对外设做软复位后 ORE
|
||
**毫秒级重锁**，于是每轮 drain 都会耗掉 100ms 量级的块超时。
|
||
|
||
**为什么会被误判**：本设计是"心跳位全员健康、无 STALL 日志"的**纯节奏性饥饿**——
|
||
没有任何任务真的死等，只是主循环周期被 drain 拉长到 450~500ms，而喂狗抽样是 100ms
|
||
节流的、IWDG 最坏容限仅 1.7s，间歇被拉长就触发停喂。**看日志会以为"系统很健康"**。
|
||
|
||
**已做（缓解）**：单次 drain 250ms 预算（round-3）+ 发送故障后 300ms 冷却（round-6）
|
||
+ 超时判据换 DWT（round 8b）。
|
||
|
||
**未做（根治）**：让 USART1 为 **TX-only**（.ioc 中不再使能 RX / PA10 不作 USART1_RX），
|
||
从机制上消除 ORE。属 `.ioc` 结构性改动 + CubeMX 重生成，需单开一轮并复跑台架闭环
|
||
→ 已登记为 `docs/任务规划/登记簿.md` **S-3**。
|
||
|
||
## 13. 开放问题
|
||
|
||
| # | 项 | 说明 |
|
||
|---|----|------|
|
||
| O1 | 未注册期裸发无互斥 | 启动窗口（内核启动 → attach）`dbg_console_write_raw` 无互斥 → 多任务并发会**逐字节交错**（非旧 `HAL_BUSY` 丢整行）。2026-10-10 已固化"周期任务用 `dbg_console_writer_ready()` 门控"纪律；若未来开机日志密度上升，可升级为"内核前静态待发行 + attach 后统一补发"或给裸发加轻量互斥 |
|
||
| O2 | `HAL_UART_Transmit` 超时未计数 | 超时块（UART 物理失效）丢弃但不入 `s_con_drop`；v2 可加独立超时计数 |
|
||
| O3 | `printf` 逐字节开销 | 遗留 `printf` 路径 = 逐字节临界区 + 逐字节事件置位；遗留调用点全部切 `DBG_*` 宏后开销自然消失（不改变机制） |
|
||
| O4 | **ORE 僵尸未根治** | §12：现仅有缓解（250ms 预算 / 300ms 冷却 / DWT 超时），机制根源是 USART1 使能了 RX。根治需 `.ioc` 改 TX-only + CubeMX 重生成 → 已登记 `docs/任务规划/登记簿.md` **S-3** |
|
||
|
||
## 14. 相关文档
|
||
|
||
- `项目架构总览.md` —— 六层分层 / 启动时序 / 6 任务（写者任务与就绪屏障位置）
|
||
- `运行与自检记录设计说明.md` —— sys_log 持久化日志（姊妹模块：同写者任务、不同通道）
|
||
- `测试说明/链路延迟测试说明.md` —— D6 日志税 / S8 非阻塞日志（需求出处与 09-22 丢行实证）
|
||
- `测试说明/自动化测试流程.md` —— `@test` 标记体系（Required / Forbidden 模式，`[ERR]` 语义）
|
||
- AGENTS.md —— 平台约束（内核前禁内核对象 / C 堆禁令 / 事件位语义 / 内存预算）
|
||
|
||
## 修订记录
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| v1.0 | 2026-09-25 | 初版：完整设计说明（背景根因 / 单写者模型 / 详细设计 / API / 参数 / 失效模式 / 内存预算 / 设计决策 / 验证记录）；实现位于 `App/log/console_log.{h,c}` |
|
||
| 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.4 | 2026-10-10 | 新增 `dbg_console_writer_ready()`（写者就绪查询）并固化"未注册期只有 defaultTask 记日志、周期任务用就绪门控"纪律；更正 §3.4 / §7 / §9-D5 / §13-O1 的"只丢不交错"旧结论（裸发已改寄存器级轮询、无 `gState` 互斥） |
|