STM32F4-Base/docs/子系统设计/控制台单写者日志设计说明.md

控制台单写者日志设计说明

版本：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 拓扑

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）

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）

/* 注册（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，无限递归）。

稳态时序：

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 互斥）