Files
STM32F4-Base/App/iec60870
wandering1 cb59f1cf47 merge: 合入网络 fd 失效值契约(含 104 目录重构解冲突)
把 dsh-204f318c-38b4 的网络 fd 契约工作流合入主树:NET_FD_INVALID
单一契约 + 静态门禁 + 回归测试 + 全仓审计 + 最小加固。

解冲突与集成修复:
- 5 个数值快照(RAM 文档/tsv/size_attestation/report.json)两侧各自
  过时,取主线重构后结构,合并后用权威 Keil 构建(0/0)重新回填:
  Code=365896 RO=48336 RW=2736 ZI=173104,IRAM1 90.3% / CCM 87.9%。
- iec104_net_mcu.c 的 net_fd 改动随主树 104 目录重构
  App/protocol/ → App/iec60870/ 自动迁移,路径正确。
- net-handle 豁免面从旧路径 App/protocol/iec60870/ 对齐到主树重构后的
  App/iec60870/(大写 IEC104_* 上游代码暂免检,小写 iec104_* 自研
  适配层仍受检),消除 read_socket 布尔标志的误报。

验证:net-handle 0 违规/493 文件 + selftest 42 PASS;size-gate 同码
PASS;mem 双区 <92%;本次 6 文档链接 PASS;主机套件全绿。
预存红项(ioboard_di.c / IEC60870-Slave 第三方文档)不在本次提交。
2026-11-18 22:28:49 +08:00
..

App/iec60870/ — IEC 60870-5-104 协议栈(项目自有)

本目录是本项目的 IEC 60870-5-104(变电站远动通信协议,下文简称「104」)协议栈实现:一边接 主站的 TCP 连接,一边经平台接缝取本站数据。它现在是团队自己的代码,按项目规范维护; 下文每节说明该目录的边界、改动纪律与真正的知识,避免新接手者必须读遍约 5 万行才能动手。

历史出处(一句):仓库根的 IEC60870-Slave/ 是原始第三方快照,保留作独立验证基线; 本目录代码已于 2026-11-18 收编为项目自有,不再做逐字节保真校验。

1. 目录结构

接手先看这张表:它回答「某个功能该改哪个目录」。

子目录 职责 详情
common/ 与传输无关的协议数据面:ASDU(应用服务数据单元)编解码、信息对象、时间表示,以及 101/104 共用的子站发送接口抽象 common/README.md
104/ APCI(应用规约控制信息)传输层 + 业务状态机 + 平台适配与装配 104/README.md
104/business/ 业务状态机:收到的 I 帧按业务类型分派、校验、应答与主动上送 104/business/README.md
examples/ 声明式 DTU(配电终端)点表 profile,一份头文件,无示例 main examples/README.md

104/ 下有两类文件,命名前缀就是分层标记:IEC104_* 是协议主体(传输与状态机), iec104_*(小写)是本项目的装配与平台层——iec104_core(生命周期与事件循环)、 iec104_source(数据/模拟动作/参数 RAM/虚拟墙钟)、iec104_net_mcu(CH395F 网络后端)、 iec104_dtu_table(标准 DTU 点表)、iec104_comm(/config.ini 的 [comm] 段:本站公共地址 与端口号的 RAM 副本、工厂默认、getter 合法带与 setter 守卫)。改协议行为先找 IEC104_*, 改「数据从哪来」先找 iec104_source,改「本站地址写在哪」先找 iec104_comm。

2. 能力边界(能做什么、明确不做什么)

动手前先确认需求是否在边界内,越界的功能要复用既有子系统而不是往这里加:

已实现:APCI 传输(APDU 帧、k=12/w=8 窗口、t1=15 s / t2=10 s / t3=20 s 超时)、 总召与计数量总召(GI/CI)、突发(COT=3)与周期遥测上送、遥控(含选择/执行两段)、校时、 读命令、标准参数(Type200~203 远方参数读写)、Type42 故障事件(扩展布局)。

未实现:历史数据、事故记录、文件传输、录波文件、固件升级后端。这些能力在本项目里 已有归属(存储栈、日志子系统、FTP 服务),集成时必须复用它们,不要在本目录内实现第二份。

