362 lines
19 KiB
C
362 lines
19 KiB
C
/*
|
|
* 模块:故障录波采样缓存实现。
|
|
* ARMED 持续维护环形历史,Trigger 固定绝对采样窗口,收齐后以 READY 冻结供导出。
|
|
* 前后窗口都包含端点;内存归调用者所有,不做采样、时钟换算或文件操作。
|
|
* 公开接口的参数、返回值及串行调用要求见 IEC60870_FaultRecorder.h。
|
|
*/
|
|
#include "IEC60870_FaultRecorder.h"
|
|
|
|
#include <string.h>
|
|
|
|
/**
|
|
* 功能:统计达到上限后饱和,避免长期运行时回绕为 0 而掩盖历史错误。
|
|
* 输入参数:value——待处理数值。
|
|
* 输出参数:value——更新后的饱和计数。
|
|
* 返回值:无。
|
|
* 说明:调用方串行访问同一实例,采样数组的存储寿命由调用方负责。
|
|
*/
|
|
static void Increment(uint32_t *value)
|
|
{
|
|
if (*value != UINT32_MAX) { ++*value; }
|
|
}
|
|
|
|
/**
|
|
* 功能:按半开字节区间判重叠;末地址本身无法表示时也按重叠拒绝,避免加法回绕漏检。
|
|
* 输入参数:a——第一段内存首地址;a_size——第一段内存字节数;b——第二段内存首地址;b_size——第二段内存字节数。
|
|
* 输出参数:无。
|
|
* 返回值:true表示内存区间重叠或末地址溢出,false表示可判定不重叠。
|
|
* 说明:此检查只约束地址范围,不替代调用者对指针有效性和对象生命周期的保证。
|
|
*/
|
|
static bool Overlap(const void *a, size_t a_size, const void *b, size_t b_size)
|
|
{
|
|
uintptr_t a_start = (uintptr_t)a, b_start = (uintptr_t)b;
|
|
if (a_size > UINTPTR_MAX - a_start || b_size > UINTPTR_MAX - b_start) { return true; }
|
|
return a_start < b_start + b_size && b_start < a_start + a_size;
|
|
}
|
|
|
|
/**
|
|
* 功能:将前后周波数换成采样间隔数,并检查最终帧数在目标平台能否安全寻址。
|
|
* 输入参数:config——配置及调用期间借用的元数据。
|
|
* 输出参数:pre——故障前采样间隔数;post——故障后采样间隔数;required——完整录波所需帧数。
|
|
* 返回值:true表示窗口配置和帧容量计算合法,false表示配置或容量范围非法。
|
|
* 说明:调用方串行访问同一实例,采样数组的存储寿命由调用方负责。
|
|
*/
|
|
static bool Layout(const IEC60870_FaultRecorderConfig_t *config,
|
|
size_t *pre, size_t *post, size_t *required)
|
|
{
|
|
uint64_t pre_product, post_product, pre_count, post_count, total;
|
|
if (config == NULL || config->nominal_frequency_hz == 0U ||
|
|
config->pre_cycles < 4U || config->post_cycles < 8U ||
|
|
config->digital_count == 0U || config->digital_count > IEC60870_FAULT_RECORDER_MAX_DIGITAL ||
|
|
(uint64_t)config->sample_rate_hz < (uint64_t)config->nominal_frequency_hz * 80U) {
|
|
return false;
|
|
}
|
|
/* 先扩为 64 位再乘;用商加非零余数向上取整,避免 product + frequency - 1 溢出。 */
|
|
pre_product = (uint64_t)config->sample_rate_hz * config->pre_cycles;
|
|
post_product = (uint64_t)config->sample_rate_hz * config->post_cycles;
|
|
pre_count = pre_product / config->nominal_frequency_hz +
|
|
(pre_product % config->nominal_frequency_hz != 0U ? 1U : 0U);
|
|
post_count = post_product / config->nominal_frequency_hz +
|
|
(post_product % config->nominal_frequency_hz != 0U ? 1U : 0U);
|
|
if (pre_count > UINT32_MAX || post_count > UINT32_MAX) { return false; }
|
|
/* pre/post 是间隔数,公共触发点只计一次:默认 320 + 640 + 1 = 961 帧。 */
|
|
total = pre_count + post_count + 1U;
|
|
if (total > UINT32_MAX || total > SIZE_MAX / sizeof(IEC60870_FaultRecorderFrame_t)) { return false; }
|
|
*pre = (size_t)pre_count; *post = (size_t)post_count; *required = (size_t)total;
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
* 功能:这里只判定 Init 已建立的实例,不能替代对外部指针可访问性或并发所有权的保证。
|
|
* 输入参数:self——只读模块实例。
|
|
* 输出参数:无。
|
|
* 返回值:true表示实例非空且已初始化,false表示实例无效。
|
|
* 说明:只根据传入数据计算或判定,不改写输入对象。
|
|
*/
|
|
static bool Valid(const IEC60870_FaultRecorder_t *self)
|
|
{
|
|
return self != NULL && self->initialized;
|
|
}
|
|
|
|
/**
|
|
* 功能:读取输出不能别名到控制对象或采样数组;Push 也复用此规则检查输入帧, 防止移动环形边界或写入目的帧时破坏同一块内存中的输入数据。
|
|
* 输入参数:self——只读模块实例;output——待检查的输出内存;size——字节数。
|
|
* 输出参数:无。
|
|
* 返回值:true表示输出非空且不与控制对象或采样区重叠,false表示不允许使用。
|
|
* 说明:只根据传入数据计算或判定,不改写输入对象。
|
|
*/
|
|
static bool Output_Allowed(const IEC60870_FaultRecorder_t *self, const void *output, size_t size)
|
|
{
|
|
return output != NULL && !Overlap(self, sizeof(*self), output, size) &&
|
|
!Overlap(self->storage, self->capacity * sizeof(*self->storage), output, size);
|
|
}
|
|
|
|
/**
|
|
* 功能:offset 是从最旧帧开始的逻辑偏移,调用者保证小于 capacity。
|
|
* 输入参数:self——只读模块实例;offset——从最旧帧起的逻辑偏移。
|
|
* 输出参数:无。
|
|
* 返回值:对应的环形数组物理下标。
|
|
* 说明:分段换算环形下标,避免直接计算 oldest + offset 时发生 size_t 溢出。
|
|
*/
|
|
static size_t Index(const IEC60870_FaultRecorder_t *self, size_t offset)
|
|
{
|
|
size_t remaining = self->capacity - self->oldest;
|
|
return offset < remaining ? self->oldest + offset : offset - remaining;
|
|
}
|
|
|
|
/**
|
|
* 功能:只使旧采样在逻辑上失效,不清数组字节,也不丢失配置和累计统计。
|
|
* 输入参数:self——调用方持有的模块实例及当前状态。
|
|
* 输出参数:self——更新后的录波状态、环形索引及统计。
|
|
* 返回值:无。
|
|
* 说明:调用方串行访问同一实例,采样数组的存储寿命由调用方负责。
|
|
*/
|
|
static void Clear_History(IEC60870_FaultRecorder_t *self)
|
|
{
|
|
self->oldest = 0U; self->count = 0U; self->record_start = 0U;
|
|
self->first_sequence = 0U; self->last_sequence = 0U;
|
|
self->trigger_sequence = 0U; self->record_first = 0U; self->record_last = 0U;
|
|
self->state = IEC60870_FAULT_RECORDER_ARMED;
|
|
}
|
|
|
|
/**
|
|
* 功能:上层已保证本帧连续或历史为空;容量满时覆盖最旧帧,并同步移动其绝对序号。
|
|
* 输入参数:self——调用方持有的模块实例及当前状态;sequence——顺序号;frame——采样帧。
|
|
* 输出参数:self——更新后的录波状态、环形索引及统计。
|
|
* 返回值:无。
|
|
* 说明:CAPTURING 也使用同一环,最小容量覆盖整个录波窗口,直到末帧到达仍能保住首帧。
|
|
*/
|
|
static void Append(IEC60870_FaultRecorder_t *self, uint64_t sequence,
|
|
const IEC60870_FaultRecorderFrame_t *frame)
|
|
{
|
|
IEC60870_FaultRecorderFrame_t *destination;
|
|
unsigned i, words = (self->config.digital_count + 15U) / 16U;
|
|
if (self->count == self->capacity) {
|
|
self->oldest = self->oldest + 1U == self->capacity ? 0U : self->oldest + 1U;
|
|
++self->first_sequence;
|
|
} else {
|
|
if (self->count == 0U) { self->first_sequence = sequence; }
|
|
++self->count;
|
|
}
|
|
destination = &self->storage[Index(self, self->count - 1U)];
|
|
memcpy(destination->analog, frame->analog, sizeof(destination->analog));
|
|
/* 不让调用者未配置的数字位进入文件;末字不足 16 路时还须屏蔽其高位。 */
|
|
for (i = 0U; i < IEC60870_FAULT_RECORDER_DIGITAL_WORDS; ++i) {
|
|
destination->digital[i] = i < words ? frame->digital[i] : 0U;
|
|
}
|
|
if (self->config.digital_count % 16U != 0U) {
|
|
destination->digital[words - 1U] &= (uint16_t)((1U << (self->config.digital_count % 16U)) - 1U);
|
|
}
|
|
self->last_sequence = sequence;
|
|
}
|
|
|
|
/**
|
|
* 功能:环中可能还保留早于窗口的历史;先将窗口首序号换成物理下标,再冻结整个缓存。
|
|
* 输入参数:self——调用方持有的模块实例及当前状态。
|
|
* 输出参数:self——更新后的录波状态、环形索引及统计。
|
|
* 返回值:无。
|
|
* 说明:READY 后 Push 不再覆盖数据,Get_Frame 可从 record_start 按时间顺序重复读取。
|
|
*/
|
|
static void Complete(IEC60870_FaultRecorder_t *self)
|
|
{
|
|
self->record_start = Index(self, (size_t)(self->record_first - self->first_sequence));
|
|
self->state = IEC60870_FAULT_RECORDER_READY;
|
|
Increment(&self->completed);
|
|
}
|
|
|
|
/**
|
|
* 功能:建立默认窗口配置,不创建实例或分配帧存储;容量仍须由 Required_Capacity 校核。
|
|
* 输入参数:无。
|
|
* 输出参数:config——写入默认配置;NULL时不操作。
|
|
* 返回值:无。
|
|
* 说明:仅填写配置,不分配存储或初始化模块实例。
|
|
*/
|
|
void IEC60870_FaultRecorder_Config_Default(IEC60870_FaultRecorderConfig_t *config)
|
|
{
|
|
if (config == NULL) { return; }
|
|
memset(config, 0, sizeof(*config));
|
|
config->sample_rate_hz = 4000U; config->nominal_frequency_hz = 50U;
|
|
config->pre_cycles = 4U; config->post_cycles = 8U; config->digital_count = 16U;
|
|
}
|
|
|
|
/**
|
|
* 功能:只有 Layout 完整通过才发布最小帧数;配置不合法时保留调用者原来的容量输出。
|
|
* 输入参数:config——配置及调用期间借用的元数据。
|
|
* 输出参数:capacity——成功写入所需最小帧数。
|
|
* 返回值:true表示容量计算成功;false表示配置或输出指针无效,输出不变。
|
|
* 说明:调用方串行访问同一实例,采样数组的存储寿命由调用方负责。
|
|
*/
|
|
bool IEC60870_FaultRecorder_Required_Capacity(
|
|
const IEC60870_FaultRecorderConfig_t *config, size_t *capacity)
|
|
{
|
|
size_t pre, post, required;
|
|
if (capacity == NULL || !Layout(config, &pre, &post, &required)) { return false; }
|
|
*capacity = required;
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
* 功能:校验完容量和控制对象/帧区不重叠后才重置状态,不擦除调用者的采样数组。
|
|
* 输入参数:self——调用方持有的模块实例及当前状态;config——配置及调用期间借用的元数据;storage——由调用方持有的采样帧数组;capacity——采样数组可容纳的帧数。
|
|
* 输出参数:self——成功建立ARMED状态并重置统计;参数失败不变。
|
|
* 返回值:true表示初始化完成;false表示配置、容量或内存重叠校验失败。
|
|
* 说明:调用方串行访问同一实例,采样数组的存储寿命由调用方负责。
|
|
*/
|
|
bool IEC60870_FaultRecorder_Init(IEC60870_FaultRecorder_t *self,
|
|
const IEC60870_FaultRecorderConfig_t *config,
|
|
IEC60870_FaultRecorderFrame_t *storage, size_t capacity)
|
|
{
|
|
size_t pre, post, required;
|
|
IEC60870_FaultRecorderConfig_t saved;
|
|
if (self == NULL || storage == NULL || !Layout(config, &pre, &post, &required) ||
|
|
capacity < required || capacity > SIZE_MAX / sizeof(*storage) ||
|
|
Overlap(self, sizeof(*self), storage, capacity * sizeof(*storage))) { return false; }
|
|
/* config 可以指向 self->config;先保存再清控制对象,避免初始化时破坏配置源。 */
|
|
saved = *config;
|
|
memset(self, 0, sizeof(*self));
|
|
self->config = saved; self->storage = storage; self->capacity = capacity;
|
|
self->pre_samples = pre; self->post_samples = post; self->record_count = required;
|
|
self->state = IEC60870_FAULT_RECORDER_ARMED; self->initialized = true;
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
* 功能:每次只消费一帧;未触发时可从断点重新积累,触发后断点则使整个窗口失败。
|
|
* 输入参数:self——调用方持有的模块实例及当前状态;sequence——顺序号;frame——采样帧。
|
|
* 输出参数:self——更新后的录波状态、环形索引及统计。
|
|
* 返回值:INVALID表示参数或操作状态非法;BUSY表示当前状态不允许继续;DISCONTINUITY表示采样序号不连续;COMPLETE表示本次收齐完整录波窗口;OK表示操作完成。
|
|
* 说明:COMPLETE 表示最后需要的端点已入环;此后读者接管冻结源,采样调用返回 BUSY。
|
|
*/
|
|
IEC60870_FaultRecorderResult_t IEC60870_FaultRecorder_Push(
|
|
IEC60870_FaultRecorder_t *self, uint64_t sequence,
|
|
const IEC60870_FaultRecorderFrame_t *frame)
|
|
{
|
|
bool discontinuity;
|
|
if (!Valid(self) || !Output_Allowed(self, frame, sizeof(*frame))) {
|
|
return IEC60870_FAULT_RECORDER_INVALID;
|
|
}
|
|
if (self->state == IEC60870_FAULT_RECORDER_READY || self->state == IEC60870_FAULT_RECORDER_FAILED) {
|
|
return IEC60870_FAULT_RECORDER_BUSY;
|
|
}
|
|
/* 绝对序号不允许模 2^64 回绕;重复帧、缺帧和乱序都破坏固定采样间隔。 */
|
|
discontinuity = self->count != 0U &&
|
|
(self->last_sequence == UINT64_MAX || sequence != self->last_sequence + 1U);
|
|
if (discontinuity) {
|
|
Increment(&self->discontinuities);
|
|
/* 已触发的窗口不能跨缺帧拼接;尚未触发时则可用当前帧重建连续历史。 */
|
|
if (self->state == IEC60870_FAULT_RECORDER_CAPTURING) {
|
|
self->state = IEC60870_FAULT_RECORDER_FAILED;
|
|
return IEC60870_FAULT_RECORDER_DISCONTINUITY;
|
|
}
|
|
Clear_History(self);
|
|
}
|
|
Append(self, sequence, frame);
|
|
if (self->state == IEC60870_FAULT_RECORDER_CAPTURING && sequence == self->record_last) {
|
|
Complete(self);
|
|
return IEC60870_FAULT_RECORDER_COMPLETE;
|
|
}
|
|
return discontinuity ? IEC60870_FAULT_RECORDER_DISCONTINUITY : IEC60870_FAULT_RECORDER_OK;
|
|
}
|
|
|
|
/**
|
|
* 功能:触发依据采样源绝对序号,与任务调用时间无关;先确认前窗口还在,才登记触发。
|
|
* 输入参数:self——调用方持有的模块实例及当前状态;trigger_sequence——触发采样的绝对序号。
|
|
* 输出参数:self——更新后的录波状态、环形索引及统计。
|
|
* 返回值:INVALID表示参数或操作状态非法;BUSY表示当前状态不允许继续;NO_HISTORY表示故障前历史不足;COMPLETE表示本次收齐完整录波窗口;OK表示操作完成。
|
|
* 说明:支持迟到判据,但不会凭空补齐已经被环覆盖的故障前样本。
|
|
*/
|
|
IEC60870_FaultRecorderResult_t IEC60870_FaultRecorder_Trigger(
|
|
IEC60870_FaultRecorder_t *self, uint64_t trigger_sequence)
|
|
{
|
|
uint64_t first;
|
|
if (!Valid(self)) { return IEC60870_FAULT_RECORDER_INVALID; }
|
|
if (self->state != IEC60870_FAULT_RECORDER_ARMED) {
|
|
Increment(&self->busy_triggers);
|
|
return IEC60870_FAULT_RECORDER_BUSY;
|
|
}
|
|
if (self->count != 0U && trigger_sequence > self->last_sequence) {
|
|
return IEC60870_FAULT_RECORDER_INVALID;
|
|
}
|
|
if (trigger_sequence > UINT64_MAX - self->post_samples) { return IEC60870_FAULT_RECORDER_INVALID; }
|
|
if (self->count == 0U || trigger_sequence < self->pre_samples || trigger_sequence < self->first_sequence) {
|
|
Increment(&self->history_misses);
|
|
return IEC60870_FAULT_RECORDER_NO_HISTORY;
|
|
}
|
|
/* 判据可晚于故障帧到达,但所需前端点必须仍在环中,不能仅检查触发帧存在。 */
|
|
first = trigger_sequence - self->pre_samples;
|
|
if (first < self->first_sequence) {
|
|
Increment(&self->history_misses);
|
|
return IEC60870_FAULT_RECORDER_NO_HISTORY;
|
|
}
|
|
self->record_first = first; self->trigger_sequence = trigger_sequence;
|
|
self->record_last = trigger_sequence + self->post_samples;
|
|
self->state = IEC60870_FAULT_RECORDER_CAPTURING;
|
|
Increment(&self->triggers);
|
|
/* 迟触发时故障后端点也可能已入环,无须等待下一帧即可冻结完整窗口。 */
|
|
if (self->last_sequence >= self->record_last) {
|
|
Complete(self);
|
|
return IEC60870_FAULT_RECORDER_COMPLETE;
|
|
}
|
|
return IEC60870_FAULT_RECORDER_OK;
|
|
}
|
|
|
|
/**
|
|
* 功能:先构造局部快照再一次发布;READY 之外 frame_count=0,防止误把未完成窗口当文件。
|
|
* 输入参数:self——只读模块实例。
|
|
* 输出参数:info——成功时写入的独立结果副本。
|
|
* 返回值:true表示已取得状态快照;false表示实例或输出内存无效,输出不变。
|
|
* 说明:调用方串行访问同一实例,采样数组的存储寿命由调用方负责。
|
|
*/
|
|
bool IEC60870_FaultRecorder_Get_Info(const IEC60870_FaultRecorder_t *self,
|
|
IEC60870_FaultRecorderInfo_t *info)
|
|
{
|
|
IEC60870_FaultRecorderInfo_t result;
|
|
if (!Valid(self) || !Output_Allowed(self, info, sizeof(*info))) { return false; }
|
|
memset(&result, 0, sizeof(result));
|
|
result.state = self->state; result.sample_rate_hz = self->config.sample_rate_hz;
|
|
result.nominal_frequency_hz = self->config.nominal_frequency_hz; result.digital_count = self->config.digital_count;
|
|
result.pre_samples = self->pre_samples; result.post_samples = self->post_samples;
|
|
result.frame_count = self->state == IEC60870_FAULT_RECORDER_READY ? self->record_count : 0U;
|
|
result.trigger_index = self->pre_samples;
|
|
result.first_sequence = self->record_first; result.trigger_sequence = self->trigger_sequence;
|
|
result.last_sequence = self->record_last; result.triggers = self->triggers;
|
|
result.completed = self->completed; result.busy_triggers = self->busy_triggers;
|
|
result.history_misses = self->history_misses; result.discontinuities = self->discontinuities;
|
|
*info = result;
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
* 功能:index 相对于冻结窗口首帧;转换到物理环后按值拷贝,外部不借用可覆盖的帧指针。
|
|
* 输入参数:self——只读模块实例;index——零基索引。
|
|
* 输出参数:frame——成功时写入的独立结果副本。
|
|
* 返回值:true表示已复制指定冻结帧;false表示状态、索引或输出内存不合法,输出不变。
|
|
* 说明:调用方串行访问同一实例,采样数组的存储寿命由调用方负责。
|
|
*/
|
|
bool IEC60870_FaultRecorder_Get_Frame(const IEC60870_FaultRecorder_t *self,
|
|
size_t index, IEC60870_FaultRecorderFrame_t *frame)
|
|
{
|
|
size_t position, remaining;
|
|
if (!Valid(self) || self->state != IEC60870_FAULT_RECORDER_READY ||
|
|
index >= self->record_count || !Output_Allowed(self, frame, sizeof(*frame))) { return false; }
|
|
/* index 属于冻结记录而非当前环的 oldest,导出层无需了解物理回绕位置。 */
|
|
remaining = self->capacity - self->record_start;
|
|
position = index < remaining ? self->record_start + index : index - remaining;
|
|
*frame = self->storage[position];
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
* 功能:调用方确认所有文件读者已结束后,显式放弃本次窗口并重新积累故障前历史。
|
|
* 输入参数:self——调用方持有的模块实例及当前状态。
|
|
* 输出参数:self——更新后的录波状态、环形索引及统计。
|
|
* 返回值:true表示已重新进入空历史ARMED;false表示实例未初始化或为空。
|
|
* 说明:调用方串行访问同一实例,采样数组的存储寿命由调用方负责。
|
|
*/
|
|
bool IEC60870_FaultRecorder_Release(IEC60870_FaultRecorder_t *self)
|
|
{
|
|
if (!Valid(self)) { return false; }
|
|
Clear_History(self);
|
|
return true;
|
|
}
|