添加遥控、参数装载、文件传输等业务
CI / L0 静态门禁 (pre-commit) (push) Failing after 7m46s
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 21s

This commit is contained in:
STF
2026-11-16 22:19:17 -08:00
parent e1b0434774
commit bdcc8b6500
288 changed files with 118386 additions and 150057 deletions
@@ -0,0 +1,385 @@
<a id="energy-freeze-design"></a>
# 冻结电能、潮流反转与持久恢复
本文说明当前EnergyFreeze实现的时间窗口、持久记录、封存、XML和宿主模拟计量接线。同步日期为2026-11-14。这里的持久冻结是附录B文件的数据源,与Type101请求中的FRZ命令限定词分开;104计数量请求规则仍由[CounterInterrogation](../104/IEC104_CounterInterrogation_设计架构.md)管理。
接入顺序:[对象生命周期](#energy-freeze-ownership) → [时间与网格](#energy-freeze-time) → [结果处理](#energy-freeze-results) → [存储回调](#energy-freeze-store-contract) → [示例调用顺序](#energy-freeze-integration)。恢复问题见[提交边界](#energy-freeze-commit-order)及[检测能力边界](#energy-freeze-recovery-limits),导出问题见[XML接口契约](#energy-freeze-export-contract)。函数签名集中在[API汇总](../104/IEC104_API接口汇总.md#energy-freeze-api)。
## 1. 模块与所有权
| 文件 | 职责 |
|---|---|
| [IEC60870_EnergyFreeze.h](../../common/IEC60870_EnergyFreeze.h)、[实现](../../common/IEC60870_EnergyFreeze.c) | INTERVAL、DAY、FLOWREV、SEAL和META编码、时间准入、恢复及查询;不依赖104、文件系统或线程 |
| [IEC60870_EnergyFreezeFile.h](../../common/IEC60870_EnergyFreezeFile.h)、[实现](../../common/IEC60870_EnergyFreezeFile.c) | 校验封存并流式生成FRZ/FLOWREV XML;不持有下载会话 |
| [宿主存储适配](../../examples/iec104_example_energy_freeze.h)、[实现](../../examples/iec104_example_energy_freeze.c) | 独占energy.store、双bank提交,以及目录和下载的独立临时文件快照 |
| [模拟计量源](../../examples/iec104_example_energy_meter.h)、[实现](../../examples/iec104_example_energy_meter.c) | 整数方波、八个当前示值、持久示值恢复、校时分段和有界FLOW补算 |
| [主示例](../../examples/iec104_slave_example.c) | CLI、Type206计数量快照、Type210路由及主循环/退出编排 |
核心实例及其存储回调由应用持有;Config和Store结构按值复制,点表、context仍借用。调用方须使这些对象持续有效,串行执行记录、查询、恢复和导出;回调不可重入本实例。核心没有自动采集线程,也不因TCP断线停止计量或删除持久文件。
```mermaid
flowchart LR
Source[采集或模拟计量源] --> Core[EnergyFreeze记录与封存]
Core --> Store[原子持久槽接口]
Store --> Banks[energy.store双bank]
Core --> XML[EnergyFreezeFile校验并生成XML]
XML --> Snapshot[目录及下载临时快照]
Snapshot --> File[Type210文件服务]
Source --> Current[Type206 BEGIN当前值快照]
```
<a id="energy-freeze-ownership"></a>
### 1.1 对象生命周期与并发边界
| 对象 | 所有者与有效期 |
|---|---|
| `IEC60870_EnergyFreeze_t` | 调用方静态分配;公开布局用于分配空间,字段由核心维护,不是应用扩展点 |
| Config、Store结构 | `Init`按值复制;原结构不必持续存在,但其点表指针、回调及`context`须持续有效 |
| 三张IOA点表 | 核心借用,实例使用期间不可修改内容或顺序;点数、单位或映射语义变化须重新设计兼容/迁移策略 |
| 写入的values、quality、indices | 仅在本次同步调用期间借用;成功记录以显式字节格式落到存储 |
| `Read_*`、`Get_FlowReverse`、`Get_Seal`输出 | 调用方持有的副本;不会借出内部`wire`指针 |
| XML配置及sink | 只在一次`EnergyFreezeFile_Write`期间借用;生成的稳定下载快照由宿主适配管理 |
核心没有内部锁;读操作也会复用`wire`,并可能因发现损坏而锁存`faulted`。记录、读取、`Init`、校验和XML生成必须对同一实例及其后端串行执行;同步回调不得重入该实例。只保护写操作不能保证一致性。
正常读写要求`initialized && !faulted`。有效Init在清空内存状态后执行恢复,直到全部校验成功才置`initialized`;存储或内容故障会阻止后续正常访问。重新Init能否恢复服务取决于介质和配置是否通过验证,不能通过直接清`faulted`绕过恢复。
<a id="energy-freeze-time"></a>
## 2. 配置、点序和时间
| 配置 | 默认及限制 |
|---|---|
| interval_ioas / day_ioas、point_count | 默认空;两张表共用点数,上限64,分别规定INTERVAL/DAY值数组的顺序 |
| flowrev_ioas / flowrev_count | 默认空,上限64;单条FLOWREV最多携带8个索引/值/品质 |
| value_semantics | 默认0;由应用标识值的含义、单位及映射版本,参与指纹 |
| day_start_minutes | 默认0,范围0..1425且为15的倍数;固定UTC+8本地日的窗口起点 |
| grid_tolerance_ms | 默认1000,上限60000;冻结时刻与15分钟网格的偏差上限 |
| max_delay_ms | 默认1000,上限900000;采样冻结时刻早于提交观测时刻的最长延迟 |
组内IOA必须为非零24位地址且互不重复。数组顺序是接口语义,不能在Init后重排。三张表的点数、逐项IOA、value_semantics和day_start_minutes共同形成指纹;容差和延迟不参与指纹。配置与已有记录不符返回CONFIG,不能把旧档案当作空库覆盖。
公开时间均为UTC纪元毫秒,支持固定UTC+8本地2000-01-01至2099-12-31。窗口日期由`Window_Day`计算,窗口起点由`Window_Start`返回;不依赖主机当前时区或夏令时。核心不读取墙钟,now与freeze/occur的来源由应用保证。
### 2.1 日序、实际采样时刻与名义网格
`day`是窗口起始本地日期相对1970-01-01的整数日序,不是`YYYYMMDD`。记网格间隔`G=900000ms`、一天`D=86400000ms`、时区偏移`Z=28800000ms`、业务起点偏移`O=day_start_minutes×60000ms`,核心使用:
| 量 | 计算与用途 |
|---|---|
| 记录名义网格`N` | `floor((freeze + G/2) / G) × G`;定位节号,原始`freeze`仍保存在记录中 |
| 窗口日序 | `floor((N + Z - O) / D)`;由`Window_Day(N, ...)`返回,非法日期返回`UINT32_MAX` |
| 窗口起点`S` | `day × D - Z + O`;由`Window_Start`输出UTC毫秒 |
| INTERVAL节号 | `(N - S) / G + 1`;DAY的节号固定为0,名义网格必须为`S` |
| Due候选网格 | `floor(now / G) × G`;只查询已到达的当前网格,不向未来取整 |
例如`day_start_minutes=480`时,11月14日窗口从本地11月14日08:00延续至11月15日08:00之前;第1节和DAY均对应14日08:00,第96节对应15日07:45。窗口由**名义网格**决定:边界前几百毫秒的实际采样若通过容差校验,可能归入下一窗口第1节。
`Record_*`要求`abs(freeze-N) <= grid_tolerance_ms`。若`freeze <= now`,还要求`now-freeze <= max_delay_ms`;若`freeze > now`,则要求其超前不超过`grid_tolerance_ms`。`Due`只在`now`位于当前网格之后的容差内提示INTERVAL,还要满足尚未记录、未封存等条件;它不预判采样品质或替代写入接口的完整准入检查。
以默认1000ms容差、未写入的当前窗口为例:10:14:59.600的采样可由`Record_Interval`归到10:15网格,但此时`Due`不会提示未来的10:15;10:15:00.600会提示10:15;10:15:01.001则已错过本次调度容差。不得把`due.grid_utc_ms`作为实际采样时刻来绕过准入检查。
容差和延迟虽然不参与配置指纹,仍会改变当前准入与封存时机。恢复历史记录时使用格式允许的最大时间容差,不以当前`max_delay_ms`重新拒绝过去记录;派生DAY的`observed`本就可以远晚于原始`freeze`。
实际UTC在公开范围内也不保证归槽成功:世纪起点附近的业务日界可能把日序移到1999年,末尾采样也可能取整到2100年,这些冻结请求会被拒绝。支持2099年末的有效记录,不代表可完成最后一个业务窗口的封存;窗口结束已超出`Advance`接受的UTC范围,当前实现没有范围外封存入口。
<a id="energy-freeze-records"></a>
## 3. 冻结与事件记录
### 3.1 INTERVAL与DAY
一个业务窗口为24小时。INTERVAL第1节对应窗口起点,第96节对应起点后23小时45分;DAY对应同一窗口起点。它们不沿用History定点模块的第1节00:15约定。两类记录均保存来源示值,核心不计算相邻示值差分或日用电量。
`Record_Interval(now, freeze, values, quality, count)`和`Record_Day`把freeze归到最近的15分钟网格,检查容差、提交延迟、保留窗口、封存状态及该类已写最大网格。品质非零或非有限值返回SKIPPED,不落部分点;DAY还要求命中窗口起点。now小于已观测高水位返回TIME_REVERSED。合法快照不允许覆盖同网格不同内容:相同值和品质返回DUPLICATE,不同返回CONFLICT;旧网格返回TIME_REJECTED。
`Derive_Day(now, day)`直接读取该窗口已存第1节,复制值、品质和原freeze时刻,使用当前now作为DAY的observed时刻。即使补的是较早窗口,DAY已写最大网格也只取max,不倒退。它不重采当前示值,不将第2节或其他节冒充第1节;来源缺失返回EMPTY。
重复判断只针对该类最新名义网格,比较`count`、值的原始字节和品质,不比较`freeze/observed`;正负零的位差也构成不同内容。较旧网格即使值相同也会被拒绝。`Derive_Day`是允许补较早窗口的独立路径,不能借此覆盖已有不同内容的DAY。
### 3.2 FLOWREV事件
FLOWREV独立按到达顺序分配不回绕的64位序号,保存最近256条。每条包含1..8个严格递增的配置索引,occur时刻允许倒退,不推进冻结观测高水位。最近16条按发生时刻、索引、值的原始字节和品质完全相等去重。单条中的坏品质/非有限值可以留存,XML只输出有效项;这些不完整或无效事件不用于示例计量恢复。
`indices`是`flowrev_ioas`的0起始下标,不是IOA本身;配置表最多64点,单条最多引用其中8点。序号从1开始,满256条覆盖最旧事件;`Get_FlowReverse`的`oldest_index=0`总是当前保留区最旧序号,与物理槽0无关。去重只覆盖最近16条;超出该范围的相同输入可能形成新事件。序号到`UINT64_MAX`后返回ERROR而不回绕,该分支本身不锁存故障。
<a id="energy-freeze-results"></a>
### 3.3 返回值与状态副作用
下表省略`IEC60870_ENERGY_FREEZE_`前缀。正值不都表示新记录已提交,负值也不都表示实例已故障。
| 返回值 | 触发含义 | 调用方处理 |
|---|---|---|
| `OK (1)` | 请求成功;`Advance`也可能只推进时间,没有新封存 | 按接口含义继续;通过状态确认封存前沿/积压 |
| `EMPTY (0)` | 无到期任务、普通缺测、无封存或事件下标越界 | 保持缺失语义,不生成替代记录 |
| `DUPLICATE (2)` | 最新冻结位置内容相同,或FLOW命中去重窗口 | 无新提交;不把重交算成新增事件 |
| `SKIPPED (3)` | INTERVAL/DAY任一点品质非零或值非有限 | 整条跳过,禁止只写部分点 |
| `INVALID (-2)` | 参数或初始化配置非法 | 修正输入;非法Init参数在清空实例前就返回 |
| `TIME_REVERSED (-4)` | 传入now低于观测高水位W | 本次不推进W;保留原高水位等待时间追平 |
| `TIME_REJECTED (-5)` | 时间容差/延迟、保留边界、封存状态或写入顺序不允许 | 不覆盖旧记录,不用改写采样时刻的方式重试 |
| `CONFLICT (-6)` | 同一冻结位置已存在不同值或品质 | 保留先前内容,由应用诊断来源或调用错误 |
| `CONFIG (-3)` | 已提交记录的配置指纹与当前配置不符 | 核心锁存故障;恢复匹配配置或采用明确的迁移流程 |
| `ERROR (-1)` | 实例未就绪、存储/内容错误,或FLOW序号耗尽 | 结合`Get_Status`判断;读坏/提交失败后停止正常服务,重新Init核验 |
`Record_Interval`、`Record_Day`及`Derive_Day`在基本参数和回拨检查通过后就推进RAM中的W;后续返回TIME_REJECTED、SKIPPED、DUPLICATE、CONFLICT或EMPTY仍可能已改变W。`Due`和查询接口不推进W。`Advance`返回OK不承诺这次观测时间已经持久化,具体恢复规则见[观测状态](#energy-freeze-sealing)。
带`out`的记录/事件/封存读取和`Due`只在OK时填写输出,调用方不能在EMPTY或失败后使用旧输出。`Get_Status`返回bool,允许诊断`faulted`实例;Init中途失败时状态可能只是部分恢复结果。`FlowReverse_Count`在未就绪或故障时返回0,不能单凭0判断事件库为空。错误码与实例健康状态须分别处理。
<a id="energy-freeze-sealing"></a>
## 4. 观测高水位、封存与恢复
### 4.1 内存状态与持久事实
| 状态 | 含义 |
|---|---|
| observed_utc_ms | 已观测now的高水位;回拨时保留旧值,恢复从有效持久事实取最大值 |
| latest_interval / latest_day | 两类记录各自已写最大名义网格;补旧DAY不降低它 |
| retained_from | 当前32个业务窗口的保留下界;复用旧槽前先持久推进此下界 |
| present[32][13] | 每窗口96个INTERVAL及一个DAY的存在位图,不保存点值 |
| sealed_day / seals | 连续封存前沿和各槽封存状态;SEAL是文件可导出的依据 |
| flow_sequence / flow_count | FLOWREV最大序号及保留条数,与墙钟顺序无关 |
W在实例存活期间单调,但不是每次更新都单独提交META。恢复取META及所有有效非FLOW记录的`observed`最大值,已过保留期的合法记录也参与此最大值计算;只存在于RAM、尚未随任何记录/META持久化的观测时间,重启后可能丢失。`latest_interval/latest_day`则从保留区有效记录的名义网格重建。
### 4.2 有界封存与调度查询
`Advance(now)`更新观测高水位,每次至多封存一个满足`窗口结束 + max_delay_ms <= W`的窗口。SEAL保存97位存在图、记录数和规范内容摘要,空窗口也有SEAL。摘要按小端日序、完整13字节位图、INTERVAL节序再DAY连接记录正文,排除每条记录自身尾CRC,避免把固定CRC余数误当成内容校验。封存后不允许补写该窗口。
`Due(now)`只查询当前窗口可写的INTERVAL和已有第1节可派生的DAY;没有任务返回EMPTY且不修改输出,不补造错过网格的值。32窗口轮转前先提交META,丢弃尚未封存但已有数据的旧窗时累计evicted_unsealed;Status同时提供seal_backlog,应用持续有界推进,不以导出触发补写。
32窗口指保留日序范围`[R, R+31]`,不是最近32个非空窗口。写入日期跨出范围时,新的`R=day-31`;无数据空窗被淘汰不计损失,有数据但未封存的窗口计入`evicted_unsealed`,计数在`UINT32_MAX`饱和。`Get_Seal`只验证封存记录自身;需要核对正文时使用`Validate_Seal`或文件导出的一遍校验。后两者连位图为0的位置也读取,以检测意外新增记录。
### 4.3 Init恢复顺序
正常完整扫描共3393次逻辑read且不写介质;遇错立即停止,不一定读完全部槽位。顺序如下:
1. 读META,取保留下界R、封存前沿提示、FLOW序号下界及持久观测时间;只有全空存储允许没有META。
2. 读全部SEAL,建立各物理窗口的位图及期望摘要;先读SEAL可让后续数据扫描直接累计摘要。
3. 按物理顺序扫描INTERVAL,再扫描DAY。每窗的摘要顺序为I1..I96、DAY;恢复存在位、两类最新网格及W。
4. 扫描FLOWREV,结合序号与物理槽关系检查最大序号、最小序号及保留条数是否构成最近连续事件段。
5. 验证保留范围内SEAL从R起连续,位图与实际记录完全一致、摘要相符;META有效前沿提示若不早于R,就不能超过已验证前沿,早于R的旧提示则忽略。全部通过才置`initialized`。
每条记录都先检查魔数、版本、长度、CRC、指纹、类别、物理槽及业务字段,再按保留边界过滤。旧日期残留中的已提交损坏也会阻止恢复,不能因为过期而隐藏。已知SEAL存在时,其数据丢失或被替换不能降为“缺测”。
FLOWREV同时核对保留序号连续性、条数和META中的持久序号下界,防止丢失最新尾部后悄悄缩短历史。记录已提交而随后META提交未完成时,恢复以有效记录事实补足状态;返回失败不意味着介质没有变化。
<a id="energy-freeze-commit-order"></a>
### 4.4 提交顺序与中断后的可见结果
以下每个箭头两侧都是独立原子槽提交,整个业务调用不是跨槽事务。任一commit返回false,本次实例都进入`faulted`;表中结果须经重新Init核验后才能使用。
| 操作 | 持久顺序 | 中断后的恢复含义 |
|---|---|---|
| 首次INTERVAL/DAY | 建立含R的META → 写记录 | META已提交但正文未提交时,可恢复为已建立保留区、该位置仍缺测 |
| 已建立窗口的普通记录/派生DAY | 写记录;通常无需再提交META | 记录的有效提交状态决定是否存在;返回失败后也可能读到新记录 |
| 封存已有窗口 | SEAL → 更新META前沿提示 | SEAL已提交、META滞后时,按SEAL事实恢复;不能因调用失败允许重新补写 |
| 新日期复用旧数据槽 | 推进R的META → 新记录 | 边界成功而正文未完成时,旧窗已淘汰,新位置仍可缺测;不能恢复旧R冒充仍保留 |
| 封存跨出当前保留范围 | 推进R的META → 新SEAL → 更新META提示 | 先淘汰旧SEAL槽的日期,再复用;允许META提示暂时落后实际封存 |
| 追加FLOWREV | 首次先建META;随后事件 → 更新META序号下界 | 事件事实可领先META;恢复必须同时核对连续序号和已有META下界 |
这也解释了为何返回ERROR后不能在原实例直接重试:调用方不知道哪一个独立提交已落盘。重新Init本身只做验证和状态重建,不回填滞后的META,不格式化、不修复损坏记录。
<a id="energy-freeze-recovery-limits"></a>
### 4.5 检测能力边界
恢复依据是**仍可读取的记录与META见证**,没有独立的完整写入日志或防回滚根。下列情况应区分,不能统一宣称任何历史丢失都能检出:
| 情形 | 当前实现能判定的范围 |
|---|---|
| 后端仍看到已提交标记,但头、载荷或CRC损坏 | 必须报错;后端不能退回旧版本并伪装成功,核心也不把它当EMPTY |
| 活实例中,RAM位图已知存在的数据突然缺失 | 读取该位置会锁存故障;已知封存正文的缺失、增添、替换还受SEAL摘要约束 |
| 重启前未封存记录已完全消失,后端只能返回EMPTY或合法旧日残留 | 没有持久存在位图可证明它曾写入,可能与原本缺测无法区分;Init会据现存事实重建 |
| 最新SEAL曾提交、META提示仍滞后,而该SEAL随后完全消失 | 若剩余SEAL仍连续、META不要求更高前沿,可能恢复为未封存;后续SEAL或META前沿能提供缺失见证 |
| 最新FLOW曾提交、META下界仍滞后,而事件随后丢失或回退 | 若剩余事件仍满足连续性及META下界,核心无法推断曾有更高序号;META已成功记下的尾部下界不能静默退回 |
后两类描述的是后续介质丢失/回退导致的证据消失,与“提交中断但有效事实仍在”不同。CRC用于内容一致性检查,不提供密码学防篡改。核心全槽EMPTY可初始化为空库;宿主文件头检查及原子bank契约只能在其可见证据范围内加强检测,不能替代应用所需的外部完整性或恢复策略。
<a id="energy-freeze-storage"></a>
## 5. 线格式与宿主持久文件
<a id="energy-freeze-store-contract"></a>
### 5.1 可移植存储回调契约
核心只认识`(kind, index)`逻辑槽,`Slot_Count(kind)`返回各区域的槽数;未知类别返回0。物理bank、擦写粒度和文件偏移属于后端,不能泄漏为核心索引。
| 类别 | 逻辑索引 |
|---|---|
| INTERVAL | `(day % 32) × 96 + slot - 1`,slot为1..96 |
| DAY / SEAL | `day % 32` |
| FLOWREV | `(sequence - 1) % 256`,sequence从1起 |
| META | 固定0 |
`read(context, kind, index, bytes, capacity, size)`同步完成:OK表示已复制整条已提交记录并填写实际size,EMPTY仅表示没有已提交记录;读取失败或已提交损坏必须报错。不得截断后仍报告OK,也不得将CRC错误转换为EMPTY。
`commit(context, kind, index, bytes, size)`在返回true前须原子、持久地替换指定槽;返回false可能发生在新值已经提交之后。两个回调都不能保留核心的缓冲指针。原子替换保证由后端实现,核心CRC本身不提供原子性;一次业务调用中的多个逻辑槽提交顺序见[提交边界](#energy-freeze-commit-order)。
### 5.2 核心规范字节格式
内部记录采用显式小端字段,不写C结构体镜像。公共头为44字节,尾CRC为4字节;与早期草案的36字节头及360字节工作区不同,当前需要同时保存freeze和observed时刻。
| 头偏移 | 字段 |
|---|---|
| 0..7 | EFZ1、版本1、类别、点数、保留字节 |
| 8..11 | 配置指纹 |
| 12..19 | 序号;FLOWREV使用,其余按各类规则填写 |
| 20..27 | freeze/occur或封存窗口结束时刻 |
| 28..35 | observed时刻 |
| 36..41 | 窗口日序及节号 |
| 42..43 | 保留字节 |
| 类别 | 载荷 | 最大记录长度 | 逻辑槽数 |
|---|---|---:|---:|
| INTERVAL | 每点binary32值4字节+品质1字节 | 368 | 3072 |
| DAY | 同INTERVAL | 368 | 32 |
| FLOWREV | 每点索引1字节+值4字节+品质1字节 | 96 | 256 |
| SEAL | 位图13字节、计数1字节、摘要4字节 | 66 | 32 |
| META | 封存前沿、保留下界、淘汰计数、状态及FLOW序号下界 | 72 | 1 |
SEAL/META载荷采用以下固定偏移,偏移相对整条记录起点;不是相对载荷起点:
| 类别 | 偏移与字段 |
|---|---|
| SEAL | 44..56:13字节位图(位0..95为INTERVAL,位96为DAY,其余位为0);57:置位数;58..61:内容摘要;62..65:单记录CRC |
| META | 44..47:封存前沿提示;48..51:保留下界;52..55:淘汰计数;56:有效位;57..59:零;60..67:FLOW序号下界;68..71:单记录CRC |
META的有效位bit0表示保留下界有效,bit1表示封存前沿提示有效;bit1成立须同时有bit0。无效字段编码为0,不能只依据日期字段是否非零判断状态。SEAL的count统计记录位置,不统计点数;空窗count为0仍有完整合法SEAL。
整数以小端读写,float以binary32原始位编码,不以文本浮点或结构体内存代替。单记录CRC-32使用反射多项式`0xedb88320`、全1初值及最终取反;SEAL的整体摘要使用相同递推,但其覆盖顺序和排除尾CRC规则见[封存流程](#energy-freeze-sealing)。头内未使用字段和保留字节须符合各类别的零值规则,不能随意扩展而仍沿用v1版本号。
### 5.3 Windows双bank适配
宿主使用独占`energy.store`,与history.store和ulog.store分离。文件头32字节,包含`IEC104-ENERGY1`、最大点数64、窗口32、事件256及头CRC;每个逻辑槽有两个bank,各自增加32字节头,包含EZL1、有效长度、代次、头/载荷CRC和提交标记。
| 区域 | 起始偏移 | 每bank字节 | 双bank区域字节 |
|---|---:|---:|---:|
| 文件头 | 0 | — | 32 |
| INTERVAL | 32 | 400 | 2457600 |
| DAY | 2457632 | 400 | 25600 |
| FLOWREV | 2483232 | 128 | 65536 |
| SEAL | 2548768 | 98 | 6272 |
| META | 2555040 | 104 | 208 |
布局末端为2555248字节;偏移固定,不因本次只配置8点而缩小。文件按写入位置增长,未写区域按未提交槽处理;已有零长度文件、头不符或超过布局末端的文件拒绝打开。
提交选择较旧bank,依次执行“清提交标记并同步 → 写完整候选并同步 → 写有效标记并同步”,每阶段调用FlushFileBuffers。提交前中断可以继续使用旧有效版本。任一带有效提交标记的bank发生头/载荷校验错误,都使逻辑槽失败,不回退旧bank掩盖已提交损坏;同代次但内容不同也失败。
常规FLOWREV先提交事件,再提交META,通常需要两次逻辑commit、六次同步;首条建立META还可能增加一次提交。任意commit失败后核心进入faulted,应用停止服务并重新打开/Init恢复,不在原实例盲目重试。同步API和故障注入测试不等于已经验证目标介质的真实掉电保证。
<a id="energy-freeze-xml"></a>
## 6. FRZ/FLOWREV与不可变下载快照
FRZ路径为`HISTORY/FRZ/frzYYYYMMDD.xml`,日期是业务窗口起始日。只导出最近30个已封存窗口中的非空文件;缺窗不向更早日期补足30份。非空文件在一遍读取中核对SEAL位图、摘要并输出候选XML,全部成功才对外发布;声称为空的窗口也必须验证,不能用“没有数据文件”绕过封存完整性检查。XML包含FixFrz、DayFrz元数据及实际存在的记录;各点单位分别配置,不把无功电能统一写成kWh。
FLOWREV路径固定为`HISTORY/FLOWREV/flowrev.xml`,启用事件表后允许生成num=0空文件。事件按持久序号顺序导出,单条内按配置索引顺序输出有效DI;num统计DI数量,不是事件条数。发生时刻可以乱序;文件时间取最新序号事件的occur,不把排序改成墙钟排序。
XML生成是同步、串行的流式输出,写回调只借用当前片段;失败时丢弃整份候选文件。设备名和单位须为合法UTF-8/XML属性内容并转义特殊字符;数值输出处理主机locale的小数分隔符。XML不是恢复计量状态的输入,恢复只读二进制记录。
宿主每实例允许一个活动目录和一个下载。打开目录时一次冻结清单、文件名、大小、时间及所有XML到临时文件;关闭目录枚举后保留该版本,随后按名字打开下载时复制成独立快照。新冻结、新目录或循环覆盖不改变已打开下载。直接按完整名读取也遵守封存和保留窗口规则。退出先清理Type210会话,再关闭临时文件和energy.store。
<a id="energy-freeze-export-contract"></a>
### 6.1 名称、时标及输出回调
`EnergyFreezeFile_Name`只格式化相对路径,不检查记录是否存在;FRZ使用业务窗口日序,FLOWREV忽略day。capacity包含结尾NUL,失败时保持name原内容。`EnergyFreezeFile_Write`返回true才表示整份候选成功,size非NULL时写回总字节数(不含NUL);失败保持size原值,但sink可能已收到部分甚至大部分XML。
| XML项目 | 数据含义 |
|---|---|
| FRZ `dataNum` | 每条记录的配置点数 |
| FRZ `sectNum` | 实际存在的INTERVAL节数,不含DAY;缺节保留原节号,不重新编号 |
| FixFrz / DayFrz元数据 | 两组均输出,即使其中一类没有数据记录 |
| FRZ时标 | 固定UTC+8的名义网格,精确到秒;第1节和DAY用窗口起点,不输出采样偏差 |
| FLOWREV时标 | 原事件occur转固定UTC+8,保留毫秒;同一事件各有效点共享时标 |
| FLOWREV `num` | 有效DI数量,先遍历统计、再遍历输出,因此两遍之间也必须独占输入 |
sink返回true表示当前length字节已完整接收,false立即中止。bytes仅在回调内有效,不含结尾NUL;片段不保证按XML节点或UTF-8字符分界。调用方先写入独立候选,待整个Write成功后再发布;不能一收到片段就把它作为已验证文件提供给下载端。
设备名与逐点单位按UTF-8原文传入,不预先XML转义;属性最多255字节,不含NUL。编码器验证UTF-8最短编码及XML合法字符、转义特殊字符,并以字符引用保留属性中的换行/制表符。数值采用9位有效数字,规范小数分隔符为`.`,不修改进程locale。
Write返回false还可能表示空FRZ、超出导出窗口、非法配置或sink失败;这些本身不等于核心故障。存储/封存完整性失败会锁存`faulted`,可通过`Get_Status`区分。即使结果为false,也必须丢弃本次候选;空FRZ仍执行封存完整性验证。
<a id="energy-freeze-meter"></a>
## 7. 示例计量、恢复与校时
主示例通过`--energy-freeze existing-directory`启用该数据源和Type210,使用Type206及全组读取QCC=0x05;这是应用选择,不裁剪通用计数量库。未开启时仍保留既有RAM计数量演示。`--energy-period-ms`接受2000..86400000且为4倍数,默认1200000。
模拟源使用六个独立非负整数累加器,顺序为P+、P-、Q1、Q2、Q3、Q4,单位Wms/varms,初始基线全部为零。一个周期四等分:P前半为+400000W、后半为负;Q第一及第四段为+150000var,其余为负,四段依次累计Q1、Q4、Q3、Q2。每个独立寄存器为累加器除以3600000的整数部分;两个无功合计由四象限整数相加。
八值顺序固定为`P+、Q+、Q1、Q4、P-、Q-、Q2、Q3`,编码为`(float)((double)R / 1000.0)`。Evaluate_At根据恢复基线、完整周期导通时间和相位重叠毫秒直接计算,受检加乘,不依赖调用次数或上次输出。它没有“取max上次输出”的缓存;先读取较新当前值再补旧FLOW,旧事件仍携带其真实历史值。Snapshot只编码纯查询结果并返回零品质。
### 7.1 启动示值恢复
恢复收集保留范围内的INTERVAL、DAY,以及恰含索引0..7、品质全零、数值有限的完整FLOWREV。候选按全部八个binary32值字典序排列,再检查相邻向量逐分量不下降;互不支配表示来源不一致,停止启动。只有八值全部相同才可互换,不能只比较六个独立量,也不能用浮点总和排序。
最后的最大向量通过encode的单调二分查找得到各整数原像。六个独立量先与`[0,2562047788015]`相交,选择最接近`double(v)*1000`的整数,同距取小;两个无功合计再与分量区间和求交并拆分。合计不受单个累加器上限限制,但必须位于其编码原像。恢复后八值全部重新编码并逐字节匹配,独立量受检乘以3600000写入基线。
该过程要求binary32、至少53位有效二进制double、FLT_EVAL_METHOD=0及最近偶数舍入模式。它避免`ceil(v*1000)`引入1Wh到2Wh的虚增,也能处理六独立float相同但合计不同的记录。恢复丢弃原累加器不足1Wh/varh的余数;最后一份可恢复记录之后的积分也可能丢失,不保证固定15分钟损失上界,不提供精确计量检查点。
### 7.2 分段墙钟与有界FLOW
启动有效墙钟建立首个单调时刻/UTC基准;成功校时后,动作回调之外调用Set_Epoch加入新的切换点。这里使用ClockSynchronization的执行检查base_ms作为应用逻辑切点,不声称是RTC硬件实际生效时刻。Energy只使用自身分段时钟,不自动跟随主示例每60秒的系统时钟刷新。
P每半周期产生一个反转,事件时刻为`origin + k*T/2`,k从1开始。事件值用该时刻的Evaluate_At;发生UTC使用最后一个不晚于该事件的基准。16段队列保留尚未消费事件需要的映射,已提交事件不重标。满队列时丢弃最老时段尚未产生的事件并累计flowrev_dropped。
每次Step至多提交4条FLOW,积压超过256仅保留最新256条并计数;当前Type206和定时冻结不等待FLOW追完。随后Advance,再根据Due记录当前值或由已存第1节派生DAY;TIME_REVERSED只暂停定时冻结,不暂停FLOW。任何持久失败、时间准入缺陷或数值溢出使meter锁存faulted,应用退出,不重做失败提交。
QRP1保留整个meter、分段时钟和energy.store;206在BEGIN获取一轮独立快照,WAIT不重采。它不与普通遥信总召、NORMAL事件队列或文件下载共用候选帧。
<a id="energy-freeze-integration"></a>
### 7.3 主循环的一轮接入顺序
当前顺序由[Example_Energy_Meter_Step](../../examples/iec104_example_energy_meter.c)实现:
1. 将本轮单调时刻映射为UTC,裁剪FLOW积压并按既定预算提交历史事件;事件示值按各自发生时刻求值。
2. 清理已不再使用的墙钟分段,再调用`Advance(now)`;发生TIME_REVERSED时本轮结束,先前的FLOW处理已经完成。
3. 调用`Due(now)`。EMPTY表示本轮没有冻结/派生任务;OK时分别检查interval、derive_day标志。
4. 若interval为true,获取当前采样快照并调用`Record_Interval`。示例传本次真实映射UTC作为now及freeze,不传调度名义网格冒充采样时刻。
5. 成功写入INTERVAL后**再次调用Due**,以便刚写入第1节时在同一轮发现待派生DAY。
6. 若derive_day为true,调用`Derive_Day(now, due.day)`;来源是已存第1节,不再次采样。
主循环将OK/DUPLICATE视为已接受,EMPTY/SKIPPED按接口含义结束当前工作;其他异常按示例策略锁存meter故障并停止后续提交。核心支持`Record_Day`直接接收窗口起点快照,当前模拟源选择第1节派生路径。文件目录和下载只消费已形成的数据,不驱动补采、补写或封存。
<a id="energy-freeze-resources"></a>
## 8. 资源、验证与移植范围
2026-11-14在Windows x64 MinGW GCC、`-std=c99 -O2 -Wall -Wextra -Werror -pedantic`下实测:
| 对象 | sizeof/容量 |
|---|---:|
| EnergyFreeze核心 | 960字节 |
| Record / FlowReverse | 352 / 72字节 |
| Seal / Status | 40 / 56字节 |
| ExampleEnergyFreeze,含核心、目录项及两个bank缓冲 | 4776字节 |
| ExampleEnergyMeter,含16段时钟 | 360字节 |
| 核心wire工作区 | 368字节,已包含于核心实例 |
| meter启动排序候选 | 最多3360×8×4=107520字节临时Windows堆 |
排序工作区通过HeapAlloc申请,恢复返回前HeapFree;失败明确结束启动,不把105KiB放到栈或常驻实例。板端移植必须另行选择恢复排序工作区和原子存储适配,不能照搬宿主堆与FlushFileBuffers保证。
GCC `-fstack-usage`报告meter的单函数静态栈:Evaluate_At 160字节、Snapshot 160字节、Step 192字节、Restore 560字节,逆像恢复主要内部函数400字节。它们不是调用链峰值,也不是ARMCC或硬件任务栈验收值。
同机GCC `-O2 -fstack-usage`下,核心Init/Derive_Day/Advance单函数帧分别为912/784/144字节,XML Write为688字节,宿主Open/Directory_Open/Read_Open/Store_Commit为896/336/496/208字节。最大启动调用链还需叠加核心恢复与宿主读取;上述数字不能直接当作所需任务栈。测量产物位于本目录`.build/energy-freeze-final-measure.su`和`.build/energy-freeze-stack-20261114/`。
一次非空FRZ编码使用GetSeal及97个记录位置,共98次逻辑读取;宿主目录另外读取一次SEAL判定是否为空,合计每窗99次。30个完整窗口、每窗96节加DAY、每条8点的宿主样本生成703222字节XML,目录打开实测503.843ms,共2970次逻辑read、5940次bank读取。该数值只描述这份Windows样本,不作为64点、其他磁盘或板端响应时限保证;目录生成仍为同步操作。
[meter专项](../../test/iec104_example_energy_meter_test.c)的9组已实跑通过,包含200000次确定种子原像/固定点测试、四象限精确整数期望、跨校时和回拨、有界长步补算、源不一致、近上限与失败隔离。两秒周期跨一天产生86400个反转候选,计数丢弃86144个,256个保留事件分64轮提交,较新读取不污染旧事件值。
核心、XML、宿主故障注入及TCP测试入口统一为:
```powershell
./scripts/build.ps1 -Test -Suite EnergyFreeze
```
<a id="energy-freeze-verification"></a>
### 8.1 设计约束与现有验证入口
下表用于从设计定位回归用例,具体执行日期和结果集中在[电能量冻结测试说明](../test/IEC104测试文档.md#energy-freeze-tests),不将本文更新视为重新执行测试。
| 设计约束 | 现有验证入口 |
|---|---|
| 网格/日界、回拨高水位、同网格重复及冲突、派生DAY、32窗口保留 | [核心专项](../../test/iec60870_energy_freeze_test.c):`test_record_time_and_duplicates`、`test_derive_maximum_and_due`、`test_offsets_tolerance_and_calendar_edges`等 |
| SEAL连续性、META滞后、过期损坏仍报错、FLOW连续序号 | [核心恢复用例](../../test/iec60870_energy_freeze_test.c):`test_seal_meta_failure_and_manifest`、`test_meta_empty_hint_and_stale_corruption`、`test_flow_dedup_and_recovery` |
| 缺节不改编号、单位区分、失败size不变、FLOW过滤及DI计数 | [XML专项](../../test/iec60870_energy_freeze_file_test.c):`Test_Frz`、`Test_Flow` |
| 等长合法正文替换并重算单条CRC仍被SEAL检出;读取途中替换不发布候选 | [XML完整性用例](../../test/iec60870_energy_freeze_file_test.c):`Test_Seal_Replacement` |
| bank损坏不能静默退回、META已记下的FLOW尾部丢失、打开的下载不随新目录变化 | [宿主持久适配专项](../../test/iec104_example_energy_freeze_test.c) |
| 首次META、普通记录、DAY派生、SEAL→META、先淘汰再复用的分阶段失败恢复 | [提交中断矩阵](../../test/iec104_energy_freeze_transitions_test.c) |
| 八值原像恢复、分段校时、旧事件值稳定、每轮FLOW预算、失败隔离 | [模拟计量专项](../../test/iec104_example_energy_meter_test.c) |
| Type210目录与下载、96节+DAY、XML解析、跨进程重启与字节一致性 | [TCP回环](../../test/energy_freeze_loopback_test.cjs) |
编码实现还包含UTF-8/XML字符及locale处理规则,以上用例不代表每一种字符边界、运行时locale或目标编译器均已覆盖。现有同步故障注入、宿主回归和资源数据不替代实际主站互操作或真实介质掉电验收;当前没有板端Flash磨损、恢复时延上限、采集接线或硬件计量精度的验收结论。
@@ -0,0 +1,290 @@
# IEC60870 故障事件信息设计
本文定义 Type42 `M_FT_NA_1` 的扩展格式编解码,以及通过 Spontaneous 发布故障快照的接入契约。公共接口见 [IEC60870_FaultEvent.h](../../common/IEC60870_FaultEvent.h),104 发布入口见 [IEC104_Spontaneous.h](../../104/business/IEC104_Spontaneous.h)。所有实现和验证范围均限于 IEC60870-Slave。
阅读导航:[协议依据](#fault-event-profile) · [报文布局](#fault-event-wire) · [校验顺序](#fault-event-validation-order) · [时标语义](#fault-event-time) · [内存所有权](#fault-event-ownership) · [模块分工](#fault-event-integration) · [上送流程](#fault-event-publish) · [错误处理](#fault-event-errors) · [资源与验证](#fault-event-validation)。
<a id="fault-event-profile"></a>
## 1. 协议依据与兼容范围
业务依据是项目所附[配电自动化实施细则](../../20170804163032284877151.pdf)的 §7.5、§8.1.6:Type42、COT=3,故障发生时上送对应遥信和故障时刻测量值,内容至少包含三相及零序电压、电流,并早于故障录波数据。该格式属于配电实施细则扩展,不能把它描述成基础 IEC 101/104 已定义的通用 ASDU。
具体线格式依据用户提供的主站接收端解析分析:101、104 均按两组数量、类型及记录解析故障事件,再交给故障事件页面显示。本文记录这份对接约定,不把接收端静态分析结果称作已完成主站实机联调,也不将该扩展格式描述为基础标准强制要求。
| 差异或疑点 | 本实现约定及原因 |
|---|---|
| 实施细则第19页未标注遥测数量、类型长度 | 按已确认的主站接收端布局使用各1字节 |
| 实施细则故障遥信点号为2字节 | 按已确认的接收端约定,遥信和遥测都使用链路的 `sizeOfIOA`;104 为3字节,不单独硬编码遥信2字节 |
| 模板参数 `0x9119` | 用户确认当前主站解码路径不使用它;本实现不据此改变故障遥信地址宽度 |
| 遗留 DLL 的独立遥信地址长度接口 | 不作为当前运行解析器的兼容依据;将来需要其他格式时应显式增加独立配置及测试 |
| VSQ | 发送固定 `0x01` 占位;解析数量来自报文体,不根据 VSQ 的数量或 SQ 位定位记录 |
| 内部类型值 | 只支持明确的遥信1/3/30/31、遥测9/11/13,不沿用接收端将其他编号归入默认类型的行为 |
<a id="fault-event-wire"></a>
## 2. 完整 ASDU 布局
公共头仍按应用层参数编码,记 `H = 2 + sizeOfCOT + sizeOfCA`、`L = sizeOfIOA`。下表从 ASDU 的 TI 开始,不包含104的6字节 APCI。
| 顺序 | 字段 | 字节数 |
|---|---|---:|
| 1 | TI=42、VSQ=0x01 | 1+1 |
| 2 | COT=3、可选 OA、公共地址 CA | `sizeOfCOT + sizeOfCA` |
| 3 | 遥信个数 N、遥信类型 | 1+1 |
| 4 | N条遥信:IOA、SIQ/DIQ、CP56Time2a | 每条 `L+1+7` |
| 5 | 遥测个数 M、遥测类型 | 1+1 |
| 6 | M条遥测:IOA、数值 | 每条 `L+D` |
公共头后直接是 N,不存在普通信息对象结构中的额外外层 IOA。所有多字节整数采用低字节在前;遥测类型13的 `D=4`,类型9/11的 `D=2`。遥测没有 QDS,也没有自己的时标。遥信类型即使选择1或3,也仍然有完整 CP56Time2a。
完整长度为 `H + 4 + N*(L+8) + M*(L+D)`。例如104参数2/2/3、1条遥信、8条浮点遥测占77字节 ASDU,连同 APCI 为83字节。数量字段可表示0..255,实际可放记录数还受单帧容量约束;不能仅按数量字段的上限分配或接收。
当前104发布入口限制总长不超过249字节。超长报告返回输入错误,整份不入队;不自动拆成多个 Type42,因为当前格式没有事件编号和分片关联字段,擅自拆分会改变故障快照的含义。
### 2.1 容量与记录定位
104使用 `H=6`、`L=3`,浮点遥测使用 `D=4`,因此总长为 `10 + 11*N + 7*M`。下表仅判断结构和容量,业务发布还须通过站点、点号及记录内容校验。
| 遥信数 N | 浮点遥测数 M | ASDU字节数 | 编码与发布边界 |
|---:|---:|---:|---|
| 0 | 0 | 10 | 公共编解码允许;业务入口拒绝空报告 |
| 1 | 8 | 77 | 满足最少记录数;内容合法时可整份发布 |
| 2 | 31 | 249 | 恰好达到104单帧上限 |
| 4 | 28 | 250 | 公共Encode在249字节容量下返回FULL;业务发布返回INPUT,不能等待后再按原样提交 |
两组数量和类型字段始终存在;数量为0时只省略记录,不省略类型。以从TI起算的0基字节偏移表示,N/type位于 `H/H+1`,首条遥信从 `H+2` 开始,M/type位于 `H+2+N*(L+8)` 及其后一字节,首条遥测从 `H+4+N*(L+8)` 开始。1遥信、8浮点遥测的例子中,M/type在19/20,首条遥测从21开始;不能把这些示例偏移写死用于多遥信报文。
<a id="fault-event-data"></a>
## 3. 公共数据结构与字段校验
`IEC60870_FaultEvent_t` 借用两组数组,分别描述遥信与遥测;数组类型及数量独立。`IEC60870_FaultEvent_Init` 清空数组和数量,默认遥信类型30、遥测类型13。初始化后仍须填入记录,不能把空初始化当作完整业务事件。
| 类型 | 数据成员 | 契约 |
|---|---|---|
| `IEC60870_FaultEventSignal_t` | `ioa`、`value`、`timestamp` | `value` 是完整 SIQ/DIQ 字节;`timestamp` 是已冻结的 CP56 日历及 IV/SU,不是发布时刻 |
| `IEC60870_FaultEventMeasurement_t` | `ioa`、`value.short_float` | 类型13使用有限 IEEE 754 binary32,拒绝 NaN 和正负无穷 |
| 同上 | `value.unsigned_value` | 类型9/11使用0..65535的原始16位码,按已确认的接收端无符号解析行为保存,不自动做有符号解释或比例换算 |
| `IEC60870_FaultEvent_t` | `signal_type`、`measurement_type`、两数组及数量 | 两组分别同类型;编码先检查数量范围和数组指针,再逐项校验值并核对总容量;解析先检查完整字节长度再读取记录 |
遥信类型1/30按 SIQ 校验,3/31按 DIQ 校验,允许的品质位保留,保留位非法则拒绝。主站对带品质状态的显示处理不属于编码器职责;不能为了迁就界面而悄悄清除品质。已确认的接收端在双点显示中把0解释为异常态、3解释为中间态,与普通双点常见表述有差异;本库保留调用方给定的两位状态码,不自动交换0和3。
CP56 复用公共时间编解码,检查日历、毫秒和标志是否合法,保留 IV/SU。应用应在故障捕获时提供符合项目时区约定的日历;编码器不读取系统时间,不依据当前校时状态覆盖故障时标。已确认的接收端在遥测行显示 PC 当前时间属于界面行为,不表示终端应发送当前测量值。
公共头仅允许 COT=3、P/N=0,TEST可为0或1。公共编解码检查CA和IOA能否由给定宽度表示,允许零地址,不检查站点注册;104业务入口另行限制CA为已注册的1..65534、IOA为1..0xFFFFFF。
公共编解码允许任一组乃至两组数量均为0,非零数量要求对应数组非NULL;它只验证结构与编码,不知道哪些地址代表 Ua 或 Ia,也不强制8项电气量或检查重复地址。完整故障业务要求由[104发布入口](#fault-event-publish)和应用点表共同承担。
<a id="fault-event-validation-order"></a>
### 3.1 校验顺序与失败输出
| 入口 | 校验与输出顺序 | 失败时保持的内容 |
|---|---|---|
| `Encode` | 输出指针、链路参数和公共头 → 数量/数组/内部类型 → 全部记录字段 → 完整长度与双重容量限制 → 写完整原文和长度 | `out`及`out_length`不变 |
| `Parse` | 公共头及最短报文体 → 遥信类型与第二组起点边界 → 遥测类型与精确总长 → 两组所有记录 → 写入视图 | 调用方原有`view`不变 |
| `Get_Signal` / `Get_Measurement` | 重新校验视图借用的整帧 → 下标范围 → 按值输出一条完整记录 | 调用方原有记录输出不变 |
Encode先把N/M限制为0..255,再遍历数组和计算长度,避免截窄数量后接受不完整快照。字段非法返回 `ERROR`;仅当字段全部合法而 `capacity` 或 `maxSizeOfASDU` 不足时返回 `FULL`。同一输入同时有非法字段和容量不足,结果仍为 `ERROR`。写出阶段依赖预检时看到的同一份输入,调用方不能在校验与写出之间修改数组。
Parse先确认第二组的数量和类型字节都存在,再读取它们;随后要求实际总长与计算结果精确相等,既拒绝截短,也拒绝额外尾字节或误加的QDS。任一记录损坏都会拒绝整帧,不返回“前半段可用”的部分成功结果。空数组也必须指定受支持的内部类型。
104发布在公共编码之外增加业务检查:必要指针与实例 → 服务监听及队列快照 → 站点身份、必需记录及业务地址 → Encode → 原文容器包装 → 入队。各阶段错误映射见[返回值与恢复责任](#fault-event-errors);任一前置阶段失败均不尝试入队。
<a id="fault-event-time"></a>
### 3.2 CP56日历与原文字节的区别
故障时刻通过 `IEC60870_CP56Time2a_t` 传递,编码器保留日历、毫秒、IV及SU,不做时区换算。IV=1表示时间无效,但不允许用非法日期占位;调用方仍须提供可编码的日历。时标的星期和GEN遵循[公共时间模块](../../common/IEC60870_Time.c)的语义:
| 项目 | 处理方式 |
|---|---|
| 编码星期 | `has_weekday=1`时按日期重新计算;否则线上星期字段为0 |
| 解析星期 | 根据日期重新计算`time.weekday`,`has_weekday`记录线上是否提供星期;不保留收到的星期位模式 |
| GEN | 解析允许该位存在,但日历结构不导出它;重新编码固定为0 |
| 其他保留位 | 编码清零;解析拒绝非法非零保留位 |
因此Parse/Getter再Encode不承诺七字节时标逐字节相同。需要原文留档或透明转发的调用方应保留完整原文,不能用日历结构代替字节副本。故障发布始终使用捕获时的日历,普通突发模块的时间基准、`TIME_AT_PUBLISH`、后续校时及等待时长均不改变它。
<a id="fault-event-ownership"></a>
### 3.3 借用内存与串行调用
| 数据 | 持有者及有效期 | 何时可复用 |
|---|---|---|
| `event`及两组输入数组 | 应用持有;整个Encode/发布调用期间有效且不变,发布模块不保存数组指针 | Encode返回后按上层用途决定;业务发布OK后可复用,WAIT仍须保存快照内容 |
| 编码输出缓冲 | 调用方持有;104发布使用实例已有单帧缓冲 | 服务入队已复制原文后,实例可用于下一次发布 |
| `view.parameters`与`view.asdu` | Parse只借用,不复制、不延长寿命;后续每次Getter期间仍须有效且不变 | 全部读取完成后;复用接收缓冲解析下一帧前须结束旧视图使用 |
| Getter输出记录 | 调用方持有,成功时按值复制 | 不再依赖原文,可独立使用 |
输入与输出、两个输出及相关控制结构不得重叠。Getter每次重新校验整帧是保证失败不留下部分输出的措施,不是并发保护,也不能发现原文已释放;不允许据此修改原文后继续使用旧视图。逐条读取会重复整帧校验,调用方应按单帧长度和记录数安排处理时间。
104发布须与所属Slave及其他Spontaneous调用串行,并位于网络推进和业务回调之外。采集上下文通过应用自己的同步机制交接冻结快照,再由协议循环调用发布;接口不提供锁,也不能从采集中断直接调用。WAIT重试要求保持同一故障的值、时标和站点归属,不要求下一次使用相同的物理数组地址,但新存储必须完整保存这些内容并满足同样的寿命约束。
<a id="fault-event-integration"></a>
## 4. 与普通 ASDU 编解码的边界
普通 `IEC60870_Asdu_Add_InformationObject` 按 VSQ 对象数、单一对象类型和 IOA 布局组织数据。Type42 内部同时有两组不同长度的记录,不能把它注册为一个普通变长对象后继续套用该布局。
`IEC60870_FaultEvent` 因而提供专用整帧编码、解析及逐项读取接口。它复用公共应用层参数、ASDU头值类型和时间工具,不依赖104网络、队列、时钟源或故障检测。普通 `Asdu_Parse/Get_Element` 不承担 Type42 内部记录解析,调用方应按 TI 显式选择专用入口。
独立文件承载的是这一种报文布局,业务上送仍接入现有Spontaneous和服务队列;不新增任务或另设故障发送通道。各层职责如下:
| 层次 | 负责内容 | 保持的边界 |
|---|---|---|
| 应用故障捕获 | 故障判据、冻结测量与时标、点表/单位/倍率、等待中的快照和录波开放顺序 | 库不能仅凭IOA证明八项测量的实际含义或同一时刻性 |
| [公共FaultEvent](../../common/IEC60870_FaultEvent.c) | 扩展布局、字段校验、完整ASDU编解码及借用视图 | 参数可供101/104共用;公共编解码不等于已接入101上送业务 |
| [104 Spontaneous](../../104/business/IEC104_Spontaneous.c) | 站点身份、最少记录、业务地址、固定等级、入队及发布统计 | 复用既有实例和单帧缓冲,不持有WAIT报告 |
| 服务队列与发送层 | 原文副本、启动门禁、下一帧选择、断线恢复、ACK及覆盖回收 | 不从报文反推采集值,不保证掉电持久化或主站界面已显示 |
<a id="fault-event-data-boundaries"></a>
### 4.1 故障简报、连续录波与历史 SOE
三者可由同一次现场故障产生,但保存的数据与交接条件不同:
| 数据 | 捕获与冻结时刻 | 输出与保留责任 |
|---|---|---|
| Type42 故障简报 | 应用在故障时冻结遥信、测量值及 CP56;发布等待不能改用当前值 | 主动上送一份 ASDU;成功只交接原文给 NORMAL,不写历史库 |
| [连续采样录波](IEC60870_FaultRecorder_设计架构.md#fault-recording-capture) | 环形缓冲持续接收瞬时采样;故障前后窗口齐全后进入 READY | 生成 CFG/DAT,由应用成对保存并公开;READY 前还不能从录波只读接口取完整记录 |
| [历史 SOE](IEC60870_History_设计架构.md#history-design) | 应用在源变位时按点表追加事件,与发送重试及 ACK 分开 | 持久循环保存,按需生成 `HISTORY/SOE/soe.xml`,经 Type210 读取 |
简报中的一组故障测量不能还原连续波形,录波缓存中的遥信也不会自动成为历史 SOE。Spontaneous、FaultRecorder 与 History 没有隐式互调;应用须分别交接所需数据。当前历史示例接入普通单点/双点源变位,不把发布成功的 Type42 反向展开为历史事件,避免把网络重试或合成报告误记为新变位。
### 4.2 专用编码与入队
104发布时,专用编码器先生成完整原文,再用 `IEC60870_Asdu_Create_From_Buffer` 建立借用容器,交给既有事件入队接口。借用容器只负责包装已经校验的字节,不能替代故障事件的完整校验,也不能继续调用普通 Add 追加记录。
| 公共接口 | 用途 |
|---|---|
| `IEC60870_FaultEvent_Init` | 初始化默认内部类型和空数组,不产生时标 |
| `IEC60870_FaultEvent_Encode` | 把完整快照编码为一条ASDU,不包含APCI |
| `IEC60870_FaultEvent_Parse` | 完整校验后返回借用原文和参数的 `IEC60870_FaultEventView_t` |
| `IEC60870_FaultEvent_Get_Signal` | 按0起始下标读取遥信地址、SIQ/DIQ和CP56到独立值结构 |
| `IEC60870_FaultEvent_Get_Measurement` | 按0起始下标读取遥测地址及对应类型的值 |
完整签名和返回值见[公共故障事件API](../104/IEC104_API接口汇总.md#fault-event-codec-api)。
<a id="fault-event-publish"></a>
## 5. 104故障快照上送
`IEC104_Spontaneous_Publish_Fault_Event` 使用现有 Spontaneous 实例,不新增业务实例或内部任务。输入 `IEC104_SpontaneousFaultEvent_t` 保存 CA、可选 `station_id` 和公共故障事件描述。
业务约束如下:
- CA必须已注册,非零 `station_id` 必须与当前注册编号一致,防止旧快照误归到重注册的站点。
- 至少1条遥信、8条遥测;遥测数组前8项约定为 Ua、Ub、Uc、U0、Ia、Ib、Ic、I0,允许其后附加其他测量。
- 全部业务 IOA 非零且适合链路宽度,遥测地址不能重复。实际工程含义、倍率、单位和地址映射由应用点表保证,库不能只凭地址数值识别电气量。
- 所有记录来自同一次故障捕获;应用在进入通信循环前完成快照,不能在发布或 WAIT 重试时重新读取实时值。
- 固定使用 COT=3、故障事件第6级;不继承普通变化的 `forms`、`cause` 或可选等级,也不额外发送无时标/带时标两份报告。
```mermaid
sequenceDiagram
participant A as 应用故障快照
participant P as Spontaneous
participant C as FaultEvent编解码
participant Q as NORMAL与发送层
A->>P: Publish_Fault_Event(同一份快照)
P->>P: 站点、必需记录和业务地址校验
P->>C: 编码到现有单帧缓冲
alt 编码失败
C-->>P: ERROR或FULL
P-->>A: ERROR / INPUT,published=0
else 编码成功
C-->>P: 完整Type42原文
P->>Q: Enqueue_Event_Priority(FAULT_EVENT)
alt 已接手
Q-->>P: OK,原文已复制
P-->>A: OK,published=1
else 暂不可接手
Q-->>P: WAIT
P-->>A: WAIT,published=0
A->>A: 保留同一故障的值、时标和站点归属
else 提交失败
Q-->>P: ERROR或FATAL
P-->>A: ERROR / SUBMIT,published=0
end
end
```
返回 `OK` 只表示整份报告曾被队列接手。输入数组随后可释放或复用,已经保存的报文原文不会随调用方改值改变。`WAIT` 表示本次没有交接,应用保留同一份快照到后续事件循环重试。错误按 INPUT、STATE、QUEUE、SUBMIT 分类处理,服务错误不能当作普通背压无限重试。
单份发布的 `info.published` 只取0或1,按完整报告计;`failed_index` 固定为 `SIZE_MAX`。累计 `published` 对该入口每成功报告加1,`asdus` 加1,`objects` 加 N+M,`time_invalid` 加本报告中 CP56.IV=1 的遥信条数。它与普通 Publish 共用状态计数,因此混合使用时 `published` 是普通变化与完整报告各自成功单位的累计值,不能解释为全部遥信点数。
### 5.1 断线、启动顺序与录波
报告进入服务级 NORMAL 后,离线缓存、STOP后续发、断线恢复、启动门禁和 ACK 回收均沿用现有发送层。启动门禁开启时,即使报告已入队,也要等本轮初始化和初始化总召完成后才允许选帧。
严格业务调度按第6级选择可发送的故障报告,先于第10/11级文件业务;已交接或部分写出的帧仍会完整发送。应用应先冻结并发布故障快照,再开放对应录波文件传输;等级无法让尚未提交的故障报告排到已经发送的录波帧之前。兼容调度模式不保证12级严格顺序,详见[业务优先级设计](../104/IEC104_业务优先级设计.md)。
NORMAL容量不足时可能覆盖最旧原文,Type42没有专用保留空间。`OK` 不保证原文一直保留,也不等于已发送、已ACK或主站已显示;断线重发也可能重复到达。`Slave_Close` 清空服务缓存,不提供掉电持久化。覆盖诊断和恢复责任见[Spontaneous生命周期](../104/IEC104_Spontaneous_设计架构.md#spontaneous-lifecycle-boundaries)。
### 5.2 发布接入示例
下面假设应用已在故障发生时冻结 `signals`、`measurements` 及其数量,且前8条测量符合约定顺序;`station` 是已注册站点,`spontaneous` 已创建。数组由应用已有快照保存,片段不另外建立缓存。采集上下文通过应用自己的同步机制交接冻结快照;报告准备、站点身份读取及发布都在所属协议循环执行,不能从采集中断直接调用发布入口。首次准备报告时绑定这些数组,之后跨事件循环保留 `report` 及其借用内容:
```c
/* Prepare once in the protocol loop after receiving the frozen snapshot. */
IEC104_SpontaneousFaultEvent_t report = { 0 };
report.common_address = common_address;
report.station_id = IEC104_Station_Get_Id(station);
IEC60870_FaultEvent_Init(&report.event); /* Signal 30, measurement 13. */
report.event.signals = signals;
report.event.signal_count = signal_count;
report.event.measurements = measurements;
report.event.measurement_count = measurement_count;
/* Run in the owning protocol loop, outside callbacks. */
IEC104_SpontaneousPublishInfo_t info;
IEC104_SpontaneousPublishResult_t result;
result = IEC104_Spontaneous_Publish_Fault_Event(spontaneous, &report, &info);
```
应用仅在 `result == IEC104_SPONTANEOUS_PUBLISH_OK` 后推进自己的故障队列,此时可复用本份数组。`WAIT` 时保持 `report`、数组数值和每条 `timestamp` 不变,在后续网络推进后重试同一报告;不能再次执行故障采集或用当前时间重建CP56。`ERROR` 时根据 `info.error` 修正输入或恢复服务,不能直接删除快照后假装已交付。报告结构只借用数组,若准备函数返回,数组也必须由应用的长期存储继续持有。
<a id="fault-event-errors"></a>
### 5.3 返回值与恢复责任
下表以调用方提供有效且不重叠的 `info` 为前提。函数返回值判断本次是否交接,`info.error`细分错误;所有失败均不发布这份报告。
| 函数结果 / `info.error` | `info.published` | 触发原因及应用处理 |
|---|---:|---|
| `OK` / `NONE` | 1 | 原文已经复制入队,可推进应用故障队列;后续发送由服务层负责 |
| `WAIT` / `NONE` | 0 | 入队暂不可接手;保留快照并在后续协议循环重试,不重新采样、不忙循环 |
| `ERROR` / `INPUT` | 0 | 报告、站点身份、类型/字段非法或超出单帧容量;定位输入原因,单纯等待不会修复 |
| `ERROR` / `STATE` | 0 | 实例无效、服务句柄失效或未处于监听状态;恢复实例/服务生命周期 |
| `ERROR` / `QUEUE` | 0 | 发布前服务状态查询失败或队列快照无效;恢复服务并重新查询,不能视为普通背压 |
| `ERROR` / `SUBMIT` | 0 | 已编码原文包装失败,或底层入队返回ERROR/FATAL;结合`info.submit_result`诊断底层故障 |
`info.failed_index`始终为 `SIZE_MAX`,该入口不提供记录级失败下标。`info.submit_result`初始化为 `IEC104_TCP_SUBMIT_OK`,当前实现只在SUBMIT错误时改写;WAIT路径也保持这个初始值,不能用它代替函数返回值判断是否入队。`info=NULL`直接返回ERROR,无法提供输出详情。
字段校验在服务状态确认之后进行,因此服务尚未就绪时应先处理STATE/QUEUE,不能假设所有非法报告都会立即得到INPUT。使用非零 `station_id` 的快照在站点重注册后会被拒绝;应用应核对旧故障归属,不应把ID改成0或当前新ID来绕过检查。
入队尝试后,无论返回OK、WAIT还是底层错误,都会读取队列快照统计NORMAL覆盖情况,成功交接数分别按1或0计算;预检及原文包装失败的提前返回不执行这一步。若后续查询失败,只增加 `accounting_errors` 表示统计不完整,不撤销已发生的交接,也不改变原返回值。应用不能因为该计数增加就重新发布已获OK的报告;否则会主动制造重复。零交接也不表示诊断计数不变。报告数、内部记录数和丢失/覆盖计数须分别解读,覆盖诊断仍沿用[Spontaneous生命周期](../104/IEC104_Spontaneous_设计架构.md#spontaneous-lifecycle-boundaries)。
<a id="fault-event-validation"></a>
## 6. 资源、构建与验证边界
专用公共模块使用调用方提供的数组和输出缓冲,不分配堆,也不保存可变全局状态。104发布复用现有 `buffer[249]`,不扩大普通 `IEC104_SpontaneousChange_t` 联合体、不增加实例缓冲或发送队列。新增源文件需要在实际使用它的工程中登记;本目录的构建入口由 `scripts/build.ps1` 维护,未接入父工程或板级采集代码。
2026-11-12已执行本目录 `./scripts/build.ps1 -BuildName type42-build`,GCC C11、`-O2 -Wall -Wextra -Werror` 构建为0错误0警告。以下为同次宿主资源测量,原始报告位于 `.build/type42-20261112/measure/`;数值仅适用于该MinGW构建,不代表ARMCC结果或完整最坏调用链:
| 项目 | 新增前 | 新增后 |
|---|---:|---:|
| Spontaneous目标文件text | 5244 B | 6420 B |
| Spontaneous目标文件BSS | 384 B | 384 B |
| FaultEvent目标文件text | 无 | 3100 B |
| FaultEvent目标文件data/BSS | 无 | 0 B / 0 B |
同一宿主配置的单函数栈报告为:故障发布288 B、Encode 128 B、Parse 224 B、两个Getter各80 B。发布复用了现有组帧缓冲;该单函数报告不能通过直接相加替代板端栈分析。
验证分为公共编解码与104发布两层,分别定位到 [iec60870_fault_event_test.c](../../test/iec60870_fault_event_test.c) 和 [iec104_fault_event_test.c](../../test/iec104_fault_event_test.c)。应覆盖固定预期字节、不同地址宽度、内部类型、负浮点和16位无符号码、每个截断位置、额外尾字节、错误输出不变、业务必需项、站点身份、WAIT原快照重试、固定等级和NORMAL生命周期。
本次专项及完整回归已执行,覆盖249/250字节边界和多遥信后的记录偏移;实际命令、配置数量、沙箱重试过程及通过记录集中在[Type42测试记录](../test/IEC104测试文档.md#fault-event-tests)。
自动测试用于验证本库与已确认的主站解析规则一致,不能替代真实主站接收验证。最终联调仍需确认故障事件页面收到记录、点号和点名匹配、单/双点状态显示、负浮点值、故障时标及录波前后顺序;测试报告应区分宿主回归、真实TCP回环和主站实机结果,不预先记录未执行的通过结论。
@@ -0,0 +1,297 @@
# 故障录波与 COMTRADE 文件生成
<a id="fault-recording-overview"></a>
`IEC60870_FaultRecorder`接收连续瞬时采样和故障采样序号,冻结故障前后波形;`IEC60870_Comtrade`将冻结记录编码为COMTRADE 1999的ASCII配置文件及二进制数据文件。两者没有硬件、RTOS、文件系统、协议传输或堆分配依赖,存储由调用方提供。实现与公开契约分别见[录波核心](../../common/IEC60870_FaultRecorder.c)、[录波头文件](../../common/IEC60870_FaultRecorder.h)、[编码器](../../common/IEC60870_Comtrade.c)、[编码头文件](../../common/IEC60870_Comtrade.h)。
依据是项目所附[配电自动化实施细则](../../20170804163032284877151.pdf)附录A,PDF第47–48页:故障前不少于4周波、后不少于8周波、不少于80点/周波,包含三相及零序电压、电流和遥信;CFG与DAT成对,放入COMTRADE目录。此处实现格式与采样截取接口,真实传感器数据、故障判据、采样同步、时钟有效性及目标预算由产品接入保证。本次没有接入板级驱动。
本文是录波采样、编码和应用交接的设计入口;操作命令见[模拟录波示例](../examples/IEC104子站示例.md#example-recording),Type210线格式及主站兼容性见[文件服务设计](../104/IEC104_FileService_设计架构.md#file-service-client-compat),测试矩阵与执行记录统一维护在[录波验证](../test/IEC104测试文档.md#recording-tests)。
## 1. 数据流与边界
### 1.1 实现位置与依赖
以下路径均相对于`IEC60870-Slave`,产品接入不应把主机示例的静态对象或文件I/O隐式并入协议实例。
| 位置 | 职责 | 输入与输出 |
|---|---|---|
| [common/IEC60870_FaultRecorder.c](../../common/IEC60870_FaultRecorder.c) | 连续样本校验、环形历史、触发窗口、冻结记录 | 帧及绝对采样序号 → READY记录;不包含故障判据 |
| [common/IEC60870_Comtrade.c](../../common/IEC60870_Comtrade.c) | COMTRADE 1999编码及BAY名称生成 | READY记录及元数据 → CFG文本、DAT字节切片;使用公共时间工具 |
| [examples/iec104_example_recording.c](../../examples/iec104_example_recording.c) | 单条模拟波形、主机保存和内存读取适配 | 调用方对象 → 一对文件;属于演示应用 |
| [examples/iec104_slave_example.c](../../examples/iec104_slave_example.c) | 命令行启用、TI42入队、目录与读回调 | 通过`saved/published`决定文件何时可见 |
| [104/business/IEC104_FileService.c](../../104/business/IEC104_FileService.c) | Type210目录会话、文件激活及分段传输 | 借用应用提供的稳定清单和文件内容,不解析COMTRADE |
| [104/business/IEC104_Spontaneous.c](../../104/business/IEC104_Spontaneous.c) | Type42故障快照发布与发送调度 | 接收独立故障简报,不从文件反推实时故障 |
录波核心不依赖编码器;编码器依赖录波只读接口与`IEC60870_Time`;示例应用组合这些公共模块与104业务模块。公共模块可复用到其他传输方式,但这里的文件服务集成和验证仅覆盖104,不能据此认定101文件链路已经完成。
Type42简报、连续采样录波和持久历史SOE的区别见[三类数据边界](IEC60870_FaultEvent_设计架构.md#fault-event-data-boundaries)。本模块的“历史”指故障前的RAM采样环,与附录B的[历史记录存储](IEC60870_History_设计架构.md#history-design)分别管理;启用历史存储不会自动持久化录波环或恢复COMTRADE目录。
### 1.2 数据流
```mermaid
flowchart LR
A[调用方连续瞬时采样] --> B[FaultRecorder环形历史]
T[故障采样序号] --> B
B --> C[READY冻结记录]
C --> D[Comtrade CFG与DAT编码]
D --> E[应用存储与文件目录]
E --> F[现有Type210文件服务]
T --> G[Type42故障快照]
```
八路固定顺序是`Ua, Ub, Uc, U0, Ia, Ib, Ic, I0`。每帧包含8个`int16_t`模拟量和4个`uint16_t`遥信字,支持配置1–64路遥信;第一路遥信对应`digital[0]`的最低位,未配置位在入库时清零。每帧须代表一个共同采样时刻。核心不计算有效值或相量,也不从Type42的单次测量快照重建波形。
| 需求 | 当前模块承担的部分 | 应用仍需保证 |
|---|---|---|
| 前4/后8周波、每周波至少80点 | 校验配置下限并截取完整序号窗口 | 实际采样频率、连续性、验收频率范围 |
| 八路电气量及遥信 | 固定通道顺序和数字位编码 | 同步采集、通道语义、标度及品质处理 |
| 1999版CFG/BINARY DAT | 格式、相对时标、文件名及准确长度 | 有效故障时间、元数据、成对保存及文件寿命 |
| 故障简报先于录波数据 | 示例先提交TI42,再开放文件 | 真实故障时刻的及时发布及丢失/重试策略 |
| 主站主动召取COMTRADE文件 | 目录、激活和数据分段接口 | 稳定目录快照、记录保留及重启恢复策略 |
## 2. 周波窗口和内存
### 2.1 时间窗口与端点
设采样率为`Fs`、配置额定频率为`f0`,前后周波数为`Npre/Npost`:
```text
P = ceil(Fs * Npre / f0)
Q = ceil(Fs * Npost / f0)
record_count = P + 1 + Q
record_first = trigger_sequence - P
record_last = trigger_sequence + Q
```
`P/Q`是触发点两侧的采样间隔数;输出同时包含首点、触发点和末点。只按`Fs × 总时长`取点数会少计一个端点,因此默认采用961帧,而不是把960帧误当作首末相隔完整240 ms。
默认配置为50 Hz、4,000帧/秒、故障前4周波、后8周波、16路遥信。前后时间间隔分别向上取整为采样间隔数,且同时保留窗口两端和故障点:
| 项目 | 默认值 |
|---|---:|
| 采样间隔 | 250 μs |
| `pre_samples` / `post_samples` | 320 / 640 |
| 完整记录帧数 | 320 + 1 + 640 = 961 |
| 故障帧逻辑下标 | 320,从0起算 |
| 首点至故障 / 故障至末点 | 80 ms / 160 ms |
| 原始帧大小 | 24 B,包含64路遥信的固定存储位 |
| 调用方帧数组 | 961 × 24 = 23,064 B |
| 16路遥信时DAT每帧 / 总长 | 26 B / 24,986 B |
帧数组之外还需控制对象、CFG输出及应用存储资源,23,064 B不是整个功能的总RAM。`Required_Capacity`校验每额定周波至少80点、前后最小周波数和整数/字节容量溢出。更多容量可保留更长的延迟触发历史;它不会自动增加已配置的输出窗口。额定频率检查不等于全部实际频率范围已验收,接入方应按频率范围和判据延迟选择采样率、窗口和容量。
### 2.2 延迟触发的容量
故障判据可在故障样点之后才形成。令`D = 最新已接收序号 - trigger_sequence`,在采样连续、启动历史已经充分积累且序号不溢出的前提下,调用`Trigger`时保留前端点至少需要`P + D + 1`帧;后续完整窗口还要求`P + Q + 1`帧。若最大判据延迟为`Dmax`,所需容量为:
```text
capacity >= P + 1 + max(Q, Dmax)
```
默认容量961帧可以容纳至多640个采样间隔、即160 ms的迟触发。`D<Q`时继续收齐后置窗口;`D>=Q`且完整历史仍在时,`Trigger`直接返回`COMPLETE`。容量更大只延长可追溯历史,不改变输出的961帧。启动后历史不足、所需前端点已覆盖或中途断样时,不能依靠该容量公式补回缺失数据。
### 2.3 资源与实时性
`Push`只复制固定8路模拟量及4个遥信字,`Trigger/Get_Frame`只进行有界索引和复制,不扫描整份录波。CFG生成随通道及文本长度增长;DAT读取随请求字节数增长,内部最多使用一帧32 B的编码暂存,不建立整份DAT副本。文件写入属于应用层,不应占用采样或网络推进的实时路径。
主机示例额外持有4096 B的CFG缓冲、文件名及状态;其配置不能直接用作任意64路长名称CFG的容量保证,产品应先查询`Build_CFG`长度。`main`中的`static ExampleRecording`无条件占用BSS,关闭`--recording-demo`只是不生成和公开记录,不会收回这块静态存储。公共录波与编码模块无可写全局数据,但调用方存储仍计入总RAM。已有宿主BSS和单函数栈测量统一见[验证记录](../test/IEC104测试文档.md#recording-tests),不能代替目标ARMCC调用链预算和板端水位。
<a id="fault-recording-capture"></a>
## 3. 录波接口和状态
以下函数均以前缀`IEC60870_FaultRecorder_`导出;完整参数定义以[头文件](../../common/IEC60870_FaultRecorder.h)为准。
| API | 契约 |
|---|---|
| `Config_Default` / `Required_Capacity` | 建立默认配置、计算最小帧容量;失败不改容量输出 |
| `Init` | 借用控制对象与帧数组,不分配、不清空整个数组;失败不改控制对象 |
| `Push` | 输入一帧及`uint64_t`采样序号;首序号任意,以后必须严格加1,最大值不回绕 |
| `Trigger` | 引用已经接收的故障采样序号,要求该点及前置历史仍在缓存中;支持延迟触发 |
| `Get_Info` | 所有已初始化状态可查询;完整`frame_count`仅在READY有效,序号字段在有效触发后才有意义 |
| `Get_Frame` | 仅READY可按逻辑时间顺序复制一帧;失败不改输出 |
| `Release` | 显式丢弃历史、进行中或冻结记录并重新布防,保留统计计数;必须先结束全部导出者和读句柄 |
```mermaid
stateDiagram-v2
[*] --> ARMED: Init
ARMED --> CAPTURING: Trigger且后置数据未齐
ARMED --> READY: 延迟Trigger时完整窗口已在历史中
CAPTURING --> READY: 收到后置窗口末点
CAPTURING --> FAILED: 序号不连续
ARMED --> ARMED: 不连续时以当前帧重建历史
READY --> ARMED: Release
FAILED --> ARMED: Release
CAPTURING --> ARMED: Release主动放弃
```
`COMPLETE`表示已经形成完整窗口;`BUSY`表示当前不能接收新触发或样本;`NO_HISTORY`表示故障前历史不足或已被覆盖;未来触发序号、后置序号会溢出等参数错误返回`INVALID`。ARMED期间遇缺帧返回`DISCONTINUITY`并重新积累历史;CAPTURING期间缺帧会进入FAILED,不能导出成完整记录。重复触发不会覆盖正在捕获或冻结的记录,状态与计数由`Get_Info`读取。
`Trigger`按传入的故障采样序号确定窗口,不能用判据处理时的最新序号代替故障点。迟触发若已收到后置末点可立即返回`COMPLETE`,冻结范围仍截止于故障序号加后置点数,不把处理延迟追加进文件。该结果只证明采样窗口完整;故障日历由应用另行冻结,编码成功、存盘成功及对主站可见分别具有后续条件。
所有调用,包括查询与导出,均须串行,或在采集和导出上下文之间明确转移所有权。控制对象、帧数组、输入帧及输出对象须遵守头文件的不重叠要求。READY在`Release/Init`前保持不可变,但不存在隐藏的第二缓冲;冻结期间的新采样返回BUSY。连续多故障采集需要调用方另外设计记录池和调度,本模块不提供自动排队。
### 3.1 失败后的处理
| 结果或状态 | 已发生的状态变化 | 调用方处理 |
|---|---|---|
| ARMED下`Push`返回`DISCONTINUITY` | 旧历史丢弃,当前帧已作为新历史首帧 | 记录采样异常,继续积累;不能将该帧当成未接收后再次推入 |
| CAPTURING下`Push`返回`DISCONTINUITY` | 当前帧未接收,进入FAILED | 本次录波不导出,结束持有后`Release`再布防 |
| `Trigger`返回`NO_HISTORY` | 不启动捕获,保留当前历史 | 可报告故障但标记录波未形成,继续正常采样 |
| `Trigger`返回`BUSY` | 原记录不被覆盖 | 按产品策略登记新故障,不把新时标改写进旧记录 |
| READY/FAILED下`Push`返回`BUSY` | 不接收新样本 | 处理记录生命周期;不能认为冻结期间还有后台历史 |
| 参数校验失败 | 不构成成功采样或触发 | 修正参数并记录原因,不能用默认成功值替代返回值 |
`triggers/completed/busy_triggers/history_misses/discontinuities`为饱和到`UINT32_MAX`的计数;`Release`保留,重新`Init`清零。`busy_triggers`只统计被拒绝的触发,不能当作冻结期间被拒绝的样本数;如需统计丢样,应用应根据`Push`结果另计。
### 3.2 冻结对象的所有权
采集所有者在COMPLETE后将只读记录交给编码/存储所有者;全部导出和文件读会话结束后,才允许`Release`并重新接收采样。若后续Type210仍直接从RAM编码,保存文件成功本身不足以释放这块RAM。若产品改为读取已提交的磁盘文件,可在存储交接完成、没有其他RAM读者时提前释放录波,但这是应用后端的不同设计。
Release同时清除故障前历史。默认配置恢复采样后,要重新积累至少321个连续样点,才能对当前样点形成含320个前置间隔的触发。`ExampleRecording`内的控制对象持有其`frames`指针,初始化后不能用按值搬移整个对象来转移记录;转移所有权应保持对象地址及引用稳定。
<a id="fault-recording-format"></a>
## 4. COMTRADE 1999编码
### 4.1 CFG字段与容量
CFG使用ASCII、CRLF行尾及终止NUL;输出长度不含NUL,实际文件不写NUL。源码和文档仍遵守仓库LF约定。CFG描述8路固定模拟量、已配置遥信、单一采样率、总点数、首点/故障时刻、`BINARY`及`timemult=1`。模拟量名称及单位固定为上述电压V、电流A。
模拟量按`物理值 = multiplier × DAT整数 + offset`解释,`primary/secondary`和`P/S`标志说明一次/二次量。四个数值字段使用调用方提供的十进制ASCII字符串,避免平台浮点格式化及区域设置差异;最长13字符,允许符号、小数和有界指数,倍率非零、变比正数。站名、设备名和自定义遥信名为非空可打印ASCII、最长64字符、不含逗号。默认遥信名称为`D1..D64`、正常状态为0。
CFG依次写站名/设备名/`1999`、通道总数及模拟/数字通道数、8行模拟通道、D行数字通道、额定频率、采样率段数`1`、采样率及末点号、首点日期、触发日期、`BINARY`、时标倍率`1`。模拟通道时差固定为0,应用必须先保证帧的同时刻性;不能仅靠此字段把不同步输入宣称为同步。
`Build_CFG`先用同一套输出逻辑测算长度,再在容量足够时生成;容量不足不输出半份CFG。即使只查询长度,仍要求记录READY及元数据有效。长度查询和实际生成期间,元数据、指向的字符串及录波应保持不变;元数据字符串只在调用期间借用,CFG生成后保存的是编码后的字节。
### 4.2 DAT字节布局与分段读取
DAT多字节字段全部小端,每帧依次为4字节采样序号(从1起)、4字节相对首点的微秒时间、8个有符号16位模拟量、每16路一组的遥信字。未使用遥信位为0。`-32768`保留为COMTRADE缺测标记,实际数值范围为`-32767..32767`;编码器不裁剪,也不自动把无符号ADC码换算为有符号量。
| 帧内偏移 | 字节数 | 含义 |
|---|---:|---|
| 0 | 4 | 文件采样点号`index + 1`;与采集绝对序号无关 |
| 4 | 4 | 相对文件首点的微秒偏移 |
| 8、10、12、14 | 各2 | Ua、Ub、Uc、U0,有符号16位 |
| 16、18、20、22 | 各2 | Ia、Ib、Ic、I0,有符号16位 |
| 24起 | `2 × ceil(D / 16)` | 遥信字;D为实际通道数,通道1对应首字bit0 |
总长度为`record_count × (24 + 2 × ceil(D / 16))`。编码器逐字节写字段,不依赖C结构体布局或宿主字节序。读取时以`offset / frame_bytes`找到帧、`offset % frame_bytes`找到帧内位置,再按剩余长度复制;Type210的段边界无须对齐采样点或字段。请求必须整体落在文件范围内,不短读、不补零;EOF处仅零长度读取合法。冻结记录使重复偏移返回相同字节。
默认记录的故障点为逻辑下标320,对应DAT点号321和时标80,000 μs;末点为逻辑下标960,对应点号961和时标240,000 μs。采集绝对序号可以从其他值开始,不能将DAT点号直接传给`Trigger`。
### 4.3 日历时间与采样时间
故障日历为本项目标准时间UTC+8,要求CP56的IV=0、SU=0,另有0–999的微秒余数。首点时间从故障时刻减去前置间隔得到;不足整微秒时统一四舍五入,CFG与DAT故障点使用相同规则。不支持闰秒;首点越出2000–2099、采样率超过1 MHz、DAT大小越出`uint32_t`或时间触及`0xffffffff`缺测时标均拒绝。1999格式自身不携带2013版的时区字段,使用方需保持约定时间域。
对文件逻辑下标`i`,`t_us(i) = floor((i × 1000000 + floor(Fs / 2)) / Fs)`。CFG首点时间为冻结的触发时间减去`t_us(P)`,DAT逻辑下标P(文件点号P+1)的相对时间则为`t_us(P)`;因此二者相加仍对应同一故障时刻。每点直接按下标计算,避免逐点累加舍入误差。采集中发生校时不能改变样本绝对序号,也不能在保存时重新取当前时间覆盖已冻结时标。
### 4.4 API与命名
| API,前缀`IEC60870_Comtrade_` | 契约 |
|---|---|
| `Config_Default` | 单位倍率/变比、默认标识及自动遥信名;故障日期仍无效,调用方必须填写 |
| `Build_CFG` | 要求READY;`buffer=NULL, capacity=0`查询长度;实际容量必须大于长度;元数据仅在调用期借用 |
| `Data_Size` | 计算不可变READY记录的准确DAT字节数,不需要元数据 |
| `Read_DAT` | 从任意字节偏移读取准确长度,包括跨帧和帧内偏移;整体范围必须合法,不补EOF;允许`offset=size, length=0` |
| `File_Name` | 间隔1–99、序号1–9999、合法故障时间生成同基名CFG/DAT;不含目录,输出缓冲至少35 B |
| `Next_Sequence` | 9999后返回1;非法输入返回0;计数持久化及重名检查由应用负责 |
例如`BAY08_0010_20141114_192135_830.cfg`与同名`.dat`。CFG调用期间元数据必须有效;全部CFG/DAT读取直到应用最后一次文件关闭前,录波对象及帧数组必须一直保持READY。调用失败不改输出,具体别名限制见编码头文件。
文件名由间隔、该间隔的序号及故障时间共同确定。`Next_Sequence`只做数值回绕,不保留任何状态;应用需要保存序号并检查重名,尤其要处理重启、时钟回拨和序号回绕后的同名情况。当前示例固定BAY01/序号0001,不能把演示当成已实现自动历史编号。
<a id="fault-recording-integration"></a>
## 5. 宿主演示与104接入
### 5.1 当前演示时序
[示例适配](../../examples/iec104_example_recording.h)通过`Example_Recording_Demo`产生确定性的模拟波形:采样序号从0开始,在序号320触发、960完成。示例将这一条记录保持到进程退出,不自动释放或轮换。
主示例用`--recording-demo existing-directory`启用,并自动开启Type210;命令和联调步骤见[录波示例](../examples/IEC104子站示例.md#example-recording)。示例只生成一次模拟故障,不使用真实采样驱动,也不受普通`--events`模拟变化节拍控制。CFG站名为`SIMULATION`,启动输出明确包含`RECORDING SIMULATED`。
同一冻结故障点经现有`IEC104_Spontaneous_Publish_Fault_Event`提交Type42。返回OK后示例才置`published`,COMTRADE目录和OPEN_READ据此开放;WAIT继续使用同一冻结记录及故障时标。该门禁只表示事件先入队,不表示已交接、已ACK或主站已显示。NORMAL覆盖、断线和协议复位仍可能影响故障事件交付,不能声称每个可读文件都已有主站收到的前置事件。发送边界见[故障事件设计](IEC60870_FaultEvent_设计架构.md#fault-event-integration)。
```mermaid
sequenceDiagram
participant M as 主机示例启动
participant R as 录波与保存适配
participant A as 应用主循环
participant Q as TI42发布队列
participant F as Type210文件服务
participant H as 主站
M->>R: 生成模拟样点0..960,320触发
R->>R: READY,生成CFG及配对名称
R->>R: 写两个临时文件,DAT再CFG改名
R-->>M: complete=true,saved=true
M->>A: 启动监听与事件循环
A->>Q: 提交同一冻结故障快照
alt WAIT
Q-->>A: 尚未接收,下轮重试
else OK
Q-->>A: 已入队
A->>F: published=true,允许列出和读取
H->>F: 主动召COMTRADE目录并读两个文件
F->>R: 从同一冻结记录按偏移取字节
F-->>H: 目录确认、激活确认及数据段
end
```
图中OK以后只保证文件开放条件成立,不表示TI42已送达主站。当前示例在监听前已经录完并存盘,TI42稍后才入队;它验证文件读取流程与快照一致性,不验证真实终端“故障出现即上送简报,后置8周波仍在采集”的时序。产品接入顺序见[第6节](#fault-recording-product)。
### 5.2 保存状态与失败边界
| 结果或状态标志 | 成立条件 | 可执行操作 |
|---|---|---|
| 核心返回`COMPLETE`、状态READY | `Push`或迟触发`Trigger`已形成完整前后窗口 | 只读样点,尝试生成CFG/DAT;不证明编码或保存成功 |
| `complete` | 全部样点、CFG和两个文件名生成成功 | 内部内存读取或尝试保存 |
| `saved` | 两个临时文件写完且两次改名成功 | 等待故障简报入队;尚不足以对主站开放 |
| `published` | TI42发布返回OK | 与`saved`同时成立时列目录和OPEN_READ |
后三项属于宿主`ExampleRecording`,不是公共录波状态机的状态;其中`published`是一次成功入队的事实,不是主站回执。`Example_Recording_Read`只检查`complete`,因此主示例必须在目录与直接OPEN_READ两处共同检查`saved && published`;调用内部读函数不能绕开应用可见性约定。即使`saved`已成立,当前网络读取仍借用冻结RAM,必须等全部目录和读会话结束后才能重新生成或Release。
保存要求父目录存在,并由调用方独占这些目标名的写入。适配器创建或检查`COMTRADE`子目录,先检查两个最终名及两个`.tmp`名,再分块写临时文件;短写、`fflush`或`fclose`失败都算失败。两份写完后先改名DAT、再改名CFG,最后才置`saved`。存在性检查与写入之间没有跨进程锁,不能当成并发安全的不覆盖机制。
| 失败位置 | 处理与可见性 |
|---|---|
| 生成失败 | `complete`未成立;对象可能已重置,旧记录不能继续使用 |
| 父目录、路径长度、已有同名文件等预检失败 | 不置`saved`,已有文件不作为本次记录发布 |
| 临时写入或改名失败 | 尝试清理本次临时文件和已改名DAT;不置`saved`,清理失败可能留文件 |
| TI42发布WAIT | 保存结果保留,维持同一快照重试;目录及OPEN_READ仍不开放 |
| TI42发布ERROR | 向主循环返回失败并走原清理流程;已落盘文件不因此回滚 |
### 5.3 Type210目录与读取
目录项提供`COMTRADE/文件名`完整虚拟路径,主站可将目录项名称原样放入op3;FileService回调按offset从冻结记录读取,不在网络推进中做磁盘I/O。磁盘导出与网络读取使用同一编码器和不可变记录。读目录快照、文件读句柄结束前不得重新生成或Release此记录。
目录打开时复制稳定清单;后续按时间过滤、分页前瞻或发送WAIT均可能重取同一下标,不能在list回调中消费或重建条目。OPEN_READ沿用目录的`saved && published`条件,防止跳过目录提前读文件。读会话记录CFG/DAT类别、大小与归属,关闭时清除读状态;只匹配目录给出的完整路径,不猜测短文件名。
主站流程为op1/COT5召目录、op2/COT5确认,再对每个文件分别op3/COT6激活、op4/COT7确认、op5/COT5传数据、最后op6/COT5确认。目录ID是协议字段,不是应用选择文件后端的索引:示例按`COMTRADE`名称选择目录,默认ZERO模式回ID0,也接受主站携带ID6的目录请求。
正常非空录波末段携带剩余数据,非空目录末页携带真实条目;不会额外补一帧空尾段或空目录尾页。真正的空目录、过滤无结果及异常仍按文件服务协议处理,不伪造文件。录波不压缩,CFG/DAT同基名、同目录供查看器打开。接收端静态分析来源、空结果的待实测表现、模和/大小检查等兼容性事项只在[互操作说明](../104/IEC104_FileService_设计架构.md#file-service-client-compat)维护。
这是单记录宿主适配,未提供持久目录索引、重启扫描恢复、连续多记录采集、跨进程并发发布或物理掉电原子性。两次rename不等于掉电事务。`--config`的INI不保存录波。协议库具备接收真实样本的接口,不意味着本次已完成真实终端、主站客户端或录波分析工具联调。
<a id="fault-recording-product"></a>
## 6. 真实终端接入要求
以下是使用公共模块接入真实产品时应实现的调用关系,本次未修改目录外的采集、任务、存储配置或工程文件。
1. 在部署预算内准备控制对象和帧数组,以`Config_Default/Required_Capacity/Init`建立录波实例。采集层将同一时刻的八路瞬时量和遥信按通道语义组帧,使用真实采样源的连续序号调用`Push`。不能重复低速样本、插值或更改CFG采样率来代替达到所需实际采样率。
2. 故障判据形成时,冻结故障序号、对应日历时刻以及Type42所需快照。先保证故障帧已Push,再调用`Trigger`;在正常业务上下文尽早提交TI42,并继续采集后置窗口。TI42快照须由应用在此时保留,`Get_Frame`只允许读取READY记录,不能用它在CAPTURING中取简报。即使录波因历史不足未形成,故障简报仍可由应用独立处理。
3. `Push`或迟到的`Trigger`返回COMPLETE后,通过`Get_Info`确认READY,冻结记录及元数据。生成CFG、查询DAT大小,按块读取DAT写入产品存储;核对短写和关闭结果。时标、通道、标度和文件名必须始终对应同一条故障。
4. 成对提交后才将两项加入产品目录,并遵守其故障简报发布策略。Type210回调提供稳定目录快照和不可变文件内容;可选择RAM编码或已提交文件后端,但必须明确句柄归属、超时及关闭后资源释放。
5. 结束所有RAM导出和读者后Release,恢复历史积累。需要连续多故障时,另行设计记录池、容量上限、忙时处置与保留周期;不能从当前单记录示例推断已经支持无间断录波。
目标存储必须能保存34字符的BAY文件名,或由文件服务提供稳定的长逻辑名称到物理文件的映射;仅支持8.3名的后端不能直接采用当前文件名。产品还需定义间隔序号持久化、存储满处置、掉电残留文件恢复,以及是否在重启后重新公开已完成文件。上述策略属于应用存储设计,当前主机适配不替代这些能力。
接入构建时,采样缓存加入`common/IEC60870_FaultRecorder.c`,COMTRADE加入`common/IEC60870_Comtrade.c`及其`IEC60870_Time.c`依赖,头文件搜索路径包含`common/`;104发布和文件服务沿用已有业务依赖。主机保存适配使用C标准文件I/O,只作为参考;目标工程的源文件注册、采样实现和存储后端须在相应产品接入范围另行完成。
## 7. 验证入口与证据范围
复现命令、需求到用例的映射、历史执行结果及最近注释等价检查集中在[录波专项验证](../test/IEC104测试文档.md#recording-tests),不在设计文档重复维护测试台账。已有证据覆盖公共采样缓存、格式编码、主机成对保存、104目录/读文件接入及真实TCP回环。
这些证据不包含真实采样频率及同步性、目标ARMCC构建与RAM/栈、真实故障到TI42的时延、连续多故障、物理掉电恢复、主站客户端或录波查看器验收。长稳包装程序曾通过严格构建,尚不能记作已完成长时间稳定性测试。
@@ -0,0 +1,289 @@
<a id="firmware-update-design"></a>
# 持久化软件安装与恢复设计
`IEC60870_FirmwareUpdate`管理候选接收、安装授权、试运行确认及失败恢复;`IEC104_SoftwareUpgrade`仍只负责211会话和结束确认的ACK。应用在`Take_Restart`成功后把一次性协议授权转为持久安装任务。已收完的文件、END肯定及未确认的END都不能单独触发安装。
依据为本目录规范PDF的§8.1.12(第39–40页):启动、通过210传文件、结束后短延时重启;保留两个程序版本,旧版以“程序名-1”备份。规范没有定义实际程序名、升级包封装或远程回退命令。本文的工程包、三槽、事务号和健康确认是实现选择,不作为规范原文要求。
| 层次 | 实现及职责 |
|---|---|
| 协议会话 | [SoftwareUpgrade](../../104/business/IEC104_SoftwareUpgrade.h):START、END、CANCEL、ABANDON及ACK后授权 |
| 文件传输 | [FileService](../../104/business/IEC104_FileService.h):分段、偏移、段校验及最终COMMIT/ABORT |
| 通用安装核心 | [FirmwareUpdate.c](../../common/IEC60870_FirmwareUpdate.c)、[头文件](../../common/IEC60870_FirmwareUpdate.h):持久状态、角色轮换、完整性复验和恢复决策 |
| Windows介质后端 | [iec104_example_upgrade.c](../../examples/iec104_example_upgrade.c)、[头文件](../../examples/iec104_example_upgrade.h):真实文件、独占存储、持久提交及安装副本 |
| 示例应用 | [iec104_slave_example.c](../../examples/iec104_slave_example.c):会话归属、延迟激活、协议重建、宿主文件健康确认、版本读回及阶段日志 |
宿主模式真实保存、安装和恢复负载文件,不加载或执行负载,不刷写MCU,也不把协议重建等同于新固件已运行。目标Flash、复位与Bootloader调用时点见[板端接入](#firmware-update-target)。默认RAM演示和持久模式分别启用。
<a id="firmware-update-state"></a>
## 1. 三槽与持久状态
三个槽保存纯负载,角色为`current`、`backup`及`candidate`;实际槽号可轮换。`current`始终是最后确认过的映像,`backup`是它的上一版本。下载和试运行期间不覆盖这两份源映像。第三槽是更新所需的临时空间,因此“双版本保存”不等于磁盘上只能有两个物理文件。
每份描述含非零版本、非零负载长度和负载CRC32。核心用固定256字节工作区分块复验,不在RAM复制完整程序;固定60字节元数据按小端编码,保存状态、角色、三份描述及不回绕的事务号。元数据原子持久提交由后端保证,不能直接把C结构写到介质。
```mermaid
stateDiagram-v2
[*] --> EMPTY
EMPTY --> STABLE: Provision真实旧映像
STABLE --> RECEIVING: Begin新候选
RECEIVING --> VERIFIED: Finish同步及读回复验
RECEIVING --> STABLE: Abort或启动清理
VERIFIED --> STABLE: Abort或启动清理
VERIFIED --> AUTHORIZED: Take之后Authorize
AUTHORIZED --> INSTALLING: Prepare_Boot先提交意图
INSTALLING --> TRIAL: 幂等安装成功并提交
INSTALLING --> ROLLING_BACK: 候选缺失或复验失败
TRIAL --> STABLE: 健康检查通过后Confirm
TRIAL --> ROLLING_BACK: 下次启动仍未确认
ROLLING_BACK --> STABLE: 重新安装旧current
```
`Init`仅恢复元数据;`Prepare_Boot`每次实际启动或应用激活调用一次,不能当作轮询推进接口。遇到未授权的RECEIVING/VERIFIED时取消孤立候选,保留已确认版本。遇到INSTALLING时按同一事务号、槽和描述重新执行幂等安装;候选缺失、读失败或复验失败则转入持久回退。上次遗留TRIAL表示尚未确认,恢复旧current。当前映像及已有backup均须通过复验,否则拒绝继续,不能把错误当作空库初始化。
Confirm成功才把candidate变为current、原current变为backup,释放更早backup的角色。回退保留原current和原backup。空库基线没有上一版本,不制造假备份;首次升级成功后才形成一对确认版本。无角色槽允许保留旧字节,但不得作为有效版本对外发布。
<a id="firmware-update-wire"></a>
### 1.1 核心记录的60字节布局
以下偏移均相对核心记录起点。所有多字节整数为小端,CRC采用反射多项式`0xEDB88320`、初值`0xFFFFFFFF`及最终取反;不保存结构体填充、指针或宿主句柄。
| 偏移 | 长度 | 内容及约束 |
|---|---:|---|
| 0 | 4 | ASCII `FWU1` |
| 4 | 1 | 核心格式版本,当前为1,与映像版本无关 |
| 5 | 1 | 状态0..7,依次为EMPTY、STABLE、RECEIVING、VERIFIED、AUTHORIZED、INSTALLING、TRIAL、ROLLING_BACK |
| 6、7、8 | 各1 | current、backup、candidate的物理槽号;有效值0..2,无角色为255 |
| 9 | 3 | 保留,全零 |
| 12 | 8 | 升级事务号 |
| 20、32、44 | 各12 | 槽0、1、2的描述;每项依次为u32版本、u32负载字节数、u32负载CRC |
| 56 | 4 | 前56字节的CRC,不包含CRC字段自身 |
EMPTY要求事务号为0、三个角色均为255、所有描述全零。其余状态必须有current;STABLE没有candidate,其他非空状态有candidate。所有有效角色互异,描述的版本和长度非零且长度不超过`max_image_size`;无角色描述必须全零。CRC为零可以是合法负载校验值。`Init`同时检查这些结构约束,即使整条记录CRC正确也不接纳重复角色、未知格式或非法描述。
`Provision`把事务号置1;每次成功提交`Begin`递增一次,取消、安装、确认和回退不改变它。安装重试沿用`(transaction_id, slot, descriptor)`,不能靠重新生成事务号掩盖上一轮副作用。事务号耗尽时`Begin`返回ERROR,不写介质、不置faulted,已确认版本仍可启动。宿主bank代次在每次元数据提交递增,和这个事务号是两个计数。
`received_size`、`receiving_active`、`initialized`和`faulted`都不写入记录。恢复RECEIVING只恢复候选意图,不恢复写权限或偏移;`Write`只能接续本次成功`Begin`。即使负载看起来完整,恢复后也由`Prepare_Boot`撤销未授权候选,不能自行补做Finish或Authorize。
<a id="firmware-update-api"></a>
## 2. 核心接口和错误契约
调用方持有`IEC60870_FirmwareUpdate_t`和后端context,所有操作串行。核心不分配堆、不创建任务、不依赖文件系统和协议库。完整参数及输出保持规则以[公开头](../../common/IEC60870_FirmwareUpdate.h)为准。
| 接口(省略`IEC60870_FirmwareUpdate_`) | 约束与结果 |
|---|---|
| Init | 恢复元数据,不读映像、不执行安装;空库保持EMPTY;不得用它冒充启动确认 |
| Provision | 仅空库;调用方先写真实基线,再同步和读回校验,成功登记current |
| Begin | 仅STABLE;复验current及已有backup,先持久接收意图,再重置空闲槽 |
| Write | 连续负载偏移,非零长度、不得越界;进度仅本次接收有效,不支持掉电续传 |
| Finish | 总长度齐全后同步,再从介质读回CRC和可选产品策略;通过才VERIFIED |
| Abort | 只取消未授权候选;EMPTY/STABLE无候选时幂等;不能撤回已授权任务 |
| Authorize | 仅VERIFIED;应用先领取协议授权,再持久提交AUTHORIZED,本接口不安装 |
| Prepare_Boot | 先复验current及已有backup,再处理孤立候选、安装及回退;仅OK时输出本次应启动映像 |
| Confirm | 仅TRIAL;应用已通过实际健康检查,再复验保留角色及候选,持久轮换角色 |
| Get_Status | 返回值快照,包含faulted;不校验介质、不推进安装、不取得授权 |
### 2.1 返回值与故障闭锁
| 返回值 | 含义及后续动作 |
|---|---|
| OK = 1 | 当前操作成功;空介质的Init也返回OK,状态为EMPTY |
| EMPTY = 0 | 核心公开入口中仅表示Prepare_Boot没有基线,输出保持不变;后端metadata_read也以它表示无提交 |
| INVALID = -2 | 参数或调用阶段不符,不产生介质副作用;修正调用前提后再决定下一步 |
| REJECTED = -3 | Provision/Finish的CRC或产品许可拒绝,不置faulted;Finish仍留RECEIVING,可Abort后重新接收 |
| ERROR = -1 | 未初始化、已闭锁或当前操作无法继续;I/O及不确定提交通常闭锁,事务号耗尽是无副作用的例外 |
不得按非零统一判断成功。元数据提交false可能已经提交:核心不公布新的内存状态,只在旧快照置faulted,后续修改入口停止,直到重新Init读取事实。`Get_Status`仍可查询已初始化的故障实例,但它显示的state不一定是介质最新状态。Init恢复失败则实例不可用,不能通过查询旧字段继续运行。
同一个读失败在不同阶段有不同后果:Finish读回失败会闭锁;Prepare_Boot已复验current/backup后,候选缺失、短读、CRC错或validate拒绝都会先持久ROLLING_BACK,再恢复旧角色;任何保留角色验证失败都闭锁。安装回调false也可能已改变目标,保留调用时的持久状态(INSTALLING/ROLLING_BACK,或稳定启动时的STABLE),重新Init后幂等恢复。窗口中的具体路径见[恢复表](#firmware-update-recovery)。
### 2.2 后端回调边界
回调表按值复制,context仍归调用方;输入、输出及工作缓冲只在同步调用期间借用。回调可用Get_Status只读查询角色,不能重入任何会修改同一核心的入口。实例及后端必须在同一串行上下文操作。
| 回调 | 必须满足的语义 |
|---|---|
| metadata_read | 选出一条已提交记录;OK填写完整字节及长度,只有无提交才EMPTY,系统读取失败或可检测的已提交损坏为ERROR,不能退选旧记录掩盖损坏 |
| metadata_commit | 原子替换一条记录并完成持久同步才true;false可能已产生新版本,不能由核心原样重试 |
| image_begin | 重置核心指定的空闲槽;调用前RECEIVING意图已提交,不得改current/backup |
| image_write / image_read | 使用纯负载偏移,必须完成全部length字节,短写或短读为false;写成功本身不等于已同步 |
| image_sync | 确认Provision基线或Finish候选的全部负载已持久完成 |
| install | 不改三个源槽;按事务、槽及描述幂等安装或选择目标,持久完成并验证结果后才true;返回前不得复位或跳转 |
| validate | 可为空;只有实际CRC匹配后才调用,用于实际槽长、机型、签名及版本许可等产品约束 |
validate也会检查current和已有backup,不能用“版本必须高于current”的无条件判断阻断保留版本启动。核心只检查非零版本,不内置升降级策略;宿主在接收工程包头时单独要求候选版本高于current,其validate只核对源槽真实长度等于描述长度。CRC只证明字节完整性,不提供来源认证;未实现的签名、机型及硬件兼容策略不能由宿主校验替代。
<a id="firmware-update-host"></a>
## 3. 宿主文件后端
`ExampleUpgrade`拥有存储锁、三个槽文件句柄及小块工作区;成功Open后地址保持稳定。父目录必须已存在且可写。首次启用必须提供完整I104基线包;已有存储再次给seed会被拒绝,不能借初始化覆盖现场版本。Open只加载或登记基线,调用者随后执行Prepare_Boot及就绪确认。首次登记失败或中断也不自动清除残留档案;确认基线来源后可在新的空目录初始化。
<a id="firmware-update-storage"></a>
### 3.1 固定文件与双bank格式
线上`upgrade.bin`只用于选择升级写入口,不能直接拼成宿主路径。所有内部文件名由后端固定,源槽不随角色改名。
| 文件 | 保存内容及地位 |
|---|---|
| `upgrade.store` | 布局头和两个元数据bank,角色与恢复决策的依据 |
| `upgrade-slot0.bin`、`upgrade-slot1.bin`、`upgrade-slot2.bin` | 纯负载;是否有效由元数据角色决定,无角色文件可以留有旧内容 |
| `dtu` | 本次安装目标的派生负载;TRIAL时可以是candidate,不能据此提前公布current |
| `dtu-1` | 安装时保存旧current;稳定启动/回退时恢复元数据中的backup,没有backup则删除此派生文件 |
| `dtu.new`、`dtu-1.new` | 安装临时文件;中断后可残留,后续幂等安装覆盖,不作为独立有效版本 |
`upgrade.store`由32字节固定头及两个92字节bank组成,bank起点分别为32和124,上限216字节。文件不强制预分配到216字节,首次仅提交bank0时可以只有124字节;读取必须根据实际字节数判断,不能把预先清零的工作缓冲视为读到完整记录。
| 固定头偏移 | 长度 | 内容 |
|---|---:|---|
| 0 | 12 | ASCII `IEC104-UPG1`及末尾NUL |
| 12 | 4 | 保留,全零 |
| 16 | 4 | 核心记录长度60 |
| 20 | 4 | bank跨度92 |
| 24 | 4 | 映像槽数3 |
| 28 | 4 | 前28字节CRC |
已有文件须能完整读到固定头、逐字节匹配上述布局,且文件长度不超过216;已有零长度文件、未知布局及超长档案均拒绝。只有本次`CREATE_NEW`成功的新档案可以写固定头,随后才复制并登记seed。存储文件不存在时,若任一固定源槽、安装目标或临时文件已存在,也拒绝新建,避免把缺失元数据当作首次使用。
| bank内偏移 | 长度 | 内容 |
|---|---:|---|
| 0 | 4 | ASCII `UPB1` |
| 4 | 4 | 载荷长度60 |
| 8 | 8 | 非零物理代次,每次元数据提交递增 |
| 16 | 4 | 60字节核心记录的CRC |
| 20 | 4 | bank前20字节CRC |
| 24 | 4 | 提交标记,0为未提交,`0x54494D43`为已提交 |
| 28 | 4 | 保留,全零 |
| 32 | 60 | [核心记录](#firmware-update-wire),仍有自己的内部CRC和格式检查 |
提交标记不在bank头CRC范围内,可独立清除和发布。每次提交先重读并检查两份bank;任一份损坏或系统I/O错误、两份有效但同代次核心载荷不同,均在任何写入前失败,不改写介质。检查通过后,选择非最新的有效副本或未提交副本作为目标,不覆盖选定的最新有效副本,也不通过覆盖损坏副本继续提交;新代次为当前最大有效代次加1,耗尽则失败。文件格式保持不变。一次提交有三个顺序阶段:
1. 把目标bank标记清零,`FlushFileBuffers`成功后继续。
2. 写完整92字节候选(标记仍为零),再次同步。
3. 写已提交标记并第三次同步,全部成功才向核心返回true。
重开时先分类每份bank,再选载荷;损坏和系统读取错误都使本次读取失败,不能因另一份有效而忽略。提交前也执行相同的检查。
| 两份bank的读取结果 | 恢复行为 |
|---|---|
| 任一Seek/ReadFile系统失败 | ERROR,不猜测另一份就是最新事实 |
| 实际读0字节,或至少读到28字节且标记为0 | 该bank为未提交;其中可残留旧头、旧载荷或不完整候选 |
| 非未提交bank但不足92字节,或魔数/长度/CRC/非零提交标记/保留位/代次非法 | 该bank损坏,返回ERROR;即使另一份有效且代次更新也拒绝 |
| 两份均未提交 | metadata_read返回EMPTY;已有宿主档案恢复到EMPTY仍被Open拒绝,不自动重新Provision |
| 一份有效、另一份未提交 | 选择有效副本;标记为零的候选不参与代次竞争 |
| 两份有效、代次不同 | 选择较大代次 |
| 两份有效、代次相同 | 核心载荷一致则选bank0;不一致为冲突,ERROR |
选出的载荷还须由核心Init验证内部CRC和角色约束;这一步失败不会绕回后端自动试用另一份。Init不验证负载,后续Begin/Prepare_Boot复验保留角色,Confirm也复验源槽。两份元数据能处理提交窗口中的旧新版本选择,可检测的已提交损坏必须报错,不得用旧授权或旧角色继续运行。但这不保证任意介质破坏均可识别:整段删去导致EOF,或标记被改为零,可能与未提交无法区分;没有外部提交账本就不能证明被删除的最新提交曾存在。文件头也没有第三份备份,格式迁移、现场损坏修复及基线重新登记都不属于自动恢复动作。
### 3.2 安装别名及健康确认
元数据角色是依据,文件名和修改时间不参与版本选择。INSTALLING时先把旧current复制为`dtu-1`,再把candidate复制为`dtu`;STABLE和ROLLING_BACK则从原backup/current恢复两个别名,没有原backup时先删除`dtu-1`。回退不把试运行候选当作旧版备份。
每次复制都完整写对应`.new`文件,检查短读/短写,Flush后关闭,再以`MoveFileExA`的替换及写穿透标志发布目标,最后重新打开目标核对长度和CRC。两个别名并非一个原子事务;任何中断由已持久化的安装/回退意图及不变的源槽恢复。实现的持久边界仍依赖操作系统和介质兑现同步,不把成功的宿主故障注入等同于物理掉电保证。
宿主Confirm再次核对实际`dtu`:TRIAL时与candidate匹配后调用核心Confirm,核心复验源槽并轮转角色;STABLE时与current匹配即可成功,不写元数据、不重复轮转。安装文件不匹配只返回false,不由该文件检查直接置核心faulted;主示例将该失败锁存在应用层并退出。调用者必须已完成协议及应用就绪检查,这仍不证明负载能在某款MCU执行。
<a id="firmware-update-host-api"></a>
### 3.3 宿主门面与生命周期
完整声明及参数见[宿主头文件](../../examples/iec104_example_upgrade.h)。下表省略`Example_Upgrade_Store_`,除Close为void外都返回bool;描述输出按值返回,失败保持输出。
| 接口 | 状态、所有权和失败边界 |
|---|---|
| Open | 首次使用零初始化对象;取得独占元数据句柄,加载已有角色或用显式seed登记基线,不调用Prepare_Boot;失败释放本次句柄但保留已创建档案 |
| Close | 先关源槽再释放元数据锁,禁用核心及上传;可重复调用,不删文件、不自动Abort或Confirm |
| Current | 只查询健康核心的已确认描述,TRIAL仍返回旧current;不读源槽或dtu |
| Candidate_Open | 仅健康STABLE且无活动上传;只预留包头和整包长度,不清槽、不立即Begin |
| Candidate_Write | offset包含16字节包头,连续且不越界;头可跨段,完整且版本高于current后才Begin,后续只写负载;内部失败关闭本次接收资格 |
| Candidate_Finish | 收齐后关闭接收资格,再同步、读回并提交VERIFIED;CRC拒绝需Abort后重传,I/O/提交不确定须停下恢复 |
| Candidate_Abort | 未授权候选持久撤销后才清门面标志;STABLE无候选时幂等,不撤回授权,失败不清标志 |
| Candidate_Info | 仅健康VERIFIED可取描述,供END固定目标;取得描述不是取得安装授权 |
| Authorize | 只持久保存已领取的授权,不安装;false可能已经落盘,不能盲目转为Abort |
| Prepare_Boot | 调用方先结束活动上传;每次启动/激活调用一次,由核心选择安装或恢复;返回true也可能表示已回退旧current |
| Confirm | 由实际就绪条件触发,按上一节分别处理TRIAL和STABLE;不能以收到END或ACK代替调用时点 |
候选门面和核心的偏移单位不同,但都是易失会话状态。包头完整前断开只需清门面上传;核心Begin之后断开还须提交Abort。入口参数错误不会推进偏移;内部写失败即使返回false也可能留下已提交RECEIVING和部分槽字节。主示例检查核心faulted:单纯包头/CRC/许可拒绝可完成原handle收尾后重传,存储不确定错误则退出并重开恢复。
启动路径为Open → 一次Prepare_Boot → 协议初始化及COI登记 → 实际文件健康Confirm → 发布确认版本。运行期路径在[应用调用流程](../104/IEC104_完整调用流程.md#flow-software-upgrade)中:Take成功先把清理所有权交给持久任务,再Authorize,完成协议收尾及延时后Prepare_Boot,重新就绪后Confirm。普通105协议复位没有已领取升级任务时不再次Prepare_Boot,因此不会把当前试运行错误地当作下一轮启动。
Close不是协议收尾替代品。外层先按原文件handle、owner及transfer token交完COMMIT/ABORT/ABANDON义务,再关闭后端;授权提交结果不确定时,应用的`persistent_handoff`阻止普通取消清掉持久事实。当前进程退出只结束内存任务,磁盘AUTHORIZED/INSTALLING/TRIAL留给下次启动恢复。日志及版本发布时点见[示例操作说明](../examples/IEC104子站示例.md#example-firmware-update)。
<a id="firmware-update-recovery"></a>
### 3.4 中断窗口与恢复动作
下表以重开后实际选出的有效元数据为准,不从上次API返回false推测是哪一行。物理错误仍存在或保留角色无法验证时,恢复也会失败;不通过重试清空文件来绕过故障。
| 中断窗口/恢复状态 | 重新Init后的处理 |
|---|---|
| 首次写头、复制seed或Provision提交前中断 | 可能留下无有效基线的已有档案;宿主Open拒绝,不借seed覆盖或自动清库 |
| Begin提交前 | 仍STABLE,未授权;核心未允许清槽,正常启动已确认映像 |
| RECEIVING已提交,清槽或写入中断 | 偏移不恢复;Prepare_Boot持久取消候选,再确保旧current已安装 |
| Finish同步/读回或VERIFIED提交期间 | 恢复为RECEIVING或VERIFIED都视为未授权,启动时取消 |
| Authorize提交期间 | 若仍VERIFIED则取消;若AUTHORIZED已有效,则继续安装;应用失败清理不能擅自撤销 |
| INSTALLING意图提交前后、目标复制/替换中断 | AUTHORIZED先提交意图;INSTALLING复验候选并以同一事务幂等重做;候选不可读/不合格时提交ROLLING_BACK |
| 安装完成、TRIAL提交未生效 | 仍INSTALLING,重做幂等安装后提交TRIAL |
| TRIAL已提交,但尚未确认,包括尚未实际跳入新程序就断电 | 下次Prepare_Boot视为未确认,先提交ROLLING_BACK,再恢复原current/backup |
| ROLLING_BACK期间、或回退完成但STABLE提交未生效 | 继续按原角色幂等回退,成功后才取消candidate角色 |
| Confirm提交期间 | 若仍TRIAL则下次启动回退;若STABLE已有效则新current生效,按新角色确保安装文件 |
| STABLE启动修复安装文件失败 | 核心仍STABLE并闭锁;重开后仍修复同一确认版本,不制造候选或回退角色 |
元数据bank三阶段对应另一组边界:目标标记清零后和完整候选写入后都不得选目标bank;标记发布且全部校验有效才可成为新版本。第三次同步失败可能已经发布,必须重扫。安装别名读回失败、源槽I/O、元数据错误和纯参数拒绝不可归为同一类:前者由应用或核心停机恢复,后者可修正请求;恢复不会自动重放协议ACK或重新取得一次授权。
<a id="firmware-update-resources"></a>
### 3.5 资源寿命与同步预算
核心拥有60字节wire及256字节读回缓冲;宿主额外拥有两个92字节bank工作区、256字节复制缓冲、16字节包头、200字节父目录,以及固定的状态和句柄字段。这些数组容量由源码确定,不是包含ABI填充、调用栈或操作系统缓存的总RAM测量。宿主实例不能移动,因为回调context指向自身;所有调用串行,句柄的共享文件指针不能被并发Seek/Read/Write。
| 资源 | 获取及释放 |
|---|---|
| upgrade.store句柄 | Open以共享模式0取得,维持后端单写者约束;Close最后释放 |
| 三个源槽句柄 | 首次访问时惰性独占打开,保持到该槽下一次image_begin重置或Close |
| seed句柄 | 只在首次Open复制/校验基线期间持有,无论结果都收尾关闭 |
| 安装临时文件句柄 | 单次复制期间持有,关闭后才替换目标;失败文件可能保留,但句柄归还 |
| 已安装目标读句柄 | 单次长度/CRC检查期间持有,检查结束关闭 |
| 上传小包头及偏移 | 归同一ExampleUpgrade对象;Abort/Close结束使用资格,不形成跨重启快照 |
整包上限16MiB且至少17字节,单槽负载上限为`L = 16 MiB - 16 B`。按所有固定映像文件都占满的保守容量计算,三个源槽、两个安装别名及两个残留临时文件合计至多`7 × L`,另加最多216字节元数据;这不含调用方seed包、文件系统分配开销或其他业务数据,也不表示这些文件同时必然存在。
核心Verify和宿主复制均按256字节分块,但函数仍同步读完或复制完整映像,不在块间把执行权还给协议调度器。Begin复验current/backup,Finish完成同步及候选全量读回;Prepare_Boot可能同时承担保留槽和候选校验、两份目标复制及读回,Confirm还会读回dtu并复验源槽。元数据每次提交包含三次Flush,因此文件最终回调和激活阶段的耗时不能按单个数据段估计。
代码未设置独立安装任务或固定耗时上限。目标适配须核算完整调用链栈、介质带宽、Flash擦写时间、看门狗及同步失败策略;固定小缓冲不等于已满足目标实时预算。原RAM演示的64KiB静态候选数组仍保留在宿主程序,持久模式不会动态释放它;不能据流式接收宣称整个可执行文件已省掉该数组。
<a id="firmware-update-usage"></a>
## 4. 工程包与运行
使用既有I104工程包:ASCII `I104`、u32le版本、u32le负载长度、u32le负载CRC32,随后非空负载。CRC算法和报文顺序见[工程包契约](../104/IEC104_SoftwareUpgrade_设计架构.md#software-upgrade-package)。文件名仍为`upgrade.bin`;安装目标名`dtu`是本宿主后端约定。
打包、首次建库、重复启动、线上操作及版本核对的完整命令集中在[持久安装操作入口](../examples/IEC104子站示例.md#example-firmware-update),工具实现为[make_upgrade_package.cjs](../../scripts/make_upgrade_package.cjs)。`--upgrade-store`自动开启210/211,首次显式seed与后续禁止seed覆盖的规则由后端落实,不是仅靠CLI提示约束。
202的0x8005/0x8006来自已确认描述,不能把传输包、END肯定或TRIAL中的dtu提前发布为确认版本。配合`--user-log`时,持久模式阶段标为`HOST_FILE`,原RAM演示为`SIMULATED`;阶段记录只表达该动作已发生,不扩大健康检查的证明范围。
<a id="firmware-update-target"></a>
## 5. 板端接入边界
板端实现同一存储回调:槽放在适合的非易失介质,元数据保证原子提交;`install`执行目标Flash安装或启动槽选择并读回验证。应用收到Take后完成Authorize,再请求平台进入Bootloader;Bootloader在同一启动轮调用Init和Prepare_Boot,得到本次启动描述后直接跳转所选映像。install回调内不得复位,Prepare_Boot成功后也不能再额外复位,否则TRIAL会被下一轮启动判为未确认并回退。
新应用达到产品定义的健康条件后调用Init恢复状态,再调用Confirm,**不能再次调用Prepare_Boot**,否则同一试运行会被当作上一轮未确认启动而回退。若新应用未能运行到确认点,由看门狗或复位使Bootloader再次进入Prepare_Boot;TRIAL随即恢复旧版。普通轮询、读版本和网络重连也不能调用Prepare_Boot。
Bootloader和新应用必须共享相同的元数据格式、槽映射和后端持久契约。实际跳转后若使用新的核心实例,Init只恢复TRIAL,应用完成健康检查后调用Confirm即可;不需要也不能通过再次安装“确认”新版本。单独调用Get_Status或读取版本也没有安装及确认副作用。若硬件安装方案必须在Prepare_Boot之后再次复位,须先另行设计启动握手,不能直接套用当前一次Prepare契约。
Flash分区、应用链接地址、向量表切换、掉电时存储行为、看门狗时限、签名与机型验证均由目标适配提供。本次只在IEC60870-Slave实现公共核心、Windows后端及协议接线;目标工程注册、ARMCC构建、实际安装和硬件故障试验尚未完成。
<a id="firmware-update-tests"></a>
## 6. 验证入口
构建命令、场景映射和实际运行结果集中在[持久升级测试记录](../test/IEC104测试文档.md#firmware-update-tests),协议及原RAM演示另见[软件升级测试](../test/IEC104测试文档.md#software-upgrade-tests)。本设计不复制运行数量和产物结论。
验证分为三层:[核心夹具](../../test/iec60870_firmware_update_test.c)以可跨Init保留的内存介质检查状态及提交前后失败;[Windows后端测试](../../test/iec104_example_upgrade_test.c)使用实际文件及同步/替换后的故障钩子;[TCP回环](../../test/firmware_update_loopback_test.cjs)独立构造报文和CRC,核对线上授权与实际安装内容。夹具不证明文件系统行为,故障钩子不等于切断供电,宿主负载从不执行;这些验证不能代替目标ARMCC、Flash、Bootloader及硬件健康确认验收。
@@ -0,0 +1,348 @@
<a id="history-design"></a>
# 历史记录、持久存储与 XML 文件生成
本模块实现[规范 PDF](../../20170804163032284877151.pdf)附录 B 的 SOE、遥控操作、定点和极值记录。循环记录与 XML 编码可移植;示例通过 Windows 文件后端提供持久化,再由现有 TI=210 文件服务提供目录和下载。FRZ、FLOWREV 与附录 C 的 ULOG 不在本模块范围内。
ULOG由独立的[运行日志模块](IEC60870_UserLog_设计架构.md#user-log-design)实现1024条循环及XML,示例通过`--user-log`启用并使用`ulog.store`;可与`--history`共用父目录,但不共用核心实例、槽布局或持久文件。
## 1. 模块边界
| 实现 | 职责 |
|---|---|
| [IEC60870_History.h](../../common/IEC60870_History.h)、[核心实现](../../common/IEC60870_History.c) | 点表校验、固定容量记录、UTC+8 日归属、极值累计、序列化、CRC 与启动恢复 |
| [IEC60870_HistoryFile.h](../../common/IEC60870_HistoryFile.h)、[XML 编码](../../common/IEC60870_HistoryFile.c) | 附录 B.3.2 的四种 XML、大小写敏感文件名、分块输出与导出范围 |
| [宿主适配接口](../../examples/iec104_example_history.h)、[Windows 后端](../../examples/iec104_example_history.c) | 双副本原子提交、独占文件、目录快照、稳定读文件 |
| [子站示例](../../examples/iec104_slave_example.c) | 记录来源、墙钟基准、命令行选项及 FileService 回调接线 |
| [FileService](../../104/business/IEC104_FileService.h) | TI=210 协议、目录时间筛选、分段传输、会话收尾 |
```mermaid
flowchart LR
A[变位 / 遥控 / 遥测观测] --> B[History 核心]
B --> C[持久存储接口]
B --> D[HistoryFile XML]
D --> E[不可变文件快照]
E --> F[TI=210 FileService]
```
核心和编码器不分配堆内存,也不依赖 RTOS、TCP 或文件系统。调用者持有实例和点表,串行调用写入、读取及导出接口。记录保存与实时上报分别推进:实时发送成功、重连、发送事件清理和协议实例重建都不删除持久历史。
<a id="history-time-rules"></a>
## 2. 容量与时间规则
| 类型 | 内部保留 | 导出范围 | 文件路径 |
|---|---|---|---|
| SOE | 最新 1024 条 | 最新 1024 条,不足时按实数 | `HISTORY/SOE/soe.xml` |
| 遥控操作 | 最新 30 条 | 最新 30 条,不足时按实数 | `HISTORY/CO/co.xml` |
| 定点 | 32 个日期槽,每日最多 96 节 | 最新 30 个完成日中实际存在的数据 | `HISTORY/FIXPT/fixptYYYYMMDD.xml` |
| 极值 | 32 个日期槽,每日每点一组最大/最小值 | 最新 30 个完成日中实际存在的数据 | `HISTORY/EXV/exvYYYYMMDD.xml` |
32 个日期槽用于保留 31 个完整历史日及正在累计的当天。导出窗口是相对于最后恢复或观测到的日期计算的 30 个已完成日;缺数据的日期不补文件,也不向更早日期扩展来凑满 30 个文件。恢复后应先用可信墙钟推进观测,再对外提供符合当前日期的目录。
全部 UTC 毫秒输入必须能表示固定 UTC+8 的 2000-01-01 至 2099-12-31。两位 XML 年份按 2000 年起解释;`time_valid=false` 不放宽日历范围。`IEC60870_History_Local_Day` 返回自 1970-01-01 起的本地日序号,越界返回 `UINT32_MAX`。
定点第 1 节的区间结束时刻为 `00:15`,第 96 节为同一天的 `24:00`。内部实际采样时间可表示为次日 `00:00`;保存的日期和槽号仍归前一天。午夜先处理前一天第 96 节,再开始新一天的极值累计。支持范围第一天的午夜不会生成 1999-12-31 的文件。
`Observe` 应接收持续产生的遥测,而不是只在每 15 分钟调用。每次观测更新各点极值;只有落在整刻之后 `freeze_grace_ms` 容差窗口内的首个有效观测才保存定点。容差范围为 0~1000 ms,定点记录保留实际采样时间,XML 节时间使用规定的区间结束时刻。缩小现行容差不会使旧记录失效,读取只检查所有版本共有的 1000 ms 上限。
每节包含全部配置遥测点。只有品质字节为 0 且数值有限的样本有效;任一点无效时跳过该节,窗口结束后不补造。极值逐点判断,有效点仍可更新;未出现过有效样本的点不导出极值。相同极值保留首次发生时刻。
同一日期和槽号不会因重试重复记录。观察时间早于本实例已观测时间时返回 `TIME_REVERSED`,不回写旧日;调用方等待墙钟追平。重启后时间下限由实际持久记录恢复,因此未改变极值且未形成定点的纯观察时刻不构成持久化时钟水位。已保存定点仍按日期和槽号去重。
<a id="history-core-api"></a>
## 3. 核心接口与恢复
`IEC60870_History_Init` 借用配置中的 SOE、遥控、遥测三组点表,以及 `read/commit` 存储回调。IOA 必须在 24 位非零地址范围内,各表不得重复;遥测最多 32 点。任何不在相应点表中的 SOE、遥控写入都返回 `INVALID`。
点表的数量、地址和顺序生成持久指纹。启动扫描遇到不同指纹返回 `CONFIG`,不将旧位置的数值解释成新点,也不自动清空旧文件。改变现场点表必须迁移存储或显式选择新的存储命名空间。单位由 XML 配置另行提供;宿主演示使用空单位,实际接入应提供与保存数值一致的工程单位。
记录具有固定小端字段、版本、点表指纹、事件序号或日期槽、时间和 CRC32。数值按 IEEE 754 binary32 保存,C 结构体填充和主机字节序不进入文件。启动逐槽检查 CRC、布局、时间、地址与逻辑归属,并重建事件头尾、最新观测日期及时间。
事件按序号递增,按容量取模写槽。恢复按仍可见记录的最大序号检查保留序列连续性,拒绝该范围内的缺口;没有独立的持久序号下界时,最新提交证据全部消失仍可能使历史尾部缩短,检测限制见[恢复矩阵](#history-recovery-matrix)。日记录按日期取模,但读取同时核对完整日期,避免把旧轮转数据误当当前日期的数据。
存储回调的约定如下:
- `read` 返回 `OK`、`EMPTY` 或 `ERROR`,其中 `EMPTY` 只表示从未有效提交该槽。
- `commit` 原子替换一个槽;成功必须代表新记录已经可靠持久化,失败前不能破坏旧的已提交记录。
- 提交失败可能已经写成新记录,例如最终同步后上层得到错误。核心进入 `faulted`,必须重新 `Init` 恢复事实后才继续;调用者不能原样盲重试并声称没有副作用。
- 一个 `Observe` 可以分别提交定点和极值,并非跨记录事务。前一个提交成功、后一个失败时,恢复保留前者;同一时间重试不会重复定点。
当日极值每次发生变化就提交,包括值和发生时间,不等到午夜才写盘。重启后继续读取当天已有极值累计,避免遗失此前峰值。日切换即使全部样本无效,也保存该日的空极值状态,使恢复能够知道日期已前进;空极值状态不生成虚构数值。
### 3.1 内存状态与值对象
公开结构用于调用方静态分配,不表示业务可以直接修改内部状态。配置和存储回调表被浅拷贝;点表数组及存储 `context` 仍由调用方持有,整个实例使用期间必须有效且保持不变。
| 对象或字段 | 实际含义与更新时机 |
|---|---|
| `config`、`fingerprint` | 三组点表及其有序指纹;`freeze_grace_ms` 不参与指纹,调整容差不改变旧记录的点号含义 |
| `event_sequence[2]`、`event_count[2]` | 分别对应 SOE、CO 的最大序号与当前条数;只有单槽提交成功后才推进 |
| `latest_day`、`have_day` | 最新测量日及其是否存在;由恢复到的定点/极值或成功观测建立,SOE、CO 不推进它 |
| `observed_utc_ms` | 本次运行的观测时间下界;重启仅能从已落盘测量记录恢复,不能恢复没有写入的纯观测时刻 |
| `initialized`、`faulted` | 恢复完成后才可使用;读取损坏、指纹不符或提交失败会阻止后续访问,须重新初始化核对存储事实 |
| `wire[1024]`、`work_extrema` | 单条编码和当日极值候选工作区;每次操作会复用,不能跨调用保存其中指针 |
| `HistoryEvent` | 事件序号、UTC 毫秒、点号、状态、品质、操作阶段及时间有效位的独立值副本 |
| `HistoryFixed` | 归属日、原始节号、实际采样时间及全部配置遥测值/品质;数组按点表顺序对应 |
| `HistoryExtrema` | 归属日、最近一次持久化变更时间和逐点最大/最小值及其发生时间;`valid=false` 的点无有效累计结果 |
### 3.2 API、返回值与调用次序
下表省略函数名前缀 `IEC60870_History_`。参数校验、输出保持和所有权的完整声明见[核心头文件](../../common/IEC60870_History.h)。
| 接口 | 输入与输出 | 关键失败或边界 |
|---|---|---|
| `Slot_Count(kind)` | 查询后端布局所需的逻辑槽数 | 未知类别返回 0,不含后端冗余空间 |
| `Local_Day(utc_ms)` | UTC 毫秒转换为本地日序 | 越出可表示日历返回 `UINT32_MAX` |
| `Init(self, config, store)` | 扫描全槽并恢复索引;不改写介质 | 参数校验失败不重置旧实例;开始扫描后失败则新实例不可用 |
| `Append_Soe(...)` | 对白名单点追加一次变位,状态范围 0..3 | 不检测变化、不自动去重;应用不能在发送重试时重复调用 |
| `Append_Control(...)` | 对白名单点追加选择、执行或撤销阶段 | 记录阶段不等于证明设备动作成功;状态范围 0..3 |
| `Observe(...)` | 输入同一时刻的完整遥测数组;先定点,后极值 | `count` 须匹配点表;时间回退不写;两个提交不是一个事务 |
| `Event_Count(kind)` | 只读内存中已恢复/已提交的条数 | 空库、未知类别、未初始化和故障实例都返回 0,不能用它单独判健康 |
| `Get_Event(kind, oldest_index, out)` | 下标 0 为保留区最旧记录;成功复制值到 `out` | 越界/缺槽为 `EMPTY`;不借出 `wire` 指针 |
| `Read_Fixed(day, slot, out)` | 读取原始 1..96 节号 | 缺测、超存储窗口、同物理槽已属于其他日期均为 `EMPTY` |
| `Read_Extrema(day, out)` | 可读取完成日,也可读取当前日累计 | 有记录仍须逐点检查 `valid`;是否允许导出由文件层再判断 |
| `Latest_Day(out)` | 输出最新测量日 | 尚无测量日或实例不可用返回 false,保留输出值 |
`Get_Event`、`Read_Fixed`、`Read_Extrema` 仅在 `OK` 时填写输出。状态码含义如下,不能把所有非 `OK` 都视为可重试:
| 返回值 | 含义 | 调用方处理 |
|---|---|---|
| `OK` = 1 | 本次操作成功 | `Observe` 可能没有产生新记录,不按返回次数推算定点条数 |
| `EMPTY` = 0 | 查询无记录,或没有配置遥测点 | 保留实际缺口,不补造数据 |
| `ERROR` = -1 | 参数之外的状态、读取、提交或容量边界错误 | 若已 `faulted`,重新恢复前不得继续;序号耗尽也返回此值 |
| `INVALID` = -2 | 点号、数量、时标或其他调用参数不合法 | 修正输入,不能重放已发生的设备动作来“补一次调用” |
| `CONFIG` = -3 | 持久记录指纹与当前点表不同 | 保留原数据,按[迁移责任](#history-failure-migration)处理 |
| `TIME_REVERSED` = -4 | 观测时间早于当前下界 | 暂停该次测量记录,等待可信墙钟追平;既有历史不回写 |
```mermaid
sequenceDiagram
participant A as 应用
participant H as History
participant S as 存储后端
A->>H: Init 点表与存储回调
H->>S: 逐槽读取并校验
S-->>H: 已提交记录 / 空槽 / 错误
H-->>A: 恢复成功或明确失败
A->>H: Append 或 Observe
H->>S: 原子提交一个逻辑槽
S-->>H: 已持久化 / 结果不确定
alt 提交成功
H-->>A: 推进相应索引并返回
else 提交失败
H-->>A: faulted,要求重新恢复
end
```
应用在变位或操作阶段发生处追加一次,再独立安排实时上报;测量侧持续提供观测。查询和导出必须与上述写入串行。核心不创建线程、锁或后台刷盘任务,`commit` 也不是“排进异步队列就成功”的接口。
<a id="history-record-layout"></a>
### 3.3 核心记录字节布局
下列布局是内部持久格式,不是附录 B 的对外 XML。整数均为小端,浮点按 binary32 位模式保存。固定头 36 B,末尾 CRC32 为 4 B;CRC 覆盖从偏移 0 到载荷末尾,不包括 CRC 字段自身。
| 字节偏移 | 长度 | 内容 |
|---|---|---|
| 0 | 4 | 魔数 `HST1` |
| 4 | 1 | 版本 1 |
| 5 | 1 | 类别:SOE=1、CO=2、FIXPT=3、EXV=4 |
| 6 | 1 | 遥测点数;事件为 0 |
| 7 | 1 | 保留,须为 0 |
| 8 | 4 | 点表指纹 |
| 12 | 8 | 事件序号;日记录为 0 |
| 20 | 8 | UTC 毫秒;定点为实际采样时刻,极值为本次累计变更时刻 |
| 28 | 4 | 本地归属日;事件为 0 |
| 32 | 2 | 定点节号 1..96;其他类别为 0 |
| 34 | 2 | 保留,须为 0 |
| 36 | 按类别 | 载荷 |
| 载荷末尾 | 4 | 核心 CRC32 |
| 类别 | 载荷顺序 | 总字节数 |
|---|---|---|
| SOE / CO | IOA 4 B、状态 1 B、品质 1 B、操作阶段 1 B、时间有效位 1 B | 48 B |
| FIXPT | 按点表顺序重复:浮点值 4 B、品质 1 B | `40 + 5 × N`,32 点为 200 B |
| EXV | 按点表顺序重复:有效位 1 B、最大值 4 B、最小值 4 B、最大值时间 8 B、最小值时间 8 B | `40 + 25 × N`,32 点为 840 B |
SOE 的操作阶段字段固定为 0;CO 的品质字段固定为 0。点号不在定点/极值载荷逐项重复,必须通过匹配的点表指纹解释。指纹按三组点数及有序点号形成,CRC 与指纹均不提供密码学认证。
物理槽由内容反向校验:事件为 `(sequence - 1) % capacity`;定点为 `(day % 32) × 96 + slot - 1`;极值为 `day % 32`。定点读取还核对硬容差上限、区间终点及归属日;极值核对数值有限、最大值不小于最小值、发生时刻位于同日且不晚于累计变更时刻。通过 CRC 不会跳过这些语义校验。
<a id="history-store-layout"></a>
## 4. Windows 持久化后端
`Example_History_Open` 在调用者提供的已有目录内打开 `history.store`,整个实例生命周期独占该文件。存储头不兼容或核心恢复失败时拒绝打开,不自动格式化。
每个逻辑槽有两个 bank,各带代次、长度、头部 CRC、载荷 CRC 和提交标记。读取和提交都先检查两份 bank;任一份损坏或发生系统 I/O 错误均失败,即使另一份有效或代次更新也不继续。两份有效但同代次内容不同也拒绝。提交前检查失败不改写介质;检查通过后,提交选用较旧或未提交的 bank,顺序为:
1. 清除目标 bank 的提交标记并 `FlushFileBuffers`。
2. 写入新头部与完整记录,再次 `FlushFileBuffers`。
3. 写入有效提交标记,第三次 `FlushFileBuffers` 后才报告成功。
旧 bank 在新版本完成前保持可恢复;标记为零的未提交候选可以忽略。检测到已提交副本损坏时,整个逻辑槽读取和提交都失败,不能退选另一份来掩盖损坏,也不能覆盖坏副本来继续写入。只有通过两份 bank 的检查后,才在有效副本中选择较高代次。后端 CRC 与核心记录 CRC分别校验存储封装和业务记录;本次收紧检查不改变文件格式。
这个协议依赖操作系统和存储设备兑现同步契约。测试覆盖同步边界处中断、损坏副本、同代次冲突和重开恢复,最新执行结果见[三后端损坏拒绝验证](../test/IEC104测试文档.md#strict-bank-recovery-validation),完整场景见[历史专项记录](../test/IEC104测试文档.md#history-tests)。**尚未进行真实设备任意时刻断电实验**,不能将宿主测试等同于物理掉电验收。对可检测的损坏明确拒绝启动是失败保护,不能宣称所有介质损坏都可自动恢复。
宿主布局按最大 32 个遥测点预留双 bank;其地址上限约 1.65 MB,不是只按测量值估算的约 260 KB。有效文件长度随写入的最高槽增长;XML目录及读快照还需要临时磁盘空间。真实介质适配可以采用紧凑布局,但必须维持相同原子提交和失败语义。
### 4.1 文件、类别区与 bank 头
`history.store` 的前 32 B 是文件布局头:偏移 0..13 为 `IEC104-HISTORY1`,16..19 为最大遥测点数 32,20..23 为日槽数 32,28..31 为前 28 B 的 CRC,其余保留字节写零。打开时与当前布局头完整比较;它与每条核心记录中的点表指纹承担不同职责。
类别区按 SOE、CO、FIXPT、EXV 的顺序固定排列,每槽的 bank 0 与 bank 1 相邻。下表的区间采用左闭右开,容量按当前最大配置预留,不随实际点数移动:
| 类别区 | 起始偏移 | 逻辑槽数 | 单 bank 大小 | 区间结束偏移 |
|---|---|---|---|---|
| SOE | 32 | 1024 | 32 B 头 + 48 B 载荷 = 80 B | 163872 |
| CO | 163872 | 30 | 80 B | 168672 |
| FIXPT | 168672 | 3072 | 32 B 头 + 200 B 最大载荷 = 232 B | 1594080 |
| EXV | 1594080 | 32 | 32 B 头 + 840 B 最大载荷 = 872 B | 1649888 |
某 bank 的地址为 `类别区起点 + (逻辑槽号 × 2 + bank号) × 单bank大小`。提交只写实际核心记录长度,后续未使用的预留尾部不参与载荷 CRC。文件可能因高偏移写入形成未写空洞,不能仅凭总文件长度推算记录条数。
| bank 内偏移 | 长度 | 内容与检查 |
|---|---|---|
| 0 | 4 | 魔数 `HSL1` |
| 4 | 4 | 实际核心记录长度,不能超过本类别最大载荷 |
| 8 | 8 | 本逻辑槽的提交代次,从 1 起;不是 SOE/CO 的业务事件序号 |
| 16 | 4 | 实际载荷 CRC32,包含核心记录自身的 CRC 字段 |
| 20 | 4 | 前 20 B 的头部 CRC32 |
| 24 | 4 | 提交标记:0 表示未提交候选,`0x54494D43` 表示已提交;其他非零值为损坏 |
| 28 | 4 | 保留,写入时清零 |
| 32 | 实际长度 | 完整核心记录 |
标记不包含在头部 CRC 内,便于最后单独提交。两份 bank 均通过分类和冲突检查后,选择目标时保留最新有效 bank,写另一个有效旧 bank 或未提交 bank;新代次取有效副本最大代次加 1。损坏、I/O 错误、同代次内容冲突或代次耗尽均在写入前返回失败,不回绕代次,也不清除损坏证据。后端工作区固定为实例内两个 bank 缓冲,存储历史不整体驻留 RAM。
<a id="history-recovery-matrix"></a>
### 4.2 三阶段提交与恢复矩阵
以下矩阵描述可观察的存储事实,不把“函数返回失败”解释成“介质一定没变”。阶段边界以真实 `FlushFileBuffers` 完成点定义。
| 中断或读取状态 | 另一 bank 有有效旧记录 | 另一 bank 未提交 |
|---|---|---|
| 清标记尚未完成 | 重新分类两份 bank;若出现损坏则报错,否则按有效代次选择 | 两份未提交才为空;任一损坏均报错 |
| 阶段 1 完成:目标标记为 0 | 恢复旧记录 | 两 bank 均无提交记录时返回 `EMPTY` |
| 阶段 2 完成:候选头/载荷已同步,标记仍为 0 | 仍恢复旧记录,不能提前采用候选 | 仍视为未提交,不把候选暴露为新记录 |
| 阶段 3 完成:有效标记已同步且完整记录校验通过 | 采用更高代次的新记录;另一份也须有效或未提交 | 采用新记录 |
| 标记为零,候选头/载荷不完整或 CRC 不匹配 | 忽略未提交候选,恢复旧记录 | 两份均未提交时返回 `EMPTY` |
| 非零非法标记、不能确认标记的短记录,或已提交记录校验失败 | 返回错误;不退选旧记录,也不忽略损坏的较旧 bank | 返回错误,不自动重建或清空 |
| 两份有效且代次相同 | 长度及载荷相同才选 bank 0;不同则冲突报错 | 不适用 |
| 最终同步结果不确定,核心已得到失败 | 实例进入 `faulted`;重新打开后按实际事实恢复旧记录、完整新记录或报告损坏 | 同样必须重新读取后判定,不能盲目重放 |
读取两个 bank 时,底层定位/读取 I/O 错误或任一 bank 损坏都直接上报;不能因为另一份碰巧有效就掩盖错误。实际读到 0 字节,或至少读到 28 字节且提交标记为零,归为未提交;其他非零非法标记、无法确认标记的短读以及已提交记录的长度、头部或载荷校验失败均为损坏。两份都有效时选择较高代次;代次相等仅在长度及载荷相同时选 bank 0。仅一份有效且另一份未提交时选有效副本;两份均未提交才返回 `EMPTY`。提交复用相同的损坏和冲突检查,检查失败时尚未执行任何写入。外层恢复成功后还要经过核心 CRC、字段和事件连续性检查。
上述规则拒绝可见的损坏,不保证所有历史回退都能检出。某 bank 被整段截去而读到 EOF,或曾经提交的标记后来被清零,可能与从未提交的候选无法区分;其他记录的序列约束有时能提供缺失见证,但没有外部提交账本就不能证明每条消失的最新记录曾存在。读取成功仍不能等同于介质从未丢失数据。
首次打开对象必须清零,已打开对象再次 `Open` 会被拒绝而不丢失句柄。只有本次新创建的零长度文件可以写初始布局头;已经存在但长度为零、头部截断或布局不符的文件均拒绝打开。失败时关闭本次句柄,保留磁盘文件供诊断。新文件的布局头初始化不是另一套自动修复协议;首次创建过程中损坏也可能需要调用方处理。
## 5. XML 与下载快照
`IEC60870_HistoryFile_Name` 构造完整、大小写敏感的虚拟路径。`IEC60870_HistoryFile_Write` 通过同步 sink 分块输出;成功后才更新输出大小,失败时可能已经写出前缀,调用者必须丢弃整个候选。编码期间禁止修改核心、点表及编码配置。
本实现选择附录 B 允许的 XML,`Header` 使用 `fileVer="1.00"`。SOE、CO 使用 `DataRec num`,时标为 `YYMMDD_HHMMSS_MS`;CO 的 `cmd` 为 `select/oper/cancel`。EXV 使用 `DataAttr num` 和一组按点表顺序排列的 `max/max_tm/min/min_tm`。FIXPT 使用 `dataNum/sectNum/interval="15min"`,每节以原始 1~96 槽号标识;缺节时 `sectNum` 是实际节数,不重排剩余槽号。
设备名和单位校验 UTF-8/XML字符,并转义属性中的特殊字符。IOA 和数值输出十进制,浮点小数点固定为 `.`。XML 的字段大小写、元素顺序及时间形式依据规范示例;不沿用 MSG 的十六进制地址规则。
内部 SOE 保存品质及时间有效位,但附录 B 的 XML 模板没有独立的品质/时间 IV 属性。本实现不添加自定义属性,也不把无效时标换成导出时刻;保留采集时记录的日历,调用方必须了解导出无法表达该无效位。宿主示例启用历史时建立可编码的墙钟基准,生产接入仍须保证该时间源可信。
宿主目录打开时将选定目录的全部 XML冻结到临时文件,保存对应名称、大小、时间和偏移。目录结束后仍保留这版快照供随后读文件;下一次目录打开替换缓存。读文件拥有独立快照,后续变位、轮转或再次召目录都不会改变同偏移读出的字节。临时文件使用关闭时删除标志,退出时释放。
SOE、CO目录时间使用最新一条记录的时间;空文件使用固定纪元标记且记录数为 0。日文件的目录时间为所属日期当地 `00:00`,不使用本次导出时间。召唤标志为 1 的时间筛选由 FileService 按这些目录时间执行,目录名称决定数据类型,不依赖主站请求中的非零目录 ID。
<a id="history-snapshot-lifecycle"></a>
### 5.1 两级快照的所有权与释放
编码器本身不拥有冻结历史视图:它要求整个调用内核心、点表和编码配置不变。定点编码会先遍历 96 槽统计实际节数,再按存在表读取一次输出;期间不能并发轮转。sink 必须同步接收全部片段,字节指针仅回调期间有效,单片甚至可能只是一个 UTF-8 字符的部分字节。
宿主用临时文件把这种串行编码结果转换为可跨多次协议轮询使用的稳定快照,而不是把实时历史槽直接借给网络发送:
| 资源 | 建立与内容 | 保留与释放 |
|---|---|---|
| `storage` | `Open` 打开的独占 `history.store` | 整体 `Close` 释放;协议重建不重新格式化 |
| `directory_file` | `Directory_Open` 把该目录所有候选 XML 顺序拼接到一个临时文件 | `Directory_Close` 只结束枚举,保留缓存;下次有效目录打开或整体关闭才释放 |
| `entries[]` | 同版的完整名称、文件大小、业务时间和拼接偏移,最多 30 项 | 与目录缓存同寿命;枚举结束后仍供后续按名读文件使用 |
| `read_file` | `Read_Open` 从匹配的目录缓存复制该文件;没有匹配缓存时生成当前允许范围内的新快照 | 独立于目录缓存,`Read_Close` 或整体关闭释放;新召目录不改变当前下载 |
| `read_size` | 当前读快照长度 | 读打开成功后发布,读关闭归零;越界读取被拒绝 |
空目录名按 SOE 处理;其他名称与四个固定目录精确匹配。日目录只列当前 30 完成日窗口中有数据的日期。没有匹配缓存时,直接读取只能命中固定事件名或允许窗口内的规范日文件名,不能将任意主站路径拼到宿主目录上;大小写错误、未知名称和无数据的日文件都不能成为成功下载。已经冻结的目录缓存仍按原版本提供文件,即使其原始记录后来轮转出当前窗口,也不会在下载中途切换成新内容。
同一实例最多一个活动目录枚举和一个读快照。开始新目录时旧缓存会被释放;新目录生成失败不会恢复旧缓存,但已经建立的独立读快照仍可继续使用。快照文件采用关闭时删除标志,不是重启后保留的历史数据库。重启后的目录由持久记录重新生成。
```mermaid
sequenceDiagram
participant F as FileService
participant A as 宿主历史适配
participant D as 目录缓存文件
participant R as 独立读快照
F->>A: OPEN_DIRECTORY
A->>D: 冻结该目录 XML 与元数据
F->>A: list 按下标枚举
F->>A: CLOSE_DIRECTORY
Note over A,D: 枚举结束,缓存继续保留
F->>A: OPEN_READ 完整虚拟名
A->>R: 复制缓存对应文件或生成新快照
F->>A: read 偏移与长度
A->>R: 读取固定字节范围
F->>A: CLOSE_READ
A->>R: 关闭并删除临时文件
```
本节只描述适配层所有权。协议的打开/收尾次数、背压、超时及目录时间比较规则统一由[文件服务设计](../104/IEC104_FileService_设计架构.md)定义;历史模块不在网络确认后删除记录,也不因一次读失败清空存储。
## 6. 示例运行与性能边界
在仓库根执行:
```powershell
./scripts/build.ps1 -Test -Suite History -BuildName history-check
New-Item -ItemType Directory -Path .build/history-data -Force
./.build/history-check/iec104_slave_example.exe --ca 1 --history .build/history-data
```
`--history` 自动启用 Type210,替换固定 SOE 演示文件并增加 CO、EXV、FIXPT 目录。SOE来自确认后的单/双点变化;遥控记录来自已交付应用的选择、执行和撤销阶段。入口直接拒绝或 TEST 请求不等同于已执行操作,当前接线不宣称覆盖所有被拒绝报文的审计。
持久化失败会使示例报告错误并停止继续运行,不能静默丢失记录后继续显示成功。历史存储在协议重建期间保留;退出时先结束文件会话再关闭后端。
Windows示例使用同步文件 I/O:极值变化可能执行三次同步,目录打开可能扫描并生成最多30天的 XML。这些操作没有硬实时延迟上限,不能把宿主运行结果当作 MCU 网络调度、栈或介质寿命验收。嵌入式适配应按存储属主、调度预算和真实介质特性安排这些操作,并保持提交和快照语义。
本次Windows x64 GCC/O2测量:核心实例2216 B;宿主适配实例7336 B(包含核心,不应重复相加);定点读出结构184 B、极值读出结构1048 B。`.su`单函数帧中核心`Observe`为128 B、XML极值输出为1152 B、宿主日期存在性检查为1120 B。这些不是完整调用链最坏栈,也不代表ARMCC目标布局;测量程序、对象和`.su`保存在本目录`.build/history-final/`。
<a id="history-validation"></a>
## 7. 验证入口与范围
`-Suite History` 注册于[构建脚本](../../scripts/build.ps1),包括:
| 测试 | 主要覆盖 |
|---|---|
| [核心测试](../../test/iec60870_history_test.c) | 1024/30条覆盖、提交前后失败恢复、96节与午夜、缺测与品质、32日轮转、32点、时间范围与迟到记录拒绝 |
| [XML测试](../../test/iec60870_history_file_test.c) | 四类结构、实际条数、最新30完成日、第96节24:00、属性转义、UTF-8、输出失败与路径 |
| [宿主后端测试](../../test/iec104_example_history_test.c) | bank同步边界中断、重开、损坏副本、30日目录、不可变下载快照 |
核心与XML专项使用 C99、`-pedantic -Wall -Wextra -Werror`。XML测试可接收已有输出目录参数,生成四类样本用于独立解析器检查;`.build/history-xml/`的一轮样本已使用.NET XML解析器核对1024条SOE、30条遥控、96节定点以及极值。
据本次提供的联调行为,客户端能完成目录、筛选和文件字节传输,但不解析历史MSG/XML。现场验收必须额外核对下载字节、XML结构、时间和记录数量。物理掉电、真实采集时间精度、长期写入寿命、目标内存/栈与真实主站互操作仍需各自证据。
现有证据的详细执行命令、样本和验证范围由[历史专项记录](../test/IEC104测试文档.md#history-tests)汇总。本设计说明中的恢复矩阵来自当前代码契约和已有同步边界/磁盘损坏测试;没有把矩阵中每一种可能的介质撕裂都描述成已经实测。
<a id="history-failure-migration"></a>
## 8. 故障处置与迁移责任
| 情况 | 当前实现行为 | 应用或产品适配责任 |
|---|---|---|
| 提交返回失败 | 核心进入故障态;旧或完整新版本须经恢复确认 | 停止盲写,保留错误证据;不能把操作事件重新执行一遍来补历史 |
| 点表数量、地址或顺序变化 | 指纹不匹配,拒绝解释旧数据 | 保留原点表及介质,另行迁移或选择新命名空间;当前没有自动迁移工具 |
| 工程单位、比例或点号语义改变,但有序 IOA 未变 | 现有指纹不会识别这些业务含义变化 | 应用自行版本管理或切换存储;不能只改 XML 单位后把旧值当成新量纲 |
| 任一 bank 损坏或系统 I/O 错误 | 即使另一份有效也拒绝读取和提交;提交前检查失败不写介质 | 保存原文件诊断,明确修复或迁移策略;不通过覆盖坏副本自动恢复写入 |
| 两 bank 有效、同代次但长度或载荷不同 | 视为冲突,拒绝读取和提交,不任选一份 | 保留冲突证据,核查写入来源与介质 |
| 双 bank 坏、布局头坏、已有文件截断为零 | 明确拒绝打开,不自动格式化 | 保存原文件诊断,决定恢复/迁移;不把删除原文件作为普通启动兜底 |
| 时钟回退或缺测 | 拒绝回退观测,保留缺节及实际条数 | 修复时间源、调度和采集;不能以当前值回填过去 |
| XML sink 失败、快照空间不足 | 生成失败,丢弃候选前缀;持久记录不因此删除 | 排查磁盘与资源,再发起新的导出;不能发布部分文件 |
| 设备重启或协议重建 | 宿主重开扫描持久槽;协议重建保留历史后端 | 保持配置、存储及采集来源一致;重新建立可信时间基准后提供日目录 |
CRC、指纹、独占文件和双 bank 解决的是记录一致性及失败可判定性,不是访问控制、介质加密或全介质灾难备份。移植到实际存储时需要自行兑现 `commit` 持久化与原子替换契约,并实测同步延迟、写入寿命和突然失电后的恢复;当前模块没有替目标平台创建额外任务、掉电保存中断或硬件保电机制。
@@ -1,6 +1,6 @@
# IEC 60870-5-101/104 公共时间工具
`IEC60870_Time.c/h` 为 IEC 60870-5-101 和 IEC 60870-5-104 提供共用的公历计算、CP16/CP24/CP56Time2a 编解码、本地标准时间转换及纪元秒数工具。时间源模块集中在`IEC60870_Clock.c/h`:Clock.c包含公共校验和Windows读写,Clock.h包含业务接口及RTC预留声明。时间源限定为Windows系统时钟或RTC,由`IEC60870_CLOCK_USE_RTC`在编译时二选一;RTC具体芯片驱动暂不实现,也不规划其他操作系统适配。Type 103业务已由独立的[ClockSynchronization模块](../104/IEC104_ClockSynchronization_设计架构.md)接入,应用显式执行设时动作;公共Time/Clock仍不自行分派ASDU。原始解码保留源日历和标志,业务再调用转换接口取得本地标准时间日历。公共模块不维护连接状态、共享可变状态或动态内存,可独立于协议链路编译和链接;时间戳转日期可选择平台库或保留的纯整数算法。
`IEC60870_Time.c/h` 为 IEC 60870-5-101 和 IEC 60870-5-104 提供共用的公历计算、CP16/CP24/CP56Time2a 编解码、本地标准时间转换及纪元秒数工具。时间源模块集中在`IEC60870_Clock.c/h`:Clock.c包含公共校验和Windows读写,Clock.h包含业务接口及RTC预留声明。时间源限定为Windows系统时钟或RTC,由`IEC60870_CLOCK_USE_RTC`在编译时二选一;RTC具体芯片驱动暂不实现,也不规划其他操作系统适配。Type 103业务已由独立的[ClockSynchronization模块](../104/IEC104_ClockSynchronization_设计架构.md)接入,应用显式执行设时动作;公共Time/Clock仍不自行分派ASDU。CP56解码保留源年月日和时间、IV/SU及星期是否出现,星期按日期重算,GEN不导出;业务再调用转换接口取得本地标准时间日历。公共模块不维护连接状态、共享可变状态或动态内存,可独立于协议链路编译和链接;时间戳转日期可选择平台库或保留的纯整数算法。
## 101/104 的共用边界
@@ -8,7 +8,7 @@
两个协议的业务层接入时均可包含 `IEC60870_Time.h` 并调用同一组 `IEC60870_Time_*` 接口,不需要分别维护时间实现。当前模块覆盖日历工具及 CP16/CP24/CP56Time2a。CP16为2字节经过时间,范围0..65535毫秒;CP24为3字节短时标,保存分钟、分钟内毫秒和IV,不含SU、小时或日期。两者分别使用`To_CP16/From_CP16`和`To_CP24/From_CP24`,成功返回1,失败返回0且保留输出。CP24解析检查bit6保留位、分钟0..59及分钟内毫秒0..59999,不自动恢复完整日期。不同时间类型具有不同字段,不能把CP24交给CP56解码。
日历支持 1970..2099、将 CP56 两位年份解释为 2000..2099、非零星期一致性及保留位严格检查,属于本模块明确采用的范围和接入策略。通信双方须就世纪和时区约定保持一致,不能把这些实现约定理解为 101 或 104 独有的规则。
日历支持1970..2099,将CP56两位年份解释为2000..2099。CP56接收以合法日期为准,容忍非零星期与日期不一致及分钟bit6 RES1/GEN为1,小时RES2、月RES3和年RES4仍须为0;具体边界见[CP56字段策略](#cp56-reception-policy)。这些是本模块的范围和接入策略,通信双方仍须就世纪和时区约定保持一致。
## 本地标准时间与 SU 处理
@@ -30,7 +30,7 @@ IEC 60870-5-101:2003/AMD1:2015 第7.2.6.18条将SU规定为可选且不推荐使
| 业务发送示例 | 调用方提供已是本地标准时间的日历,示例显式设置SU=0,IV由零初始化保持为0 |
| 业务接收示例 | `From_CP56 → CP56_To_Local`,直接取得本地标准时间日历 |
`From_CP56`只保留源日历及SU;`CP56_To_Local`读取完整解析值,输出已经修正为本地标准时间的`IEC60870_WallTime_t`。**调用方不需要再加八小时或再减夏令时的一小时。** 使用独立输出存储时,原始输入不改写;若输入与输出重叠,成功写回会覆盖重叠的存储,调用方须按转换后的时间基准使用结果,再次生成时标时构造新的CP56值并置SU=0。ClockSynchronization使用`CP56_To_Seconds`取得UTC秒数,在64位毫秒域补偿受理后的滞留,再调用`Seconds_To_Local`;确认直接回显原请求,不重编码补偿后的日历。
`From_CP56`不转换源日历时区,保留IV/SU和星期出现标志,但会重算星期且不导出GEN;`CP56_To_Local`读取解析值,输出已经修正为本地标准时间的`IEC60870_WallTime_t`。**调用方不需要再加八小时或再减夏令时的一小时。** 使用独立输出存储时,原始输入不改写;若输入与输出重叠,成功写回会覆盖重叠的存储,调用方须按转换后的时间基准使用结果,再次生成时标时构造新的CP56值并置SU=0。ClockSynchronization的COT6设时路径使用`CP56_To_Seconds`取得UTC秒数,在64位毫秒域补偿受理后的滞留,再调用`Seconds_To_Local`;ACT_CON直接回显原请求,不重编码补偿后的日历。
转换接口的`source_standard_utc_offset_minutes`表示“源报文标准当地时间减UTC”的分钟数,向东为正、向西为负。双方约定本地标准时间时传`IEC60870_LOCAL_UTC_OFFSET_MINUTES`(480);源报文为UTC时传0,源标准时区为UTC-5时传-300。-1439..1439是本接口约定的参数范围;输出时区始终是本地标准时间。
@@ -60,22 +60,23 @@ SU本身不携带时区信息;源偏移须来自双方约定。这里的“本
|---|---|
| 日期合法性、闰年、星期、UTC 日期与纪元秒数互换 | `IEC60870_Time` |
| UTC纪元秒数直接转本地标准时间,统一处理时区及日期进位 | `IEC60870_Time_Seconds_To_Local` |
| CP56Time2a 七字节布局、日期和星期检查、IV/SU标志保留 | `IEC60870_Time` |
| CP56Time2a七字节布局、日期校验、星期归一化、RES1/GEN接收及IV/SU标志保留 | `IEC60870_Time` |
| CP56转本地标准时间,检查IV、处理SU和源时区,输出完整日历 | `IEC60870_Time_CP56_To_Local` |
| 统一读时、设时入口,校验日历、重算星期并检查时间质量标志 | `IEC60870_Clock` |
| Windows系统时钟读写,UTC与固定UTC+8日历互换 | `IEC60870_Clock.c`中的Windows分支 |
| 新生成时标使用本地标准时间并设置SU=0;请求回显保留原时标 | ASDU业务层,Type 103确认由ClockSynchronization按原文生成 |
| 新生成时标使用本地标准时间并设置SU=0;请求回显保留原时标 | ASDU业务层,Type103的COT6校时确认由ClockSynchronization按原文生成;COT5读时成功回复新时标 |
| 校时ASDU校验、期限、滞留补偿及确认 | `IEC104_ClockSynchronization`;设备权限、实际设时及事件时间戳仍由应用接入 |
| 实现`IEC60870_Clock_RTC_Read/Set`,处理RTC寄存器、BCD、时间基准、掉电标志及读写一致性 | 板级接入层和具体RTC驱动,暂不实现 |
| t1/t2/t3 及发送期限使用的单调计时 | 平台提供 `now_ms`,Link/Connection 使用 |
| 业务期限、周期扫描及示例测量平滑的经过时间 | `IEC104_Net_Now_Ms()`提供单调毫秒;由各业务或应用保存计时状态 |
使用已有时间值进行转换或编解码时,业务层包含`IEC60870_Time.h`,构建时加入`IEC60870_Time.c`。读取或设置实际时钟时,包含`IEC60870_Clock.h`,再加入`IEC60870_Clock.c`。默认Windows模式链接Kernel32(通常由Windows工具链默认链接);以后使用RTC时,编译Clock.c定义`IEC60870_CLOCK_USE_RTC=1`,加入实现RTC预留接口的板级驱动。仅调用时间转换工具时,无需构建Clock。
模块不依赖 Codec、Receiver、Link 或 Connection,也不会自动注册 ASDU 处理或设置系统时间。墙上时间用于业务时间戳;链路超时使用单调时间,校时不能改变链路期限。
模块不依赖 Codec、Receiver、Link 或 Connection,也不会自动注册 ASDU 处理或设置系统时间。墙上时间用于业务时间戳;链路及业务超时使用单调时间,校时不能改变这些期限。示例测量平滑同样使用单调时差,不因墙钟设时重置滤波或计算一次虚假的大时差;应用算法见[参数测量平滑](../104/IEC104_Parameter_设计架构.md#parameter-measurement-filter)。
## 当前接入状态与待补齐项
当前已实现日期转换、星期计算、CP56Time2a编解码、统一时间源接口、Windows系统时钟适配及Type 103业务模块。公共工具、协议处理及设备接入的边界如下:
当前已实现日期转换、星期计算、CP16/CP24/CP56Time2a编解码、统一时间源接口、Windows系统时钟适配及Type 103业务模块。公共工具、协议处理及设备接入的边界如下:
| 项目 | 当前状态与待补齐内容 |
|---|---|
@@ -84,7 +85,7 @@ SU本身不携带时区信息;源偏移须来自双方约定。这里的“本
| 时间有效性及失败处理 | `Clock_Read`分别返回操作状态和`is_invalid`,校验日期及0/1标志,失败保留输出;具体驱动负责识别未初始化、掉电或失去可信时间。下文示例传递质量到CP56的IV;实际业务仍须决定是否发送无效时间。IV=1也不能用全零日期占位 |
| ASDU业务收发与校时 | `IEC60870_InformationObjects.c`复用CP16/CP24/CP56编解码,`IEC60870_Asdu.c`维护容器与原文应答;ClockSynchronization处理Type 103校验、排队、补偿、显式执行及成功/失败确认。事件采集、校时权限及平台设时仍由应用action接入;示例默认模拟,显式system模式调用Clock_Set |
| 日期转换实现 | 保留Windows CRT和纯整数算法两种实现。RTC直接提供日历时无需时间戳展开;需要转换时间戳且没有Windows CRT时使用整数算法,不规划增加其他操作系统时间库 |
| 项目内的时间模块回归 | `iec60870_asdu_test.c`已覆盖CP56已知字节、IV/SU保留、非法日期和保留位,并分别使用两种时间实现编译运行;这不等于完整日期转换一致性测试。独立转换边界及平台读写失败、时间质量用例仍待补齐 |
| 项目内的时间模块回归 | `iec60870_asdu_test.c`覆盖CP56已知字节、星期0..7与GEN/IV/SU组合、按日期重算星期、RES2/3/4逐位拒绝及失败输出不变,两种时间实现均纳入构建矩阵;业务回归另查原文回显与动作拒绝边界,见[CP56接收测试](../test/IEC104测试文档.md#cp56-reception-regression)。这不等于完整日期转换一致性测试,平台读写失败及硬件时间质量用例仍待补齐 |
RTC已有年月日时分秒时,可按约定直接整理后编码;只有需要从时间戳取得日期时,才涉及平台库或整数算法的选择。RTC未提供亚秒值时,可约定毫秒填0,但这不表示时间源具有毫秒精度。已提供的Windows适配从UTC统一转换为固定UTC+8,避免依赖电脑设置的本地时区。
@@ -204,7 +205,7 @@ Windows显式使用64位版本,避免32位`time_t`限制原有的1970..2099年
`IEC60870_WallTime_t` 是公开的日历值类型,包含年月日、时分秒、毫秒和派生的星期,不包含时区字段。`Seconds_To_Local`和`CP56_To_Local`输出本地标准时间;`From_Seconds`输出UTC。CP56Time2a中的源日历值须结合SU及双方约定的时间基准解释,不能仅凭结构体类型猜测时区。
`IEC60870_CP56Time2a_t` 另存 `is_invalid`(IV)、`is_summer_time`(SU)及 `has_weekday`,三个标志都只能是0或1。编解码保留IV/SU,由业务决定是否使用该时间。结构体只用于内存传值,不能按 `sizeof` 复制为报文,也不能把七字节报文强转成结构体指针。
`IEC60870_CP56Time2a_t`另存`is_invalid`(IV)、`is_summer_time`(SU)及`has_weekday`,三个标志都只能是0或1。编解码保留IV/SU,由业务决定是否使用该时间。解码时`has_weekday`只表示报文星期非零,`time.weekday`始终按日期计算;结构没有GEN字段,不导出该位。结构体只用于内存传值,不能按`sizeof`复制为报文,也不能把七字节报文强转成结构体指针。
| 项目 | 约定 |
|---|---|
@@ -214,7 +215,7 @@ Windows显式使用64位版本,避免32位`time_t`限制原有的1970..2099年
| 时、分、秒、毫秒 | 0..23、0..59、0..59、0..999;不表示闰秒 |
| 内存中的星期 | 0=周日,1=周一,…,6=周六;输入的 `weekday` 不作为编码或秒数转换的依据 |
| 返回值 | 1=成功,0=参数/格式非法、结果越界、平台转换失败或将IV=1转为有效时间;失败不改输出 |
| 缓冲区 | 编解码检查非空及长度至少为7,仅处理前7字节;实际空间必须与所报长度一致 |
| 缓冲区 | CP16/CP24/CP56编解码分别检查长度至少为2/3/7,只处理对应字节;实际空间必须与所报长度一致 |
本地标准时间接口保留毫秒并重算星期。CP56日历输入须在2000..2099年,SU或源时区修正后得到1999年的本地标准时间可以成功;本地标准时间超过2099-12-31 23:59:59则失败。例如源本地标准时间的2099年最后一秒仍可完整输出,源UTC的2099-12-31 16:00则会因转换到本地标准时间2100年而失败。
@@ -222,23 +223,32 @@ Windows显式使用64位版本,避免32位`time_t`限制原有的1970..2099年
纪元秒数0是正常结果,不用来表示错误。基础`To_Seconds`和`CP56_To_Seconds`只输出完整秒数;`From_Seconds`和`Seconds_To_Local`同时接收秒数和毫秒余数。所有入口均检查毫秒范围,越界直接报错,不截断、不进位。
<a id="cp56-reception-policy"></a>
## CP56Time2a 字段策略
七字节布局采用[Beckhoff 的 CP56Time2a 字段说明](https://infosys.beckhoff.com/content/1033/tf6500_tc3_iec60870_5_10x/983926923.html):
七字节布局和本库接收策略按以下标准条款及字段表说明。
IEC 60870-5-101:2003第7.2.6.18条将星期定义为可选字段,并允许在监视方向用RES1表示GEN:0为原生时标,1为替代时标。该定义没有要求接收方必须忽略日期与非零星期的矛盾;本项目选择以日期为准重算星期,避免仅因冗余星期不一致拒绝有效日历。[标准字段定义](https://1library.net/article/i-nformation-elements-selections-iec-definition-coding-application.zpn89gwo)
IEC TS 60870-5-604:2016表5、表7的CP56检查列出RES1可为0或1,并要求RES2、RES3、RES4为0。本接收器接受分钟bit6的两种取值,既不将GEN=1当作IV=1,也不据此放宽其他保留位、日期或业务时效检查。[一致性测试字段表](https://www.scribd.com/document/1014126417/iec60870-5-604-ed2-0-en)
| 字节(从0开始) | 内容 |
|---|---|
| 0、1 | 分钟内毫秒,低字节在前,范围0..59999,拆成秒和毫秒余数 |
| 2 | bit7为IV,bit6保留,bit0..5为分钟 |
| 3 | bit7为SU,bit5..6保留,bit0..4为小时 |
| 2 | bit7为IV,bit6为RES1/GEN,接收0或1;bit0..5为分钟 |
| 3 | bit7为SU,bit5..6为RES2,须为0;bit0..4为小时 |
| 4 | bit5..7为星期,bit0..4为日 |
| 5 | bit4..7保留,bit0..3为月 |
| 6 | bit7保留,bit0..6为两位年份;数值100..127不接受 |
| 5 | bit4..7为RES3,须为0;bit0..3为月 |
| 6 | bit7为RES4,须为0;bit0..6为两位年份,数值100..127不接受 |
- **星期**:`has_weekday=0` 编码为报文星期0;为1时从日期计算1=周一至7=周日。解码允许星期0,此时仍计算内存中的 `time.weekday`;非零星期必须与日期一致,否则失败。这样不依赖调用方传入的过期星期,也不会默默接受相互矛盾的日期和星期。
- **星期**:`has_weekday=0`编码为报文星期0;为1时从日期计算1=周一至7=周日。解码接受报文星期0..7,`has_weekday`仅记录是否非零,`time.weekday`始终从合法日期计算。非零星期与日期不一致不使解码失败;无效日期仍失败,不能用星期反向修正日期。
- **IV**:编解码保留该标志。IV=1表示业务时间无效,不等于报文格式无法解析;调用方必须检查该标志后再决定是否记录或使用时间。即使IV=1,本模块也要求日期和时间字段合法,不接受全零日期等占位数据。
- **SU**:公共编解码支持0和1,复制标志而不调整日历值;本地标准时间转换接口在SU=1时扣除一小时,并处理源标准时区与本地标准时间的差值。编码或转换时SU大于1均失败。应用新生成时标使用SU=0,Type 103确认保留原SU;接收时将完整解析值交给转换接口,不丢弃SU后直接使用原时间。
- **保留位**:编码统一清零,解码严格拒绝非零值。分钟bit6按本模块采用的布局视为保留位,不接受将它另作扩展标志的报文。这是明确的接入约束,不能把此接口当作任意七字节数据的无损容器。
- **SU**:公共编解码支持0和1,复制标志而不调整日历值;本地标准时间转换接口在SU=1时扣除一小时,并处理源标准时区与本地标准时间的差值。编码或转换时SU大于1均失败。应用新生成时标使用SU=0,Type103的COT6校时确认保留原SU;接收时将完整解析值交给转换接口,不丢弃SU后直接使用原时间。
- **RES1/GEN**:分钟bit6接收0或1,不影响日期、IV/SU或时区换算。当前解析结构没有GEN字段,所以解码不导出GEN,日历编码统一生成GEN=0。
- **其他保留位**:小时RES2、月RES3和年RES4编码清零,解码仍拒绝非零值。本次CP56接收策略不扩大到CP24或其他信息元素。
`From_CP56 → To_CP56`是日历与标志的转换,不保证七字节无损往返:非零错误星期会被纠正,GEN=1会变为0。Type103的COT6校时确认、Type58..64和Type107的业务应答通过保存并回显请求原文保留这两项原始字节,不以解析结构重新编码;这与公共日历接口的输出策略不同。Type103的COT5读时使用全零请求占位,成功回复另行编码当前本地标准时间、SU=0及星期1–7,见[读时钟设计](../104/IEC104_ClockSynchronization_设计架构.md#clock-read)。
数值校验成功只说明日期真实存在、各字段符合上述约定。它不保证远端时钟准确,也不决定校时权限或业务接受策略。
@@ -246,6 +256,8 @@ Windows显式使用64位版本,避免32位`time_t`限制原有的1970..2099年
| 接口 | 功能 |
|---|---|
| `IEC60870_Time_To_CP16 / From_CP16` | 两字节经过时间编解码,使用完整0..65535毫秒范围,不含品质或日历 |
| `IEC60870_Time_To_CP24 / From_CP24` | 三字节短时标编解码,保存分钟、分钟内毫秒及IV;检查bit6保留位,不推断小时或日期 |
| `IEC60870_Time_Is_Valid` | 检查1970..2099年的年月日、时分秒及毫秒;忽略派生星期,不转换时间或判断时钟质量 |
| `IEC60870_Time_Get_Weekday` | 校验日期并返回星期 |
| `IEC60870_Time_To_Seconds` | UTC日历转完整纪元秒数,成功状态和数值分开返回 |
@@ -253,8 +265,8 @@ Windows显式使用64位版本,避免32位`time_t`限制原有的1970..2099年
| `IEC60870_Time_Seconds_To_Local` | UTC纪元秒数加毫秒余数直接转固定UTC+8的本地日历,自动处理日期和星期 |
| `IEC60870_Time_CP56_To_Local` | CP56解析值转本地标准时间日历,检查IV、处理SU及源时区,保留毫秒并重算星期 |
| `IEC60870_Time_CP56_To_Seconds` | CP56解析值转UTC秒数,检查IV、扣除SU的一小时和标准时区偏移 |
| `IEC60870_Time_To_CP56` | 日历与标志编码为七字节,校验输出容量 |
| `IEC60870_Time_From_CP56` | 从至少七字节的输入解析日历与标志,校验格式和日期 |
| `IEC60870_Time_To_CP56` | 日历与标志编码为七字节,按日期生成所需星期、GEN置0,校验输出容量 |
| `IEC60870_Time_From_CP56` | 从至少七字节的输入解析日历和IV/SU,接受RES1/GEN,重算星期且记录是否出现,严格检查日期及RES2/3/4 |
下面示例供后续业务层接入时使用,示例函数尚未作为生产接口实现。示例适用于**通信双方已约定CP56使用本地标准时间基准**的接入:发送使用本地标准时间日历、SU=0;接收支持SU=0和1,输出已修正的本地标准时间日历。输入日历由调用方提供,工具本身不读取系统时钟或设置RTC。
@@ -294,8 +306,27 @@ int Decode_Local_Timestamp(const uint8_t *in, size_t length,
例如收到本地标准时间基准的12:00、SU=0时,输出小时为12;SU=1时输出小时为11。收到00:30、SU=1时,输出前一天23:30,日期和星期同步调整。IV=1、字段非法或转换结果越界时,整个输出日历保持不变。业务完成权限和时间合理性检查后,可以将结果交给按本地标准时间运行的RTC或显示模块,无需再次加八小时。若对端使用其他时区,应将示例中固定的480替换为对端约定的源标准时区偏移。
<a id="time-input-selection-and-diagnostics"></a>
## 按输入时间域选择接口与排障
接入前先为数据源注明单位、时间基准和可信性。`IEC60870_WallTime_t`本身不携带时区,整数也不会说明自己是UTC秒数、UTC毫秒还是启动后经过时间;类型能编译通过不代表这三者可以互换。
| 已取得的数据 | 接入路径 | 易误判的现象与检查点 |
|---|---|---|
| UTC纪元秒数,另有毫秒余数 | 显示本地日历用Seconds_To_Local;需要UTC日历用From_Seconds | 相差8小时先查是否提前加了偏移;毫秒余数须为0..999,不把完整UTC毫秒窄化后当秒传入 |
| RTC提供完整的固定UTC+8日历 | 适配为Clock的本地日历,检查质量;生成CP56时另行设置IV/SU | 多加8小时说明重复转换;读时返回成功只证明取得数据,不证明掉电后日期可信,见统一时间源读写 |
| 接收到CP56字节 | From_CP56后保留完整解析值;按约定源偏移调用CP56_To_Local或CP56_To_Seconds | 解码成功但转换失败时检查IV、源偏移及换算后范围;不能跳过SU或将失败后保留的旧输出当本次成功值 |
| 接收到CP24字节 | From_CP24只取得分钟、分钟内毫秒及IV,完整日期另由应用的时间上下文确定 | 每小时会出现相同短时标;不能直接补“接收当天、当前小时”后声称得到真实发生时间 |
| Net单调毫秒或设备运行时长 | 用于期限、间隔;需要绝对时刻时由业务维护它与UTC的配对基准 | 将单调计数交给From_Seconds得到的是错误纪元日期;本工具不自动建立该映射,参考[突发时间输入](../104/IEC104_Spontaneous_设计架构.md#52-时间输入与换算) |
CP24的跨小时例子:接收时刻为可信的`2026-11-07 10:00:02`,短时标是分钟59、分钟内59000ms,即某个小时的59分59秒。**只有当应用另有明确契约:双方时间基准一致、事件不超前且传输滞留不超过5秒**,才可在该窗口内将它定位为同日09:59:59。直接拼当前小时会误写成10:59:59;断线积压、时钟跳变或缺少延迟界限时,这个推断条件不成立,应保留短时标及不确定性,不能凭本模块恢复日期。该例是应用判定条件的说明,库没有CP24补日期接口,也不把IV=0解释为日期已经确定。
排查转换失败时先检查返回值,再观察输出;本模块失败保持旧输出,继续使用上一次成功日历会掩盖输入错误。对“解码成功但不能用作有效时间”的情况,保留原IV及原字节供诊断,再按业务策略拒绝校时或记录无效事件,不修改标志来强行通过转换。CP56字段规则仍以[接收策略](#cp56-reception-policy)为准。
已有回归入口为[公共扩展测试](../../test/iec60870_asdu_extended_test.c)的`test_short_times`(CP16/CP24边界及失败输出保持)、[公共ASDU测试](../../test/iec60870_asdu_test.c)的`test_cp56_reception`,以及[业务集成测试](../../test/iec104_slave_example_test.c)的`test_clock_timezone_rollover`和`test_clock_time_errors`。这些用例不提供CP24日期重建或目标RTC质量的验收;新增数据源仍须验证其时间基准和读取一致性。
## 与原代码草案的差异
文件、类型、宏和API统一使用 `IEC60870` 公共前缀,供101和104共用。原草案中的单值秒数返回改为“状态返回 + 输出参数”,编解码增加缓冲区长度,并引入独立的CP56标志值类型。所有入口先检查指针、范围和格式再提交输出,修复非法日期、年份混淆、毫秒静默截断和纪元值与错误混用的问题。
原草案解码时丢弃报文星期和SU、遇IV直接失败;现在保留IV/SU及星期是否出现,检查非零星期的一致性,并通过独立转换接口落实SU=1的一小时修正。原始解码仍可返回IV=1以供业务记录,但转成有效时间戳时会拒绝。已有接收、链路和发送模块的接口及行为不变,时间工具由需要处理时间戳的业务按需接入。
原草案解码时丢弃报文星期和SU、遇IV直接失败;现在保留IV/SU及星期是否出现,以日期重算星期,并通过独立转换接口落实SU=1的一小时修正。CP56接收允许RES1/GEN为1但不导出GEN,其他保留位仍严格检查。原始解码仍可返回IV=1以供业务记录,但转成有效时间戳时会拒绝。已有接收、链路和发送模块的接口不变,时间工具由需要处理时间戳的业务按需接入。
@@ -0,0 +1,253 @@
<a id="user-log-design"></a>
# 附录 C 运行日志设计
`IEC60870_UserLog`保存最近1024条日志,`IEC60870_UserLogFile`生成`HISTORY/ULOG/ulog.xml`,应用通过Type210文件服务提供远程调阅。日志按持久提交序号排列,墙钟回拨不重排记录。核心、XML和宿主后端分别负责记录语义、文件编码及介质原子性;它们与附录B的SOE/遥控/定点/极值使用独立实例和存储。
规范依据为附录C的C.1、表C.1及C.2.2(PDF第60–61页):至少循环保存、上送最新1024条日志。掉电保存依据附录B.1 a)的历史数据要求及表B.1中的ULOG目录,附录C没有另行重述这一条。当前选择XML格式,不生成MSG;未满容量按实际条数输出,空库可以生成`num="0"`。
| 层次 | 实现与责任 |
|---|---|
| 公共记录核心 | [UserLog.c](../../common/IEC60870_UserLog.c)、[UserLog.h](../../common/IEC60870_UserLog.h):输入校验、循环序号、小端编码、CRC、恢复与查询 |
| 公共XML编码 | [UserLogFile.c](../../common/IEC60870_UserLogFile.c)、[UserLogFile.h](../../common/IEC60870_UserLogFile.h):固定字段、转义、时标转换、同步分片输出;依赖公共Time |
| Windows持久后端 | [iec104_example_user_log.c](../../examples/iec104_example_user_log.c)、[头文件](../../examples/iec104_example_user_log.h):独占文件、双bank提交、目录缓存和独立下载快照 |
| 示例应用 | [iec104_slave_example.c](../../examples/iec104_slave_example.c):识别实际事实、维护来源状态、转换发生时刻、处理存储失败及Type210路由 |
## 1. 类型与记录触发
| 类型 | 表C.1含义 | 值约束 | 当前示例来源 |
|---|---|---|---|
| 01 | 终端重启记录 | 行为,只有1 | 宿主进程实际启动;协议模拟重建另标`SIMULATED` |
| 02 | 通道连接建立与断开记录 | 状态,0或1 | TCP连接建立1、断开0;START/STOP不算连接变化 |
| 03 | 通信过程异常记录 | 状态,0或1 | 本Slave通信通道首次故障1,下次CONNECTED恢复0 |
| 04 | 装置内部各类插件、元件异常自检记录 | 状态,0或1 | 外部采集接入后调用Append |
| 05 | 装置内部软件进程异常记录 | 状态,0或1 | 外部进程监测接入后调用Append |
| 06 | 主电源通断及电压异常记录 | 状态,0或1 | 外部电源监测接入后调用Append |
| 07 | 备用电源通断、活化及电压异常记录 | 状态,0或1 | 外部电源监测接入后调用Append |
| 08 | 控制回路断线异常记录 | 状态,0或1 | 外部回路监测接入后调用Append |
| 09 | 开关位置异常记录 | 状态,0或1 | 外部开关监测接入后调用Append |
| 10 | 终端参数修改记录 | 行为,只有1 | 参数实际应用且前后值不同 |
| 11 | 软件版本升级记录 | 行为,只有1 | 升级阶段事实;RAM模式标`SIMULATED`,持久文件安装标`HOST_FILE` |
规范定义状态类“发生1、返回0”,行为类只记发生1;02的“连接建立1、断开0”是本实现的极性约定,规范未逐项明确其连接极性。03的恢复表示当前单服务通道重新连接,不代表所有通信介质或硬件已恢复。
状态检测必须按实际来源维护。例如两路电源同时异常属于两个来源,不能因类别同为06而丢掉第二条。核心每次合法Append都追加,不维护全局类别状态、不识别来源、不消除重复。应用应在同一来源发生/恢复边沿调用一次,把来源身份写入文本;多通道、多插件产品自行保存各来源状态。04..09的输入接口已具备,示例没有生成未接硬件的假事件。
<a id="user-log-core-api"></a>
## 2. 核心接口与调用顺序
调用方拥有`IEC60870_UserLog_t`、存储后端及回调context;全部操作包括Get和XML导出须串行。实例只保留最新序号、条数、最新提交时标、故障状态和164字节工作区,不在RAM保存1024条记录。公开结构用于静态分配,业务不能直接改内部字段。完整声明见[API第39节](../104/IEC104_API接口汇总.md#user-log-api)。
| 接口(省略`IEC60870_UserLog_`) | 输入、成功与失败 |
|---|---|
| Init(self, store) | 扫描1024槽并恢复;允许`store=&self->store`。无效参数返回INVALID且保留原实例;开始扫描后的错误返回ERROR并禁用实例,不修复或清空介质 |
| Append(self, type, utc_ms, value, text) | 提交一条事实;仅原子持久提交成功才推进序号/条数。非法输入INVALID;未初始化、故障、存储失败或序号耗尽ERROR;成功OK |
| Count(self) | 返回保留条数;空库、NULL、未初始化及故障都返回0,不能单独用作健康检查 |
| Get(self, oldest_index, record) | 0起始、按提交顺序从旧到新;越界EMPTY;仅OK填写独立记录副本。读取或格式错误ERROR并闭锁,输出保持不变 |
| Latest_Time(self, utc_ms) | 返回最新提交记录的时间,非最大墙钟;空库或实例不可用返回false且保持输出,不读取介质 |
枚举值为`OK=1`、`EMPTY=0`、`ERROR=-1`、`INVALID=-2`。Get的输出对象不得与实例或存储重叠;文本输入本次借用,Append先复制文本再复用工作区。Init浅拷贝回调表,不接管context资源。
存储接口`read(context,index,bytes,capacity,size)`只能用EMPTY表示未提交槽;I/O失败或坏记录必须ERROR,仅OK填写实际size。`commit(context,index,bytes,size)`须原子替换一槽并完成持久同步才返回true,不能把异步排队当成功。字节指针仅在回调期间有效,回调不得重入实例。
```mermaid
sequenceDiagram
participant A as 应用事实源
participant C as UserLog核心
participant S as 持久后端
participant X as XML与文件服务
A->>C: Init(store)
C->>S: 扫描全部槽并校验连续性
A->>C: 来源边沿或已完成行为 → Append
C->>S: 原子持久commit一个槽
S-->>C: 成功后才推进序号和条数
A->>X: 主站召唤目录
X->>C: Count及Get,串行导出
X->>X: 冻结目录文件版本
A->>X: 主站读文件
X->>X: 复制独立快照并按偏移读取
```
<a id="user-log-state"></a>
### 2.1 核心状态与应用失败锁存
核心只有`initialized=true && faulted=false`时可正常读写。Init不是清库:它从介质重建控制状态;开始扫描后的失败可能留下部分扫描计数,这些值不可供业务使用。下表中的Append/Get输入检查以非空有效对象为前提,字段非法行特指核心原先可用时。
| 操作与条件 | 返回及状态转换 | 内存、介质和输出 |
|---|---|---|
| Init参数不完整 | INVALID,原状态不变 | 不清零旧实例,不访问介质 |
| Init扫描完整成功 | OK,initialized=true、faulted=false | 恢复条数、序号和最新提交时标;不写盘 |
| Init读取、格式或连续性校验失败 | ERROR,initialized=false、faulted=true | 实例不可用,不能把部分扫描结果当历史 |
| Append字段非法 | INVALID,仍可用 | 不调用commit,不推进序号,不置faulted |
| Append全局序号已为UINT64_MAX | ERROR,仍可用 | 拒绝新增,不置faulted;已存记录仍可Get及导出 |
| Append的commit返回false | ERROR,faulted=true | 内存序号/条数不推进;介质可能已是新版,恢复前禁止再次追加 |
| Append提交成功 | OK,保持可用 | 才推进序号/条数及最新提交时标 |
| Get下标超出当前条数 | EMPTY,状态不变 | 输出不变,不读取该槽 |
| Get保留范围内缺槽、读失败或记录不符 | ERROR,faulted=true | 输出不变,不能以EMPTY掩盖丢失记录 |
| 已故障或未初始化时Append/Get | ERROR,状态不变 | 不访问介质;Get输出不变 |
因此不能把所有ERROR都解释成介质已损坏,也不能把Count返回0解释成存储已清空。核心序号耗尽与后端单槽代次耗尽还不同:前者在调用commit之前拒绝;后者由后端返回false,核心按不确定提交路径闭锁。
在应用追加入口,`user_log_failed`的失败策略比核心faulted更严格:追加结果只要不是OK,就锁存应用失败,包含INVALID和序号耗尽;文本格式化失败、发生时刻不能换算等也会进入同一应用路径。即使核心仍可查询,示例也不会继续正常业务。该标志独立于核心faulted,不是其同步镜像,文件导出另按[失败分类](#user-log-failure)处理。重新Init核心不会自动清除这个应用标志;示例完成资源收尾后退出,由下次启动恢复,不能只改标志继续运行。
## 3. 时间、输入与恢复
`utc_ms`采用UTC纪元毫秒,支持`946656000000..4102415999999`,对应固定UTC+8的2000-01-01至2099-12-31。核心不读取时钟,不接受范围外占位值;XML通过公共Time转换为本地时标。文本为非空、最多128字节的可打印ASCII(0x20..0x7E);控制字符、非ASCII和超长内容直接拒绝,不截断。01/10/11仅接受value=1,02..09接受0/1。
序号从1开始,每次提交加1,槽号为`(sequence-1)%1024`。达到容量后覆盖最旧记录,`UINT64_MAX`耗尽后拒绝追加,不回绕复用;现有记录仍可读取。墙钟允许回拨,连续两条可能时间倒序,导出和Latest_Time仍按序号理解。
恢复先逐槽校验长度、版本、CRC、保留位、文本、类型/值、时间和槽号。槽映射排除重复序号后,要求条数等于`min(max_sequence,1024)`且最小序号为`max_sequence-count+1`,从而拒绝保留区缺口和旧尾混入。提交false会锁存faulted,因为新版本可能已可靠写入;必须重新Init或关闭重开恢复事实,不能盲目重试同一事实。核心不提供跨业务动作与日志的共同事务或恰一次重放账本。
<a id="user-log-format"></a>
## 4. 内部记录与XML格式
内部编码与传输XML是两种格式。内部每条为`36+文本字节数`,范围37..164字节;整数显式小端,不持久化C结构体或指针。
| 偏移 | 长度 | 字段 |
|---|---|---|
| 0 | 4 | ASCII魔数`ULG1` |
| 4 | 1 | 格式版本1 |
| 5 | 1 | 保留0 |
| 6 | 2 | 文本长度1..128 |
| 8 | 8 | 单调提交序号 |
| 16 | 8 | UTC毫秒 |
| 24 | 1 | 类别1..11 |
| 25 | 1 | 信息值0/1,另受行为类约束 |
| 26 | 6 | 保留0 |
| 32 | 文本长度 | ASCII文本,不含NUL |
| 32+文本长度 | 4 | 前面全部实际字节的CRC32 |
CRC32采用反射多项式`0xEDB88320`,初始值全1、最终取反。CRC不代替语义检查,也不用于鉴权。没有自动版本迁移;改变布局或业务文本约定时,由产品决定兼容解析、显式迁移或另用存储空间,不能以格式不符为由静默清库。
对外固定路径大小写为`HISTORY/ULOG/ulog.xml`,不映射为内部`ulog.store`。XML选择C.2.2正式模板中的`txt`;同节随后示例写成`text`,本实现采用模板、不同时输出两个属性。`fileType="Ulog"`、`fileVer="1.00"`和`devID`也按C.2.2,不能照搬附录B的`devName`。
```xml
<?xml version="1.0" encoding="UTF-8"?>
<DataFile>
<Header fileType="Ulog" fileVer="1.00" devID="IEC104-EXAMPLE"/>
<DataRec num="1">
<DI logType="01" tm="261112_080000_000" txt="HOST_PROCESS_START" val="1"/>
</DataRec>
</DataFile>
```
`logType`固定两位,`tm`为`YYMMDD_HHMMSS_MS`且毫秒三位,`num`为实际条数。终端ID限定非空可打印ASCII、最多24字符;这是当前实现的输入约束,不在XML中填充至固定宽度。文本和ID中的`& < > " '`分别转义;文件用CRLF、不含末尾NUL。内部序号不扩展成未定义的XML属性。
`IEC60870_UserLogFile_Write`同步分片输出,sink必须完整接收本片才返回true。输入、读取、sink或长度检查失败立即停止;可选size仅成功时更新。失败可能已有前缀,调用方须丢弃整个候选。成功只证明字节被sink接收,文件冻结与原子发布仍由后端负责,见[API第40节](../104/IEC104_API接口汇总.md#user-log-file-api)。
<a id="user-log-storage"></a>
## 5. Windows存储与文件快照
后端首次使用的`ExampleUserLog`须全零初始化;Open要求已存在的父目录和合法ID,拒绝重复打开,支持Close后用实例内原字符串重开。`ulog.store`以共享模式0独占打开,与同目录`history.store`独立。仅本次新建的零长度文件可以初始化;已有空文件、坏头、过大文件和恢复失败均拒绝,不自动格式化。
文件头32字节:0..11为`IEC104-ULOG1`及NUL,12..15为0,16处保存1024槽数,20处保存164载荷上限,24处保存196 bank跨度,28处保存前28字节CRC。之后每槽两个bank,位置为`32+(index*2+bank)*196`;最大布局`32+1024*2*196=401440`字节。文件可稀疏增长,不要求启动时预填全部空间。
每个bank有32字节头和最多164字节核心记录:魔数`USL1`位于0,实际载荷长度位于4,64位代次位于8,载荷CRC位于16,头前20字节CRC位于20,提交标记位于24,28..31保留0。标记`0x54494D43`表示已提交。记录CRC、bank载荷CRC和头CRC分别校验不同边界。
bank预留196字节,候选写入只覆盖32字节头和本次实际载荷;短记录替换长记录后,固定bank范围内可能仍有旧尾部。读取最多196字节,要求实际读到至少`32+载荷长度`,仅以头中实际长度校验载荷CRC并向核心交付,不要求整bank填满或尾部清零。核心再要求`实际记录长度=36+文本长度`并校验内部CRC,旧尾部不会进入新文本或文件。
bank代次属于一个逻辑槽,只在该槽两份副本之间比较;核心sequence则是全环每次追加的全局序号。例如正常依次写入时,序号1在槽0对应首个bank代次1,序号1025再次写槽0时对应代次2。不能跨槽按bank代次排序日志,也不能用其代替核心连续性检查。提交标记位于头CRC覆盖范围之外,允许三个同步阶段独立清除和发布;实际长度、代次及载荷CRC仍受头CRC保护。
提交先重读并检查两份bank:任一份损坏或系统I/O错误、两份有效但同代次长度或载荷不同,都在任何写入前失败,不改写介质。检查通过后,选择当前最新有效bank之外的有效旧副本或未提交副本,代次加1且不允许回绕;不能覆盖坏副本来继续提交。文件格式保持不变。每次写检查实际字节数,执行三个持久同步阶段:
| 阶段 | 写入和同步 | 在测试注入点报告失败后的重开结果 |
|---|---|---|
| 1 | 将目标标记清零,FlushFileBuffers | 保留旧提交;目标按未提交候选忽略 |
| 2 | 写新头、载荷和CRC,标记仍零,再Flush | 保留旧提交;完整候选尚未发布 |
| 3 | 写提交标记,再Flush | 新版已经可能可靠存在,重新扫描确认 |
读取两bank时,任一系统I/O错误或任一bank损坏都返回ERROR,即使损坏的是较旧副本、另一份有效且代次更新也不忽略。实际读到0字节,或至少读到28字节且标记为零,归为未提交;非零非法标记、无法确认标记的短读,以及带有效提交标记的长度、魔数、CRC、保留位或代次错误均为损坏。两份均未提交才EMPTY;一份有效且另一份未提交时选有效副本;两份有效则选较大代次,相同代次仅在长度及载荷相同时选bank0,否则冲突报错。标记为零的候选可以忽略,但可检测的已提交损坏不能通过退选另一份掩盖。核心随后仍须检查全环连续性。
这不构成所有回退都可检测的保证。整段bank消失导致EOF,或原提交标记被清零,可能与未提交无法区分;全环序列约束只能核对仍可见记录要求的范围,没有独立提交见证时不能保证发现最新尾部缩短。读取和提交采用上述同一判据,既不把可检测损坏降为EMPTY,也不声称能恢复已消失的提交证据。
主站目录请求匹配`HISTORY/ULOG`,应用不靠目录ID选择类型。Directory_Open完整生成临时XML后才发布一项名称、大小和文件时间;文件时间取最新提交的时间,空库用本地2000-01-01且不伪造日志。Directory_Close只结束枚举,保留该版本缓存。下一次通过入口检查的ULOG Directory_Open才开始替换缓存;召唤其他数据源的目录不会触发该后端打开,也不使旧ULOG缓存失效。协议层按目录项时间执行时间范围筛选。
Read_Open只接受完整固定路径,有目录缓存时复制该缓存,否则生成当前版本。下载拥有独立临时文件,因此新日志、目录刷新或偏移重试不会改变当前文件大小和内容。读取不得越界;EOF只接受长度0。Read_Close释放下载;最终Close先清下载、目录缓存再关持久文件,禁用核心但不删除`ulog.store`。临时文件采用删除随关闭,不承诺跨进程保留目录快照。
<a id="user-log-host-api"></a>
### 5.1 宿主接口与资源所有权
[宿主头文件](../../examples/iec104_example_user_log.h)公开9个接口,下表省略`Example_User_Log_`前缀。调用方提供首次全零的对象并串行使用;成功Open后`core.store.context`指回self,直到Close及所有使用结束前,整个对象地址必须稳定,不能按值复制或移动。parent和device_id在成功打开后存为对象内副本,线上名称按显式length比较、不要求NUL,也不直接拼接成宿主路径。
| 接口 | 成功结果与借用 | 拒绝、失败和关闭边界 |
|---|---|---|
| Open(self,parent,device_id) | 打开独占持久文件、安装核心回调并恢复;true才可追加。父目录须已存在,ID为1..24字节可打印ASCII | 活对象重复打开不改变原状态;失败释放本次取得的句柄,可再Close。已有坏文件不删除,新建后初始化失败的文件也不自动删除 |
| Close(self) | 依次释放下载、目录缓存、持久锁,置opened=false并禁用核心 | 可重复调用,NULL无操作;须先让协议交完旧资源回调,不删除持久记录 |
| Directory_Open(self,name,length) | 只接受HISTORY/ULOG,完整生成后发布单项元数据和缓存,置directory_active | 未打开、核心故障、已有活动枚举或名称不符拒绝。通过入口检查后先丢弃旧缓存,再生成候选;生成失败不恢复旧缓存,但不影响独立活动下载 |
| Directory_Count(self) | 活动枚举返回1,即使日志条数为0 | 未活动或NULL返回0;不能据此判断核心健康或缓存是否存在 |
| Directory_Get(self,index,entry) | 活动枚举且index=0时按值复制名称、大小及时间 | false保持entry不变;输出副本不借用临时栈 |
| Directory_Close(self) | 只置directory_active=false | 可重复调用;缓存和entry继续存在,供随后下载 |
| Read_Open(self,name,length,size) | 固定完整路径;命中目录缓存则复制旧版,否则导出当前记录;成功发布独立read_file并写size | 最多一个活动下载;核心故障、参数/名称无效或创建/复制/导出失败均false。失败size不变,只清本次候选,已有目录缓存不受影响 |
| Read(self,offset,buffer,length) | 从冻结文件准确读取指定范围,同一偏移可重复;合法范围内length=0允许NULL buffer | 无下载、越界、短读或I/O错误false;底层读失败可能已写入buffer前缀,调用方不能使用该次数据 |
| Read_Close(self) | 仅关闭下载临时句柄,将read_file置空、read_size归零 | 可重复调用,NULL无操作;不关闭目录缓存或持久文件 |
三份句柄由宿主对象分别拥有,没有共享关闭或引用转移:
| 资源 | 寿命及失效条件 |
|---|---|
| storage | 成功Open至整体Close,负责独占ulog.store;不因目录枚举结束、下载结束或新日志产生而更换 |
| directory_file与entry | 成功目录生成后保留;Directory_Close仅结束枚举,下一次通过入口检查的Directory_Open即废弃旧版,或由整体Close释放 |
| read_file与read_size | Read_Open成功至Read_Close/整体Close;与目录缓存是两份文件,目录刷新不会改变下载内容 |
opened只表示宿主打开已完成,不证明核心之后没有faulted。故障核心拒绝新Directory_Open/Read_Open,但已有独立快照的Read不再访问核心记录,可按协议完成或取消后关闭。最终释放storage之前,应用仍须完成文件服务的原身份收尾,不能靠Close跳过协议资源责任。
<a id="user-log-integration"></a>
## 6. 示例接线、发生时间与失败处理
主示例通过`--user-log existing-directory`独立启用并自动开启Type210,可与`--history`同时使用同一父目录。未开启时原ULOG演示文本仍属于文件服务演示;开启后ULOG路径由实际XML接管,旧`ulog.msg`请求不能回落为演示内容。操作步骤见[运行日志示例](../examples/IEC104子站示例.md#example-user-log)。
启动先读有效宿主墙钟,建立UTC毫秒和Net单调毫秒基准;成功校时后更新基准。此基准独立于system模式的周期墙钟刷新,避免已经排队的连接通知落到新基准之前。连接/启停事实发生时的单调时间保存于`event.transport.data.connection.occurred_ms`,应用按“基准UTC + 发生时刻 - 基准单调值”计算日志时间,不使用延迟出队时间。早于当前基准或计算越界会报告日志错误,不把无效结果夹到边界。校时回拨后的新记录仍合法,提交顺序保持不变。
01用`HOST_PROCESS_START`表示本宿主进程启动;QRP1等协议模拟重建保留同一日志实例,追加`SIMULATED PROTOCOL_RESTART`。02/03状态由本Slave通道分别维护,重复故障快照不重复追加,普通无故障断开只记02。10只记已应用的实际变化,包含对象、区号及old/new;预置、TEST、同值和确认重试不追加,非当前区的已保存参数用`REMOTE_STORED`区分。11按实际升级阶段记录:RAM路径带`SIMULATED`,持久文件路径带`HOST_FILE`,后者在文件安装、应用就绪及健康确认后才发布成功。恢复、试运行及确认规则见[安装设计](IEC60870_FirmwareUpdate_设计架构.md),均不声称已刷写Flash或重启硬件。
启动从保留记录中倒序查找最新03,恢复本服务通道的异常状态,使重连仍能形成恢复记录;没有保留03时不补造恢复。连接标志不跨进程恢复,也不补造断电期间未知的断开时刻。若产品要求异常状态在相关记录被循环覆盖后仍可恢复,应另行持久化每个来源的状态,不能把有限长度日志当作永久状态库。
应用记录入口的失败锁存`user_log_failed`,不能把已应用参数或已完成升级阶段改判拒绝、回滚或重复执行。当前生命周期通知继续分派,文件/升级资源按既有顺序收尾,主循环随后以失败结束。恢复时重新打开介质确认已持久事实,产品如需跨业务动作与日志的原子一致性,须另设计共同事务。
<a id="user-log-failure"></a>
### 6.1 失败分类与恢复责任
持久记录失败、导出候选失败和业务动作失败是三个不同边界;处理前先确认哪一层已完成事实。宿主的Close/Open负责重新取得介质事实,不负责重做已经执行的业务动作。
FileService的目录/读取打开路径只把后端false转换成文件请求拒绝,不主动调用`Example_User_Log_Result`。因此XML内部Get读坏记录虽会置核心faulted,却不会仅凭本次文件拒绝立即置`app.user_log_failed`;后续应用追加遇到该故障才走追加失败锁存。单纯临时文件创建、复制或sink写入失败则连核心faulted也不设置,不能将所有导出失败统一解释成服务立刻停机。
| 失败点 | 已发生的结果 | 清理与恢复 |
|---|---|---|
| 核心commit返回false | 核心faulted;内存序号未前进,但介质可能已提交 | 停止追加,完成活动会话清理后Close/Open扫描。不能盲重试相同日志,不能因返回false便认定新版不存在或清库 |
| Init/Get读取损坏或连续性失败 | Init使实例不可用;Get保留输出并置faulted;导出中的Get失败也终止整个候选 | 保留错误介质供定位,修复原因后再恢复;无有效数据时显式失败,不降级空库。宿主Open失败自行关闭句柄 |
| XML sink失败或临时文件短写 | 编码false且size保持原值;候选可能仅有前缀,单纯sink失败不置核心faulted | 关闭并丢弃候选,不发布半文件。输出条件修复后可重新生成完整快照,无须因此重放日志;若来自Directory_Open,旧目录缓存已被废弃 |
| Read_Open复制目录缓存失败 | 不发布下载,size不变,目录缓存保留;核心未因此故障 | 关闭本次候选,处理临时文件I/O原因后可再次Read_Open,仍复制同一缓存。不能用部分复制文件继续传输 |
| 参数/升级已完成后日志追加失败 | 业务事实不能撤回;可能同时核心faulted,也可能只是输入INVALID或序号耗尽 | 应用锁存失败、继续必需生命周期和文件/升级清理后退出;不能改判原动作未执行、重复动作或强行清标志继续 |
上表允许的“重新生成/复制快照”只涉及读取产物,不是自动重试Append。日志核心没有跨业务动作的幂等键,重新打开成功也不能仅靠返回码判定是否需要补记同一行为;如产品需要自动补记与恰一次审计,须另设计可恢复的共同事务和来源身份。
## 7. 内存与移植边界
核心和编码器无堆、无RTOS、无文件系统依赖。核心只有164字节wire工作区及常数大小元数据;宿主另外有两个196字节bank工作区,快照复制使用256字节栈缓冲,完整XML保存在临时文件中。实际对象及调用栈大小取决于目标ABI,不能把1024条介质容量当作RAM分配。
当前GCC x64/O2实测:核心实例216字节、记录值副本152字节、含核心的宿主对象952字节、目录项84字节。`-fstack-usage`给出的单函数静态帧为Init/Append/Get各224字节、XML Write 320字节、宿主Open 720字节、Directory_Open 192字节、Read_Open 96字节、Store_Commit 176字节。这些是单函数帧,不是完整最坏调用链,也不是ARMCC目标测量;产品仍须按实际编译器、线程栈和回调链核算。
`occurred_ms`只增加连接事件载荷8字节,没有给每类通知重复加字段。当前x64 ABI下`IEC104_TcpEvent_t`仍为296字节,默认事件字节环因4个启停预留和1个断开预留共增加40字节;其他容量或ABI须重新计算,库与调用方须一起重新编译。
板端移植替换read/commit后端,落实掉电原子替换、同步屏障、短写检查、磨损管理及资源预算。Windows的Flush边界测试不能替代实际存储器、驱动、文件系统和供电条件下的断电验收。格式校验也不能证明被整体删除的历史曾存在:例如全部记录被变成空槽,或最新尾部被完全移除后仍形成合法前缀,无外部提交账本无法区分。CRC不防恶意修改,当前没有日志签名或独立审计存储。
<a id="user-log-validation"></a>
## 8. 验证入口与已覆盖边界
从本目录执行`./scripts/build.ps1 -Test -Suite UserLog`。脚本包含公共核心/XML、Windows后端及真实TCP调阅;结果与命令统一见[运行日志测试](../test/IEC104测试文档.md#user-log-tests)。
| 已运行的验证 | 覆盖与结果 |
|---|---|
| [公共核心单测](../../test/iec60870_user_log_test.c) | 严格C99、pedantic、Werror编译;6组通过:1025条循环/重启、全部类型和值、128字节ASCII、时标边界/回拨、提交前后失败、损坏/缺口及序号耗尽 |
| [XML单测](../../test/iec60870_user_log_file_test.c) | 同等严格编译;4组通过:固定字段、实际条数、转义、时间两端、循环顺序、每个sink片段失败及存储读取失败 |
| [宿主后端测试](../../test/iec104_example_user_log_test.c) | 严格C99、pedantic、Werror编译并通过:三次同步后的中断、实文件CRC损坏/截断、单/双bank、独占/重开、缓存与独立下载、历史存储隔离 |
应用集成及真实TCP结果以测试文档最新实跑记录为准;这里不以已写测试或接口编译代替通过证据。04..09硬件来源和真实掉电验收尚不由上述主机测试证明。