204 lines
14 KiB
C
204 lines
14 KiB
C
/* 三映像槽升级核心:角色与动作意图持久化,介质及安装动作由平台回调实现。
|
||
* 纯 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 */
|