3. 关键设计约束(代码为什么长成这样)

读代码时若觉得某处写法多余,先来这里对照——这些不是历史包袱,是有原因的项目决策。

3.1 C99 没有 _Static_assert,用数组宽度实现编译期断言

common/IEC60870_StaticAssert.h 是项目的 C99 约束实现,不是对第三方的兼容补丁: ARM Compiler 5(AC5,Keil MDK 默认编译器)只到 C99,没有 C11 的 _Static_assert。 该头在 __STDC_VERSION__ < 201112L 时把 _Static_assert(condition, message) 展开成 typedef char <唯一名>[(condition) ? 1 : -1]——条件为假时数组宽度为负,编译直接失败, 没有任何运行期开销。C11 及以上的目标仍走原生断言。

全目录 43 处断言调用点全部保留,每条断言条件都没改过(唯一变动是 SOE 容量守卫的 提示文字随容量宏改数字,而 C99 下该文字本来就被 shim 丢弃,语义不动)。

3.2 SOE 深度取 128 而非上游的 256

SOE(Sequence of Events,事件顺序记录)深度的两个容量宏 IEC104_TCP_SOE_CAPACITY 与 IEC104_ASDU_SOE_MAX_CAPACITY 都设为 128U, 是为了守住 RAM 预算。协议标准本身不规定 SOE 深度;本项目采信的数值下界是 瑞典 Svk TR02-04-04 §7.4.1 建议的 ≥100 条,因此 128 合规。 断言条件 SOE_CAPACITY == ASDU_SOE_MAX_CAPACITY 未被改动,它守的不变式仍然成立。

3.3 遥控点表元素 12 B → 8 B,为的是放进 const Flash

104/business/IEC104_Command.h 的点表结构去掉了每点各自携带的 common_address (公共地址,下文简称 CA),元素从 12 字节降到 8 字节,使整张表能作为 const 常量驻留 Flash 而不是占静态 RAM。

代价是 CA 不再逐点存储,改为实例级绑定:IEC104_Command 在首个被接受的请求时绑定本站 CA,此后 Find_Point 在二分查找前先比对 CA,不匹配直接走与「未知 IOA(信息对象地址)」 相同的拒绝路径。所以「CA 不匹配」与「点不存在」对外表现一致——这是设计选择,不是疏漏。 点表按 IOA 严格升序排列,同一 IOA 只允许一项。

3.4 枚举区间判断用无符号上界比较

104/IEC104_SendManager.c 与 104/business/IEC104_Spontaneous.c 里,非负枚举的区间 校验写成 (unsigned)x >= (unsigned)上限 而不是 x < 0 || x >= 上限。原因:负数转无符号后 会落到有效范围之上,照样被拒(语义不变),但 AC5 不再报「无意义的有符号/无符号比较」诊断。 这是为了让编译零警告,不是改变判定逻辑。

3.5 104/IEC104_TcpServer.c 的显式类型转换

把字节宽度的环形队列头展开进事件校验辅助函数时,有三处显式 IEC104_TcpEventType_t 转换:两个校验辅助函数的调用点(Event_Payload_Length_Valid、Is_State_Event) 与展开后的 copy.type 赋值。环里存的是 uint8_t,公开结构里是枚举,不加转换 AC5 会因 隐式转换告警。条件、容量、存储布局与运行行为均未改变。

3.6 common/IEC60870_FaultEvent.c 是链接依赖,不是可选模块

IEC104_Spontaneous_Publish_Fault_Event(104/business/IEC104_Spontaneous.c)在发布路径上 调用 IEC60870_FaultEvent_Encode(),因此 common/IEC60870_FaultEvent.c 必须一起编译链接, 缺了就是链接期未定义符号。 它实现的是 Type42 故障事件的扩展布局(两组异构记录 + 报文体内计数),不属于基础标准定义。

4. 容量覆盖面(构建期可调,不用改源码)

十一个模块级容量宏都用 #ifndef 包着,因此构建时可以直接 -D 覆盖, 不必编辑任何源文件——MCU 骨架档靠这个把工作队列压小,而模拟器保留全部业务模块。

