/* * 模块名称:保护定值模型(P1,定值校验和 载体) * 模块功能:保护定值的 RAM 模型——编号 / 范围 / 默认值 / 校验和自检, * 以及 B7 定值持久化的**纯逻辑层**(blob 序列化/解析 + 原子装载)。 * 文件读写胶水在 App/cfg/prot_set_store.c(MCU 端)。 * * 设计口径(docs/算法/继电保护功能复现规划.md §5): * - 定点存储:Q10(×1024),与参考系统定点系数 2^10 一致(§5.3); * - 协议地址(IEC 60870-5-104 IOA)**不在本模块**:唯一真源是 * App/iec60870/104/iec104_dtu_table.c 的 iec104_dtu_protection_mapping() * (s_consumer_map[],17 项,含 scale),本结构不存地址。 * 历史:曾按参考 g_tCommSetParaTab(Comm/Pub/Const_CommSetPara.c)给每项 * 拟定协议地址(基址 0x8820),2026-11-19 与点表逐条比对发现 17 个消费者里 * 13 个指向了完全不同的功能(例 0x8841 语义是 OC1 跳闸投退、拟定地址却写 * 0x8857 = 检合环投退),故整个字段删除,不再维护第二真源; * - 校验和(定值校验和):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 /* size_t(批量接口) */ #include /* 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 数组序 = 校验和覆盖序,只增不删不改序)。 * * ⚠ 本枚举只表达语义,**不存协议地址**:104 可寻址项的 IOA 唯一真源是 * iec104_dtu_protection_mapping() 桥表;历史上按参考 g_tCommSetParaTab * 拟定的逐项地址(0x8856 等)已被证明 13/17 与点表语义冲突,2026-11-19 * 整体删除,勿从旧版本/历史日志把这些数字搬回来。 */ typedef enum { /* --- 三段式相间过流(A 相):投退/跳闸投退/电流/延时 --- */ PS_OC1_EN = 0, /* Ⅰ段投退 */ PS_OC1_TRIP, /* Ⅰ段跳闸投退(0 告警 / 1 跳闸) */ PS_OC1_CUR, /* Ⅰ段电流定值(A,二次值) */ PS_OC1_DLY, /* Ⅰ段延时(ms) */ PS_OC2_EN, /* Ⅱ段投退 */ PS_OC2_TRIP, /* Ⅱ段跳闸投退 */ PS_OC2_CUR, /* Ⅱ段电流定值(A,二次值) */ PS_OC2_DLY, /* Ⅱ段延时(ms) */ PS_OC3_EN, /* Ⅲ段投退 */ PS_OC3_TRIP, /* Ⅲ段跳闸投退 */ PS_OC3_CUR, /* Ⅲ段电流定值(A,二次值) */ PS_OC3_DLY, /* Ⅲ段延时(ms) */ /* --- 过负荷(A 相) --- */ PS_OL_EN, /* 过负荷投退 */ PS_OL_TRIP, /* 过负荷跳闸投退 */ PS_OL_CUR, /* 过负荷电流定值(A,二次值) */ PS_OL_DLY, /* 过负荷延时(ms) */ /* --- 过压 / 欠压(UA) --- */ PS_OV_EN, /* 本地投退(参考告警类无独立投退,V0.1 补) */ PS_OV_VOL, /* 过电压门限(V,二次值) */ PS_OV_DLY, /* 过电压延时(ms) */ PS_UV_EN, /* 本地投退 */ PS_UV_VOL, /* 低电压门限(V,二次值) */ PS_UV_DLY, /* 低电压延时(ms) */ /* --- 零序过压(UN) --- */ PS_3U0_EN, /* 3U0 投退 */ PS_3U0_VOL, /* 3U0 定值(V,二次值) */ PS_3U0_DLY, /* 3U0 延时(ms) */ /* --- 公共 --- */ PS_RET_OVER, /* 过量返回系数(返回门槛 = 定值 × 系数,<1) */ PS_RET_UNDER, /* 欠量返回系数(返回门槛 = 定值 × 系数,>1) */ PS_PT_PRI, /* PT 一次额定(V) */ PS_PT_SEC, /* PT 二次额定(V) */ PS_CT_PRI, /* CT 一次额定(A) */ PS_CT_SEC, /* CT 二次额定(A) */ /* --- 全局软压板(B7):104 YK12 两段式投退;0 = 保护退出服务 --- */ PS_GLOBAL_EN, /* 本地项(经 YK12 写、C_RD 不可读) */ /* --- 过频 / 低频(B8):投退/动作频率/延时 + 各自返回系数 --- * ⚠ 本地项判定:OF/UF 八项不在 iec104_dtu_protection_mapping() 桥表内, * 故 104 C_SE / C_RD 不可寻址;本模块不再持有地址概念。 * ⚠ 默认值/范围为**拟定**(同全表口径,规划 §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 值区)。 * ⚠ 协议地址的唯一真源是 iec104_dtu_protection_mapping(),本结构不存地址。 */ typedef struct { 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 */