Files
STM32F4-Base/App/protocol/iec60870/104/business/IEC104_SystemCommand.h
T
wandering1 2e9272cc8a feat(iec104): 在模拟器跑通共享协议核心与标准DTU点表
引入成熟 IEC 60870-5-104 子站的只读子集(App/protocol/iec60870,28 个源文件
按原字节复制,UPSTREAM.sha256 记录来源,兼容补丁保留全部断言与容量),在其上
装配单属主共享核心(Start/Poll/Stop/Get_Status),并把标准 DTU 演示点表全量
接入为唯一真源。

- iec104_core:threadless 推进,poll 零等待,通知/交互/COV 扫描全部有界;
  生命周期区分失败启动待重试、重复启动拒绝、断线保固化 RAM。
- iec104_dtu_table / iec104_source:标准 DTU 全点表注册,无数据源的点读 0,
  遥控只做模拟状态可读回,不触碰实际出口。
- iec104_sim:仅窗口与独立服务模式起真实 TCP,无头黄金模式保持确定性假统计。
- test/host/iec104_dtu:独立真实 TCP 11 项、传输层 10 项、生命周期与借用负例。

验证:lvgl_sim 真实 TCP 11/11、传输 10/10,UI 像素回归未回退;AC5 单 TU
编译 0 错误 0 诊断。板端尚未切换:完整库闭包 RAM 超 92% 门禁净增预算 25730B,
结论为停止转实施,记录在 IEC104_MCU最小可行性验证.md。旧实现与 board 服务
保持原样,未提交 MDK 工程改动,未烧板。
2026-11-17 20:48:00 +08:00

