531 lines
30 KiB
C
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;
|
|
}
|