四篇讲「本项目怎么接 104」的文档原来散在子系统设计与网络两个目录, 和随库迁入的 36 篇协议库设计混在一起。现集中到 docs/iec60870/板端落地/: - IEC104上行设计说明.md(原 docs/子系统设计/) - IEC104_Net适配契约.md(原 docs/网络/) - IEC104_MCU落地规划.md(原 docs/子系统设计/) - IEC104_MCU最小可行性验证.md(原 docs/子系统设计/) 改动: - 四篇 git mv 保留历史,全库引用经 rename_ref.py 逐篇改写(27 个文件 54 处引用行),旧路径残留扫描为 0。 - docs/README.md:§5.3 改为「IEC 60870-5-104 文档(40 篇)」,拆成 「板端落地 4 篇」与「协议库设计与接口 36 篇」两张表,说明两条轴的分工; 从 §5.1 功能子系统表里移除这三篇的重复条目。 - docs/iec60870/README.md:新增两条轴入口与板端落地表,原阅读顺序 改标注为「协议库部分」。 验证: - check_doc_links.py --all --sections-strict:310 篇 0 问题。 - 三份索引 markdown 链接可达性逐个 exists() 校验,断链 0;索引表覆盖 36 篇协议库文档,与实际磁盘文件双向差集为空。 - 板端落地目录 4 篇 BOM / CR / U+FFFD 均为 0。 - 工作树 Keil 权威构建 0 errors 0 warnings(Code=365896 RO=48336 RW=2736 ZI=173104),此后预提交 21 Passed / 0 Failed。
10 KiB
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 |
iec104_dtu_profile.h(标准 DTU 点表数据本体)也在 104/ 下,由 iec104_dtu_table.c 包含进产品;它虽名为 profile,却是实打实的产品代码,详见 104/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/iec60870/板端落地/IEC104上行设计说明.md、docs/iec60870/板端落地/IEC104_MCU落地规划.md - 网络层阻塞模型与
netTask调用边界 →docs/网络/Net层阻塞模型架构设计.md - Net 适配契约(LISTEN/CLIENT 双句柄、代次不变式)→
docs/iec60870/板端落地/IEC104_Net适配契约.md - 目录总览 →
App/README.md