Files
STM32F4-Base/App/algo/prot_set.h
T
wandering1 7d1db02164 perf(iec104): 参数区按 17 项真实消费者收窄并接上真实定值模型
104 协议侧参数通道此前镜像了厂商点表的全部 430 条参数(697 槽),
但其中 413 条在本设备上没有任何消费者——104 与设备侧真实定值模型
prot_set 之间零调用,主站改定值只落在无人读的 RAM 镜像里,保护功能
毫无感知。本次按"严格按消费者收窄"口径收口:

可见性以 iec104_dtu_protection_mapping() 语义桥表为唯一判据,只放行
三段过流投退/定值/延时(9 项)、低压与过压定值/延时(4 项)、PT 与
CT 一次/二次额定(4 项)。其余参数在位表枚举层即不可见,主站读取
得到 COT=47 + P/N=1 的显式否定确认,不静默丢弃。values[697]→values[53]、
staged[264]→staged[17],并删除生成式 iec104_source_ranks.h。

桥表接真实源:iec104_serv 的 parameter_read/apply 从 NULL 改为直读
prot_set 与整批原子提交,Q10 量化后一次事务落地,持久化仍由
defaultTask 的脏标志闭环负责。

prot_set 因此出现两个运行时写者(netTask 的 104 与 uiTask 的本地整
定),原"写者靠启动时序串行"的约定失效。加入写事务互斥与 seqlock
序号:四个写入口全部进锁,校验与提前返回一律在 enter 之前;序号卡
奇数连续 8 拍即判保护闭锁,避免自检被永久跳过而静默失去防篡改能力。
锁的安装在 defaultTask 的存储 bring-up 阶段,不在 app_main_init——
后者早于 osKernelInitialize,内核启动前禁止任何 RTOS 创建类 API。

实测:RW_IRAM1 117,304→113,720 B(−3,584 B,89.50%→86.76%);
ER_IROM1 413,392→411,668 B(−1,724 B);iec104_source.o 5,656→2,056 B;
prot_set.o 344→352 B(+8 B,写事务序号与锁句柄)。Keil 构建 0 错误
0 警告;主机侧 prot_set 175/175、iec104_dtu 7/7;真实 TCP 验收
13/13;暂存口径门禁 18 项全通过。

已知边界:模拟器不链接 iec104_serv.c,TCP 验收不覆盖 prot_set 绑定,
板端需实机确认主站写入能反映到本地定值页;17 项中 15 项的出厂默认
值与点表字面量不同,主站读到的是真实模型的值;绑定真实源后定值区
切换一律拒绝(单套活跃值无原子整区事务)。
2026-11-19 15:48:21 +08:00

