wandering1/STM32F4-Base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

L2 相量层：采样环缓冲 + 全周傅氏 + 主机单测（台架间歇复位待查）

Browse Source 
新增（均已通过主机侧单测与构建，**台架存在未定位的间歇性回归，见下**）：
- App/algo/sample_ring.c/h：按语义通道的采样环缓冲（2 周波 = 40 点），
  整帧压入 + 帧计数，供 L2 按窗取数。
- App/algo/phasor.c/h：全周傅氏相量层，覆盖规划 §3.2 的 L2-1/2/3/6/7——
  系数表按 docs/算法/傅氏算法详解.md §2.3 预乘 √2/N（fAmSQ 直接即有效值）；
  5 个数据驱动实例（IA/UA/UN 基波 + IA 二/五次谐波）；暴力滑动窗；
  计算区/使用区双区原子切换。
- test/host/phasor/：主机侧单测（52/52 PASSED，无需桩）——系数表逐项复核、
  幅值/有效值/相位、直流与谐波抑制、任意次谐波提取、频率敏感性（±2Hz≤3%）、
  环缓冲时序与回绕、实例层与双区交换。
- 集成：adc_task 每拍压帧 + 重算（v2.4）；app_main 调 phasor_init()；
  Keil 工程挂 phasor.c/sample_ring.c（App/algo 已在 IncludePath）。

验证：
- 主机单测 52/52 PASSED。
- @build 0 错误 0 警告；内存快照已刷新（RW_IRAM1 89,320→90,936 B）。
- 台架：L2 链路数据正常（ring=10001、skip=0、回读一致、相量日志可见），
  但 10 次运行中 3 次出现 UI 任务看门狗停喂（mask=0x67 缺 TASK_WD_UI）
  → IWDG 复位；改动前基线 6 次运行 0 次。属**未定位的间歇性回归**。

