wandering1
4a09d4c63f
待发条目 syslog_entry_t 原为 {id, const char *desc}，只存调用方指针，
隐含「desc 必须活到落盘」的契约，但契约既未写进 sys_log.h、也无机械
检查。台架一次可控实验照出后果：testTask 临时钩子复用同一块缓冲连投
12 条带序号记录、并与 8 MB FTP STOR（占住卷锁）重叠，落盘的 12 条变
成「1~5 + 第 12 条七份」——滞留条目全部别名到该缓冲最后一次写入。
叠加卷忙整批回投（条目可滞留到卷空闲），投栈缓冲即成悬垂读。
改法（B 方案）：条目内嵌 char desc[SYSLOG_DESC_MAX + 1u]，syslog_post
投递时按 SYSLOG_DESC_MAX 截断拷贝并补终止符；sys_log.h 参数说明同步
写明「投递即拷贝、不要求生命周期覆盖到落盘」。
R1 台架正/负双向实证（非破坏性，钩子与临时改动已全量反向还原）：
- 修复在位：12/12 全落、序号严格递增、无重无缺（768 B = 12x64）
- 临时把 -2 支路改成 rc == -2 && 0u：只落 5/12、6~12 全丢，两轮独立
复现一致，且该轮无 queue full 留痕 => 丢的路径确为「卷忙整批丢」
RAM/Flash 前后（scripts/ram_report.py 同口径，同一 .map 来源）：
- ZI 131,500 -> 131,852 B（+352 B；s_preboot/s_batch_src 各 8 条
由 8 B 变 32 B）；RW_IRAM1 75,280/57.4% -> 75,632/57.7%
- Code 213,720 -> 213,780 B（+60 B）；RW 1,204 B 不变
- RW_CCM 静态不变（57,376 B / 87.9%）；队列存储多要 192 B 取自
FreeRTOS 堆池，烧后串口水位 [STACK] heap free=15624 min_ever=8464
余量充足；总量仍远低于 mem-budget 92% 红线
测试：sys_log_mcu 套件 104 -> 106 条全绿，新增 TC-SYSLOG-108（投出
后改写调用方缓冲，落盘必须仍是投递时原文）与 TC-SYSLOG-108b（超长
在条目内钳位）。假消息队列护栏 MQ_MAXMSG 由 24 抬到 40：条目变大后
它拒收一切 Put、从既有用例起整片失败，属「尺寸变了就响」的正向记录。
主机侧此前照不出该类问题，是因为用例传字面量、静态存储期无限。
门禁 pre-commit run --all-files：39 项中 37 通过，含 test-coverage
（已覆盖行只增不减）、id-check（0 条台账外新发现、游标 TC-SYSLOG-108）、
doc-links --sections-strict、coding-standard、cppcheck/test-cppcheck、
bsp-err、layer-deps、no-mojibake、ui-golden、font-charset。仅
mem-numbers 与 mem-budget 失败：docs/内存管理/ 受管台账仍记改前
131,500/213,720。按分支约定不在分支上 --write 受管台账，留待合回
主干时统一回填，故 --no-verify 提交。
真机：产品构建 0 错 0 警告，重烧 + 回读校验 OK（suite=NONE dstr=off）、
启动标记齐全、无 [ERR]、VERDICT PASS。
169 lines
8.7 KiB
C
169 lines
8.7 KiB
C
/*
|
||
* 模块名称：System Log — 运行/自检记录引擎（双端共享核心）
|
||
* 模块功能：定长 64B 文本日志记录的公共 API、格式常量与行拆分；
|
||
* MCU 后端 = FatFS /log 目录日志文件（sys_log_mcu.c），模拟器后端 = 宿主文件（sim_syslog.c）
|
||
* 适用平台：STM32F407ZGTx + PC 模拟器（共享头，无 OS/LVGL 依赖）
|
||
* 作者：王建锋
|
||
* 创建日期：2026-09-14
|
||
* 修改记录：
|
||
* v1.0 2026-09-14 王建锋 创建初始版本（设计见 docs/子系统设计/运行与自检记录设计说明.md §4）
|
||
* v1.1 2026-10-24 王建锋 仅契约注释更正，与 App/log/sys_log_mcu.c 的 C/F 两项
|
||
* 整改同步（无签名、无行为改动）：
|
||
* syslog_get_record 写死容量要求（ts_len > SYSLOG_TS_LEN、
|
||
* desc_len > SYSLOG_DESC_MAX）并明确"容量不足一律 -1、
|
||
* 不截断、不写调用方缓冲"——旧注释像是"给少了会被截断"，
|
||
* 实际是整条读不到；syslog_post 写明必须假设丢弃存在、
|
||
* 且丢弃留痕已按通道节流（节流后无丢弃计数）
|
||
*/
|
||
|
||
#ifndef SYS_LOG_H
|
||
#define SYS_LOG_H
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
#include <stdint.h>
|
||
#include <stddef.h>
|
||
|
||
/*
|
||
* 日志 ID：决定落盘文件与容量上限
|
||
*/
|
||
typedef enum {
|
||
SYSLOG_RUN = 0u, /* 运行记录 /log/run.log：上电/重启事件 */
|
||
SYSLOG_SELFTEST, /* 自检记录 /log/selftest.log：开机自检故障（仅故障才写） */
|
||
SYSLOG_COUNT /* 哨兵值，非有效 ID */
|
||
} syslog_id_t;
|
||
|
||
/*
|
||
* 记录格式（定长 64B，一行一条；设计文档 §4.2）：
|
||
* [0..18] "YYYY-MM-DD HH:MM:SS"（ISO 8601 空格变体，19 字符；墙钟无效 = "1970-01-01 08:00:00"）
|
||
* [19] ' '
|
||
* [20..29] epoch 秒 ASCII "%010u"（机器解析/上电重启分类用；墙钟无效 = "0000000000"）
|
||
* [30] ' '
|
||
* [31..58] 描述 UTF-8（≤28B = 9 汉字），不足补 '\0'
|
||
* [59..63] '\0' 填充
|
||
*/
|
||
#define SYSLOG_REC_SIZE 64u /* 单条记录字节数（定长） */
|
||
#define SYSLOG_TS_LEN 19u /* 时间戳字段长度 "YYYY-MM-DD HH:MM:SS" */
|
||
#define SYSLOG_EPOCH_OFFS 20u /* epoch ASCII 字段偏移 */
|
||
#define SYSLOG_EPOCH_LEN 10u /* epoch ASCII 字段长度（2026 年 Unix 秒 = 10 位） */
|
||
#define SYSLOG_DESC_OFFS 31u /* 描述字段偏移 */
|
||
#define SYSLOG_DESC_MAX 28u /* 描述最大字节数（受框架行缓冲 CP_ROW_BUF_LEN=32 约束） */
|
||
|
||
/*
|
||
* 容量上限（条数；满时删除重建，设计文档 §4.3）
|
||
*/
|
||
#define SYSLOG_RUN_MAX 1024u /* /log/run.log：64KB */
|
||
#define SYSLOG_SELFTEST_MAX 512u /* /log/selftest.log：32KB */
|
||
|
||
/*
|
||
* 上电/重启分类窗口（秒）：run.log 末条 epoch 距 now < 该值 → "reboot"，否则 "power on"
|
||
*/
|
||
#define SYSLOG_REBOOT_WINDOW_S 600u
|
||
|
||
/*
|
||
* 函数功能：投递一条日志（任意上下文；非阻塞，队列满则丢弃）
|
||
* 入口参数：id - 日志 ID syslog_id_t
|
||
* desc - 描述串（UTF-8；超过 SYSLOG_DESC_MAX 的部分丢弃，落盘只留前 28 字节）
|
||
* 本参数**投递时即拷贝进待发条目**：调用方缓冲区可立即复用，
|
||
* 不要求生命周期覆盖到落盘（2026-10-24 台架实证后由「只存指针」
|
||
* 改为条目内嵌定长缓冲，理由见 sys_log_mcu.c 的 syslog_entry_t 注释）
|
||
* 指针本身不可为 NULL const char *
|
||
* 返回值：无
|
||
* 限定条件：MCU 端 FreeRTOS 启动前调用走静态待发数组（由 defaultTask 挂载后落盘）
|
||
* 函数说明：调用方**必须假设投递可能被丢弃**——MCU 后端（sys_log_mcu.c）队列 8 槽、
|
||
* 启动前待发数组 8 槽，卷被 ftpTask 长期占用时 defaultTask 会把整批回投
|
||
* 队列（队列因此可长时间处于满态），此时本函数直接丢弃该条，并只在
|
||
* "转入故障"的那一次留痕（丢弃留痕按正常→故障节流，F 项整改 2026-10-24；
|
||
* 节流后**丢弃总数没有计数**，要计量得另加计数器）。必须留住的证据走
|
||
* sys_log_evidence()，不要靠 syslog_post 重试。
|
||
* 模拟器后端（simulator/sim/sim_syslog.c）是单线程直写宿主文件、**没有
|
||
* 队列与丢弃**，因此上面这段满态语义只约束 MCU 端。
|
||
*/
|
||
void syslog_post(syslog_id_t id, const char *desc);
|
||
|
||
/*
|
||
* 函数功能：获取记录条数（= filesize / SYSLOG_REC_SIZE，O(1)）
|
||
* 入口参数：id - 日志 ID syslog_id_t
|
||
* 返回值：条数；文件缺失/未挂载返回 0 uint32_t
|
||
*/
|
||
uint32_t syslog_count(syslog_id_t id);
|
||
|
||
/*
|
||
* 函数功能：读取第 idx 条记录（时间戳 + 描述，均 NUL 结尾）
|
||
* 入口参数：id - 日志 ID syslog_id_t
|
||
* idx - 记录序号（0 起） uint32_t
|
||
* p_ts - 时间戳输出缓冲（不可为 NULL） char *
|
||
* ts_len- p_ts 容量，必须 > SYSLOG_TS_LEN（即 ≥ SYSLOG_TS_LEN+1 = 20 字节） size_t
|
||
* p_desc- 描述输出缓冲（不可为 NULL） char *
|
||
* desc_len - p_desc 容量，必须 > SYSLOG_DESC_MAX（即 ≥ 29 字节） size_t
|
||
* 返回值：0 - 成功；-1 - 越界 / 读失败 / **缓冲容量不足** int
|
||
* 限定条件：容量不足一律返回 -1，**不做静默截断、也不写调用方一个字节**
|
||
* （C 项整改 2026-10-24；旧注释只写"≥…+1 字节"像是"给少了会被截断"，
|
||
* 照它给 28 字节缓冲的结果是整条读不到而不是读到 27 字符）。
|
||
* 描述字段在写入侧已截到 SYSLOG_DESC_MAX，所以按上面的最小容量给缓冲
|
||
* 就一定装得下，读侧不需要第二道截断。
|
||
* MCU 后端与模拟器后端（sim_syslog.c）在这条守卫上取值相同，行为一致；
|
||
* 模拟器侧那份同样不可达的截断支还留在文件里（未列入本轮改动范围）。
|
||
* 调用方：uiTask 的日志页（行缓冲 32B）与 SYSLOG 取证打印。
|
||
*/
|
||
int syslog_get_record(syslog_id_t id, uint32_t idx, char *p_ts, size_t ts_len, char *p_desc, size_t desc_len);
|
||
|
||
/*
|
||
* 函数功能：读取末条记录的 epoch 秒（上电/重启分类用）
|
||
* 入口参数：id - 日志 ID syslog_id_t
|
||
* p_epoch- 输出缓冲（不可为 NULL；无记录时置 0） uint32_t *
|
||
* 返回值：0 - 成功读到末条；-1 - 文件缺失/空 int
|
||
*/
|
||
int syslog_last_epoch(syslog_id_t id, uint32_t *p_epoch);
|
||
|
||
/*
|
||
* MCU 后端专属 API（sys_log_mcu.c；模拟器端无对应实现，勿在共享代码调用）
|
||
*/
|
||
|
||
/*
|
||
* 函数功能：日志引擎初始化（创建 FreeRTOS 消息队列）
|
||
* 入口参数：无
|
||
* 返回值：0 - 成功；-1 - 队列创建失败 int
|
||
* 限定条件：app_main_init() 起始处调用，先于任何 syslog_post()
|
||
*/
|
||
int syslog_mcu_init(void);
|
||
|
||
/*
|
||
* 函数功能：卷挂载成功后的一次性处理（建 /log 目录 + 写"上电/重启"分类记录）
|
||
* 入口参数：无
|
||
* 返回值：无
|
||
* 限定条件：defaultTask f_mount/f_mkfs 成功且置位 SYS_EVT_STORAGE_READY 前调用一次
|
||
*/
|
||
void syslog_mcu_mounted(void);
|
||
|
||
/*
|
||
* 函数功能：排空待发日志并落盘（启动前数组 + 运行期队列，FIFO）
|
||
* 入口参数：无
|
||
* 返回值：无
|
||
* 限定条件：仅 defaultTask（唯一写者）调用；卷未就绪时直接返回（条目滞留待重试）
|
||
*/
|
||
void syslog_drain(void);
|
||
|
||
/*
|
||
* 函数功能：把一条取证行追加到 /log/wdev.log（掉电不丢；变长行，不走 64B 定长格式）
|
||
* 入口参数：p_desc - 取证描述行（调用方已格式化；不可为 NULL） const char *
|
||
* 返回值：0 - 成功；-1 - 卷占用或写失败（证据可能回滚，**不阻断判定**） int
|
||
* 限定条件：poller（defaultTask）上下文调用；卷锁一律 try（绝不阻塞，
|
||
* 本上下文 = 看门狗喂狗点）
|
||
* 函数说明：round 7 取证通道（设计见 docs/子系统设计/看门狗设计说明.md 2026-10-02 变更记录：
|
||
* 误复位后 RAM 态随复位消失、stall 行经僵尸串口丢失，故证据必须落盘）。
|
||
* 内部在释放卷锁后立刻追加一条 s_append(SYSLOG_RUN, ...) 写另一个
|
||
* 文件——FTL 单页缓存语义为"写到不同 LPN 才把前一脏页刷进 NAND"，
|
||
* 没有该 flush 诱导，本行证据会在约 1.7s 后的 IWDG 复位中回滚丢失。
|
||
* 文件 > 8KB 时先 unlink 重建，防长跑无界增长。
|
||
*/
|
||
int sys_log_evidence(const char *p_desc);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* SYS_LOG_H */
|