wandering1
04997e48aa
同族第二道：代码注释面。41 个 run_unit_test.py 文件头与引用行、common harness 与两份 README、4 个 *_test.c 文件头、App/** 14 处（含 BOM 文件 App/cfg/cfg_file.c）、 GD5F nand_ftl.c 1 处，共 73 站点 / 64 文件；措辞取「主机侧纯逻辑单元测试运行器 （纯标准库）」避免同行「主机侧」重复。 零行为改动（机器证据，不是口头）： - 17 个 .c/.h 剥掉注释后与 HEAD **逐字节相同**； - 42 个 .py 走 ast.dump 比较、仅归一 docstring（真实字符串字面量参与比较，故旗标或 输出文本被动过必然报红）→ 全部相等；behaviour_changed=0。 - py_compile 42/42；抽跑 watchdog 47/47、freq 46/46（动手前先取基线，改后同数）； CR 字节 0、EF BF BD 0、BOM 与 HEAD 逐一一致、check_bom_drift rc=0。 刻意未动：6 处字符串字面量（FTP 应答 "215 UNIX Type: L8"、lftpd_test.c SYST 断言、 console_log_test.c 的 "L1\r\n"、phasor_test.c 的 "L2-in ring" 文案与 printf 标题）—— 改了就是改测试输出/行为；UI 设计令牌层 L0（ui_tokens.h、ui_content_page.c）与 test/host/README.md 的算法层号是**另外的族**。 两条 SyntaxWarning（ftp_cfg / net_cfg 文件头 \S 转义）**HEAD 同样存在**，已对 HEAD 副本 复现证明非本次引入，未顺手改。
126 lines
5.5 KiB
C
126 lines
5.5 KiB
C
/*
|
||
* 模块名称：SOE Record — 事件顺序记录编解码（纯逻辑，双端可测）
|
||
* 模块功能：定长 64B SOE（Sequence-of-Events）记录的构建与解析：
|
||
* CP56Time2a 时标 + 记录类型 + 元件号 + 单调序号 + 值 + 校验和。
|
||
* **零 I/O、零 OS 依赖**（仅 stdint/string）→ 主机侧纯逻辑离线单测
|
||
* （分层约束：协议/记录与硬件 I/O 分离）。
|
||
* 记录口径（docs/算法/继电保护功能复现规划.md §3.4「SOE 记录」「动作记录」，B9）：
|
||
* 落盘文件 = /log/soe.log（8.3 合规；FF_USE_LFN=0 约束），定长 64B 一条
|
||
* （照 run.log 先例：count = filesize/64 O(1)、容量满删除重建）。
|
||
* 独立于 run.log 的理由：run.log 是文本记录（时间戳+epoch+UTF-8 描述，
|
||
* syslog_get_record/UI 按文本读），SOE 是二进制结构化记录（时标/类型/
|
||
* 序号/值），混入同一文件会破坏现有文本读者。
|
||
* 记录布局（64B，多字节字段一律小端）：
|
||
* [0] 版本 SOE_REC_VER
|
||
* [1] 类型 soe_type_t
|
||
* [2] 元件号（prot_elm_id_t；SOE_ELM_NONE=0xFF = 非元件事件）
|
||
* [3] 标志位（bit7 IV = 记录时时钟无效，CP56 IV 位同步置位）
|
||
* [4..7] 序号 seq（uint32 小端；上电内单调，跨复位重启计数——见 soe_store.h）
|
||
* [8..14] CP56Time2a（7B，IEC 60870-5-4 §5.1.6；秒域时基 → ms 字段恒 0）
|
||
* [15..18] epoch 秒（uint32 小端；IV 时置 0，主机解码交叉校验用）
|
||
* [19..22] 值 value（uint32 小端；语义随类型，见 soe_type_t 注释）
|
||
* [23..62] 保留（恒 0）
|
||
* [63] 校验和 = sum8([0..62])（撕裂/半写检测，解析侧拒绝不匹配）
|
||
* 创建日期：2026-10-12（B9）
|
||
*/
|
||
#ifndef SOE_REC_H
|
||
#define SOE_REC_H
|
||
|
||
#include <stdint.h>
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* 记录尺寸与版本（定长；改布局必须升 SOE_REC_VER） */
|
||
#define SOE_REC_SIZE 64u
|
||
#define SOE_REC_VER 1u
|
||
|
||
/* 字段偏移（解析/主机解码工具共用口径） */
|
||
#define SOE_OFF_VER 0u
|
||
#define SOE_OFF_TYPE 1u
|
||
#define SOE_OFF_ELM 2u
|
||
#define SOE_OFF_FLAGS 3u
|
||
#define SOE_OFF_SEQ 4u /* 4B */
|
||
#define SOE_OFF_CP56 8u /* 7B */
|
||
#define SOE_OFF_EPOCH 15u /* 4B */
|
||
#define SOE_OFF_VALUE 19u /* 4B */
|
||
#define SOE_OFF_SUM 63u
|
||
|
||
/* 标志位 */
|
||
#define SOE_FLG_IV 0x80u /* bit7：记录时时钟无效（CP56 IV 位同步置位） */
|
||
|
||
/* 非元件事件的元件号 */
|
||
#define SOE_ELM_NONE 0xFFu
|
||
|
||
/*
|
||
* 记录类型（值语义随类型）：
|
||
* 1 元件动作 value = 元件状态打包（bit0 asserted / bit1 picked / bit2 enabled）
|
||
* 2 元件返回 value = 同上（返回瞬间的旧状态快照）
|
||
* 3 软压板退出 value = 0
|
||
* 4 软压板投入 value = 1
|
||
* 5 采样闭锁 value = adc_health 闭锁位图（触发时的 hf & mask）
|
||
* 6 采样恢复 value = 0
|
||
* 7 标定闭锁 value = UA/UN/IA VALID 未齐的通道位图（未标定即闭锁，2026-10-25）
|
||
* 8 标定复归 value = 0
|
||
*/
|
||
typedef enum {
|
||
SOE_T_ELM_ASSERT = 1u,
|
||
SOE_T_ELM_RETURN,
|
||
SOE_T_PLATE_OUT,
|
||
SOE_T_PLATE_IN,
|
||
SOE_T_SAMPLE_BLOCK,
|
||
SOE_T_SAMPLE_RESUME,
|
||
/* 未标定闭锁（「数据可信」未标定即闭锁一项，2026-10-25 道A 追加）：UA/UN/IA 的 VALID
|
||
* 未全置位 → 判据停走；与采样闭锁分型，边沿各留一条记录 */
|
||
SOE_T_CAL_BLOCK,
|
||
SOE_T_CAL_RESUME,
|
||
SOE_T_COUNT /* 哨兵值，非有效类型 */
|
||
} soe_type_t;
|
||
|
||
/* 解析产物（字段原样拷贝；CP56 不在此层换算，主机工具解码） */
|
||
typedef struct {
|
||
uint8_t ver;
|
||
uint8_t type;
|
||
uint8_t elm_id;
|
||
uint8_t flags;
|
||
uint32_t seq;
|
||
uint8_t cp56[7];
|
||
uint32_t epoch_s;
|
||
uint32_t value;
|
||
} soe_rec_t;
|
||
|
||
/*
|
||
* 函数功能：构建一条 64B SOE 记录（纯计算，无 I/O；任意上下文可调）
|
||
* 入口参数：rec - 输出缓冲（SOE_REC_SIZE 字节，不可为 NULL） uint8_t *
|
||
* type - 记录类型 soe_type_t（越界按 SOE_T_COUNT 处理为保留 0）
|
||
* elm_id - 元件号（非元件事件传 SOE_ELM_NONE） uint8_t
|
||
* flags - 标志位（SOE_FLG_IV = 时钟无效） uint8_t
|
||
* seq - 单调序号 uint32_t
|
||
* epoch_s - 墙钟 epoch 秒（IV 时传 0；同时 flags 须带 SOE_FLG_IV）
|
||
* value - 类型相关值 uint32_t
|
||
* 返回值：无
|
||
* 函数说明：epoch_s → CP56Time2a（UTC 分解，Hinnant civil 日历算法，与
|
||
* iec104_asdu.c 同一算法族；钳位 [2000-01-01, 2127-12-31]，
|
||
* ms 字段恒 0——sys_clock 秒域时基，如实登记）。
|
||
* flags 带 IV 时 CP56 byte2 bit7 置位（标准"时间无效"语义）。
|
||
*/
|
||
void soe_rec_build(uint8_t *rec, uint8_t type, uint8_t elm_id, uint8_t flags,
|
||
uint32_t seq, uint32_t epoch_s, uint32_t value);
|
||
|
||
/*
|
||
* 函数功能：解析一条 64B SOE 记录（校验版本 + 校验和）
|
||
* 入口参数：rec - 原始记录（SOE_REC_SIZE 字节，不可为 NULL） const uint8_t *
|
||
* out - 解析输出（不可为 NULL） soe_rec_t *
|
||
* 返回值：0 成功 / -1 参数错 / -2 版本不符 / -3 校验和不符（撕裂/半写） int
|
||
* 函数说明：只读，不改动 rec。类型/标志不做强校验（前向兼容：新版本类型
|
||
* 旧解析器可读），版本与校验和是硬门槛。
|
||
*/
|
||
int soe_rec_parse(const uint8_t *rec, soe_rec_t *out);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* SOE_REC_H */
|