wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
Files
8744c833e58b2d0e1b3c9901ab8642bf898820e5
STM32F4-Base/App/algo/adc_input.h
T
wandering1 593c5d0c84 refactor(编号): 采集链分层 L1/L1.5/L2/L2.5/L3/L4/L5 → 语义名（批次 1） 
用户裁定（2026-10-28）：L1/L1.5/L2/L2.5/L3 这套层号「谁能看懂」，改用语义名。
映射（同一批定稿，含 L4/L5）：
  L1   → 语义取数与有效性
  L1.5 → 标定折算
  L2   → 全周傅氏相量
  L2.5 → 测频与遥测快照
  L3   → 保护判据
  L4   → 出口与记录
  L5   → 动作留痕

实测规模：384 站点 / 62 文件（App/algo、App/task、test/host 六个套件、docs/算法、
产品需求、架构总览、启动顺序、ADC 采样节拍、IEC104 上行、采集短板评测、内存管理、
AGENTS.md、README.md、docs/README.md、.pre-commit-config.yaml 与 scripts 里的注释）。

改法（不是全局替换，逐模式有上下文规则）：
- 先吃同位语再落裸词：L1 有效性校验 → 语义取数与有效性校验、L2 相量层 → 全周傅氏
  相量层、L3 保护 → 保护判据、L2.5 遥测快照 → 测频与遥测快照，避免「保护判据保护判据」
  这类重复（第一版就是这么坏掉的，已整体回滚重做）。
- .c/.h 只改注释：先把字符串字面量切出去（引号数为奇数的跨行注释按整行处理），
  C 字符串里的 L2-in ring 之类原样保留——AGENTS 铁律「字符串字面量必须纯 ASCII」。
- 层内条目号（L1-3 / L2-3 这类）**本批不动**，属批次 2；另外三族（UI 菜单层级
  L0~L3、链路延迟分段 L1~L8、CubeMX 防丢失三层）也不动，属批次 3。
- 顺手修的措辞：范围写法 L1~L3 → 「分层（语义取数与有效性 → 保护判据）」、
  CI 段「不含 L1/L2/L3」→「不含采集链分层」、目录地图里同一处并列表述。

验证：@build 0 错 0 警（Code=236456，与改前逐字节同尺寸——纯注释改动）；
内存布局配图已按新脚本重生成（自检通过）；doc-links --all --sections-strict 通过
（195 文档）；mojibake / bom-guard / coding-standard / 新编号门禁自查 全 rc=0；
git diff --check 干净。
2026-10-28 13:04:02 +08:00