266 lines
15 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.
/*
* 模块名称:保护定值模型(P1,定值校验和 载体)
* 模块功能:保护定值的 RAM 模型——编号 / 通讯地址 / 范围 / 默认值 / 校验和自检,
* 以及 B7 定值持久化的**纯逻辑层**(blob 序列化/解析 + 原子装载)。
* 文件读写胶水在 App/cfg/prot_set_store.c(MCU 端)。
*
* 设计口径(docs/算法/继电保护功能复现规划.md §5):
* - 定点存储:Q10(×1024),与参考系统定点系数 2^10 一致(§5.3);
* - 通讯地址:与参考 g_tCommSetParaTab(Comm/Pub/Const_CommSetPara.c)逐项对齐,
* 基址 0x8820(=34848);告警类沿用运行参数段 0x8027/0x8029;
* - 校验和(定值校验和):sum32 正码 + 反码成对封存(参考 tagPRS 的
* dwTagSum/dwTagSumN 模式),selfcheck 失配 → 置闭锁;
* - ⚠ 默认值/范围为**拟定值**:参考 EEPROM 出厂默认表未在本仓库,
* 待对照后逐项修订(规划 §10.3 待补项);范围先按 DTU 馈线典型量级。
*
* 线程约定(多写者 + 写事务锁):
* 装载(init/store_parse)在 defaultTask(存储 bring-up);落盘在 defaultTask
* (配置引擎属主);读在保护消费者任务(快照值原子,读接口一律不加锁)。
* 运行时写者有两个——netTask(104 定值下发,走 apply_batch / set_sealed)与
* uiTask(本地整定,经 ui_data 注入的 set_sealed)。
* 双缓冲 + 单字交换只保证"读侧看到完整快照",**不保证写者之间不交错**:一方
* 已写封存对、尚未交换活跃区时被另一方抢占,后者再交换一次,最终值区与封存
* 对失配 → selfcheck 判"定值被非法改写" → 整台保护闭锁。所以写入口统一走
* 写事务:可选 enter/exit 钩子(prot_set_lock_install 安装,板端接 RTOS 互斥
* 量;模拟器与主机单测不装 = 单写者假设)包住"影子区改值 + 封存 + 交换",
* 同时把提交序号置奇/回偶,selfcheck 借它识别"提交进行中"而不误判失配。
* 跳过本轮是**有界**的:连撞 8 拍仍是奇数 → 判写者已死 → 闭锁(fail-safe,
* 否则一条"锁内提前返回"的 bug 就会让防篡改自检永久静默失效)。
* 本模块只持有两个函数指针,不 include 任何 RTOS/HAL 头——纯逻辑三方编译
* (固件 / 模拟器 / 主机单测)不受影响。
*
* 创建日期:2026-10-11
*/
#ifndef PROT_SET_H
#define PROT_SET_H
#include <stddef.h> /* size_t(批量接口) */
#include <stdint.h>
/* Q10 定点:工程量 × 1024(与参考 2^10 口径一致)。
* 必须写成单精度:×/÷1024 只是 2^10 指数平移,float 与 double 的结果逐位相同
* (宏里 42 个字面量 + int32 全域往返均已穷举核对),而写成 double 会把
* MicroLIB 的软浮点拉进镜像——F407 只有单精度 FPU,本工程的保护判据每
* 20 ms 节拍每元件要读三次定值(见 prot_elm_run),软件双精度纯属白烧。 */
#define PROT_SET_Q10(v) ((int32_t)((float)(v) * 1024.0f))
#define PROT_SET_FROM_Q10(v) ((float)(v) / 1024.0f)
/* 定值项编号(枚举序 = RAM 数组序 = 校验和覆盖序,只增不删不改序) */
typedef enum {
/* --- 三段式相间过流(A 相):投退/跳闸投退/电流/延时 --- */
PS_OC1_EN = 0, /* 0x8856 Ⅰ段投退 */
PS_OC1_TRIP, /* 0x8857 Ⅰ段跳闸投退(0 告警 / 1 跳闸) */
PS_OC1_CUR, /* 0x8858 Ⅰ段电流定值(A,二次值) */
PS_OC1_DLY, /* 0x8859 Ⅰ段延时(ms) */
PS_OC2_EN, /* 0x885A */
PS_OC2_TRIP, /* 0x885B */
PS_OC2_CUR, /* 0x885C */
PS_OC2_DLY, /* 0x885D */
PS_OC3_EN, /* 0x885E */
PS_OC3_TRIP, /* 0x885F */
PS_OC3_CUR, /* 0x8860 */
PS_OC3_DLY, /* 0x8861 */
/* --- 过负荷(A 相) --- */
PS_OL_EN, /* 0x8871 */
PS_OL_TRIP, /* 0x8872 */
PS_OL_CUR, /* 0x8873 */
PS_OL_DLY, /* 0x8874 */
/* --- 过压 / 欠压(UA;沿用参考告警段 0x8029/0x8027) --- */
PS_OV_EN, /* 本地投退(参考告警类无独立投退,V0.1 补) */
PS_OV_VOL, /* 0x8029 过电压门限(V,二次值) */
PS_OV_DLY, /* 0x802A 过电压延时(ms) */
PS_UV_EN, /* 本地投退 */
PS_UV_VOL, /* 0x8027 低电压门限(V,二次值) */
PS_UV_DLY, /* 0x8028 低电压延时(ms) */
/* --- 零序过压(UN) --- */
PS_3U0_EN, /* 0x888E */
PS_3U0_VOL, /* 0x888F 3U0 定值(V,二次值) */
PS_3U0_DLY, /* 0x8890 延时(ms) */
/* --- 公共 --- */
PS_RET_OVER, /* 过量返回系数(返回门槛 = 定值 × 系数,<1) */
PS_RET_UNDER, /* 欠量返回系数(返回门槛 = 定值 × 系数,>1) */
PS_PT_PRI, /* 0x8820 PT 一次额定(V) */
PS_PT_SEC, /* 0x8821 PT 二次额定(V) */
PS_CT_PRI, /* 0x8825 CT 一次额定(A) */
PS_CT_SEC, /* 0x8826 CT 二次额定(A) */
/* --- 全局软压板(B7):104 YK12 两段式投退;0 = 保护退出服务 --- */
PS_GLOBAL_EN, /* 本地项(无通讯地址,经 YK12 写、C_RD 不可读) */
/* --- 过频 / 低频(B8):投退/动作频率/延时 + 各自返回系数 ---
* ⚠ 通讯地址:参考 g_tCommSetParaTab 的保护定值段(0x8820~0x8882)
* 含"低压/低频"类目(规划 §5.1),但 OF/UF 的**逐项地址不在本仓库**
* (参考 Comm 源文件未随仓库提供)→ 按"找不到对应即本地项"规则全部
* comm_addr=0 登记本地项(104 C_SE 不可寻址),待对照参考表后补。
* ⚠ 默认值/范围为**拟定**(同全表口径,规划 §5.4 落实进度注)。 */
PS_OF_EN, /* 过频投退(本地) */
PS_OF_HZ, /* 过频动作频率(Hz) */
PS_OF_DLY, /* 过频延时(ms) */
PS_UF_EN, /* 低频投退(本地) */
PS_UF_HZ, /* 低频动作频率(Hz) */
PS_UF_DLY, /* 低频延时(ms) */
PS_RET_OF, /* 过频返回系数(返回门槛 = 定值 × 系数,<1;本地) */
PS_RET_UF, /* 低频返回系数(返回门槛 = 定值 × 系数,>1;本地) */
PS_ID_COUNT
} prot_set_id_t;
/* 定值项元数据(ROM 常量表,校验和自检不覆盖它——只覆盖 RAM 值区) */
typedef struct {
uint16_t comm_addr; /* 通讯信息体地址(0 = 本地项,不上送) */
uint8_t is_ctl; /* 1 = 投退/枚举项(0/1),0 = 模拟量项 */
int32_t def; /* 默认值(Q10;投退项为 0/1 的 Q10) */
int32_t min; /* 下限(Q10) */
int32_t max; /* 上限(Q10) */
} prot_set_meta_t;
extern const prot_set_meta_t g_prot_set_meta[PS_ID_COUNT];
/*
* 函数功能:装载出厂默认值并封存校验和(幂等,内核启动前可调)
*/
void prot_set_init(void);
/*
* 函数功能:整表装载外部值(P4 起由 cfg_file 定值段调用),逐项范围校验
* 入口参数:vals - PS_ID_COUNT 个 Q10 值
* 返 回 值:0 全部合法(已装载并封存)/ -1 存在越界项(**整表不装载**,
* 返回前可经 prot_set_bad_mask() 取越界位图)
*/
int prot_set_load_raw(const int32_t *vals);
/* 越界位图(bit i = 第 i 项越界)。
*
* ⚠ 契约(调用方必读):本函数返回的位图**只反映整表装载/解析**
* (prot_set_load_raw / prot_set_store_parse)的越界结果,
* 最后一次整表操作失败后有效,直到下一次整表操作或 prot_set_init 覆写。
* **不随单项写入(prot_set_set / prot_set_set_sealed)或批量写入
* (prot_set_apply_batch)变化**:增量写入的失败一律以函数返回 -1 表达,
* 既不置位也不清位。
* 推论:一笔成功的批量提交**不会**清掉历史上整表装载留下的越界位;
* 反过来,一笔失败的批量提交也**不会**在位图上留下痕迹。拿位图反显
* "刚才那批哪几项越界"是误用——请用 apply_batch 的返回值。
* B8:项数 32→40,位图随项数扩为 64 位;板端闭锁走 prot_set_locked()。 */
uint64_t prot_set_bad_mask(void);
/*
* 函数功能:单项写入(范围校验;**不自动重封校验和**——批量改完必须
* 显式 prot_set_seal(),否则 selfcheck 判"定值被非法改写")
* 返 回 值:0 / -1 越界拒写
*/
int prot_set_set(prot_set_id_t id, int32_t q10);
int32_t prot_set_get(prot_set_id_t id); /* Q10 原值 */
float prot_set_get_f(prot_set_id_t id); /* 工程量浮点 */
uint8_t prot_set_get_ctl(prot_set_id_t id); /* 投退项:!=0 视为投入 */
/* 校验和(定值校验和):sum32 覆盖 RAM 值区;seal 封存正/反码对 */
uint32_t prot_set_checksum(void);
void prot_set_seal(void);
/* 自检:重算并与封存值比对,失配 → 置闭锁并返回 -1(已闭锁也返回 -1)。
* 提交进行中(写者正在改值区/发封存对)撞见的中间态**只跳过本轮、不判失配**;
* 但跳过是有界的:连续撞见"提交进行中"达 8 拍(约 160 ms)即视为写者已死,
* 置闭锁并返回 -1(fail-safe:宁可保护停走,不可带不可信定值判据)。
* 解锁的唯一合法路径是 prot_set_seal()(或 prot_set_init() 重装)。 */
int prot_set_selfcheck(void);
uint8_t prot_set_locked(void);
/*
* 函数功能:单项**原子**写入+封存(B7,收口 B5 竞态窗口)
* 入口参数:id - 定值项编号;q10 - Q10 定点值
* 返 回 值:0 / -1 越界或非法编号拒写(原值不动)
* 函数说明:影子缓冲拷贝 → 改影子 → 重封校验和 → 单字交换活跃区。
* selfcheck 永远看到"值区与封存一致"的完整快照,不存在
* "已改值未封存"中间态(区别于 prot_set_set+seal 的批处理路径,
* 两条路径不得在一次批处理中途交错)。置脏标志(待持久化)。
*/
int prot_set_set_sealed(prot_set_id_t id, int32_t q10);
/* ---------------- 批量读写(104 定值下发:PRE 预检 + SOL 原子提交) ----------------
* 协议一次改 1..17 项,两段式:第一段只校验(不落任何状态),第二段整批提交。
* 与单项 set_sealed 同一原子口径:任一项非法则整批一项都不改。
*/
/* 一批定值变更(Q10 工程量)。同一批内 id 不得重复。 */
typedef struct {
prot_set_id_t id;
int32_t q10;
} prot_set_change_t;
/* 单批上限 = 整表 40 项(算法侧上限)。超过上限返回 -1,不做任何改动。
* ⚠ 与协议上限的关系:40 是**本模型能接受的最大批量**(整表就 40 项);
* IEC 60870-5-104 参数区另有 **17 项**的消费者上限,那是协议/调用方的
* 约束,由调用方自己拦——本层不代拦。所以 18 项的一批在这里是合法的,
* 接线方若想守 17 项,必须在上层先判,别指望这里替它拒。 */
#define PROT_SET_BATCH_MAX ((size_t)PS_ID_COUNT)
/*
* 函数功能:读一批定值当前值(Q10 工程量)
* 入口参数:ids - 编号数组;n - 个数;out - 输出数组(out[i] 对应 ids[i])
* 返 回 值:0 成功 / -1 参数非法(空指针、n 为 0、n 超过上限、任一号越界)
* 限定条件:任意上下文安全——双缓冲保证读侧只看到完整快照,不需要持锁
*/
int prot_set_read_batch(const prot_set_id_t *ids, size_t n, int32_t *out);
/*
* 函数功能:原子写入一批定值
* 入口参数:changes - 变更数组;n - 个数;validate_only - 非 0 只校验
* 返 回 值:0 整批合法(validate_only 时仅为"预检通过")/ -1 有非法项
* 限定条件:两段式第一段(validate_only 非 0)**零副作用**——不置脏、不动值区、
* 不动闭锁位、不进写事务锁;第二段(validate_only 为 0)先整批校验,
* 任一项非法即一字未改地返回,全部合法才提交并置脏。
* 函数说明:失败条件 = changes 为空、n 为 0、n 超上限、任一号越界、任一值越出
* 该项 min/max、同批 id 重复。提交在写事务锁内完成(见下方钩子)。
* 返 回 值补充(与 prot_set_bad_mask 的关系):**任何失败都不会反映到位图上**
* ——成功也不清、失败也不置。要定位是哪一项不合法,请在调用前自己
* 对照 g_prot_set_meta[id] 的 min/max 逐项查,或改用两段式第一段
* 预检后自行分组重试;位图上看到的内容属于更早的整表装载。
*/
int prot_set_apply_batch(const prot_set_change_t *changes, size_t n, int validate_only);
/* 写事务锁钩子(可选)。未安装 = 调用方保证单写者(模拟器 / 主机单测即如此)。
* enter/exit 必须成对;enter 允许阻塞,不得用关中断实现。 */
typedef struct {
void (*enter)(void);
void (*exit)(void);
} prot_set_lock_t;
/*
* 函数功能:安装/卸载写事务锁
* 入口参数:lock - 钩子(传 NULL = 卸载,退回单写者假设)
* 返 回 值:无
* 限定条件:应在任何写者启动前安装;本函数本身不加锁、不可重入。
* 钩子只在"值区提交"这段临界区里被调用,读接口永不进入。
*/
void prot_set_lock_install(const prot_set_lock_t *lock);
/* 脏标志(存在未落盘的定值改动):set_sealed 置位;load/init 不置 */
uint8_t prot_set_dirty_peek(void); /* 非消费(生产者用它通知属主任务) */
uint8_t prot_set_dirty_take(void); /* 消费(属主任务落盘前取) */
void prot_set_dirty_mark(void); /* 写盘失败回置(等下轮重试) */
/* ---------------- 持久化 blob(B7;纯逻辑,主机可单测) ----------------
* 格式(小端):magic 'PSET'(4B) + version u16 + count u16
* + values u32×count + sum32 u32 + ~sum32 u32
* 版本 2(B8:定值表 32→40 项,OF/UF 尾追加);count 必须等于 PS_ID_COUNT
* (定值表增项 → 旧 blob 整体作废,编号不回收但格式换代,宁可用出厂默认
* 也不半装载)。ver 1 旧档在 parse 即被版本闸拒绝 → 出厂默认 + 日志
* (措辞 = "version change",非 CORRUPT,见 prot_set_store/default_task)。 */
#define PROT_SET_BLOB_MAGIC 0x50534554uL /* 字节序 P,S,E,T */
#define PROT_SET_BLOB_VER 2u
#define PROT_SET_BLOB_HDR_SZ 8u /* magic(4)+ver(2)+cnt(2) */
#define PROT_SET_BLOB_SZ (PROT_SET_BLOB_HDR_SZ + 4u * (uint32_t)PS_ID_COUNT + 8u)
/*
* 函数功能:把当前值区序列化为 blob(校验和按值区现算,不依赖封存值)
* 返 回 值:0 / -1 缓冲不足或参数非法;*p_len 输出实际长度
*/
int prot_set_store_serialize(uint8_t *p_buf, uint32_t cap, uint32_t *p_len);
/*
* 函数功能:解析 blob 并**整表原子**装载(all-or-nothing)
* 入口参数:p_buf/len - blob 字节流
* 返 回 值:0 已装载并封存 / -1 拒绝(magic/版本/长度/校验对不符或
* 任一项越界 → 值区一字不动;越界项经 prot_set_bad_mask() 指认)
*/
int prot_set_store_parse(const uint8_t *p_buf, uint32_t len);
#endif /* PROT_SET_H */