177 lines
12 KiB
C
177 lines
12 KiB
C
/*
|
||
* 模块:故障录波采样缓存。
|
||
* 职责:保存连续瞬时采样的故障前历史,按采样序号触发,收齐故障后窗口后冻结记录。
|
||
* 本模块不采集硬件、不生成波形、不写文件;不依赖 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 */
|