Files
STM32F4-Base/Drivers/BSP/UI/ui_w_soe.h
T
wandering1 b7a3e18dca docs(ui): UI_数据供给设计改为现状设计并去「说明」,引用与注释全仓校准
- 改名走 rename_ref.py:22 文件 55 处路径引用随迁;764 行规划态
  重写为 584 行现状设计,删落地步骤/验收判据两章与全部历史注
- 新增 §6.4:维护动作/遥测整定/通讯参数/录波回放四条常驻注入
  通道写成现状表;§7.4 SOE 改「已绑定」现状
- ui_data.h 注释修正:rt 帧 212 B→216 B 两处(uint64 位图使整帧
  按 8 对齐,单测 021g 钉 216);录波注入「通道六」改「通道七」
  (与通讯参数撞号)
- 既有断链债清 4 处:屏板链路旧 §9.1/§9.2 ×3、覆盖率口径
  §4.5→§4.4、登记簿标注已删除;check_doc_links 外部名单加
  IEC 60870
- 并发会话的 UI_时间响应分析.md 及其四篇修订不在本笔:README
  行级拆分只暂存数据供给摘要行

验证:keil-build 0 错误 0 警告;pre_commit --all-files 全过;
check_doc_links --all 237 篇零问题;ui_data 主机单测 303/303。
2026-11-17 11:59:45 +08:00