255 lines
19 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
* IEC104系统命令:104/107测试回显、70初始化结束和105进程/事件缓冲复位。
* Handle_Event/Process不调用应用;Execute_Next仅同步调用一次本次传入的action。
* 全部入口与Slave在同一事件循环串行调用;回调不得推进Slave或重入修改入口。
* QRP=1及已启用的专用QRP在首次STOP/断开前肯定确认按时被协议ACK即确定授权;会话清理不撤销。
* Take_Reset一次性交给应用;显式Cancel仍可主动放弃,且不撤回发送层已接手的确认。
* 广播105按受理时站点快照逐站决定,以实际CA回复;QRP=2逐站清未提交CP56事件。
* 应用先清该站自己的缓冲,库随后清该CA的NORMAL。广播不授权整机复位。
* 专用QRP128..255由应用显式启用,和QRP1同样在ACK后经Take_Reset交出动作许可;库不解释其业务。
* TEST=1的105通过库配置/报文校验后肯定回显并保留T;不调用应用、不清事件、不创建动作授权。
* 专用QRP的肯定测试回复不代表应用批准真实动作;T=0仍须应用决定及有效ACK。
* Create必须早于消费Slave通知;每轮读空并分派通知后执行Process、Execute_Next和Take_Reset。
* 配置统一由IEC104_Startup_Config_Default初始化,默认每次实际START重报已登记的COI。
* 模块不执行实际设备复位,不持久化COI,不保证Type70是START后的第一条I帧。
* 完整状态机、支持范围及示例接入见docs/104/IEC104_SystemCommand_设计架构.md。
*/
#ifndef IEC104_SYSTEM_COMMAND_H
#define IEC104_SYSTEM_COMMAND_H
#include "IEC104_Slave.h"
#ifdef __cplusplus
extern "C" {
#endif
typedef struct IEC104_SystemCommand IEC104_SystemCommand_t;
/* 功能位按位组合;TEST_COMMAND同时启用104/107,独立于请求COT中的TEST位。
* 105的三个RESET功能都关闭才整体IGNORED,单独关闭的QRP回否定ACT_CON。 */
#define IEC104_SYSTEM_COMMAND_FEATURE_TEST_COMMAND 0x01U /* Type104/107,原文测试回显。 */
#define IEC104_SYSTEM_COMMAND_FEATURE_INIT_END 0x02U /* Type70,按站点快照上送COI。 */
#define IEC104_SYSTEM_COMMAND_FEATURE_RESET_PROCESS 0x04U /* Type105/QRP1,ACK后交出授权。 */
#define IEC104_SYSTEM_COMMAND_FEATURE_RESET_EVENTS 0x08U /* Type105/QRP2,本CA事件清除。 */
#define IEC104_SYSTEM_COMMAND_FEATURE_RESET_PRIVATE 0x10U /* Type105/QRP128..255,显式启用后ACK交授权。 */
/* 两种策略都须先登记COI。ONCE已完成后不会因重连自动重发;未完成轮次仍可在下次激活重试。
* EVERY_START以实际ACTIVATED通知为边界,覆盖同TCP的STOP/START和重连后的START;
* 已激活时重复收到START不会形成新激活轮次,也不会仅凭这条重复请求再发Type70。 */
typedef enum {
IEC104_SYSTEM_COMMAND_INIT_ONCE = 0, /* 每次登记完整交接一轮;未完成的轮次允许重试。 */
IEC104_SYSTEM_COMMAND_INIT_EVERY_START = 1 /* 每次实际ACTIVATED后再按最近COI发一轮。 */
} IEC104_SystemCommandInitPolicy_t;
typedef struct {
uint8_t features; /* 默认0x0F,仅标准功能;专用功能须显式加0x10,其他未知位使Create失败。 */
IEC104_SystemCommandInitPolicy_t init_policy; /* 统一配置为EVERY_START;专项可显式采用ONCE。 */
uint32_t decision_timeout_ms; /* 105受理至回调开始前,默认15000ms;0禁用。 */
/* 默认30000ms;从返回ACCEPT的那次回调开始前base_ms算到首次有效ACK,包含回调耗时。
* 正常推进时,确认尚未提交而到期会取消许可并原位转否定ACT_CON,WAIT继续保留回复;
* 确认已被发送层接手后到期只取消许可,不再发送相反确认。STOP/断线/Cancel仍按清理处理。
* 0仅禁用业务期限;尚未编号的确认不受链路t1覆盖,可能一直等待容量或观察槽。 */
uint32_t reset_ack_timeout_ms;
} IEC104_SystemCommandConfig_t;
/* 纯值请求;回调指针只在本次调用有效。Take_Reset交出后station_id不保证节点仍存活。 */
typedef struct {
IEC104_SlaveEventIdentity_t identity; /* 原Slave实例和TCP代次;可用于按原身份关闭连接。 */
uint64_t receive_serial, station_id; /* 原接收流水号(诊断)、原站注册编号(查context)。 */
uint16_t common_address; /* 实际目标CA,广播也不返回65535;QRP2不区分同CA历次注册。 */
uint8_t originator_address, qualifier; /* 原OA、QRP(1/2或已启用的128..255);TEST请求不会进入此回调。 */
uint64_t accepted_ms, base_ms; /* Net单调毫秒:受理采样、本次回调开始前采样。 */
} IEC104_SystemCommandResetRequest_t;
typedef enum {
IEC104_SYSTEM_COMMAND_DECISION_REJECT = 0, /* 必须没有副作用。 */
IEC104_SYSTEM_COMMAND_DECISION_ACCEPT = 1 /* QRP1/专用QRP仅许可;QRP2已清本CA应用缓冲。 */
} IEC104_SystemCommandDecision_t;
/* 同步短时;QRP1/专用QRP不得在回调中执行动作,仅判定是否许可。允许Get_Status和站点只读查询。
* 禁止推进/修改Slave。专用QRP的具体动作由应用约定,库不清NORMAL、不将其解释为整机复位。
* 只按station_id取原站context;不得按CA重查替换节点。每请求的每个目标至多调用一次。
* 广播某站拒绝不阻止后站;应用只授权本CA,不可将一个站的ACCEPT解释为整机许可。
* QRP2返回ACCEPT后库清除失败会返回FAULT,应用动作不可重做或假定已回滚。 */
typedef IEC104_SystemCommandDecision_t (*IEC104_SystemCommandResetAction_t)(void *context,
const IEC104_SystemCommandResetRequest_t *request);
typedef enum {
IEC104_SYSTEM_COMMAND_EVENT_ERROR = -1, /* 参数、重入、归属或内部准备失败;不能继续44兜底。 */
IEC104_SYSTEM_COMMAND_EVENT_IGNORED = 0, /* 非目标类型、功能关闭、旧会话或无关通知。 */
IEC104_SYSTEM_COMMAND_EVENT_HANDLED = 1 /* 含受理、拒绝、丢新、状态处理,不表示已经应答。 */
} IEC104_SystemCommandEventResult_t;
typedef enum {
IEC104_SYSTEM_COMMAND_EXECUTE_FAULT = -2, /* 动作已调用、库清除失败;继续Process尝试否定。 */
IEC104_SYSTEM_COMMAND_EXECUTE_ERROR = -1, /* 未调用action;参数/重入/前置查询失败。 */
IEC104_SYSTEM_COMMAND_EXECUTE_EMPTY = 0, /* 队首不是DECIDE,未调用action。 */
IEC104_SYSTEM_COMMAND_EXECUTE_WAIT = 1, /* 队首DECIDE保留,先读通知;未调用action。 */
IEC104_SYSTEM_COMMAND_EXECUTE_OK = 2 /* 队首转为回复;可因预检拒绝而未调用action。 */
} IEC104_SystemCommandExecuteResult_t;
/* 只读调度与累计计数;计数从Create起累计,Cancel、启停、重连不清零。
* submitted类计数只到发送层接手,不能据此推断已写完、已ACK或实际设备已复位。
* pending_tasks只统计任务FIFO;ACK动作提交后的授权槽、Type70轮次另由专属标志表示。
* 下述ACK动作指QRP1与已启用的专用QRP,不包括QRP2。 */
typedef struct {
uint64_t generation; /* 已分派会话代次;尚无会话或已消费DISCONNECTED时为0。 */
/* active为模块维护的激活状态;events_pending要求先分派Slave通知;decide_pending仅指队首DECIDE。 */
bool active, events_pending, decide_pending;
bool send_waiting; /* FIFO与Type70各自等待标志的汇总,不用于互相清除。 */
/* 分别为Type70最后凭证仍PENDING、ACK动作观察仍QUEUED/SENT、已具备可领取授权。
* reset_ready表示至少一个授权可领取;广播须等同批回复结束且全部ACK结果确定。
* 已确定授权可跨STOP/断线/换代等待Take_Reset;领取前仍须读空通知。 */
bool handoff_pending, ack_pending, reset_ready;
/* 已登记COI、ARMED状态、启动许可、SENDING或HANDOFF状态;ARMED不一定允许立即开始。 */
bool init_registered, init_armed, init_start_allowed, init_round_active;
/* 最近非空Type70轮次完整交接时的实际START编号;0表示尚无完成事实。
* 仅末帧HANDED后更新,不以全部提交OK、空轮或首站成功代替;HANDED也不是socket写完或ACK。
* 新轮尚未完成时保留旧值。先分派通知,再结合active、当前generation/activation_id以及
* init_armed/init_round_active判断;累计init_rounds或一个非零历史编号不能证明本轮已初始化。 */
uint64_t init_completed_activation_id;
/* need_process表示当前可推进的清理/提交/完成事实;回调内不要求重入推进。
* timer_active只计启用且尚未处理的DECIDE期限及ACK动作确认/ACK期限,不计普通回复。 */
bool need_process, timer_active;
uint32_t timeout_remaining_ms; /* 上述期限的最小剩余值;到期或无计时任务时为0。 */
unsigned pending_tasks; /* FIFO占槽数;单播ACK动作在WAIT_ACK后不占;广播逐站回复完才释放整条任务。 */
/* 两种测试命令合计:accepted为合法104/107入槽数,answered为肯定确认提交OK数。
* answered不表示socket写完或收到ACK;否定确认计入negative_submitted,WAIT不重复计数。 */
unsigned long test_accepted, test_answered;
/* reset_accepted为合法105请求入槽数(广播只计一次);reset_refused按目标站计决定拒绝
* 或ACK动作提交前到期转否定次数(含部分失败),
* 不含Handle_Event校验拒绝。reset_busy为授权槽忙拒绝;reset_cancelled为已ACCEPT的ACK动作取消;
* ack_timeouts是reset_cancelled中因业务ACK期限到期的部分。 */
unsigned long reset_accepted, reset_refused, reset_busy, reset_cancelled, ack_timeouts;
unsigned long reset_cancelled_handed; /* 确认已被发送层接手,不等于已写出。 */
unsigned long resets_released; /* Take_Reset成功交给应用的次数,不是实际设备复位次数。 */
/* QRP2成功清除的目标站次数、从NORMAL删除的ASDU条数(不计应用缓存),以及执行前原站失效次数。 */
unsigned long events_cleared_requests, events_discarded, station_mismatches;
/* 应用ACCEPT后NORMAL清除失败次数;action返回非ACCEPT/REJECT值的次数。 */
unsigned long partial_failures, invalid_decisions;
/* Type70整轮交接数、单帧提交OK数、未完成轮次终止数、未发出任何一帧的空轮数。 */
unsigned long init_rounds, init_frames, init_retries, init_empty_rounds;
/* 全部提交OK数(含Type70及ACK动作确认),以及其中P/N=1的回复数。 */
unsigned long submitted, negative_submitted;
/* rejected仅计Handle_Event校验拒绝;waits计两个发送来源的每次提交WAIT。
* cancelled计普通FIFO任务取消,已ACCEPT的ACK动作与Type70分别计专属取消/轮次计数。
* overloads/dropped_requests同时统计满槽丢新;timeouts仅计DECIDE到期转否定,每条一次。 */
unsigned long rejected, waits, cancelled, overloads, dropped_requests, timeouts;
} IEC104_SystemCommandStatus_t;
/* 配置由IEC104_Startup_Config_Default的system_config参数初始化,再按部署设置期限与功能。
* 统一策略为标准功能0x0F、EVERY_START、决定15000ms及ACK30000ms;应用仍须显式登记COI。 */
/**
* 功能:每Slave一个实例,必须早于消费其通知。复制config,不保存回调、不启动网络。
* 输入参数:slave——所属从站服务。
* config——配置。
* 输出参数:无。
* 返回值: 参数非法、重复绑定或池满返回NULL,不消费通知或自动启动Type70轮次。
* 说明:广播只占一个FIFO槽;内部IEC104_SYSTEM_COMMAND_RESET_CAPACITY默认4,限定待领取QRP1/专用授权数。
* 额外槽仅用于同一广播的不同站,槽不足的站在action前否定;单播仍保持全局复位忙规则。
* 无效Slave/config、未知功能位、非法策略、重复绑定或静态池耗尽时返回NULL。
*/
IEC104_SystemCommand_t *IEC104_SystemCommand_Create(IEC104_Slave_t *slave,
const IEC104_SystemCommandConfig_t *config);
/**
* 功能:无效句柄、尚有任务、复位授权/观察槽、进行中的Type70轮次/快照或回调中返回false。
* 输入参数:self——本模块实例。
* 输出参数:self——本模块实例的更新结果。
* 返回值: 无效句柄、动作回调重入或尚有持有责任返回false。
* 说明:不隐式Cancel、不关闭Slave;true后句柄失效。
*/
bool IEC104_SystemCommand_Destroy(IEC104_SystemCommand_t *self);
/**
* 功能:应用显式放弃工作(含已确定但未领取的READY),归还模块引用/ACK观察槽;保留COI登记。
* 输入参数:self——本模块实例。
* 输出参数:self——本模块实例的更新结果。
* 返回值:无。
* 说明:自动STOP/断线清理与此不同:先冻结有效ACK事实,保留已确定的复位决定。
* 已提交确认不撤回,不关闭Slave,后续可继续受理;无效句柄或回调中无操作。
*/
void IEC104_SystemCommand_Cancel(IEC104_SystemCommand_t *self);
/**
* 功能:COI低7位3..31、INIT_END关闭、无效句柄或回调中返回false,其余登记成功返回true。
* 输入参数:self——本模块实例。
* coi——初始化原因。
* 输出参数:self——本模块实例的更新结果。
* 返回值:!Owned(self) || self->in_action || !(self->config.features & IEC104_SYSTEM_COMMAND_FEATURE_INIT_END) || (reason >= 3U && reason <= 31U)时返回false;其余分支返回false、true。
* 说明:活动轮仍使用原COI,新登记只覆盖唯一pending值;空轮等待新的登记或ACTIVATED。
* 已激活时登记也可触发下一轮,不必等待下次START;本调用不发送报文。
*/
bool IEC104_SystemCommand_Set_Initialization(IEC104_SystemCommand_t *self, uint8_t coi);
/**
* 功能:所有Slave通知按FIFO分派;输入事件始终只读,不调用应用、不在本入口发送回复。
* 输入参数:self——本模块实例。
* event——事件。
* 输出参数:self——本模块实例的更新结果。
* 返回值:按处理分支返回IEC104_SYSTEM_COMMAND_EVENT_ERROR、ended ? IEC104_SYSTEM_COMMAND_EVENT_HANDLED : IEC104_SYSTEM_COMMAND_EVENT_ERROR、IEC104_SYSTEM_COMMAND_EVENT_IGNORED、IEC104_SYSTEM_COMMAND_EVENT_HANDLED、Request(self, event, &identity)。
* 说明:104校验固定AA 55,107解析测试序号并校验CP56字段;合法请求保留OA/CA/T及原载荷排普通ACT_CON。
* 两种测试命令均不支持广播,不因T=0产生设备动作;只回一次确认,不追加ACT_TERM。
* 合法105 TEST直接排普通肯定ACT_CON(T=1),不进入DECIDE、不占授权/ACK观察槽。
* 非法限定词、未启用功能及其他报文错误仍按原原因拒绝;非空广播逐站以具体CA回复。
* I帧返回HANDLED后不再兜底;生命周期通知仍应继续分派给其他业务实例。
*/
IEC104_SystemCommandEventResult_t IEC104_SystemCommand_Handle_Event(IEC104_SystemCommand_t *self,
const IEC104_SlaveEvent_t *event);
/**
* 功能:每轮网络推进并读空通知后调用,含WAIT重试、全FIFO决定到期转换和ACK结果处理。
* 输入参数:self——本模块实例。
* 输出参数:self——本模块实例的更新结果。
* 返回值:!Owned(self) || self->in_action时返回false;state == IEC104_SLAVE_REQUEST_ERROR时返回false;state != IEC104_SLAVE_REQUEST_READY时返回true;!Advance_Reset(self, now, true)时返回false;其余分支返回false、true。
* 说明:QRP1/专用QRP提交前到期保留原槽转否定回复,同时撤销动作许可;提交后的肯定确认不改写。
* 有界推进,不调用action;参数、重入、会话/ACK查询及内部准备失败返回false。
* true也包含让出通知、等待发送以及发送故障后取消完成,不表示已应答或已复位。
*/
bool IEC104_SystemCommand_Process(IEC104_SystemCommand_t *self);
/**
* 功能:action非NULL,context原样传入;只决定FIFO队首105的当前目标,每次至多调用一次,不保存函数/参数。
* 输入参数:self——本模块实例。
* action——动作回调。
* context——调用方上下文。
* 输出参数:self——本模块实例的更新结果。
* 返回值: QRP2应用已接受但库侧清事件失败返回FAULT,不回滚或重复应用动作。
* 说明:ACCEPT或拒绝后回复由Process提交;提交WAIT不再调用action。EMPTY不表示模块全空。
* FAULT仍留有待发否定回复,应用应记录部分失败并继续Process,不能重做已发生的清除。
*/
IEC104_SystemCommandExecuteResult_t IEC104_SystemCommand_Execute_Next(IEC104_SystemCommand_t *self,
IEC104_SystemCommandResetAction_t action, void *context);
/**
* 功能:只有授权READY、通知已读空且服务查询无错误才写出、释放授权并返回true;其余不改输出。
* 输入参数:self——本模块实例。
* request——请求。
* 输出参数:request——请求的更新结果。
* 返回值:成功交出首个可领取的复位请求时返回true;无可领取授权、通知未读或查询失败时返回false。
* 说明:QRP1和已启用的专用QRP共用本入口;应用须按输出的原qualifier及目标CA执行约定动作。
* 广播须等同批全部回复提交完成,且肯定确认均已有效ACK或取消/超时;然后逐站领取。
* STOP/断线清理后,只保留已确定站的许可;每条输出仅代表其实际CA,不代表整机许可。
* 原连接已STOP/断开/换代仍可领取,输出保留原身份;成功后复位责任交给应用,仅能领取一次。
* 须在每轮Step中调用,不能仅等新网络事件;显式Cancel可主动放弃尚未领取的决定。
*/
bool IEC104_SystemCommand_Take_Reset(IEC104_SystemCommand_t *self,
IEC104_SystemCommandResetRequest_t *request);
/**
* 功能:只读取得有效SystemCommand实例绑定的Slave,用于跨业务协调前校验归属。
* 输入参数:self——待查询实例;NULL、池外地址或已销毁实例返回NULL。
* 返回值:原绑定Slave的借用指针,不延长其寿命;调用方仍须遵守先销毁业务再销毁Slave。
* 说明:不查询连接、不消费通知、不改变实例;本入口不能证明某轮初始化已完成。
*/
IEC104_Slave_t *IEC104_SystemCommand_Get_Slave(const IEC104_SystemCommand_t *self);
/**
* 功能:只读,回调内允许;无效句柄/输出或服务、凭证、ACK查询失败返回false且不改输出。
* 输入参数:self——本模块实例。
* status——状态快照。
* 输出参数:status——全部查询成功后写回快照,失败保持原值。
* 返回值: Process再次查询会取消错误授权并报告false,调用者按服务错误清理。
* 说明:失败时不得继续使用旧快照做调度;查询不会取消授权、处理到期或推进发送。
* 立即续跑:events_pending || need_process || decide_pending || reset_ready。
* 等待网络上限取timeout_remaining_ms;Get_Status不代替每轮Process。
*/
bool IEC104_SystemCommand_Get_Status(const IEC104_SystemCommand_t *self,
IEC104_SystemCommandStatus_t *status);
#ifdef __cplusplus
}
#endif
#endif /* IEC104_SYSTEM_COMMAND_H */