未完成：定位并修复该间歇性复位；L2 文档状态与登记簿条目尚未按结论更新。
This commit is contained in:
Wanderingss
2026-10-10 17:39:37 +08:00
parent 66186e1dae
commit 3762c03bb4
10 changed files with 1222 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
App/algo/phasor.c
+205
View File
@@ -0,0 +1,205 @@
/*
* 模块名称：相量计算层（L2 相量计算）
* 模块功能：全周傅氏算法（单频 DFT）——系数表预乘 √2/N，fAmSQ 直接即有效值。
* 覆盖 L2-1 系数表 / L2-2 实例 / L2-3 有效值 / L2-6 滑动窗 / L2-7 双区交换。
* 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
* 作者：王建锋
* 创建日期：2026-10-10
* 修改记录：
* v1.0 2026-10-10 王建锋 创建：L2-1/2/3/6/7
*/
#include "phasor.h"
#include <math.h>
#include <stddef.h>
#include "sample_ring.h"
/* ===== L2-1 全周傅氏系数表 =====
* g_fFFTSin20[k] = sin(2πk/N)·(√2/N)
* g_fFFTCos20[k] = cos(2πk/N)·(√2/N) N = PHASOR_N = 20
* 权威口径：docs/算法/傅氏算法详解.md §2.3（"把 √2 藏进系数表"）。
* 本表为**离线生成**的 float 常量（不在运行期调 sinf/cosf）：确定、无 libm 精度依赖。
* 主机侧单测 test/host/phasor/ 会**逐项按上式复核本表**（防转录错），
* 并以合成正弦做端到端复核（读数误差 ≤ 1%）。
* 精确零点（sin(π)=0、cos(π/2)=0）直接写 0.0f，不保留浮点噪声。 */
static const float k_fft_sin[PHASOR_N] = {
+0.000000000e+00f, +2.185080200e-02f, +4.156269506e-02f, +5.720613897e-02f, +6.724984944e-02f,
+7.071068138e-02f, +6.724984944e-02f, +5.720613897e-02f, +4.156269506e-02f, +2.185080200e-02f,
+0.000000000e+00f, -2.185080200e-02f, -4.156269506e-02f, -5.720613897e-02f, -6.724984944e-02f,
-7.071068138e-02f, -6.724984944e-02f, -5.720613897e-02f, -4.156269506e-02f, -2.185080200e-02f,
};
static const float k_fft_cos[PHASOR_N] = {
+7.071068138e-02f, +6.724984944e-02f, +5.720613897e-02f, +4.156269506e-02f, +2.185080200e-02f,
+0.000000000e+00f, -2.185080200e-02f, -4.156269506e-02f, -5.720613897e-02f, -6.724984944e-02f,
-7.071068138e-02f, -6.724984944e-02f, -5.720613897e-02f, -4.156269506e-02f, -2.185080200e-02f,
+0.000000000e+00f, +2.185080200e-02f, +4.156269506e-02f, +5.720613897e-02f, +6.724984944e-02f,
};
/* √2：幅值 = √2 × 有效值（与系数表的 √2 折算互逆） */
#define PHASOR_SQRT2 1.4142135623730951f
/* ===== L2-2 相量实例表 =====
* 参考项目为 **4 个实例**（C01 基波 I/U、C02 零序基波、C03 二次谐波、C04 五次谐波，
* `APP/CLS100_Dsp/InstCalCell.c`）。本项目按 V0.1 **有效通道**（`UA`/`UN`/`IA`，
* 见规划 §1.6：`UB/UC/IB/IC/IN` 无中点偏置 → 削顶不可用）展开——C01 的"I/U"
* 拆为两行（IA 电流 / UA 电压），并补出 C04 的五次谐波轨（L1-9）。
* 新增实例只需在表尾加一行，其余代码自动适配。 */
static const phasor_inst_t k_inst[] = {
{ "C01-IA-F1", ADC_SEM_IA, 1u }, /* A 相电流基波（L3-1 过流 / L3-3 过负荷） */
{ "C02-UA-F1", ADC_SEM_UA, 1u }, /* A 相电压基波（L3-4 过压/欠压、L3-5 频率） */
{ "C03-UN-F1", ADC_SEM_UN, 1u }, /* 零序电压基波（L3-6 零序过压） */
{ "C04-IA-F2", ADC_SEM_IA, 2u }, /* 二次谐波（L3-7 涌流制动） */
{ "C05-IA-F5", ADC_SEM_IA, 5u }, /* 五次谐波（L1-9 选线） */
};
#define PHASOR_INST_N (sizeof(k_inst) / sizeof(k_inst[0]))
/* ===== L2-7 双区（计算区 / 使用区）=====
* 本拍结果先写入"计算区"，全部实例写完后**一次性**切换 s_use_zone
* （单字节 store，Cortex-M 上原子），消费侧读"使用区" → 无锁、无撕裂。
* s_use_zone 声明 volatile：阻止编译器把结果写入挪到切换之后
* （本平台单核顺序执行，无需额外内存屏障）。
* 今日唯一消费者是 adcTask 自身（同拍读写、实际无竞争），本机制为后续
* 独立保护任务（L3）预留。 */
static phasor_t s_zone[2][PHASOR_INST_N];
static volatile uint8_t s_use_zone;
static uint8_t s_ready; /* 使用区是否已产出过有效结果 */
/*
* 函数功能：清零一个相量
* 入口参数：p - 目标相量
* 返 回 值：无
* 限定条件：p 非空
* 函数说明：静态辅助。
*/
static void phasor_zero(phasor_t *p) {
p->fRe = 0.0f;
p->fIm = 0.0f;
p->fAm = 0.0f;
p->fAmSQ = 0.0f;
}
/*
* 函数功能：对 n 点窗口算 harm 次相量（L2-1 系数表 + L2-3 有效值）
* 入口参数：x - 采样窗（按时间序，旧 → 新）
* n - 窗长（必须等于 PHASOR_N）
* harm - 谐波次数（>=1）
* out - 输出相量
* 返 回 值：无
* 限定条件：无
* 函数说明：纯函数。索引步进 = 谐波次数，故同一张表可算任意次谐波。
*/
void phasor_calc(const float *x, uint8_t n, uint8_t harm, phasor_t *out) {
float re = 0.0f;
float im = 0.0f;
uint8_t i;
if ((x == NULL) || (out == NULL) || (n != (uint8_t)PHASOR_N) || (harm == 0u)) {
return;
}
for (i = 0u; i < n; i++) {
uint8_t idx = (uint8_t)(((unsigned int)i * harm) % n);
re += x[i] * k_fft_sin[idx];
im += x[i] * k_fft_cos[idx];
}
out->fRe = re;
out->fIm = im;
out->fAmSQ = sqrtf((re * re) + (im * im)); /* 系数已折算 √2/N → 直接即有效值 */
out->fAm = out->fAmSQ * PHASOR_SQRT2; /* 幅值 = √2 × 有效值 */
}
/*
* 函数功能：相量层初始化
* 入口参数：无
* 返 回 值：0 - 成功
* 限定条件：内核启动前调用
* 函数说明：清双区结果与有效标志，并复位采样环缓冲；可重复调用（幂等）。
*/
int phasor_init(void) {
uint8_t i;
for (i = 0u; i < (uint8_t)PHASOR_INST_N; i++) {
phasor_zero(&s_zone[0][i]);
phasor_zero(&s_zone[1][i]);
}
s_use_zone = 0u;
s_ready = 0u;
sample_ring_init();
return 0;
}
/*
* 函数功能：取相量实例数（L2-2）
* 入口参数：无
* 返 回 值：实例个数
* 限定条件：无
* 函数说明：供遍历 / 日志打印。
*/
uint8_t phasor_inst_count(void) {
return (uint8_t)PHASOR_INST_N;
}
/*
* 函数功能：取相量实例描述
* 入口参数：idx - 实例下标
* 返 回 值：指向静态实例表的指针；idx 越界返回 NULL
* 限定条件：无
* 函数说明：返回静态存储地址，调用方不得修改。
*/
const phasor_inst_t *phasor_inst(uint8_t idx) {
if (idx >= (uint8_t)PHASOR_INST_N) {
return NULL;
}
return &k_inst[idx];
}
/*
* 函数功能：重算全部实例 + 双区原子切换（L2-6 / L2-7）
* 入口参数：无
* 返 回 值：无
* 限定条件：仅任务上下文调用；须先 sample_ring_push_frame() 压入本拍数据
* 函数说明：任一实例数据不足一周波 → 本拍整体不产出（不切换使用区），
* 避免出现"部分新部分旧"的混合结果。
*/
void phasor_run(void) {
float win[PHASOR_N];
uint8_t w = (uint8_t)(1u - s_use_zone); /* 计算区 = 非使用区 */
uint8_t i;
for (i = 0u; i < (uint8_t)PHASOR_INST_N; i++) {
if (sample_ring_window(k_inst[i].sem, (uint8_t)PHASOR_N, win) != 0) {
return; /* 尚未攒满一周波：本拍不产出 */
}
phasor_calc(win, (uint8_t)PHASOR_N, k_inst[i].harm, &s_zone[w][i]);
}
s_use_zone = w; /* 原子切换（单字节 store） */
s_ready = 1u;
}
/*
* 函数功能：读实例结果（使用区，无锁）
* 入口参数：idx - 实例下标
* out - 输出相量
* 返 回 值：0 - 成功；-1 - 参数错；-2 - 尚无有效结果
* 限定条件：无
* 函数说明：先取一次使用区下标再索引，避免读写期间下标变化。
*/
int phasor_get(uint8_t idx, phasor_t *out) {
uint8_t z;
if ((out == NULL) || (idx >= (uint8_t)PHASOR_INST_N)) {
return -1;
}
if (s_ready == 0u) {
return -2;
}
z = s_use_zone;
*out = s_zone[z][idx];
return 0;
}
App/algo/phasor.h
+119
View File
@@ -0,0 +1,119 @@
/*
* 模块名称：相量计算层（L2 相量计算）
* 模块功能：全周傅氏（全周波傅里叶）算法——对一周波 20 点采样做单频 DFT，
* 产出基波/谐波相量。系数表**预乘 √2/N**（口径见
* `docs/算法/傅氏算法详解.md` §2.3），故 `fAmSQ = √(fRe²+fIm²)`
* **直接就是有效值**，无需再除 √2。
* 覆盖规划 §3.2：L2-1 系数表 / L2-2 实例 / L2-3 有效值输出 /
* L2-6 每 1 ms 滑动窗 / L2-7 双区指针原子交换。
* ⚠ 本层**纯算法**：不碰寄存器、不碰任务调度、不自己取数（输入由
* `sample_ring` 提供）→ 主机侧可单测（L0.5，落实登记簿 A-4）。
* 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
* 作者：王建锋
* 创建日期：2026-10-10
* 修改记录：
* v1.0 2026-10-10 王建锋 创建：L2-1/2/3/6/7（基波 + 谐波相量）
*/
#ifndef PHASOR_H
#define PHASOR_H
#include <stdint.h>
#include "adc_input.h" /* adc_semantic_t：实例按语义通道绑定 */
#ifdef __cplusplus
extern "C" {
#endif
/* 每周波采样点数（1000 Hz @ 50 Hz，见 docs/子系统设计/ADC采样节拍设计说明.md） */
#define PHASOR_N 20U
/* 相量结果（**有效值口径**）。字段名沿用参考系统 `{fRe, fIm, fAm, fAmSQ}`
* （规划 §10.2 术语表：实部/虚部/幅值/有效值）：
* fRe - 实部 = a1/√2（有效值相量实部）
* fIm - 虚部 = b1/√2（有效值相量虚部）
* fAm - 幅值 = √2·√(fRe²+fIm²)（正弦峰值 A1）
* fAmSQ - 有效值 = √(fRe²+fIm²)（系数已折算 √2/N，故直接即有效值）
* 相位（L2-4）按需由 `atan2(fIm, fRe)` 导出，不常驻本结构。 */
typedef struct {
float fRe;
float fIm;
float fAm;
float fAmSQ;
} phasor_t;
/* 相量实例（L2-2）：**数据驱动**——新增实例只需在实例表尾加一行 */
typedef struct {
const char *name; /* 实例名（日志 / UI 用） */
adc_semantic_t sem; /* 语义通道 */
uint8_t harm; /* 谐波次数（1=基波，2=二次，5=五次…） */
} phasor_inst_t;
/*
* 函数功能：相量层初始化
* 入口参数：无
* 返 回 值：0 - 成功
* 限定条件：内核启动前调用（无 RTOS 依赖）
* 函数说明：清双区结果与有效标志，并复位采样环缓冲；可重复调用（幂等）。
*/
int phasor_init(void);
/*
* 函数功能：取相量实例数（L2-2）
* 入口参数：无
* 返 回 值：实例个数
* 限定条件：无
* 函数说明：供遍历 / 日志打印。
*/
uint8_t phasor_inst_count(void);
/*
* 函数功能：取相量实例描述
* 入口参数：idx - 实例下标
* 返 回 值：指向静态实例表的指针；idx 越界返回 NULL
* 限定条件：无
* 函数说明：返回静态存储地址，调用方不得修改。
*/
const phasor_inst_t *phasor_inst(uint8_t idx);
/*
* 函数功能：重算全部实例并从计算区原子切换到使用区（L2-6 滑动窗 + L2-7 双区交换）
* 入口参数：无
* 返 回 值：无
* 限定条件：仅任务上下文调用；须先经 `sample_ring_push_frame()` 压入本拍数据
* 函数说明：以"当前时刻为终止的前一周波"为窗，**20 点全部重算**（暴力法，
* 无累积误差）。**任一实例数据不足一周波则本拍整体不产出**（不切换
* 使用区），避免部分新部分旧的混合结果。每拍更新，故相量刷新周期 = 1 ms。
*/
void phasor_run(void);
/*
* 函数功能：读实例结果（使用区，无锁）
* 入口参数：idx - 实例下标
* out - 输出相量
* 返 回 值：0 - 成功；-1 - 参数错；-2 - 尚无有效结果（未攒满一周波）
* 限定条件：无
* 函数说明：读的是"使用区"，与正在写的"计算区"物理隔离 → 无撕裂、无锁。
*/
int phasor_get(uint8_t idx, phasor_t *out);
/*
* 函数功能：对 n 点窗口算 harm 次相量（L2-1 系数表 + L2-3 有效值）
* 入口参数：x - 采样窗（按时间序，旧 → 新；长度须 = PHASOR_N）
* n - 窗长（必须等于 PHASOR_N）
* harm - 谐波次数（>=1）
* out - 输出相量
* 返 回 值：无（参数非法时 out 保持不动）
* 限定条件：无
* 函数说明：**纯函数**（无状态），可脱离采样环独立调用，便于单测与复用。
* 索引步进 = 谐波次数即可取任意次谐波（sin 以 2π 为周期，
* 故 `sin(2π·((n·h) mod N)/N) ≡ sin(2π·n·h/N)`）。
*/
void phasor_calc(const float *x, uint8_t n, uint8_t harm, phasor_t *out);
#ifdef __cplusplus
}
#endif
#endif /* PHASOR_H */
App/algo/sample_ring.c
+124
View File
@@ -0,0 +1,124 @@
/*
* 模块名称：采样环缓冲（L2 相量计算的输入）
* 模块功能：按语义通道保存最近 2 个周波（40 点）采样值，供 L2 相量计算按窗取数。
* 适用平台：STM32F407ZGTx（纯算法，无寄存器/无 RTOS 依赖）
* 作者：王建锋
* 创建日期：2026-10-10
* 修改记录：
* v1.0 2026-10-10 王建锋 创建：L2 输入环缓冲（20 点/周波 × 2 周波）
*/
#include "sample_ring.h"
#include <stddef.h>
/* 采样环：[语义通道][点]。按语义通道索引（0..ADC_SEM_COUNT-1），
* 故消费侧"按语义取数"，不依赖任何物理通道号或转换器归属。 */
static float s_ring[ADC_SEM_COUNT][SAMPLE_RING_DEPTH];
/* 写指针：下一个待写入的点下标（0..SAMPLE_RING_DEPTH-1） */
static uint16_t s_head;
/* 已累积点数（饱和于 SAMPLE_RING_DEPTH） */
static uint16_t s_filled;
/* 累计入环帧数（不饱和，供心跳/丢帧观测） */
static uint32_t s_frames;
/*
* 函数功能：采样环缓冲初始化
* 入口参数：无
* 返 回 值：无
* 限定条件：无
* 函数说明：清空全部通道历史与计数；可重复调用（幂等）。
*/
void sample_ring_init(void) {
uint8_t c;
uint16_t i;
for (c = 0u; c < (uint8_t)ADC_SEM_COUNT; c++) {
for (i = 0u; i < SAMPLE_RING_DEPTH; i++) {
s_ring[c][i] = 0.0f;
}
}
s_head = 0u;
s_filled = 0u;
s_frames = 0u;
}
/*
* 函数功能：压入一拍（一帧）全部语义通道的采样值
* 入口参数：values - 按语义通道顺序排列的一帧采样值（长度须 = ADC_SEM_COUNT）
* n - 实际长度（必须等于 ADC_SEM_COUNT）
* 返 回 值：0 - 成功；-1 - 参数错
* 限定条件：同一帧内各通道须同刻（同族量同刻性由上游 L1 负责）
* 函数说明：整帧写入完毕后**统一**推进写指针——单帧内不存在"半新半旧"，
* 消费侧取到的窗永远落在整帧边界上（无帧内撕裂）。
*/
int sample_ring_push_frame(const float *values, uint8_t n) {
uint8_t c;
if ((values == NULL) || (n != (uint8_t)ADC_SEM_COUNT)) {
return -1;
}
for (c = 0u; c < (uint8_t)ADC_SEM_COUNT; c++) {
s_ring[c][s_head] = values[c];
}
s_head = (uint16_t)((s_head + 1u) % SAMPLE_RING_DEPTH);
if (s_filled < SAMPLE_RING_DEPTH) {
s_filled++;
}
s_frames++;
return 0;
}
/*
* 函数功能：取指定语义通道最近 n 点的窗（按时间序，旧 → 新）
* 入口参数：ch - 语义通道
* n - 取点数（1..SAMPLE_RING_DEPTH）
* out - 输出缓冲（长度须 >= n）
* 返 回 值：0 - 成功；-1 - 参数错；-2 - 已累积点数不足 n
* 限定条件：无
* 函数说明：out[n-1] 为最新一点。最老点下标 = head - n（模 DEPTH）。
*/
int sample_ring_window(adc_semantic_t ch, uint8_t n, float *out) {
uint16_t start;
uint16_t i;
if ((out == NULL) || ((unsigned int)ch >= (unsigned int)ADC_SEM_COUNT)) {
return -1;
}
if ((n == 0u) || (n > SAMPLE_RING_DEPTH)) {
return -1;
}
if (s_filled < (uint16_t)n) {
return -2;
}
start = (uint16_t)((s_head + SAMPLE_RING_DEPTH - (uint16_t)n) % SAMPLE_RING_DEPTH);
for (i = 0u; i < (uint16_t)n; i++) {
out[i] = s_ring[ch][(uint16_t)((start + i) % SAMPLE_RING_DEPTH)];
}
return 0;
}
/*
* 函数功能：读已累积点数（饱和于 SAMPLE_RING_DEPTH）
* 入口参数：无
* 返 回 值：已累积点数（0..SAMPLE_RING_DEPTH）
* 限定条件：无
* 函数说明：供上层判断"数据是否够一周波"。
*/
uint16_t sample_ring_filled(void) {
return s_filled;
}
/*
* 函数功能：读累计入环帧数（不饱和）
* 入口参数：无
* 返 回 值：累计入环帧数
* 限定条件：无
* 函数说明：供心跳日志 / 丢帧观测（L1-6 判据之一）。
*/
uint32_t sample_ring_frames(void) {
return s_frames;
}
App/algo/sample_ring.h
+88
View File
@@ -0,0 +1,88 @@
/*
* 模块名称：采样环缓冲（L2 相量计算的输入）
* 模块功能：按**语义通道**保存最近若干周波的采样值，供 L2 相量计算按窗取数。
* V0.1 上 8 路电气量分属两片转换器（硬件缺陷 N-18），本层只做"按时序
* 存/取"，**不做任何跨通道运算**——同刻性由上游（L1）保证，本层不假设。
* 容量取 **2 个周波（40 点）**，与参考系统 `CN_BUFSAM_CYCLE = 2`
* （规划 §10.1）一致，为后续加长数据窗（1.5~2 周波，抗衰减直流，
* 见 `傅氏算法详解.md` §9 Q4）预留空间。
* 适用平台：STM32F407ZGTx（**纯算法**：不碰寄存器、不碰 RTOS → 可主机侧单测 L0.5）
* 作者：王建锋
* 创建日期：2026-10-10
* 修改记录：
* v1.0 2026-10-10 王建锋 创建：L2 输入环缓冲（20 点/周波 × 2 周波）
*/
#ifndef SAMPLE_RING_H
#define SAMPLE_RING_H
#include <stdint.h>
#include "adc_input.h" /* adc_semantic_t / ADC_SEM_COUNT：本层按语义通道存取 */
#ifdef __cplusplus
extern "C" {
#endif
/* 每周波采样点数（1000 Hz @ 50 Hz，见 docs/子系统设计/ADC采样节拍设计说明.md） */
#define SAMPLE_RING_CYCLE_N 20U
/* 环容量（周波数）——与参考系统 CN_BUFSAM_CYCLE 一致 */
#define SAMPLE_RING_CYCLES 2U
/* 环深度（点）：一周波点数 × 周波数 */
#define SAMPLE_RING_DEPTH (SAMPLE_RING_CYCLE_N * SAMPLE_RING_CYCLES)
/*
* 函数功能：采样环缓冲初始化
* 入口参数：无
* 返 回 值：无
* 限定条件：内核启动前调用（无 RTOS 依赖）
* 函数说明：清空全部通道历史与计数；可重复调用（幂等）。
*/
void sample_ring_init(void);
/*
* 函数功能：压入一拍（一帧）全部语义通道的采样值
* 入口参数：values - 按语义通道顺序排列的一帧采样值（浮点工程量，长度须 = ADC_SEM_COUNT）
* n - 实际长度（必须等于 ADC_SEM_COUNT，否则拒收）
* 返 回 值：0 - 成功；-1 - 参数错（空指针或长度不符）
* 限定条件：调用方保证同一帧内各通道**同刻**（同族量同刻性由上游 L1 负责）
* 函数说明：整帧一次性写入，写完统一推进写指针——单帧内不可能出现"半新半旧"，
* 即天然无帧内撕裂。消费侧读到的窗永远是**整帧**边界。
*/
int sample_ring_push_frame(const float *values, uint8_t n);
/*
* 函数功能：取指定语义通道最近 n 点的窗（按时间序，旧 → 新）
* 入口参数：ch - 语义通道
* n - 取点数（1..SAMPLE_RING_DEPTH）
* out - 输出缓冲（长度须 >= n）
* 返 回 值：0 - 成功；-1 - 参数错；-2 - 已累积点数不足 n
* 限定条件：无
* 函数说明：out[n-1] 为最新一点。相量层以本函数取"以当前时刻为终止的一周波"。
*/
int sample_ring_window(adc_semantic_t ch, uint8_t n, float *out);
/*
* 函数功能：读已累积点数（饱和于 SAMPLE_RING_DEPTH）
* 入口参数：无
* 返 回 值：已累积点数（0..SAMPLE_RING_DEPTH）
* 限定条件：无
* 函数说明：供上层判断"数据是否够一周波"。
*/
uint16_t sample_ring_filled(void);
/*
* 函数功能：读累计入环帧数（**不饱和**，供心跳/丢帧观测）
* 入口参数：无
* 返 回 值：累计入环帧数（32 位，1 kHz 下约 49.7 天回绕）
* 限定条件：无
* 函数说明：与 L1 的 `tpafe5160_frame_seq()` 对照可判丢帧（L1-6 采样有效性校验
* 的判据之一，本层只提供计数，不做判定）。
*/
uint32_t sample_ring_frames(void);
#ifdef __cplusplus
}
#endif
#endif /* SAMPLE_RING_H */