Files
STM32F4-Base/App/algo/run_par.h
T
wandering1 84c5a5d92a fix(docs): 修 16 处指向已删文件的历史指针,别让读者照着找空门
上一笔改名把 App/protocol/iec104 搬到 App/iec60870/104_port 时,机械
文本替换把「讲一个已经删掉的文件当初做什么」的叙述也一起改了:

  iec104_pts.c  / iec104_asdu.c  / iec104_link.c

这三个文件在 90cc9a7d 里就删了(旧自研协议层整体退役),
App/iec60870/104_port/ 下从来没有它们。于是文档与注释里出现了一批
「新路径 + 旧行为」的混合描述,读者按图索骥只会撞空。

按两类分别处理,共 11 个文件(只有注释与 Markdown,零代码行):

一、讲历史事实的 -> 写回当时真实的旧名,就近标「已删除」
  App/task/ui_task.c            SYSLOG_OPER 那条原写入点
  App/algo/run_par.h            104 消费侧每拍读取
  Drivers/BSP/UI/ui_data.h      YX_DP_N / 遥控记录两条
  Drivers/BSP/UI/ui_page_oper.c 操作页写入点
  Drivers/BSP/UI/ui_page_reset.c 复归串与远端那条刻意不同
  Drivers/BSP/UI/ui_page_yk.c   遥控页写入点
  Drivers/BSP/UI/ui_data.c      CP56 正反两套实现同族
  test/host/ui_data/ui_data_test.c  两处历史注释
  simulator/main.c              双点位图固定帧的来历
  App/log/README.md             oper.log / yk.log 生产者
  docs/UI设计/UI_数据供给设计.md
  docs/UI设计/页面扩充详细方案.md
  docs/产品需求/产品需求设计文档.md  链路层与点表实现指针

二、讲现在仍活着的接缝的 -> 指向真实存在的文件,并 test -f 过
  App/algo/run_par.h:23  死区分流现由 iec104_dtu_table.c +
                         iec104_source.c 承担
  App/algo/meas.h        数值口径改指 common/IEC60870_InformationObjects.h
                         的 IEC60870_ASDU_QUALITY_*;顺带修掉同句里两个
                         既有错:引用了不存在的 test/host/iec104/,
                         且 104 当前消费点是 iec104_serv.c 的 s_measure()
  test/host/bench/iec104/iec104_master.py  常量与帧头说明改指
                         common/IEC60870_Asdu.c 与 104/IEC104_Types.h

App/task/iec104_serv.c 单独说明:文件还在但 s_clock_sync() 已随新契约
消失(grep RC=1),所以写「同日重写后不再投递」,不写「已删除」。

验证:grep 新假路径零命中;旧真名 14 处全部带删除标注;check_bom_drift
RC=0(6 个带 BOM 文件按原始字节补回,未过文本编解码);check_mojibake
RC=0;check_coding_standard 逐文件 RC=0;doc-links 308 篇 / 30 处问题
全部仍在 IEC60870-Slave 供应商快照内,非 vendor 计数仍为 0。
2026-11-18 14:32:40 +08:00

