/* 三槽升级事务:候选数据与元数据分别同步,安装意图先于平台副作用持久化。 * 核心只决定角色与恢复顺序;原子提交、实际安装及健康判定分别属于后端和应用。 * 所有入口串行使用同一实例,不在本模块内重试结果不确定的外部副作用。 */ #include "IEC60870_FirmwareUpdate.h" #include /** * 功能:内部调用只使用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; }