wandering1
a6cdebde62
- D-6 目录规范化：docs 根目录散落文档归入 UI设计/子系统设计/架构设计/审查记录/ 环境与部署/网络 等子目录，去掉目录名空格，重命名 嵌入式C语言代码规范_V1.0.md - D-7 三档一致性门禁：新增 scripts/check_doc_links.py（链接存在性）、 scripts/gen_task_table.py（FreeRTOS 任务表数值）、scripts/check_mem_numbers.py （内存/Flash 体积），均支持 --check/--write/--diff，pre-commit 钩子同步注册 - D-5 文档索引：新建 docs/README.md，新建 docs/文档规范.md 约束目录命名与链接写法 - D-1 芯片手册瘦身：删除 1069 张无引用孤儿图片（77.06 MB）， docs/芯片手册 120 MB → 41 MB，已引用图片零断链 - 同步 C 源码注释中的文档路径引用（D-6 重组后），构建 0 错误 0 警告
127 lines
4.9 KiB
C
127 lines
4.9 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）
|
||
*/
|
||
|
||
#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 字节；超长截断） const char *
|
||
* 返回值：无
|
||
* 限定条件：MCU 端 FreeRTOS 启动前调用走静态待发数组（由 defaultTask 挂载后落盘）
|
||
*/
|
||
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 - 时间戳输出缓冲（≥SYSLOG_TS_LEN+1 字节；不可为 NULL） char *
|
||
* ts_len- p_ts 容量 size_t
|
||
* p_desc- 描述输出缓冲（≥SYSLOG_DESC_MAX+1 字节；不可为 NULL） char *
|
||
* desc_len - p_desc 容量 size_t
|
||
* 返回值：0 - 成功；-1 - 越界/读失败 int
|
||
*/
|
||
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);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* SYS_LOG_H */
|