Files
STM32F4-Base/App/algo/meas.h
T
wandering1 84c5a5d92a fix(docs): 修 16 处指向已删文件的历史指针,别让读者照着找空门
上一笔改名把 App/protocol/iec104 搬到 App/iec60870/104_port 时,机械
文本替换把「讲一个已经删掉的文件当初做什么」的叙述也一起改了:

  iec104_pts.c  / iec104_asdu.c  / iec104_link.c

这三个文件在 90cc9a7d 里就删了(旧自研协议层整体退役),
App/iec60870/104_port/ 下从来没有它们。于是文档与注释里出现了一批
「新路径 + 旧行为」的混合描述,读者按图索骥只会撞空。

按两类分别处理,共 11 个文件(只有注释与 Markdown,零代码行):

一、讲历史事实的 -> 写回当时真实的旧名,就近标「已删除」
  App/task/ui_task.c            SYSLOG_OPER 那条原写入点
  App/algo/run_par.h            104 消费侧每拍读取
  Drivers/BSP/UI/ui_data.h      YX_DP_N / 遥控记录两条
  Drivers/BSP/UI/ui_page_oper.c 操作页写入点
  Drivers/BSP/UI/ui_page_reset.c 复归串与远端那条刻意不同
  Drivers/BSP/UI/ui_page_yk.c   遥控页写入点
  Drivers/BSP/UI/ui_data.c      CP56 正反两套实现同族
  test/host/ui_data/ui_data_test.c  两处历史注释
  simulator/main.c              双点位图固定帧的来历
  App/log/README.md             oper.log / yk.log 生产者
  docs/UI设计/UI_数据供给设计.md
  docs/UI设计/页面扩充详细方案.md
  docs/产品需求/产品需求设计文档.md  链路层与点表实现指针

二、讲现在仍活着的接缝的 -> 指向真实存在的文件,并 test -f 过
  App/algo/run_par.h:23  死区分流现由 iec104_dtu_table.c +
                         iec104_source.c 承担
  App/algo/meas.h        数值口径改指 common/IEC60870_InformationObjects.h
                         的 IEC60870_ASDU_QUALITY_*;顺带修掉同句里两个
                         既有错:引用了不存在的 test/host/iec104/,
                         且 104 当前消费点是 iec104_serv.c 的 s_measure()
  test/host/bench/iec104/iec104_master.py  常量与帧头说明改指
                         common/IEC60870_Asdu.c 与 104/IEC104_Types.h

App/task/iec104_serv.c 单独说明:文件还在但 s_clock_sync() 已随新契约
消失(grep RC=1),所以写「同日重写后不再投递」,不写「已删除」。

验证:grep 新假路径零命中;旧真名 14 处全部带删除标注;check_bom_drift
RC=0(6 个带 BOM 文件按原始字节补回,未过文本编解码);check_mojibake
RC=0;check_coding_standard 逐文件 RC=0;doc-links 308 篇 / 30 处问题
全部仍在 IEC60870-Slave 供应商快照内,非 vendor 计数仍为 0。
2026-11-18 14:32:40 +08:00