170 lines
7.8 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.
/*
* 模块名称：ADC 输入层（语义取数与预处理）
* 模块功能：把两片转换器的原始码值按**语义**（UA/UB/UC/UN/IA/IB/IC/IN/温度）统一
* 暴露，使上层（UI / 自检 / 保护算法）**按语义取数，不写死下标**：
* ① 语义通道映射表（通道语义映射）——权威口径 docs/硬件平台/ADC通道映射说明.md；
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* ② STM32 ADC1 9 通道采样（STM32 ADC1 启动与扫描）——由 **TIM3 TRGO 硬件触发 + DMA 双缓冲
* 搬运**，本层只消费、不触发、不等待。
* V0.1 上 8 路电气量分属两片转换器（硬件缺陷：双转换器无共同采样触发）：UA/UN/IA 走
* TPAFE5160（16 位 / ±5 V 双极性），UB/UC/IB/IC/IN 走 STM32 ADC1
* （12 位 / 0~3.3 V 单极性）。V0.2 改版（8 路电气量全部接 TPAFE）
* 只改映射表内容，本层 API 与上层语义不动。
* 适用平台：STM32F407ZGTx + TPAFE5160
* 作者：王建锋
* 创建日期：2026-10-10
* 修改记录：
* v1.0 2026-10-10 王建锋 创建：STM32 ADC1 启动与扫描（STM32 ADC1 扫描）+ 通道语义映射（语义映射）
* v2.0 2026-10-10 王建锋 STM32 侧改 TIM3 TRGO 硬件触发 + DMA 双缓冲消费：
* 消除逐通道轮询的 2 ms 忙等；节拍源 TIM6 -> TIM3
* （换源判据：F4 上 ADC1 收不到 TIM6/TIM7 的 TRGO，见
* docs/子系统设计/ADC采样节拍设计说明.md §3.2）；新增
* adc_input_stm32_seq() / _hw_errs()
* v2.1 2026-10-21 王建锋 adc_input_stm32_gaps() 单位由「次数」改为「帧点数」，
* 与判定层 adc_health_tpafe_gaps() 同单位
*/
#ifndef ADC_INPUT_H
#define ADC_INPUT_H
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* 语义通道（V0.1：8 路电气量 + 温度）。枚举值即语义编号，顺序不得随意变更；
* 备用通道（RESERVED）不接入语义，故不在此枚举内。 */
typedef enum {
ADC_SEM_UA = 0, /* A 相电压（TPAFE） */
ADC_SEM_UB, /* B 相电压（STM32） */
ADC_SEM_UC, /* C 相电压（STM32） */
ADC_SEM_UN, /* 零线电压（TPAFE） */
ADC_SEM_IA, /* A 相电流（TPAFE） */
ADC_SEM_IB, /* B 相电流（STM32） */
ADC_SEM_IC, /* C 相电流（STM32） */
ADC_SEM_IN, /* 零线电流（STM32） */
ADC_SEM_TEMP, /* 温度（STM32，V_ZL2） */
ADC_SEM_COUNT /* 语义通道数（哨兵） */
} adc_semantic_t;
/* 数据来源：V0.1 的 8 路电气量分属两片转换器（双转换器无共同采样触发） */
typedef enum {
ADC_SRC_TPAFE = 0, /* TPAFE5160：16 位、±5 V 双极性、8 通道同步 */
ADC_SRC_STM32 /* STM32 ADC1：12 位、0~3.3 V 单极性、9 通道顺序扫描 */
} adc_source_t;
/* 语义通道 → 物理通道描述 */
typedef struct {
adc_source_t source; /* 数据来源 */
uint8_t index; /* TPAFE 源：驱动 buf 下标 0..7；STM32 源：ADC1 通道号 0..15 */
} adc_channel_desc_t;
/* TPAFE5160 一帧通道数（= 驱动 buf 长度） */
#define ADC_INPUT_TPAFE_CH_NUM 8U
/* STM32 ADC1 顺序扫描通道数（Rank 1..9） */
#define ADC_INPUT_STM32_CH_NUM 9U
/* STM32 ADC1 最近一次取帧状态码（DMA 消费，已无"轮询超时"这一档） */
#define ADC_INPUT_RC_OK (0) /* 取到新一帧 */
#define ADC_INPUT_RC_START (-1) /* HAL_ADC_Start_DMA 挂载失败 */
#define ADC_INPUT_RC_STALL (-2) /* 本拍无新帧（TIM3 未启动 / ADC 停摆 / DMA 出错） */
#define ADC_INPUT_RC_NOT_RUN (-3) /* 尚未取过帧 */
/*
* 函数功能：ADC 输入层初始化
* 入口参数：无
* 返 回 值：0 - 成功；-1 - 语义映射表自检失败（映射指向了不会被扫描的通道）；
* -2 - STM32 ADC1 的 DMA 挂载失败
* 限定条件：内核启动前调用（无 RTOS 依赖）；STM32 ADC1 外设已由 MX_ADC1_Init 配好
* 函数说明：清缓冲与统计 + 映射表自洽性自检 + 挂载一次 ADC1 DMA（此后转换由
* TIM3 TRGO 硬件触发、DMA 自动搬运）。须在启动采样节拍之前调用。
*/
int adc_input_init(void);
/*
* 函数功能：采集一拍（TPAFE 原子快照 + 消费一帧 STM32 ADC1 DMA 采样）
* 入口参数：无
* 返 回 值：TPAFE 快照结果（1=有新帧 0=无新帧 -1=参数错）；STM32 侧状态另见
* adc_input_stm32_rc() / adc_input_stm32_seq()
* 限定条件：仅**任务上下文**调用（TPAFE 快照走临界区）
* 函数说明：本函数只搬运原始码值，不做标定/运算；STM32 侧**零忙等**（不触发、
* 不等待转换）。STM32 侧无新帧不阻断 TPAFE 快照，也不影响返回值语义。
* ⚠ STM32 侧数据滞后 1 拍（乒乓双缓冲固有延迟，9 路一致）。
*/
int adc_input_poll(void);
/*
* 函数功能：取语义通道的物理描述
* 入口参数：ch - 语义通道
* 返 回 值：指向静态描述表的指针；ch 越界返回 NULL
* 限定条件：无
* 函数说明：供自检注入 / UI 通道序等需要"语义 → 物理通道"映射的场景使用。
*/
const adc_channel_desc_t *adc_input_desc(adc_semantic_t ch);
/*
* 函数功能：读取语义通道的原始码值（未标定）
* 入口参数：ch - 语义通道
* out - 输出原始码值（TPAFE 侧为 16 位二进制补码；STM32 侧为 0..4095）
* 返 回 值：0 - 成功；-1 - 参数错；-2 - 该来源当前无有效数据
* 限定条件：无
* 函数说明：消费侧取数的唯一入口（按语义，不写死下标）。取数前须先成功
* adc_input_poll() 一次。
*/
int adc_input_raw(adc_semantic_t ch, int32_t *out);
/*
* 函数功能：读取 STM32 ADC1 最近一次取帧状态码
* 入口参数：无
* 返 回 值：ADC_INPUT_RC_xxx
* 限定条件：无
* 函数说明：供心跳日志 / 自检观测 STM32 侧健康度。
*/
int adc_input_stm32_rc(void);
/*
* 函数功能：读取 STM32 ADC1 停摆故障累计次数
* 入口参数：无
* 返 回 值：DMA 挂载失败次数 + "连续 >=2 拍无新帧"的次数
* 限定条件：无
* 函数说明：单调递增，供心跳日志观测。单拍无新帧（消费者相位伪影）不计入。
*/
uint32_t adc_input_stm32_errs(void);
/*
* 函数功能：读取 STM32 ADC1 累计丢帧点数
* 入口参数：无
* 返 回 值：Σ(完成计数每次前进的超出部分)，即没被消费就被覆盖掉的帧数
* 限定条件：无
* 函数说明：与 errs 分开——gap = 消费者超拍（单拍耗时 > 1 ms），
* err = 节拍源/ DMA 停摆。两类故障处置不同，混在一起就查不了。
* 单位与判定层 adc_health_tpafe_gaps() 一致（帧点数），心跳里可直接对比；
* 2026-10-21 之前的固件该字段是"次数"口径。
*/
uint32_t adc_input_stm32_gaps(void);
/*
* 函数功能：读取 STM32 ADC1 的 DMA 整帧完成计数
* 入口参数：无
* 返 回 值：DMA 半区/整区完成中断的累计次数（正常时每拍 +1）
* 限定条件：无
* 函数说明：与 tpafe5160_frame_seq() 对称的 STM32 侧"节拍是否还在喂数据"观测量。
*/
uint32_t adc_input_stm32_seq(void);
/*
* 函数功能：读取 STM32 ADC1 的 HAL 层错误回调累计次数
* 入口参数：无
* 返 回 值：HAL_ADC_ErrorCallback 触发次数（DMA 传输错误等）
* 限定条件：无
* 函数说明：与 adc_input_stm32_errs() 分开计数，用于区分"节拍源停了"与"DMA 出错"。
*/
uint32_t adc_input_stm32_hw_errs(void);
#ifdef __cplusplus
}
#endif
#endif /* ADC_INPUT_H */
Reference in New Issue View Git Blame Copy Permalink