166 lines
8.5 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
* 模块名称:UI SOE 记录页共享组件(ui_w_soe)
* 模块功能:把"/log/soe.log 二进制定长 64 B 事件记录 → 每记录 2 行(偶数行时标、
* 奇数行"元件 + 事件类型")+ 单条读盘缓存 + 空态伪行"无记录"这套逻辑
* 收成一份,与文本记录组件 ui_w_records 同构(用户学习成本为零);
* 数据经注入式 reader 函数表取,本头**不含任何 App 头**
* 与文本记录的区别:SOE 是结构化二进制记录(时标/类型/元件号/序号/值),
* 不是"时间戳 + 描述文本",不能让文本读者混读——故另立组件与另立
* 记录视图结构(照 ui_w_records.h 的注入模式,不复用其 desc 字段)
* 显示名映射(本组件私有,属表现层):事件类型与元件都按**不透明编号**入参,
* 编号值与 App 侧枚举逐项相等(一致性由 test/host/ui_data 主机单测
* 现场核对,不是照抄文档转述);文案是显示规格,不进快照也不进 App 层
* (口径 docs/UI设计/UI_数据供给设计.md §8)
* 适用范围:Drivers/BSP/UI(分层方向由 scripts/check_layer_deps.py 守护)
* 说明:reader 注入点已备好但**两端均未绑定**——SOE 文件的只读 API
* (条数 / 按序号读一条)尚未在落盘侧提供,绑定与页面接线属道E 后续
* 任务;未绑定期间本组件按空态渲染("无记录"伪行),不崩不读野
* 作者:王建锋
* 创建日期:2026-10-25
* 修改记录:
* v1.0 2026-10-25 王建锋 创建(道E task-14:事件类型/元件显示名映射 +
* reader 契约;映射含未标定闭锁/复归两类新事件)
*/
#ifndef UI_W_SOE_H
#define UI_W_SOE_H
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
/* 时间戳缓冲容量(与文本记录组件同宽:19 字符 + NUL) */
#define UI_W_SOE_TS_LEN 20u
/*
* 事件类型不透明编号:UI 侧只认编号,不认识 App 的 soe_type_t。
* ⚠ 编号值与 App/log/soe_rec.h 的 soe_rec.h 枚举逐项相等(现场核对 2026-10-25:
* 1 元件动作 / 2 元件返回 / 3 软压板退出 / 4 软压板投入 / 5 采样闭锁 /
* 6 采样恢复 / 7 未标定闭锁 / 8 标定复归 / 9 = 哨兵),漂移由主机单测拦
* (test/host/ui_data 的 TC-UIDATA-012);新增类型 = 枚举尾追加 + 这里加编号
* + 名字表加一行 + 单测加一条
*/
#define UI_W_SOE_T_NONE 0u /* UI 私有:未知/未映射编号(读失败行) */
#define UI_W_SOE_T_ELM_ASSERT 1u /* 元件动作(值 = 状态打包) */
#define UI_W_SOE_T_ELM_RETURN 2u /* 元件返回(值 = 返回前状态快照) */
#define UI_W_SOE_T_PLATE_OUT 3u /* 软压板退出 */
#define UI_W_SOE_T_PLATE_IN 4u /* 软压板投入 */
#define UI_W_SOE_T_SAMPLE_BLOCK 5u /* 采样闭锁(值 = 采样故障闭锁位图) */
#define UI_W_SOE_T_SAMPLE_RESUME 6u /* 采样恢复 */
#define UI_W_SOE_T_CAL_BLOCK 7u /* 未标定闭锁(值 = VALID 未齐的通道位图) */
#define UI_W_SOE_T_CAL_RESUME 8u /* 标定复归 */
#define UI_W_SOE_T_COUNT 9u /* 哨兵 = 名字表长度(不是有效类型) */
/* 元件编号:与保护元件枚举同序(0..8),0xFF = 非元件事件
* (一致性由同名单测 TC-UIDATA-013 现场核对) */
#define UI_W_SOE_ELM_N 9u
#define UI_W_SOE_ELM_NONE 0xFFu
/* 记录标志位:bit7 = 记录时时钟无效(时标不可信,页面须显式标记而非显示假时间) */
#define UI_W_SOE_FLG_IV 0x80u
/*
* SOE 记录视图(reader 的输出形态;字段原样搬运,不做时标换算与业务判断)
* 单条 32 B:读盘缓存按实例存,一页 8 行 = 4 条记录也只缓存当前正在渲染的那条
*/
typedef struct {
char ts[UI_W_SOE_TS_LEN]; /* "YYYY-MM-DD HH:MM:SS";IV 或未对时时为空串 */
uint8_t type; /* UI_W_SOE_T_*(未知编号原样透传,名字表回 "--") */
uint8_t elm; /* 0..UI_W_SOE_ELM_N-1 或 UI_W_SOE_ELM_NONE */
uint8_t flags; /* UI_W_SOE_FLG_IV */
uint8_t rsv; /* 预留(对齐填充) */
uint32_t seq; /* 记录序号(上电内单调) */
uint32_t value; /* 类型相关值(页面当前不展开,留作详情行) */
} ui_w_soe_rec_t;
/*
* 注入式 SOE reader(只读函数表;契约与 ui_w_records.h 的 ui_rec_reader_t 同构,
* 只是数据是二进制记录,所以取回的是整条视图而不是两段文本)
* 实现体在 App / 模拟器侧,uiTask 上下文同步调用——绘制路径上的读盘时序与
* 文本记录页一致,无新增并发面
*/
typedef struct {
/*
* 函数功能:取 SOE 记录总条数
* 入口参数:无
* 返回值:条数(0 = 空态,页面显示"无记录"伪行) uint16_t
*/
uint16_t (*count)(void);
/*
* 函数功能:读第 idx 条 SOE 记录(解码成视图)
* 入口参数:a_idx - 记录序号(0 起) uint32_t
* a_out - 输出视图(非 NULL) ui_w_soe_rec_t *
* 返回值:0 = 成功;-1 = 序号越界;-2 = 读失败或校验和不符
* (码值与文本记录 reader 同族) int
*/
int (*get)(uint32_t a_idx, ui_w_soe_rec_t *a_out);
} ui_soe_reader_t;
/* SOE 记录页实例(读盘缓存必须按实例存,理由同 ui_w_records.h 的实例说明) */
typedef struct {
uint8_t cache_valid; /* 1 = rec 是 last_rec 那条 */
uint32_t last_rec; /* 已缓存的记录序号 */
ui_w_soe_rec_t rec; /* 当前记录缓存 */
} ui_w_soe_t;
/*
* 函数功能:注入 SOE reader(启动时一次;NULL = 撤销注入,页面回空态)
* 入口参数:a_reader - 只读函数表(生命周期由注入方保证,组件只存指针)
* const ui_soe_reader_t *
* 返回值:无
* 限定条件:uiTask 启动期注入(ui_menu_init 之前,与记录 reader 同址同纪律)
*/
void ui_w_soe_bind(const ui_soe_reader_t *a_reader);
/*
* 函数功能:事件类型编号 → 显示名(表现层映射表)
* 入口参数:a_type - 类型编号(UI_W_SOE_T_*) uint8_t
* 返回值:Flash 字符串指针(恒非 NULL;未知编号回 "--",不空指针、不空白) const char *
* 限定条件:无
* 函数说明:元件类事件(动作/返回)的名字短(2 字),放**值列**;
* 非元件事件(压板/采样/标定四类,4 字)放**名列**——两列宽度不同,
* 由 ui_w_soe_refresh 按 elm 是否有效决定落在哪一列
*/
const char *ui_w_soe_type_name(uint8_t a_type);
/*
* 函数功能:元件编号 → 显示名(表现层映射表)
* 入口参数:a_elm - 元件编号(0..UI_W_SOE_ELM_N-1) uint8_t
* 返回值:Flash 字符串指针(恒非 NULL;越界或非元件事件回 "--") const char *
* 限定条件:无
* 函数说明:名称最长 4 字(零序过压/过流Ⅰ段),名列可用宽约 94 px = 7 汉字
* (口径 docs/UI设计/页面扩充详细方案.md §2.3 第 4 条)
*/
const char *ui_w_soe_elm_name(uint8_t a_elm);
/*
* 函数功能:总行数(每条记录 2 行;空态 = 单条伪行"无记录")
* 入口参数:a_inst - SOE 页实例 ui_w_soe_t *
* 返回值:总行数 uint16_t
* 限定条件:无(未注入 reader 视同 0 条)
*/
uint16_t ui_w_soe_count(ui_w_soe_t *a_inst);
/*
* 函数功能:逐行取数(偶数行 = 时标,奇数行 = 元件 + 事件类型)
* 入口参数:a_inst - SOE 页实例 ui_w_soe_t *
* a_row - 全局行下标 uint16_t
* a_name - 名输出缓冲(框架 UI_BUF_STRLEN) char *
* a_value - 值输出缓冲(同上) char *
* 返回值:无
* 限定条件:页面打开中(框架绘制/按键上下文,uiTask)
* 函数说明:时标行——时钟无效(IV 位)或时标为空时名列显示 "--",
* **不显示猜测时间**(诚实性判据,同待机屏空串先例);
* 内容行——元件事件名 = 元件、值 = 动作/返回;非元件事件名 = 类型、
* 值 = 空串(值列宽约 59 px = 4 汉字,非元件事件词放这里放不下)
*/
void ui_w_soe_refresh(ui_w_soe_t *a_inst, uint16_t a_row, char *a_name, char *a_value);
#ifdef __cplusplus
}
#endif
#endif /* UI_W_SOE_H */