Files
STM32F4-Base/IEC60870-Slave/common/IEC60870_FirmwareUpdate.h
T
STF bdcc8b6500
CI / L0 静态门禁 (pre-commit) (push) Failing after 7m46s
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 21s
添加遥控、参数装载、文件传输等业务
2026-11-16 22:19:17 -08:00

204 lines
14 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.
/* 三映像槽升级核心:角色与动作意图持久化,介质及安装动作由平台回调实现。
* 纯 C99,无堆/RTOS/文件系统;调用方持有实例和后端,所有操作必须串行。 */
#ifndef IEC60870_FIRMWARE_UPDATE_H
#define IEC60870_FIRMWARE_UPDATE_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#define IEC60870_FIRMWARE_UPDATE_SLOT_COUNT 3U
#define IEC60870_FIRMWARE_UPDATE_NO_SLOT 255U
#define IEC60870_FIRMWARE_UPDATE_WIRE_SIZE 60U
#define IEC60870_FIRMWARE_UPDATE_SCRATCH_SIZE 256U
/* INVALID 表示参数或调用阶段不符,不产生介质副作用;REJECTED 表示基线/候选
* 完整性或产品许可拒绝。ERROR 表示不可继续当前操作;介质/安装不确定时会置
* faulted,事务号耗尽则仅拒绝 Begin,不置故障。EMPTY 仅用于无基线的启动准备。 */
typedef enum {
IEC60870_FIRMWARE_UPDATE_REJECTED = -3,
IEC60870_FIRMWARE_UPDATE_INVALID = -2,
IEC60870_FIRMWARE_UPDATE_ERROR = -1,
IEC60870_FIRMWARE_UPDATE_EMPTY = 0,
IEC60870_FIRMWARE_UPDATE_OK = 1
} IEC60870_FirmwareUpdateResult_t;
/* 这些值写入元数据,已有值的含义不能随枚举顺序调整。VERIFIED 仅表示内容
* 已核验;AUTHORIZED 才允许下一次启动安装。TRIAL 尚未轮转已确认的源槽。 */
typedef enum {
IEC60870_FIRMWARE_UPDATE_STATE_EMPTY = 0,
IEC60870_FIRMWARE_UPDATE_STABLE = 1,
IEC60870_FIRMWARE_UPDATE_RECEIVING = 2,
IEC60870_FIRMWARE_UPDATE_VERIFIED = 3,
IEC60870_FIRMWARE_UPDATE_AUTHORIZED = 4,
IEC60870_FIRMWARE_UPDATE_INSTALLING = 5,
IEC60870_FIRMWARE_UPDATE_TRIAL = 6,
IEC60870_FIRMWARE_UPDATE_ROLLING_BACK = 7
} IEC60870_FirmwareUpdateState_t;
/* 槽中仅保存 payload,不含传输包头。version/size 必须非零,crc 是 payload
* 的反射 CRC32;CRC 完整性检查不代替产品的签名、机型及版本许可策略。 */
typedef struct {
uint32_t version; /* 产品版本标识;核心只检查非零,不内置升降级准入规则。 */
uint32_t size; /* 纯负载字节数,受 Init 的 max_image_size 限制。 */
uint32_t crc; /* 完整负载的 CRC32 最终值;零本身也是合法校验值。 */
} IEC60870_FirmwareUpdateDescriptor_t;
/* 所有缓冲只在同步回调期间借用,不保存指针或重入会修改本实例的接口;
* 回调允许通过 Get_Status 只读查询角色,供平台决定当前/备份派生内容。
* metadata_read:仅从未提交返回 EMPTY;读取/损坏 ERROR,OK 才填写 size。
* metadata_commit:单条原子替换并完成持久同步才 true,false 可能已提交。
* image_begin:重置指定空闲槽为新候选;write/read 必须完成全部 length 字节。
* image_sync:候选完整内容已持久化才 true。install 不修改这三个源槽,按
* (transaction_id,slot,descriptor) 幂等地安装/选择运行映像,成功须持久完成;
* 它不得在返回前跳转或重启。相同回调用于安装、回退及确保稳定映像已安装。
* validate 可 NULL,在实际读回 CRC 正确后执行产品许可校验,false 为拒绝。
* 它也用于 current/backup 复验,不能无条件把旧版拒绝掉;实际槽长等介质
* 约束也由后端在这里检查,核心只读取描述符指定的字节数。
* context 由调用方保活;Init 不自动启动安装或取得后端资源所有权。 */
typedef struct {
void *context;
IEC60870_FirmwareUpdateResult_t (*metadata_read)(void *context,
uint8_t *bytes, size_t capacity, size_t *size);
bool (*metadata_commit)(void *context, const uint8_t *bytes, size_t size);
bool (*image_begin)(void *context, uint8_t slot, uint32_t size);
bool (*image_write)(void *context, uint8_t slot, uint32_t offset,
const uint8_t *bytes, size_t length);
bool (*image_read)(void *context, uint8_t slot, uint32_t offset,
uint8_t *bytes, size_t length);
bool (*image_sync)(void *context, uint8_t slot);
bool (*install)(void *context, uint8_t slot,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor, uint64_t transaction_id);
bool (*validate)(void *context, uint8_t slot,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor);
} IEC60870_FirmwareUpdateStore_t;
/* current 始终表示最后确认的映像;TRIAL 时实际试运行的是 candidate。
* Confirm 才轮转 current/backup,回退保留旧 current 及其原 backup。
* received_size 只在本次连续接收会话有效,不作为断电续传偏移。 */
typedef struct {
IEC60870_FirmwareUpdateState_t state; /* 最近一次已知成功提交的状态,故障时未必等于介质最新值。 */
uint8_t current_slot; /* 已确认角色;空库为 NO_SLOT。 */
uint8_t backup_slot; /* 上一个确认版本;首次 Provision 后为 NO_SLOT。 */
uint8_t candidate_slot; /* 有候选的持久阶段才有效,与两个保留角色互异。 */
uint64_t transaction_id; /* Provision 从1开始,每次 Begin 加1;安装及回退重试沿用它。 */
IEC60870_FirmwareUpdateDescriptor_t images[IEC60870_FIRMWARE_UPDATE_SLOT_COUNT]; /* 按物理槽索引,无角色项全零。 */
uint32_t received_size; /* 易失的已接收负载字节数,Init 后归零。 */
bool faulted; /* 易失闭锁位;仅重新 Init 可解除,查询仍可读取该位。 */
} IEC60870_FirmwareUpdateStatus_t;
/* 公开布局仅供静态分配,应用须通过API读取/修改状态。store 为浅拷贝;
* 接收会话和工作缓冲均不是可跨调用借用的文件快照。 */
typedef struct {
IEC60870_FirmwareUpdateStore_t store; /* 回调表按值保存,context 仍由调用方拥有。 */
IEC60870_FirmwareUpdateStatus_t status;
uint32_t max_image_size; /* 所有槽统一的负载上限,不包含任何传输封装。 */
bool initialized; /* 元数据结构及角色关系完整校验后才置位。 */
bool receiving_active; /* 仅本次 Begin 成功可写;恢复 RECEIVING 不会恢复写权限。 */
uint8_t wire[IEC60870_FIRMWARE_UPDATE_WIRE_SIZE]; /* 独立格式编码缓冲,不按结构体布局保存。 */
uint8_t scratch[IEC60870_FIRMWARE_UPDATE_SCRATCH_SIZE]; /* 同步读回工作区,不随映像增大。 */
} IEC60870_FirmwareUpdate_t;
/**
* 功能:校验参数和元数据,允许 store=&self->store。
* 输入参数:self——调用方持有的模块实例及当前状态;store——同步存储回调表及其上下文;max_image_size——允许的映像大小上限,单位字节。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:参数 INVALID 保留原实例; 恢复失败实例不可用。空介质恢复为 STATE_EMPTY,不制造初始运行映像。 max_image_size 非零;Init 只恢复,不调用
* install 或自动授权候选。 恢复成功(包括空介质)返回 OK;此时尚未复验各映像的实际字节。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Init(
IEC60870_FirmwareUpdate_t *self, const IEC60870_FirmwareUpdateStore_t *store,
uint32_t max_image_size);
/**
* 功能:只允许空库;调用方先把真实基线 payload 写入 slot。
* 输入参数:self——调用方持有的模块实例及当前状态;slot——映像物理槽号;descriptor——映像版本、大小和CRC描述。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;REJECTED表示映像内容或描述校验不通过;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:本接口同步并读回校验, 成功后持久登记为唯一 current,不创建假备份,也不调用 install。 descriptor 本次借用;内容/策略拒绝返回 REJECTED,仍保持空库角色。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Provision(
IEC60870_FirmwareUpdate_t *self, uint8_t slot,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor);
/**
* 功能:只在 STABLE 接受候选,选择 current/backup 之外的槽,先持久记录接收意图。
* 输入参数:self——调用方持有的模块实例及当前状态;descriptor——映像版本、大小和CRC描述。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:Write 要求连续 offset,Finish 同步并读回完整 payload;不能靠包头宣称验证。 重启不续传接收偏移,Prepare_Boot 将未授权
* RECEIVING/VERIFIED 候选取消。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Begin(
IEC60870_FirmwareUpdate_t *self, const IEC60870_FirmwareUpdateDescriptor_t *descriptor);
/**
* 功能:bytes 在同步调用期间借用,length 必须非零;OK 才推进易失接收偏移。
* 输入参数:self——调用方持有的模块实例及当前状态;offset——文件或映像内的字节偏移;bytes——字节数据;length——字节数。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:后端写失败可能已有部分副作用,核心闭锁而不猜测可继续的偏移。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Write(
IEC60870_FirmwareUpdate_t *self, uint32_t offset, const uint8_t *bytes, size_t length);
/**
* 功能:仅完整接收会话可结束。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;REJECTED表示映像内容或描述校验不通过;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:REJECTED 不闭锁,候选仍未验证,可由 Abort 撤销; 同步/读回 I/O 及元数据提交失败均闭锁,不能把完整接收当作持久成功。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Finish(IEC60870_FirmwareUpdate_t *self);
/**
* 功能:Abort 只取消未授权候选,EMPTY/STABLE 无候选时幂等返回 OK;Authorize 只 接受 VERIFIED,持久成功才返回 OK。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:任意不确定元数据提交均故障闭锁直到 Init,不能原样重试同一动作。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Abort(IEC60870_FirmwareUpdate_t *self);
/**
* 功能:只保存授权事实,不执行安装。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:外层负责证明授权来源及等待激活时点;核心 不接触协议 ACK,不能根据本接口参数自行判断业务授权是否成立。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Authorize(IEC60870_FirmwareUpdate_t *self);
/**
* 功能:每次真实启动/应用激活只调用一次,不是循环推进接口。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态;boot_image——仅OK时写入本次选择的启动映像描述。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:先保存安装/回退意图, 再调用幂等 install;AUTHORIZED/恢复的 INSTALLING 成功进入 TRIAL。 后一次启动见 TRIAL 即回退到旧 current;恢复的
* ROLLING_BACK 继续回退。 STABLE 校验并确保 current 已安装;未授权候选被取消。仅 OK 填写 boot_image, EMPTY 或失败保持输出;
* 输出对象不得与实例重叠。实际引导/跳转由返回后的 平台代码执行。已复验旧 current/backup 后,候选内容或读取失败均转入回退;
* 旧映像验证、元数据提交或安装失败则闭锁等待重新初始化。安装失败保留 调用时的持久状态,稳定启动修复失败仍是 STABLE,不会凭失败制造回退意图。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Prepare_Boot(
IEC60870_FirmwareUpdate_t *self, IEC60870_FirmwareUpdateDescriptor_t *boot_image);
/**
* 功能:只在 TRIAL 的实际健康检查通过后调用,持久轮转角色;不能以收到协议ACK 代替运行确认。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:本接口复验源槽,但不代替应用的运行/安装目标健康检查。 元数据提交失败可能已提交,须重新 Init 核对事实;调用阶段不符仍为 INVALID。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Confirm(IEC60870_FirmwareUpdate_t *self);
/**
* 功能:成功拷贝状态值,含故障位;NULL/未初始化返回 false 且输出不变。
* 输入参数:self——只读模块实例。
* 输出参数:status——仅成功时写入升级状态副本。
* 返回值:true表示已复制已初始化实例状态,false表示实例或输出无效。
* 说明:查询不验证映像字节、不推进状态,输出对象不得与实例重叠。
*/
bool IEC60870_FirmwareUpdate_Get_Status(const IEC60870_FirmwareUpdate_t *self,
IEC60870_FirmwareUpdateStatus_t *status);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_FIRMWARE_UPDATE_H */