Files
STM32F4-Base/IEC60870-Slave/examples/iec104_example_upgrade.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

859 lines
44 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.
/* Windows 实文件升级后端。源槽只存负载,元数据决定 current/backup/candidate。
* dtu 与 dtu-1 是由角色派生的安装文件;安装先备份再替换,不执行任何映像。
* 全部句柄及工作缓冲由调用方对象拥有,平台调用和核心调用须在同一串行上下文。 */
#include "iec104_example_upgrade.h"
#include <stdio.h>
#include <string.h>
#include <windows.h>
/* upgrade.store:32 字节固定头,其后两个 92 字节 bank,总上限 216 字节。
* 文件头 0..11 为布局标识及 NUL,12..15 为零,16/20/24 分别为核心记录长度、
* bank 跨度和槽数,28 保存前 28 字节 CRC。整数显式小端,不保存 C 结构体。
* bank 头:0 魔数,4 载荷长度,8 uint64 代次,16 载荷 CRC,20 头前 20 字节 CRC,
* 24 提交标记,28 保留零;32 起是核心 60 字节记录。标记不在头 CRC 范围内,
* 可独立清除/发布;物理代次只决定元数据副本先后,不等于升级事务身份。 */
#define STORE_HEADER 32U
#define BANK_HEADER 32U
#define BANK_SIZE (BANK_HEADER + IEC60870_FIRMWARE_UPDATE_WIRE_SIZE)
#define STORE_SIZE (STORE_HEADER + 2U * BANK_SIZE)
#define BANK_COMMITTED UINT32_C(0x54494d43)
/* 钩子只在真实 Flush 或替换完成后报告失败;不能代替物理掉电验收。
* 1..3 是元数据三阶段,4 是映像同步,5/6 和 7/8 是备份/当前文件同步及替换。
* 失败发生在结果交回之前,介质可能已更新;生产编译没有故障注入入口。 */
#ifdef IEC104_EXAMPLE_UPGRADE_TEST
/**
* 功能:在真实持久操作完成后提供测试中断判定。
* 输入参数:point——已完成的同步或替换阶段编号。
* 输出参数:无输出参数;测试实现更新故障注入计数。
* 返回值:true允许继续,false在指定阶段模拟中断。
* 说明:仅测试宏启用时链接;真实写入已发生,返回false不撤销已同步内容。
*/
extern bool Example_Upgrade_Test_Continue(unsigned point);
#else
#define Example_Upgrade_Test_Continue(point) true
#endif
/* 三个固定物理文件不跟随角色改名;无角色槽可残留旧字节,不能据文件存在推断资格。 */
static const char *const slot_names[IEC60870_FIRMWARE_UPDATE_SLOT_COUNT] = {
"upgrade-slot0.bin", "upgrade-slot1.bin", "upgrade-slot2.bin"
};
/**
* 功能:真实打开安装目标读回全部字节,不能仅凭源槽 CRC 或协议准备成功宣称安装健康。
* 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;descriptor——固件映像描述。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:安装目标的长度、内容CRC和描述一致时返回true,否则返回false。
* 说明:句柄仅在本次验证期间持有;长度、短读或 CRC 不符均 false,不在此修改核心状态。
*/
static bool Installed_Valid(ExampleUpgrade *self, const char *name,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor);
/**
* 功能:从字节缓冲解码32位小端整数。
* 输入参数:bytes——字节数据缓冲。
* 输出参数:无独立输出参数。
* 返回值:解码后的32位无符号整数。
* 说明:按字节解码,允许输入未对齐,避免依赖 Windows 整数或结构体布局。
*/
static uint32_t Get32(const uint8_t *bytes)
{
return (uint32_t)bytes[0] | ((uint32_t)bytes[1] << 8) |
((uint32_t)bytes[2] << 16) | ((uint32_t)bytes[3] << 24);
}
/**
* 功能:将32位整数写成小端字节序。
* 输入参数:bytes——字节数据缓冲;value——本次待处理的数值。
* 输出参数:bytes——字节数据缓冲。
* 返回值:无。
* 说明:调用方保证四字节空间;各字段使用相同的小端编码。
*/
static void Put32(uint8_t *bytes, uint32_t value)
{
unsigned i;
for (i = 0U; i < 4U; ++i) { bytes[i] = (uint8_t)(value >> (8U * i)); }
}
/**
* 功能:从字节缓冲解码64位小端整数。
* 输入参数:bytes——字节数据缓冲。
* 输出参数:无独立输出参数。
* 返回值:解码后的64位无符号整数。
* 说明:高半字先扩为 uint64 再移位,兼容 32 位编译器。
*/
static uint64_t Get64(const uint8_t *bytes)
{
return Get32(bytes) | ((uint64_t)Get32(bytes + 4U) << 32);
}
/**
* 功能:将64位整数写成小端字节序。
* 输入参数:bytes——字节数据缓冲;value——本次待处理的数值。
* 输出参数:bytes——字节数据缓冲。
* 返回值:无。
* 说明:代次完整保存为八字节,不能截断成宿主 unsigned long。
*/
static void Put64(uint8_t *bytes, uint64_t value)
{
Put32(bytes, (uint32_t)value); Put32(bytes + 4U, (uint32_t)(value >> 32));
}
/**
* 功能:更新可跨片段续算的CRC-32中间值。
* 输入参数:crc——跨片段CRC累积值;bytes——字节数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:无独立输出参数。
* 返回值:本片段处理后的CRC中间状态,尚未做末尾取反。
* 说明:返回尚未最终取反的 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-32校验值。
* 输入参数:bytes——字节数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:无独立输出参数。
* 返回值:完成初值处理和末尾取反后的CRC-32值。
* 说明:一次性元数据校验使用相同初值和最终取反;CRC 不提供来源鉴权。
*/
static uint32_t Crc(const uint8_t *bytes, size_t length)
{
return ~Crc_Update(UINT32_MAX, bytes, length);
}
/**
* 功能:名称仅来自内部固定表,不把线上文件名拼入宿主路径。
* 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;path——调用方提供的路径缓冲。
* 输出参数:path——调用方提供的路径缓冲。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:无。
*/
static bool Path(const ExampleUpgrade *self, const char *name, char *path)
{
int length = snprintf(path, MAX_PATH, "%s/%s", self->parent, name);
return length > 0 && length < MAX_PATH;
}
/**
* 功能:将文件读写位置移动到指定绝对偏移。
* 输入参数:file——已打开的同步文件句柄;offset——从起点计算的字节偏移。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:每次访问显式定位;句柄文件指针共享,因此后端不允许并发调用。
*/
static bool Seek(HANDLE file, uint32_t offset)
{
LARGE_INTEGER position;
position.QuadPart = offset;
return SetFilePointerEx(file, position, NULL, FILE_BEGIN) != 0;
}
/**
* 功能:定位并完整写入指定字节段。
* 输入参数:file——已打开的同步文件句柄;offset——从起点计算的字节偏移;bytes——字节数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:同时检查系统返回值与实际字节数;完整写入仍须由上层明确执行持久同步。
*/
static bool Write_At(HANDLE file, uint32_t offset, const uint8_t *bytes, size_t length)
{
DWORD done = 0U;
return length <= MAXDWORD && Seek(file, offset) &&
WriteFile(file, bytes, (DWORD)length, &done, NULL) && done == length;
}
/**
* 功能:定位并完整读出指定字节段。
* 输入参数:file——已打开的同步文件句柄;offset——从起点计算的字节偏移;bytes——字节数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:bytes——字节数据缓冲。
* 返回值:true表示指定范围的数据已完整读出;false表示范围非法、读取失败或短读。
* 说明:短读也失败;失败可能已覆盖输出前缀,调用者必须丢弃该次数据。
*/
static bool Read_At(HANDLE file, uint32_t offset, uint8_t *bytes, size_t length)
{
DWORD done = 0U;
return length <= MAXDWORD && Seek(file, offset) &&
ReadFile(file, bytes, (DWORD)length, &done, NULL) && done == length;
}
/**
* 功能:读取并核验指定持久副本的提交标记、载荷及代次。
* 输入参数:self——调用方持有的模块实例;bank——双副本编号0或1;generation——持久提交代次回写位置。
* 输出参数:generation——持久提交代次回写位置。
* 返回值:1表示有效提交,0表示未提交,-1表示损坏,-2表示系统读取错误。
* 说明:0 仅表示无提交;损坏为 -1,系统读取失败为 -2,不能据此格式化档案。
* 清零标记的残缺候选允许忽略;有效标记下的短头、短载荷和 CRC 错不能当空。
* generation 仅在返回 1 后有效;无外部账本时,整段被删或标记变零可能与未提交
* 不可区分,这不是任意介质破坏均可恢复的承诺。
*/
static int Read_Bank(ExampleUpgrade *self, unsigned bank, uint64_t *generation)
{
uint8_t *bytes = self->banks[bank];
DWORD done = 0U;
memset(bytes, 0, BANK_SIZE);
if (!Seek((HANDLE)self->storage, STORE_HEADER + bank * BANK_SIZE) ||
!ReadFile((HANDLE)self->storage, bytes, BANK_SIZE, &done, NULL)) { return -2; }
if (done == 0U || (done >= 28U && Get32(bytes + 24U) == 0U)) { return 0; }
if (done != BANK_SIZE || memcmp(bytes, "UPB1", 4U) != 0 ||
Get32(bytes + 4U) != IEC60870_FIRMWARE_UPDATE_WIRE_SIZE ||
Get32(bytes + 20U) != Crc(bytes, 20U) || Get32(bytes + 24U) != BANK_COMMITTED ||
Get32(bytes + 28U) != 0U ||
Get32(bytes + 16U) != Crc(bytes + BANK_HEADER, IEC60870_FIRMWARE_UPDATE_WIRE_SIZE)) {
return -1;
}
*generation = Get64(bytes + 8U);
return *generation == 0U ? -1 : 1;
}
/**
* 功能:恢复已提交的固件元数据。
* 输入参数:context——调用方注册的回调上下文;bytes——字节数据缓冲;capacity——目标缓冲容量;size——实际字节数回写位置。
* 输出参数:bytes——字节数据缓冲;size——实际字节数回写位置。
* 返回值:OK表示元数据已恢复,EMPTY表示两副本均无提交,ERROR表示读取、校验或容量失败。
* 说明:选较大有效代次;同代次只有内容一致才可接纳,两份都未提交才是 EMPTY。
* 任一副本损坏或系统读取失败即报错,不退选另一份旧元数据。
* 选定载荷仍须由核心复验角色,并在使用时核验源槽;只在 OK 时复制载荷及 size。
*/
static IEC60870_FirmwareUpdateResult_t Metadata_Read(void *context,
uint8_t *bytes, size_t capacity, size_t *size)
{
ExampleUpgrade *self = context;
uint64_t generations[2] = {0U, 0U};
int first = Read_Bank(self, 0U, &generations[0]);
int second = Read_Bank(self, 1U, &generations[1]);
unsigned winner;
if (bytes == NULL || size == NULL || capacity < IEC60870_FIRMWARE_UPDATE_WIRE_SIZE ||
first < 0 || second < 0) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
if (first != 1 && second != 1) {
return first == 0 && second == 0 ? IEC60870_FIRMWARE_UPDATE_EMPTY : IEC60870_FIRMWARE_UPDATE_ERROR;
}
if (first == 1 && second == 1 && generations[0] == generations[1] &&
memcmp(self->banks[0] + BANK_HEADER, self->banks[1] + BANK_HEADER,
IEC60870_FIRMWARE_UPDATE_WIRE_SIZE) != 0) { return IEC60870_FIRMWARE_UPDATE_ERROR; }
winner = second == 1 && (first != 1 || generations[1] > generations[0]) ? 1U : 0U;
memcpy(bytes, self->banks[winner] + BANK_HEADER, IEC60870_FIRMWARE_UPDATE_WIRE_SIZE);
*size = IEC60870_FIRMWARE_UPDATE_WIRE_SIZE;
return IEC60870_FIRMWARE_UPDATE_OK;
}
/**
* 功能:持久提交固件元数据的下一代副本。
* 输入参数:context——调用方注册的回调上下文;bytes——字节数据缓冲;size——本次数据的字节数。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:先清标记并同步,再写候选并同步,最后发布标记并同步。false 可能已经提交;
* 核心必须闭锁后重新扫描,不能重用内存中的旧状态继续动作。
* 任一副本损坏或读取失败均拒绝写入;永不覆盖当前最新有效 bank,代次耗尽拒绝。
* 字节指针只借用本次调用,不能用旧副本重建代次后覆盖损坏证据。
* 三阶段保证边界依赖系统与介质兑现 Flush,跨两个安装别名并不是一个文件事务。
*/
static bool Metadata_Commit(void *context, const uint8_t *bytes, size_t size)
{
ExampleUpgrade *self = context;
uint64_t generations[2] = {0U, 0U}, next;
int first = Read_Bank(self, 0U, &generations[0]);
int second = Read_Bank(self, 1U, &generations[1]);
unsigned target;
uint32_t offset;
uint8_t marker[4] = {0U, 0U, 0U, 0U};
uint8_t *candidate;
HANDLE file = (HANDLE)self->storage;
if (bytes == NULL || size != IEC60870_FIRMWARE_UPDATE_WIRE_SIZE ||
first < 0 || second < 0) { return false; }
if (first == 1 && second == 1 && generations[0] == generations[1] &&
memcmp(self->banks[0] + BANK_HEADER, self->banks[1] + BANK_HEADER,
IEC60870_FIRMWARE_UPDATE_WIRE_SIZE) != 0) { return false; }
target = first == 1 && (second != 1 || generations[0] >= generations[1]) ? 1U : 0U;
next = first == 1 ? generations[0] : 0U;
if (second == 1 && generations[1] > next) { next = generations[1]; }
if (next == UINT64_MAX) { return false; }
offset = STORE_HEADER + target * BANK_SIZE;
if (!Write_At(file, offset + 24U, marker, sizeof(marker)) || !FlushFileBuffers(file) ||
!Example_Upgrade_Test_Continue(1U)) { return false; }
candidate = self->banks[target];
memset(candidate, 0, BANK_HEADER);
memcpy(candidate, "UPB1", 4U);
Put32(candidate + 4U, (uint32_t)size); Put64(candidate + 8U, next + 1U);
Put32(candidate + 16U, Crc(bytes, size)); Put32(candidate + 20U, Crc(candidate, 20U));
memcpy(candidate + BANK_HEADER, bytes, size);
if (!Write_At(file, offset, candidate, BANK_SIZE) || !FlushFileBuffers(file) ||
!Example_Upgrade_Test_Continue(2U)) { return false; }
Put32(marker, BANK_COMMITTED);
return Write_At(file, offset + 24U, marker, sizeof(marker)) && FlushFileBuffers(file) &&
Example_Upgrade_Test_Continue(3U);
}
/**
* 功能:按固件源槽编号取得或打开对应文件句柄。
* 输入参数:self——调用方持有的模块实例;slot——固件源槽编号。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:对应源槽的文件句柄;槽号无效或打开失败返回INVALID_HANDLE_VALUE。
* 说明:源槽句柄独占并保留到 Close;仅核心选出的空闲槽可由 image_begin 重置。
*/
static HANDLE Image_Handle(ExampleUpgrade *self, uint8_t slot)
{
char path[MAX_PATH];
HANDLE file;
if (slot >= IEC60870_FIRMWARE_UPDATE_SLOT_COUNT) { return INVALID_HANDLE_VALUE; }
if (self->images[slot] != NULL) { return (HANDLE)self->images[slot]; }
if (!Path(self, slot_names[slot], path)) { return INVALID_HANDLE_VALUE; }
file = CreateFileA(path, GENERIC_READ | GENERIC_WRITE, 0U, NULL, OPEN_EXISTING,
FILE_ATTRIBUTE_NORMAL, NULL);
if (file != INVALID_HANDLE_VALUE) { self->images[slot] = file; }
return file;
}
/**
* 功能:为当前接收事务重建空闲固件源槽。
* 输入参数:context——调用方注册的回调上下文;slot——固件源槽编号;size——本次数据的字节数。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:核心已先持久登记 RECEIVING,并保证此槽不是 current/backup。关闭该槽旧句柄
* 后截断候选;失败可能已经改变空闲槽,不能借此删除或重建已确认的两份映像。
*/
static bool Image_Begin(void *context, uint8_t slot, uint32_t size)
{
ExampleUpgrade *self = context;
char path[MAX_PATH];
HANDLE file;
if (slot >= IEC60870_FIRMWARE_UPDATE_SLOT_COUNT || size == 0U ||
size > EXAMPLE_UPGRADE_PACKAGE_MAX - 16U || !Path(self, slot_names[slot], path)) { return false; }
if (self->images[slot] != NULL) { CloseHandle((HANDLE)self->images[slot]); self->images[slot] = NULL; }
file = CreateFileA(path, GENERIC_READ | GENERIC_WRITE, 0U, NULL, CREATE_ALWAYS,
FILE_ATTRIBUTE_NORMAL, NULL);
if (file == INVALID_HANDLE_VALUE) { return false; }
self->images[slot] = file;
return true;
}
/**
* 功能:回调偏移只针对 payload;连续性由核心校验,本层再做容量及短写检查。
* 输入参数:context——调用方注册的回调上下文;slot——固件源槽编号;offset——从起点计算的字节偏移;bytes——字节数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:无。
*/
static bool Image_Write(void *context, uint8_t slot, uint32_t offset,
const uint8_t *bytes, size_t length)
{
ExampleUpgrade *self = context;
HANDLE file = Image_Handle(self, slot);
return file != INVALID_HANDLE_VALUE && offset <= EXAMPLE_UPGRADE_PACKAGE_MAX - 16U &&
length <= EXAMPLE_UPGRADE_PACKAGE_MAX - 16U - offset &&
(length == 0U || bytes != NULL) && Write_At(file, offset, bytes, length);
}
/**
* 功能:复验和安装都读真实源槽,不使用上传期间的内存副本;缺文件/短读明确失败。
* 输入参数:context——调用方注册的回调上下文;slot——固件源槽编号;offset——从起点计算的字节偏移;bytes——字节数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:bytes——字节数据缓冲。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:无。
*/
static bool Image_Read(void *context, uint8_t slot, uint32_t offset, uint8_t *bytes, size_t length)
{
ExampleUpgrade *self = context;
HANDLE file = Image_Handle(self, slot);
return file != INVALID_HANDLE_VALUE && offset <= EXAMPLE_UPGRADE_PACKAGE_MAX - 16U &&
length <= EXAMPLE_UPGRADE_PACKAGE_MAX - 16U - offset &&
(length == 0U || bytes != NULL) && Read_At(file, offset, bytes, length);
}
/**
* 功能:同步固件源槽内容并执行测试中断判定。
* 输入参数:context——调用方注册的回调上下文;slot——固件源槽编号。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:只有真实 Flush 完成并通过测试注入点才向核心报告成功,随后仍须完整读回校验。
*/
static bool Image_Sync(void *context, uint8_t slot)
{
HANDLE file = Image_Handle(context, slot);
return file != INVALID_HANDLE_VALUE && FlushFileBuffers(file) && Example_Upgrade_Test_Continue(4U);
}
/**
* 功能:核心已逐字节读回 CRC;后端另核对真实长度,拒绝正确前缀后夹带额外内容。
* 输入参数:context——调用方注册的回调上下文;slot——固件源槽编号;descriptor——固件映像描述。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:无。
*/
static bool Image_Validate(void *context, uint8_t slot,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor)
{
HANDLE file = Image_Handle(context, slot);
LARGE_INTEGER size;
return file != INVALID_HANDLE_VALUE && descriptor != NULL &&
GetFileSizeEx(file, &size) && size.QuadPart == descriptor->size;
}
/**
* 功能:通过临时文件和原子替换安装一个固件角色别名。
* 输入参数:self——调用方持有的模块实例;slot——固件源槽编号;descriptor——固件映像描述;backup——是否生成备份别名。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:先完整写固定临时文件并同步,再原子替换目标。中断遗留的临时文件只会被
* 后续同一幂等安装覆盖;源槽不受影响。替换后还要真实打开目标核对长度和 CRC。
* 临时句柄在全部分支关闭,失败不删除证据文件;替换已完成却返回 false 仍须
* 按元数据恢复。每个别名分别替换,依靠先备份及持久意图恢复跨文件中断。
*/
static bool Install_File(ExampleUpgrade *self, uint8_t slot,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor, bool backup)
{
char temporary[MAX_PATH], destination[MAX_PATH];
uint32_t offset = 0U;
HANDLE file;
bool result = false;
if (!Path(self, backup ? "dtu-1.new" : "dtu.new", temporary) ||
!Path(self, backup ? "dtu-1" : "dtu", destination)) { return false; }
file = CreateFileA(temporary, GENERIC_READ | GENERIC_WRITE, 0U, NULL, CREATE_ALWAYS,
FILE_ATTRIBUTE_NORMAL, NULL);
if (file == INVALID_HANDLE_VALUE) { return false; }
while (offset < descriptor->size) {
size_t amount = descriptor->size - offset;
if (amount > sizeof(self->io)) { amount = sizeof(self->io); }
if (!Image_Read(self, slot, offset, self->io, amount) || !Write_At(file, offset, self->io, amount)) {
goto finished;
}
offset += (uint32_t)amount;
}
result = FlushFileBuffers(file) && Example_Upgrade_Test_Continue(backup ? 5U : 7U);
finished:
if (!CloseHandle(file)) { result = false; }
if (!result) { return false; }
return MoveFileExA(temporary, destination, MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH) &&
Example_Upgrade_Test_Continue(backup ? 6U : 8U) &&
Installed_Valid(self, backup ? "dtu-1" : "dtu", descriptor);
}
/**
* 功能:没有原 backup 时应明确不提供 dtu-1;只删除派生别名,不删除任何源槽。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:已不存在视为幂等成功,其他删除错误必须阻止继续安装。
*/
static bool Remove_Backup(ExampleUpgrade *self)
{
char path[MAX_PATH];
if (!Path(self, "dtu-1", path)) { return false; }
if (DeleteFileA(path)) { return true; }
return GetLastError() == ERROR_FILE_NOT_FOUND;
}
/**
* 功能:根据核心的持久角色恢复当前及备份安装文件。
* 输入参数:context——调用方注册的回调上下文;slot——固件源槽编号;descriptor——固件映像描述;transaction_id——本次业务事务身份。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:安装意图已由核心持久化。INSTALLING 先把旧 current 保存为 dtu-1;稳定启动
* 或回退则恢复原 backup(没有原 backup 时移除派生文件),再恢复 current。
* 核心此前已复验所需源槽;此回调只读 Get_Status,不重入任何状态变更接口。
* 同一角色/描述重复安装得到相同字节,所以无需另按 transaction_id 命名文件;
* 它只恢复宿主文件,不跳转、启动进程或证明目标程序已健康运行。
*/
static bool Install(void *context, uint8_t slot,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor, uint64_t transaction_id)
{
ExampleUpgrade *self = context;
IEC60870_FirmwareUpdateStatus_t status;
uint8_t backup;
(void)transaction_id;
if (!IEC60870_FirmwareUpdate_Get_Status(&self->core, &status)) { return false; }
backup = status.state == IEC60870_FIRMWARE_UPDATE_INSTALLING ? status.current_slot : status.backup_slot;
if (backup == IEC60870_FIRMWARE_UPDATE_NO_SLOT) {
if (!Remove_Backup(self)) { return false; }
} else if (backup >= IEC60870_FIRMWARE_UPDATE_SLOT_COUNT ||
!Install_File(self, backup, &status.images[backup], true)) { return false; }
return Install_File(self, slot, descriptor, false);
}
/**
* 功能:I104 头固定为魔数、目标版本、负载长度及负载 CRC;先检查整包边界再减头长。
* 输入参数:header——完整包头字节;package_size——含包头的整包字节数;descriptor——固件映像描述。
* 输出参数:descriptor——固件映像描述。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:这里仅校验声明格式,实际负载 CRC 由核心在同步后读回验证。
*/
static bool Package_Header(const uint8_t *header, uint32_t package_size,
IEC60870_FirmwareUpdateDescriptor_t *descriptor)
{
IEC60870_FirmwareUpdateDescriptor_t value;
if (package_size < 17U || package_size > EXAMPLE_UPGRADE_PACKAGE_MAX ||
memcmp(header, "I104", 4U) != 0) { return false; }
value.version = Get32(header + 4U); value.size = Get32(header + 8U); value.crc = Get32(header + 12U);
if (value.version == 0U || value.size != package_size - 16U) { return false; }
*descriptor = value;
return true;
}
/**
* 功能:检查首次建库所需的源槽和派生文件是否均为空缺。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:无独立输出参数。
* 返回值:首次建库涉及的目标均不存在时返回true,否则返回false。
* 说明:首次初始化不能覆盖已有派生文件或孤立源槽;它们可能是缺失元数据后的证据。
*/
static bool New_Layout_Clear(const ExampleUpgrade *self)
{
static const char *const names[] = {
"upgrade-slot0.bin", "upgrade-slot1.bin", "upgrade-slot2.bin", "dtu", "dtu-1", "dtu.new", "dtu-1.new"
};
char path[MAX_PATH];
size_t i;
for (i = 0U; i < sizeof(names) / sizeof(names[0]); ++i) {
if (!Path(self, names[i], path)) { return false; }
if (GetFileAttributesA(path) != INVALID_FILE_ATTRIBUTES || GetLastError() != ERROR_FILE_NOT_FOUND) {
return false;
}
}
return true;
}
/**
* 功能:seed 的完整包头先验证;负载写入槽后仍由核心同步、逐字节读回 CRC 才登记。
* 输入参数:self——调用方持有的模块实例;seed——首次初始化的基线包路径或句柄;size——本次数据的字节数;descriptor——固件映像描述。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:无。
*/
static bool Provision(ExampleUpgrade *self, HANDLE seed, uint32_t size,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor)
{
uint32_t offset = 0U;
if (!Image_Begin(self, 0U, descriptor->size)) { return false; }
while (offset < size - 16U) {
size_t amount = size - 16U - offset;
if (amount > sizeof(self->io)) { amount = sizeof(self->io); }
if (!Read_At(seed, 16U + offset, self->io, amount) || !Image_Write(self, 0U, offset, self->io, amount)) {
return false;
}
offset += (uint32_t)amount;
}
return IEC60870_FirmwareUpdate_Provision(&self->core, 0U, descriptor) == IEC60870_FIRMWARE_UPDATE_OK;
}
/**
* 功能:Open 取得独占资源并恢复元数据,或用显式 seed 登记真实初始 current。
* 输入参数:self——调用方持有的模块实例;parent——已存在的宿主父目录;seed_path——可选首次初始化基线包路径。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示请求的资源或存储实例已准备就绪;false表示输入校验、资源获取或恢复失败。
* 说明:不调用 Prepare_Boot:已有源槽的健康检查及安装/回退由后续显式启动入口执行。
* 失败关闭已取得句柄,但不删首次初始化中留下的存储/槽,避免把中断证据当空库。
*/
bool Example_Upgrade_Store_Open(ExampleUpgrade *self, const char *parent, const char *seed_path)
{
char saved_parent[200], path[MAX_PATH];
uint8_t header[STORE_HEADER], expected[STORE_HEADER] = {0};
IEC60870_FirmwareUpdateStore_t store;
IEC60870_FirmwareUpdateDescriptor_t baseline;
IEC60870_FirmwareUpdateStatus_t status;
LARGE_INTEGER size;
HANDLE file = INVALID_HANDLE_VALUE, seed = INVALID_HANDLE_VALUE;
DWORD attributes, error;
uint32_t seed_size = 0U;
bool exists, result = false;
size_t i;
if (self == NULL || self->opened || self->storage != NULL || parent == NULL ||
parent[0] == '\0' || strlen(parent) >= sizeof(self->parent)) { return false; }
for (i = 0U; i < IEC60870_FIRMWARE_UPDATE_SLOT_COUNT; ++i) {
if (self->images[i] != NULL) { return false; }
}
attributes = GetFileAttributesA(parent);
if (attributes == INVALID_FILE_ATTRIBUTES || (attributes & FILE_ATTRIBUTE_DIRECTORY) == 0U) { return false; }
/* parent 允许借用上次 Close 后的 self->parent,清对象前先复制。 */
strcpy(saved_parent, parent);
memset(self, 0, sizeof(*self)); strcpy(self->parent, saved_parent);
if (!Path(self, "upgrade.store", path)) { return false; }
attributes = GetFileAttributesA(path); error = GetLastError();
exists = attributes != INVALID_FILE_ATTRIBUTES;
/* 无 seed 的首次调用在创建任何档案前拒绝;已有档案不能用 seed 覆盖重置。 */
if ((!exists && error != ERROR_FILE_NOT_FOUND) || (exists && seed_path != NULL) ||
(!exists && (seed_path == NULL || !New_Layout_Clear(self)))) { return false; }
if (!exists) {
seed = CreateFileA(seed_path, GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING,
FILE_ATTRIBUTE_NORMAL, NULL);
if (seed == INVALID_HANDLE_VALUE || !GetFileSizeEx(seed, &size) || size.QuadPart < 17 ||
size.QuadPart > EXAMPLE_UPGRADE_PACKAGE_MAX || !Read_At(seed, 0U, header, 16U)) { goto finished; }
seed_size = (uint32_t)size.QuadPart;
if (!Package_Header(header, seed_size, &baseline)) { goto finished; }
}
/* CREATE_NEW 防止检查之后其他实例抢先创建;共享模式零维持整个对象的单写者约束。 */
file = CreateFileA(path, GENERIC_READ | GENERIC_WRITE, 0U, NULL,
exists ? OPEN_EXISTING : CREATE_NEW, FILE_ATTRIBUTE_NORMAL, NULL);
if (file == INVALID_HANDLE_VALUE) { goto finished; }
self->storage = file;
memcpy(expected, "IEC104-UPG1", 12U);
Put32(expected + 16U, IEC60870_FIRMWARE_UPDATE_WIRE_SIZE);
Put32(expected + 20U, BANK_SIZE); Put32(expected + 24U, IEC60870_FIRMWARE_UPDATE_SLOT_COUNT);
Put32(expected + 28U, Crc(expected, 28U));
if (!GetFileSizeEx(file, &size) || size.QuadPart > STORE_SIZE) { goto finished; }
if (!exists) {
/* 仅本次新建可写固定头;已有空文件、错布局及超长档案绝不重新初始化。 */
if (size.QuadPart != 0 || !Write_At(file, 0U, expected, sizeof(expected)) || !FlushFileBuffers(file)) {
goto finished;
}
} else if (size.QuadPart < STORE_HEADER || !Read_At(file, 0U, header, sizeof(header)) ||
memcmp(header, expected, sizeof(header)) != 0) { goto finished; }
memset(&store, 0, sizeof(store));
store.context = self; store.metadata_read = Metadata_Read; store.metadata_commit = Metadata_Commit;
store.image_begin = Image_Begin; store.image_write = Image_Write; store.image_read = Image_Read;
store.image_sync = Image_Sync; store.install = Install; store.validate = Image_Validate;
if (IEC60870_FirmwareUpdate_Init(&self->core, &store, EXAMPLE_UPGRADE_PACKAGE_MAX - 16U) !=
IEC60870_FIRMWARE_UPDATE_OK) { goto finished; }
if (!exists && !Provision(self, seed, seed_size, &baseline)) { goto finished; }
if (!IEC60870_FirmwareUpdate_Get_Status(&self->core, &status) || status.faulted ||
status.state == IEC60870_FIRMWARE_UPDATE_STATE_EMPTY) { goto finished; }
self->opened = true; result = true;
finished:
if (seed != INVALID_HANDLE_VALUE) { CloseHandle(seed); }
if (!result) { Example_Upgrade_Store_Close(self); }
return result;
}
/**
* 功能:只释放句柄和内存使用资格,不提交 Abort/Confirm,也不改变持久角色。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:无。
* 说明:源槽先关,元数据锁最后关;调用方须先结束借用本对象的文件和激活回调。
*/
void Example_Upgrade_Store_Close(ExampleUpgrade *self)
{
size_t i;
if (self == NULL) { return; }
for (i = 0U; i < IEC60870_FIRMWARE_UPDATE_SLOT_COUNT; ++i) {
if (self->images[i] != NULL) { CloseHandle((HANDLE)self->images[i]); self->images[i] = NULL; }
}
if (self->storage != NULL) { CloseHandle((HANDLE)self->storage); self->storage = NULL; }
self->opened = self->candidate_open = self->candidate_started = false;
self->core.initialized = false;
}
/**
* 功能:查询已打开固件存储的健康状态。
* 输入参数:self——调用方持有的模块实例;status——固件核心状态回写位置。
* 输出参数:status——固件核心状态回写位置。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:门面统一拒绝未打开或已故障核心;opened 本身不是持续健康证明。
*/
static bool Status(const ExampleUpgrade *self, IEC60870_FirmwareUpdateStatus_t *status)
{
return self != NULL && self->opened && IEC60870_FirmwareUpdate_Get_Status(&self->core, status) &&
!status->faulted;
}
/**
* 功能:查询已确认角色,不能把试安装 dtu 的内容提前公布为正式版本;无介质读取副作用。
* 输入参数:self——调用方持有的模块实例;descriptor——固件映像描述。
* 输出参数:descriptor——固件映像描述。
* 返回值:true表示取得相应角色的有效映像描述;false表示存储状态或角色不可用。
* 说明:无。
*/
bool Example_Upgrade_Store_Current(const ExampleUpgrade *self, IEC60870_FirmwareUpdateDescriptor_t *descriptor)
{
IEC60870_FirmwareUpdateStatus_t status;
if (descriptor == NULL || !Status(self, &status) ||
status.current_slot >= IEC60870_FIRMWARE_UPDATE_SLOT_COUNT) { return false; }
*descriptor = status.images[status.current_slot];
return true;
}
/**
* 功能:只预留当前上传的小包头和长度;旧 VERIFIED 需调用方先显式 Abort 才能替换。
* 输入参数:self——调用方持有的模块实例;package_size——含包头的整包字节数。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示请求的资源或存储实例已准备就绪;false表示输入校验、资源获取或恢复失败。
* 说明:无。
*/
bool Example_Upgrade_Store_Candidate_Open(ExampleUpgrade *self, uint32_t package_size)
{
IEC60870_FirmwareUpdateStatus_t status;
if (!Status(self, &status) || self->candidate_open || package_size < 17U ||
package_size > EXAMPLE_UPGRADE_PACKAGE_MAX || status.state != IEC60870_FIRMWARE_UPDATE_STABLE) { return false; }
memset(self->package_header, 0, sizeof(self->package_header));
self->package_size = package_size; self->received_size = 0U;
self->candidate_started = false; self->candidate_open = true;
return true;
}
/**
* 功能:解析可跨段包头,并把连续负载写入候选固件源槽。
* 输入参数:self——调用方持有的模块实例;offset——从起点计算的字节偏移;bytes——字节数据缓冲;length——本次数据或名称的有效字节数。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:外部偏移包含包头,核心偏移只含负载。头可跨段,只有其完整且版本策略通过
* 才持久 Begin;本段越过头尾时把剩余部分立即送入同一候选源槽。
* 入口参数错误不推进,内部失败撤销本次接收资格,核心残留状态另由 Abort/恢复处理。
*/
bool Example_Upgrade_Store_Candidate_Write(ExampleUpgrade *self, uint32_t offset,
const uint8_t *bytes, size_t length)
{
IEC60870_FirmwareUpdateDescriptor_t descriptor, current;
size_t header_size = 0U;
if (self == NULL || !self->opened || !self->candidate_open || offset != self->received_size ||
offset > self->package_size || length > self->package_size - offset ||
(length != 0U && bytes == NULL)) { return false; }
if (offset < 16U) {
header_size = 16U - offset;
if (header_size > length) { header_size = length; }
if (header_size != 0U) { memcpy(self->package_header + offset, bytes, header_size); }
if (offset + header_size == 16U && !self->candidate_started) {
if (!Package_Header(self->package_header, self->package_size, &descriptor) ||
!Example_Upgrade_Store_Current(self, &current) || descriptor.version <= current.version ||
IEC60870_FirmwareUpdate_Begin(&self->core, &descriptor) != IEC60870_FIRMWARE_UPDATE_OK) {
self->candidate_open = false; return false;
}
self->candidate_started = true;
}
}
if (length > header_size && (!self->candidate_started ||
IEC60870_FirmwareUpdate_Write(&self->core, offset + (uint32_t)header_size - 16U,
bytes + header_size, length - header_size) != IEC60870_FIRMWARE_UPDATE_OK)) {
self->candidate_open = false; return false;
}
self->received_size += (uint32_t)length;
return true;
}
/**
* 功能:收齐才进入核心最终同步/读回;先关闭接收资格,使失败后不能继续补写已提交候选。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:CRC 拒绝与持久 I/O 故障不同,调用方须查看核心状态后执行允许的收尾。
*/
bool Example_Upgrade_Store_Candidate_Finish(ExampleUpgrade *self)
{
bool result;
if (self == NULL || !self->opened || !self->candidate_open || !self->candidate_started ||
self->received_size != self->package_size) { return false; }
self->candidate_open = false;
result = IEC60870_FirmwareUpdate_Finish(&self->core) == IEC60870_FIRMWARE_UPDATE_OK;
return result;
}
/**
* 功能:只在核心确认未授权候选已撤销后清门面标志;授权后及故障态拒绝,保留恢复事实。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:无。
*/
bool Example_Upgrade_Store_Candidate_Abort(ExampleUpgrade *self)
{
if (self == NULL || !self->opened ||
IEC60870_FirmwareUpdate_Abort(&self->core) != IEC60870_FIRMWARE_UPDATE_OK) { return false; }
self->candidate_open = self->candidate_started = false;
return true;
}
/**
* 功能:END 可据此固定已验证描述;返回值副本不延长上传缓冲寿命,也不授予安装资格。
* 输入参数:self——调用方持有的模块实例;descriptor——固件映像描述。
* 输出参数:descriptor——固件映像描述。
* 返回值:true表示取得相应角色的有效映像描述;false表示存储状态或角色不可用。
* 说明:无。
*/
bool Example_Upgrade_Store_Candidate_Info(const ExampleUpgrade *self,
IEC60870_FirmwareUpdateDescriptor_t *descriptor)
{
IEC60870_FirmwareUpdateStatus_t status;
if (descriptor == NULL || !Status(self, &status) || status.state != IEC60870_FIRMWARE_UPDATE_VERIFIED ||
status.candidate_slot >= IEC60870_FIRMWARE_UPDATE_SLOT_COUNT) { return false; }
*descriptor = status.images[status.candidate_slot];
return true;
}
/**
* 功能:真实协议授权的持久边界;失败可能已经写入 AUTHORIZED,不能改走普通取消重传。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:无独立输出参数。
* 返回值:true表示核心接受了持久授权;false表示状态不允许或提交失败,落盘结果仍须按故障契约确认。
* 说明:无。
*/
bool Example_Upgrade_Store_Authorize(ExampleUpgrade *self)
{
return self != NULL && self->opened &&
IEC60870_FirmwareUpdate_Authorize(&self->core) == IEC60870_FIRMWARE_UPDATE_OK;
}
/**
* 功能:核心负责选择取消、安装或回退,Install 回调负责真实别名文件恢复。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:每次启动/应用激活调用一次;再次对 TRIAL 调用将按未确认重启处理并回退。
*/
bool Example_Upgrade_Store_Prepare_Boot(ExampleUpgrade *self)
{
IEC60870_FirmwareUpdateDescriptor_t boot;
return self != NULL && self->opened &&
IEC60870_FirmwareUpdate_Prepare_Boot(&self->core, &boot) == IEC60870_FIRMWARE_UPDATE_OK;
}
/**
* 功能:真实打开安装目标读回全部字节,不能仅凭源槽 CRC 或协议准备成功宣称安装健康。
* 输入参数:self——调用方持有的模块实例;name——文件名或显式长度的协议名称;descriptor——固件映像描述。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:安装目标的长度、内容CRC和描述一致时返回true,否则返回false。
* 说明:句柄仅在本次验证期间持有;长度、短读或 CRC 不符均 false,不在此修改核心状态。
*/
static bool Installed_Valid(ExampleUpgrade *self, const char *name,
const IEC60870_FirmwareUpdateDescriptor_t *descriptor)
{
char path[MAX_PATH];
HANDLE file;
LARGE_INTEGER size;
uint32_t offset = 0U, crc = UINT32_MAX;
bool result = false;
if (!Path(self, name, path)) { return false; }
file = CreateFileA(path, GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
if (file == INVALID_HANDLE_VALUE) { return false; }
if (!GetFileSizeEx(file, &size) || size.QuadPart != descriptor->size) { goto finished; }
while (offset < descriptor->size) {
size_t amount = descriptor->size - offset;
if (amount > sizeof(self->io)) { amount = sizeof(self->io); }
if (!Read_At(file, offset, self->io, amount)) { goto finished; }
crc = Crc_Update(crc, self->io, amount); offset += (uint32_t)amount;
}
result = ~crc == descriptor->crc;
finished:
CloseHandle(file);
return result;
}
/**
* 功能:STABLE 仅核对现有 dtu,不重复轮转角色;TRIAL 核对候选安装文件后才让核心确认。
* 输入参数:self——调用方持有的模块实例。
* 输出参数:无独立输出参数。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:TRIAL 路径中文件不匹配仍留 TRIAL,便于下一启动回退;核心确认提交失败则可能已发布新角色,
* 调用方停止新业务并重开核对,不能把任一 false 一概当成“从未安装”。
*/
bool Example_Upgrade_Store_Confirm(ExampleUpgrade *self)
{
IEC60870_FirmwareUpdateStatus_t status;
if (!Status(self, &status)) { return false; }
if (status.state == IEC60870_FIRMWARE_UPDATE_STABLE) {
return status.current_slot < IEC60870_FIRMWARE_UPDATE_SLOT_COUNT &&
Installed_Valid(self, "dtu", &status.images[status.current_slot]);
}
if (status.state != IEC60870_FIRMWARE_UPDATE_TRIAL ||
status.candidate_slot >= IEC60870_FIRMWARE_UPDATE_SLOT_COUNT ||
!Installed_Valid(self, "dtu", &status.images[status.candidate_slot])) { return false; }
return IEC60870_FirmwareUpdate_Confirm(&self->core) == IEC60870_FIRMWARE_UPDATE_OK;
}