222 lines
14 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.
/*
* 模块名称:运行参数段(全周傅氏相量/保护判据整定层,「数据可信」这一项)
* 模块功能:遥测死区(9 点)与通道标定系数覆盖(k/b 各 8 路)的**单一真源**:
* - 死区 = 本模块 int32 毫单位 RAM 副本(注册进 cfg 引擎 [run_par] 段,
* 工厂默认 = 「数据可信」下游常数按工程量重定后的额定 0.5 % 档),原 104 消费侧
* (旧 App/protocol/iec104/iec104_pts.c,该文件 2026-11-18 随骨架迁 MCU 删除;
* 当前 run_par_deadband() 的调用方只剩装配层 App/app/ui_data_feed.c,104 侧无调用方)
* 每拍实时读取——无投递、无缓存
* 副本(104 改读快照曾在 pts 侧留运行时副本 s_yc_db,运行参数段落地后收编于此,
* 双源必打架);
* - 系数覆盖 = **直通 adc_cal_set() / adc_cal_set_ratio()**
* ([adc_cal]/[adc_cal_ofs]/[adc_cal_sec] 是系数与变比的
* 唯一真源,标定落盘与整定入口已定;本模块只加 104 地址映射 + 落盘请求,不另存
* 一份系数——同 D1 裁"两处判断必打架"逻辑)。
* 104 地址映射(docs/算法/继电保护功能复现规划.md §5.1 运行参数类
* 0x8020H~0x8058H;逐项表原文"待补"(参考项目 CommPara_ConfigTable
* 不在仓),本表即运行参数段的落实,送检点表若另给权威地址只改常量段:
* 0x8030~0x8038 = 死区 UA/UB/UC/UN/IA/IB/IC/IN/FREQ(工程量 V/A/Hz);
* 0x8040~0x8047 = k 覆盖(µV/码);0x8048~0x804F = b 覆盖(码值,可负);
* 0x8050~0x8057 = 变比 r 覆盖(比值,无单位;0 = 本路不折算,见
* run_par_cal_r_set 的说明);
* 其余留白(未启用类别),**0x8027~0x802A 属 prot_set 告警段**,本表
* 永不让位(两表按精确地址分流,见旧 iec104_pts.c 的 set 路由;
* 该文件 2026-11-18 已删除,现行分流在 App/iec60870/104_port/
* iec104_dtu_table.c 与 iec104_source.c)。
* 持久化(B7 prot_set 先例同款):任一写成功 → 脏标志只置不清;
* iec104Task 主循环 peek → 置 SYS_EVT_RUN_PAR_SAVE → defaultTask
* (配置引擎属主)run_par_store_save() 调 cfg_file_save() 整档外科
* 保存(含 [run_par] 与刚被 adc_cal_set()/adc_cal_set_ratio() 改写的
* [adc_cal]/[adc_cal_ofs]/[adc_cal_sec] 副本)→ 成功清脏;
* 失败留脏 = 下轮天然重试。本模块自身零文件 IO
* (属主纪律)。
* ⚠ 三份职责别混(道G task-43 第③项,此前只有意图式陈述):
* - **谁写 RAM**:系数/零点的唯一真源是 adc_cal 的引擎副本,而本模块那两支
* 语义 setter(run_par_cal_k_set / run_par_cal_b_set,task-7 落地)是**唯一
* "写值 + 置脏"成对发生**的入口;任何消费者绕过它们直调 adc_cal_set(),
* 值只进 RAM、脏标志不动 ⇒ 屏上"当前生效"是新的、盘上仍是旧的、重启即丢,
* 且该路径**没有错误返回**。这条形态现在可观测:adc_cal 侧
* set_ok 与落盘水位的差额 > 0,而 run_par_dirty_peek() 恒为 0。
* - **谁落盘 / 什么时机**:只有 defaultTask 的 run_par_store_save()(由
* iec104Task peek 后置的 SYS_EVT_RUN_PAR_SAVE 驱动);本模块零文件 IO。
* - **cfg_file_poll() 不是保存路径**:它的方向是**盘 → RAM 的重载**(外部
* 改档 → 沉降去抖 → 重载),拿它"兜住"未落盘的改值会把 FTP 侧的旧档倒灌
* 回 RAM,比不兜更坏。设计依据见 docs/算法/采集与算法层设计说明.md §10.1。
* 并发契约:引擎副本 int32 对齐字读写在 Cortex-M4 上原子;poll 重载 µs 级窗口
* 为docs/算法/采集与算法层设计说明.md §13.8 明载设计(adc_cal 同款)。写路径 = 104 执行段
* (iec104Task)与引擎读路径互不加锁,勿改成"读侧缓存"(缓存 = 新真源)。
* 纯算法:只用 stdint/stddef/math + cfg_file.h/adc_cal.h 头(注册/直通均为
* 接口级)→ 主机侧可单测(test/host/run_par,链真 cfg 引擎 + 真 adc_cal)。
* 适用平台:STM32F407ZGTx(Cortex-M4F,硬件 FPU)
* 作者:DTU 项目组
* 创建日期:2026-10-25(道D 运行参数段)
* 修改记录:
* v1.0 2026-10-25 DTU 项目组 创建:[run_par] 段 + 104 地址映射 + 直通
* adc_cal + B7 式脏标志落盘请求
* v1.1 2026-10-27 DTU 项目组 道F task-7(遥测整定两页)配套:新增语义
* setter run_par_cal_k_set / run_par_cal_b_set
* (写值 + 置脏成对;104 的 k/b 两支同批改调它,
* 消除两份置脏逻辑)+ 合法域唯一出口
* run_par_db_range() + 系数粗守上限
* RUN_PAR_K_MAX_UV;毫→工程换算收进模块内单点
* s_milli_to_eng()(顺带把 task-43 第①项所需的
* "写值必置脏"这一半满足掉)
* v1.2 2026-10-27 DTU 项目组 道G task-43 第②③项:run_par_store_save() 成功路径
* 给标定层盖一次落盘水位(纯观测回执,不参与判定);
* 本头把"谁写 RAM / 谁落盘 / 什么时机 / poll 不是保存
* 路径"从意图式陈述改成逐条契约
* v1.3 2026-11-11 DTU 项目组 变比维:+run_par_cal_r_set()(0 = 本路不折算)
* + 104 地址 0x8050~0x8057 读写
*/
#ifndef RUN_PAR_H
#define RUN_PAR_H
#include <stdint.h>
#include "adc_cal.h" /* adc_semantic_t:公开语义 setter 的形参类型(同层 algo→algo,方向不逆)*/
#ifdef __cplusplus
extern "C" {
#endif
/* 死区/覆盖点数(死区 = YC 表行数:电气 8 + 频率;覆盖 = 语义电气 8 路) */
#define RUN_PAR_DB_N 9u
#define RUN_PAR_CH_N 8u
/* 系数 k 的**粗守**上限(µV/码):只为挡误写(如把 mV 当 µV 填),不是工况域;
* 真合法带在 adc_cal 执行段裁(µV/码 ×[0.5,2.0]),两层各说各的、互不掩盖。
* 公开它是因为 UI 整定页要给编辑器设上限——上限在这里,就不许页面再抄一份。*/
#define RUN_PAR_K_MAX_UV 1.0e9f
/*
* 函数功能:运行参数初始化——副本置工厂默认 + 注册 [run_par] 段进 cfg 引擎
* 入口参数:无
* 返 回 值:无
* 限定条件:**内核启动前**调用(app_main_init,adc_cal_init 之后);注册必须先
* 于 defaultTask 的 cfg_file_load(FTP 鉴权确立的契约,同 adc_cal 先例);幂等
* 函数说明:注册失败(段名重复/段数超限)打 [ERR] 后继续——工厂默认照常生效,
* 仅文件整定失效(adc_cal_init 同款降级)。
*/
void run_par_init(void);
/*
* 函数功能:读第 idx 路遥测死区(工程量)
* 入口参数:idx - 0..7 = 语义通道序(UA..IN),8 = 频率 uint8_t
* 返 回 值:死区 V / A / Hz;idx 越界返 0.0(调用方按"无死区"保守处理) float
* 限定条件:任意上下文(int32 单字读原子;104 COV 每拍调用)
* 函数说明:毫单位 → 浮点的换算在本模块内也只有一处(run_par.c 的
* s_milli_to_eng(),run_par_deadband 与 run_par_db_range 共用);
* 消费侧一律取本模块给的工程量,不要再各自除 1000。
*/
float run_par_deadband(uint8_t idx);
/*
* 函数功能:写第 idx 路死区(工程量,含范围守卫 + 脏置位)
* 入口参数:idx - 同上 uint8_t;db - 死区工程量(V/A/Hz,≥0) float
* 返 回 值:0 成功;-1 越界/越程/NaN(副本不动) int
* 限定条件:写者两门——**iec104Task**(104 C_SE 执行段)与 **uiTask**(遥测死区页
* 经 ui_data 通道五注入转达,道F task-7 起;ui_data.h 通道五表注:合法域
* 与"写值+置脏"必须原子发生在执行侧)。两门都只写 RAM 副本 + 置脏,
* 落盘统一收敛在 defaultTask(勿在 adcTask 调用;此句为 2026-10-27 措辞
* 收口——原写"UI 若整定需另行走属主路径"是 task-2 期遗留,task-7 已接线)
* 函数说明:合法域按点型分档——电压 0~50 V、电流 0~1 A、频率 0~5 Hz(上限 =
* 额定 × 二档裕量,守卫目的是挡误写不是限工况;见 .c 常量段)。
* 成功即置脏(落盘请求,见文件头持久化契约)。
*/
int run_par_deadband_set(uint8_t idx, float db);
/*
* 函数功能:104 运行参数地址读(C_RD 路由,先于 prot_set 扫描)
* 入口参数:addr - 通讯地址(0x8020~0x8058 段内) uint32_t;out - 工程量浮点
* (死区 V/A/Hz;k 覆盖 µV/码;b 覆盖 码值) float *
* 返 回 值:0 命中并写出;-1 地址不归本段(调用方继续走 prot_set) int
* 限定条件:iec104Task 上下文
* 函数说明:命中集 = 0x8030~0x8038 / 0x8040~0x8047 / 0x8048~0x804F 精确匹配;
* k/b 读回 = adc_cal **当前生效值**(与折算同视图:文件坏值被合法带
* 哨兵回退 ROM 时,回显的就是 ROM——主站看到的即下游实际吃到的)。
*/
int run_par_104_read(uint32_t addr, float *out);
/*
* 函数功能:104 运行参数地址写(C_SE 两段式路由,先于 prot_set 扫描)
* 入口参数:addr - 通讯地址 uint32_t;v - 工程量浮点 float;
* select - 1 = 选择段(只校验不落副本)/ 0 = 执行段 uint8_t
* 返 回 值:0 接受;-1 拒绝(越程/NaN/合法带外/非本段可写地址命中守卫);
* -2 地址不归本段(调用方继续走 prot_set) int
* 限定条件:iec104Task 上下文;执行段成功即置脏
* 函数说明:k/b 覆盖经 adc_cal_set() 合法带哨兵(µV/码 ×[0.5,2.0]、|b|≤8192,
* 越带 -1 → 104 侧 PN 否定确认,adc_cal 不留痕由**其自身**越带 [ERR]
* 机制负责——本模块直通不重复留痕);两段式与 prot_set 定值写同构。
*/
int run_par_104_write(uint32_t addr, float v, uint8_t select);
/*
* 函数功能:写某路系数 k(µV/码)**并在同一函数内置脏**——整定的语义写入口
* 入口参数:sem - 电气语义通道(adc_semantic_t 枚举序) adc_semantic_t;
* k_uv - 系数(µV/码,须 >0 且 <= RUN_PAR_K_MAX_UV) float
* 返回值:0 - RAM 副本已写且已置脏;-1 - 粗守或执行段拒(副本未动、不置脏) int
* 限定条件:整定路径上下文(iec104Task 的 C_SE 执行段;UI 侧由装配层
* App/app/ui_data_feed.c 经 ui_data_yt_ops_t 转进来)。勿在 adcTask 调用
* 函数说明:**写值与置脏成对,不许拆开**(lead 裁②):拆开就等于"屏上已改、
* 盘上永不落、且没有任何错误返回"。因此本模块**不提供**公开的
* mark_dirty——单独调它等于空承诺;零点 b 由本函数 RMW 取当前生效值。
*/
int run_par_cal_k_set(adc_semantic_t sem, float k_uv);
/*
* 函数功能:写某路零点偏移 b(码值)并置脏(与 k 同款语义,粗守 ±1e6 码)
* 入口参数:sem - 电气语义通道 adc_semantic_t;b_codes - 零点(码值) int32_t
* 返回值:0 - 已写并置脏;-1 - 粗守或执行段拒(副本未动、不置脏) int
* 限定条件:同 run_par_cal_k_set()
* 函数说明:k 侧 RMW 取当前生效值;±8192 真带由 adc_cal 执行段裁。消费者 =
* 104 的 0x8048~ 分支(改造后走这里),不是为将来预留的口
*/
int run_par_cal_b_set(adc_semantic_t sem, int32_t b_codes);
/*
* 函数功能:写某路变比 r(比值)**并在同一函数内置脏**(与 k/b 同款语义)
* 入口参数:sem - 电气语义通道 adc_semantic_t
* r - 变比(无单位;**0 = 本路不折算**,否则须落在 1.0 ~ 32767.99) float
* 返回值:0 - 已写并置脏;-1 - 粗守或执行段拒(副本未动、不置脏) int
* 限定条件:同 run_par_cal_k_set()
* 函数说明:**0 是合法入参**,语义 = 「这一路退回引脚电压」——不是清零、不是非法。
* 104 上写 0 就是现场把某路折算关掉的正规手段;写 1.0 反而会留下一个
* 假变比(端子值 = 引脚电压),那是错的事实而不是"关掉"。
*/
int run_par_cal_r_set(adc_semantic_t sem, float r);
/*
* 函数功能:取第 idx 路死区的合法域(工程量)——**合法域的唯一出口**
* 入口参数:idx - 0..8 uint8_t;lo/hi - 输出下限/上限(V/A/Hz) float *
* 返回值:0 - 已写出;-1 - idx 越界或指针空(调用方不得回退成自造默认域) int
* 限定条件:任意上下文(纯常量读)
* 函数说明:存在的唯一理由:UI 整定页要给编辑器设 min/max,而这些上限的真源是
* 本模块的 RUN_PAR_DB_MAX_*;页面抄一份就是第二真源。给的是**粗守域**,
* 真提交仍由与 104 选择段同源的守卫裁,两条路不会漂移到两套数字。
*/
int run_par_db_range(uint8_t idx, float *lo, float *hi);
/*
* 函数功能:落盘脏标志探查(非消费)
* 入口参数:无
* 返 回 值:1 = 有已整定未落盘的改动;0 = 干净 uint8_t
* 限定条件:任意上下文(单字节);iec104_serv 主循环 peek 后投递事件(B7 同款)
*/
uint8_t run_par_dirty_peek(void);
/*
* 函数功能:执行落盘请求(cfg_file_save 整档外科保存 + 成功清脏)
* 入口参数:无
* 返 回 值:0 成功(或无脏可存);-1 写盘失败(脏保持,下轮重试) int
* 限定条件:**defaultTask(配置引擎属主)上下文**,由 SYS_EVT_RUN_PAR_SAVE 驱动
* 函数说明:save 走引擎唯一写闸(超长拒写/原子改名);本函数不清
* 引擎以外模块的脏语义([adc_cal] 副本值已由写路径就位)。
*/
int run_par_store_save(void);
#ifdef __cplusplus
}
#endif
#endif /* RUN_PAR_H */