Files
STM32F4-Base/App/iec60870/README.md
T
wandering1 4784df923e refactor(iec60870): 解除第三方钉死,104 协议栈按项目自有代码维护
这个目录里的 104 协议栈原先按「第三方导入、逐字节保真」的方式管理:
改动要登记进哈希清单,门禁靠对比上游字节来判断有没有被动过。现在它已经是
团队自己的代码(用户裁定有完整处置权),这套机制就变成了纯粹的阻力——
它会让正常的功能修改看起来像篡改。这一版把它拆掉。

主要动作:

- App/iec60870/IMPORT.md 改名为 README.md。原来的名字本身就在说「这是导入的」,
  而按仓库文档规范,每个自建代码目录都该有 README。
- 删除 App/iec60870/UPSTREAM.sha256(84 条上游哈希)。它唯一的运行时消费者
  是 transport 测试的源文件清单,那个脚本已改成显式列出 27 个 .c。
- 许可证表述改为项目自有。仓库根的 IEC60870-Slave/ 是另一件事:那份仍是原始
  快照、仅作独立验证基线,许可状态未确认,不因本目录收编而改变。
- 四个子目录 README 从 4~6 行扩写到 32~69 行,各自说清职责、边界与改动纪律。
- coding-standard 的排除面收窄:从排除整个 104/ 改为只排除 business/ 与
  大写开头的 IEC104_*。我们自己的适配层 iec104_*.{c,h} 重新进入受检面,
  11 个文件实测 RC=0。

保留的技术知识(没有随保真框架一起删掉):C99 静态断言为何需要 shim 与
43 处断言条件未改、SOE 深度 128 的合规依据、点表元素 12B 降到 8B 以放进
const Flash、无符号上界比较消诊断、FaultEvent 的链接依赖、11 个容量宏的
默认值表、以及能力边界(历史/录波/文件/升级后端未导入)。

验证:

- 全量 pre-commit 12 Passed / 0 Failed
- doc-links 308 篇 / 30 处问题,全部在 IEC60870-Slave/ 内,我方零新增
- transport 测试改前改后编译集逐字节一致(27 个 .c,哈希相同),10 条用例全过
- 8 个改动文件字节体检 BOM=False / CR=0 / U+FFFD=0
2026-11-18 21:31:03 +08:00

157 lines
10 KiB
Markdown
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.
# 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`](common/README.md) |
| `104/` | APCI(应用规约控制信息)传输层 + 业务状态机 + **平台适配与装配** | [`104/README.md`](104/README.md) |
| `104/business/` | 业务状态机:收到的 I 帧按业务类型分派、校验、应答与主动上送 | [`104/business/README.md`](104/business/README.md) |
| `examples/` | 声明式 DTU(配电终端)点表 profile,一份头文件,无示例 main | [`examples/README.md`](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`](../README.md)