211 lines
13 KiB
C
211 lines
13 KiB
C
/*
|
||
* 国网扩展 Type211 软件升级:命令校验、单会话和经 ACK 确认的重启授权。
|
||
* 升级包经 Type210 文件服务到达;文件存储、校验、设备独占和实际激活由应用负责。
|
||
* 本模块与 Slave 在同一串行上下文推进,仅 Execute_Next 同步调用应用动作。
|
||
* 接入流程、互操作配置和应用所有权约定见 docs/104/IEC104_SoftwareUpgrade_设计架构.md。
|
||
*/
|
||
#ifndef IEC104_SOFTWAREUPGRADE_H
|
||
#define IEC104_SOFTWAREUPGRADE_H
|
||
|
||
#include "IEC104_Slave.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
typedef struct IEC104_SoftwareUpgrade IEC104_SoftwareUpgrade_t;
|
||
/* 211 是本模块的国网扩展类型,不复用公共层标准 Type121 的 F_SR_NA_1 名称。 */
|
||
#define IEC104_SOFTWARE_UPGRADE_TYPE_ID 211U
|
||
/* CTYPE 高位区分启动/结束;低七位未定义,动作与确认均保留请求原值。 */
|
||
#define IEC104_SOFTWARE_UPGRADE_CTYPE_SE 0x80U
|
||
|
||
typedef enum {
|
||
IEC104_SOFTWARE_UPGRADE_OP_START = 1, /* COT6、S/E1:准备候选并取得应用设备所有权。 */
|
||
IEC104_SOFTWARE_UPGRADE_OP_END, /* COT6、S/E0:验收并冻结候选;此处不得重启。 */
|
||
IEC104_SOFTWARE_UPGRADE_OP_CANCEL, /* COT8、S/E0:使候选失效,接受即结束会话。 */
|
||
IEC104_SOFTWARE_UPGRADE_OP_ABANDON /* 非命令收尾通知,不发送确认,动作返回值忽略。 */
|
||
} IEC104_SoftwareUpgradeOperation_t;
|
||
|
||
typedef enum {
|
||
IEC104_SOFTWARE_UPGRADE_ABANDON_NONE = 0, /* 普通动作的默认值。 */
|
||
IEC104_SOFTWARE_UPGRADE_ABANDON_SUPERSEDED, /* 同归属的新 START 取代旧 OPEN 会话。 */
|
||
IEC104_SOFTWARE_UPGRADE_ABANDON_SESSION_TIMEOUT, /* OPEN 会话期限到期。 */
|
||
IEC104_SOFTWARE_UPGRADE_ABANDON_ACK_TIMEOUT, /* END 肯定确认提交或获 ACK 超期。 */
|
||
IEC104_SOFTWARE_UPGRADE_ABANDON_ACK_LOST, /* 策略允许观察的时段结束,尚未获 ACK。 */
|
||
IEC104_SOFTWARE_UPGRADE_ABANDON_CANCELLED /* 生命周期/故障清理,或应用显式 Cancel。 */
|
||
} IEC104_SoftwareUpgradeAbandonReason_t;
|
||
|
||
typedef enum {
|
||
IEC104_SOFTWARE_UPGRADE_RESTART_ACKED = 0, /* 默认:期限内 ACK,包含首次 STOP 后排空期。 */
|
||
IEC104_SOFTWARE_UPGRADE_RESTART_ACTIVE_ACKED = 1 /* 仅认首次 STOP 或断开前的 ACK,与 105 QRP1 相同。 */
|
||
} IEC104_SoftwareUpgradeRestartPolicy_t;
|
||
|
||
typedef enum {
|
||
IEC104_SOFTWARE_UPGRADE_SESSION_NONE = 0, /* 无真实会话;仍可能欠 ABANDON 应用收尾。 */
|
||
IEC104_SOFTWARE_UPGRADE_SESSION_OPEN, /* START 已接受,允许写候选、END 或 CANCEL。 */
|
||
IEC104_SOFTWARE_UPGRADE_SESSION_WAIT_ACK, /* END 已接受;肯定确认待提交或等待 ACK。 */
|
||
IEC104_SOFTWARE_UPGRADE_SESSION_RESTART_READY /* 授权已确定,跨连接保留到领取或 Cancel。 */
|
||
} IEC104_SoftwareUpgradeSessionState_t;
|
||
|
||
/* 只读值副本;回调只能在返回前借用此指针,Take_Restart 则按值写出 END 请求。
|
||
* ABANDON 的原请求字段取被接受的 START,仅 operation/reason 改为通知,
|
||
* session_serial/session_started_ms 使用接受后的会话值,不混用触发清理的请求。 */
|
||
typedef struct {
|
||
IEC104_SlaveEventIdentity_t identity; /* 原 Slave 句柄、实例编号及连接代次,整体比较。 */
|
||
uint64_t receive_serial, station_id, session_serial; /* 原 I 帧流水号、站点注册编号、升级会话序号。 */
|
||
uint16_t common_address; /* 与完整 identity、station_id 一起确定会话归属。 */
|
||
uint8_t originator_address, ctype; /* 原 OA 和完整 CTYPE;OA 不参与会话键。 */
|
||
uint32_t ioa; /* 原三字节 IOA,默认不限制其值。 */
|
||
IEC104_SoftwareUpgradeOperation_t operation;
|
||
IEC104_SoftwareUpgradeAbandonReason_t reason; /* 仅 ABANDON 有收尾原因。 */
|
||
uint64_t accepted_ms, session_started_ms; /* 请求入槽、START 接受时刻;START 动作内后者为 0。 */
|
||
} IEC104_SoftwareUpgradeRequest_t;
|
||
|
||
/* 未列出的动作返回值也按 REJECT 处理;START 拒绝不消耗会话序号。 */
|
||
typedef enum {
|
||
IEC104_SOFTWARE_UPGRADE_DECISION_REJECT = 0,
|
||
IEC104_SOFTWARE_UPGRADE_DECISION_ACCEPT = 1
|
||
} IEC104_SoftwareUpgradeDecision_t;
|
||
|
||
/* 同步短时动作,REJECT 必须没有副作用;END 验收并冻结候选,但不得重启。
|
||
* ABANDON 使候选失去激活资格;旧文件/验证引用须由应用安全收尾,不能提前释放仍会使用的存储。
|
||
* 从请求入槽到会话结局交付,action/context 身份必须稳定;仍被应用异步工作引用时继续延寿。
|
||
* 回调内可 Get_Status 或只读查询站点;不得推进 Slave,也不得重入本模块修改入口。 */
|
||
typedef IEC104_SoftwareUpgradeDecision_t (*IEC104_SoftwareUpgradeAction_t)(void *context,
|
||
const IEC104_SoftwareUpgradeRequest_t *request);
|
||
|
||
typedef struct {
|
||
IEC104_SoftwareUpgradeRestartPolicy_t restart_policy; /* 只支持上述两种 ACK 策略。 */
|
||
/* 分别为 END 确认置 S/E1、要求 IOA0、额外接受 VSQ1;默认均 false。 */
|
||
bool end_confirm_se_one, check_ioa, accept_vsq_one;
|
||
/* 分别从请求入槽、普通回复首次到队首、START 接受、END 动作调用前开始计时。 */
|
||
uint32_t execute_timeout_ms, reply_timeout_ms, session_timeout_ms, restart_ack_timeout_ms;
|
||
} IEC104_SoftwareUpgradeConfig_t;
|
||
|
||
typedef enum {
|
||
IEC104_SOFTWARE_UPGRADE_EVENT_ERROR = -1, /* 参数/归属/重入/内部失败,不能再按未知类型回 44。 */
|
||
IEC104_SOFTWARE_UPGRADE_EVENT_IGNORED = 0, /* 未接手该事件,由应用继续分派。 */
|
||
IEC104_SOFTWARE_UPGRADE_EVENT_HANDLED = 1 /* 已接手,含拒绝/丢新/生命周期;不代表确认已提交。 */
|
||
} IEC104_SoftwareUpgradeEventResult_t;
|
||
|
||
typedef enum {
|
||
IEC104_SOFTWARE_UPGRADE_EXECUTE_ERROR = -1, /* 参数/重入/查询失败,本次未调用动作。 */
|
||
IEC104_SOFTWARE_UPGRADE_EXECUTE_EMPTY = 0, /* 无可执行队首;待发确认交由 Process 推进。 */
|
||
IEC104_SOFTWARE_UPGRADE_EXECUTE_WAIT = 1, /* 待执行队首保留,先读空并分派 Slave 通知。 */
|
||
IEC104_SOFTWARE_UPGRADE_EXECUTE_OK = 2 /* 执行一个任务或交付 ABANDON,不代表确认已提交。 */
|
||
} IEC104_SoftwareUpgradeExecuteResult_t;
|
||
|
||
/* 只读调度快照;计数从 Create 累计,Cancel/连接启停均不清零。
|
||
* execute_pending 表示 FIFO 任意位置有待执行请求或欠 ABANDON;execute_ready 才表示可立即推进。
|
||
* need_process 不因单纯等 ACK/发送 WAIT 而置位,应用仍须每轮调用 Process。
|
||
* faulted 粘滞至 Destroy/Create,停止普通业务计时,只允许清理及既有授权处置。 */
|
||
typedef struct {
|
||
uint64_t generation;
|
||
bool active, events_pending, execute_pending, execute_ready, need_process, timer_active;
|
||
IEC104_SoftwareUpgradeSessionState_t session_state; /* 真实会话;session_active 仅含 OPEN/WAIT_ACK。 */
|
||
bool session_active, session_test, ack_pending, restart_ready, abandon_pending, faulted;
|
||
/* 真实会话为 NONE 时清零;应用设备 owner 可能仍由 ABANDON/文件收尾/激活任务持有。 */
|
||
IEC104_SlaveEventIdentity_t session_identity;
|
||
uint16_t session_common_address;
|
||
uint64_t session_station_id, session_serial;
|
||
uint32_t timeout_remaining_ms; /* 各启用期限的最早剩余值;为 0 时须结合 timer_active 判是否到期。 */
|
||
unsigned pending_requests; /* 占用任务槽数,含待执行和待提交确认。 */
|
||
unsigned long accepted, rejected, dropped_requests, timeouts;
|
||
unsigned long starts, ends_accepted, ends_rejected, cancels, abandons;
|
||
unsigned long session_timeouts, ack_timeouts, acks_lost, ack_errors, restarts_released;
|
||
unsigned long submitted, negative_submitted, waits, cancelled;
|
||
unsigned long reply_timeouts, send_errors, close_errors, faulted_dropped;
|
||
} IEC104_SoftwareUpgradeStatus_t;
|
||
|
||
/**
|
||
* 功能:默认 ACKED、S/E 镜像、IOA 不检查、仅 VSQ0;执行/普通回复各 15s、会话不限、ACK 30s。
|
||
* 输入参数:config——配置。
|
||
* 输出参数:config——配置的更新结果。
|
||
* 返回值:无。
|
||
* 说明:任一期限为 0 仅禁用该业务计时,不取消链路期限或 ACK 要求;config 为 NULL 无操作。
|
||
*/
|
||
void IEC104_SoftwareUpgrade_Config_Default(IEC104_SoftwareUpgradeConfig_t *config);
|
||
/**
|
||
* 功能:每 Slave 至多一个实例,按值复制 config;可在 Slave_Init 前创建,但须早于首条通知消费。
|
||
* 输入参数:slave——所属从站服务。
|
||
* config——配置。
|
||
* 输出参数:无。
|
||
* 返回值: 参数非法、池满或实例编号耗尽返回NULL;
|
||
* 说明:无效 slave/config、策略越界、重复绑定、池满或实例编号耗尽返回 NULL,不占用池槽。
|
||
*/
|
||
IEC104_SoftwareUpgrade_t *IEC104_SoftwareUpgrade_Create(IEC104_Slave_t *slave,
|
||
const IEC104_SoftwareUpgradeConfig_t *config);
|
||
/**
|
||
* 功能:不隐式 Cancel;仍有任务、真实/TEST 会话、ACK、ABANDON、未领取授权或在回调内均失败。
|
||
* 输入参数:self——本模块实例。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:回调内或仍有未完成责任时返回false。
|
||
* 说明:不隐式取消工作;回调内或仍有未完成责任时返回false。
|
||
*/
|
||
bool IEC104_SoftwareUpgrade_Destroy(IEC104_SoftwareUpgrade_t *self);
|
||
/**
|
||
* 功能:必须在 Slave_Close 前调用:清任务/TEST、释放观察,并放弃真实工作(含未领取 READY)。
|
||
* 输入参数:self——本模块实例。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:无。
|
||
* 说明:真实会话站点引用留到随后 Execute_Next 交付 ABANDON;不撤回已提交确认、不解除 faulted。
|
||
*/
|
||
void IEC104_SoftwareUpgrade_Cancel(IEC104_SoftwareUpgrade_t *self);
|
||
/**
|
||
* 功能:按 Slave FIFO 次序传入全部生命周期通知及候选 I 帧,不调用动作。
|
||
* 输入参数:self——本模块实例。
|
||
* event——事件。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:旧代次通知忽略,身份或重入错误返回ERROR。
|
||
* 说明:faulted 消费可识别的 211,防止落入未知类型兜底;其他模块仍须接收生命周期通知。
|
||
*/
|
||
IEC104_SoftwareUpgradeEventResult_t IEC104_SoftwareUpgrade_Handle_Event(IEC104_SoftwareUpgrade_t *self,
|
||
const IEC104_SlaveEvent_t *event);
|
||
/**
|
||
* 功能:每轮都调用,即使 need_process 为 false;有界推进确认、期限和 ACK,不调用应用动作。
|
||
* 输入参数:self——本模块实例。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:false表示实例/查询/发送故障,true不承诺已有工作完成。
|
||
* 说明:发送/查询/关闭故障置 faulted 并返回 false,应用须有序收尾,不能忙循环重试。
|
||
*/
|
||
bool IEC104_SoftwareUpgrade_Process(IEC104_SoftwareUpgrade_t *self);
|
||
/**
|
||
* 功能:先交付 ABANDON,否则只处理队首,至多调用一次 action;action/context 不保存。
|
||
* 输入参数:self——本模块实例。
|
||
* action——动作回调。
|
||
* context——调用方上下文。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值: 通知阻塞有待执行队首时返回WAIT,无工作返回EMPTY;
|
||
* 动作完成后返回OK,即使随后的确认提交失败也不能据此重做动作;
|
||
* 说明:动作后的提交故障仍返回 OK,通过状态/Process 报告,调用者不得重做已发生的动作。
|
||
*/
|
||
IEC104_SoftwareUpgradeExecuteResult_t IEC104_SoftwareUpgrade_Execute_Next(IEC104_SoftwareUpgrade_t *self,
|
||
IEC104_SoftwareUpgradeAction_t action, void *context);
|
||
/**
|
||
* 功能:已确定授权用原 END 身份检查:READY/STALE 可且仅可领取一次,WAIT_EVENTS/ERROR 保留授权。
|
||
* 输入参数:self——本模块实例。
|
||
* request——请求。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* request——请求的更新结果。
|
||
* 返回值:存在满足确认条件且可领取的重启授权时返回true并交付;身份、状态、通知或观察条件不满足时返回false。
|
||
* 说明:false 不改输出;本函数不执行/排空任务 FIFO。应用在 END 接受前预留激活任务,领取前固定候选,
|
||
* 成功同轮进入设备 QUIESCING,取消尚未执行的请求并停止新业务,候选所有权交给应用激活任务。
|
||
*/
|
||
bool IEC104_SoftwareUpgrade_Take_Restart(IEC104_SoftwareUpgrade_t *self,
|
||
IEC104_SoftwareUpgradeRequest_t *request);
|
||
/**
|
||
* 功能:允许在动作内查询;会话/ACK 查询失败返回 false 且输出不变,不得继续用旧快照调度。
|
||
* 输入参数:self——本模块实例。
|
||
* status——状态快照。
|
||
* 输出参数:status——全部查询成功后写回快照,失败保持原值。
|
||
* 返回值:查询错误返回false且输出不变。
|
||
* 说明:不推进ACK裁决或调用清理,回调内压住推进提示;查询错误返回false且输出不变。
|
||
*/
|
||
bool IEC104_SoftwareUpgrade_Get_Status(const IEC104_SoftwareUpgrade_t *self,
|
||
IEC104_SoftwareUpgradeStatus_t *status);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
#endif /* IEC104_SOFTWAREUPGRADE_H */
|