/* 附录 C 日志核心。介质中保存显式小端记录,不保存结构体填充或指针。 */ #include "IEC60870_UserLog.h" #include #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; }