/* Windows 升级后端:三份真实负载、双 bank 元数据及可恢复的 dtu/dtu-1 文件。 * 全部操作串行;首次清零对象,Open 后保持地址稳定,不执行或加载映像字节。 * 存储和安装错误可能已经改变介质,故障实例须 Close/Open 后恢复事实。 */ #ifndef IEC104_EXAMPLE_UPGRADE_H #define IEC104_EXAMPLE_UPGRADE_H #include "IEC60870_FirmwareUpdate.h" /* 整包包含 16 字节 I104 头;持久槽及安装文件只包含非空 payload。 */ #define EXAMPLE_UPGRADE_PACKAGE_MAX (16U * 1024U * 1024U) typedef struct { IEC60870_FirmwareUpdate_t core; /* 拥有角色及事务状态;回调 context 指回本对象。 */ void *storage; /* 独占元数据句柄同时承担整个升级目录的单写者锁。 */ void *images[IEC60870_FIRMWARE_UPDATE_SLOT_COUNT]; /* 惰性打开的独占源槽,保持至重置该槽或 Close。 */ char parent[200]; /* 复制保存已有父目录;所有内部文件使用固定名称。 */ uint8_t banks[2][IEC60870_FIRMWARE_UPDATE_WIRE_SIZE + 32U]; /* 两份头加载荷工作区,不是额外映像槽。 */ uint8_t io[256]; /* 槽复制及真实安装共用,不在 RAM 保存完整映像。 */ uint8_t package_header[16]; /* 只累计传输包头,槽文件不保存这 16 字节。 */ uint32_t package_size; /* 本次声明的完整工程包长度,包含头。 */ uint32_t received_size; /* 本次成功接收的完整包偏移;不作为跨重启续传凭据。 */ bool opened; /* 元数据恢复/基线登记成功;不证明映像已安装或核心始终健康。 */ bool candidate_open; /* 门面是否继续接受当前上传的字节。 */ bool candidate_started; /* 包头完整且核心 Begin 成功,已持久登记接收意图。 */ } ExampleUpgrade; /** * 功能:Open 取得独占资源并恢复元数据,或用显式 seed 登记真实初始 current。 * 输入参数:self——调用方持有的模块实例;parent——已存在的宿主父目录;seed_path——可选首次初始化基线包路径。 * 输出参数:self——本次操作更新的实例或工作区。 * 返回值:true表示请求的资源或存储实例已准备就绪;false表示输入校验、资源获取或恢复失败。 * 说明:没有升级档案时必须提供真实完整 I104 基线包;已有存储拒绝再次提供 seed。 * Open 只恢复或登记基线,调用者须另调 Prepare_Boot,再按真实就绪结果 Confirm。 * 父目录须存在;活对象重复打开不改变原资源,已有坏档案不自动重建。 * 失败关闭本次取得的句柄,但首次 seed 复制/登记失败留下的档案仍保留; * 无 seed 的首次拒绝不创建文件。成功后对象不能移动,所有调用须串行。 */ bool Example_Upgrade_Store_Open(ExampleUpgrade *self, const char *parent, const char *seed_path); /** * 功能:只释放句柄和内存使用资格,不提交 Abort/Confirm,也不改变持久角色。 * 输入参数:self——调用方持有的模块实例。 * 输出参数:self——本次操作更新的实例或工作区。 * 返回值:无。 * 说明:先关闭源槽再释放元数据锁,禁用核心及上传;可重复调用,不删除任何持久文件。 * 关闭本身不撤销候选或确认试运行,调用方先交完原文件/升级会话的必要收尾。 */ void Example_Upgrade_Store_Close(ExampleUpgrade *self); /** * 功能:查询已确认角色,不能把试安装 dtu 的内容提前公布为正式版本;无介质读取副作用。 * 输入参数:self——调用方持有的模块实例;descriptor——固件映像描述。 * 输出参数:descriptor——固件映像描述。 * 返回值:true表示取得相应角色的有效映像描述;false表示存储状态或角色不可用。 * 说明:按值返回最后确认的负载描述,TRIAL 期间仍为旧 current;失败保持输出。 * 这是健康核心的元数据查询,不读取槽或检查当前 dtu 文件。 */ bool Example_Upgrade_Store_Current(const ExampleUpgrade *self, IEC60870_FirmwareUpdateDescriptor_t *descriptor); /** * 功能:只预留当前上传的小包头和长度;旧 VERIFIED 需调用方先显式 Abort 才能替换。 * 输入参数:self——调用方持有的模块实例;package_size——含包头的整包字节数。 * 输出参数:self——本次操作更新的实例或工作区。 * 返回值:true表示请求的资源或存储实例已准备就绪;false表示输入校验、资源获取或恢复失败。 * 说明:仅 STABLE 且没有活动上传时接受 17..上限字节的整包,只重置小包头及偏移。 * 此时不占新核心候选、不截断源槽;已有未授权候选应先 Abort。 */ bool Example_Upgrade_Store_Candidate_Open(ExampleUpgrade *self, uint32_t package_size); /** * 功能:解析可跨段包头,并把连续负载写入候选固件源槽。 * 输入参数:self——调用方持有的模块实例;offset——从起点计算的字节偏移;bytes——字节数据缓冲;length——本次数据或名称的有效字节数。 * 输出参数:self——本次操作更新的实例或工作区。 * 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。 * 说明:offset 指整个包,必须连续且不越界;bytes 只借用本次调用,16 字节头可跨段。 * 头完整后验证长度、魔数及高于 current 的版本,再 Begin 并仅写负载到空闲槽。 * 入口拒绝不推进偏移;包头/核心失败关闭本次接收资格,已提交意图可能仍存在, * 调用方按核心状态 Abort 或关闭恢复,不能以 false 推断介质未变。 */ bool Example_Upgrade_Store_Candidate_Write(ExampleUpgrade *self, uint32_t offset, const uint8_t *bytes, size_t length); /** * 功能:收齐才进入核心最终同步/读回;先关闭接收资格,使失败后不能继续补写已提交候选。 * 输入参数:self——调用方持有的模块实例。 * 输出参数:self——本次操作更新的实例或工作区。 * 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。 * 说明:只接受已收齐的候选;关闭接收资格后同步源槽、读回 CRC 并持久登记 VERIFIED。 * 这不安装、不授权、不改变 current。CRC 拒绝须 Abort 后重传;I/O 或提交不确定 * 可能使核心故障。未收齐的入口拒绝仍保留上传,最终收尾由调用方负责。 */ bool Example_Upgrade_Store_Candidate_Finish(ExampleUpgrade *self); /** * 功能:只在核心确认未授权候选已撤销后清门面标志;授权后及故障态拒绝,保留恢复事实。 * 输入参数:self——调用方持有的模块实例。 * 输出参数:self——本次操作更新的实例或工作区。 * 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。 * 说明:STABLE 无候选时幂等成功,RECEIVING/VERIFIED 时持久撤销角色后清上传标志。 * 不删除源槽旧字节,不撤回已经持久授权的安装或试运行事实;失败保留当前标志。 */ bool Example_Upgrade_Store_Candidate_Abort(ExampleUpgrade *self); /** * 功能:END 可据此固定已验证描述;返回值副本不延长上传缓冲寿命,也不授予安装资格。 * 输入参数:self——调用方持有的模块实例;descriptor——固件映像描述。 * 输出参数:descriptor——固件映像描述。 * 返回值:true表示取得相应角色的有效映像描述;false表示存储状态或角色不可用。 * 说明:仅健康 VERIFIED 状态按值返回描述,供 END 固定任务;失败保持输出。 * 描述不借用内部内存,也不表示已经获得安装授权。 */ bool Example_Upgrade_Store_Candidate_Info(const ExampleUpgrade *self, IEC60870_FirmwareUpdateDescriptor_t *descriptor); /** * 功能:真实协议授权的持久边界;失败可能已经写入 AUTHORIZED,不能改走普通取消重传。 * 输入参数:self——调用方持有的模块实例。 * 输出参数:无独立输出参数。 * 返回值:true表示核心接受了持久授权;false表示状态不允许或提交失败,落盘结果仍须按故障契约确认。 * 说明:只将 VERIFIED 持久转为 AUTHORIZED;调用方先取得实际协议授权。 * 不在此安装文件;false 可能已持久授权,须停下恢复,不能转而盲目 Abort。 */ bool Example_Upgrade_Store_Authorize(ExampleUpgrade *self); /** * 功能:核心负责选择取消、安装或回退,Install 回调负责真实别名文件恢复。 * 输入参数:self——调用方持有的模块实例。 * 输出参数:无独立输出参数。 * 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。 * 说明:每次启动/激活只调用一次,调用方须先结束活动上传;不由 Open 自动调用。 * STABLE 修复安装文件,未授权候选取消,已授权候选安装为 TRIAL;上次遗留 * TRIAL 恢复旧 current/backup。false 可能已有部分安装效果,按持久意图重开恢复。 * 只复制和核对文件字节,不运行任意二进制,也不能把它当循环推进接口。 */ bool Example_Upgrade_Store_Prepare_Boot(ExampleUpgrade *self); /** * 功能:STABLE 仅核对现有 dtu,不重复轮转角色;TRIAL 核对候选安装文件后才让核心确认。 * 输入参数:self——调用方持有的模块实例。 * 输出参数:无独立输出参数。 * 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。 * 说明:宿主确认只证明安装字节匹配,调用者仍须先完成协议及应用就绪检查。 * STABLE 读回 dtu 与 current 匹配后成功,不写元数据;TRIAL 先读回 dtu 与候选 * 匹配,再由核心复验源槽并持久轮转 current/backup。TRIAL 路径的安装文件不匹配 * 会返回 false 且仍留 TRIAL,核心提交失败则可能已确认;两者都不能直接重做业务。 * 不执行映像,不能用接收 END 或协议 ACK 代替该调用时点。 */ bool Example_Upgrade_Store_Confirm(ExampleUpgrade *self); #endif /* IEC104_EXAMPLE_UPGRADE_H */