4784df923e
这个目录里的 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
157 lines
10 KiB
Markdown
157 lines
10 KiB
Markdown
# 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)
|