140 lines
9.0 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.
/*
* 模块名称:遥测快照发布层(全周傅氏相量派生·发布侧,docs/算法/采集与算法层设计说明.md §13.9)
* 模块功能:每 **200 ms** 从 全周傅氏相量层取一次基波有效值 + 品质,产出一份全仓唯一的
* 遥测快照(meas_snap_t,布局权威 = docs/算法/采集与算法层设计说明.md §13.9),
* 让 104 与 UI **共用同一份上游**——"什么时候算新值、品质怎么判"只此
* 一处决定(M5 遥测链的地基;104 侧消费见「数据可信」104 改读快照,UI 侧 ui_data_feed 属
* 「UI 扩展」波次,两者都只是本快照的读者)。
* 值口径(批 2「遥测快照发布」的 A-lite 裁决,2026-10-25):**基波有效值瞬时透传**
* (同拍 phasor 使用区口径,系数已在 标定折算折算进帧值——现单位 = ADC
* 引脚电压 V,二次值语义等 adc_cal_flags() 出 VALID,见
* docs/算法/采集与算法层设计说明.md §10 红线③);**不做** 4 点平均 /
* 谐波方和根——docs/算法/采集与算法层设计说明.md §13.9 明示"200 ms 是上送节拍
* 不是平均窗,再平均引入滞后";谐波 k-bin 轨(docs/算法/继电保护功能
* 复现规划.md 遥测谐波轨(可选))将来扩展时只许在本结构**尾部追加**或留在发布侧
*(保护功能清单见 docs/算法/继电保护功能复现规划.md)
* 内部状态,既有字段序不得变更。
* TEMP 通道(docs/算法/采集与算法层设计说明.md §13.3:不参与线性标定):yc = 最新一拍原始
* 帧值透传,qds 恒置 NT——值在场但非交流量语义,UI 按docs/算法/采集与算法层设计说明.md §13.3
* 三态表显示占位符,104 无对应点。
* 并发(docs/算法/采集与算法层设计说明.md §13.9 原文口径):沿用 phasor 的
* **双区 + 单字节活跃索引翻转**(双区指针原子交换 同型,不是新机制)——写侧填满
* 计算区后一次 store 翻转,读者先取索引再整体拷贝,全程无锁;
* seq 只增,消费者据此判"是否换帧"。
* 本层**纯算法**:不碰寄存器、不碰 RTOS、不自己取数(窗自 sample_ring、
* 频率/品质由调用方注入)→ 主机侧免桩纯逻辑单测 test/host/meas/。
* 发布纪律:唯一发布者 = adcTask(在 phasor_run()/freq_run() 之后 200 ms 分频
* 调 meas_tick())。评审判据 = 全仓 meas_tick 调用点数 == 1(「数据可信」
* §8 风险表"快照双写"行);其余任务/模块**只读**。
* 适用平台:STM32F407ZGTx(Cortex-M4F,硬件 FPU)
* 作者:DTU 项目组
* 创建日期:2026-10-25(道D 遥测快照发布)
* 修改记录:
* v1.0 2026-10-25 DTU 项目组 创建:200 ms 遥测快照 + 双区无锁读
*/
#ifndef MEAS_H
#define MEAS_H
#include <stdint.h>
#include "adc_input.h" /* adc_semantic_t / ADC_SEM_COUNT:yc/qds 下标 = 语义通道 */
#ifdef __cplusplus
extern "C" {
#endif
/* 上送节拍(ms):adc_task 按本宏对 1 kHz 拍做**经过时间**分频(非拍计数——
* idle/skip 拍会把拍计数口径拉得比名义值长),落点见 App/task/adc_task.c */
#define MEAS_PERIOD_MS 200u
/* 每点品质位(uint16)。**低字节与线上 104 QDS 字节同值**(OV/NT/IV,数值
* 口径同 App/iec60870/common/IEC60870_InformationObjects.h 的 IEC60870_ASDU_QUALITY_*;
* 旧参照头 App/protocol/iec104/iec104_asdu.h 的 IEC104_QDS_* 已于 2026-11-18 删除,
* 常量值同值未变)——但本层**不得**
* include 协议层头(分层方向:算法层在协议层之下,反向依赖禁止),故在此自
* 定义同值常量;104 侧消费(App/task/iec104_serv.c 的 s_measure() 取快照后
* 直接截低字节上送,见该函数注释)一致性由 meas 单测双向钉住。高字节为 meas 域扩展位(线上不直接
* 出现,由消费者映射): */
#define MEAS_QDS_OV (0x0001u) /* 溢出(留位,本项不产出——判据待运行参数化) */
#define MEAS_QDS_NT (0x0020u) /* 非当前值:未就绪 / 语义未处理(TEMP) */
#define MEAS_QDS_IV (0x0080u) /* 无效:该路取窗失败,无有效读数 */
#define MEAS_QDS_CLIPPED (0x0100u) /* 硬件削顶(adc_cal_flags 位图直通,
* docs/算法/采集与算法层设计说明.md §13.3 三态表;AC 量不可信,
* 消费者应映射为品质无效,如 104 改读快照侧的 IV) */
/* 遥测快照(docs/算法/采集与算法层设计说明.md §13.9 权威布局;实测 72 B,2×72 ≈ 144 B
* 双区 = 本项 DoD 预算口径,由 test/host/meas/ 的布局钉死用例锁字段偏移——
* 改字段 = 破协议,须同步 104 改读快照 / UI) */
typedef struct {
uint32_t seq; /* 只增;消费者据此判断是否换帧 */
uint32_t tick_ms; /* 发布拍时基(osKernelGetTickCount 原值) */
uint8_t valid; /* 整帧有效:本拍 8 电气路取窗全部成功 */
uint8_t rsv[3]; /* 对齐填充,恒 0 */
float yc[ADC_SEM_COUNT]; /* 工程量(引脚电压 V 域;二次值等 VALID 标定) */
uint16_t qds[ADC_SEM_COUNT]; /* 每点品质 MEAS_QDS_*(值本身不因品质清零) */
uint8_t freq_valid; /* 频率读数新鲜度(freq_valid() 注入) */
float freq_hz; /* 频率读数(freq_last() 注入,未收敛为 0) */
} meas_snap_t;
/*
* 函数功能:遥测快照层初始化(清双区 / 索引 / 序号 / 就绪标志)
* 入口参数:无
* 返 回 值:0 - 成功 int
* 限定条件:内核启动前或任务上下文皆可(纯 .bss 状态,无 RTOS 依赖);
* 本仓落点 = adc_task_init()(每开机一次,幂等可重复调)
* 函数说明:init 后 meas_get() 返 -2、meas_seq() 返 0,直到首次 meas_tick()
* 发布——消费者据 -2 走"未就绪"分支,不读半初始化数据。
*/
int meas_init(void);
/*
* 函数功能:一拍遥测发布(200 ms 分频由调用方把关,本函数被调即发布一帧)
* 入口参数:tick_ms - 本拍时基(毫秒) uint32_t
* freq_valid_in - 频率读数新鲜度(freq_valid() 值) uint8_t
* freq_hz_in - 频率读数(freq_last() 值;从未收敛为 0.0) float
* clip_mask - 削顶通道位图(bit s = 语义通道 s;来源唯一 =
* adc_cal_flags() 的 ADC_CAL_F_CLIPPED,编排方注入,
* 本层不链 adc_cal——可用性属主在折算侧) uint32_t
* 返 回 值:无
* 限定条件:**仅 adcTask 上下文、全仓唯一调用点**(发布纪律见文件头);
* 须在 sample_ring_push_frame()/phasor_run() 之后调用,本拍窗才含最新点
* 函数说明:8 电气路逐路取"以本拍为终止的一周波"做基波 DFT(复用 phasor_calc
* 纯函数核,与 phasor 使用区同窗同核 → 同拍同值,见单测钉死),
* 任一路窗不足 → 该路 yc=0 + qds=IV|NT、整帧 valid=0(不产出半新半旧
* 混合帧;与 phasor_run 的差异:phasor 宁可不切区,meas **照常发布**
* 让品质位可见——消费者需要节拍性的品质刷新,seq 亦随之只增)。
* TEMP = 最新一点透传 + NT(见文件头)。末尾单字节翻转使用区,
* 读者无锁。
*/
void meas_tick(uint32_t tick_ms, uint8_t freq_valid_in, float freq_hz_in,
uint32_t clip_mask);
/*
* 函数功能:读当前使用区快照(无锁整体拷贝)
* 入口参数:out - 输出快照;失败(含 -2 未就绪)时**清零填充**,调用方可安全读
* 返 回 值:0 - 成功;-1 - 参数错;-2 - 从未发布过(out 已清零,seq=0) int
* 限定条件:任意上下文(任务级读者:iec104Task / uiTask / protectTask)
* 函数说明:先取一次使用区索引再索引拷贝——拷贝期间写者最多改"**非使用区**",
* 本帧无撕裂(双区不变量,同 phasor_get 口径;写者两帧间隔 200 ms
* 远大于 72 B 拷贝耗时,读者被压超 200 ms 的竞态窗口按 §4.5 设计接受)。
* 判"新不新"用 seq:与上次不同则换帧。
*/
int meas_get(meas_snap_t *out);
/*
* 函数功能:读已发布帧数(只增)
* 入口参数:无
* 返 回 值:seq(0 = 从未发布;单字 32 位读,Cortex-M 原子) uint32_t
* 限定条件:任意上下文
* 函数说明:轻量观测入口(104 周期上送可先比 seq 省 72 B 拷贝);
* 与 meas_get 之间无原子性配对要求(读者以 get 返回的 seq 为准)。
*/
uint32_t meas_seq(void);
#ifdef __cplusplus
}
#endif
#endif /* MEAS_H */