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

177 lines
12 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.
/*
* 模块:故障录波采样缓存。
* 职责:保存连续瞬时采样的故障前历史,按采样序号触发,收齐故障后窗口后冻结记录。
* 本模块不采集硬件、不生成波形、不写文件;不依赖 RTOS、时钟或传输层,也不分配内存。
* 调用者提供控制对象和采样数组,并负责实际采样率、同一时刻性及调用串行化。
*/
#ifndef IEC60870_FAULT_RECORDER_H
#define IEC60870_FAULT_RECORDER_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#define IEC60870_FAULT_RECORDER_ANALOG_COUNT 8U
#define IEC60870_FAULT_RECORDER_MAX_DIGITAL 64U
#define IEC60870_FAULT_RECORDER_DIGITAL_WORDS 4U
/* 一帧必须来自同一采样时刻:模拟量依次为 Ua、Ub、Uc、U0、Ia、Ib、Ic、I0。
* 保存输入的瞬时整数值,不做有效值、相量或标度换算;物理单位和系数由导出层说明。
* 遥信第 1 路为 digital[0] 的 bit 0,后续通道依次排列;未配置的位在入队时清零。 */
typedef struct {
int16_t analog[IEC60870_FAULT_RECORDER_ANALOG_COUNT];
uint16_t digital[IEC60870_FAULT_RECORDER_DIGITAL_WORDS];
} IEC60870_FaultRecorderFrame_t;
typedef struct {
uint32_t sample_rate_hz; /* 实际输入帧率;须不少于额定频率的 80 倍。 */
uint32_t nominal_frequency_hz; /* 窗口计算使用的额定频率,不能为 0。 */
uint32_t pre_cycles; /* 不少于 4;前后时长均向上取整到完整采样间隔。 */
uint32_t post_cycles; /* 不少于 8;窗口两端点及触发点都保留。 */
uint16_t digital_count; /* 有效遥信通道数:1..64。 */
} IEC60870_FaultRecorderConfig_t;
/* 主流程:ARMED -> CAPTURING -> READY;迟触发也可从 ARMED 直接完成到 READY。
* CAPTURING 遇到不连续采样进入 FAILED;Release 后重新从空历史的 ARMED 开始。 */
typedef enum {
IEC60870_FAULT_RECORDER_ARMED = 0, /* 循环更新故障前历史,允许触发。 */
IEC60870_FAULT_RECORDER_CAPTURING, /* 已固定触发序号,等待故障后端点。 */
IEC60870_FAULT_RECORDER_READY, /* 完整记录冻结,允许读取,拒绝继续写入。 */
IEC60870_FAULT_RECORDER_FAILED /* 本次窗口不连续,须显式释放后重建历史。 */
} IEC60870_FaultRecorderState_t;
typedef enum {
IEC60870_FAULT_RECORDER_OK = 0, /* 已接收采样或触发,窗口尚未完成。 */
IEC60870_FAULT_RECORDER_COMPLETE, /* 本次调用使完整窗口进入 READY。 */
IEC60870_FAULT_RECORDER_BUSY, /* 当前状态不允许该操作。 */
IEC60870_FAULT_RECORDER_NO_HISTORY, /* 触发所需的故障前采样尚未收齐或已被覆盖。 */
IEC60870_FAULT_RECORDER_DISCONTINUITY, /* 输入序号重复、跳变或试图回绕。 */
IEC60870_FAULT_RECORDER_INVALID /* 参数、内存重叠或序号范围不合法。 */
} IEC60870_FaultRecorderResult_t;
typedef struct {
IEC60870_FaultRecorderState_t state;
uint32_t sample_rate_hz;
uint32_t nominal_frequency_hz;
uint16_t digital_count;
size_t pre_samples, post_samples; /* 触发点前后各有多少个采样间隔。 */
size_t frame_count; /* 仅 READY 返回完整记录帧数,其他状态为 0。 */
size_t trigger_index; /* 触发帧在完整记录中的下标,从 0 开始。 */
uint64_t first_sequence, trigger_sequence, last_sequence; /* 有效触发后才有意义的窗口绝对序号。 */
uint32_t triggers, completed, busy_triggers, history_misses, discontinuities; /* 饱和计数,Release 保留。 */
} IEC60870_FaultRecorderInfo_t;
/* 控制对象由调用者持有;成员仅供实现维护,应用不要直接改写。
* 使用对象前必须 Init;所有调用(含读取)须串行化,或在采集与导出上下文间转交所有权。
* 内部没有锁。self 和 storage 不得重叠,且必须存活到全部读取者结束。
* absolute sequence 表示采样时间顺序;oldest/record_start 等仅是环形数组的物理下标。 */
typedef struct {
IEC60870_FaultRecorderConfig_t config;
IEC60870_FaultRecorderFrame_t *storage;
size_t capacity, oldest, count, pre_samples, post_samples, record_count;
size_t record_start;
uint64_t first_sequence, last_sequence, trigger_sequence, record_first, record_last;
uint32_t triggers, completed, busy_triggers, history_misses, discontinuities;
IEC60870_FaultRecorderState_t state;
bool initialized;
} IEC60870_FaultRecorder_t;
/**
* 功能:向 config 写入默认配置;config 为 NULL 时不操作。 默认 50 Hz、4000 帧/秒、故障前 4 周波/后 8 周波、16 路遥信。 保留两端点后共 320 + 640
* + 1 = 961 帧,触发帧下标为 320。 周波覆盖按额定频率计算;实际验收频率范围所需的帧率与窗口由调用者配置。
* 输入参数:无。
* 输出参数:config——写入默认配置;NULL时不操作。
* 返回值:无。
* 说明:仅填写配置,不分配存储或初始化模块实例。
*/
void IEC60870_FaultRecorder_Config_Default(IEC60870_FaultRecorderConfig_t *config);
/**
* 功能:校验 config,并将所需最小帧数写入 capacity(不是字节数)。 校验每额定周波不少于 80 点、前后周波下限、遥信数量和帧数/字节数溢出。 返回 true 表示成功;无效参数返回
* false,并保持 capacity 的原值。 Init 可使用更大的采样数组,以保留更早的历史并容纳更迟到的故障触发。
* 输入参数:config——配置及调用期间借用的元数据。
* 输出参数:capacity——成功写入所需最小帧数。
* 返回值:true表示容量计算成功;false表示配置或输出指针无效,输出不变。
* 说明:调用方串行访问同一实例,采样数组的存储寿命由调用方负责。
*/
bool IEC60870_FaultRecorder_Required_Capacity(
const IEC60870_FaultRecorderConfig_t *config, size_t *capacity);
/**
* 功能:用 config 初始化 self,借用含 capacity 帧的 storage,进入空历史 ARMED。
* 输入参数:self——调用方持有的模块实例及当前状态;config——配置及调用期间借用的元数据;storage——由调用方持有的采样帧数组;capacity——采样数组可容纳的帧数。
* 输出参数:self——成功建立ARMED状态并重置统计;参数失败不变。
* 返回值:true表示初始化完成;false表示配置、容量或内存重叠校验失败。
* 说明:前提:storage 容量不少于 Required_Capacity 的结果,与 self 不重叠且生命周期足够。 返回 true 表示成功;失败返回 false 并保持 self 不变。
* 成功会重置计数器;不分配或清空采样数组,调用者后续须逐帧 Push 建立历史。
*/
bool IEC60870_FaultRecorder_Init(IEC60870_FaultRecorder_t *self,
const IEC60870_FaultRecorderConfig_t *config,
IEC60870_FaultRecorderFrame_t *storage, size_t capacity);
/**
* 功能:复制一帧瞬时采样;sequence 是采样源的绝对序号,首帧可从任意值开始。
* 输入参数:self——调用方持有的模块实例及当前状态;sequence——顺序号;frame——采样帧。
* 输出参数:self——更新后的录波状态、环形索引及统计。
* 返回值:INVALID表示参数或操作状态非法;BUSY表示当前状态不允许继续;DISCONTINUITY表示采样序号不连续;COMPLETE表示本次收齐完整录波窗口;OK表示操作完成。
* 说明:前提:后续每帧序号严格加 1,UINT64_MAX 不回绕;frame 不得与 self/storage 重叠。 ARMED 遇到不连续序号时丢弃旧历史,以本帧重新开始并返回
* DISCONTINUITY。 CAPTURING 遇到不连续序号时拒收本帧,进入 FAILED 并返回 DISCONTINUITY, 防止将缺点的窗口误当成固定采样率的有效录波。
* READY/FAILED 拒收并返回 BUSY。 正常接收返回 OK;收齐故障后端点返回 COMPLETE,记录被冻结以供导出。 未初始化、NULL 或重叠内存返回 INVALID,
* 不修改对象。
*/
IEC60870_FaultRecorderResult_t IEC60870_FaultRecorder_Push(
IEC60870_FaultRecorder_t *self, uint64_t sequence,
const IEC60870_FaultRecorderFrame_t *frame);
/**
* 功能:按已接收的 trigger_sequence 触发录波;该值是绝对序号,不是环形下标。
* 输入参数:self——调用方持有的模块实例及当前状态;trigger_sequence——触发采样的绝对序号。
* 输出参数:self——更新后的录波状态、环形索引及统计。
* 返回值:INVALID表示参数或操作状态非法;BUSY表示当前状态不允许继续;NO_HISTORY表示故障前历史不足;COMPLETE表示本次收齐完整录波窗口;OK表示操作完成。
* 说明:前提:状态为 ARMED,触发帧及其前 pre_samples 个间隔仍完整保留在历史中。 支持判据延迟上报:若故障后窗口也已在缓存内,立即冻结并返回 COMPLETE; 否则进入
* CAPTURING 并返回 OK,后续 Push 收齐剩余窗口。 非 ARMED 返回 BUSY;故障前历史不足返回 NO_HISTORY;未来触发序号或故障后 序号加法溢出返回
* INVALID。失败不会改动缓存采样,但可能更新对应统计计数。
*/
IEC60870_FaultRecorderResult_t IEC60870_FaultRecorder_Trigger(
IEC60870_FaultRecorder_t *self, uint64_t trigger_sequence);
/**
* 功能:将当前状态、配置与统计快照写入 info,任意已初始化状态均可读取。 frame_count 仅在 READY 非零;窗口绝对序号字段仅在有效触发后有意义。
* 输入参数:self——只读模块实例。
* 输出参数:info——成功时写入的独立结果副本。
* 返回值:true表示已取得状态快照;false表示实例或输出内存无效,输出不变。
* 说明:前提:info 不得与 self/storage 重叠,读取也须遵守对象的串行访问约定。 返回 true 表示成功;失败返回 false,保持 info 不变。
*/
bool IEC60870_FaultRecorder_Get_Info(const IEC60870_FaultRecorder_t *self,
IEC60870_FaultRecorderInfo_t *info);
/**
* 功能:按时间顺序复制冻结记录的第 index 帧,index 从 0 开始且须小于 frame_count。
* 输入参数:self——只读模块实例;index——零基索引。
* 输出参数:frame——成功时写入的独立结果副本。
* 返回值:true表示已复制指定冻结帧;false表示状态、索引或输出内存不合法,输出不变。
* 说明:前提:状态为 READY,frame 不得与 self/storage 重叠,读取期间不得 Release/Init。 返回 true 表示成功;失败返回 false,保持 frame 不变。
* READY 的采样保持不变直到显式 Release/Init,可供导出层按需反复读取。
*/
bool IEC60870_FaultRecorder_Get_Frame(const IEC60870_FaultRecorder_t *self,
size_t index, IEC60870_FaultRecorderFrame_t *frame);
/**
* 功能:放弃历史、正在录制或冻结的记录,保留配置与计数器,重新进入空历史 ARMED。
* 输入参数:self——调用方持有的模块实例及当前状态。
* 输出参数:self——更新后的录波状态、环形索引及统计。
* 返回值:true表示已重新进入空历史ARMED;false表示实例未初始化或为空。
* 说明:前提:所有导出者/读取句柄已结束对冻结记录的使用,且没有并发读写。 返回 true 表示成功;对象未初始化或为 NULL 时返回 false。 本模块只有一个采样数组:READY
* 期间不接收新样本,释放后须重新积累故障前历史; Release 不补采这段空档,也不清零数组的旧字节。
*/
bool IEC60870_FaultRecorder_Release(IEC60870_FaultRecorder_t *self);
#ifdef __cplusplus
}
#endif
#endif /* IEC60870_FAULT_RECORDER_H */