296 lines
14 KiB
C
296 lines
14 KiB
C
/* 附录 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;
|
||
}
|