wandering1
4a4ad6bc5f
现状口径：/keil-build 与 /serial-boot-test 是 DSH 会话的技能调用名， 不是 shell 命令；「名 + 命令行参数」的命令形态改为可执行体 run_boot_test.py 的真实调用。 - AGENTS.md：别名说明重写为「技能调用名不是 shell 命令」，两条目改 「编译（/keil-build）」「串口回归（/serial-boot-test）」 - keil-build / serial-boot-test 两 skill 调用名与示例同步；task-worktree 方案文档去掉 @build/@test 惯例从句；@task 保留（不在点名范围） - 123 文件现状陈述全改；台架捕获、变更记录/时间线、rename 映射输入 等 41 行历史证据保留旧名 - gen_memory_svg.py 6 处措辞随改，3 张 SVG 产物同批重跑 - 顺手补并行方案同行漏网计数 51→52 钩子 验证：提交期快钩子对 123 文件实跑全 Passed；check_doc_links --all rc=0（3038 处、无法判定 0）；check_mermaid --all rc=0；YAML 解析 52 钩子不变；skill-size rc=0；py_compile 全过；字节卫生零漂移。
91 lines
5.6 KiB
C
91 lines
5.6 KiB
C
/*
|
||
* 模块名称：Console Single-Writer Logging — 控制台单写者日志（RS232#1 / UART5）
|
||
* 模块功能：调试控制台单写者环形缓冲的公共 API：所有任务/上下文（含 printf）只把
|
||
* 已格式化整行文本入环形缓冲，写者任务（defaultTask）为唯一
|
||
* HAL_UART_Transmit 发送点（行级原子 + 指针可控）
|
||
* 使用方法：
|
||
* 1. 生产者：DBG_ERROR/DBG_INFO/DBG_DEBUG 宏（dbg_log.h，内部用库 snprintf
|
||
* 有界格式化整行后调 dbg_console_write_line）；或直接调 dbg_console_write_line
|
||
* 2. 写者任务：进入主循环前调 dbg_console_writer_attach() 注册为唯一发送者，
|
||
* 循环中周期调 dbg_console_drain() 排空（defaultTask 已接线，见 Src/freertos.c）
|
||
* 适用平台：STM32F407ZGTx（仅 MCU 端；模拟器不编译本模块——模拟器 DBG_*
|
||
* 直接映射 printf，见 simulator/dbg_log.h）
|
||
* 作者：王建锋
|
||
* 创建日期：2026-09-24
|
||
* 修改记录：
|
||
* 2026-09-24 王建锋 创建（自 Src/usart.c USER CODE 区迁出：
|
||
* HAL 库生成文件不得包含应用代码）
|
||
* 2026-10-26 王建锋 道G task-23：裸发路径加「行级单一所有者」（O1 第二实例），
|
||
* 新增 dbg_console_tx_begin()/dbg_console_tx_end() 供"一条行分多段裸发"
|
||
* 的调用方收口；dbg_console_write_raw() 的"不加锁"三个字从接口上取消
|
||
*/
|
||
|
||
#ifndef CONSOLE_LOG_H
|
||
#define CONSOLE_LOG_H
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
#include <stdio.h>
|
||
#include <stdint.h>
|
||
|
||
/*
|
||
* 单写者控制台 API（与 DBG_ENABLE 无关，任何构建都必须可见）：
|
||
* dbg_console_write_line - 生产者入口：调用方已格式化好的整行文本一次入环形缓冲
|
||
* （刻意**不用**自研可变参数函数——规范 S12 7.6 禁止；格式化在
|
||
* DBG_PRINT 宏内用库 snprintf 完成）
|
||
* dbg_console_write_raw - 异常/早期路径：有界单次直发；**整行独占发送器**
|
||
* （道G task-23：拿不到独占就把整行原文转入环形缓冲延后发，
|
||
* 与当场直发逐字节相同——不补前缀、不重打时间戳；
|
||
* 连环都放不下才计入 dbg_console_dropped()）
|
||
* dbg_console_writer_attach- 写者任务（defaultTask）注册自己为唯一发送者
|
||
* dbg_console_writer_ready - 写者是否已注册（1=已注册）。供**周期性任务**在写者就绪前
|
||
* 抑制日志用：写者未注册时 con_append 走无锁直发路径
|
||
* （仅假设 defaultTask 在日志），其余任务此时落日志会与
|
||
* defaultTask 的存储初始化日志字节级交错（2026-10-10 台架实测）
|
||
* dbg_console_drain - 写者任务排空缓冲并发送（单次有界；TX 失败自动软复位自愈）
|
||
* dbg_console_dropped - 真没落地的丢弃数：① 缓冲满丢的一行；② 一个没能确认
|
||
* 送达而出环的块；③ 抢不到整行所有权**且**环也放不下的裸发
|
||
* （道G task-23）。诊断；[ERR] CONSOLE dropped 行报的就是它。
|
||
* ⚠ 抢不到所有权但成功让路入环的那条行**不入本账**（它没丢，
|
||
* 只是晚一点发）——这本账必须保持"红得有意义"，因为
|
||
* [ERR] 是 /serial-boot-test 的 Forbidden 标记）
|
||
* dbg_console_tx_fault - 因僵尸通道软复位自愈的次数（诊断，语义不变）
|
||
* dbg_console_tx_timeout - 写者排空时观察到的块超时次数（TXE / TC 两条硬上界都算）。
|
||
* 三本账分开：看日志有没有在丢 -> dropped；看外设自愈了几次
|
||
* -> tx_fault；看 UART 物理失效（含"字节已发出但 TC 不置位"）
|
||
* -> tx_timeout。别把三本账混成一个数（docs §13-O2 ）
|
||
* dbg_console_tx_fault_log_take
|
||
* - 取走"TX 故障待上报"标志（读后清）。**必须**由写者任务在
|
||
* dbg_console_drain() 之外调用后自行 syslog_post——本模块
|
||
* 刻意不调日志子系统，否则形成 write_line→con_append→drain
|
||
* →syslog_post→write_line 调用图成环，静态栈深全线虚高
|
||
*/
|
||
#define DBG_CON_LINE_MAX 192U /* 单行文本上限（含结尾 '\0'，超出截断） */
|
||
int dbg_console_write_line(const char *line, unsigned len);
|
||
void dbg_console_write_raw(const char *buf, unsigned len);
|
||
uint8_t dbg_console_tx_begin(void); /* 1=已独占一条行；0=别人持有（调用方照发即可） */
|
||
void dbg_console_tx_end(void); /* 与 tx_begin 成对；未持有时空操作（幂等） */
|
||
void dbg_console_writer_attach(void);
|
||
uint8_t dbg_console_writer_ready(void);
|
||
void dbg_console_drain(void);
|
||
uint32_t dbg_console_dropped(void);
|
||
uint32_t dbg_console_tx_fault(void);
|
||
uint32_t dbg_console_tx_timeout(void);
|
||
uint8_t dbg_console_tx_fault_log_take(void);
|
||
|
||
/*
|
||
* 函数功能：MicroLIB printf 底层重定向（C 库 retarget 钩子，须为全局符号）
|
||
* 入口参数：ch - 字符；f - 文件流（忽略）
|
||
* 返回值：原样返回 ch
|
||
* 限定条件：printf 调用点执行（任意任务上下文）；字节交单写者路径
|
||
*/
|
||
int fputc(int ch, FILE *f);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* CONSOLE_LOG_H */
|