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

296 lines
14 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.
/* 附录 C 日志核心。介质中保存显式小端记录,不保存结构体填充或指针。 */
#include "IEC60870_UserLog.h"
#include <string.h>
#define USER_LOG_HEADER 32U
#define USER_LOG_OVERHEAD (USER_LOG_HEADER + 4U)
/**
* 功能:将整数的低length字节按小端写入目标区。
* 输入参数:value——待处理数值;length——字节数。
* 输出参数:bytes——编码或复制结果的目标字节区。
* 返回值:无。
* 说明:固定头:magic[0..3]、version[4]、保留[5]、文本长度[6..7]、序号[8..15]、 UTC 毫秒[16..23]、类别[24]、值[25]、保留[26..31];
* 随后是无 NUL 文本及 CRC32。CRC 覆盖除末尾 CRC 自身以外的全部实际字节,即固定头及实际文本; 不覆盖工作区剩余字节。整数辅助函数只由内部以已知的 2/4/8 字节宽度调用,
* 逐字节访问避免未对齐读写及宿主端序影响。
*/
static void Put_Unsigned(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)); }
}
/**
* 功能:从已验证长度的字节区读取小端无符号整数,支持未对齐地址;内部宽度为2/4/8字节。
* 输入参数:bytes——字节数据;length——字节数。
* 输出参数:无。
* 返回值:按小端还原的无符号整数。
* 说明:调用方保证源区域可读,不在此辅助入口进行长度检查。
*/
static uint64_t Get_Unsigned(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;
}
/**
* 功能:反射 CRC32,初始/最终异或全 1;独立于存储后端的提交校验。
* 输入参数:bytes——字节数据;length——字节数。
* 输出参数:无。
* 返回值:初始和最终异或均为全1的CRC32校验值。
* 说明:校验值只用于内容一致性检查,不提供来源认证。
*/
static uint32_t Checksum(const uint8_t *bytes, size_t length)
{
uint32_t crc = UINT32_MAX;
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;
}
/**
* 功能:行为类只记发生,状态类允许发生/返回;这里不比较前一条日志的类别或值, 同类不同来源都能形成记录。
* 输入参数:type——类别编号;value——待处理数值;utc_ms——UTC纪元毫秒。
* 输出参数:无。
* 返回值:true表示日志类别、值和时标满足存储约束,false表示任一字段非法。
* 说明:时间只检查可编码范围,不禁止墙钟回拨。
*/
static bool Fields_Valid(uint8_t type, uint8_t value, uint64_t utc_ms)
{
return type >= 1U && type <= 11U && value <= 1U &&
((type != 1U && type != 10U && type != 11U) || value == 1U) &&
utc_ms >= IEC60870_USER_LOG_UTC_MIN && utc_ms <= IEC60870_USER_LOG_UTC_MAX;
}
/**
* 功能:有界检查:最多读取 129 字节,拒绝空串、控制字符及非 ASCII 字节。
* 输入参数:text——文本或文本输出器。
* 输出参数:无。
* 返回值:有效非空ASCII文本的字节数;NULL、空串、过长或非法文本返回0。
* 说明:返回 0 同时表示空串和非法文本,调用者统一将它们视为无效输入。
*/
static size_t Text_Length(const char *text)
{
size_t length;
if (text == NULL) { return 0U; }
for (length = 0U; length <= IEC60870_USER_LOG_TEXT_MAX; ++length) {
unsigned char byte = (unsigned char)text[length];
if (byte == 0U) { return length; }
if (byte < 0x20U || byte > 0x7eU) { return 0U; }
}
return 0U;
}
/**
* 功能:先验格式与内容校验再返回解析值,防止 CRC 正确但语义非法的记录混入。
* 输入参数:self——调用方持有的模块实例及当前状态;index——零基索引。
* 输出参数:self——复用wire读取工作区;record——仅OK时写入完整日志副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:槽号也属于恢复约束,任何序号必须位于 (sequence-1)%1024。 仅成功才写 record;本函数只分类结果,是否故障闭锁由 Init/Get 决定。
*/
static IEC60870_UserLogResult_t Load(IEC60870_UserLog_t *self, uint32_t index,
IEC60870_UserLogRecord_t *record)
{
uint8_t *wire = self->wire;
IEC60870_UserLogRecord_t decoded;
IEC60870_UserLogResult_t result;
size_t size = 0U, length, i;
result = self->store.read(self->store.context, index, wire, sizeof(self->wire), &size);
if (result == IEC60870_USER_LOG_EMPTY) { return result; }
if (result != IEC60870_USER_LOG_OK || size < USER_LOG_OVERHEAD + 1U ||
size > sizeof(self->wire)) { return IEC60870_USER_LOG_ERROR; }
length = (size_t)Get_Unsigned(wire + 6U, 2U);
if (memcmp(wire, "ULG1", 4U) != 0 || wire[4] != 1U || wire[5] != 0U ||
length == 0U || length > IEC60870_USER_LOG_TEXT_MAX ||
size != USER_LOG_OVERHEAD + length ||
Get_Unsigned(wire + size - 4U, 4U) != Checksum(wire, size - 4U)) {
return IEC60870_USER_LOG_ERROR;
}
for (i = 26U; i < USER_LOG_HEADER; ++i) {
if (wire[i] != 0U) { return IEC60870_USER_LOG_ERROR; }
}
memset(&decoded, 0, sizeof(decoded));
decoded.sequence = Get_Unsigned(wire + 8U, 8U);
decoded.utc_ms = Get_Unsigned(wire + 16U, 8U);
decoded.type = wire[24];
decoded.value = wire[25];
if (decoded.sequence == 0U ||
(decoded.sequence - 1U) % IEC60870_USER_LOG_CAPACITY != index ||
!Fields_Valid(decoded.type, decoded.value, decoded.utc_ms)) {
return IEC60870_USER_LOG_ERROR;
}
for (i = 0U; i < length; ++i) {
if (wire[USER_LOG_HEADER + i] < 0x20U || wire[USER_LOG_HEADER + i] > 0x7eU) {
return IEC60870_USER_LOG_ERROR;
}
}
memcpy(decoded.text, wire + USER_LOG_HEADER, length);
*record = decoded;
return IEC60870_USER_LOG_OK;
}
/**
* 功能:只读扫描全部逻辑槽,重建连续序号、保留条数和最新序号对应的时间。
* 输入参数:self——调用方持有的模块实例及当前状态;store——同步存储回调表及其上下文。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:参数非法不清实例;有效参数通过后复制store并重建RAM,内容错误锁存faulted。 全空介质可初始化成功;不修复或改写损坏记录,context与回调仍由调用方持有。
*/
IEC60870_UserLogResult_t IEC60870_UserLog_Init(IEC60870_UserLog_t *self,
const IEC60870_UserLogStore_t *store)
{
IEC60870_UserLogStore_t saved_store;
IEC60870_UserLogRecord_t record;
uint64_t first = UINT64_MAX;
uint32_t index;
if (self == NULL || store == NULL || store->read == NULL || store->commit == NULL) {
return IEC60870_USER_LOG_INVALID;
}
/* 支持 Init(self,&self->store),必须先保存别名输入再清工作状态。 */
saved_store = *store;
memset(self, 0, sizeof(*self));
self->store = saved_store;
for (index = 0U; index < IEC60870_USER_LOG_CAPACITY; ++index) {
IEC60870_UserLogResult_t result = Load(self, index, &record);
if (result == IEC60870_USER_LOG_EMPTY) { continue; }
if (result != IEC60870_USER_LOG_OK) {
self->faulted = true;
return IEC60870_USER_LOG_ERROR;
}
++self->count;
if (record.sequence < first) { first = record.sequence; }
/* 最新时间跟随最大序号,不能取最大的 UTC 值,否则校时回拨后目录时间
* 会错误地指向更早提交的记录。扫描顺序只是物理槽顺序,不是事件顺序。 */
if (record.sequence > self->sequence) {
self->sequence = record.sequence;
self->latest_utc_ms = record.utc_ms;
}
}
/* 槽映射排除了重复序号;首尾跨度和应有条数共同排除中间缺口及旧尾混入。
* 未写满时必须是 1..最大序号,写满后必须是最大序号之前连续的 1024 条。
* 没有外部提交日志时,无法证明被后端误报 EMPTY 的全部历史曾经存在,
* 也不能识别完整删除最新尾部后仍构成合法前缀的情况。 */
if (self->count != 0U &&
(self->count != (self->sequence < IEC60870_USER_LOG_CAPACITY ?
(size_t)self->sequence : IEC60870_USER_LOG_CAPACITY) ||
first != self->sequence - self->count + 1U)) {
self->faulted = true;
return IEC60870_USER_LOG_ERROR;
}
self->initialized = true;
return IEC60870_USER_LOG_OK;
}
/**
* 功能:将类别、UTC时刻、状态及非空ASCII文本编码为新序号,原子提交后才更新内存计数。
* 输入参数:self——调用方持有的模块实例及当前状态;type——类别编号;utc_ms——UTC纪元毫秒;value——待处理数值;text——文本或文本输出器。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:时间允许回拨,满环覆盖最旧记录;非法字段返回INVALID,序号耗尽只拒绝新增。 commit失败可能已落盘,须锁存故障并重新Init,不能直接复用序号重试。
*/
IEC60870_UserLogResult_t IEC60870_UserLog_Append(IEC60870_UserLog_t *self,
uint8_t type, uint64_t utc_ms, uint8_t value, const char *text)
{
char saved_text[IEC60870_USER_LOG_TEXT_MAX + 1U];
size_t length, size;
uint64_t sequence;
uint8_t *wire;
if (self == NULL) { return IEC60870_USER_LOG_INVALID; }
if (!self->initialized || self->faulted) { return IEC60870_USER_LOG_ERROR; }
length = Text_Length(text);
if (!Fields_Valid(type, value, utc_ms) || length == 0U) { return IEC60870_USER_LOG_INVALID; }
/* 耗尽只拒绝新增,不能回绕复用身份;它不破坏已有记录,也不置介质故障。 */
if (self->sequence == UINT64_MAX) { return IEC60870_USER_LOG_ERROR; }
/* 输入可能来自实例工作区,先保存文本再生成新的序列化记录。 */
memcpy(saved_text, text, length);
sequence = self->sequence + 1U;
wire = self->wire;
memset(wire, 0, USER_LOG_HEADER);
memcpy(wire, "ULG1", 4U);
wire[4] = 1U;
Put_Unsigned(wire + 6U, length, 2U);
Put_Unsigned(wire + 8U, sequence, 8U);
Put_Unsigned(wire + 16U, utc_ms, 8U);
wire[24] = type;
wire[25] = value;
memcpy(wire + USER_LOG_HEADER, saved_text, length);
size = USER_LOG_OVERHEAD + length;
Put_Unsigned(wire + size - 4U, Checksum(wire, size - 4U), 4U);
if (!self->store.commit(self->store.context,
(uint32_t)((sequence - 1U) % IEC60870_USER_LOG_CAPACITY), wire, size)) {
/* false 不代表介质仍是旧值;重扫前绝不能复用同一序号继续提交。 */
self->faulted = true;
return IEC60870_USER_LOG_ERROR;
}
/* 这是内存状态的提交点;失败路径只置故障,不把不确定的新版本记为成功。 */
self->sequence = sequence;
self->latest_utc_ms = utc_ms;
if (self->count < IEC60870_USER_LOG_CAPACITY) { ++self->count; }
return IEC60870_USER_LOG_OK;
}
/**
* 功能:返回已恢复或已提交的内存条数;空指针、未初始化和故障实例均返回0。
* 输入参数:self——只读模块实例。
* 输出参数:无。
* 返回值:当前保留条数;NULL、未初始化或故障实例返回0。
* 说明:只根据传入数据计算或判定,不改写输入对象。
*/
size_t IEC60870_UserLog_Count(const IEC60870_UserLog_t *self)
{
/* 只读恢复后的内存计数,不触碰介质;返回 0 不足以证明这是健康空库。 */
return self != NULL && self->initialized && !self->faulted ? self->count : 0U;
}
/**
* 功能:按持久序号从旧到新复制一条日志,oldest_index为0表示当前最旧记录。
* 输入参数:self——调用方持有的模块实例及当前状态;oldest_index——按提交顺序从最旧记录起的零基索引。
* 输出参数:self——本次操作后的运行状态及复用工作区;record——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:下标越界返回EMPTY;应有记录缺失、损坏或序号不符返回ERROR并锁存故障。 仅OK时填写record,返回副本而非内部wire指针。
*/
IEC60870_UserLogResult_t IEC60870_UserLog_Get(IEC60870_UserLog_t *self,
size_t oldest_index, IEC60870_UserLogRecord_t *record)
{
IEC60870_UserLogRecord_t decoded;
uint64_t sequence;
if (self == NULL || record == NULL) { return IEC60870_USER_LOG_INVALID; }
if (!self->initialized || self->faulted) { return IEC60870_USER_LOG_ERROR; }
if (oldest_index >= self->count) { return IEC60870_USER_LOG_EMPTY; }
/* 先由逻辑下标求预期序号,再验证物理槽确实仍属于它。Count 无法发现的
* 后续介质损坏在这里被识别;保留范围内缺槽也属于 ERROR,而非普通 EMPTY。 */
sequence = self->sequence - self->count + 1U + oldest_index;
if (Load(self, (uint32_t)((sequence - 1U) % IEC60870_USER_LOG_CAPACITY), &decoded) !=
IEC60870_USER_LOG_OK || decoded.sequence != sequence) {
self->faulted = true;
return IEC60870_USER_LOG_ERROR;
}
*record = decoded;
return IEC60870_USER_LOG_OK;
}
/**
* 功能:查询最大已提交序号的UTC时间,不取墙钟数值最大值,因日志时刻允许回拨。
* 输入参数:self——只读模块实例。
* 输出参数:utc_ms——成功时写入最新提交记录的UTC毫秒。
* 返回值:true表示已取得最新提交记录的时标;false表示不可用或无记录,输出不变。
* 说明:无记录、实例不可用或输出为空时返回false且不改写输出;不访问介质。
*/
bool IEC60870_UserLog_Latest_Time(const IEC60870_UserLog_t *self, uint64_t *utc_ms)
{
if (self == NULL || utc_ms == NULL || !self->initialized || self->faulted || self->count == 0U) {
return false;
}
*utc_ms = self->latest_utc_ms;
return true;
}