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

120 lines
6.6 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 运行日志:固定容量循环保存,介质原子性由调用方后端保证。
* 无堆、无操作系统和文件系统依赖;全部访问须由调用方串行化。 */
#ifndef IEC60870_USER_LOG_H
#define IEC60870_USER_LOG_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* CAPACITY 是介质逻辑槽数,不要求 RAM 保存整环;WIRE_MAX 为单条最大编码:
* 32 字节固定头 + 128 字节文本 + 4 字节 CRC。UTC 两端均包含在合法范围内。 */
#define IEC60870_USER_LOG_CAPACITY 1024U
#define IEC60870_USER_LOG_TEXT_MAX 128U
#define IEC60870_USER_LOG_WIRE_MAX 164U
#define IEC60870_USER_LOG_UTC_MIN UINT64_C(946656000000)
#define IEC60870_USER_LOG_UTC_MAX UINT64_C(4102415999999)
/* INVALID 表示输入错误;ERROR 包括实例/介质错误及序号耗尽。并非所有 ERROR
* 都设置 faulted,例如耗尽时已有记录仍可查询;EMPTY 用于空槽或越界查询。 */
typedef enum {
IEC60870_USER_LOG_INVALID = -2,
IEC60870_USER_LOG_ERROR = -1,
IEC60870_USER_LOG_EMPTY = 0,
IEC60870_USER_LOG_OK = 1
} IEC60870_UserLogResult_t;
/* index 为 0..1023 的逻辑槽。read 仅在 OK 时填写实际 size;EMPTY 只表示
* 从未提交的空槽,损坏/短读/I/O 失败必须 ERROR。commit 成功表示原子替换并
* 完成持久同步;失败可能已经提交,核心将故障闭锁直到重新 Init。
* context 由调用方持有,缓冲仅在回调中借用,不得保存指针或重入实例。 */
typedef struct {
void *context;
IEC60870_UserLogResult_t (*read)(void *context, uint32_t index,
uint8_t *bytes, size_t capacity, size_t *size);
bool (*commit)(void *context, uint32_t index, const uint8_t *bytes, size_t size);
} IEC60870_UserLogStore_t;
/* sequence 按提交顺序递增,校时回拨不改变记录顺序;text 始终以 NUL 结尾。
* 这是独立的内存值副本,text 的终止符和结构体填充不属于持久化字节布局。 */
typedef struct {
uint64_t sequence;
uint64_t utc_ms;
uint8_t type;
uint8_t value;
char text[IEC60870_USER_LOG_TEXT_MAX + 1U];
} IEC60870_UserLogRecord_t;
/* 调用方静态分配;公开布局仅为分配方便,业务不得直接改内部状态。
* store 为浅拷贝;wire 是复用工作区,不能作为跨调用的记录借用。 */
typedef struct {
IEC60870_UserLogStore_t store;
uint64_t sequence;
uint64_t latest_utc_ms;
size_t count;
bool initialized;
bool faulted;
uint8_t wire[IEC60870_USER_LOG_WIRE_MAX];
} IEC60870_UserLog_t;
/**
* 功能:扫描全部槽并校验格式、CRC、槽号和序号连续性;不清空或修复介质。
* 输入参数:self——调用方持有的模块实例及当前状态;store——同步存储回调表及其上下文。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:self/store 必须非空且回调齐全。允许 store=&self->store;参数错误返回 INVALID 并保留旧实例,扫描失败返回 ERROR 且实例不可用,成功返回 OK。
* 实例与回调 context 均由调用方持有,初始化不取得资源所有权。
*/
IEC60870_UserLogResult_t IEC60870_UserLog_Init(IEC60870_UserLog_t *self,
const IEC60870_UserLogStore_t *store);
/**
* 功能:追加一条事实:type 为 1..11;1/10/11 的 value 只能为 1,其余为 0/1。
* 输入参数:self——调用方持有的模块实例及当前状态;type——类别编号;utc_ms——UTC纪元毫秒;value——待处理数值;text——文本或文本输出器。
* 输出参数:self——本次操作后的运行状态及复用工作区。
* 返回值:OK表示操作完成;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:text 是非空、至多 128 字节的可打印 ASCII;utc_ms 是 UTC 毫秒,允许范围 对应 UTC+8 的 2000..2099。时标允许回拨,不按类别去重,来源状态转换由
* 应用控制。参数本次调用内借用。成功 OK,非法输入 INVALID,故障/序号耗尽 ERROR;仅持久提交成功后推进内存条数/序号,失败不会自动重试。 01/10/11
* 分别表达重启、参数修改、升级行为;02..09 为状态类。核心只检验 类型和值,不推断来源身份、连接极性或设备动作是否真的发生。
*/
IEC60870_UserLogResult_t IEC60870_UserLog_Append(IEC60870_UserLog_t *self,
uint8_t type, uint64_t utc_ms, uint8_t value, const char *text);
/**
* 功能:返回当前保留条数;空库、空指针、未初始化或故障实例都返回 0,不能据此 区分空库与错误。
* 输入参数:self——只读模块实例。
* 输出参数:无。
* 返回值:当前保留条数;NULL、未初始化或故障实例返回0。
* 说明:需要导出时应由 Write/Get 的结果确认实例可用性。
*/
size_t IEC60870_UserLog_Count(const IEC60870_UserLog_t *self);
/**
* 功能:oldest_index 从 0 起,按提交顺序从旧到新查询;超出条数返回 EMPTY。
* 输入参数:self——调用方持有的模块实例及当前状态;oldest_index——按提交顺序从最旧记录起的零基索引。
* 输出参数:self——本次操作后的运行状态及复用工作区;record——成功时写入的独立结果副本。
* 返回值:OK表示操作完成;EMPTY表示没有所需记录或到期任务;INVALID表示参数或操作状态非法;ERROR表示实例不可用、I/O失败或内容损坏。
* 说明:record 须指向调用方独立的输出对象,不得与 self 或存储重叠。成功 OK 时 拷贝完整记录;其他结果保持输出不变。读取/校验错误返回 ERROR 并故障闭锁, 参数错误返回
* INVALID;查询不消费记录。
*/
IEC60870_UserLogResult_t IEC60870_UserLog_Get(IEC60870_UserLog_t *self,
size_t oldest_index, IEC60870_UserLogRecord_t *record);
/**
* 功能:返回最新提交记录的时标,并非所有记录中的最大墙钟值;空库/实例无效/ 输出为空时返回 false,保持输出不变。
* 输入参数:self——只读模块实例。
* 输出参数:utc_ms——成功时写入最新提交记录的UTC毫秒。
* 返回值:true表示已取得最新提交记录的时标;false表示不可用或无记录,输出不变。
* 说明:调用方拥有输出值,无介质读取。
*/
bool IEC60870_UserLog_Latest_Time(const IEC60870_UserLog_t *self, uint64_t *utc_ms);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_USER_LOG_H */