宏 默认值 所在文件
IEC104_INTERROGATION_TASK_CAPACITY 4U 104/business/IEC104_Interrogation.c
IEC104_INTERROGATION_EVENT_CAPACITY 4U 104/business/IEC104_Interrogation.c
IEC104_SYSTEM_COMMAND_TASK_CAPACITY 4U 104/business/IEC104_SystemCommand.c
IEC104_SYSTEM_COMMAND_RESET_CAPACITY 4U 104/business/IEC104_SystemCommand.c
IEC104_PERIODIC_SCAN_GROUP_CAPACITY 4U 104/business/IEC104_PeriodicScan.c
IEC104_PARAMETER_TASK_CAPACITY 4U 104/business/IEC104_Parameter.c
IEC104_REMOTE_PARAMETER_TASK_CAPACITY 2U 104/business/IEC104_RemoteParameter.c
IEC104_CLOCK_SYNCHRONIZATION_TASK_CAPACITY 4U 104/business/IEC104_ClockSynchronization.c
IEC104_READ_TASK_CAPACITY 4U 104/business/IEC104_Read.c
IEC104_COMMAND_REPLY_CAPACITY 4U 104/business/IEC104_Command.c
IEC104_SPONTANEOUS_CAPACITY IEC104_TCP_SERVER_CAPACITY 104/business/IEC104_Spontaneous.c

调之前先知道两件事:① IEC104_SPONTANEOUS_CAPACITY 虽可覆盖但省不下 RAM——它的池元素是 回调与状态而非按容量分配的数组,所以骨架档让它留在默认值;② 这些宏调的是业务模块内部 单实例工作队列,不涉及 TCP 服务池、SOE=128、k/w 窗口或并发语义,因此改动它们不影响 92% RAM 门禁的口径。任何容量调整前先按 docs/内存管理/ 的方法核算。

5. 构建注册与平台后端

新增或删除本目录的 .c 必须双端同步,两个构建系统都是显式文件清单,不会自动发现:

  • Keil 工程:MDK-ARM/STM32F407-Demo.uvprojx
  • 模拟器:simulator/CMakeLists.txt 的 IEC104_SOURCES

注册纪律与动作 → new-source-file skill。

一个目标只能链接一个 Net 后端:板端用 104/iec104_net_mcu.c(经 CH395F), 模拟器用 104/IEC104_Net_Windows.c,两份实现同一个 IEC104_Net ABI。 两者同时链接会得到重复符号,或更糟——静默链到错的那份。

6. 改动纪律

改这个目录的代码时:

  • 按项目规范改,不必迁就上游写法;命名、注释、结构以 docs/代码规范/ 为准。
  • 动数据来源看 iec104_source.c,动协议行为看 IEC104_*,两者别混在同一个改动里。
  • 不许为了消警告把断言、品质位或门禁关掉;SOE 与窗口容量要改,先按 §4 的方法核算并留证据。
  • 编码规范门禁对本目录暂时豁免(.pre-commit-config.yaml 的 coding-standard 排除项): 约 1,200 处标识符驼峰(RULE-10)改造尚未进行,属单独排期;豁免不是永久状态, 那批改造完成后必须删除排除项。

7. 权属与许可

本目录的代码是团队自有代码,项目拥有完整处置权:可以按本仓规范自由修改命名、注释、 结构与实现,不需要为「保持与上游一致」做任何妥协,也不再有逐字节校验拦路。

仓库根的 IEC60870-Slave/ 是另一件事:它是收编前的原始快照,仅作独立验证基线保留, 其原始许可状态未经确认,与本目录的权属不是一回事——不要因为本目录已收编就认为那份基线 也可以自由分发。要在本目录之外复用那边的代码,先确认许可。

8. 相关文档

  • 板端设计与落地结论 → docs/子系统设计/IEC104上行设计说明.md、docs/子系统设计/IEC104_MCU落地规划.md
  • 网络层阻塞模型与 netTask 调用边界 → docs/网络/Net层阻塞模型架构设计.md
  • Net 适配契约(LISTEN/CLIENT 双句柄、代次不变式)→ docs/网络/IEC104_Net适配契约.md
  • 目录总览 → App/README.md