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

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;
}