diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index fe60b0e3..beef812f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -155,14 +155,18 @@ repos: types: [c] # 范围与 cppcheck 钩子一致;另排除 CubeMX 生成文件(Src/、Inc/,重新生成即覆盖)、 # dhara/FatFS 接口适配层(nand_ftl,函数名由外部 API 固定) - # `App/iec60870/{common,104,examples}/` 与 `IEC60870-Slave/` 在 2026-11-18 之前是 - # 逐字节钉在 UPSTREAM.sha256 上的第三方源码(IEC 60870-5-104 子站库,45k 行)。 - # 2026-11-18 起该库转为项目自有代码:不再做字节保真校验,命名/注释/结构按本仓规范 - # 逐步收编(`UPSTREAM.sha256` 仅作迁移出处的历史记录,不再作为门禁判据)。 - # 本排除项暂留,是因为收编尚未完成(12xx 处 RULE-10 待改);收编完成后必须删除这三行。 - # ⚠ 排除面必须逐条写成子树前缀(common/、104/、examples/),**不能**写成祖先 - # `App/iec60870/`:那会把协议核心之外的其它子目录一起吞掉(2026-11-18 实测过 - # 这种误伤:写成祖先形态后 `104/` 内我们自己的装配文件被判 EXCLUDED)。 + # `App/iec60870/` 下的协议栈曾是第三方 IEC 60870-5-104 子站库(约 5 万行), + # 2026-11-18 起收编为项目自有代码:不再做字节保真校验(`UPSTREAM.sha256` 已删除), + # 命名/注释/结构按本仓规范逐步改造。 + # 下列排除项只覆盖**尚未改造的那部分代码**,收编完成后必须删除: + # 1,200+ 处标识符仍是驼峰,RULE-10 会全量报错。这批改造属 Phase 3 单独排期, + # 不在收编范围;改完必须删掉这三行,否则等于自建代码永久免检。 + # 我们自己写的适配文件不受这条豁免——`104/` 下小写的 `iec104_*.{c,h}`(core / + # net_mcu / source / dtu_table / comm)在受检面内,逐个直调脚本实测 RC=0。 + # 大写开头的 `IEC104_*` 才是尚未改造的上游文件,仍被下一条规则排除。 + # ⚠ 排除面必须逐条写成可判定的前缀,**不能**写成祖先 `App/iec60870/`:那会把 + # 协议核心之外的其它子目录一起吞掉(2026-11-18 实测过这种误伤)。 + # `104/` 同样不能整目录排除——那会连我们自己的适配层一起豁免掉。 exclude: | (?x)^( Drivers/CMSIS/| @@ -171,7 +175,8 @@ repos: Drivers/BSP/GD5F2GQ5UE/nand_ftl\.| Drivers/BSP/dhara/| App/iec60870/common/| - App/iec60870/104/| + App/iec60870/104/business/| + App/iec60870/104/IEC104[_.]| App/iec60870/examples/| IEC60870-Slave/| Lib/| diff --git a/App/README.md b/App/README.md index 8398a589..fbe29239 100644 --- a/App/README.md +++ b/App/README.md @@ -20,7 +20,7 @@ FreeRTOS/CMSIS-RTOS API**(本条与「就绪屏障位必须 `osFlagsNoClear` | `log/` | **日志子系统**:syslog(NAND)+ 控制台单写者日志 | [`log/README.md`](log/README.md) | | `task/` | **FreeRTOS 任务实现**(6 个任务) | [`task/README.md`](task/README.md) | | `util/` | **通用工具**:CRC / 环形缓冲 / 墙钟时间 | [`util/README.md`](util/README.md) | -| `iec60870/` | **通信协议**:IEC 60870-5-104,只维护一个实现——`common/` 编解码 + `104/` 协议与平台适配(core/source/net_mcu/dtu_table/comm 同目录) | [`iec60870/IMPORT.md`](iec60870/IMPORT.md)(迁移出处);结构见本文末节 | +| `iec60870/` | **通信协议**:IEC 60870-5-104,只维护一个实现——`common/` 编解码 + `104/` 协议与平台适配(core/source/net_mcu/dtu_table/comm 同目录) | [`iec60870/README.md`](iec60870/README.md)(目录说明与设计约束);结构见本文末节 | ## 关键约束 @@ -42,7 +42,7 @@ FreeRTOS/CMSIS-RTOS API**(本条与「就绪屏障位必须 `osFlagsNoClear` 改动口径:全部按项目自有代码对待(命名、注释、结构遵循 `docs/代码规范/`); `iec104_*` 是本项目自己的装配与平台层,`IEC104_*` / `IEC60870_*` 是协议主体与共享编解码。 -设计入口 → `docs/子系统设计/IEC104上行设计说明.md`;迁移出处 → [`iec60870/IMPORT.md`](iec60870/IMPORT.md)。 +设计入口 → `docs/子系统设计/IEC104上行设计说明.md`;目录说明与改动纪律 → [`iec60870/README.md`](iec60870/README.md)。 ## 相关文档 diff --git a/App/iec60870/104/README.md b/App/iec60870/104/README.md index 309d9cfa..64c54749 100644 --- a/App/iec60870/104/README.md +++ b/App/iec60870/104/README.md @@ -1,5 +1,69 @@ -# Transport import +# `104/` — APCI 传输层与协议状态机 -Byte-preserved subset of `IEC60870-Slave/104` at baseline f84855a5. -Slave/TcpServer own nonblocking I/O, partial sends and connection identity. -Only one Net backend may be linked into a target. +本目录负责 104 协议的**传输面**:把字节流切成 APDU 帧、维护 k/w 发送窗口与超时, +并把解析出的事件交给 `business/` 的业务状态机。要改「帧怎么收发、连接怎么管」在这一层; +要改「某类请求怎么应答」去 `business/`。 + +本目录同时承载**平台适配与装配**(小写 `iec104_*` 前缀,见 §3),因为一个目标只能链接一个 +Net 后端,装配代码与它服务的传输层放在一起才能一眼看清这条唯一链路的全貌。 + +## 1. 文件分工 + +| 文件组 | 职责 | +| --- | --- | +| `IEC104_Codec.c` | APDU 帧编解码:I/S/U 帧格式、长度字段、APCI 头部 | +| `IEC104_Link.c` · `IEC104_Link_Slave_StartStop.c` | 链路状态机:STARTDT/STOPDT/TESTFR 与从站启停 | +| `IEC104_Connection.c` | 单条连接的收发状态、序号维护 | +| `IEC104_Receiver.c` | 接收侧组帧与校验,产出待处理事件 | +| `IEC104_SendBuffer.c` · `IEC104_SendManager.c` | 发送缓冲与发送调度(含部分发送处理、优先级车道) | +| `IEC104_AsduQueue.c` | ASDU 队列:HIGH/NORMAL 两级,跨重连保留语义见该文件注释 | +| `IEC104_TcpServer.c` · `IEC104_TcpServer_Config.h` | 非阻塞 TCP 服务:连接身份、事件环、SOE 容量 | +| `IEC104_Slave.c` · `IEC104_Slave.h` | 从站主体:对外统一入口(启动、轮询、状态查询) | +| `IEC104_Net.h` · `IEC104_Net_Windows.c` | Net 后端 ABI 与主机(模拟器)实现 | +| `IEC104_Log.h` | 日志宏声明头,**当前是孤儿**:实现文件 `IEC104_Log.c` 未随迁,无任何文件 include 它,两套构建清单里也没有它。本目录按 §4 的零日志惯例运行,保留此头仅为不破坏上游文件集合的完整性 | + +## 2. 关键约束 + +**一个目标只能链接一个 Net 后端。** `IEC104_Net.h` 定义一套 ABI,板端由 +`iec104_net_mcu.c`(经 CH395F)实现,模拟器由 `IEC104_Net_Windows.c` 实现。 +同时链接两份会重复定义符号,或者更隐蔽地链到错的那份——两条路径的阻塞语义完全不同, +后者不会报错,只会让时序对不上。板端后端的句柄规则(LISTEN/CLIENT 双槽、代次不变式) +见 `docs/网络/IEC104_Net适配契约.md`。 + +**非阻塞 I/O 与部分发送是这一层的前提。** `Slave`/`TcpServer` 假定 Net 后端从不在调用内 +阻塞,因而发送必须能返回「已写一部分」,由 `SendManager` 记住偏移下轮续写。 +板端网络层是「两段式等待 + `netTask` 单属主」模型,与本假设的接缝 +→ `docs/网络/Net层阻塞模型架构设计.md`。 + +**SOE 容量是 RAM 预算决策**:`IEC104_TcpServer_Config.h` 把 +`IEC104_TCP_SOE_CAPACITY` 设为 `128U`(上游为 256),理由与合规依据见 +[`../README.md`](../README.md) §3.2。 + +## 3. 装配与平台层(小写 `iec104_*`) + +这五个模块是本项目的自有代码,不是协议主体的一部分: + +| 文件 | 职责 | 不能据此推断 | +| --- | --- | --- | +| `iec104_core.c` | ``iec104_core_start/poll/stop`` 生命周期与事件循环,串行驱动上面整套状态机 | PC 运行不证明 CH395F、RTOS 或板端监听生命周期正确 | +| `iec104_source.c` | 数据源、模拟动作、参数 RAM、虚拟设备墙钟;`iec104_source_bind()` 是可选平台接缝 | 接口存在不等于已绑定 UI、保护或标定真源 | +| `iec104_net_mcu.c` | CH395F 的 Net 后端实现(板端唯一后端) | 不经板端台架验证过 | +| `iec104_dtu_table.c` | 标准 DTU 点表与元数据(含 SP/DP/ME 分段与参数表) | 新旧通信地址相同不代表语义相同 | +| `iec104_comm.c` | `/config.ini` 的 `[comm]` 段:本站公共地址/端口号的 RAM 副本、工厂默认、getter 合法带自愈与 setter 守卫;键表口径见 `docs/子系统设计/网络配置说明.md` | 落盘属主是配置引擎(`App/cfg/`),本模块只提供 `iec104_comm_store_save()` 与脏位 | + +调用必须由**同一事件循环属主串行执行**,源回调必须短且不阻塞。当前属主是 `netTask`: +`App/task/iec104_serv.c` 在 1 ms 循环里调 `iec104_serv_net_tick()`,不另建 104 任务。 + +## 4. 日志与诊断 + +本目录的协议主体遵循**零日志输出**惯例(不 `printf`、不直写串口),状态通过 +`IEC104_Slave_Get_Status()` 与各模块 `status` 结构暴露,由上层(`App/task/iec104_serv.c`) +决定怎么记录。理由:协议层不知道自己运行在哪个任务上下文,直写日志会引入不可重入与 +栈深度不可控。要加诊断信息,请扩状态结构而不是往协议层塞日志宏。 + +## 5. 相关文档 + +- 完整协议栈与目录总览 → [`../README.md`](../README.md) +- 板端设计与落地结论 → `docs/子系统设计/IEC104上行设计说明.md` +- Net 适配契约 → `docs/网络/IEC104_Net适配契约.md` +- 阻塞模型与 `netTask` 调用边界 → `docs/网络/Net层阻塞模型架构设计.md` diff --git a/App/iec60870/104/business/README.md b/App/iec60870/104/business/README.md index 91af909f..77b6b256 100644 --- a/App/iec60870/104/business/README.md +++ b/App/iec60870/104/business/README.md @@ -1,5 +1,46 @@ -# Business import +# `104/business/` — 业务状态机层 -Byte-preserved subset of `IEC60870-Slave/104/business` at baseline f84855a5. -Application data providers remain outside these protocol state machines. -File/history/recording/firmware-update implementations are not imported. +本目录把**收到的 I 帧**翻译成业务动作:总召、遥控、校时、读、远方参数……每种业务一个 +模块,各自维护自己的任务池与超时。要改「某类请求怎么校验、怎么应答、什么时候主动上送」 +在这里;要改「字节怎么收发」去 `104/`,要改「数据从哪来」去 `iec104_source.c`。 + +**应用数据提供者不在这一层,也不该塞进来。** 这一层只认协议语义:它调用 +`IEC104_Slave` 提供的应答接口把结果写回队列,数据本身由上层通过平台接缝提供 +(板端是 `App/task/iec104_serv.c` 的绑定函数,见 [`../README.md`](../README.md) §3)。 +把业务数据源直接写进状态机会让这一层无法被主机单测脱机验证。 + +## 1. 文件分工 + +| 文件 | 职责 | 对应 104 类型 | +| --- | --- | --- | +| `IEC104_Startup.c` | 启动配置默认值与初始化顺序 | — | +| `IEC104_GeneralInterrogation.c` | 总召(站总召)的接收、分轮应答与终止 | C_IC_NA_1 | +| `IEC104_CounterInterrogation.c` | 计数量总召 | C_CI_NA_1 | +| `IEC104_Interrogation.c` | 总召/计总召的公共任务池与事件调度 | — | +| `IEC104_Command.c` | 遥控:选择/执行两段、点表许可检查、CA 绑定、类型掩码 | C_SC/C_DC/C_RC… | +| `IEC104_ClockSynchronization.c` | 校时 | C_CS_NA_1 | +| `IEC104_Read.c` | 读命令 | C_RD_NA_1 | +| `IEC104_Parameter.c` | 标准参数(定值区/预置/固化) | P_ME/P_AC… | +| `IEC104_RemoteParameter.c` | 远方参数读写(Type200~203) | Type 200~203 | +| `IEC104_PeriodicScan.c` | 周期扫描上送分组 | — | +| `IEC104_Spontaneous.c` | 突发上送,含 Type42 故障事件发布入口 | M_SP/M_DP/M_ME… | + +## 2. 关键约束 + +十个模块的容量宏都可 `-D` 覆盖(共 11 个宏,`IEC104_Interrogation.c` 占 2 个), +但覆盖的是「同时可挂几个任务」,不是「池有多大」。默认值与所在文件列在 +[`../../README.md`](../../README.md) §4 的表里,调之前先看那张表的注意事项—— +其中 `IEC104_SPONTANEOUS_CAPACITY` 覆盖后省不下 RAM。 + +**遥控点表的 CA 是实例级绑定,不是逐点存储。** `IEC104_Command.c` 在首个被接受的请求时 +绑定本站 CA,`Find_Point` 先比 CA 再二分查找;不匹配走「未知 IOA」路径, +所以「CA 不对」与「点不存在」对外不可区分。原因与代价见 [`../../README.md`](../../README.md) §3.3。 + +**未实现的能力不要在这里补。** 历史数据、事故记录、文件传输、录波、固件升级后端都没有 +实现;本项目已有对应子系统(存储栈、日志、FTP),集成时复用它们,别造第二份。 + +## 3. 相关文档 + +- 完整协议栈与目录总览 → [`../../README.md`](../../README.md) +- 容量表与 RAM 口径 → [`../../README.md`](../../README.md) §4 +- 板端落地与已知缺口 → `docs/子系统设计/IEC104上行设计说明.md`、`docs/子系统设计/IEC104_MCU落地规划.md` diff --git a/App/iec60870/IMPORT.md b/App/iec60870/IMPORT.md deleted file mode 100644 index 4ae7d4bf..00000000 --- a/App/iec60870/IMPORT.md +++ /dev/null @@ -1,124 +0,0 @@ -# IEC60870-Slave product subset - -Source: repository `IEC60870-Slave/` at baseline `f84855a5`. - -The source directory is retained as the independent validation baseline. Only -this product subset is to be compiled into the replacement product target. -No example main is included. Copying is byte-preserving; source hashes are -recorded in the directory manifests before local compatibility edits. - -## Verification status - -| Check | Status | -| --- | --- | -| Original byte provenance | `UPSTREAM.sha256`; independent final 84-file check passed, seventeen locally differing files: twelve reviewed patches and five trailing-blank-line-only. The command-table patch spans two files in one directory (`IEC104_Command.h` and `.c`) and both are counted. The SOE-128 change touches `IEC104_TcpServer_Config.h` and `IEC104_AsduQueue.h` (capacity) plus `IEC104_TcpServer.c` (assert message text), with three comment-only corrections in `IEC104_Slave.h`, `IEC104_TcpServer.h`, `IEC104_Spontaneous.h` (stale "256" SOE wording fixed to 128, quantifiers only, semantics untouched; Lead decision 2026-11-18). | -| C99 assertions | 43 original invocations remain; every assertion condition unchanged (one message text tracks the SOE capacity macro); independent AC5 true passes / false fails, invalid capacities including SOE128 rejected | -| Final compiler diagnostics | Independent AC5 default/compact: 62 translation-unit compilations, RC0 and zero diagnostics; simulator and runtime tests tracked separately | -| Static memory / runtime integration | Separate build-verifier and integration task evidence; no board runtime claim | -| License | No license grant confirmed; redistribution not authorized by this import | - -Required scope: APCI transport, GI/CI, spontaneous/periodic measurements, -commands, clock synchronization, read, standard parameters and Type200-203. -History, recording, file storage and firmware-upgrade backends are not imported; -product integrations must reuse existing subsystems. -Organizational source import is not a rename; baseline paths remain unchanged. -Local edits use the Edit tool only. - -## Local patches - -- Added `common/IEC60870_StaticAssert.h`, included by shared Types and the - standalone Net header. In pre-C11 C, each existing assertion expands to a - line-unique typedef with array bound `(condition) ? 1 : -1`; false assertions - are compile errors. C11 targets retain native assertions. All 43 assertion - invocations remain, and every assertion CONDITION is unchanged. The only - message text that differs is the SOE guard's event count, which tracks the - capacity macro this product sets to 128 (see below); on C99 the message is - discarded by the shim, so no assertion semantics move with it. -- `104/IEC104_TcpServer.c`: two explicit `IEC104_TcpEventType_t` casts when - expanding the byte-sized ring header into event validation helpers; no - condition, capacity, storage layout or runtime behavior is changed. -- `104/IEC104_SendManager.c` and `104/business/IEC104_Spontaneous.c`: - convert nonnegative enum range checks to unsigned upper-bound comparisons. - Invalid negative values still convert above the valid range and are rejected; - AC5 no longer diagnoses pointless unsigned comparisons against zero. -- `104/business/IEC104_Command.h` + `104/business/IEC104_Command.c`: mask each - TYPE_BIT shift count with 15, and remove the per-point `common_address`. - Selected valid branches already use shifts 0..13; range guards still return - zero for unsupported types. This avoids MSVC diagnostics about unsigned - underflow in unselected conditional branches, not a proven executed runtime UB. - The point table now sorts by IOA only; the instance binds its station CA on the - first accepted request and `Find_Point` rejects any other CA before searching, - so a CA mismatch still takes the unchanged unknown-IOA path. Point entry size - drops from 12 to 8 bytes on ARM Compiler 5, letting the application hold the - table in const Flash instead of static RAM. No capacity, SOE, ordering or - acceptance semantics change; see `ci-artifacts/iec104-mcu-skeleton/core-trim/` - for the element-wise and lookup equivalence probes. -- Added `common/IEC60870_FaultEvent.c` as an exact-copy link dependency of - `IEC104_Spontaneous_Publish_Fault_Event`, with Lead authorization. -- `UPSTREAM.sha256`: 84 original byte hashes (29 implementations, 54 directory - headers and the declarative profile header). Paths are relative to this - directory and to `IEC60870-Slave/`; hashes describe upstream bytes, not the - twelve locally differing files. The compatibility header is new and not upstream. -- Trailing blank lines: five files (`common/IEC60870_Codec.c`, - `common/IEC60870_InformationObjects.c`, `common/IEC60870_InformationObjects.h`, - `common/IEC60870_InformationObjects_Internal.h`, - `examples/iec104_dtu_profile.h`) differ from upstream by exactly one - end-of-file blank line, removed by the repository's `end-of-file-fixer` - pre-commit hook (it does not exempt this tree). Content normalized for that - single line is byte-identical to upstream, and `verify_vendor.py` asserts as - much: its `BLANK` class may only list such files, and a semantic edit carried - into one of them fails the check instead of hiding behind the class. -- SOE capacity: this product sets `IEC104_TCP_SOE_CAPACITY` and - `IEC104_ASDU_SOE_MAX_CAPACITY` to `128U` (upstream `256U`) to fit the RAM - budget, and the guard message text follows the new count. IEC 60870-5-101/104 - does not specify SOE depth; the only numeric lower bound in play is the - Swedish Svk TR02-04-04 §7.4.1 guidance of 100 entries, so 128 stays compliant. - The assertion CONDITION (`SOE_CAPACITY == ASDU_SOE_MAX_CAPACITY`) is untouched, - so the invariant it guards still holds. - -## Capacity override surface (skeleton profile) - -Eleven per-module capacity macros are already wrapped in `#ifndef`, so a build may -override them with `-D` **without editing any source file**. This is what keeps the -MCU skeleton profile small while the simulator keeps every business module enabled. -`verify_vendor.py` compiles both the default and compact configurations and would -catch an undefined-macro regression, but note that no `-D` is baked into any source. - -| Macro | Default | File | -| --- | --- | --- | -| `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` is overrideable but yields no RAM saving (its pool -element is callbacks/state, not a capacity-sized array), so the skeleton profile -leaves it at its default. The 92% gate is unaffected: these macros size single -instance work queues inside a business module, not the TCP server pool, SOE=128, -k/w windows or concurrency semantics. -- Independent hash/diff and AC5 true/false assertion verification is performed - by build-verifier; product integration and simulator build have separate owners. - -## License - -No license grant has been inferred. The baseline license must be checked before -redistribution outside this authorized project integration. - -## Layout - -- `common`: shared ASDU, information-object codecs and time representation. -- `104`: mature transport and business state machines. -- `examples`: DTU declarative point-profile header only, never an example main. - -The board network backend is a later integration task; importing this subset -does not by itself remove dependencies of the current board service. - -Resource capacities must be measured before adjustment. No assertions, quality -gates, stack limits or compiler diagnostics are disabled by this import. diff --git a/App/iec60870/README.md b/App/iec60870/README.md new file mode 100644 index 00000000..1bfb47fd --- /dev/null +++ b/App/iec60870/README.md @@ -0,0 +1,156 @@ +# 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) diff --git a/App/iec60870/UPSTREAM.sha256 b/App/iec60870/UPSTREAM.sha256 deleted file mode 100644 index 92f76aee..00000000 --- a/App/iec60870/UPSTREAM.sha256 +++ /dev/null @@ -1,84 +0,0 @@ -327031ef8dc8939f5ed61a182caf66d7204d30f8022a4b9541db063187a477ea common/IEC60870_FaultEvent.c -3233d4c114de769dcf0572bad9be9fb962e0ac9da085dc294f33eb97327ff4aa common/IEC60870_Asdu.c -0410b30a3b67301af145f8a2337f80dae9ac6c15a39ae3d0ecd82b22de085b55 common/IEC60870_Codec.c -5a068619e313f4c40f2e054e7a1ef5199bb8e38871c8294e6de901ec9ef10e95 common/IEC60870_InformationObjects.c -74742af727ce571c137aa3eff49c427e4e9788f4ca55a5a75689329874c33029 common/IEC60870_Slave.c -7e647faf1411068768a1763782eb11a9386605194e91cec42f30349fd2cf0637 common/IEC60870_Time.c -6ea101c4cc867cd54e7d58484b1ce22e54e2a51ed14c8b181864304162a06f3f 104/IEC104_AsduQueue.c -cbcbc548ee1eacdd52ff473220924d0a4e87d01278da139e2295a16eca28988b 104/IEC104_Codec.c -c6b8b017f246e3c69e43d52810b2214b4047ee065de37a20c411471642c6611a 104/IEC104_Connection.c -f1fd5e378b573c28bdbf633435b812148d18246fbf9c727d09af113e0075ecb4 104/IEC104_Link.c -ba0f92161655fcf0d89526d9ca0235294f3808629281528552e797530ad4860b 104/IEC104_Link_Slave_StartStop.c -6fdbac76e7578453875ecfd2067d17cd62b32b75cf45c022521b6fb6bcd7b331 104/IEC104_Receiver.c -2b1e46491cf0b60ecbb102e6eaacf98b8650e6e27bba2ef9ba09a811b18a8773 104/IEC104_SendBuffer.c -c50de5654fa1a9ae002302b3bba46b0766ac0d6effd1c42bc2c3e77b4f258ddc 104/IEC104_SendManager.c -d6e14ec7c5b2c9f2a3f1eed1af3d2ed65bff8acdd58682769b8d0bccb0f06d52 104/IEC104_Slave.c -4f0cd643272aee21b62a0753f17ae0deda41eeacc4649efe23141faadad8fa21 104/IEC104_TcpServer.c -67a6633d7cb60eb4ef7a2917145d76f1d5912230a37977f43cf2dc963c65ef6e 104/IEC104_Net_Windows.c -94f10165db4c1910d3111c1b99d59f1f7eeb9bcf5d9020fc67a4604d4fea5bba 104/business/IEC104_GeneralInterrogation.c -b301157bc2d36def848d660c02c54dc5757061fd989f9795129351c11cca060e 104/business/IEC104_CounterInterrogation.c -0d706feaf3e44cc2401b62dfffbcb598c28ee2e1fd9b6c16d9919b1a7657303e 104/business/IEC104_Interrogation.c -a1c20fd50ad6bfffb317b97ec68ff818bf6f8ab87f2a9c06c4d02e3bbf220cfa 104/business/IEC104_Command.c -fb3246e3ea200826c6a95a6326806259b7e88883bad9f6db6ebaae372bdd9261 104/business/IEC104_ClockSynchronization.c -b3388f8d69123c17e636c5a66361b013b9dfb8546c1f4838ba38c18aad11b770 104/business/IEC104_RemoteParameter.c -57d3e648e2f1a40bf2dbba2b20295a91d11bf2db5370dcdb6ff3607d984466ff 104/business/IEC104_Read.c -0cfd97f763fcb7a06208f8c8c225581c1d78a2dd3e75e259a7481cd6a8141d60 104/business/IEC104_Parameter.c -1ffa8c162870e4161308720e26df0662c1549a5a00eef3beb47a0230dca651ec 104/business/IEC104_Startup.c -3b2566e7baf2fcb6fd7e745fb05c59d423e7fa8d6df005e8581cd8a9b8cdcd55 104/business/IEC104_SystemCommand.c -99105c1b62adaaff4e4cd93f11f860620e864a72e528a1291e66c102ce71c00f 104/business/IEC104_Spontaneous.c -795aa4f58bb6558890bd39f3d5667e41d420ed7cffcf52348d888b89ffdbbf1c 104/business/IEC104_PeriodicScan.c -b9593f92d2fd0a9f62c903a1d3796c3397b9d4c5a7926860a017744f07a915bc examples/iec104_dtu_profile.h -8bdaed26d6bfb4a2542f2a3a05d83d3a167f8b83da227dc51a250aa49af71296 common/IEC60870_Asdu.h -bbc770a0c8c9d5f3db1e3bef23b226ba35a651f550bbd76fa5d2d1b037b238d3 common/IEC60870_Clock.h -d469ab5ab1c5dc9bcc63f73c8b78d2755c8f29245b9a60ea1288116bd067f246 common/IEC60870_Codec.h -37cb14ba14d9f1c203a88bd44d13c91feb173f34d6bb3047b6c6258ffb047709 common/IEC60870_Comtrade.h -ab613c01496c1a4db1f200a72fb0daa6a26a9ab18e211ac096b8c416a012b9e7 common/IEC60870_EnergyFreeze.h -7551feed3f9677e7530730d78fe41d2c4e2d8e68bc20e929ebe7e71b46118071 common/IEC60870_EnergyFreezeFile.h -48978f098e1ffd2d5e63a746105807b8a6e7f26b81c8eb9949ca8ba177a4f215 common/IEC60870_FaultEvent.h -e684c5c08a02a75cdce916a2723d46acf88913697d60e65dbeb8f31e7635e9c7 common/IEC60870_FaultRecorder.h -a31c1af966eae8e8db72cbba1b421f26571b387dbfd0d40d2134b7f5028dfc94 common/IEC60870_FirmwareUpdate.h -9a348feedbaee0f19052c104a0d4691412180441ed3bab4c268b71f704dd36e2 common/IEC60870_History.h -fb651a7880508028c000478407989eed799fda06aa0625066654c99a299c7c05 common/IEC60870_HistoryFile.h -6abb49ad964f06eb67c08740a22ed4b63d758fd79e73cb5382b0bc1d50ed61f1 common/IEC60870_InformationObjects.h -f48f007af81fd7cf115543013624c6db692ba9a5624df4692b1650233fa8b733 common/IEC60870_InformationObjects_Internal.h -ccce0a5a60f63f18f7102beb544f3c31bacf84487de7895513b45015e92b2914 common/IEC60870_Slave.h -e3c7272690f6b19dd22b667e70800f7bb537fd25152735597334292ea1589ede common/IEC60870_Time.h -5630a82e2f8d091e7a5f03947aa3edc4ce0d6918dca4520295ac341cc50cadaf common/IEC60870_Types.h -b932b901c8fb72d7d81c59fbfc07421b80be9b11e20b3a7296ef06553be99b02 common/IEC60870_UserLog.h -7f55ec5b078ba5c3eddebdb7ab0fcbb3ff720a2049947004c808f6a65c70216c common/IEC60870_UserLogFile.h -c2895eb330ac965f15bef3497040c6057750bdc91884e14e9f4b1fbfe2676c40 104/IEC104.h -9d4fb32cd6d3f9ed27da15a25af3b0e9d6c4330e284e7e1f226bde6b5c64db89 104/IEC104_AsduQueue.h -f8fd4ff0729bffc8ff61bd5a141f0835a65c3748c0edb989da44317ccc92af91 104/IEC104_Codec.h -6faab842068b08a62085134b3afd03ed80a9edba78bb805198c72105b48916c9 104/IEC104_Config_Internal.h -67581c583e25ab7ecc1d5c48dbf37061f27550b6eac7fd9833949ec37b4e3733 104/IEC104_Connection.h -aa0b38c75c8d7a45ab025bda362e9232570ab4d24b20d6e208bcf86957acf14d 104/IEC104_Link.h -1286b460c3d0f4227fe71863a802fdb2df432e7a421011f67d102400d537542b 104/IEC104_Link_Common.h -52b17e1569f3f77d3854b49ba4578b43b38e508fe13effff20320c78c6de6e94 104/IEC104_Link_Internal.h -0f775839caf342595994fc39d1c80c777d6518c22d8e446a0f1a2c460f38e5ca 104/IEC104_Link_Master_StartStop.h -abd78dbb2ff0e1fb5cb523bb723fbc0f2f99a4c83972adad6c9b077950c349ff 104/IEC104_Link_Slave_StartStop.h -fd638e59aebb6f4e290d64bf4d118241726f5b50a2c988541001ac7a3870f734 104/IEC104_Log.h -7f4dd379903597d7862558d2a64160123cdbf81386968e174f47b8715b5b1689 104/IEC104_Net.h -2e537e84cdbea9bb22ee1d51324283004e39b0baf56f179fe9b0c5515db5383e 104/IEC104_Receiver.h -355685ef39ebc7a2f23576d0c1a30d19330a9710f26b1031ae30b5d87463b89b 104/IEC104_SendBuffer.h -0c3016d4b4b9d2a102e735231b69ec61f9fb6a2d9ea54265f76c2371ad40a20f 104/IEC104_SendManager.h -79323ec066c967bec4659c09a3704e6b85841c43b1b9ead744bc1967d6c90bb7 104/IEC104_Slave.h -24bc094ae559969d4e9d00e954ff975e8d11222d475a8463aacd5bbb1d4cab34 104/IEC104_TcpServer.h -dde7e19193f059c287022be21612faa56924c6f4d09a5d30948afbce4bde0044 104/IEC104_TcpServer_Config.h -62cfef7d7b26602132948f89a22f9ec6804ea6514254867ba7ceff3c01478b93 104/IEC104_TcpTypes.h -8c4a7393c2c4ed179d7ea7ed7a2416bc15dc21d6bf3e6e6bcb6dffe01dcfa1ce 104/IEC104_Types.h -3dd3fad52a82887d7289fbef6dd833eee0768863cd8a5419979fa1208116c731 104/business/IEC104_BusinessConfig_Internal.h -1d401209adc80765ed0e75a355ee09a9436b2a6f859dab706dca14eed23c9f04 104/business/IEC104_ClockSynchronization.h -fac10b37cb07ec2a28cf542f0110ad173234f06d42b2366f72cb233bcc50ddc2 104/business/IEC104_Command.h -d33cf5ff2d4ea5c47ce0cf31c6a061378658145ffed32dc381754d56bd671a5a 104/business/IEC104_CounterInterrogation.h -9cdc16cd13af259cd95ec8a48fc09d40be4af7ee6c3df9496f78cb819737e2f4 104/business/IEC104_FileService.h -785d298fa21493592b61d72aede75f5e48f8909472eae9a897dc5d1bb8a1df79 104/business/IEC104_GeneralInterrogation.h -8e918298330d7e3fc21b019cdd07e603c9fd71d84aad328399ca708f517f8fd7 104/business/IEC104_Interrogation.h -eca3aed1c801fdb33a2a5de3da97832af417d3676e80fd70ea400381183ff407 104/business/IEC104_Interrogation_Internal.h -4eff0700b1ddb7eba97e35717f39de7a4f06ade86456e7956bfba7b970a8b1fc 104/business/IEC104_Parameter.h -6c67a4dd97eb4a7ac097eed198f6d72a102f0011e34a94d38f427f29a1957e44 104/business/IEC104_PeriodicScan.h -92558942b53b5651dac9867b60107fba2dc2e17cb20f13abcd271b336f83b0fa 104/business/IEC104_Read.h -f07d9faeb25c7d3c7053d123af06c38be0678faba0d2f97038364dddb41d4b83 104/business/IEC104_RemoteParameter.h -25deb64a0653efaf840419b2c58ab226eb17771900591294658127b5257855fa 104/business/IEC104_SoftwareUpgrade.h -fa0c3acb87beff12d2b62aee27b52b1501b3db06bb45314ee4880c6210029bd0 104/business/IEC104_Spontaneous.h -d8dc8c018917f99239e85845aa2125528dd60b1865bfde7980a8174f16e0fb06 104/business/IEC104_Startup.h -556db981f2d58e1441ecafc676917f70698eac5d790e2fe2a5bc1e58f8b2e35d 104/business/IEC104_SystemCommand.h diff --git a/App/iec60870/common/README.md b/App/iec60870/common/README.md index b9db1c03..2840834f 100644 --- a/App/iec60870/common/README.md +++ b/App/iec60870/common/README.md @@ -1,6 +1,43 @@ -# Shared codec import +# `common/` — 与传输无关的协议数据面 -Byte-preserved subset of `IEC60870-Slave/common` at baseline f84855a5. -Asdu, Codec, InformationObjects, Slave and Time implement shared protocol data. -FaultEvent is also required by the imported spontaneous Type42 encoder. -Local compatibility patches preserve every compile-time assertion condition. +本目录放 104 协议里**不关心网络怎么收发**的那一半:ASDU 编解码、信息对象(遥信/遥测/遥控/ +累计量)的字段布局、时间表示。要改「报文内容长什么样」在这里;要改「报文怎么送出去」去 +`104/`。这一层同时被 101(串口)等其它 IEC 60870-5 变体共用,所以它刻意不依赖任何网络类型。 + +## 1. 文件分工 + +| 文件 | 职责 | +| --- | --- | +| `IEC60870_Types.h` | 类型与参数基线:应用层参数结构(COT/CA/IOA 各自宽度)、长度上限 | +| `IEC60870_StaticAssert.h` | C99 编译期断言 shim,见 [`../README.md`](../README.md) §3.1 | +| `IEC60870_Asdu.h` / `.c` | ASDU 容器:公共头构造与字段读写(Type ID / VSQ / COT / CA) | +| `IEC60870_Codec.h` / `.c` | 通用字节层编解码:小端读写、长度校验、视图借用 | +| `IEC60870_InformationObjects.h` / `.c` | 信息对象类型(Type 1~207)与品质位、CP56Time2a 等结构 | +| `IEC60870_Slave.h` / `.c` | 101/104 共用的**子站发送接口**(抽象层,用函数指针分派,不含 TCP/串口/队列/连接状态机,不分配内存);104 的具体实现是 `104/IEC104_Slave.c` | +| `IEC60870_Time.h` / `.c` | CP56Time2a / CP16Time2a 编解码与整数公历换算(400 年周期展开、以三月为年内起点统一处理闰日;仅在 1970..2099 年范围内运算,不读 RTC、不执行校时) | +| `IEC60870_FaultEvent.h` / `.c` | Type42 故障事件的扩展布局编解码,见 §2 | + +## 2. 关键约束 + +**`FaultEvent` 不是可选模块,是链接依赖。** `104/business/IEC104_Spontaneous.c` 的 +`IEC104_Spontaneous_Publish_Fault_Event()` 在发布路径上调用 +`IEC60870_FaultEvent_Encode()`。它实现的是 Type42 的**扩展布局**(两组异构记录共用链路 +IOA 宽度、计数位于报文体),不属于基础标准定义的 Type42 对象——所以别拿标准 Type42 的 +字节期望去比对它。 + +**应用层参数必须两端一致。** `IEC60870_AppLayerParameters_t` 定义 Type ID / VSQ / COT / CA / +IOA 各占几个字节以及 ASDU 上限。通用上限是 254;接入本工程 104 TCP 时固定用 +`IEC104_APP_LAYER_PARAMETERS_DEFAULT`(COT=2、CA=2、IOA=3,ASDU 上限 249), +`IEC104_Slave.c` 的 `Parameters_Compatible()` 会拒绝不匹配的配置。改了参数就等于改了线上 +字节布局,主站侧必须同步——不存在自动协商。 + +**断言条件一行都不许动。** 全目录共 43 处编译期断言,本目录分布 3 处 +(`IEC60870_FaultEvent.c` 1 处、`IEC60870_InformationObjects.c` 2 处),其余在 +`104/` 与 `104/business/`。改容量宏时断言条件(如 `SOE_CAPACITY == ASDU_SOE_MAX_CAPACITY`) +保持不变,它守的不变式才有意义。shim 本身见 §1 表首行。 + +## 3. 相关文档 + +- 完整协议栈与目录总览 → [`../README.md`](../README.md) +- 信息对象与品质位口径在平台侧怎么消费 → `App/algo/meas.h` 的 `MEAS_QDS_*` 注释 +- ASDU 头与 COT 宽度 → `docs/子系统设计/IEC104上行设计说明.md` diff --git a/App/iec60870/examples/README.md b/App/iec60870/examples/README.md index 466f5639..b353ad41 100644 --- a/App/iec60870/examples/README.md +++ b/App/iec60870/examples/README.md @@ -1,4 +1,32 @@ -# Declarative DTU profile +# `examples/` — 声明式 DTU 点表 profile -Only `iec104_dtu_profile.h` is imported from the baseline examples directory. -No example main or runtime implementation is compiled in the product. +本目录只有**一份头文件**:`iec104_dtu_profile.h`,用纯数据结构声明标准 DTU +(Distribution Terminal Unit,配电终端)点表——遥信、遥测、遥控、参数各段分别有多少点、 +IOA 怎么分、每个点的类型与元数据是什么。 + +它被 `App/iec60870/104/iec104_dtu_table.c` `#include` 后编译进产品,所以它是 +**实打实的产品代码**,不是示例、不会被排除在构建之外。改这里等于改点表。 + +**本目录没有任何示例 main,也没有运行时实现。** 没被产品链接的文件不要往这里放: +放进来的东西会让人误以为它参与构建。要加运行时逻辑,去 `104/` 或 `104/business/`。 + +## 关键约束 + +- **点表是「标准 DTU 演示表」,不等于现场点表。** 它按 IEC 60870-5-104 标准 DTU(配电终端) + 的典型配置编排,用于把协议栈跑通、把主站侧对点工具点亮,不代表任何现场实际接线。 + 新旧通信地址相同**不代表语义相同**;候选映射不代表真实绑定。当前哪些点真接了硬件来源, + 见 `docs/子系统设计/IEC104上行设计说明.md` 的平台接缝章节。 +- **改点数要同步改别处。** 遥信总数的事实来源是 `App/iec60870/104/iec104_dtu_table.h` 的 + `IEC104_DTU_SP_COUNT`(59,单点遥信 Single Point)与 `IEC104_DTU_DP_COUNT` + (16,双点遥信 Double Point);遥测为 `IEC104_DTU_ME_COUNT`(30,测量值 Measured Value)。 + 而产品 UI 视图的行数 `UI_DATA_YX_N` 是**另一个数**(两者语义不同、数值本就不等)。 + 改动前先读 `Drivers/BSP/UI/ui_data.h` 的 `yx_dp` 字段注释与 `App/app/ui_data_feed.c` + 的 `feed_yx_dp()`——那里有一条一次性 `DBG_ERROR` 专门盯着这个差异。 +- **本文件是 `const` 数据,进 Flash。** 五个表都声明为 `static const`(`dtu_signals` / + `dtu_measurements` / `dtu_energy` / `dtu_commands` / `dtu_parameters`),只需被一个 + 编译单元包含,因此不占静态 RAM;但体积直接影响 Flash 预算。 + +## 相关文档 + +- 完整协议栈与目录总览 → [`../README.md`](../README.md) +- 点表与 UI 视图的语义差异 → `docs/UI设计/UI_数据供给设计.md` diff --git a/docs/子系统设计/IEC104上行设计说明.md b/docs/子系统设计/IEC104上行设计说明.md index 1c8d389b..fec37d76 100644 --- a/docs/子系统设计/IEC104上行设计说明.md +++ b/docs/子系统设计/IEC104上行设计说明.md @@ -9,15 +9,17 @@ ## 0. 成熟协议核心迁入状态与验证边界 -本节说明正在迁入的 `IEC60870-Slave` 产品子集。**下文 §1 至 §8 仍描述既有板端实现及其历史验证,不代表新核心已经替换板端。** +本节说明已迁入的 104 协议栈的验证边界。**下文 §1 至 §8 仍描述既有板端实现及其历史验证,不代表新核心已经替换板端。** > **2026-11-18 补记(旧栈状态已变,此处按日期冻结)**:本节原写「当前旧 asdu/pts/link 与 `App/task/iec104_serv.c` 仍保留;删除旧栈必须在板端切换、资源闭环及实际验证后进行」——**该描述在当天之后失效**:`iec104_asdu/pts/link` 三源在同一日随骨架迁 MCU 删除(`App/task/iec104_serv.c` 被重写为新契约,不再含旧胶水),`App/protocol/` 这一层整体并入 `App/iec60870/`。§1–§8 保留为历史实现记录,其中出现的 `App/protocol/iec104/…` 路径与 `iec104Task` 承载描述均属当时事实;当前结构见 §0.1 与 `App/README.md`。 +> +> **同日起该目录代码已收编为项目自有**:不再是「必须逐字节保真的第三方导入」,按本仓规范维护即可;仓库根 `IEC60870-Slave/` 仅作独立验证基线保留。 ### 0.1 装配与生命周期 | 落点 | 当前职责 | 不能据此推断 | |---|---|---| -| `App/iec60870/` | 成熟 ASDU、Slave、业务状态机、TcpServer 与网络后端;来源见 `App/iec60870/IMPORT.md` | 目录迁入不等于 MCU 集成通过 | +| `App/iec60870/` | 成熟 ASDU、Slave、业务状态机、TcpServer 与网络后端;目录说明与设计约束见 `App/iec60870/README.md` | 目录迁入不等于 MCU 集成通过 | | `App/iec60870/104/iec104_core.c` | `iec104_core_start()` / `iec104_core_poll()` / `iec104_core_stop()` 装配共享核心;`iec104_core_get_status()` 提供状态 | PC 运行不证明 CH395F、RTOS 或板端监听生命周期正确 | | `App/iec60870/104/iec104_source.c` | 数据、模拟动作、参数 RAM 与虚拟设备墙钟;`iec104_source_bind()` 是可选平台接缝 | 接口存在不等于已绑定 UI、保护或标定真源 | | `App/iec60870/104/iec104_dtu_table.c` | 标准 DTU 演示点表与元数据 | 新旧通信地址相同不代表语义相同;候选映射不代表真实绑定 | diff --git a/test/host/iec104_dtu/run_transport_test.py b/test/host/iec104_dtu/run_transport_test.py index 687bad36..dbbbf741 100644 --- a/test/host/iec104_dtu/run_transport_test.py +++ b/test/host/iec104_dtu/run_transport_test.py @@ -25,10 +25,39 @@ def main(): if not cl: raise RuntimeError("MSVC compiler not found") env = dict(os.environ, INCLUDE=os.pathsep.join(inc), LIB=os.pathsep.join(lib)) - sources = [vendor / line.split(" ", 1)[1] for line in (vendor / "UPSTREAM.sha256").read_text().splitlines() if line.endswith(".c")] - # Each fixture includes vendor TcpServer.c and provides the Net implementation. - sources = [p for p in sources if p.name not in ("IEC104_TcpServer.c", "IEC104_Net_Windows.c")] - assert len(sources) >= 26 and all(p.is_file() for p in sources) + # 协议栈源文件清单写死在这里,不再从清单文件推导:App/iec60870 已是项目自有 + # 代码,增删文件时本次修改要同步这张表,别让测试悄悄少编一个单元。 + # 每个夹具自带 TcpServer.c 并自己提供 Net 实现,故这两份不在此列。 + sources = [vendor / rel for rel in ( + "104/IEC104_AsduQueue.c", + "104/IEC104_Codec.c", + "104/IEC104_Connection.c", + "104/IEC104_Link.c", + "104/IEC104_Link_Slave_StartStop.c", + "104/IEC104_Receiver.c", + "104/IEC104_SendBuffer.c", + "104/IEC104_SendManager.c", + "104/IEC104_Slave.c", + "104/business/IEC104_ClockSynchronization.c", + "104/business/IEC104_Command.c", + "104/business/IEC104_CounterInterrogation.c", + "104/business/IEC104_GeneralInterrogation.c", + "104/business/IEC104_Interrogation.c", + "104/business/IEC104_Parameter.c", + "104/business/IEC104_PeriodicScan.c", + "104/business/IEC104_Read.c", + "104/business/IEC104_RemoteParameter.c", + "104/business/IEC104_Spontaneous.c", + "104/business/IEC104_Startup.c", + "104/business/IEC104_SystemCommand.c", + "common/IEC60870_Asdu.c", + "common/IEC60870_Codec.c", + "common/IEC60870_FaultEvent.c", + "common/IEC60870_InformationObjects.c", + "common/IEC60870_Slave.c", + "common/IEC60870_Time.c", + )] + assert len(sources) == 27 and all(p.is_file() for p in sources) include = [vendor / "104", vendor / "104/business", vendor / "common", vendor / "platform", vendor / "examples", original] names = ("iec104_response_transport_test", "iec104_ack_tracking_test", "iec104_idle_transport_test", "iec104_strict_priority_transport_test", "iec104_tcp_event_ring_test", "iec104_tcp_scheduler_test", "iec104_remote_parameter_test") results = []