wandering1
3675b89e8e
采样板注入 Ua=5V/Ia=0.5A 读数偏小，根因是固件只输出引脚电压、 缺「端子→引脚」变比。折算改三维： 工程量 = (code + b) × k[µV/码] × 1e-6 × r k 保持 ROM 引脚 LSB，b 为零点，r 为端子变比（int32 Q16）。 变比不能并进 k：UA 端子域 k 达 1.5e5 µV/码、Q16 溢出 int32； r 单独存 Q16 不溢出。两点标定改标 r，k 仍是板级事实。 - 新开单段 [adc_cal_sec]（8 键 r_ua..r_in），cfg 段数达 8/8 上限 - 一次变比复用 prot_set 四项，不新开段；r=0 表示本路不折算 - ROM 默认带台架实测变比（电压族 1000、电流族 29.4118）， 烧进固件即显二次值；VALID 仍须两点标定，两者互不派生 - eng 判据改「每路要么已配变比、要么削顶不显示」，不再看 VALID - 104 地址 0x8050~0x8057 写 r，run_par_cal_r_set 写值与置脏同函数 - 录波 v2：通道表加 int32 r_q16，头 128→160、整段 5250→5282； code_to_milli 用余数分解换等价单次圆整，20 万组大整数对拍 0 不符 - 文档同步：采集与算法层/通道映射/故障录波/网络配置/配置文件/ 产品需求/内存台账，历史带日期实测数字按冻结口径不改 - 单测 13 套全绿，/keil-build 0 错误 0 警告（256024/31760/ 2080/152368），RAM 实测回填内存内容分配策略 §6.1
403 lines
28 KiB
C
403 lines
28 KiB
C
/*
|
||
* 模块名称：通道标定与量纲折算（标定折算，「数据可信」标定折算与落盘整定）
|
||
* 模块功能：把 adc_input 的原始码值折算成工程量——模型与系数口径的唯一落点：
|
||
* 工程量 = (code + b) × k_f × r_f
|
||
* k_f = k[µV/码] × 1e-6（前端斜率，ROM 固化的板级事实）
|
||
* r_f = r[Q16] / 65536（端子→引脚变比，现场标定产物；r = 0 = 本路不折算）
|
||
* 三维系数各管一件事，**不许合并**：
|
||
* k 管「引脚电压 ↔ 码值」——板级量程事实（TPAFE 152.59 µV/码、STM32 805.66 µV/码），
|
||
* 由 ROM 固化，合法带 = ROM × [0.5, 2.0]（只容纳晶体/基准的板间差）；
|
||
* b 管零点偏移（码值，±ADC_CAL_B_MAX）；
|
||
* r 管「端子二次值 ↔ 引脚电压」——由端子/子板分压与 CT 负担电阻决定，
|
||
* 出厂默认按台架实测反算（电压 1000 V/V、电流 29.4118 A/V），
|
||
* 两点标定今后标的就是它。
|
||
* 为什么必须分开：把变比折进 k 会溢出存储口径——UA 端子域 k = 152 587.9 µV/码，
|
||
* Q16 = 1.0e10 超出 int32 上限 2.147e9；而 r 单独存 Q16 完全够（1000 → 65 536 000）。
|
||
* 合并还会把「硬件分压比」伪装成「前端斜率」，正是
|
||
* docs/硬件平台/ADC通道映射说明.md §7.2 反对的「用系数凑硬件」。
|
||
* k / b / r 三份 RAM 副本注册进 cfg_file 引擎（[adc_cal] / [adc_cal_ofs] /
|
||
* [adc_cal_sec] 三段，布局见 docs/算法/采集与算法层设计说明.md §13.8）；
|
||
* **不挂回调**——RAM 副本即生效值，逐点折算现取现用（1 kHz × 9 通道 = 9k 次/秒
|
||
* 浮点乘，可忽略）。
|
||
* 三态可用性：ADC_CAL_F_VALID（该路已两点标定确认）与
|
||
* ADC_CAL_F_CLIPPED（V0.1 硬件削顶）由 adc_cal_flags() 单点查询，
|
||
* 104 / UI / 保护闭锁（未标定即闭锁）共用（docs/算法/采集与算法层设计说明.md §13.3）。
|
||
* **未标定闭锁的判定本身也归本层**（`adc_cal_prot_blocked()`）：它讲的是
|
||
* 「这几路标定齐了没」，属标定层事实，不是任务编排逻辑——保护任务与 UI
|
||
* 组装器都只是它的消费者（道F task-16 把此前的两份实现收成一份）。
|
||
* ⚠ 两个**互不派生**的事实，别互相反推：
|
||
* · 数值量纲由 r 决定——r ≠ 0 的通道，adc_cal_apply() 输出的就是二次值（V 或 A）；
|
||
* · VALID 由两点标定置位——它回答"这个数准不准"，回答不了"这个数是什么单位"。
|
||
* 屏面第 7 行的量纲标签（eng）只看前者，保护闭锁只看后者。
|
||
* 一次值（eng=2）仍留预留：其变比的家是 prot_set 已在册的
|
||
* PS_PT_PRI/PS_PT_SEC 与 PS_CT_PRI/PS_CT_SEC 四项（**不再新开 cfg 段**，
|
||
* 否则同一事实两个真源），当前无消费者，故本层不产出一次值。
|
||
* TEMP 不参与线性标定（决策 5），adc_cal_apply() 原样透传码值。
|
||
* 本层**纯算法 + 纯数据**：不碰寄存器、不等事件；adc_cal_init() 内核前
|
||
* 可调（注册进引擎必须先于 cfg_file_load，FTP 鉴权确立的契约）；apply/flags
|
||
* 任意上下文可读（cfg RAM 副本 4 字节对齐字读写在 Cortex-M4 上原子，
|
||
* 与 defaultTask 的 load/poll 复位存在 µs 级混窗——设计接受，见 .c 头）。
|
||
* 适用平台：STM32F407ZGTx（Cortex-M4F）；主机侧纯逻辑单测 test/host/adc_cal/
|
||
* 作者：DTU 项目组
|
||
* 创建日期：2026-10-25（道A 标定折算与落盘整定）
|
||
* 修改记录：
|
||
* v1.0 2026-10-25 DTU 项目组 创建：Q16 系数/零点 + 折算/flags/集
|
||
* v1.1 2026-10-25 DTU 项目组 运行参数段：+adc_cal_b_codes()（run_par 回显/RMW 用）
|
||
* v1.2 2026-10-26 DTU 项目组 道F task-16：+adc_cal_prot_blocked()——「UA/UN/IA
|
||
* 三路 VALID 是否齐」这份判据停走条件从
|
||
* protect_task.c 与 ui_data_feed.c 的两份重复实现收成本层
|
||
* 单点（DTU_BENCH 旁路同时收成一处）
|
||
* v1.3 2026-10-29 DTU 项目组 故障录波 task-2：新增 adc_cal_k_q16()——k 的 int32
|
||
* Q16 原值直读口（adc_cal_k_uv 的孪生）。录波段头 k 字段
|
||
* 是 LSB 精确记账，float 在 5.28e7 码字上掉尾数，
|
||
* 禁止经浮点反推（docs/子系统设计/故障录波设计说明.md §6.3）
|
||
* v2.0 2026-11-11 DTU 项目组 新增变比维：折算改 (code+b)×k×1e-6×r，
|
||
* r 存新段 [adc_cal_sec]（int32 Q16，0 = 本路不折算）。
|
||
* 理由 = 端子域 k 的 Q16 溢出 int32（UA 152587.9 µV/码
|
||
* → 1.0e10），变比并进 k 这条路不通；且变比是硬件
|
||
* 事实、k 是前端斜率，混一起就是「用系数凑硬件」。
|
||
* 同步：adc_cal_two_point() 改标 r（k 由 ROM 固化）、
|
||
* +adc_cal_ratio_q16()/+adc_cal_ratio()/+adc_cal_ratio_configured()
|
||
* +adc_cal_set_ratio()
|
||
*/
|
||
#ifndef ADC_CAL_H
|
||
#define ADC_CAL_H
|
||
|
||
#include <stdint.h>
|
||
|
||
#include "adc_input.h" /* adc_semantic_t（语义通道编号 = 系数表下标口径） */
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* 通道可用性标志（adc_cal_flags() 返回值位） */
|
||
#define ADC_CAL_F_VALID (0x01u) /* 该路已两点标定确认（k/b/r 合法带内 → 读数可信） */
|
||
#define ADC_CAL_F_CLIPPED (0x02u) /* 硬件削顶（V0.1 STM32 侧单极性无偏置）→ 交流量不可信 */
|
||
|
||
/*
|
||
* ROM 默认系数（int32 Q16 = µV/码 × 65536，量程口径冻结定死的引脚侧口径）：
|
||
* TPAFE ±5 V 档：10 V 跨度 / 65536 码 = 152.587890625 µV/码 → ×65536 = 10,000,000（整）
|
||
* STM32 0~3.3 V：3.3 V / 4096 码 = 805.6640625 µV/码 → ×65536 = 52,800,000（整）
|
||
* 两个默认值在 Q16 下**无舍入**（系数定点舍入项从误差预算里抹掉，
|
||
* 选型依据 → docs/算法/采集与算法层设计说明.md §13.2）
|
||
*/
|
||
#define ADC_CAL_K_Q16_TPAFE (10000000L)
|
||
#define ADC_CAL_K_Q16_STM32 (52800000L)
|
||
|
||
/*
|
||
* ROM 默认变比（int32 Q16 = 比值 × 65536）——**出厂就编进镜像，不是缺省 0**：
|
||
* 电压族 1000.0 V/V → 65 536 000（Q16 无舍入）
|
||
* 电流族 29.4118 A/V → 1 927 532（= 29.4118 × 65536，回落 29.41180，相对误差 < 2e-7）
|
||
* 出处 = 2026-11-11 台架实测反算（继保仪注 UA 端子 5.000 V → 屏上 0.005 V，
|
||
* 5.000/0.005 = 1000.0；注 IA 端子 0.500 A → 屏上 0.017 V，0.5/0.017 = 29.4118），
|
||
* 电流族与 docs/硬件平台/ADC通道映射说明.md §7.2 的登记值精确吻合。
|
||
* ⚠ 电压族的 1000.0 与 §7.2 早先按子板参数算定的 606.06 **不一致**——606.06 的依据是
|
||
* 200 kΩ/330 Ω 假定值，而台架读数差 60 %（0.005 vs 0.008），远超屏面分辨率，
|
||
* 故以实测为准；§7.2 已按本次结论改写（子板原理图仍不在仓库，见该节「复核边界」）。
|
||
* ⚠ 这两个数是**单点粗测**（5 V 注入只有 33 码，1 LSB = 3 %），
|
||
* 变比真值区间约 909~1111（电压族）；送检前必须用标准源两点标定重写 r（见
|
||
* adc_cal_two_point() 的语义变更）。
|
||
* r = 0 是合法值，语义 = 「本路不折算，输出停在 ADC 引脚电压」——TEMP 恒此态，
|
||
* 也是现场关掉某路折算的显式手段（不是 1.0）。
|
||
*/
|
||
#define ADC_CAL_R_Q16_VOLT (65536000L) /* 1000.0 V/V */
|
||
#define ADC_CAL_R_Q16_CURR (1927532L) /* 29.4118 A/V */
|
||
|
||
/* 变比合法带（Q16）：**0 = 本路不折算**，或落在 [ADC_CAL_R_MIN, ADC_CAL_R_MAX]（比值 1.0 ~ 32767.99）。
|
||
* 为什么用绝对带而不是像 k 那样用 ROM×[0.5,2.0]：k 的窄带是为了容纳晶体/基准的板间差，
|
||
* 而 r 是现场标定量（不同 CT/PT 变比差几个数量级），窄带没有意义。下界取 1.0 是因为
|
||
* 分压与负担电阻都只会把端子值变小——比「比值 < 1」更可能的是把 mV 当 V 填错。
|
||
* 上界 = int32 上限（Q16 下最大比值 32767.99），1000 与 29.41 都远在带内。
|
||
* ⚠ 工程实现上**只在下界用 ADC_CAL_R_MIN 比较**：r 是 int32，`r > ADC_CAL_R_MAX`
|
||
* 是恒假分支（cppcheck 报 knownConditionTrueFalse）。ADC_CAL_R_MAX 留给
|
||
* int64 中间量（两点标定算出的 kq / 除法前的分子）做上界闸。 */
|
||
#define ADC_CAL_R_MIN (65536L) /* 1.0 */
|
||
#define ADC_CAL_R_MAX (2147483647L)
|
||
|
||
/* 零点偏移幅值上限（码值）：超此即判文件损坏/异常标定，回退 ROM 并留痕 */
|
||
#define ADC_CAL_B_MAX (8192L)
|
||
|
||
/* 两点标定的端子输入域上界（µV，含电流按 µA 同域）：±1000 V / 1000 A。
|
||
* 它只拦「把 mV 或码值当 µV 填」这一类量级错——本平台 V0.1 端子量程远低于此，
|
||
* 定值本身不是量程声明，别拿它当"支持 1000 V"的依据 */
|
||
#define ADC_CAL_V_MAX (1000000000L)
|
||
|
||
/*
|
||
* 函数功能：标定层初始化——RAM 副本置 ROM 默认 + 注册三段进 cfg 引擎（幂等）
|
||
* 入口参数：无
|
||
* 返 回 值：无
|
||
* 限定条件：内核启动前调用（app_main_init）；注册必须先于 cfg_file_load
|
||
* （「所有受管段先注册、后 load」契约，见 Drivers/BSP/NETCFG/net_cfg.c 的
|
||
* net_cfg_load 注释）
|
||
* 函数说明：段属主为 defaultTask（配置引擎），本模块只提供 RAM 副本与默认值；
|
||
* 文件值由引擎 load/poll 原地写入 RAM 副本，本层逐点折算现读。
|
||
* ⚠ 变比段 [adc_cal_sec] 的 ROM 默认**不是 0**（电压 1000 / 电流 29.4118），
|
||
* 因此烧进新固件后屏上立刻显二次值——这是刻意的：变比是硬件事实，
|
||
* 出厂就该带着；而 VALID（准不准）仍然要求两点标定，两者互不代替。
|
||
*/
|
||
void adc_cal_init(void);
|
||
|
||
/*
|
||
* 函数功能：码值 → 工程量折算（docs/算法/采集与算法层设计说明.md §13.2 模型）
|
||
* 入口参数：sem - 语义通道（TEMP 透传不折算） adc_semantic_t
|
||
* code - 原始码值（TPAFE 16 位补码 / STM32 0..4095） int32_t
|
||
* 返 回 值：工程量浮点（r≠0 → 二次值 V/A；r=0 → ADC 引脚电压 V） float
|
||
* 限定条件：无（任意上下文，纯读）
|
||
* 函数说明：eng = (code + b) × k[µV/码] × 1e-6 × r[Q16]/65536，由三份 Q16/int32
|
||
* 现值派生，无缓存副本（避免无回调下的陈旧系数）；k/b 越合法带 → 该通道
|
||
* 回退 ROM 默认 + 首见沿 [ERR] 留痕（adc_cal_init 重置留痕位），
|
||
* flags 同时不报 VALID。r 越带或为 0 → 该路按 1.0 处理（不折算），
|
||
* 同样不报 VALID。
|
||
*/
|
||
float adc_cal_apply(adc_semantic_t sem, int32_t code);
|
||
|
||
/*
|
||
* 函数功能：读通道可用性标志（消费者判「能不能信」的唯一入口）
|
||
* 入口参数：sem - 语义通道 adc_semantic_t
|
||
* 返 回 值：ADC_CAL_F_VALID / ADC_CAL_F_CLIPPED 组合；TEMP 恒 0；sem 越界恒 0 uint32_t
|
||
* 限定条件：无
|
||
* 函数说明：VALID = 文件位图置位 **且** 该通道 k/b 在合法带内 **且** 变比已配置
|
||
* （r ≠ 0 且在带内）——三个条件一起才叫"这路标定过"。哨兵不落状态，
|
||
* 天然跟随 load/poll 重载。CLIPPED = V0.1 静态表（UB/UC/IB/IC/IN）。
|
||
* ⚠ VALID 回答「准不准」，**不**回答「什么单位」：单位由 r 决定
|
||
* （r≠0 → 二次值；r=0 → 引脚电压），而 r=0 时 VALID 必为 0，
|
||
* 所以「VALID 未置位却有二次值读数」这种组合不可能出现。
|
||
*/
|
||
uint32_t adc_cal_flags(adc_semantic_t sem);
|
||
|
||
/*
|
||
* 函数功能：**未标定闭锁判定**——保护判据所需的三路标定是否齐（「数据可信」未标定即闭锁
|
||
* / §4.3；道F task-16 把它从两处重复实现收敛成这一份真源）
|
||
* 入口参数：无
|
||
* 返 回 值：1 - 闭锁（UA/UN/IA 中至少一路 `ADC_CAL_F_VALID` 未置位，判据链应停走）；
|
||
* 0 - 三路全 VALID（标定侧允许判据跑） uint8_t
|
||
* 限定条件：任意上下文（纯读 `adc_cal_flags()`，与它同一条并发契约：int32 对齐
|
||
* 字读写原子、cfg poll 重载 µs 级混窗设计接受）；**现查，本层不留任何状态**
|
||
* 函数说明：① **为什么恰好这三路**：V0.1 把 8 路电气量分给两片转换器（AGENTS
|
||
* 「双转换器无共同采样触发」），UA/UN/IA = TPAFE 侧这三路是**唯一有效**
|
||
* 的测量通道；UB/UC/IB/IC/IN 即使将来标定也另受 `CLIPPED` 品质约束
|
||
* （M5 快照层处理），不掺进本闭锁源。
|
||
* ② ⚠ **不得当「保护在跑」的总括用**：判据停走共四路来源，本函数只覆盖
|
||
* 第二路——(a) 自检失败闭锁 采样故障闭锁（`adc_health_flags()`）；(b) 本函数
|
||
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
|
||
* （未标定）；(c) 定值校验和失配闭锁（`prot_set_locked()`）；(d) 全局软压板
|
||
* 退出（`PS_GLOBAL_EN` = 0）。要判「这拍到底评估了没有」必须四路一起看
|
||
* （编排顺序见 `App/task/protect_task.c`）。
|
||
* ③ ⚠ **两个同族谓词与它不是一件事，不要顺手合并**（两种口径各有用途）：
|
||
* · 整帧量纲标签 eng（`App/app/ui_data_feed.c` 的 `feed_eng()`）看的是
|
||
* **每路 r 是否配置**（配了就出二次值），判据 = 「每路要么已配变比、
|
||
* 要么削顶不显示」——削顶通道页面本来就显 "--"，不参与整帧量纲断言；
|
||
* 并进来会让"三路标定齐但八路变比未全配"的整帧被误标引脚电压，
|
||
* 反过来把本三路口径当量纲用，V0.1 下五路削顶会让徽标永不解除；
|
||
* · 逐通道打印 VALID/CLIPPED 位图是诊断输出（`App/task/adc_task.c`），
|
||
* 不是判定。
|
||
* ④ 台架调试旁路 = 编译期 `-DDTU_BENCH`（`docs/算法/采集与算法层设计说明.md`
|
||
* 仅本地台架自行定义；本仓任何工程档都不定义 = 产品恒强制）。旁路**只在
|
||
* 本函数实现内部这一处**，调用方不再各自写 `#ifndef`：否则有人只给单个
|
||
* TU 加宏，屏上「未标定」徽标与判据停走当场分叉，且 0 错误 0 警告。
|
||
*/
|
||
uint8_t adc_cal_prot_blocked(void);
|
||
|
||
/*
|
||
* 函数功能：读通道当前生效系数（µV/码，浮点）
|
||
* 入口参数：sem - 语义通道 adc_semantic_t
|
||
* 返 回 值：k[µV/码]（回退后口径）；TEMP / 越界返 0 float
|
||
* 限定条件：无
|
||
* 函数说明：采样通道自检 门限换算、日志与整定界面回显用；勿据其反推二次值（看 flags）
|
||
*/
|
||
float adc_cal_k_uv(adc_semantic_t sem);
|
||
|
||
/*
|
||
* 函数功能：读通道当前生效零点偏移（码值，浮点）——adc_cal_k_uv 的孪生入口
|
||
* 入口参数：sem - 语义通道 adc_semantic_t
|
||
* 返 回 值：b[码值]（越带时为 0，与折算同视图）；TEMP/越界返 0 float
|
||
* 限定条件：无
|
||
* 函数说明：104 运行参数段（「数据可信」这一项）b 覆盖回显与 k 单侧改写的 RMW
|
||
* 读侧用（App/algo/run_par.c）；勿据其反推二次值（看 flags）。
|
||
*/
|
||
float adc_cal_b_codes(adc_semantic_t sem);
|
||
|
||
/*
|
||
* 函数功能：读通道当前生效系数的 **int32 Q16 原值**（µV/码 × 65536）——
|
||
* adc_cal_k_uv() 的孪生入口，给「必须 LSB 精确」的消费者用
|
||
* 入口参数：sem - 语义通道 adc_semantic_t
|
||
* 返 回 值：k[Q16 原值]（与折算同一生效视图：越带回退 ROM、b 不参与）；TEMP/越界返 0 int32_t
|
||
* 限定条件：无（任意上下文，纯读）
|
||
* 函数说明：故障录波段头的 k 字段是 int32 LSB 精确记账（docs/子系统设计/故障录波设计说明.md
|
||
* §6.3 裁定）——float 还原后在 5.28e7 码字上掉尾数，**禁止**拿
|
||
* adc_cal_k_uv() 反乘 65536 回算落盘，故开本原值口。
|
||
*/
|
||
int32_t adc_cal_k_q16(adc_semantic_t sem);
|
||
|
||
/*
|
||
* 函数功能：读该路变比（浮点，V/V 或 A/V）——屏面/104 回显与标定链的读数口
|
||
* 入口参数：sem - 语义通道 adc_semantic_t
|
||
* 返 回 值：r（比值）；**r=0 表示本路不折算**（输出停在引脚电压）；TEMP/越界返 0 float
|
||
* 限定条件：无（任意上下文，纯读）
|
||
* 函数说明：与折算同视图（0 或越带即按 0 报，不给"带外值"这种第三态）。
|
||
* 别拿它反推 VALID——VALID 是"标定过没有"，r 是"折算比是多少"，
|
||
* 两者由两个字段各记各的（见 adc_cal_flags 的注释）。
|
||
* ⚠ 本值是**整体折算比**（端子二次值 ÷ 引脚电压），不是纯硬件分压比：
|
||
* k 由 ROM 固化成板级名义斜率，其残差被 r 吸收（见 adc_cal_two_point 说明）。
|
||
*/
|
||
float adc_cal_ratio(adc_semantic_t sem);
|
||
|
||
/*
|
||
* 函数功能：读该路变比的 **int32 Q16 原值**（比值 × 65536）——录波段头记账口
|
||
* 入口参数：sem - 语义通道 adc_semantic_t
|
||
* 返 回 值：r[Q16]；TEMP/越界/带外/0 均返 0（0 = 本路不折算） int32_t
|
||
* 限定条件：无（任意上下文，纯读）
|
||
* 函数说明：理由与 adc_cal_k_q16() 同一条——录波头必须 LSB 精确，
|
||
* 65000×65536 这类值经 float 往返会掉尾数（docs/子系统设计/故障录波设计说明.md §6.3）。
|
||
*/
|
||
int32_t adc_cal_ratio_q16(adc_semantic_t sem);
|
||
|
||
/*
|
||
* 函数功能：该路变比是否"已配置"（r 非 0 且落在合法带内）——**整帧量纲标签的唯一判据源**
|
||
* 入口参数：sem - 语义通道 adc_semantic_t
|
||
* 返 回 值：1 - 已配置（该路输出是二次值）；0 - 未配置（输出是引脚电压） uint8_t
|
||
* 限定条件：无（任意上下文，纯读）
|
||
* 函数说明：存在的唯一理由：`App/app/ui_data_feed.c` 的 `feed_eng()` 要给整帧贴
|
||
* 「二次值/未标定」标签，而它需要的是**量纲事实**（配了变比没有），
|
||
* 不是**准确度事实**（VALID）。这两件事在 V0.1 上必然分叉——五路削顶通道
|
||
* 永远拿不到 VALID，但它们配了变比后输出确实已经是二次值。
|
||
* TEMP 恒返 0（不参与线性标定）。
|
||
*/
|
||
uint8_t adc_cal_ratio_configured(adc_semantic_t sem);
|
||
|
||
/*
|
||
* 函数功能：整定入口——写通道系数与零点，并置位 VALID（「数据可信」标定落盘与整定入口）
|
||
* 入口参数：sem - 语义通道（电气 8 路） adc_semantic_t
|
||
* k_q16 - 系数，µV/码 × 65536 内 int32_t
|
||
* b_codes - 零点偏移，码值 内 int32_t
|
||
* 返 回 值：0 - 成功；-1 - 参数非法/越出合法带（RAM 不动，[ERR] 留痕） int
|
||
* 限定条件：**整定路径上下文**（defaultTask 标定流程/整定链；运行参数段落地起 iec104Task
|
||
* 经 App/algo/run_par.c 的 0x8040~/0x8048~ 直通写亦为授权写者——写的仍是
|
||
* 引擎对齐 int32 单字，µs 级混窗契约同docs/算法/采集与算法层设计说明.md §13.8）。勿在 adcTask 调用
|
||
* 函数说明：**只写 RAM 副本，不置脏、不落盘、不返回"稍后会存"的承诺**——落盘由属主经
|
||
* cfg_file_save 完成，而"要不要落盘"这件事只有一个真源：run_par 的脏标志。
|
||
* 因此授权写者是 run_par 的语义 setter（写值 + 置脏成对发生，lead 裁②）；
|
||
* 绕过它直调本函数 = 值只活在 RAM 里，重启即丢且**没有错误返回**，
|
||
* 该形态现可被本层观测计数抓到（差分口径见下方 adc_cal_stats_t 那张表）
|
||
*/
|
||
int adc_cal_set(adc_semantic_t sem, int32_t k_q16, int32_t b_codes);
|
||
|
||
/*
|
||
* 函数功能：整定入口——写该路变比（「数据可信」标定链的第二个写入点）
|
||
* 入口参数：sem - 语义通道（电气 8 路） adc_semantic_t
|
||
* r_q16 - 变比，比值 × 65536（0 = 本路不折算） int32_t
|
||
* 返 回 值：0 - 成功；-1 - 通道非法 / 变比在合法带外（RAM 不动，[ERR] 留痕） int
|
||
* 限定条件：与 adc_cal_set() 同一条并发契约（引擎对齐 int32 单字、µs 级混窗；
|
||
* 勿在 adcTask 调用）
|
||
* 函数说明：**只写 RAM 副本，不置脏、不落盘**——与 adc_cal_set() 完全同一条理由，
|
||
* 落盘的唯一真源仍是 run_par 的脏标志（授权写者 = run_par 的语义 setter）。
|
||
* ⚠ 与 adc_cal_set() **没有先后依赖**：VALID 是每次调用现算的三个条件
|
||
* （位图 ∧ k/b ∧ r），不是"置过的位"，所以先写 r 再写 k/b 和反过来
|
||
* 结果一样。这也意味着**标定一路要调两个函数**（本函数管量纲、
|
||
* adc_cal_set 管零点并置位），少调一个 VALID 就不会亮——这是刻意的：
|
||
* 只配变比 = 出厂默认态（量纲对、准不准不知道）。
|
||
*/
|
||
int adc_cal_set_ratio(adc_semantic_t sem, int32_t r_q16);
|
||
|
||
/*
|
||
* 函数功能：两点标定公式（「数据可信」标定项的算术核，纯函数无状态）
|
||
* 入口参数：c_lo/c_hi - 两点码值（c_hi > c_lo） int32_t
|
||
* v_lo_uv/v_hi_uv - 两点**端子侧**实测值（µV：电压填 1e6 域，电流填
|
||
* 1e6 域但单位是 µA，即「0.5 A → 500000」） int32_t
|
||
* k_q16 - 该路生效系数（走 adc_cal_k_q16() 取，不要自己填） int32_t
|
||
* p_r_q16 / p_b - 输出：变比（Q16）与零点（码值） int32_t *
|
||
* 返 回 值：0 - 成功；-1 - 参数/斜率非法或算出的变比越出 [ADC_CAL_R_MIN, ADC_CAL_R_MAX]；
|
||
* -2 - 零点越 ±ADC_CAL_B_MAX（先查前端，不得用系数凑错斜率，
|
||
* docs/算法/采集与算法层设计说明.md §13.2 尾注） int
|
||
* 限定条件：无（纯整数运算，主机侧可直接单测）
|
||
* 函数说明：**v2.0 起标的是 r，不再标 k**——k 是板级前端斜率（ROM 固化，现场
|
||
* 不该改也改不动），真正未知的是「端子↔引脚」这一层。公式：
|
||
* r = (v_hi−v_lo) / [ (c_hi−c_lo) × k ] ← 零点在差分里抵消
|
||
* b = v_lo / (k × r) − c_lo
|
||
* 两条都用 int64 中间量；`k × r` 的量级先按 Q16 归一到同一个 2^32 再除，
|
||
* 避免先乘后除把 int64 顶到溢出边。v 上限 1e9 µV（1000 V / 1000 A）——
|
||
* 超了几乎必然是把 mV 或码值当 µV 填了，直接判参数错而不是算个假变比出来。
|
||
*/
|
||
int adc_cal_two_point(int32_t c_lo, int32_t c_hi, int32_t v_lo_uv, int32_t v_hi_uv,
|
||
int32_t k_q16, int32_t *p_r_q16, int32_t *p_b);
|
||
|
||
/*
|
||
* 函数功能：通道码值域「贴轨带」门限（采样通道自检 越界检出的门限来源，按 FS 百分比）
|
||
* 入口参数：sem - 语义通道 adc_semantic_t
|
||
* p_lo_th - 下轨带上界（code ≤ 此值判触底） int32_t *
|
||
* p_hi_th - 上轨带下界（code ≥ 此值判触顶） int32_t *
|
||
* 返 回 值：0 - 已给出门限；-1 - TEMP/越界（不做贴轨监视） int
|
||
* 限定条件：无
|
||
* 函数说明：TPAFE 双极性 ±98% FS（±32112）；STM32 上轨 98% FS（4013）、
|
||
* 下轨 2% FS（81）；判定状态机在 adc_health_rail_watch()（采样通道自检）
|
||
*/
|
||
int adc_cal_rail_ths(adc_semantic_t sem, int32_t *p_lo_th, int32_t *p_hi_th);
|
||
|
||
/*
|
||
* 观测计数：把「改了没落盘」从意图式陈述变成可诊断事实（道G task-43 第②项；
|
||
* 先例 App/fs/vol_lock.h 的同族设计——只计数、不取锁、不在调用点打日志、不打 [ERR]）
|
||
*
|
||
* 三态语义（**定义只在本头文件这一处**，消费者只描述取数与断言，不重定义）：
|
||
* set_ok RAM 副本被本层 API 成功改写的累计次数
|
||
* set_reject 被本层拒掉的整定请求累计次数（参数非法 / 越出合法带）
|
||
* persisted_set_ok **水位**而不是计数：最近一次随整档保存落盘成功时的
|
||
* set_ok 快照（由 adc_cal_note_persisted() 盖写，永不越过 set_ok）
|
||
*
|
||
* 未落盘差额 = set_ok − persisted_set_ok，即"自上次成功落盘之后被改写的次数"。
|
||
* 单看差额不够定性，必须与 run_par_dirty_peek() 成对读（两列一起才只有一种解释）：
|
||
*
|
||
* 差额 run_par_dirty_peek() 说的是什么事
|
||
* ------ ---------------------- ----------------------------------------------
|
||
* 0 0 盘与 RAM 齐（或压根没改过）——健康
|
||
* >0 1 改了、还没到落盘时机——正常在途
|
||
* >0 0 **改了且永远不会落盘**：写者绕过 run_par 的语义
|
||
* setter 直调 adc_cal_set()（运行参数段起的事）
|
||
*
|
||
* 消费者告诫（与 vol_lock_get_stats() 同一套，别重犯）：
|
||
* ① 本组接口不取锁、不取时刻，任意上下文可读；三个数各自是 uint32 单字读写，
|
||
* Cortex-M4 上原子，但三个数之间**没有共同时刻**——别把它们拼成"一个瞬间的快照"
|
||
* 下结论，定性只按上面那张两列表成对读。
|
||
* ② 需要"被观测到的时刻"请在消费者侧自盖并冠 obs_ 前缀命名（先例：喂狗点单写者 latch），
|
||
* 本层不存时刻——存了就得连带管溢出与单位。
|
||
* ③ 这些计数**不参与任何判定**：能不能信只看 adc_cal_flags() /
|
||
* adc_cal_prot_blocked()，要不要落盘只看 run_par 的脏标志。别拿差额去改控制流，
|
||
* 那等于把观测升级成第二真源（标定写入口已由 run_par 语义 setter 收口，不再加口）。
|
||
* ④ 写清盲区：本层刻意**不挂** cfg_file 回调，因此"盘 → RAM 的覆盖"（cfg_file_load
|
||
* 与外部变更重载）不产生任何计数；未落盘的改值被一次重载无声吞掉，正是这三个
|
||
* 数照不到的那一条。要照它得先给本层挂回调 = 行为改动，另行立项处置。
|
||
*/
|
||
typedef struct {
|
||
uint32_t set_ok; /* 成功改写 RAM 副本次数（见上方唯一落点） */
|
||
uint32_t set_reject; /* 被拒次数（见上方唯一落点） */
|
||
uint32_t persisted_set_ok; /* 落盘水位，不是计数（见上方唯一落点） */
|
||
} adc_cal_stats_t;
|
||
|
||
/*
|
||
* 函数功能：读标定层观测计数（只读，不改任何状态）
|
||
* 入口参数：p_out - 输出：三个观测计数 adc_cal_stats_t *
|
||
* 返 回 值：无 void
|
||
* 限定条件：任意上下文可读（含 ISR 与内核启动前）；adc_cal_init() 之前可读，得全 0
|
||
* 函数说明：p_out 为 NULL 时静默返回——观测件不得反过来制造故障
|
||
*/
|
||
void adc_cal_get_stats(adc_cal_stats_t *p_out);
|
||
|
||
/*
|
||
* 函数功能：落盘成功回执——把水位 persisted_set_ok 盖写为当前的 set_ok（**不是自增**）
|
||
* 入口参数：无 void
|
||
* 返 回 值：无 void
|
||
* 限定条件：只允许配置引擎属主侧"整档保存已成功"那一条路径调用；当前唯一调用点 =
|
||
* App/algo/run_par.c 的 run_par_store_save() 中 cfg_file_save() 返 0 之后
|
||
* 函数说明：为什么盖写不自增——一次 save 覆盖整档，可能对应多次整定改写（逐通道
|
||
* 标定 3 路 = 3 次 adc_cal_set + 1 次 save）；自增会留下 2 次"假未落盘"。
|
||
* 水位语义让差额只反映"上次落盘之后的改写"，回归锁见
|
||
* test/host/adc_cal/adc_cal_test.c 的 TC-ADCCAL-021
|
||
*/
|
||
void adc_cal_note_persisted(void);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* ADC_CAL_H */
|