Files
STM32F4-Base/IEC60870-Slave/common/IEC60870_FirmwareUpdate.c
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

531 lines
30 KiB
C

/* 三槽升级事务:候选数据与元数据分别同步,安装意图先于平台副作用持久化。
* 核心只决定角色与恢复顺序;原子提交、实际安装及健康判定分别属于后端和应用。
* 所有入口串行使用同一实例,不在本模块内重试结果不确定的外部副作用。 */
#include "IEC60870_FirmwareUpdate.h"
#include <string.h>
/**
* 功能:内部调用只使用4或8字节字段;显式小端编码,不依赖对齐、主机字节序或填充。
* 输入参数:value——待处理数值;length——字节数。
* 输出参数:bytes——编码或复制结果的目标字节区。
* 返回值:无。
* 说明:调用方保证目标区域容量足够;逐字节编码不要求地址对齐。
*/
static void Put(uint8_t *bytes, uint64_t value, size_t length)
{
size_t i;
for (i = 0U; i < length; ++i) { bytes[i] = (uint8_t)(value >> (8U * i)); }
}
/**
* 功能:与 Put 对称;调用方先确认整份元数据长度,避免对半条记录解码。
* 输入参数:bytes——字节数据;length——字节数。
* 输出参数:无。
* 返回值:按小端还原的无符号整数。
* 说明:调用方保证源区域可读,不在此辅助入口进行长度检查。
*/
static uint64_t Get(const uint8_t *bytes, size_t length)
{
uint64_t value = 0U;
size_t i;
for (i = 0U; i < length; ++i) { value |= (uint64_t)bytes[i] << (8U * i); }
return value;
}
/**
* 功能:可分块续算,调用方提供全1初值并在最后取反;元数据和映像使用同一CRC规则。
* 输入参数:crc——当前未取反的CRC递推状态;bytes——字节数据;length——字节数。
* 输出参数:无。
* 返回值:更新后的未取反CRC状态。
* 说明:校验值只用于内容一致性检查,不提供来源认证。
*/
static uint32_t Crc_Update(uint32_t crc, const uint8_t *bytes, size_t length)
{
size_t i;
unsigned bit;
for (i = 0U; i < length; ++i) {
crc ^= bytes[i];
for (bit = 0U; bit < 8U; ++bit) {
crc = (crc >> 1) ^ ((crc & 1U) != 0U ? UINT32_C(0xedb88320) : 0U);
}
}
return crc;
}
/**
* 功能:这里只做结构准入,不读映像;实际 CRC 及产品许可由 Verify 分别核对。
* 输入参数:descriptor——映像版本、大小和CRC描述;maximum——允许的映像大小上限。
* 输出参数:无。
* 返回值:true表示版本、长度及上限合法,false表示映像描述不合法。
* 说明:只根据传入数据计算或判定,不改写输入对象。
*/
static bool Descriptor_Valid(const IEC60870_FirmwareUpdateDescriptor_t *descriptor,
uint32_t maximum)
{
return descriptor != NULL && descriptor->version != 0U &&
descriptor->size != 0U && descriptor->size <= maximum;
}
/**
* 功能:空闲槽描述必须规范化为全零,但介质中的旧负载可以留待后续 Begin 覆盖。
* 输入参数:descriptor——映像版本、大小和CRC描述。
* 输出参数:无。
* 返回值:true表示描述的版本、长度和CRC全部为0,false表示至少一项非零。
* 说明:只根据传入数据计算或判定,不改写输入对象。
*/
static bool Descriptor_Empty(const IEC60870_FirmwareUpdateDescriptor_t *descriptor)
{
return descriptor->version == 0U && descriptor->size == 0U && descriptor->crc == 0U;
}
/**
* 功能:角色引用决定哪些描述符有效;空闲槽必须编码为全零,拒绝旧元数据残留歧义。
* 输入参数:status——升级角色及状态快照;maximum——允许的映像大小上限。
* 输出参数:无。
* 返回值:true表示角色、状态及各槽描述一致,false表示持久元数据语义非法。
* 说明:非空状态必须有 current;只有 STABLE 没有 candidate。角色不得重复引用同槽, CRC 正确也不能跳过这些结构约束。本检查不承诺角色指向的负载仍然完好。
*/
static bool Status_Valid(const IEC60870_FirmwareUpdateStatus_t *status, uint32_t maximum)
{
bool used[IEC60870_FIRMWARE_UPDATE_SLOT_COUNT] = {false, false, false};
uint8_t roles[3];
size_t i;
roles[0] = status->current_slot; roles[1] = status->backup_slot; roles[2] = status->candidate_slot;
if (status->state < IEC60870_FIRMWARE_UPDATE_STATE_EMPTY ||
status->state > IEC60870_FIRMWARE_UPDATE_ROLLING_BACK) { return false; }
if (status->state == IEC60870_FIRMWARE_UPDATE_STATE_EMPTY) {
if (status->transaction_id != 0U || roles[0] != IEC60870_FIRMWARE_UPDATE_NO_SLOT ||
roles[1] != IEC60870_FIRMWARE_UPDATE_NO_SLOT || roles[2] != IEC60870_FIRMWARE_UPDATE_NO_SLOT) {
return false;
}
} else if (status->transaction_id == 0U || roles[0] == IEC60870_FIRMWARE_UPDATE_NO_SLOT ||
((status->state == IEC60870_FIRMWARE_UPDATE_STABLE) !=
(roles[2] == IEC60870_FIRMWARE_UPDATE_NO_SLOT))) { return false; }
for (i = 0U; i < 3U; ++i) {
uint8_t slot = roles[i];
if (slot == IEC60870_FIRMWARE_UPDATE_NO_SLOT) { continue; }
if (slot >= IEC60870_FIRMWARE_UPDATE_SLOT_COUNT || used[slot] ||
!Descriptor_Valid(&status->images[slot], maximum)) { return false; }
used[slot] = true;
}
for (i = 0U; i < IEC60870_FIRMWARE_UPDATE_SLOT_COUNT; ++i) {
if (!used[i] && !Descriptor_Empty(&status->images[i])) { return false; }
}
return true;
}
/**
* 功能:只锁存内存故障,不写回介质或清掉角色;失败回调可能已完成持久副作用, 必须留给 Init 重读事实。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:事务号耗尽不经过这里,因为没有不确定的 I/O。
*/
static IEC60870_FirmwareUpdateResult_t Fault(IEC60870_FirmwareUpdate_t *self)
{
self->status.faulted = true;
return IEC60870_FIRMWARE_UPDATE_ERROR;
}
/**
* 功能:60字节固定布局:FWU1[0..3]、版本[4]、状态[5]、三角色[6..8]、保留[9..11]、 事务号LE64[12..19]、三组version/size/crc
* LE32[20..55]、前56字节CRC[56..59]。
* 输入参数:self——调用方持有的模块实例及当前状态;next——待提交的下一份升级状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:received_size 是易失接收进度,不用于断电续传,也不写入元数据。 next 先编码并交后端提交,明确成功才替换内存状态;false 时保留旧快照并闭锁,
* 不能从旧快照推断磁盘最终停在哪一版。后端自己的 bank 代次不属于本格式。
*/
static IEC60870_FirmwareUpdateResult_t Commit(IEC60870_FirmwareUpdate_t *self,
const IEC60870_FirmwareUpdateStatus_t *next)
{
size_t i;
uint8_t *wire = self->wire;
memset(wire, 0, sizeof(self->wire));
memcpy(wire, "FWU1", 4U); wire[4] = 1U; wire[5] = (uint8_t)next->state;
wire[6] = next->current_slot; wire[7] = next->backup_slot; wire[8] = next->candidate_slot;
Put(wire + 12U, next->transaction_id, 8U);
for (i = 0U; i < IEC60870_FIRMWARE_UPDATE_SLOT_COUNT; ++i) {
Put(wire + 20U + i * 12U, next->images[i].version, 4U);
Put(wire + 24U + i * 12U, next->images[i].size, 4U);
Put(wire + 28U + i * 12U, next->images[i].crc, 4U);
}
Put(wire + 56U, ~Crc_Update(UINT32_MAX, wire, 56U), 4U);
if (!self->store.metadata_commit(self->store.context, wire, sizeof(self->wire))) {
return Fault(self);
}
self->status = *next;
return IEC60870_FIRMWARE_UPDATE_OK;
}
/**
* 功能:确认真实槽内容,CRC不匹配或产品策略拒绝返回REJECTED;I/O失败为ERROR。
* 输入参数:self——调用方持有的模块实例及当前状态;slot——映像物理槽号;descriptor——映像版本、大小和CRC描述。
* 输出参数:self——复用scratch读取缓冲;不改变持久角色或故障位。
* 返回值:OK表示操作完成;REJECTED表示映像内容或描述校验不通过;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:是否转故障或回退由调用路径决定,候选坏不能阻止使用完好的旧current回退。 仅核对描述指定长度的字节,额外尾部/签名等由可选 validate 检查;CRC 匹配
* 之前不会调用产品许可回调。此函数本身不改变持久状态或故障位。
*/
static IEC60870_FirmwareUpdateResult_t Verify(IEC60870_FirmwareUpdate_t *self,
uint8_t slot, const IEC60870_FirmwareUpdateDescriptor_t *descriptor)
{
uint32_t offset = 0U, crc = UINT32_MAX;
while (offset < descriptor->size) {
size_t length = descriptor->size - offset;
if (length > sizeof(self->scratch)) { length = sizeof(self->scratch); }
if (!self->store.image_read(self->store.context, slot, offset, self->scratch, length)) {
return IEC60870_FIRMWARE_UPDATE_ERROR;
}
crc = Crc_Update(crc, self->scratch, length);
offset += (uint32_t)length;
}
if (~crc != descriptor->crc || (self->store.validate != NULL &&
!self->store.validate(self->store.context, slot, descriptor))) {
return IEC60870_FIRMWARE_UPDATE_REJECTED;
}
return IEC60870_FIRMWARE_UPDATE_OK;
}
/**
* 功能:重用空闲槽前复验所有已确认角色,避免较旧的有效元数据指向已轮转槽时 静默接纳错误映像;当前或备份不可用都须显式故障,不选择“看起来更新”的槽。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——复用scratch读取缓冲;已确认角色不可用时锁存故障。
* 返回值:OK表示操作完成;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:Begin、Prepare_Boot、Confirm 共用该检查,保证覆盖、安装和角色提升均有可信旧版。
*/
static IEC60870_FirmwareUpdateResult_t Verify_Confirmed(IEC60870_FirmwareUpdate_t *self)
{
uint8_t current = self->status.current_slot, backup = self->status.backup_slot;
if (Verify(self, current, &self->status.images[current]) != IEC60870_FIRMWARE_UPDATE_OK ||
(backup != IEC60870_FIRMWARE_UPDATE_NO_SLOT &&
Verify(self, backup, &self->status.images[backup]) != IEC60870_FIRMWARE_UPDATE_OK)) {
return Fault(self);
}
return IEC60870_FIRMWARE_UPDATE_OK;
}
/**
* 功能:仅修改待提交的状态副本;调用方保证 candidate 有效。
* 输入参数:status——升级角色及状态快照。
* 输出参数:status——移除候选引用后的角色快照。
* 返回值:无。
* 说明:取消及回退共用此步骤, 不擦除任何负载、不移动 current/backup,事务号也不倒退或复用。
*/
static void Remove_Candidate(IEC60870_FirmwareUpdateStatus_t *status)
{
memset(&status->images[status->candidate_slot], 0, sizeof(status->images[0]));
status->candidate_slot = IEC60870_FIRMWARE_UPDATE_NO_SLOT;
status->received_size = 0U;
status->state = IEC60870_FIRMWARE_UPDATE_STABLE;
}
/**
* 功能:初始化先验证回调表,再清实例;支持从实例自身的 store 重新初始化。
* 输入参数:self——调用方持有的模块实例及当前状态;store——同步存储回调表及其上下文;max_image_size——允许的映像大小上限,单位字节。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:元数据在局部状态中完整解码,只有全部检查通过才公布 initialized。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Init(
IEC60870_FirmwareUpdate_t *self, const IEC60870_FirmwareUpdateStore_t *store,
uint32_t max_image_size)
{
IEC60870_FirmwareUpdateStore_t saved_store;
IEC60870_FirmwareUpdateStatus_t status;
IEC60870_FirmwareUpdateResult_t result;
size_t size = 0U, i;
if (self == NULL || store == NULL || max_image_size == 0U ||
store->metadata_read == NULL || store->metadata_commit == NULL ||
store->image_begin == NULL || store->image_write == NULL || store->image_read == NULL ||
store->image_sync == NULL || store->install == NULL) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
saved_store = *store;
memset(self, 0, sizeof(*self)); self->store = saved_store; self->max_image_size = max_image_size;
memset(&status, 0, sizeof(status));
status.current_slot = status.backup_slot = status.candidate_slot = IEC60870_FIRMWARE_UPDATE_NO_SLOT;
result = self->store.metadata_read(self->store.context, self->wire, sizeof(self->wire), &size);
if (result == IEC60870_FIRMWARE_UPDATE_OK) {
if (size != sizeof(self->wire) || memcmp(self->wire, "FWU1", 4U) != 0 ||
self->wire[4] != 1U || self->wire[9] != 0U || self->wire[10] != 0U || self->wire[11] != 0U ||
Get(self->wire + 56U, 4U) != (uint64_t)~Crc_Update(UINT32_MAX, self->wire, 56U)) {
return Fault(self);
}
status.state = (IEC60870_FirmwareUpdateState_t)self->wire[5];
status.current_slot = self->wire[6]; status.backup_slot = self->wire[7]; status.candidate_slot = self->wire[8];
status.transaction_id = Get(self->wire + 12U, 8U);
for (i = 0U; i < IEC60870_FIRMWARE_UPDATE_SLOT_COUNT; ++i) {
status.images[i].version = (uint32_t)Get(self->wire + 20U + i * 12U, 4U);
status.images[i].size = (uint32_t)Get(self->wire + 24U + i * 12U, 4U);
status.images[i].crc = (uint32_t)Get(self->wire + 28U + i * 12U, 4U);
}
if (!Status_Valid(&status, max_image_size)) { return Fault(self); }
} else if (result != IEC60870_FIRMWARE_UPDATE_EMPTY) { return Fault(self); }
/* 接收偏移及 receiving_active 不从介质恢复,掉电前的未授权文件不能续写或自动授权。 */
self->status = status; self->initialized = true;
return IEC60870_FIRMWARE_UPDATE_OK;
}
/**
* 功能:首次基线由调用方提供真实负载;登记前同步并复验,绝不凭描述构造假 current。
* 输入参数:self——调用方持有的模块实例及当前状态;slot——映像物理槽号;descriptor——映像版本、大小和CRC描述。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;REJECTED表示映像内容或描述校验不通过;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:先同步并复验已有负载,再持久登记初始current;不负责接收该负载。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Provision(
IEC60870_FirmwareUpdate_t *self, uint8_t slot,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor)
{
IEC60870_FirmwareUpdateStatus_t next;
IEC60870_FirmwareUpdateDescriptor_t saved;
IEC60870_FirmwareUpdateResult_t result;
if (self == NULL) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
if (!self->initialized || self->status.faulted) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
if (self->status.state != IEC60870_FIRMWARE_UPDATE_STATE_EMPTY ||
slot >= IEC60870_FIRMWARE_UPDATE_SLOT_COUNT || !Descriptor_Valid(descriptor, self->max_image_size)) {
return IEC60870_FIRMWARE_UPDATE_INVALID;
}
saved = *descriptor;
if (!self->store.image_sync(self->store.context, slot)) { return Fault(self); }
result = Verify(self, slot, &saved);
if (result == IEC60870_FIRMWARE_UPDATE_ERROR) { return Fault(self); }
if (result != IEC60870_FIRMWARE_UPDATE_OK) { return result; }
next = self->status; next.state = IEC60870_FIRMWARE_UPDATE_STABLE;
next.current_slot = slot; next.images[slot] = saved; next.transaction_id = 1U;
return Commit(self, &next);
}
/**
* 功能:确认保留角色完好后才选空闲槽,接收意图必须先于清槽持久化。
* 输入参数:self——调用方持有的模块实例及当前状态;descriptor——映像版本、大小和CRC描述。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:因而 image_begin 失败也留下可识别的 RECEIVING,重启按未授权候选取消。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Begin(
IEC60870_FirmwareUpdate_t *self, const IEC60870_FirmwareUpdateDescriptor_t *descriptor)
{
IEC60870_FirmwareUpdateStatus_t next;
IEC60870_FirmwareUpdateDescriptor_t saved;
uint8_t slot;
if (self == NULL) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
if (!self->initialized || self->status.faulted) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
if (self->status.state != IEC60870_FIRMWARE_UPDATE_STABLE ||
!Descriptor_Valid(descriptor, self->max_image_size)) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
saved = *descriptor;
/* 序号耗尽不进行介质操作,也不闭锁仍可正常启动的已确认版本。 */
if (self->status.transaction_id == UINT64_MAX) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
if (Verify_Confirmed(self) != IEC60870_FIRMWARE_UPDATE_OK) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
for (slot = 0U; slot < IEC60870_FIRMWARE_UPDATE_SLOT_COUNT; ++slot) {
if (slot != self->status.current_slot && slot != self->status.backup_slot) { break; }
}
next = self->status; next.candidate_slot = slot; next.images[slot] = saved;
next.state = IEC60870_FIRMWARE_UPDATE_RECEIVING; next.received_size = 0U; ++next.transaction_id;
if (Commit(self, &next) != IEC60870_FIRMWARE_UPDATE_OK) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
if (!self->store.image_begin(self->store.context, slot, saved.size)) { return Fault(self); }
self->receiving_active = true;
return IEC60870_FIRMWARE_UPDATE_OK;
}
/**
* 功能:顺序写入是单会话契约,不接受覆盖重传或跨段留洞;外层协议负责去重。
* 输入参数:self——调用方持有的模块实例及当前状态;offset——文件或映像内的字节偏移;bytes——字节数据;length——字节数。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:长度用剩余空间比较以避免 offset+length 回绕;成功后才累计易失进度。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Write(
IEC60870_FirmwareUpdate_t *self, uint32_t offset, const uint8_t *bytes, size_t length)
{
uint8_t slot;
if (self == NULL) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
if (!self->initialized || self->status.faulted) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
if (self->status.state != IEC60870_FIRMWARE_UPDATE_RECEIVING || !self->receiving_active ||
bytes == NULL || length == 0U || offset != self->status.received_size) {
return IEC60870_FIRMWARE_UPDATE_INVALID;
}
slot = self->status.candidate_slot;
if (offset > self->status.images[slot].size || length > self->status.images[slot].size - offset) {
return IEC60870_FIRMWARE_UPDATE_INVALID;
}
if (!self->store.image_write(self->store.context, slot, offset, bytes, length)) { return Fault(self); }
self->status.received_size += (uint32_t)length;
return IEC60870_FIRMWARE_UPDATE_OK;
}
/**
* 功能:接收完整不等于文件可安装:先持久同步,再读真实槽,最后提交 VERIFIED。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;REJECTED表示映像内容或描述校验不通过;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:内容拒绝允许调用方撤销候选;I/O 或提交不确定则只能重新初始化恢复。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Finish(IEC60870_FirmwareUpdate_t *self)
{
IEC60870_FirmwareUpdateResult_t result;
IEC60870_FirmwareUpdateStatus_t next;
uint8_t slot;
if (self == NULL) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
if (!self->initialized || self->status.faulted) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
if (self->status.state != IEC60870_FIRMWARE_UPDATE_RECEIVING || !self->receiving_active) {
return IEC60870_FIRMWARE_UPDATE_INVALID;
}
slot = self->status.candidate_slot;
if (self->status.received_size != self->status.images[slot].size) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
if (!self->store.image_sync(self->store.context, slot)) { return Fault(self); }
result = Verify(self, slot, &self->status.images[slot]);
if (result == IEC60870_FIRMWARE_UPDATE_ERROR) { return Fault(self); }
if (result != IEC60870_FIRMWARE_UPDATE_OK) { return result; }
next = self->status; next.state = IEC60870_FIRMWARE_UPDATE_VERIFIED;
result = Commit(self, &next);
if (result == IEC60870_FIRMWARE_UPDATE_OK) { self->receiving_active = false; }
return result;
}
/**
* 功能:只撤销尚未交给安装任务的角色引用,绝不把 AUTHORIZED 以后的事实降格为接收取消。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:取消通过新的持久元数据发布;提交结果不确定时锁存故障。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Abort(IEC60870_FirmwareUpdate_t *self)
{
IEC60870_FirmwareUpdateStatus_t next;
IEC60870_FirmwareUpdateResult_t result;
if (self == NULL) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
if (!self->initialized || self->status.faulted) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
if (self->status.state == IEC60870_FIRMWARE_UPDATE_STATE_EMPTY ||
self->status.state == IEC60870_FIRMWARE_UPDATE_STABLE) { return IEC60870_FIRMWARE_UPDATE_OK; }
if (self->status.state != IEC60870_FIRMWARE_UPDATE_RECEIVING &&
self->status.state != IEC60870_FIRMWARE_UPDATE_VERIFIED) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
next = self->status; Remove_Candidate(&next);
result = Commit(self, &next);
if (result == IEC60870_FIRMWARE_UPDATE_OK) { self->receiving_active = false; }
return result;
}
/**
* 功能:外层已取得业务授权;这里只把授权持久化,安装留待一次明确的启动/激活入口。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:成功只代表授权状态已经持久提交,不表示安装已完成。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Authorize(IEC60870_FirmwareUpdate_t *self)
{
IEC60870_FirmwareUpdateStatus_t next;
if (self == NULL) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
if (!self->initialized || self->status.faulted) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
if (self->status.state != IEC60870_FIRMWARE_UPDATE_VERIFIED) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
next = self->status; next.state = IEC60870_FIRMWARE_UPDATE_AUTHORIZED;
return Commit(self, &next);
}
/**
* 功能:每次调用代表一次启动决策:恢复未完成安装,或把上次未确认试运行回退。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态;boot_image——仅OK时写入本次选择的启动映像描述。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:先复验 current/backup,才能在候选损坏时安全降级;任何成功输出都晚于所需提交。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Prepare_Boot(
IEC60870_FirmwareUpdate_t *self, IEC60870_FirmwareUpdateDescriptor_t *boot_image)
{
IEC60870_FirmwareUpdateStatus_t next;
IEC60870_FirmwareUpdateResult_t result;
uint8_t slot;
if (self == NULL || boot_image == NULL) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
if (!self->initialized || self->status.faulted) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
if (self->status.state == IEC60870_FIRMWARE_UPDATE_STATE_EMPTY) { return IEC60870_FIRMWARE_UPDATE_EMPTY; }
if (Verify_Confirmed(self) != IEC60870_FIRMWARE_UPDATE_OK) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
if (self->status.state == IEC60870_FIRMWARE_UPDATE_RECEIVING ||
self->status.state == IEC60870_FIRMWARE_UPDATE_VERIFIED) {
if (IEC60870_FirmwareUpdate_Abort(self) != IEC60870_FIRMWARE_UPDATE_OK) {
return IEC60870_FIRMWARE_UPDATE_ERROR;
}
}
if (self->status.state == IEC60870_FIRMWARE_UPDATE_AUTHORIZED) {
/* 安装可能改变派生目标;先落意图,掉电后才知道必须以同一任务重做。 */
next = self->status; next.state = IEC60870_FIRMWARE_UPDATE_INSTALLING;
if (Commit(self, &next) != IEC60870_FIRMWARE_UPDATE_OK) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
}
if (self->status.state == IEC60870_FIRMWARE_UPDATE_INSTALLING) {
slot = self->status.candidate_slot;
result = Verify(self, slot, &self->status.images[slot]);
if (result == IEC60870_FIRMWARE_UPDATE_OK) {
if (!self->store.install(self->store.context, slot, &self->status.images[slot], self->status.transaction_id)) {
return Fault(self);
}
next = self->status; next.state = IEC60870_FIRMWARE_UPDATE_TRIAL;
if (Commit(self, &next) != IEC60870_FIRMWARE_UPDATE_OK) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
/* 这里立即返回,不能让本次刚进入的 TRIAL 落入“上次未确认”分支。 */
*boot_image = self->status.images[slot];
return IEC60870_FIRMWARE_UPDATE_OK;
}
/* 候选缺失、读失败、CRC或产品策略拒绝均不信任候选;旧current/backup
* 已独立复验,先持久化回退意图再恢复它们,无需继续读取受损候选。 */
next = self->status; next.state = IEC60870_FIRMWARE_UPDATE_ROLLING_BACK;
if (Commit(self, &next) != IEC60870_FIRMWARE_UPDATE_OK) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
} else if (self->status.state == IEC60870_FIRMWARE_UPDATE_TRIAL) {
/* 本次入口已是 TRIAL,说明另一次启动没有得到确认;原 backup 仍需保留。 */
next = self->status; next.state = IEC60870_FIRMWARE_UPDATE_ROLLING_BACK;
if (Commit(self, &next) != IEC60870_FIRMWARE_UPDATE_OK) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
}
/* STABLE 也执行幂等安装,以修复丢失的派生目标;失败保持 STABLE 并闭锁。
* ROLLING_BACK 必须先恢复目标成功,随后才能释放候选角色并提交 STABLE。 */
slot = self->status.current_slot;
if (!self->store.install(self->store.context, slot, &self->status.images[slot], self->status.transaction_id)) {
return Fault(self);
}
if (self->status.state == IEC60870_FIRMWARE_UPDATE_ROLLING_BACK) {
next = self->status; Remove_Candidate(&next);
if (Commit(self, &next) != IEC60870_FIRMWARE_UPDATE_OK) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
}
*boot_image = self->status.images[slot];
return IEC60870_FIRMWARE_UPDATE_OK;
}
/**
* 功能:健康结论由应用给出;核心再复验源槽并原子轮转角色,不重新执行安装。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的角色、接收进度及故障状态。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:更早备份只清描述,不擦负载;下次 Begin 才可重用那个物理槽。
*/
IEC60870_FirmwareUpdateResult_t IEC60870_FirmwareUpdate_Confirm(IEC60870_FirmwareUpdate_t *self)
{
IEC60870_FirmwareUpdateStatus_t next;
uint8_t slot;
size_t i;
if (self == NULL) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
if (!self->initialized || self->status.faulted) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
if (self->status.state != IEC60870_FIRMWARE_UPDATE_TRIAL) { return IEC60870_FIRMWARE_UPDATE_INVALID; }
slot = self->status.candidate_slot;
if (Verify_Confirmed(self) != IEC60870_FIRMWARE_UPDATE_OK ||
Verify(self, slot, &self->status.images[slot]) != IEC60870_FIRMWARE_UPDATE_OK) { return Fault(self); }
next = self->status;
next.backup_slot = next.current_slot; next.current_slot = slot;
next.candidate_slot = IEC60870_FIRMWARE_UPDATE_NO_SLOT;
next.state = IEC60870_FIRMWARE_UPDATE_STABLE; next.received_size = 0U;
for (i = 0U; i < IEC60870_FIRMWARE_UPDATE_SLOT_COUNT; ++i) {
if (i != next.current_slot && i != next.backup_slot) { memset(&next.images[i], 0, sizeof(next.images[i])); }
}
return Commit(self, &next);
}
/**
* 功能:允许读取已初始化但故障闭锁的快照,便于诊断;它不能替代重读元数据恢复。
* 输入参数:self——只读模块实例。
* 输出参数:status——仅成功时写入升级状态副本。
* 返回值:true表示已复制已初始化实例状态,false表示实例或输出无效。
* 说明:只复制RAM状态,不访问存储或执行安装;faulted实例仍可诊断。
*/
bool IEC60870_FirmwareUpdate_Get_Status(const IEC60870_FirmwareUpdate_t *self,
IEC60870_FirmwareUpdateStatus_t *status)
{
if (self == NULL || status == NULL || !self->initialized) { return false; }
*status = self->status;
return true;
}