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。
This commit is contained in:
2026-11-17 11:59:45 +08:00
parent 8ebef82c20
commit b7a3e18dca
24 changed files with 645 additions and 823 deletions
+3 -3
View File
@@ -4,12 +4,12 @@
* 只读访问——本模块是纯内存叶子:不取数、不格式化、不判断业务含义、
* 不碰 LVGL、不 include 任何 App 头(职责边界与依赖方向 =
* Drivers/BSP/UI/ui_data.h 文件头与
* docs/UI设计/UI_数据供给设计说明.md §3.2)
* docs/UI设计/UI_数据供给设计.md §3.2)
* 并发模型:单写者同上下文——唯一发布者 App/app/ui_data_feed.c 与全部页面钩子都在
* uiTask 内串行执行,故无锁、无双缓冲、无 seqlock;将来真出现第二个
* 发布者,保护收在本模块内部(双槽 + 每槽 seq + 单字节活动下标,照
* App/algo/phasor.c 双区先例),页面代码不受影响
* (判据 docs/UI设计/UI_数据供给设计说明.md §5.1)
* (判据 docs/UI设计/UI_数据供给设计.md §5.1)
* 写路径(定值整定请求队列)同理:生产者是页面"保存"按键钩子、消费者是
* App 侧节拍里的 ui_data_param_drain(),两者同在 uiTask → 环形队列照旧
* 无锁;若将来出现第二个投递上下文,唯一要做的是给 request/drain 两侧
@@ -142,7 +142,7 @@ int ui_data_publish_rt(const ui_data_rt_t *a_snap) {
* 入口参数:a_snap - 源帧 const ui_data_par_t *
* 返回值:0 - 已发布;-1 - 参数无效(NULL,存量不动) int
* 限定条件:同上;发布节拍 = 定值校验和变化才发
* (docs/UI设计/UI_数据供给设计说明.md §5.2)
* (docs/UI设计/UI_数据供给设计.md §5.2)
*/
int ui_data_publish_par(const ui_data_par_t *a_snap) {
if (a_snap == NULL) {
+14 -13
View File
@@ -3,16 +3,16 @@
* 模块功能:App 层 → UI 层唯一数据通道的"存侧"——只持有最新一帧实时量(rt)/
* 参数(par)/装置信息(info) 快照 + 发布序号,给页面只读访问;
* 不取数、不格式化、不判断业务含义(职责边界 =
* docs/UI设计/UI_数据供给设计说明.md §3.2)
* docs/UI设计/UI_数据供给设计.md §3.2)
* 适用范围:Drivers/BSP/UI(表现层叶子:不 include 任何 App 头、不 include 任何
* 页面头、不碰 LVGL——分层方向由 scripts/check_layer_deps.py 守护,
* BSP → App 反向 include 一律拦提交)
* 并发模型:写侧 = App/app/ui_data_feed.c(唯一发布者);读侧 = ui_page_* 的绘制/
* 按键钩子。两侧同在 uiTask 上下文串行执行 → 无锁、无双缓冲、无 seqlock
* (判据与"将来出现第二发布者"时的扩展路径见
* docs/UI设计/UI_数据供给设计说明.md §5.1)
* docs/UI设计/UI_数据供给设计.md §5.1)
* 页面用法:行缓存按"发布序号变过才整帧拷"门控,勿逐行整帧拷贝
* (docs/UI设计/UI_数据供给设计说明.md §5.4):
* (docs/UI设计/UI_数据供给设计.md §5.4):
* static ui_data_rt_t s_rt;
* static uint32_t s_seq;
* if (ui_data_rt_seq() != s_seq) {
@@ -73,12 +73,12 @@ extern "C" {
/*
* 契约版本:结构体字段只允许尾部追加,追加即升此值并在写侧填默认值
* (禁止删除或重排字段——页面按名字取,重排是静默错位;
* 口径 docs/UI设计/UI_数据供给设计说明.md §4.3)
* 口径 docs/UI设计/UI_数据供给设计.md §4.3)
*/
/* v2(2026-10-26,道F task-1):ui_data_par_t 尾追加 cal_block——版本号是页面与
* 写侧唯一的对齐凭据,追加字段不升版 = 老页面按新帧长 memcpy 时静默错位
* v3(2026-11-16):「开入开出」页——ui_data_rt_t 尾追加 dio_di_mask/dio_di_valid/
* dio_do_mask/dio_do_valid(板级开入开出,208 B → 212 B,见 ui_data_rt_t 字段注) */
* dio_do_mask/dio_do_valid(板级开入开出,208 B → 216 B,见 ui_data_rt_t 字段注) */
#define UI_DATA_VER 3u
/* ── 通道数量 ─────────────────────────────────────────────────────────────── */
@@ -86,7 +86,7 @@ extern "C" {
/* 遥测语义通道数:下标序 = adc_semantic_t(UA/UB/UC/UN/IA/IB/IC/IN/TEMP)。
* BSP 侧不得 include App 头,故"两数相等"的编译期守卫落在写侧
* App/app/ui_data_feed.c,语义逐项对齐的断言落在 test/host/ui_data/
* (docs/UI设计/UI_数据供给设计说明.md §9.4 一致性测试) */
* (docs/UI设计/UI_数据供给设计.md §9.4 一致性测试) */
#define UI_DATA_YC_N 9u
/* 遥信点数:与 104 点表同序(bit i = 第 i 点),页面名表按点表逐行登记 */
#define UI_DATA_YX_N 33u
@@ -183,7 +183,8 @@ typedef struct {
* 冒充点表事实,主站与屏会按两套语义读同一组位——那正是本仓最忌的静默错。
* 两族字段互不引用,页面各画各的,谁改了谁也不会悄悄改到另一边。
* 字段宽度:8 路 / 4 路各一字节即够,两块 mask/valid 合占 4 B,struct 由 208 B
* 变 212 B(对齐只到 4,无尾部填充);写侧共用缓冲 s_scr 因此 +4 B(宿主机单测
* 变 216 B(帧内 uint64_t 位图成员使整帧按 8 对齐,尾部再补 4 B);写侧共用
* 缓冲 s_scr 因此 +8 B(宿主机单测
* TC-UIDATA-021g 钉尺寸,改字段要同步那里) */
uint8_t dio_di_mask; /* 8 路开入去抖后状态:bit n = 通道 n 合(1)。
* 来源 = defaultTask 的 DI 去抖快照
@@ -213,7 +214,7 @@ typedef struct {
* 参数快照:40 项定值 Q10 原值 + 封存态
* 存 Q10 而非 float 的理由:定值是整表校验和覆盖的定点值,快照存浮点会引入
* "显示值与校验和口径不一致"的二义性(Q10 → 显示小数位换算属表现层,见
* docs/UI设计/UI_数据供给设计说明.md §8)
* docs/UI设计/UI_数据供给设计.md §8)
*/
typedef struct {
uint32_t seq; /* 发布序号(本层盖章) */
@@ -240,7 +241,7 @@ typedef struct {
/*
* 装置信息快照(通道划分理由见本头文件头,契约侧同一条登记在
* docs/UI设计/UI_数据供给设计说明.md §4.4——同一事实只在一处详述)
* docs/UI设计/UI_数据供给设计.md §4.4——同一事实只在一处详述)
* 写侧随 rt 同节拍发布(内容基本不变,代价是一次约 90 B 拷贝)
*/
typedef struct {
@@ -302,7 +303,7 @@ int ui_data_publish_rt(const ui_data_rt_t *a_snap);
* 入口参数:a_snap - 源帧 const ui_data_par_t *
* 返回值:0 - 已发布;-1 - 参数无效(NULL,存量不动) int
* 限定条件:同上;发布节拍 = 定值校验和变化才发
* (docs/UI设计/UI_数据供给设计说明.md §5.2)
* (docs/UI设计/UI_数据供给设计.md §5.2)
*/
int ui_data_publish_par(const ui_data_par_t *a_snap);
@@ -370,7 +371,7 @@ uint32_t ui_data_info_seq(void);
/* ── 写路径:定值整定请求(页面只投递,执行在 App 侧)───────────────────── */
/*
* 请求队列深度(契约 docs/UI设计/UI_数据供给设计说明.md §6.2 定死 4)
* 请求队列深度(契约 docs/UI设计/UI_数据供给设计.md §6.2 定死 4)
* 为什么是 4 不是 1:整定页"保存"是用户按键,一条请求要等 App 侧 drain 才落定;
* 深度 1 会让连按两次保存把第二条判成"忙",而 4 格 = 本层 .bss 多
* 4 × sizeof(ui_data_param_req_t)(168 B/格,主机单测 TC-UIDATA-016 钉住尺寸,
@@ -461,7 +462,7 @@ int ui_data_param_request(const ui_data_param_req_t *a_req);
* 限定条件:无(只读单字,任意上下文安全)
* 函数说明:ERR_TIMEOUT(契约 §6.3 的"3 s 未取走")本层**不产出**——uiTask 每
* 10 ms 就 drain 一次,真出现"永不落定"说明 App 侧没接线,属装配缺陷;
* 页面若要兜底可自己按投递时刻计时(docs/UI设计/UI_数据供给设计说明.md
* 页面若要兜底可自己按投递时刻计时(docs/UI设计/UI_数据供给设计.md
* §6.3 已把它列为页面本地可选项)
*/
int ui_data_param_state(void);
@@ -970,7 +971,7 @@ int ui_data_comm_set(uint8_t a_idx, uint32_t a_val);
*/
uint8_t ui_data_comm_pending(void);
/* ── 通道六:故障录波(wave)────────────────────────────────────────────────
/* ── 通道七:故障录波(wave)────────────────────────────────────────────────
* 页面零 App include、零存储触点:录波执行侧(触发投递 / 段索引 / 段头字段 /
* 窗口码值与峰值 mV)全部经本注入表进来,真实现见 App/task/ui_task.c 的
* s_wave_ops;PC 模拟器绑同一形状的假件(simulator/main.c)。取数口径的
+1 -1
View File
@@ -41,7 +41,7 @@ void ui_w_records_bind(const ui_rec_reader_t *a_reader) {
* "清除"之后条数归零就是它唯一的真反馈),而 reader 是本组件私有
* 的注入表;不开放一个只读入口,页面就只能自己去注第二份 reader,
* 那正好把 task-6 刚削掉的分层反向边又接回来(口径见
* docs/UI设计/UI_数据供给设计说明.md §7.2/§7.3)。
* docs/UI设计/UI_数据供给设计.md §7.2/§7.3)。
* 本函数不带行缓存:缓存属于"某一条记录的字段",与条数无关
*/
uint16_t ui_w_records_count_of(uint8_t a_log_id) {
+1 -1
View File
@@ -113,7 +113,7 @@ void ui_w_records_bind(const ui_rec_reader_t *a_reader);
* 限定条件:uiTask 上下文(绘制/按键链)
* 函数说明:reader 是本组件私有的注入表,不开放只读入口的话,想按行显示条数的
* 页面只能自己去注第二份 reader——那正好把 task-6 刚削掉的分层反向边
* 接回来(口径 docs/UI设计/UI_数据供给设计说明.md §7.2/§7.3);
* 接回来(口径 docs/UI设计/UI_数据供给设计.md §7.2/§7.3);
* 本函数不带行缓存(缓存属于"某条记录的字段",与条数无关)
*/
uint16_t ui_w_records_count_of(uint8_t a_log_id);
+1 -1
View File
@@ -13,7 +13,7 @@
* ——id 与 App/algo/prot_set.h 枚举序的一致性由 test/host/ui_data 的主机单测
* 在两侧头文件同时可见的地方钉住(BSP 侧看不到 App 头,物理上无法自证)
* 值语义:q10[i] = 工程量 × 1024(App/app/ui_data_feed.c 只搬原值不换算,换算属表现层,
* docs/UI设计/UI_数据供给设计说明.md §8),本模块按行表 decimals 换算成
* docs/UI设计/UI_数据供给设计.md §8),本模块按行表 decimals 换算成
* "工程量 × 10^decimals" 交给 ui_w_setlist(其值通道契约)
* 适用平台:STM32F407ZGTx / PC 模拟器(共用源码)
* 作者:王建锋
+1 -1
View File
@@ -10,7 +10,7 @@
* 显示名映射(本组件私有,属表现层):事件类型与元件都按**不透明编号**入参,
* 编号值与 App 侧枚举逐项相等(一致性由 test/host/ui_data 主机单测
* 现场核对,不是照抄文档转述);文案是显示规格,不进快照也不进 App 层
* (口径 docs/UI设计/UI_数据供给设计说明.md §8)
* (口径 docs/UI设计/UI_数据供给设计.md §8)
* 适用范围:Drivers/BSP/UI(分层方向由 scripts/check_layer_deps.py 守护)
* 说明:reader 注入点已备好但**两端均未绑定**——SOE 文件的只读 API
* (条数 / 按序号读一条)尚未在落盘侧提供,绑定与页面接线属道E 后续