feat(ioboard): 开入开出板驱动、去抖快照与主机侧单测接入

74HC165 开入 + 光耦继电器开出的完整硬件抽象层,接进 defaultTask
的 50ms 节拍。开入 8 路(第二块 165 数据线板上未接,故只有 8 位),
开出 4 路(高电平吸合)。

驱动 BSP drivers:
- IOBOARD/ioboard.c 装载与移位时序,每步注明数据手册依据;
  SH/LD 拉高前先拉低 CLK,否则装载瞬间多移一位;
  单次读取上界 26us(延时按最慢列 VCC 2V 全温区取值)。
- IOBOARD/ioboard_bits.c 位序组装纯函数,只依赖 stdint.h,
  主机侧可直接 include 做单测:读 8 次为 H,G,F,E,D,C,B,A,
  A 放 bit0(bit(7-i) = reads[i])。
- 极性集中在 IOBOARD_DO_LEVEL_ACTIVE 一处,接口语义统一为
  mask 的 1 = 吸合。

业务接线:
- App/util/ioboard_di.c 通道去抖与双区快照,纯逻辑;
  刻意不 include ioboard.h(其引脚宏会牵入 main.h),
  两处路数常量由测试的编译期静态断言钉住。
- default_task.c 的 default_task_di_poll():读失败不喂去抖、
  不写发布值,只把上一有效值加 valid=0 发布出去,
  避免"全 0"被现场读成开入全部复归。
- 去抖实际粒度 50ms(每个轮询周期喂一拍),最坏上报约 100ms;
  想要真 20ms 需另建定时器,本次不做。
- Src/main.c 在 app_main_init 之前调 ioboard_init(),
  上电即把 4 路出口钉在全释放并确认 165 静止态。

测试:
- test/host/ioboard/ 100 条断言。位序主判据为单比特两端
  (只有 A 得 0x01、只有 H 得 0x80)加八点双射穷举;
  混合图样降级为辅助,因该图样曾先后被算成 0xA5、0x5A、0xAA。
- 去抖覆盖 20ms 边界、抖动不翻、跨 49.7 天回绕。
- 失败语义覆盖"失败保留上次有效值"与"失败窗口内的真实变位不丢"。

文档:
- 新增 docs/硬件平台/开入开出实施说明.md。
- 硬件规格与能力边界 §5 的能力边界现状改写:出口继电器与
  开入回路已具备、业务层未接入;4 路开出只可台架验证,
  不得用于真实跳闸。
- 修正 docs/文档规范.md §3.1:原文要求所有互链用仓库根相对,
  与 check_doc_links.py 的实际解析基准矛盾(markdown 链接按
  当前文档目录解析,反引号路径才按仓库根)。改为区分两类,
  并补 §3.1b 写明对应校验器。
- 清理 docs/任务规划/登记簿.md 改名为硬件改版登记.md 后
  遗留的 9 处旧名引用。

门禁: keil-build 0 Error 0 Warning;主机侧单测 ioboard 100/100、
sb_proto 45/45;pre-commit 48 根钩子全通过。
This commit is contained in:
2026-11-16 18:30:31 +08:00
parent d9f8dbfd90
commit fd767d1dcd
35 changed files with 3646 additions and 249 deletions
+16 -2
View File
@@ -24,6 +24,7 @@ spawn_teammate({
| `network-specialist` | 网络协议专家 | CH395F SPI 以太网、netTask socket 栈、IEC 60870-5-104、FTP、SNTP | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` |
| `storage-specialist` | 存储文件系统专家 | GD5F SPI NAND、dhara FTL、FatFs、日志系统、卷自愈 | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` |
| `ui-specialist` | UI/LVGL 专家 | LVGL 160×160 单色菜单、PC 模拟器、菜单树生成器、UI 自动化回归 | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` |
| `mcu-specialist` | STM32 底层与引脚驱动专家 | GPIO/EXTI/AF 复用、时钟树、CubeMX 用户代码区边界、外部时序器件(移位寄存器/并口/SPI 从设备)的位操作与时序实现 | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` |
### 通用工作角色(项目专项)
@@ -36,7 +37,7 @@ spawn_teammate({
> **关于工具调用预算**:角色文件 frontmatter 里都写了 `maxToolCalls`,但该预算**只对 `subagent_role` 路径生效**,对 `spawn_teammate` 起的 teammate 不起约束(插件 `lib/budget.js` 的 `arm()` 只由委派工具调用,team 路径不挂账)。所以本表不再列预算列,免得被当成上限承诺。缺口与后续补齐口径 → `.dsh/plugins/dsh-plugin-subagent-roles/docs/子Agent角色自动注入实现说明.md` §1.1。
> **关于模型**:角色文件 frontmatter **支持** `provider`/`model`/`reasoningEffort` 三个字段,但同样**只有 `subagent_role` 路径会读**。`spawn_teammate` 起的 teammate 一律跑在宿主默认模型上(本机 profile 的 `agent-default-model` = `workbuddy` / `deepseek-v4.1-flash`),与角色无关。当前 8 个角色文件都没写这三个字段,全部继承宿主默认。要给某个成员换模型用 `team_member_revive({ target, provider, model })`(活体立即生效,冷会话挂起到复活瞬间)。机制与两条改造路径 → `.dsh/plugins/dsh-plugin-subagent-roles/docs/子Agent角色自动注入实现说明.md` §1.2。
> **关于模型**:角色文件 frontmatter **支持** `provider`/`model`/`reasoningEffort` 三个字段,但同样**只有 `subagent_role` 路径会读**。`spawn_teammate` 起的 teammate 一律跑在宿主默认模型上(本机 profile 的 `agent-default-model` = `workbuddy` / `deepseek-v4.1-flash`),与角色无关。当前 9 个角色文件都没写这三个字段,全部继承宿主默认。要给某个成员换模型用 `team_member_revive({ target, provider, model })`(活体立即生效,冷会话挂起到复活瞬间)。机制与两条改造路径 → `.dsh/plugins/dsh-plugin-subagent-roles/docs/子Agent角色自动注入实现说明.md` §1.2。
## 角色详细说明
@@ -88,6 +89,18 @@ spawn_teammate({
---
### mcu-specialist(STM32 底层与引脚驱动专家)
**通用知识体系**:MCU 引脚的四层决定因素(焊盘/复用矩阵/GPIO 模式/时刻)、时钟使能与初始化顺序、微秒级时序约定(脉冲宽度、边沿极性、建立保持时间)、GPIO 位操作原子性、HAL 库的正确使用姿势(`GPIO_InitTypeDef` 清零、EXTI 回调在 ISR 上下文、HAL 时基依赖)、外部时序器件五维自查模型(装载/移位模式切换、时钟边沿方向、位序与移位方向、装载前后的时钟状态、上电静止态)、输出类器件(光耦/继电器)的有效电平与安全态。
**行业标准**:STM32F4 参考手册 RM0090(寄存器与复用映射)、数据手册 DS8626(Table 7 引脚定义)、CMSIS 与 HAL 的层次边界、74HC 系列逻辑器件手册(功能表与 AC 特性)、IEC 60255(出口回路语义)。
**项目专项**:引脚来源链 `.ioc` → `main.h` 的 `<Label>_Pin` 宏 → `gpio.c` 的 `MX_GPIO_Init()`、自定义代码只在 USER CODE 区、改引脚必须改 `.ioc` 而非手补初始化、HAL 时基是 TIM7 不是 SysTick、NVIC 优先级 ≥ 5、ARMCC C99 无 GCC 特性、新 `.c` 双端注册、`cubemx-survival` 审计脚本。
**适用场景**:新增或修改 GPIO 引脚配置、外部移位寄存器/并口/SPI 从设备驱动、EXIT 与中断引脚、继电器与光耦输出回路、引脚时序问题排查、CubeMX 重生成后的代码存活修复。
---
### code-reviewer(代码审查员)
**职责**:审查代码改动的正确性、安全性和规范合规性。按「阻塞项 / 建议项」分级输出结构化审查结论。
@@ -140,6 +153,7 @@ spawn_teammate({
| 修改网络驱动/socket 栈/IEC 104 | `network-specialist` |
| 修改 NAND/FatFs/日志/配置引擎 | `storage-specialist` |
| 修改 UI 界面/模拟器/菜单树 | `ui-specialist` |
| 修改 GPIO 引脚配置/外部时序器件驱动/继电器光耦输出 | `mcu-specialist` |
| 提交前审查代码改动 | `code-reviewer` |
| 新增或修改测试用例 | `test-engineer` |
| 构建失败或门禁报错诊断 | `build-gatekeeper` |
@@ -151,7 +165,7 @@ spawn_teammate({
- **复杂任务一律用 Agent Teams**,不用单独的 subagent/subagent_role
- 创建 teammate 时**必须在 prompt 第一行写 `@role:<id>`**
- 角色文件修改后**不需要重启 DSH**,下次委派时自动读取最新版本
- 所有 8 个角色均为双层结构(第一部分通用知识体系 + 第二部分项目专项)
- 所有 9 个角色均为双层结构(第一部分通用知识体系 + 第二部分项目专项)
## `tools` 字段说明
+146
View File
@@ -0,0 +1,146 @@
---
displayName: STM32 底层与引脚驱动专家
description: 专注 MCU 底层:GPIO/EXTI/AF 复用、时钟树、CubeMX 用户代码区边界、外部时序器件(移位寄存器/并口/SPI 从设备)的位操作与时序实现。熟悉 stm32f4xx_HAL、main.h 引脚宏、gpio.c 重生成存活、位操作原子性与 ISR 上下文约束。
tools: [edit, write, ops_grep, ops_glob, ops_bash, ops_inspect_local_file, ops_discover_tools, present, todo_write, send_message, list_agents, read_image, skill, create_skill, job_list, job_output, job_kill, working_directory, team_task_get, team_task_list, team_task_update, get_goal, update_goal, mnemon_recall, mnemon_remember, mnemon_document_search, session_search, session_event_search, web_search, web_fetch, schedule_create, schedule_list, create_goal, compress, decompress, search_context, acp_status, team_gate_open, team_gate_submit, team_gate_accept, team_gate_reject, team_gate_close, team_gate_list]
maxToolCalls: 3000
onToolCallBudget: wrap-up
---
你是 STM32F4-Base 项目的 **STM32 底层与引脚驱动专家**。你的职责是把「板子上真实存在的引脚、时序、芯片」翻译成可验证的 C 代码,边界止于 BSP 对外接口;业务语义、协议栈、存储、UI 都不归你。
# 第一部分:通用知识体系与行业标准
## 一、核心知识体系
### 1.1 MCU 底层编程的四条主线
**引脚**:一个引脚同时被四层决定——物理焊盘(哪个封装脚接了什么)、复用矩阵(AF0~AF15 里哪个外设能用它)、GPIO 模式(输入/输出/复用/模拟 + 上拉下拉 + 速度)、以及时刻(此刻谁在驱动它)。任何一层错,现象都是"读不到/读错/不动作",且**四层错的表观症状经常一样**,所以定位必须从端子往回逐层排除,不能看到"读不到"就改模式。
**时钟**:外设不使能时钟就整块寄存器无响应。这条在 F4 上比 F1 更隐蔽——F4 没有 AFIO,GPIO 端口时钟的使能顺序不影响功能,但**先写输出电平再初始化模式**会有一瞬间的浮空;CubeMX 生成的顺序(先 `HAL_GPIO_WritePin` 设初值,再 `HAL_GPIO_Init`)就是为了消掉这个毛刺。自己写初始化时要复现这个顺序。
**时序**:微秒级的电平约定(脉冲宽度、边沿极性、建立/保持时间)不能靠"应该够快"糊过去。所有对外部器件的时序断言必须来自**器件数据手册原文**,写进代码注释并标注手册的哪个表;没有手册依据的延时一律视为可疑。
**并发**:GPIO 位操作不是原子的。`HAL_GPIO_WritePin` 内部是 `BSRR` 单次写,本身原子;但"读—改—写"三步(如 `GPIOx->ODR |= bit` 或先读再决定)在任务与中断之间会被撕裂。多比特同时输出优先用 `BSRR` 一次写(`(1<<n) | (1<<(n+16))` 同时置位与复位),而不是两次 `HAL_GPIO_WritePin`。
### 1.2 HAL 库的正确使用姿势
- **`HAL_GPIO_Init` 的副作用**:它会把 `GPIO_InitTypeDef` 里所有字段都写进去,包括 Pull 与 Speed。传未清零的结构体会把上一个引脚的配置带过来——`GPIO_InitTypeDef GPIO_InitStruct = {0};` 不是可选的习惯,是正确性要求。
- **`HAL_GPIO_ReadPin` 的返回值是 `GPIO_PinState`**(`SET`/`RESET`),不是 0/1;拿它参与算术前要显式比较,别依赖枚举的具体数值。
- **EXTI 回调在中断上下文**:`HAL_GPIO_EXTI_Callback` 里不能阻塞、不能调 `HAL_Delay`、不能拿非递归互斥量。需要重活一律置标志 + `xTaskNotifyFromISR` 唤醒任务。
- **HAL 的 1ms 时基**:本项目时基是 TIM7 而非 SysTick(见 `Src/stm32f4xx_hal_timebase_tim.c`)。`HAL_Delay` 与 `HAL_GetTick` 依赖它;在 `osKernelStart` 之前的临界区里不要依赖长延时。
### 1.3 外部时序器件的实现模型
**位串行器件(移位寄存器类)**是最容易出错的一类,因为错误不会报错,只会"数据差一位/顺序颠倒/低电平有效搞反"。实现这类器件时固定按五个维度自查:
1. **装载与移位是两种模式**,由一个控制脚切换。控制脚的电平语义(高=移位 / 低=装载)必须查手册确认,不能从器件名推断。
2. **时钟边沿方向**:绝大多数 74 系列移位寄存器在**低到高**沿动作;但触发沿之前输出端的数据已经对应某个特定比特,因此"第 N 个沿读到第几比特"要按手册时序图逐格数,不能凭"第一个沿读第一比特"的直觉。
3. **移位方向与位序**:是 MSB 先出还是 LSB 先出,决定你拿到的 `uint8_t` 是直接就是端口状态还是需要位反转。对"并行装载 + MSB 先出"的器件,第一个读到的比特对应最高位索引。
4. **装载脉冲前后时钟必须满足的状态**:多数器件要求"控制脚由装载切到移位之前,时钟已经是低电平",否则数据在装载的瞬间就被多移了一位(这是个静默错位,台架上看起来"数据大体对但整体偏一位")。
5. **上电静止态**:CubeMX 给的初值是不是器件安全态。比如装载脚上电就低,意味着器件一直停在装载态,现场信号会源源不断进寄存器——这时首次读取必须补一次完整装载,或者干脆让初值就是移位态。
**并口输入器件(数据总线类)**:读取前必须确认对方已把数据摆到总线上(通常是读选通脚或"数据就绪"脚的时序),并且**读完要检查是否有丢失**(序号/回读校验)。多比特并行读要一次 `IDR` 取值,分段读会被别的任务打断而拼出跨时刻的假值。
### 1.4 输出类器件(继电器/光耦)的安全实现
- **有效电平必须由硬件定义**:光耦二极管是灌电流还是拉电流,决定 `HAL_GPIO_WritePin(SET)` 是"吸合"还是"释放"。这个方向搞反,在台架上可能看不出来(有些光耦在台架上通电就亮),但现场会误动。
- **上电默认态必须是安全态**:对出口继电器,"安全"通常是"断开"。所以初始化代码的电平设置与 `HAL_GPIO_Init` 的顺序要保证:从上电到第一次明确写入之间,不会出现短暂吸合。
- **互锁在软件层也要有一道**:如果业务规定某些出口组合不合法(比如"跳闸"与"闭锁"互斥),驱动层要给一个"整组置位"的原子接口,让调用方一次生效,而不是分两次写造成中间态。
- **状态要能读回**:至少维护一份软件影子寄存器(shadow),让业务层能查询"我上次让它是什么状态",并给一个可选的硬件回读接口(若硬件有辅助触点)。
## 二、行业标准与规范
### 2.1 STM32F4 参考手册(RM0090)
寄存器行为、复用功能映射、GPIO 电气特性以 RM0090 为准。引脚定义与封装脚号以数据手册(DS8626)Table 7 为准。两者冲突时,电气行为听 RM0090,物理连接听数据手册。
### 2.2 CMSIS 与 HAL 的层次边界
CMSIS 层是寄存器包装(`GPIOA->BSRR` 可用);HAL 层是封装(`HAL_GPIO_WritePin` 可用)。两者**可以混用**,但同一次操作不要混:要么全走 HAL,要么全走寄存器。混用的后果是时钟/锁定状态的一致性难以追踪。
### 2.3 74 系列逻辑器件手册
74HC/HCT 系列的功能表与 AC 特性来自厂家数据手册(TI SN74HC165、ST M74HC165、Nexperia 74HC165 等)。同一逻辑功能在不同厂家之间引脚兼容,但**传播延时与建立时间不同**,设计余量要按最慢的厂家取。
### 2.4 IEC 61131 / IEC 60255(输出回路)
继电保护类设备的出口回路有"动作后保持""防误动""闭锁"等语义约束。本项目是 DTU 平台而非保护装置本体,但出口语义仍需按"动作必须可追溯、释放必须明确"来实现。
## 三、设计原则与最佳实践
### 3.1 分层:BSP 只做"翻译",不做"决策"
BSP 层回答的问题是「让硬件动起来并如实汇报状态」,不回答「该不该动」。业务判断(比如"过流持续 200ms 才跳闸")属于上层。这条边界的意义是:BSP 可以单独上板验证(给定输入看输出),而带业务逻辑的驱动只能整体验证。
### 3.2 时序常量命名即规格
延时不要写魔数。命名成 `BSP_XXX_LOAD_PULSE_US` 这种带单位、带器件语义的宏,并在注释里写清来源(数据手册哪一项的最小值 + 你取的余量倍数)。这样将来换器件时,编译器会帮你找出所有需要重算的地方。
### 3.3 可测性:把纯逻辑从寄存器操作里剥出来
位序、去抖、互锁判断都是纯逻辑,可以抽成不依赖 HAL 的函数,在主机侧用假数据跑单测。寄存器读写留在薄薄的一层里。这样"位序反了""去抖窗口算错"这类错误能在 PC 上秒级发现,不用上板。
### 3.4 失败要可观测
读不到数据时返回错误码而不是返回 0;0 和"读失败"在业务上含义完全不同("没有信号" vs "设备坏了")。所有 BSP 接口的返回值都要区分这两种情况。
## 四、常见陷阱与反模式
| 反模式 | 后果 | 对策 |
|---|---|---|
| 凭器件名猜引脚电平语义 | 高有效/低有效搞反,现场误动 | 查数据手册功能表原文,写进注释 |
| 移位寄存器的触发沿与位序按直觉写 | 数据整体偏一位或位序颠倒,不报错 | 按手册时序图逐格数,写单测验证位序 |
| 装载前不停时钟 | 装载瞬间多移一位,静默错位 | 控制脚翻高之前先确保时钟低 |
| 上电初值不是安全态 | 上电瞬间继电器误动 | 初值设在 `HAL_GPIO_Init` 之前,且等于安全态 |
| 多比特输出分两次写 | 中间态被外部电路捕捉 | 用 `BSRR` 一次写多比特 |
| 在 ISR 里做长操作 | 打断采样节拍,丢帧 | ISR 里只置标志/通知任务 |
| 读失败返回 0 | 与"信号为 0"混淆 | 用错误码区分 |
| 在 USER CODE 区外写代码 | CubeMX 重生成覆盖 | 详见第二部分 |
---
# 第二部分:STM32F4-Base 项目专项
## 专业领域
- **引脚配置的来源链**:`STM32F407-Demo.ioc`(配置真相)→ `Inc/main.h` 里的 `<Label>_Pin` / `<Label>_GPIO_Port` 宏 → `Src/gpio.c` 的 `MX_GPIO_Init()`。**代码里一律引用 main.h 的宏,不写死 `GPIO_PIN_x` 裸值**。
- **BSP 驱动**:`Drivers/BSP/<器件名>/` 下 `<器件>.c` + `<器件>.h` + `README.md`。参照 `TPAFE5160`、`CH395F`、`RS485`、`GD5F2GQ5UE` 的既有结构。
- **业务消费**:`App/task/` 里的任务调用 BSP 接口;纯逻辑放 `App/algo/`(若不属于采集算法则放 BSP 内的纯函数,由单测覆盖)。
## 铁律
1. **自定义代码只写 USER CODE 区**。重生成会覆盖区外一切。每次重生成后必须跑 `scripts/check_cubemx_survival.py` 审计(`cubemx-regen` skill)。
2. **改引脚配置必须改 `.ioc`**,不许在 `gpio.c` 或 `HAL_GPIO_Init` 外面手补引脚初始化——否则 CubeMX 显示的引脚状态与真相不符,下次重生成就丢。
3. **字符串字面量必须纯 ASCII**,中文只写注释。
4. **注释里别写星号形态的路径**(ARMCC 诊断 9-D)。
5. **自研代码禁用 C 库堆分配**(MicroLIB 堆仅 512B)。
6. **新 `.c` 必须双端注册**:`MDK-ARM/STM32F407-Demo.uvprojx` 与 `simulator/CMakeLists.txt`(`new-source-file` skill)。
7. **NVIC 外设中断优先级 ≥ 5**(HAL 规定,见 `HAL_Init` 的 `TICK_INT_PRIORITY` 约束)。
8. **HAL 时基是 TIM7 不是 SysTick**,`SysTick` 归 FreeRTOS;不要在 FreeRTOS 启动后改 SysTick。
9. **只 Keil MDK-ARM (ARMCC, C99)**。不要用 GCC 特性(`__attribute__` 里的 ARMCC 不认的、`typeof` 等)。
10. **任何代码修改后必须先 `/keil-build` 验证(0 错误 0 警告)**。烧录闭环用 `/serial-boot-test`。
## 本项目的引脚与器件事实
- 完整引脚表 → `docs/架构设计/硬件规格与能力边界.md` §2
- ⚠ 网名 ≠ 板级 ADC 通道 ≠ 转换器通道号 → `docs/硬件平台/ADC通道映射说明.md`
- ⚠ V0.1 硬件缺陷:8 路电气量分属两片转换器,**禁止跨转换器做相位运算**
- 硬件缺陷与改版登记 → `docs/任务规划/硬件改版登记.md`
- 改动驱动前先读 `docs/问题记录/` 下对应器件的 Trap 记录
## 工作方式
1. **先查真实现状**:改任何引脚相关代码前,先读 `.ioc`、`main.h`、`gpio.c` 三处确认引脚当前状态,不要相信任务描述里的引脚表——它可能已经过期。
2. **时序之前先查手册**:涉及外部器件的时序(脉冲宽度、边沿、建立保持)必须引用数据手册原文。查不到手册就说"查不到",不许编。
3. **纯逻辑与寄存器分离**:位序/去抖/互锁抽成纯函数,便于主机侧单测。
4. **写注释要给后来人留依据**:每个魔数旁边写清"为什么是这个值"与出处。
5. **完成后给出改动摘要**:改了哪些文件、新增哪些宏与函数、引脚来源、如何上板验证、还有哪些未决项。
## 参考文档与技能
- `cubemx-regen` skill — 重生成存活工作流与审计脚本
- `new-source-file` skill — 新源文件双端注册
- `keil-build` skill — 编译闭环
- `docs/架构设计/硬件规格与能力边界.md` — 引脚权威表
- `docs/硬件平台/` — 网表分析与通道映射
- `docs/问题记录/` — 各器件 Trap 记录
+132
View File
@@ -69,6 +69,8 @@
#include "wave_ring.h" /* 录波环消费侧:sealed/sealed_meta/read_cb/write_done(task-2) */
#include "wave_store.h" /* 段打包游标 + 段号轮转纯函数(落盘道本体,task-2) */
#include "task_handles.h" /* 任务句柄与属性块的引用契约(定义处仍是 Src/freertos.c) */
#include "ioboard.h" /* 开入开出板 BSP(硬件动起来并如实汇报) */
#include "ioboard_di.h" /* 开入去抖 + 双区快照(纯逻辑,主机侧同一份源码被单测覆盖) */
/* Private defines -----------------------------------------------------------*/
/* 栈水位观测节奏:首次报告须晚于 bring-up 深链(mount/mkfs/探针/cfg/syslog),
@@ -119,6 +121,29 @@ static const stack_probe_task_t s_stack_probe[] = {
static void stack_probe_poll(void);
#if !defined(TEST_SUITE_STORAGE)
static void default_task_net_cfg_save_notify(void);
static uint8_t default_task_di_poll(void);
/* 周期性发布者的编译期开关:两个测试套件构建都禁用本任务的发布(见 poll 函数的说明四) */
#if defined(TEST_SUITE_CH395F) || defined(TEST_SUITE_GDRAM)
#define DEFAULT_TASK_DI_PUBLISH_EN 0
#else
#define DEFAULT_TASK_DI_PUBLISH_EN 1
#endif
/*
* 开入(DI)采集状态,**文件作用域静态零初始化**(不占任务栈、不走堆):
* s_di_ch - 8 个通道的去抖状态机(App/util/ioboard_di.c)
* s_di_snap - 双区快照(消费者无锁读,见 ioboard_di.h)
* s_di_pub_mask - 最近一次**成功**读到的去抖后 mask;读失败时原样再发布,
* 这就是"失败不得当全 0 上报"在本任务侧的落点
* s_di_fail_edges_seen - 已写入日志的故障下降沿计数("每个 episode 只记一条")
* 为什么是文件作用域而不是任务内 static:poll 函数在任务函数之外定义,
* C99 里函数内 static 无法被别处看见;放文件作用域还让"唯一写者"更显眼。
*/
static ioboard_di_ch_t s_di_ch[IOBOARD_DI_CH_NUM];
static ioboard_di_snapshot_t s_di_snap;
static uint8_t s_di_pub_mask;
static uint32_t s_di_fail_edges_seen;
static FRESULT storage_bring_up(FATFS *fs);
static void wave_store_drain(void);
#endif
@@ -189,6 +214,16 @@ void default_task_func(void *argument) {
uint32_t cfg_poll_cnt = 0u;
uint32_t led_tick = HAL_GetTick();
/* 周期性发布者的编译期开关:两个套件都禁用本任务的发布(见下方 poll 函数的说明) */
#if defined(TEST_SUITE_CH395F) || defined(TEST_SUITE_GDRAM)
#define DEFAULT_TASK_DI_PUBLISH_EN 0
#else
#define DEFAULT_TASK_DI_PUBLISH_EN 1
#endif
/* 开入第一次读取放在 bring-up 之后:此刻 MX_GPIO_Init 早已配好引脚(模块初始化期),
* 且看门狗尚未启动,几十微秒的移位读不会影响任何节拍。 */
(void)default_task_di_poll();
/* 注册控制台写者:本任务此后是串口唯一发送者(其余任务只写环形缓冲)。
* 见 App/log/console_log.c "控制台单写者日志"——消除并发写造成的日志逐字符交错,
* 并让脏指针无法再进入 HAL_UART_Transmit 的缓冲遍历。 */
@@ -305,6 +340,11 @@ void default_task_func(void *argument) {
cfg_file_poll();
#endif
}
/* 开入采集(8 路 74HC165):读、去抖、发布快照。**不单独占喂狗段**
* (见函数说明:单次裸读上界见 IOBOARD_DI_READ_MAX_US,去抖是纯比较,无需新增段号)。 */
task_prof_enter(TASK_PROF_DEF_DI);
(void)default_task_di_poll();
task_prof_exit(TASK_PROF_DEF_DI);
/* LED 心跳:500ms 翻转一次(与旧 500ms 循环节奏等效;循环基准改 50ms 后
* 不能再每轮翻转,否则变成 10Hz 闪烁) */
task_wd_seg(TASK_WD_SEG_LED);
@@ -887,3 +927,95 @@ static void default_task_net_cfg_save_notify(void) {
}
}
#endif
/*
* 函数功能:开入(8 路 74HC165)采样一拍——读、逐通道去抖、发布快照
* 入口参数:无
* 返回值:1 = 本拍成功并发布了有效快照;0 = 本拍读失败
* 限定条件:仅 defaultTask 调用(启动期一次 + 主循环每轮一次;**唯一写者**)
* 函数说明:
*
* 一、【节拍与去抖粒度 —— 必须讲清楚,别让人误以为真能 20 ms】
* 本函数挂在 defaultTask 的 50 ms 基准拍上(osEventFlagsWait(..., 50u) 的兜底,
* 无事件时一轮 = 50 ms;有事件时一轮更短)。因此**一个轮询周期只喂一拍**,
* 20 ms 去抖窗口的实际粒度是 **50 ms 而不是 20 ms**。
* 这与设计目标一致(开关量与继电器辅助触点的变位时标以"秒"计,50 ms 远够),
* 代价是单次变位的上报时延最坏约"一拍轮询 + 一个窗口"≈ 100 ms。
* 想要真 20 ms 需另建硬件定时器中断,那要动 RAM/任务预算,本次**不做**。
* 有事件唤醒时一轮会更短(>= 若干 ms),此时去抖精度随之细化 —— 只会更准,不会更差。
*
* 二、【耗时与喂狗段】
* 单次 ioboard_di_read() 上界见 ioboard.h 的 IOBOARD_DI_READ_MAX_US
* (装载 + 8 拍,每拍两相各 1 us;全程在临界区内关中断)。
* **不要在这个函数里硬写数字**:该宏是驱动的时序规格唯一出处,驱动改时序时
* 这里必须跟着改就说明注释写错了——用宏名。
* 以当前值(26 us)计:对 50 ms 一拍是 0.05%,且远小于任何中断的响应预算,故:
* · **不新增 task_wd_seg 段号**(段号是复位取证用的契约,为几十 µs 加一个段
* 只会稀释 PREVRUN 的信息量,且 enum 是新契约、要对齐文档);
* · 只加一个 task_prof 探针,把"它到底多久"变成可观测值(见 task_prof.h)。
* 临界区长度已由驱动负责(其注释写明"时序内不含任何可能阻塞的调用")。
*
* 三、【失败语义:读失败绝不当全 0 上报】
* 读失败时:不更新 s_di_ch(不喂去抖 → 候选值与计时全长不动),
* **用上一有效值 s_di_pub_mask 再次发布**,valid 置 0,并累加失败拍数。
* 于是消费者看到的是"mask 还是旧的 + valid = 0",而不是一个新鲜的全 0 ——
* 后者在现场会被读成"开入全部复归",是最危险的假信息。
* 恢复:第一拍成功读即整组重新确立去抖基准(ioboard_di_ch_reset + 喂一拍),
* 避免把"故障期间积累的旧计时"当成合法窗口。
*
* 四、【故障留痕】
* 有效性下降沿(有效 → 失效)各落一条 run.log。判据用 fail_edges 的**边沿**
* 而不是失败计数,保证一个故障 episode 只记一条(与 task_wd_poll 的位图边沿同款)。
* 写日志点放在本函数内而非 ioboard_di.c:纯逻辑层不碰文件系统。
* 且只在 !TEST_SUITE_CH395F && !TEST_SUITE_GDRAM 时发布 —— 那两个套件构建下
* 卷由 testTask 独占(与 TEST_SUITE_STORAGE 同款理由),defaultTask 侧只读不算不写盘。
*/
static uint8_t default_task_di_poll(void) {
uint8_t mask = 0u;
uint8_t rc = 0u;
uint8_t i;
uint32_t now = HAL_GetTick();
uint32_t edges = 0u;
int32_t fails = 0;
#if (DEFAULT_TASK_DI_PUBLISH_EN == 0)
/* 测试套件构建:卷上写者不是本任务,本函数不发布也不写日志(见函数说明四) */
(void)mask; (void)rc; (void)i; (void)now; (void)edges; (void)fails;
return 0u;
#else
if (ioboard_di_read(&mask) == BSP_OK) {
/* 成功:第一拍(或刚从故障恢复)先整组重新确立基准,再喂本拍 */
if (s_di_snap.valid == 0u) {
ioboard_di_ch_reset(s_di_ch, (uint8_t)IOBOARD_DI_CH_NUM, now);
}
for (i = 0u; i < (uint8_t)IOBOARD_DI_CH_NUM; i++) {
uint8_t lvl = (uint8_t)((mask >> i) & 1u);
(void)ioboard_di_ch_feed(&s_di_ch[i], lvl, now, IOBOARD_DI_DEBOUNCE_MS);
}
/* 用**去抖后**的稳定值重新组合发布值(原始 mask 只用一次,不等抖就上报) */
mask = 0u;
for (i = 0u; i < (uint8_t)IOBOARD_DI_CH_NUM; i++) {
if (s_di_ch[i].stable != 0u) {
mask = (uint8_t)(mask | (uint8_t)(1u << i));
}
}
s_di_pub_mask = mask;
(void)ioboard_di_snap_publish(&s_di_snap, mask, 1u, 1u);
rc = 1u;
} else {
/* 失败:不喂去抖、不写 mask,只把"旧值 + 无效"发布出去 */
(void)ioboard_di_snap_publish(&s_di_snap, s_di_pub_mask, 0u, 0u);
rc = 0u;
}
/* 故障下降沿留痕(每个 episode 一条;recovers 由下一拍的有效发布体现) */
ioboard_di_snap_faults(&s_di_snap, &edges, &fails);
if (edges != s_di_fail_edges_seen) {
s_di_fail_edges_seen = edges;
syslog_post(SYSLOG_SELFTEST, "di read fault");
}
return rc;
#endif
}
+217
View File
@@ -0,0 +1,217 @@
/*
* 模块名称:开入(DI)去抖与快照——纯逻辑实现(本模块可主机侧测试的那一半)
* 模块功能:ioboard_di.h 全部纯函数。零 HAL、零 FreeRTOS、零全局可变状态,
* MCU(ARMCC C99)与主机侧 MSVC 编译**同一份源码**。
* 适用平台:任何 C99
* 作者:王建锋
* 创建日期:2026-11-16
* 修改记录:
* 2026-11-16 王建锋 创建
*/
#include "ioboard_di.h"
/* 空指针统一按 "0" 处理:本层是纯逻辑,不为防御性检查引入错误码;
* 调用方(defaultTask)传的都是静态对象地址,NULL 只可能出现在测试里 */
static uint8_t di_is_null(const void *p)
{
return (p == 0) ? 1U : 0U;
}
/* ======================== 通道去抖 ======================== */
void ioboard_di_ch_reset(ioboard_di_ch_t *ch, uint8_t n, uint32_t now_ms)
{
uint8_t i;
if (di_is_null(ch) != 0U) {
return;
}
for (i = 0U; i < n; i++) {
ch[i].t_ms = now_ms;
ch[i].raw = 0U;
ch[i].stable = 0U;
ch[i].started = 0U;
}
}
uint8_t ioboard_di_ch_feed(ioboard_di_ch_t *c, uint8_t level, uint32_t now_ms,
uint32_t window_ms)
{
uint8_t lvl;
if (di_is_null(c) != 0U) {
return 0U;
}
lvl = (level != 0U) ? 1U : 0U;
/* 一、首个样本直接确立:上电后不必空等一个窗口才有开入值 */
if (c->started == 0U) {
c->started = 1U;
c->raw = lvl;
c->stable = lvl;
c->t_ms = now_ms;
return 0U; /* 首拍不算"稳定电平翻转":此前没有稳定值可翻 */
}
/* 二、原始电平变了:重新开始计时。抖动只会不断推迟翻转,这就是去抖 */
if (lvl != c->raw) {
c->raw = lvl;
c->t_ms = now_ms;
return 0U;
}
/* 三、原始电平持续满窗口 → 稳定电平跟随。
* 用无符号减法而不是 now >= t + window:tick 在 49.7 天处回绕时前者依然正确,
* 后者会在回绕附近出现一次长达 49 天的"永不翻转"(或者反过来瞬间误翻)。
* 边界取 >=:恰好满 20 ms 就应翻转。 */
if ((c->stable != lvl) && ((uint32_t)(now_ms - c->t_ms) >= window_ms)) {
c->stable = lvl;
return 1U;
}
return 0U;
}
/* ======================== 双区快照 ======================== */
uint8_t ioboard_di_snap_publish(ioboard_di_snapshot_t *s, uint8_t mask, uint8_t valid,
uint8_t is_fail)
{
uint8_t changed;
uint8_t was_valid;
if (di_is_null(s) != 0U) {
return 0U;
}
/* 先递增成奇数 = "正在写";数据写完再递增成偶数 = "可读" */
s->seq++;
was_valid = s->valid;
changed = 0U;
if (s->change_seq == 0U) {
/* 第一次发布:视为一次变化(让上位机区分"还没有值"与"已建立基线") */
changed = 1U;
} else if (s->mask != mask) {
changed = 1U;
}
/* 读失败**不自行写 0**:mask 就是调用方传进来的值(失败拍传的是上一有效值) */
s->mask = mask;
s->valid = (valid != 0U) ? 1U : 0U;
if (is_fail == 0U) {
if (s->fail_count < (int32_t)IOBOARD_DI_FAIL_COUNT_CAP) {
s->fail_count++;
}
} else {
/* 任何一次成功读都说明"当前这一拍读到了":计数从 0 重新累计,
* 表示**连续**失败拍数。不归零的话,一次偶发失败会让计数永久停在上界,
* 之后真正的断线再也看不出来(饱和计数只拦"长时间连续断线")。 */
s->fail_count = 0;
}
/* 有效 → 失效 的下降沿记一次故障次数(恢复沿不改 fail_edges,靠 valid 回落体现) */
if ((was_valid != 0U) && (s->valid == 0U)) {
s->fail_edges++;
}
if (changed != 0U) {
s->change_seq++;
}
s->seq++;
return changed;
}
uint8_t ioboard_di_snap_read(const ioboard_di_snapshot_t *s, uint8_t *out_mask,
uint32_t *out_seq)
{
uint32_t s1;
uint32_t s2;
uint8_t n;
if (di_is_null(s) != 0U) {
if (out_mask != 0) {
*out_mask = 0U;
}
if (out_seq != 0) {
*out_seq = 0U;
}
return 0U;
}
/* 一次读取两遍并校验序号:读期间若被写者打断,序号会变化或为奇数 → 作废重来 */
for (n = 0U; n < (uint8_t)IOBOARD_DI_SNAP_RETRY; n++) {
s1 = s->seq;
if ((s1 & 1U) != 0U) {
continue; /* 写者正在写 */
}
if (out_mask != 0) {
*out_mask = s->mask;
}
if (out_seq != 0) {
*out_seq = s->change_seq;
}
s2 = s->seq;
if ((s1 == s2) && ((s2 & 1U) == 0U)) {
return (s->valid != 0U) ? 1U : 0U;
}
}
/* 连续被打断 20 次:本次不给值(调用方按"无新数据"处理,绝不拿半新半旧的东西) */
return 0U;
}
void ioboard_di_snap_reset(ioboard_di_snapshot_t *s)
{
if (di_is_null(s) != 0U) {
return;
}
s->seq = 0U;
s->mask = 0U;
s->valid = 0U;
s->fail_count = 0;
s->fail_edges = 0U;
s->change_seq = 0U;
}
void ioboard_di_snap_copy(const ioboard_di_snapshot_t *s, ioboard_di_snapshot_t *out)
{
if ((di_is_null(s) != 0U) || (di_is_null(out) != 0U)) {
return;
}
out->seq = s->seq;
out->mask = s->mask;
out->valid = s->valid;
out->fail_count = s->fail_count;
out->fail_edges = s->fail_edges;
out->change_seq = s->change_seq;
}
void ioboard_di_snap_faults(const ioboard_di_snapshot_t *s, uint32_t *out_edges,
int32_t *out_fails)
{
if (di_is_null(s) != 0U) {
if (out_edges != 0) {
*out_edges = 0U;
}
if (out_fails != 0) {
*out_fails = 0;
}
return;
}
if (out_edges != 0) {
*out_edges = s->fail_edges;
}
if (out_fails != 0) {
*out_fails = s->fail_count;
}
}
+180
View File
@@ -0,0 +1,180 @@
/*
* 模块名称:开入(DI)去抖与快照——纯逻辑层
* 模块功能:把「每拍读一次 8 路开入」拆成两个与硬件无关的部件——
* ① 通道去抖:每个通道独立计时,电平连续稳定满 DI_DEBOUNCE_WINDOW_MS 才翻转;
* ② 双区快照:消费者拿到的 mask 与 seq 永远来自同一份已稳定的副本。
* 读引脚在 App/util/ioboard_di.c 的 .c 部分(本 .c 就是那一半,属于同一模块的
* 可测部分);本头文件**不 include** HAL / FreeRTOS / ioboard.h / main.h,
* 可被主机侧 MSVC 单测直接编译。
*
* 为什么去抖不放进 ioboard.c:BSP 只回答"让硬件动起来并如实汇报",去抖与
* 失败语义是上报层的事;而且 ioboard.c 依赖 HAL/FreeRTOS,主机侧编不过。
* 为什么不做成通用 di_debounce 工具:去抖的具体语义(20 ms、8 路、失败拍
* 推时间戳)是开入业务的一部分,抽成泛化工具会造出第二个真相源。
* 适用平台:任何 C99(ARMCC v5 / MSVC / GCC);仅 <stdint.h>。
* 作者:王建锋
* 创建日期:2026-11-16
* 修改记录:
* 2026-11-16 王建锋 创建
*
* 失败语义(本模块最重要的一条,单测与调用方都依赖它):
* 本项目铁律是「读失败不得把开入当全 0 上报」。本模块的落点有三处:
* · 快照 mask **只**由成功读更新:失败拍喂进去的是"上一有效值",绝不自行产生 0;
* · 但失败拍**照样推进**去抖计时并更新候选值——否则一次跨过整段失败窗口的真实
* 变位会被永久吞掉,104/UI 上看到的仍是旧值且无痕迹;
* · 有效性下降沿 / 恢复沿各记一次(fail_edges / valid),由调用方决定是否留痕;
* 本模块本身不碰文件系统、不依赖 CMSIS,所以能在 PC 上跑。
*/
#ifndef IOBOARD_DI_H
#define IOBOARD_DI_H
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* ======================== 常量 ======================== */
/* 去抖窗口(ms):某通道电平须连续稳定这么久,快照才允许翻转。
* 取 20 ms:现场开关与继电器辅助触点抖动在 5~10 ms 量级,20 ms 是常见两倍余量;
* 且 20 ms < defaultTask 的 50 ms 基准拍(最快两拍后翻转)、
* 远小于 100 ms 喂狗判定,不影响任何既有节拍。 */
#define IOBOARD_DI_DEBOUNCE_MS 20u
/* 开入路数。**刻意不复用 IOBOARD_DI_COUNT**:IOBOARD 头里的 HC165 引脚宏会展开成
* main.h 的符号,一旦被 .c 真正使用就把 MCU 头拉进本纯逻辑单元,主机侧编不过。
* 两者的一致性由主机侧测试在编译期静态断言(test/host/ioboard/ioboard_test.c)。 */
#define IOBOARD_DI_CH_NUM 8u
/* 读失败累计上界:到顶后不再增加,防止长时间断线把 int32 计数绕成负数,
* 让"一直失败"看起来像"从未失败" */
#define IOBOARD_DI_FAIL_COUNT_CAP 0x7FFFFFFFL
/* 读侧重试上限:写者一次发布是十几条指令,正常第二遍必一致;
* 20 次仍不一致 = 被持续抢占,返回 0 让调用方本次不用这个值 */
#define IOBOARD_DI_SNAP_RETRY 20u
/* ======================== 通道去抖 ======================== */
/*
* 单通道去抖状态。结构体公开是为了让调用方放进静态存储(本仓禁用 C 库堆分配)。
* 字段语义(一律走下面的函数读改写,别直接写):
* t_ms - raw 最近一次变化的时刻
* raw - 最近一拍读到的电平(0/1)
* stable - 已确认稳定的电平(就是快照里那一位)
* started - 是否已收到第一拍(0 = 尚未确立)
*/
typedef struct {
uint32_t t_ms;
uint8_t raw;
uint8_t stable;
uint8_t started;
} ioboard_di_ch_t;
/*
* 函数功能:把一组通道复位成"下一拍即整组确立"
* 入口参数:ch - 通道数组
* n - 数组长度(可小于 IOBOARD_DI_CH_NUM,便于单测只用一个通道)
* now_ms - 复位时刻(沿用调用方时间基准,通常是 HAL_GetTick)
* 返回值:无
* 限定条件:任意上下文;纯内存写,不加锁
* 函数说明:复位后**第一拍**无论读到什么都整组确立——这是 run 期"重新武装"语义:
* 调用方先让快照失效、再复位,下一拍重新建立基准,不必区分设备是上电起来
* 还是从故障恢复起来。
*/
void ioboard_di_ch_reset(ioboard_di_ch_t *ch, uint8_t n, uint32_t now_ms);
/*
* 函数功能:喂一拍采样给单个通道
* 入口参数:c - 通道状态(已复位或已初始化)
* level - 本拍电平(非 0 即 1;传更宽的值也安全)
* now_ms - 本拍时刻(ms,任意起点、允许 32 位回绕)
* window_ms - 去抖窗口(ms;0 = 不滤波,下一拍立即跟随)
* 返回值:1 = 稳定电平在本拍翻转;0 = 未翻转
* 限定条件:相邻两拍间隔须 < 2^32 ms(49 天)——本项目 50 ms 节拍天然满足
* 函数说明:
* 一、首个样本直接确立(否则上电后要空等一个窗口才有开入值)。
* 二、raw 变化 → 记新 raw 与时刻、计时重开始(抖动不断推迟翻转,这就是去抖)。
* 三、raw 未变、已稳定、且 (now - t_ms) **>=** window → stable 跟随 raw。
* 用无符号减法而不是 `now >= t + window`:后者在 tick 回绕附近会错误地
* "永久成立"或"永久不成立"(单测"回绕"一条扫这个窗口)。边界取 >=:满 20 ms 即翻。
*/
uint8_t ioboard_di_ch_feed(ioboard_di_ch_t *c, uint8_t level, uint32_t now_ms,
uint32_t window_ms);
/* ======================== 双区快照 ======================== */
/*
* 快照。**单写者**(run 期 = defaultTask;同一时刻只有一个写者),**多读者**
* (任意上下文、无锁)。读者按"序号偶数且前后一致"取一致值;写者按"奇-写-偶"发布。
*/
typedef struct {
volatile uint32_t seq; /* 偶数 = 稳定;奇数 = 正在写 */
volatile uint8_t mask; /* 去抖后的 8 路开入(bit0 = A … bit7 = H) */
volatile uint8_t valid; /* 1 = 至少成功读过一次、且当前不在失败态 */
volatile int32_t fail_count; /* **连续**读失败拍数(成功一拍即归零;饱和于 CAP) */
volatile uint32_t fail_edges; /* 有效 → 失效 的下降沿次数(= 故障次数) */
volatile uint32_t change_seq; /* 去抖后 mask 翻转次数 */
} ioboard_di_snapshot_t;
/*
* 函数功能:写者发布一拍
* 入口参数:s - 快照对象
* mask - 本拍去抖结果(读失败时**必须**传上一有效值)
* valid - 本拍之后是否有效(0/1)
* is_fail - 本拍是否读失败(0 = 失败;非 0 = 成功)
* 返回值:去抖后 mask 相对上一拍是否翻转(1 = 翻转,change_seq 已加一)
* 限定条件:单写者;不加锁;可在临界区内调用
* 函数说明:第一次发布(change_seq == 0)也返回 1,让上位机区分"还没有任何值"与
* "已建立基线"。本函数**从不自行生成 0**:mask 就是调用方传进来的值,
* 失败拍传的是上一有效值——这就是"失败不当全 0"的落点。
*/
uint8_t ioboard_di_snap_publish(ioboard_di_snapshot_t *s, uint8_t mask, uint8_t valid,
uint8_t is_fail);
/*
* 函数功能:读者取一致的一组值
* 入口参数:s - 快照对象
* out_mask - 输出,去抖后开入(可为 NULL)
* out_seq - 输出,change_seq(可为 NULL)
* 返回值:1 = 读到一致且有效的快照;0 = 快照尚无效 / 读取期间持续被打断
* 限定条件:任意上下文、无锁、不阻塞
* 函数说明:返回 0 时 out_mask 仍被写为"最近一次发布值",但**不得**当新数据用——
* 消费者按"本次无新数据"处理(保留自己上一次保存的值)。
*/
uint8_t ioboard_di_snap_read(const ioboard_di_snapshot_t *s, uint8_t *out_mask,
uint32_t *out_seq);
/*
* 函数功能:把快照清成"从未成功读过"的初始态
* 入口参数:s - 快照对象
* 返回值:无
* 限定条件:单写者(初始化期 / 尚无读者)
* 函数说明:全字段清零。**mask = 0 此时不表示"开入全 0"**——消费者必须看 valid 与
* change_seq。
*/
void ioboard_di_snap_reset(ioboard_di_snapshot_t *s);
/* 诊断副本:不保证一致性,仅供自检/串口打印 */
void ioboard_di_snap_copy(const ioboard_di_snapshot_t *s, ioboard_di_snapshot_t *out);
/*
* 函数功能:读"有效 → 失效 下降沿"累计次数与"连续失败拍数"
* 入口参数:s - 快照对象
* out_edges - 输出,fail_edges(可为 NULL)
* out_fails - 输出,fail_count(可为 NULL)
* 返回值:无
* 限定条件:任意上下文;单字读,值可能来自相邻两拍(诊断用途够用)
* 函数说明:调用方(defaultTask)用它把"开入读失败"这一事实经 syslog 留痕——
* 本模块自己不碰文件系统,留痕点只有调用方知道该写哪个日志、写多频。
*/
void ioboard_di_snap_faults(const ioboard_di_snapshot_t *s, uint32_t *out_edges,
int32_t *out_fails);
#ifdef __cplusplus
}
#endif
#endif /* IOBOARD_DI_H */
+4 -2
View File
@@ -107,6 +107,7 @@ static void prof_send(int n, uint32_t raw) {
* uiw/uis/uisn uiTask 单轮工作最坏 / 推流往返最坏 / 仍在推流段内(us)
* adc/adcm/adcn adcTask 单拍次数 / 单拍最坏 / 仍在拍内(us)
* [PROF2] defd/defs defaultTask 控制台排空最坏 / syslog 落盘最坏(us)
* defi defaultTask 开入采样一拍最坏(读 + 去抖 + 发布,us)
* netp/netn netTask 驱动轮询最坏 / 仍在轮询内(us)
* adcp/adcq adcTask ADC 单次最坏 / 仍在 ADC 内(us)
* 两行的 gl 丢弃样本数(DWT 不可用或计数器被重置)
@@ -162,13 +163,14 @@ static void prof_emit(uint32_t raw) {
(unsigned long)gl);
prof_send(n, raw);
/* 行 2:段级(占用者指认:defaultTask 排空/落盘、netTask 驱动、adcTask ADC) */
/* 行 2:段级(占用者指认:defaultTask 排空/落盘/开入、netTask 驱动、adcTask ADC) */
n = snprintf(s_prof_line, sizeof(s_prof_line),
"[PROF2] t=%lu defd=%lu defs=%lu netp=%lu netn=%lu adcp=%lu "
"[PROF2] t=%lu defd=%lu defs=%lu defi=%lu netp=%lu netn=%lu adcp=%lu "
"adcq=%lu gl=%lu\r\n",
(unsigned long)t,
(unsigned long)prof_cyc_to_us(s_prof[TASK_PROF_DEF_DRAIN].max),
(unsigned long)prof_cyc_to_us(s_prof[TASK_PROF_DEF_SYSLOG].max),
(unsigned long)prof_cyc_to_us(s_prof[TASK_PROF_DEF_DI].max),
(unsigned long)prof_cyc_to_us(s_prof[TASK_PROF_NET_POLL].max),
(unsigned long)prof_cyc_to_us(netn),
(unsigned long)prof_cyc_to_us(s_prof[TASK_PROF_ADC_POLL].max),
+2
View File
@@ -33,6 +33,7 @@
* ADC_POLL adcTask adc_input_poll() 单次(enter/exit)——隔离 ADC 超时成本
* DEF_DRAIN defaultTask dbg_console_drain()(enter/exit)——控制台忙等发送
* DEF_SYSLOG defaultTask syslog_drain()(enter/exit)——NAND/FTL 写
* DEF_DI defaultTask 开入采样一拍(默认Task,任务级 max)——开入读+去抖+发布
* NET_POLL netTask net_poll()(enter/exit)——CH395F 驱动轮询
*
* 后四个探针用于**指认占用者**:UI 心跳缺席时,谁的最坏耗时在同一窗口抬起来,
@@ -58,6 +59,7 @@ typedef enum {
TASK_PROF_DEF_DRAIN = 5, /* defaultTask 控制台排空耗时 */
TASK_PROF_DEF_SYSLOG = 6, /* defaultTask syslog 落盘耗时 */
TASK_PROF_NET_POLL = 7, /* netTask net_poll() 耗时(CH395F 驱动) */
TASK_PROF_DEF_DI = 8, /* defaultTask 开入采样一拍(读 + 去抖 + 发布) */
TASK_PROF_ID_COUNT
} task_prof_id_t;
+253
View File
@@ -0,0 +1,253 @@
# 开入开出板 BSP(IOBOARD)
**一句话**:这个驱动让板上的 74HC165 移位寄存器能够被读出 8 路开入,让 4 路光耦继电器能够被整组写入;它只做引脚与时序,不做任何业务判断。
---
## 1. 器件与接线
### 1.1 MCU 侧引脚(来源:`STM32F407-Demo.ioc` → `Inc/main.h` → `Src/gpio.c`)
| 功能 | 引脚 | `main.h` 宏 | 模式 | CubeMX 初值 | 速度 |
|---|---|---|---|---|---|
| 74HC165 装载 `SH/LD` | PC2 | `HC165_LD_Pin` | 推挽输出 | **SET**(移位模式) | VERY_HIGH |
| 74HC165 时钟 `CLK` | PC3 | `HC165_CLK_Pin` | 推挽输出 | **RESET**(时钟低) | LOW |
| 74HC165 数据 `QH` | PE3 | `HC165_IN2_Pin` | 输入 | — | — |
| 出口 0(KO6) | PC14 | `KO6_Pin` | 推挽输出 | RESET | LOW |
| 出口 1(TRIP) | PF0 | `TRIP_LED_Pin` | 推挽输出 | RESET | LOW |
| 出口 2(ERT) | PF1 | `ERT_LED_Pin` | 推挽输出 | RESET | LOW |
| 出口 3(CLZ) | PF6 | `CLZ_LED_Pin` | 推挽输出 | RESET | LOW |
PE2(旧名 `IN_D4`)与 PE4(旧名 `IN_E4`)是命名残留,**硬件上没有对应信号**,本驱动完全不碰。
> ⚠ **改动引脚只能走 CubeMX**(改 `.ioc` 后重生成)。`Src/gpio.c` 是生成文件,手改会在下次重生成时被覆盖。
> 引脚换脚/换端口时,软件侧唯一要动的地方是 `ioboard.c` 顶部的「引脚绑定」区;`ioboard.h` 不用动。
### 1.2 74HC165 侧接法
- 两块 74HC165 **级联**,共用 `CLK`(PC3)与 `SH/LD`(PC2)。
- **但只有一块芯片的 QH 回到了 MCU**(PE3)。第二块的 QH → 第一块的 SER 链路或引出线在板上缺失,
所以本驱动把一次 8 拍读到的数据当作**一块芯片的 8 位开入**(A..H 通道)。
- 这就是「已知限制」第一条的来源,见 §5。
---
## 2. 时序原理与数据手册依据
### 2.1 四条从数据手册直接得到的事实
出处:TI **SNx4HC165 Rev.H**(`SN74HC165` / `SN54HC165`)第 7 节 Detailed Description 与 7.3 节 Functional Modes 真值表;
ST **M74HC165** 与 Nexperia **74HC165** 的功能表与之相同。本驱动按 TI 版本建模。
1. `SH/LD` = **低** → 异步并行装载(A..H 八个输入进寄存器),与时钟无关。
2. `SH/LD` = **高** → 移位模式;每个 `CLK` **低到高沿**使数据向 `QH` 方向移动一位。
3. 移位方向是 **A → B → … → H → QH**,即 `H` 离输出最近。**第一个时钟沿之前** QH 上已经是 `H`,
第 8 个沿之前才是 `A`。所以 8 次采样的顺序是 **H,G,F,E,D,C,B,A**,而接口要求 `A` 在 LSB。
4. 手册明确要求:`CLK` 与 `CLK INH` 在 `SH/LD` 由低升高**之前**必须已经是低电平
(原文:"...CLK and CLK INH should be LOW before the LOW-to-HIGH transition of SH/LD to prevent shifting the data when SH/LD goes HIGH.")。
违反它的症状不是报错,而是整串数据**偏一位**。
### 2.2 为什么是这个顺序
```
CLK ‾‾|____|‾‾‾‾|____|‾‾‾‾|____|‾‾‾‾|____|‾‾‾‾ ... 共 8 个上升沿
LD ‾‾‾‾‾‾‾\________________________/‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
QH ======X= 装载后先是 H ====== 上升沿后 G ==== F ==== ... ==== A
↑采样点(每次上升沿之前读)
```
- **先让 CLK 低**:满足上面第 4 条。代码里这一步由 `ioboard_check_idle()` 保证,并在时序函数里再显式写一次,
使「CLK 低」与「LD 拉低」在代码顺序上紧邻。
- **LD 拉低 → 短暂延时 → LD 拉高**:装载是异步的,延时只为满足最小脉宽 `tw(SH/LD low)`。
- **每次先读 QH,再打上升沿**:手册时序图里数据在上升沿**之前**已稳定;上升沿后 QH 要过一个 `tpd` 才变成新值。
若改成「先打沿再读」,第 8 个沿之后读到的会是 `SER` 端的内容而不是 `A`——这是最经典的「多读一位」错误。
### 2.3 延时取值与出处(`ioboard.h` 的 `IOBOARD_HC165_*_US`)
| 宏 | 取值 | 手册原值(最慢列:VCC 2 V / −40…85 °C) | 余量 |
|---|---|---|---|
| `IOBOARD_HC165_LOAD_PULSE_US` | 1 µs | `tw(SH/LD low)` 120 ns | 8× |
| `IOBOARD_HC165_LOAD_SETTLE_US` | 1 µs | `tpd(SH/LD → QH)` 225 ns | 4× |
| `IOBOARD_HC165_CLK_PHASE_US` | 1 µs | `tw(CLK high or low)` 120 ns | 8× |
| `IOBOARD_HC165_QH_SETTLE_US` | 1 µs | `tpd(CLK → QH)` 225 ns | 4× |
**按最慢电压/温度列取值**,所以换 VCC 或温区都不必重算。
一次完整读取的上界 `IOBOARD_DI_READ_MAX_US` = 1 + 1 + 8×(1+1+1) = **26 µs**。
#### 关于 `HC165_CLK` 的速度是 LOW(≈2 MHz 上限)
**这不是缺陷,也不需要改**。SPEED_FREQ_LOW 在 3.3 V / ~50 pF 负载下的边沿约 500 ns 量级,
驱动每一位的实际周期是 2 µs 以上(上升 1 µs + 下降 1 µs),带宽利用率不到 25%,边沿永远不会成为瓶颈。
若将来确实需要提速:**去 CubeMX 把 PC3 改成 MEDIUM/HIGH 再重生成**,不要改 `Src/gpio.c`;
然后重算上表四个宏,并复核 26 µs 这个上界仍满足调用方的节拍。
---
## 3. 位序算例(人工核对依据)
设只有 **A 与 H** 两路有信号,其余 6 路无信号:
- 第 1 次采样读到 **H = 1**,第 2..7 次读到 G..B = 0,第 8 次读到 **A = 1**;
- 于是读取序列 `bits = [1,0,0,0,0,0,0,1]`;
- 组装规则 `bit(7-i) = bits[i]`:`bits[0]`(H)→ bit7,`bits[7]`(A)→ bit0;
- 结果 **`mask = 0x81`**(bit7 与 bit0 为 1)。
另一条**非对称**算例(对称图样不含位序信息,不能用):
- `bits = [1,0,1,0,1,0,1,0]` → 为 1 的是第 1/3/5/7 次采样 = **H, F, D, B** → 落在 bit7/5/3/1 → **`0xAA`**;
- 其反序 `[0,1,0,1,0,1,0,1]` → **G, E, C, A** → 落在 bit6/4/2/0 → **`0x55`**。
> 历史教训:这组输入在评审中先后被算成 `0xA5`、`0x5A`、`0xAA`。
> 正确值是 `0xAA`;`0xA5`/`0x5A` **不是任何实现的输出**,引用前请手推。
> (顺带:`[1,0,1,0,1,0,1,0]` 是回文图样,反序不变,所以它**根本不含位序信息**——正因如此才要配上 0x55 那一条成对断言。)
---
## 4. 软件结构
### 4.1 分层
```
业务层(defaultTask / 未来 104 / UI) ← 判据、去抖、互锁,全在这里
│ 只看 ioboard.h 的 4 个函数 + 位宏
▼
ioboard.c ← 引脚 + 时序 + 极性转换 + 影子寄存器(唯一 include HAL/FreeRTOS 的文件)
│ 只调 ioboard_di_assemble()
▼
ioboard_bits.c ← 纯逻辑:位序组装。只依赖 <stdint.h>,主机侧可单测
```
**为什么位序要单独成文件**:位序错一位不会报错,只表现为「开入状态差一位」——
在台架上这与「线接错一位」完全同形,无法归因。把它剥离成纯函数,主机侧用假数据一条条钉住;
台架上剩下的就只可能是物理层问题。
### 4.2 接口
| 函数 | 一句话职责 | mask 语义 |
|---|---|---|
| `ioboard_init()` | 清影子、自检引脚模式、确认静止态、4 路全释放 | — |
| `ioboard_di_read(uint8_t *out_mask)` | 一次完整装载 + 8 拍移位;任意上下文 | **bit0 = A … bit7 = H** |
| `ioboard_di_read_from_isr(uint8_t *out_mask)` | 同上,强制 FROM_ISR 临界区 | 同上 |
| `ioboard_do_write(uint8_t mask)` | 整组原子写 4 路开出 | **bit0..bit3,1 = 吸合**;bit4..bit7 忽略 |
| `ioboard_do_get(uint8_t *out_mask)` | 读软件影子寄存器(上次写入值) | 同上 |
| `ioboard_do_read_level(uint8_t *out_level)` | 读 4 路引脚**实际输出电平**(调试用) | **bit n = 1 表示引脚高电平**,与吸合语义无关 |
- `ioboard_init()` **不调用 `HAL_GPIO_Init`**:引脚模式/速度/上下拉由 `MX_GPIO_Init()` 唯一负责。
在这里再初始化一遍只会让 CubeMX 显示的引脚状态与真相脱节,下次重生成还会被覆盖。
- 读失败时**不写** `*out_mask`——「读失败」与「读到全 0」必须可区分,判断权留给上层。
上层不能把失败当成「全 0」上报(否则故障会被伪装成「信号消失」)。
- `ioboard_di_read` 自动判别任务/ISR 上下文(读 `SCB->ICSR.VECTACTIVE`)。
调度器尚未启动时(初始化阶段)自动改用 `__disable_irq()`,因为 `taskENTER_CRITICAL()`
在 `taskSCHEDULER_NOT_STARTED` 时是空操作。
### 4.3 极性:唯一可改点
`ioboard.h`:
```c
#define IOBOARD_DO_LEVEL_ACTIVE (1U) /* 1 = 高电平吸合;若硬件实测相反改成 0U */
#define IOBOARD_DO_LEVEL_RELEASE ((IOBOARD_DO_LEVEL_ACTIVE) ? 0U : 1U)
```
**改极性只改 `IOBOARD_DO_LEVEL_ACTIVE` 这一行**:调用方永远只说「哪一路吸合」,
从不手写 HIGH/LOW;`ioboard_init()` 的「上电全释放」读的也是这个宏,所以不需要另改初始化。
当前取值依据:用户口径「高电平 = 继电器吸合」。若原理图显示相反,改这一行即可。
⚠ 这个取值**尚未经原理图核对、也尚未上板验证**,见 §5 第一条。
### 4.4 构建注册
- **`ioboard_bits.c` 与 `ioboard.c` 必须一起进构建**:前者提供 `ioboard_di_assemble()` 的定义,
后者调用它;缺任何一半都会链接失败(undefined symbol)。
- Keil 工程:`MDK-ARM/STM32F407-Demo.uvprojx` 的 `Drivers/BSP` 组已注册两个文件,
`IncludePath` 已加 `../Drivers/BSP/IOBOARD`。
- 模拟器端**不编驱动**:`simulator/CMakeLists.txt` 不加,理由与本仓既有硬件驱动(`CH395F` / `TPAFE5160` / `RS485`)一致——
它们已在 `scripts/check_registration.py` 的 `SIM_EXEMPT` 名单里逐个点名「模拟器无对应」。
本驱动的纯逻辑部分由 `test/host/ioboard` 的主机侧单测直接编译覆盖,所以不进模拟器不形成覆盖空窗。
- 只想要纯逻辑时(主机侧单测、上层去抖模块):**只 include `ioboard_bits.h`**,不要 include `ioboard.h`
——后者会拉进 `bsp_err.h`,而且不提供任何纯函数。
---
## 5. 上板验证步骤
### 第 0 步:先看驱动自己报什么
上电后立刻调用一次 `ioboard_init()`,**检查返回值**:
| 返回值 | 含义 | 先查什么 |
|---|---|---|
| `BSP_OK` | 引脚模式正确、静止态确认通过 | 继续第 1 步 |
| `BSP_ERR_STATE` | PC2/PC3/PE3 模式不对,或 DWT 不可用,或主频换算不符,或引脚电平与期望不符 | 用调试器读 `GPIOC->MODER` / `GPIOE->MODER`,确认 PC2=01、PC3=01、PE3=00;读 `DWT->CTRL` 确认 CYCCNTENA=1 |
### 第 1 步:验证开入逐路对应关系(不需要示波器)
目标:确认「bit0 = A」这条不是纸面推导。
1. 上电后反复调用 `ioboard_di_read()`,记下基线 mask(无信号时通常全 0 或全 1,取决于板上端子接法)。
2. 按板子的开入端子定义,把**第 1 路**(对应 A)短接到该板定义的"ON"电平(通常是 IN 与 COM 短接,或加 24 V),依次只改一路。
3. 每次改一路,读一次 mask,**期望只有对应的 bit 翻转**:
- 第 1 路 → bit0 翻转;第 2 路 → bit1;……第 8 路 → **bit7**。
4. 若发现**整体错一位**(比如第 1 路动 bit1),那不是软件位序问题(位序已被主机侧单测钉死),
而是板上 A..H 与端子的映射顺序与预期不同——查接线图,不要改软件。
> 没有万用表也能做:用一根杜邦线手动短接 PE3 到 GND/3V3 不能验证通道对应,只能验证数据线通路。
> 通道对应必须动真实端子。
### 第 2 步:验证开出极性与逐路动作(万用表 / 耳朵)
**先验极性**——这一步决定 `IOBOARD_DO_LEVEL_ACTIVE` 的取值是否正确:
1. `ioboard_init()` 之后,4 路应**全部释放**:万用表量出口端子(常开触点)应为断开,继电器无声。
2. 调 `ioboard_do_write(IOBOARD_DO_KO6)`(只有第 0 路),期望**只有出口 0 的继电器动作**("嗒"一声)。
- 同时用 `ioboard_do_read_level()` 读引脚电平:第 0 路应为 **1**(与 `IOBOARD_DO_LEVEL_ACTIVE = 1U` 一致)。
- 若**继电器不动**、引脚电平也变了 → 极性反了,把 `IOBOARD_DO_LEVEL_ACTIVE` 改成 `0U`。
- 若**继电器吸合了但初始化后不释放**(上电就吸合)→ 同样说明极性反了,**立即改宏后重测**,
这属于安全问题,不要带着它继续做其它测试。
3. 逐路验证 bit1/bit2/bit3 分别对应 TRIP/ERT/CLZ 三路,**每次只有一路动作**。
4. 调 `ioboard_do_write(0x0F)` 四路全吸合,再 `ioboard_do_write(0x00)` 全释放。
用 `ioboard_do_get()` 回读影子寄存器,应为刚写入的值;与 `ioboard_do_read_level()` 对照,
若两者不一致 = 有人在驱动之外写了这 4 根引脚的 ODR。
### 第 3 步:有示波器时看时序
把探头接 **PC2(LD)** 与 **PC3(CLK)**,触发在 LD 下降沿。期望看到:
- LD 先为高;出现一个**低脉冲**(宽 1 µs 量级),随后回到高并保持;
- LD 回到高之后,CLK 才开始**第一组 8 个脉冲**,每个高、低各 1 µs 量级;
- **LD 由低升高的那一刻,CLK 必须是低电平**(这是 §2.1 第 4 条),放大看 LD 上升沿处 CLK 应为 0;
- 整段从 LD 下降沿到第 8 个 CLK 下降沿约 26 µs。
同时把第三个探头接 **PE3(QH)**:第一个 CLK 上升沿之前 QH 上应是第 8 路(H)的电平;
每个上升沿之后约 30~225 ns 内 QH 翻转。
> ⚠ 本驱动在读取全过程持有 FreeRTOS 临界区(关 `configMAX_SYSCALL_INTERRUPT_PRIORITY` 以下中断),
> 所以示波器上会看到这段时序**连续、无中断插入**——这正是设计意图。若看到中间被插入了一段
> 别的波形,说明有人在临界区里做了长操作,去查那个地方。
---
## 6. 已知限制
1. **第二块 74HC165 读不到**:两块级联但第二块的数据输出线在板上没接回 MCU,所以只能读 8 路开入。
软件侧适配点:`ioboard.c` 的 `ioboard_di_shift()` —— 若飞线/改板后要读 16 位,
在那里把循环次数从 `IOBOARD_DI_COUNT`(8)改为 16,并相应调整 `ioboard_bits.c` 的组装与
`IOBOARD_DI_MASK_ALL`。**不是现在该做的事**,记在此处以免将来重复推导。
2. **4 路开出分属两个端口**(GPIOC×1、GPIOF×3),所以是**两次** BSRR 写,两次之间约 10 ns 量级。
每次写内部原子,两次之间只会看到「旧态 → 新态」的跃迁,不会出现目标态以外的组合。
若将来业务要求 4 路**严格同一时刻**,需要硬件把它们挪到同一端口。
3. **极性未经原理图核对**:`IOBOARD_DO_LEVEL_ACTIVE = 1U` 目前只有「用户口径 + 上电初值为 RESET」两条间接依据,
必须按 §5 第 2 步实测确认。
4. **硬件无辅助触点回读**:`ioboard_do_get()` 读的是**软件影子寄存器**(「我上次让它是什么」),
不是「继电器现在真的动没动」。后者只能靠辅助触点或万用表。
5. **PE2 / PE4 是命名残留**:硬件无信号,本驱动不配置、不读取。若 CubeMX 里还留着它们,
那是 `IN_D4` / `IN_E4` 的旧配置,不影响本驱动。
---
## 7. 修改记录
| 日期 | 作者 | 变更 |
|---|---|---|
| 2026-11-16 | 王建锋 | 创建:74HC165 装载/移位时序、4 路光耦继电器整组写、位序纯逻辑拆分 |
+682
View File
@@ -0,0 +1,682 @@
/*
* 模块名称:开入开出板 BSP(74HC165 开入 + 光耦继电器开出)
* 模块功能:74HC165 装载/移位时序的寄存器级实现 + 4 路光耦继电器的整组原子写。
* 位序组装在 ioboard_bits.c(纯逻辑、可主机侧单测),本文件只剩引脚与时间。
* 适用平台:STM32F407ZGT6(Cortex-M4F)+ FreeRTOS V10.3.1
* 作者:王建锋
* 创建日期:2026-11-16
* 修改记录:
* 2026-11-16 王建锋 创建
*
* 分层约定(为什么这样切):
* ├─ 引脚编号只有一个来源:main.h 的 Label_Pin 宏,在本文件顶部的「引脚绑定」区
* │ 翻译成驱动内部短名字。本文件不出现任何 GPIO_PIN_x 裸值,也不调用 HAL_GPIO_Init。
* ├─ 极性只有一个可改点:ioboard.h 的 IOBOARD_DO_LEVEL_ACTIVE。
* │ 本文件只说「哪几路要吸合」,不手写高低电平。
* └─ 时序常量只有一处:ioboard.h 的 IOBOARD_HC165_ 系列与 IOBOARD_CYCLES_PER_US。
*/
#include "ioboard.h"
/* HAL / CMSIS:取引脚宏、DWT 与 CoreDebug、SCB、SystemCoreClock */
#include "main.h"
/* FreeRTOS:临界区宏与调度器状态 */
#include "FreeRTOS.h"
#include "task.h"
/* ======================== 引脚绑定(唯一改点) ======================== */
/*
* 这里把 main.h 的 <Label>_Pin 宏翻译成驱动内部的短名字。
* 只在 .c 里做这件事:main.h 的宏展开是 HC165_LD_GPIO_Port 这类 MCU 符号,
* 放进 ioboard.h 就会把「凡是 include 本驱动头文件的上层」全都拉进 main.h。
*/
#define IOBOARD_HC165_LD_PORT HC165_LD_GPIO_Port /* PC2 */
#define IOBOARD_HC165_LD_PIN HC165_LD_Pin
#define IOBOARD_HC165_CLK_PORT HC165_CLK_GPIO_Port /* PC3 */
#define IOBOARD_HC165_CLK_PIN HC165_CLK_Pin
#define IOBOARD_HC165_QH_PORT HC165_IN2_GPIO_Port /* PE3 */
#define IOBOARD_HC165_QH_PIN HC165_IN2_Pin
#define IOBOARD_DO_CH_GPIO_0_PORT KO6_GPIO_Port /* PC14 */
#define IOBOARD_DO_CH_GPIO_0_PIN KO6_Pin
#define IOBOARD_DO_CH_GPIO_1_PORT TRIP_LED_GPIO_Port /* PF0 */
#define IOBOARD_DO_CH_GPIO_1_PIN TRIP_LED_Pin
#define IOBOARD_DO_CH_GPIO_2_PORT ERT_LED_GPIO_Port /* PF1 */
#define IOBOARD_DO_CH_GPIO_2_PIN ERT_LED_Pin
#define IOBOARD_DO_CH_GPIO_3_PORT CLZ_LED_GPIO_Port /* PF6 */
#define IOBOARD_DO_CH_GPIO_3_PIN CLZ_LED_Pin
/* ======================== 内部宏与常量 ======================== */
/*
* 调度器尚未启动时,ioboard_enter_critical 的返回标记。
* PRIMASK / BASEPRI 只用到低 8 位,0xFF 只会出现在「优先级 255 的 BASEPRI」这种
* 实际上等于关中断的情形,用它做标记不会与正常运行时的返回值混淆;
* 但为了不给未来的读者留陷阱,ioboard_exit_critical 的判据是
* 「using_isr == 0 且 state == 本标记」,两个条件同时成立才走 __enable_irq。
*/
#define IOBOARD_CTX_IRQ_OFF ((uint32_t)0xFFU)
/* 上下文自动判别(ioboard_enter_critical 的 in_isr 入参) */
#define IOBOARD_CTX_AUTO ((uint8_t)0xFFU)
/*
* 4 路开出「软件 mask 位 → 端口 + 引脚」的绑定表。
* 这是 IOBOARD_DO_CH_GPIO_n_PORT/PIN 宏在运行时的唯一使用点:
* 引脚换到别的端口时只改 ioboard.h 的宏,这里一行不动。
* 用「端口指针 + Pin 掩码」而不是逐脚 HAL_GPIO_WritePin,是为了能合成一次 BSRR 写。
*/
typedef struct
{
GPIO_TypeDef *port;
uint32_t pin;
} ioboard_do_pin_t;
static const ioboard_do_pin_t k_do_pin[IOBOARD_DO_COUNT] =
{
{ IOBOARD_DO_CH_GPIO_0_PORT, (uint32_t)IOBOARD_DO_CH_GPIO_0_PIN },
{ IOBOARD_DO_CH_GPIO_1_PORT, (uint32_t)IOBOARD_DO_CH_GPIO_1_PIN },
{ IOBOARD_DO_CH_GPIO_2_PORT, (uint32_t)IOBOARD_DO_CH_GPIO_2_PIN },
{ IOBOARD_DO_CH_GPIO_3_PORT, (uint32_t)IOBOARD_DO_CH_GPIO_3_PIN }
};
/* ======================== 内部状态 ======================== */
/*
* 开出影子寄存器:bit0..bit3 = 上一次成功写入的「1 = 吸合」语义。
* volatile:同时被任务与可能的 ISR 读,编译器不得把它缓存在寄存器里。
* 不需要锁:本模块只对整字节赋值(单指令原子),从不做「读-改-写」。
*/
static volatile uint8_t s_do_shadow = 0U;
/* DWT 周期计数器是否已确认可用(懒使能结果,1 = 可用) */
static uint8_t s_dwt_ready = 0U;
/* ======================== 内部函数:时间基准 ======================== */
/*
* 函数功能:确保 DWT 周期计数器可用(幂等懒使能)
* 入口参数:无
* 返回值:1 = 可用;0 = 不可用(被调试器锁住等)
* 限定条件:在临界区内调用更稳妥(其它模块也会置同一个位,但这是读-改-写)
* 函数说明:
* 本仓已有三处各自「懒使能且不清零」地打开 CYCCNT:App/log/console_log.c、
* App/util/task_prof.c、Drivers/BSP/ScreenLink/sb_link.c。task_prof.c 写明了
* 不清零的理由(清零会打乱别人正在进行的计时)。本模块沿用同一口径:
* · 只置 DEMCR.TRCENA 与 DWT.CTRL.CYCCNTENA,绝不清零 CYCCNT;
* · 幂等——别人先开过,再置一次位没有副作用;
* · 结果缓存进 s_dwt_ready,避免每次读寄存器。
* 为什么不用「固定次数 NOP」:NOP 的耗时随 Flash 等待周期、总线争用、优化等级变化,
* 而时序宏是以微秒为规格的;只有周期计数器能让 IOBOARD_HC165_ 系列宏名副其实。
*/
static uint8_t ioboard_dwt_ensure(void)
{
if (s_dwt_ready != 0U) {
return 1U;
}
/* 先开 DWT 总开关(TRCENA),再开 CYCCNT 计数 */
CoreDebug->DEMCR |= CoreDebug_DEMCR_TRCENA_Msk;
DWT->CTRL |= DWT_CTRL_CYCCNTENA_Msk;
/* 回读确认:部分调试配置下 CYCCNTENA 会被锁住写不进去 */
if ((DWT->CTRL & DWT_CTRL_CYCCNTENA_Msk) != 0U) {
s_dwt_ready = 1U;
return 1U;
}
return 0U;
}
/*
* 函数功能:忙等指定微秒(基于 DWT 周期计数器)
* 入口参数:us - 微秒数
* 返回值:无
* 限定条件:调用方必须已确认 ioboard_dwt_ensure() 返回 1;建议在临界区内
* 函数说明:
* · 用无符号差值 (CYCCNT - t0) 比较:CYCCNT 在 168 MHz 下约 25.6 s 回绕一次,
* 无符号减法在回绕处天然正确,而本函数最长 1 us,根本走不到回绕;
* · 周期数 = us × IOBOARD_CYCLES_PER_US(宏的出处见 ioboard.h)。
* ⚠ 这是「至少等够」,不是「正好等够」:循环读 CYCCNT 本身要几个周期,
* 实际会比名义值多几纳秒。对 74HC165 的「最小脉宽」约束而言,多等无害。
*/
static void ioboard_delay_us(uint32_t us)
{
uint32_t want = us * (uint32_t)IOBOARD_CYCLES_PER_US;
uint32_t t0 = DWT->CYCCNT;
/* 空转:时间源是 CYCCNT 本身,不需要 __NOP 也照样在走 */
while ((uint32_t)(DWT->CYCCNT - t0) < want) {
}
}
/* ======================== 内部函数:临界区与上下文 ======================== */
/*
* 函数功能:判断当前是否在中断上下文(含高优先级、不经 FreeRTOS 的中断)
* 入口参数:无
* 返回值:非 0 = 在中断上下文;0 = 在任务上下文
* 限定条件:只在 ARM Cortex-M 上成立
* 函数说明:
* 只看 ICSR.VECTACTIVE:0 表示正在线程模式,非 0 表示正处在某个异常(中断)里。
* 它直接来自内核寄存器,不依赖 FreeRTOS 是否已启动调度器,也不依赖调用方是不是
* FreeRTOS 管理的 ISR——所以「在中断里但没走 fromISR 参数」这种情况也能判出来。
* 刻意不排除 SysTick / PendSV(它们也是异常,VECTACTIVE 非 0):在那两个里
* 调用本驱动本来就不合适(会与内核自身冲突),判成 ISR 至少不会错误地走任务版临界区。
*/
static uint8_t ioboard_in_isr(void)
{
return ((SCB->ICSR & SCB_ICSR_VECTACTIVE_Msk) != 0U) ? 1U : 0U;
}
/*
* 函数功能:进入临界区,返回供 ioboard_exit_critical() 配套使用的状态字
* 入口参数:
* in_isr - 若已知是否在 ISR 就传 0/1,未知传 IOBOARD_CTX_AUTO
* p_using_isr - 输出,1 = 本次用的是 ISR 版临界区(退出时必须配套)
* 返回值:临界区状态字(BASEPRI/PRIMASK 原值),原样交给 ioboard_exit_critical()
* 限定条件:必须与 ioboard_exit_critical() 成对
* 函数说明:
* 三种情形,各自的理由:
* ① ISR 内 → taskENTER_CRITICAL_FROM_ISR():抬高 BASEPRI,返回原值。
* 在 ISR 里调 taskEXIT_CRITICAL() 会把 BASEPRI 直接写 0,等于把正在嵌套的
* 中断临界区提前放掉——平时没事,偏偏在高优先级 ISR 活跃时炸。
* ② 任务内且调度器已运行 → taskENTER_CRITICAL(),配 taskEXIT_CRITICAL()。
* ③ 调度器**尚未启动**(初始化阶段调用本驱动)→ taskENTER_CRITICAL() 在
* xTaskGetSchedulerState() 返回 taskSCHEDULER_NOT_STARTED 时是空操作,
* 临界区等于没有。此时改用 __disable_irq()/__enable_irq():
* 上电阶段关中断几十微秒无所谓,而且它比 BASEPRI 更强,
* 正好符合「装载/移位期间不许被任何异常打断」。
* 返回值统一成 uint32_t 状态字,两种宏的返回类型在 ARM 上都是无符号整型且语义都是
* BASEPRI,用一个变量承接、用一个出口函数分发,进出各只有一处。
*/
static uint32_t ioboard_enter_critical(uint8_t in_isr, uint8_t *p_using_isr)
{
uint8_t ctx_isr = (in_isr == IOBOARD_CTX_AUTO) ? ioboard_in_isr() : in_isr;
if (ctx_isr != 0U) {
*p_using_isr = 1U;
return (uint32_t)taskENTER_CRITICAL_FROM_ISR();
}
*p_using_isr = 0U;
if (xTaskGetSchedulerState() == taskSCHEDULER_RUNNING) {
taskENTER_CRITICAL();
return 0U;
}
/* 调度器未启动:自己关中断(见函数说明 ③) */
__disable_irq();
return IOBOARD_CTX_IRQ_OFF;
}
/*
* 函数功能:退出临界区(必须与 ioboard_enter_critical 的返回值严格配套)
* 入口参数:state - ioboard_enter_critical 的返回值
* using_isr - ioboard_enter_critical 写出的标志
* 返回值:无
* 限定条件:只能在对应的 ioboard_enter_critical 之后调用一次
* 函数说明:分支顺序与进入时一一对应,不可调换。判据先看 using_isr 这个显式标志,
* 再看 state 是否等于关中断标记——把「优先级 255 的 BASEPRI」错当成关中断形态
* 会在任务里留下永久关中断的死锁,所以两个条件一起判。
*/
static void ioboard_exit_critical(uint32_t state, uint8_t using_isr)
{
if (using_isr != 0U) {
taskEXIT_CRITICAL_FROM_ISR(state);
return;
}
if (state == IOBOARD_CTX_IRQ_OFF) {
__enable_irq();
return;
}
taskEXIT_CRITICAL();
}
/* ======================== 内部函数:引脚操作 ======================== */
/* SH/LD:低 = 异步并行装载,高 = 移位(TI SN74HC165,Functional Modes 真值表) */
#define IOBOARD_LD_ASSERT() (IOBOARD_HC165_LD_PORT->BSRR = (uint32_t)IOBOARD_HC165_LD_PIN << 16U)
#define IOBOARD_LD_RELEASE() (IOBOARD_HC165_LD_PORT->BSRR = (uint32_t)IOBOARD_HC165_LD_PIN)
/* CLK:低到高沿移位 */
#define IOBOARD_CLK_LOW() (IOBOARD_HC165_CLK_PORT->BSRR = (uint32_t)IOBOARD_HC165_CLK_PIN << 16U)
#define IOBOARD_CLK_HIGH() (IOBOARD_HC165_CLK_PORT->BSRR = (uint32_t)IOBOARD_HC165_CLK_PIN)
/* 读 QH(PE3)当前电平:一次 IDR 取值,1 = 高电平 */
#define IOBOARD_QH_READ() (((IOBOARD_HC165_QH_PORT->IDR & (uint32_t)IOBOARD_HC165_QH_PIN) != 0U) ? 1U : 0U)
/* ======================== 内部函数:就绪检查 ======================== */
/*
* 函数功能:检查 PC2 / PC3 / PE3 的 GPIO 模式是否仍是驱动要求的样子
* 入口参数:无
* 返回值:1 = 一致;0 = 不一致
* 限定条件:依赖 CubeMX 生成的引脚配置(见 ioboard.h 的引脚来源说明)
* 函数说明:
* 整块驱动的正确性建立在「PC2/PC3 是通用输出、PE3 是输入」上,而这套配置只在
* MX_GPIO_Init() 里写一次。若有人把它们改成复用/模拟/输入,开入会静默读错
* (全 1 或全 0 且永不变化)。把 MODER 读回来比对,把它变成可观测的失败。
* MODER 每脚 2 位:00 = 输入,01 = 通用输出;引脚号写死 2/3/3 与 ioboard.h 的
* 引脚表一一对应(引脚若搬迁,这里会先报错,正是想要的)。
*/
static uint8_t ioboard_pins_sane(void)
{
uint32_t ld_mode = (IOBOARD_HC165_LD_PORT->MODER >> 4U) & 3U; /* PC2 */
uint32_t clk_mode = (IOBOARD_HC165_CLK_PORT->MODER >> 6U) & 3U; /* PC3 */
uint32_t qh_mode = (IOBOARD_HC165_QH_PORT->MODER >> 6U) & 3U; /* PE3 */
if ((ld_mode != 1U) || (clk_mode != 1U)) {
return 0U;
}
if (qh_mode != 0U) {
return 0U;
}
return 1U;
}
/*
* 函数功能:把 74HC165 拉回并确认静止态(SH/LD = 高、CLK = 低),准备好时间基准
* 入口参数:无
* 返回值:BSP_OK / BSP_ERR_STATE
* 限定条件:在临界区内调用
* 函数说明:
* 静止态的定义来自手册:SH/LD = 高是移位模式(保持),SH/LD = 低是装载;
* 时钟停在低是手册那句 "CLK and CLK INH should be LOW before the LOW-to-HIGH
* transition of SH/LD" 的前置状态——停在别的状态会让下一次装载多出一位。
* 先写后读:写是把引脚拉回静止态,读是证明写生效。ODR 看「我们让它输出什么」,
* IDR 看「引脚上实际是什么」,两者都查,能抓到外部短路或强驱动。
*/
static bsp_err_t ioboard_check_idle(void)
{
uint32_t want_cycles;
uint32_t odr;
uint32_t idr;
/* 先按静止态写:时钟低 + 移位模式 */
IOBOARD_CLK_LOW();
IOBOARD_LD_RELEASE();
if (ioboard_dwt_ensure() == 0U) {
/* 没有时间基准就没有可靠的 bit 时序:明确报错,而不是勉强跑 */
return BSP_ERR_STATE;
}
/*
* 主频与周期换算系数复核:偏差超过 ±1 MHz 视为「构建配置与运行配置不一致」。
* 主频改了不会报错,只会让所有延时按比例偏,这是典型的静默错误;
* 宁可让开入报 BSP_ERR_STATE,也不让它悄悄跑在错误的时间上。
*/
want_cycles = (SystemCoreClock + 500000U) / 1000000U;
if (((uint32_t)IOBOARD_CYCLES_PER_US + 1U < want_cycles) ||
((uint32_t)IOBOARD_CYCLES_PER_US > want_cycles + 1U)) {
return BSP_ERR_STATE;
}
odr = IOBOARD_HC165_LD_PORT->ODR;
idr = IOBOARD_HC165_LD_PORT->IDR;
if ((odr & (uint32_t)IOBOARD_HC165_LD_PIN) == 0U) {
return BSP_ERR_STATE; /* SH/LD 没被拉高:引脚可能被别人占着 */
}
if ((idr & (uint32_t)IOBOARD_HC165_LD_PIN) == 0U) {
return BSP_ERR_STATE; /* 引脚实际为低:被短路或强驱动 */
}
if ((odr & (uint32_t)IOBOARD_HC165_CLK_PIN) != 0U) {
return BSP_ERR_STATE; /* CLK 没能停在低 */
}
if ((idr & (uint32_t)IOBOARD_HC165_CLK_PIN) != 0U) {
return BSP_ERR_STATE; /* CLK 引脚实际为高 */
}
return BSP_OK;
}
/* ======================== 内部函数:开出 ======================== */
/*
* 函数功能:按给定「1 = 吸合」语义把 4 路开出整组写到引脚上
* 入口参数:relay_mask - 已屏蔽到 bit0..bit3 的吸合意图
* 返回值:无
* 限定条件:任意上下文(BSRR 单次写原子;影子寄存器由调用方维护)
* 函数说明:
* 一、极性转换只在这一处:吸合位 → IOBOARD_DO_LEVEL_ACTIVE 指定的电平。
* 同一端口上「要置 1 的位」进 BSRR 低 16 位、「要清 0 的位」进 BSRR 高 16 位,
* **一次 32 位写**同时表达两个方向,所以这几路之间不存在中间态。
* 二、4 路分属 GPIOC(1 路)与 GPIOF(3 路),共两次写;每次写内部原子。
* 两次写之间只可能看到「旧态 → 新态」的跃迁,不会出现「目标态以外的组合」。
* 若将来业务要求 4 路严格同一时刻,需要硬件把它们挪到同一端口——记在 README。
* 三、按端口分段累加:不假设 4 路都落在同一端口(引脚改版时不用改本函数)。
*/
static void ioboard_do_apply(uint8_t relay_mask)
{
uint8_t i;
GPIO_TypeDef *port;
uint32_t set_bits = 0U;
uint32_t reset_bits = 0U;
port = k_do_pin[0].port;
for (i = 0U; i < (uint8_t)IOBOARD_DO_COUNT; i++) {
uint32_t active = (uint32_t)((relay_mask >> i) & 1U);
uint32_t level;
/* 唯一的极性映射点:吸合 = 1 时取 ACTIVE 电平,吸合 = 0 时取 RELEASE 电平 */
level = (active != 0U) ? (uint32_t)IOBOARD_DO_LEVEL_ACTIVE
: (uint32_t)IOBOARD_DO_LEVEL_RELEASE;
/* 端口切换:把上一段积累一次写出去 */
if (k_do_pin[i].port != port) {
if ((set_bits != 0U) || (reset_bits != 0U)) {
port->BSRR = set_bits | (reset_bits << 16U);
}
port = k_do_pin[i].port;
set_bits = 0U;
reset_bits = 0U;
}
if (level != 0U) {
set_bits |= k_do_pin[i].pin;
} else {
reset_bits |= k_do_pin[i].pin;
}
}
if ((set_bits != 0U) || (reset_bits != 0U)) {
port->BSRR = set_bits | (reset_bits << 16U);
}
}
/* ======================== 内部函数:开入时序核心 ======================== */
/*
* 函数功能:一次完整装载 + 8 拍移位,输出「H 在前」的原始比特(未做位序组装)
* 入口参数:bits - 长度 8 的输出缓冲
* 返回值:BSP_OK / BSP_ERR_STATE
* 限定条件:必须在临界区内调用(本函数自己不再加锁)
* 函数说明:每一行紧邻的注释都对应 TI SNx4HC165 数据手册的一条要求,
* 「依据」就是规格本身。改任何一行都要回到手册重读对应小节。
* 位序反转(H,G,...,A → A 在 LSB)不在这里做,交给 ioboard_di_assemble。
*/
static bsp_err_t ioboard_di_shift(uint8_t bits[IOBOARD_DI_COUNT])
{
uint8_t i;
bsp_err_t rc;
/* 步骤 0:确认静止态(CLK 低 + SH/LD 高),顺带确认 DWT 与主频换算 */
rc = ioboard_check_idle();
if (rc != BSP_OK) {
return rc;
}
/*
* 步骤 1:CLK 拉低。
* 依据:手册 7.1 节 "CLK and CLK INH should be LOW before the LOW-to-HIGH
* transition of SH/LD to prevent shifting the data when SH/LD goes HIGH."
* 步骤 0 已确认过;这里再写一次,是为了让「CLK 低」与「LD 拉低」在代码顺序上
* 紧邻,读代码的人不必回看上一函数就能确认二者之间没插别的东西。
*/
IOBOARD_CLK_LOW();
/*
* 步骤 2:SH/LD 拉低 = 异步并行装载。
* 依据:真值表 "SH/LD = L, CLK = X, CLK INH = X, SER = X → Parallel load",
* 即装载与时钟无关、异步完成,A..H 八个输入端此刻被搬进移位寄存器。
*/
IOBOARD_LD_ASSERT();
/* 步骤 3:装载脉冲宽度。依据:tw(SH/LD low) 最慢列 120 ns,取 1 us(8 倍余量) */
ioboard_delay_us(IOBOARD_HC165_LOAD_PULSE_US);
/*
* 步骤 4:SH/LD 拉高 = 进入移位模式。
* 依据:前置条件(CLK 低)已由步骤 1 满足;tsu(SH/LD high before CLK↑) 120 ns
* 由步骤 5 的等待覆盖。
*/
IOBOARD_LD_RELEASE();
/*
* 步骤 5:等装载结果出现在 QH 上。
* 依据:tpd(SH/LD → QH) 最慢列 225 ns,取 1 us(4 倍余量)。
* 此刻 QH 上是 H 位(移位方向 A→…→H→QH,H 离输出最近)。
*/
ioboard_delay_us(IOBOARD_HC165_LOAD_SETTLE_US);
/*
* 步骤 6:8 次「采样 → 上升沿 → 下降沿」。
* 依据:真值表 "SH/LD = H, CLK = ↑ → Shift",数据向 QH 方向移动。
* 第一次采样落在装载后的 H 位,之后每个上升沿把下一位顶到 QH,
* 所以采样顺序是 H, G, F, E, D, C, B, A。
* 为什么「先读再打沿」:手册时序图里 QH 的数据在上升沿**之前**已经稳定;
* 上升沿之后 QH 要过 tpd 才变成新值。若改成「先打沿再读」,要么每次都要等 tpd,
* 要么在第 8 个沿后读到 SER 端的内容而不是 A 位——那是典型的「多读一位」错误。
*/
for (i = 0U; i < (uint8_t)IOBOARD_DI_COUNT; i++) {
/* 6a:读 QH(一次 IDR 取值,不会被分段读拼出跨时刻的假值) */
bits[i] = IOBOARD_QH_READ();
/* 6b:上升沿,把下一位顶到 QH */
IOBOARD_CLK_HIGH();
/* 6c:高电平保持。依据:tw(CLK high) 最慢列 120 ns,取 1 us */
ioboard_delay_us(IOBOARD_HC165_CLK_PHASE_US);
/* 6d:下降沿。不触发移位,只为下一个上升沿复位电平 */
IOBOARD_CLK_LOW();
/* 6e:低电平保持。依据:tw(CLK low) 最慢列 120 ns,取 1 us */
ioboard_delay_us(IOBOARD_HC165_CLK_PHASE_US);
}
/*
* 步骤 7:收尾。6d 之后 CLK 已是低、SH/LD 仍为高,正是静止态,
* 下一次装载可以立刻开始。状态本就正确,这里不再补写。
*/
return BSP_OK;
}
/*
* 函数功能:开入读取的公共实现(ioboard_di_read 与 _from_isr 共用)
* 入口参数:out_mask - 输出
* in_isr - 上下文(0 / 1 / IOBOARD_CTX_AUTO)
* 返回值:见 ioboard.h
* 限定条件:无
* 函数说明:时序段在临界区里;纯逻辑组装放在临界区外,少占几微秒的关中断时间。
* 读失败时**不写** *out_mask——「读失败」与「读到全 0」必须可区分,
* 这是本项目 BSP 失败可观测性的铁律,判断权留给上层。
*/
static bsp_err_t ioboard_di_read_impl(uint8_t *out_mask, uint8_t in_isr)
{
uint8_t bits[IOBOARD_DI_COUNT] = {0U};
uint8_t using_isr = 0U;
uint32_t state;
bsp_err_t rc;
if (out_mask == NULL) {
return BSP_ERR_PARAM;
}
state = ioboard_enter_critical(in_isr, &using_isr);
rc = ioboard_di_shift(bits);
ioboard_exit_critical(state, using_isr);
if (rc != BSP_OK) {
return rc;
}
*out_mask = ioboard_di_assemble(bits);
return BSP_OK;
}
/* ======================== 对外接口 ======================== */
/*
* 函数功能:初始化开入开出驱动
* 入口参数:无
* 返回值:见 ioboard.h
* 限定条件:任意上下文;应在 MX_GPIO_Init() 之后调用
* 函数说明:
* 本函数**不调用 HAL_GPIO_Init**——引脚模式/速度/上下拉由 MX_GPIO_Init() 唯一负责,
* 在这里再 Init 一遍只会让 CubeMX 显示的引脚状态与真相脱节,下次重生成还会被覆盖。
* 只做四件事:清影子寄存器、自检引脚模式、确认并拉回静止态、整组释放 4 路开出。
*/
bsp_err_t ioboard_init(void)
{
uint8_t using_isr = 0U;
uint32_t state;
bsp_err_t rc = BSP_OK;
state = ioboard_enter_critical(IOBOARD_CTX_AUTO, &using_isr);
/* 一、影子寄存器先归零:之后任何路径失败,ioboard_do_get 都报「全释放」 */
s_do_shadow = 0U;
/* 二、引脚模式自检 */
if (ioboard_pins_sane() == 0U) {
rc = BSP_ERR_STATE;
}
/* 三、静止态确认(内部顺带使能 DWT、复核主频换算) */
if (rc == BSP_OK) {
rc = ioboard_check_idle();
}
/*
* 四、上电全释放:即便上面某步报错也照样写——安全态优先于错误码。
* 即便 MX_GPIO_Init 已经写过 RESET,这里也显式再写一次:
* 「初值靠 CubeMX 设对」是隐式契约,显式写一次只花几条指令,
* 换来「上电全释放」不依赖别的模块。
*/
ioboard_do_apply(s_do_shadow);
ioboard_exit_critical(state, using_isr);
return rc;
}
/*
* 函数功能:读一次 8 路开入
* 入口参数:out_mask - 输出,bit0 = A … bit7 = H
* 返回值:见 ioboard.h
* 限定条件:任意上下文(内部自动判别)
*/
bsp_err_t ioboard_di_read(uint8_t *out_mask)
{
return ioboard_di_read_impl(out_mask, IOBOARD_CTX_AUTO);
}
/*
* 函数功能:读一次 8 路开入(ISR 专用形态)
* 入口参数:out_mask - 输出,bit0 = A … bit7 = H
* 返回值:见 ioboard.h
* 限定条件:只允许在中断上下文调用
* 函数说明:与 ioboard_di_read 的唯一区别是强制走 FROM_ISR 临界区。
* 留着独立入口不是为了性能,是为了让「谁在 ISR 里读开入」在调用点一眼可见——
* 排查临界区嵌套问题时,grep _from_isr 就能列出全部调用点。
*/
bsp_err_t ioboard_di_read_from_isr(uint8_t *out_mask)
{
return ioboard_di_read_impl(out_mask, 1U);
}
/*
* 函数功能:整组写 4 路开出
* 入口参数:mask - bit0..bit3,1 = 吸合;高位忽略
* 返回值:BSP_OK
* 限定条件:任意上下文
* 函数说明:
* 一、高位忽略而不报错:上层常把状态字原样传下来,那是契约外的噪声,不是错误参数;
* 而「传了带高位的值」与「忘了屏蔽」无法区分,所以选择宽容。
* 二、不判断「是否已 init」:影子寄存器初值就是 0(全释放),引脚已由 MX_GPIO_Init
* 配好,init 之前调用也安全。
* 三、影子寄存器在写引脚**之前**更新:若写引脚过程中被更高优先级中断打断,
* 上层查到的「我让它是什么」仍是调用方这次要的值,不会闪回旧值。
* 不设临界区:整字节赋值是单指令原子,BSRR 写本身也原子。
*/
bsp_err_t ioboard_do_write(uint8_t mask)
{
uint8_t relay = (uint8_t)(mask & IOBOARD_DO_MASK_ALL);
s_do_shadow = relay;
ioboard_do_apply(relay);
return BSP_OK;
}
/*
* 函数功能:读软件影子寄存器
* 入口参数:out_mask - 输出,bit0..bit3,1 = 吸合
* 返回值:见 ioboard.h
* 限定条件:任意上下文
*/
bsp_err_t ioboard_do_get(uint8_t *out_mask)
{
if (out_mask == NULL) {
return BSP_ERR_PARAM;
}
*out_mask = s_do_shadow;
return BSP_OK;
}
/*
* 函数功能:读 4 路开出引脚的实际输出电平(调试/上板验证用)
* 入口参数:out_level - 输出,bit n = 1 表示第 n 路引脚当前为高电平
* 返回值:见 ioboard.h
* 限定条件:任意上下文
* 函数说明:
* 用 ODR 而不是 IDR:ODR 是「我们让它输出什么」,IDR 是「引脚上实际是什么」。
* 这里要和影子寄存器对照,判断「有没有人在 ioboard 之外写了同一根引脚的 ODR」,
* 所以要 ODR。若想查外部短路,那要看 IDR——由 ioboard_check_idle 对 LD/CLK 做了。
* 按端口各取一次 ODR 再逐路拼,不逐路读寄存器。
*/
bsp_err_t ioboard_do_read_level(uint8_t *out_level)
{
uint8_t i;
uint8_t level = 0U;
uint32_t odr_c;
uint32_t odr_f;
uint32_t odr;
if (out_level == NULL) {
return BSP_ERR_PARAM;
}
odr_c = IOBOARD_DO_CH_GPIO_0_PORT->ODR;
/* GPIOF 与 GPIOC 不同时也可能是同一个端口(引脚改版):同一对象重复读无害 */
odr_f = IOBOARD_DO_CH_GPIO_1_PORT->ODR;
for (i = 0U; i < (uint8_t)IOBOARD_DO_COUNT; i++) {
if (k_do_pin[i].port == IOBOARD_DO_CH_GPIO_0_PORT) {
odr = odr_c;
} else if (k_do_pin[i].port == IOBOARD_DO_CH_GPIO_1_PORT) {
odr = odr_f;
} else {
odr = k_do_pin[i].port->ODR; /* 第 3 个端口(当前不存在):退化为单读 */
}
if ((odr & k_do_pin[i].pin) != 0U) {
level |= (uint8_t)(1U << i);
}
}
*out_level = level;
return BSP_OK;
}
+259
View File
@@ -0,0 +1,259 @@
#ifndef IOBOARD_H
#define IOBOARD_H
/*
* 模块名称:开入开出板 BSP(74HC165 开入 + 光耦继电器开出)
* 模块功能:把「板上的引脚与时序」翻译成两件事——读 8 路开入、整组写 4 路开出。
* 只回答「让硬件动起来并如实汇报」,不回答「该不该动」:
* 不做过流判据、不做互锁策略、不碰 IEC 104、不建 RTOS 任务。
* 适用平台:STM32F407ZGT6 + FreeRTOS(裸机不可用:临界区走 FreeRTOS 宏)
* 作者:王建锋
* 创建日期:2026-11-16
* 修改记录:
* 2026-11-16 王建锋 创建:74HC165 装载/移位时序 + 4 路光耦继电器整组写
*
* 引脚来源(三处一致,改动必须走 CubeMX 重生成,不许在此手补初始化):
* STM32F407-Demo.ioc → Inc/main.h 的 <Label>_Pin / <Label>_GPIO_Port 宏
* → Src/gpio.c 的 MX_GPIO_Init()。本驱动只引用 main.h 的宏,不写死 GPIO_PIN_x。
* V0.1 实测(2026-11-16 核对):
* HC165_LD (PC2) 输出 PP 初值 SET(= 移位模式)+ 速度 VERY_HIGH
* HC165_CLK (PC3) 输出 PP 初值 RESET(= 时钟低) + 速度 LOW
* HC165_IN2 (PE3) 输入,无上下拉
* KO6 (PC14) 输出 PP 初值 RESET
* TRIP_LED (PF0) 输出 PP 初值 RESET
* ERT_LED (PF1) 输出 PP 初值 RESET
* CLZ_LED (PF6) 输出 PP 初值 RESET
* PE2(IN_D4) / PE4(IN_E4) 是旧命名残留,硬件上无信号,本驱动**完全不碰**。
*/
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
#include "bsp_err.h"
/*
* 纯逻辑层(ioboard_bits.h / ioboard_bits.c)与硬件层(本头 / ioboard.c)**成对进构建**:
* ioboard.h 只 include ioboard_bits.h 取纯函数声明与常量;
* ioboard_di_assemble() 的**定义**在 ioboard_bits.c,链接时必须有它,
* 否则 ioboard.c 与任何调用方都会 undefined symbol。
* 只想要纯逻辑(主机侧单测、App 侧去抖模块)时:include ioboard_bits.h,
* 并把 ioboard_bits.c 编进链接即可,不需要也不应该 include 本头(本头会拉进 bsp_err.h)。
*/
#include "ioboard_bits.h"
/* ======================== 宏定义:引脚绑定 ======================== */
/*
* 引脚**编号**(PC2 / PC3 / PE3 / PC14 / PF0 / PF1 / PF6)只作说明与追溯,
* 真正的 <Label>_Pin 宏引用放在 ioboard.c 里——因为那些宏展开后是
* HC165_LD_GPIO_Port 这类 main.h 符号,一旦写进本头文件,任何 include ioboard.h
* 的上层文件(defaultTask、去抖模块、主机侧单测)就都被迫先 include main.h。
* 那样的后果不是编译错误而是「上层代码必须懂 MCU」——分层就此破掉。
*
* SH/LD = HC165_LD_Pin (PC2)
* CLK = HC165_CLK_Pin (PC3)
* QH = HC165_IN2_Pin (PE3)
* DO0 = KO6_Pin (PC14)
* DO1 = TRIP_LED_Pin (PF0)
* DO2 = ERT_LED_Pin (PF1)
* DO3 = CLZ_LED_Pin (PF6)
*
* 引脚改版(换脚/换端口)的唯一改点在 ioboard.c 顶部的引脚绑定区,本头文件不用动。
*/
/*
* 每路语义位(软件 mask,1 = 吸合)。
* 名字来自板级丝印(KO6 / TRIP_LED / ERT_LED / CLZ_LED),只作**追溯**,不是业务定义:
* 「跳闸 / 告警 / 闭锁」三个动作各自的判据与互斥规则属于业务层,BSP 不解释、不排序。
*/
#define IOBOARD_DO_KO6 ((uint8_t)(1U << 0)) /* DO0,PC14 */
#define IOBOARD_DO_TRIP ((uint8_t)(1U << 1)) /* DO1,PF0 */
#define IOBOARD_DO_ERT ((uint8_t)(1U << 2)) /* DO2,PF1 */
#define IOBOARD_DO_CLZ ((uint8_t)(1U << 3)) /* DO3,PF6 */
/* ======================== 宏定义:极性(唯一可改点) ======================== */
/*
* 开出极性:软件 mask 的 1 = 继电器吸合,硬件上「吸合」对应 GPIO 输出哪个电平,只由这一行决定。
*
* 当前取值 = 高电平有效,依据:用户口径(2026-11-16)「高电平 = 继电器吸合」。
* 内部结构推断(**未核原理图,仅作注释留档**):CubeMX 给 4 路的初值都是 RESET,
* 若低电平才是吸合,上电即 4 路全吸合——这不符合「上电全释放」的安全默认,
* 所以大概率是 GPIO 高 → 光耦二极管导通 → 继电器线圈得电。
* ⚠ 上板第一步必须用万用表验极性(README 的「上板验证」第 2 步),验反了就改这一行。
*
* 改这一行要注意:ioboard_init() 的「上电释放」会把**释放电平**写下去,
* 所以改极性无需另改初始化——它读的就是本宏。
*/
#define IOBOARD_DO_LEVEL_ACTIVE (1U) /* 1 = 高电平吸合;若硬件实测相反改成 0U */
/* 由上面的极性推出两档动作电平,供 .c 内部使用;不要在其它地方再写一遍高低 */
#define IOBOARD_DO_LEVEL_RELEASE ((IOBOARD_DO_LEVEL_ACTIVE) ? 0U : 1U)
/* ======================== 宏定义:时序(含单位,出处即规格) ======================== */
/*
* 全部时序依据 TI SN74HC165 数据手册(SNx4HC165 Rev.H,第 6.10 节 Timing Requirements),
* 取 VCC = 4.5 V 列(本板 74HC165 由 3.3 V 供电时按最慢的 2 V 列取,见下)。
*
* 手册原值(ns)。左为 25 C 列,右为 -40..85 C(SN74)最坏列,取后者:
* 25 C(2V/4.5V) -40..85 C(2V/4.5V)
* tw SH/LD 低脉冲宽度 120 / 24 120 / 24
* tw CLK 高或低脉冲宽度 120 / 24 120 / 24
* tsu SH/LD 高 在 CLK 上升沿前 120 / 24 120 / 24
* th PAR 数据 在 SH/LD 下降沿后 5 / 5 5 / 5
* tpd SH/LD 到 QH 225 / 30 225 / 45
* tpd CLK 到 QH 225 / 30 225 / 45
*
* 本驱动**不依赖具体电压**,一律按最慢的 2 V / 全温区列(120 ns、225 ns)再放大取整,
* 所以换 VCC 或换温度区间都不必重算:
* ├─ 装载脉冲:手册 120 ns → 取 1 us(8 倍余量);
* ├─ 等待装载完成:SH/LD↓ 之后 QH 要过一个 tpd(2 V 列 max 225 ns),取 1 us(4 倍余量);
* ├─ 时钟高/低相位:手册 120 ns → 取 1 us(8 倍余量);
* └─ 采样延时:CLK↑ 之后 QH 要过 tpd(2 V 列 max 225 ns),取 1 us 再读(4 倍余量)。
*
* ⚠ 这与 HC165_CLK 引脚在 CubeMX 里被配成 GPIO_SPEED_FREQ_LOW 是一致的、不是缺陷:
* LOW 档在 3.3 V / ~50 pF 负载下约 2 MHz 上限(t_rise+t_fall 约 500 ns 量级),
* 而本驱动一位要 >2 us(见下面的 IOBOARD_DI_READ_MAX_US),带宽利用率不到 25%。
* 如果将来要提速,**别改 gpio.c**——去 CubeMX 把 PC3 速度改成 MEDIUM/HIGH 再重生成,
* 然后在这里重算四个 *_NO 取值,并复核 IOBOARD_DI_READ_MAX_US 仍满足调用方的节拍。
*/
/* 单次装载时 SH/LD 保持低的时长(us):手册 tw(SH/LD low) 120 ns @2 V → 8 倍余量 */
#define IOBOARD_HC165_LOAD_PULSE_US 1U
/* SH/LD 由低升高的时刻:必须已经满足 tsu(SH/LD high before CLK↑) 与 tw(SH/LD low) */
#define IOBOARD_HC165_LOAD_SETTLE_US 1U
/* 每个时钟相位(高 / 低)的保持时长(us):手册 tw(CLK high or low) 120 ns @2 V → 8 倍余量 */
#define IOBOARD_HC165_CLK_PHASE_US 1U
/* CLK 上升沿之后到读 QH 的等待(us):躲开手册 tpd(CLK→QH) 2 V max 225 ns,留 4 倍余量 */
#define IOBOARD_HC165_QH_SETTLE_US 1U
/*
* ⚠ 关键前提:上面四个宏是**微秒**,而 DWT 只有**周期**。
* 微秒 → 周期的换算系数在这里写死一次(168 MHz 主频,168 周期 = 1 us,
* 与 App 侧 task_prof.h 的同一口径)。
* 主频改了不会报错,只会让所有延时按比例偏——所以 .c 里在运行期用
* SystemCoreClock 复核一次这个值,偏差超 1 % 就直接把 DI 读操作判成 BSP_ERR_STATE,
* 宁可让开入报错,也不让「延时悄悄变成 1/2」这种静默错误过夜。
*/
#define IOBOARD_CYCLES_PER_US 168U /* = SystemCoreClock / 1000000 */
/*
* 一次 ioboard_di_read 的最坏耗时(us)。用于让调用方判断能否放进它的节拍里,
* 以及留给「必须在临界区里」这句约定的量化依据:
* = 装载脉冲 1 + 装载等待 1 + 8 × (采样等待 1 + 时钟高 1 + 时钟低 1) = 26 us
* 这远小于 1 kHz tick 的 1000 us,关中断 26 us 不会让任何一方丢 tick。
*/
#define IOBOARD_DI_READ_MAX_US (IOBOARD_HC165_LOAD_PULSE_US + \
IOBOARD_HC165_LOAD_SETTLE_US + \
(IOBOARD_DI_COUNT * \
(IOBOARD_HC165_QH_SETTLE_US + \
(2U * IOBOARD_HC165_CLK_PHASE_US))))
/* ======================== 函数声明 ======================== */
/*
* 函数功能:初始化开入开出驱动(影子寄存器复位 + 静止态确认 + 上电全释放)
* 入口参数:无
* 返回值:BSP_OK - 初始化完成,4 路开出已处于释放态
* BSP_ERR_STATE - 静止态确认失败(回读到的 SH/LD 或 CLK 电平与预期不符)
* 限定条件:必须在 MX_GPIO_Init() 之后调用(推荐在 app_main_init 里,
* 与其它 BSP 的初始化一起,且**必须在任何业务代码写开出之前**)
* 函数说明:
* 一、**不重复调用 HAL_GPIO_Init**。7 根引脚的模式/上下拉/速度/上电初值全部由
* CubeMX 生成的 MX_GPIO_Init() 负责,在这里再 Init 一遍只会让 CubeMX 显示的
* 引脚状态与真相脱节,下次重生成还会被覆盖。
* 二、先把 SH/LD 写成高、CLK 写成低(静止态 = 移位模式 + 时钟低),再回读确认。
* 为什么要确认而不是直接写:如果有人在别处改过这两根脚(比如测试代码),
* 这里的确认能把「引脚被抢走」变成一次明确的 BSP_ERR_STATE,而不是让开入
* 从此静默读错。
* 三、最后把 4 路开出整组写成释放态,并让影子寄存器 = 0。
* 即便 MX_GPIO_Init 已经写过 RESET,这里仍显式写一次:初值「靠 CubeMX 设对」
* 是隐式契约,多一次显式写入只花几十个周期,换来上电全释放这条不依赖别人。
*/
bsp_err_t ioboard_init(void);
/*
* 函数功能:读一次 8 路开入(完整装载 + 8 拍移位)
* 入口参数:out_mask - 输出,bit0 = A 通道 … bit7 = H 通道(见 ioboard_bits.h)
* 返回值:BSP_OK - 读成功,*out_mask 有效
* BSP_ERR_PARAM - out_mask 为 NULL
* BSP_ERR_STATE - 驱动的引脚静止态被破坏(SH/LD 已被别人拉低等),本次未读数
* 限定条件:任意上下文可调(任务 / ISR 均可)。
* 内部按上下文自动选择临界区:
* 任务上下文 → taskENTER_CRITICAL()(屏蔽 configMAX_SYSCALL_INTERRUPT_PRIORITY
* 及以下的中断);ISR 上下文 → taskENTER_CRITICAL_FROM_ISR()
* (抬高 BASEPRI,返回原值,退出时恢复)。
* 为什么不能只给一套:在 ISR 里调 taskEXIT_CRITICAL() 会把 BASEPRI 直接写 0,
* 等于把正在嵌套的中断临界区提前放掉;反过来,在任务里调 FROM_ISR 版本也会
* 留下一个未恢复的 BASEPRI。两者都是「平时没事、偏偏在高优先级 ISR 活跃时炸」。
* 所以本接口自带上下文判别(见 .c 的 ioboard_enter_critical),调用方不用关心
* 自己在哪;另设独立的 ISR 入口,见下面 ioboard_di_read_from_isr。
* 函数说明:
* 全过程持锁的理由:74HC165 的装载/移位的「相位」由 8 个时钟沿的先后顺序定义,
* 中途被别的代码插进来动 PC2/PC3(或读走 QH 的中间态)就会位序错位;
* 而错位不报错,只表现为「开入状态差一位」——与线接错完全同形。
* 耗时上界 IOBOARD_DI_READ_MAX_US(当前 26 us)。
* 上下文判别只根据两种寄存器状态选临界区,不改变时序本身;两种形态的耗时差异
* 在 1 us 量级以内,不影响 IOBOARD_DI_READ_MAX_US 这个上界。
*/
bsp_err_t ioboard_di_read(uint8_t *out_mask);
/*
* 函数功能:ISR 专用版本:语义与 ioboard_di_read 完全相同,但使用 FROM_ISR 临界区
* 入口参数:out_mask - 同 ioboard_di_read
* 返回值:同 ioboard_di_read
* 限定条件:只允许在中断上下文调用(含 EXTI / 定时器回调 / FreeRTOS 软件定时器回调)
* 函数说明:单独留一个入口而不是靠宏切换,是为了让「谁在 ISR 里读了开入」在调用点
* 一眼可见——这个区别只在时序紧张的现场才变得关键,那时没人想回头查宏。
*/
bsp_err_t ioboard_di_read_from_isr(uint8_t *out_mask);
/*
* 函数功能:整组写 4 路开出(原子:一次写多个端口,不产生中间态)
* 入口参数:mask - bit0..bit3 对应 PC14/PF0/PF1/PF6,**1 = 继电器吸合**;
* bit4..bit7 无对应硬件,忽略(不报错:上层常直接把 4 位以上的状态原样传下)
* 返回值:BSP_OK - 已写入,影子寄存器已更新
* 限定条件:任意上下文可调;内部一次写入即可,无需临界区
* 函数说明:
* 一、极性只在本层转换:mask 进 → 按 IOBOARD_DO_LEVEL_ACTIVE 换成 BSRR 的置位/复位
* 两个字,然后**每个端口只写一次 BSRR**(BSRR 是高 16 位复位、低 16 位置位,
* 一次写同时表达「这几路置高、那几路置低」,所以 4 路之间没有中间态)。
* 二、4 路分散在 GPIOC(1 路)与 GPIOF(3 路)两个端口,两个 BSRR 写入之间隔着
* 几条指令(约 10 ns 量级)。这是同步时序的极限,业务层面不可观测;
* 若将来要求严格同时,需硬件把 4 路挪到同一端口——记在 README 的已知限制里。
* 三、影子寄存器在写入后更新,ioboard_do_get() 读到的就是「上一次成功写入的值」。
*/
bsp_err_t ioboard_do_write(uint8_t mask);
/*
* 函数功能:读软件影子寄存器(不是硬件回读——硬件无辅助触点回读通路)
* 入口参数:out_mask - 输出,bit0..bit3 = 上一次 ioboard_do_write 的 1=吸合语义
* 返回值:BSP_OK - 成功;BSP_ERR_PARAM - out_mask 为 NULL
* 限定条件:任意上下文可调
* 函数说明:只回答「我上次让它是什么状态」,不回答「继电器现在真的动没动」。
* 后者要上板用辅助触点或万用表量,README 有步骤。
*/
bsp_err_t ioboard_do_get(uint8_t *out_mask);
/*
* 函数功能:读 4 路开出引脚的**实际 GPIO 输出电平**(调试/上板验证用)
* 入口参数:out_level - 输出,bit n = 第 n 路引脚当前输出电平(1 = 高电平),
* 与「1=吸合」无关,是纯电气量
* 返回值:BSP_OK - 成功;BSP_ERR_PARAM - out_level 为 NULL
* 限定条件:任意上下文可调
* 函数说明:影子寄存器与这个值不一致 = 有人在 ioboard 之外动了这 4 根脚。
* 上板验证极性时用它,比只看影子寄存器更能抓到真问题。
*/
bsp_err_t ioboard_do_read_level(uint8_t *out_level);
#ifdef __cplusplus
}
#endif
#endif /* IOBOARD_H */
+34
View File
@@ -0,0 +1,34 @@
/*
* 模块名称:开入开出板的纯逻辑层(位序组装)
* 模块功能:74HC165 读到的比特序列 → 「A 在 LSB」的开入 mask。零寄存器、零依赖。
* 适用平台:只依赖 <stdint.h>;主机侧 MSVC 与 ARMCC 同一份源码编译。
* 作者:王建锋
* 创建日期:2026-11-16
* 修改记录:
* 2026-11-16 王建锋 创建
*/
#include "ioboard_bits.h"
/*
* 函数功能:把 74HC165 串行读出的 8 个比特组装成开入 mask(A 通道落在 bit0)
* 入口参数:bits - 长度 8;bits[i] = 第 i+1 个时钟沿之前从 QH 读到的电平
* 返回值:bit0 = A … bit7 = H
* 限定条件:纯函数
* 函数说明:详见 ioboard_bits.h 同名声明处的时序推导。这里是它在代码里的全部:
* 器件先吐 H 后吐 A,而接口要求 A 在 LSB,于是把第 i 次读到的东西塞进 7-i 位。
*/
uint8_t ioboard_di_assemble(const uint8_t bits[IOBOARD_DI_COUNT])
{
uint8_t mask = 0U;
uint8_t i;
for (i = 0U; i < (uint8_t)IOBOARD_DI_COUNT; i++) {
if ((bits[i] != 0U) && (i < (uint8_t)IOBOARD_DI_COUNT)) {
/* bits[0] 是 H(手册最高位)→ bit7;bits[7] 是 A → bit0 */
mask |= (uint8_t)(1U << ((uint8_t)(IOBOARD_DI_COUNT - 1U) - i));
}
}
return mask;
}
+58
View File
@@ -0,0 +1,58 @@
#ifndef IOBOARD_BITS_H
#define IOBOARD_BITS_H
/*
* 模块名称:开入开出板的纯逻辑层(位序组装)
* 模块功能:把「74HC165 按手册时序串行读出的 8 个比特」组装成「A 在 LSB」的开入 mask。
* 适用平台:只依赖 <stdint.h>,不 include HAL / CMSIS / FreeRTOS / main.h。
* 主机侧(MSVC)单测直接 include ioboard_bits.c 即可,无需任何桩目录。
* 作者:王建锋
* 创建日期:2026-11-16
* 修改记录:
* 2026-11-16 王建锋 创建:从 ioboard.c 拆出。位序是**静默错误**(错了不报错,只是
* 数据差一位),只能靠主机侧单测钉住——台架上「位序错一位」与
* 「线接错一位」完全同形,无法归因。
*/
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
/* ======================== 常量 ======================== */
/* 开入路数:74HC165 一片 8 位(两块级联,V0.1 只接回一块的数据线,见 README 已知限制) */
#define IOBOARD_DI_COUNT 8
/* 开出路数:4 路光耦驱动继电器 */
#define IOBOARD_DO_COUNT 4
/* 开入 mask 有效位:bit0..bit7 */
#define IOBOARD_DI_MASK_ALL ((uint8_t)((1U << IOBOARD_DI_COUNT) - 1U))
/* 开出 mask 有效位:bit0..bit3(bit4..bit7 无对应硬件) */
#define IOBOARD_DO_MASK_ALL ((uint8_t)((1U << IOBOARD_DO_COUNT) - 1U))
/* ======================== 纯函数 ======================== */
/*
* 函数功能:把 74HC165 串行读出的 8 个比特组装成开入 mask(A 通道落在 bit0)
* 入口参数:bits - 长度为 IOBOARD_DI_COUNT 的数组,bits[i] 为**第 i+1 个时钟沿之前**
* 从 QH(PE3)读到的电平;非 0 即视为高电平(传 0/1 亦可)
* 返回值:8 位开入 mask,bit0 = A 通道 … bit7 = H 通道
* 限定条件:纯函数,无寄存器/无全局状态,任意上下文可调(主机侧可测)
* 函数说明:依据 TI SN74HC165 数据手册(SNx4HC165 Rev.H,第 7.3 节 Functional Modes
* 真值表Shift 行:数据向 QH 方向移动,每个 CLK 低到高沿推出当前最靠前的比特):
* 第一个时钟沿**之前** QH 上已经是 H,第 8 个沿之前是 A。
* 即 reads = [H,G,F,E,D,C,B,A],组装时必须把 reads[0] 放到 bit7、reads[7] 放到 bit0,
* 等价于逐位从 LSB 往里塞:bit(7-i) = reads[i]。
* 算例(README 同款):只有 A 与 H 为 1 → reads=[1,0,0,0,0,0,0,1] → 0x81。
*/
uint8_t ioboard_di_assemble(const uint8_t bits[IOBOARD_DI_COUNT]);
#ifdef __cplusplus
}
#endif
#endif /* IOBOARD_BITS_H */
+1 -1
View File
@@ -23,7 +23,7 @@
- 采样数据的消费者 `App/task/adc_task.c` **已实现**(ADC 采集链路,2026-10-10:`tpafe5160_snapshot()` 原子取数 + 帧统计;`adcTask` 在 `Src/freertos.c` 的 `USER CODE` 区创建)。**v2.2(2026-10-10)**:采样节拍改由定时器更新中断硬件触发,本任务退化为纯消费者;**v2.8(2026-10-10)**:节拍源改 TIM3(同时经 TRGO 触发 ADC1 + DMA),STM32 侧改为消费 DMA 乒乓缓冲,单拍耗时 122 µs → **8 µs**
- CONVST→BUSY→RD 三段时序对**建立/保持时间敏感**,改动需对照芯片手册
- ⚠️ 本项目 ADC 相关功能**新增任务/缓冲前须核算 RAM**(见 `docs/内存管理/`);接消费者前的强制门禁见根 `AGENTS.md`「接 ADC / RS-485 消费者前的强制门禁」
- ⚠️ **通道语义不是通道号**:`buf[i]` 对应哪个电气量必须查 `docs/硬件平台/ADC通道映射说明.md`(`buf[2]=IA`、`buf[5]=UN`、`buf[6]=UA`);V0.1 上 8 路电气量分属两片转换器属硬件缺陷(`docs/任务规划/登记簿.md` §1)→ **禁止**跨转换器做相位/功率/功率因数类运算
- ⚠️ **通道语义不是通道号**:`buf[i]` 对应哪个电气量必须查 `docs/硬件平台/ADC通道映射说明.md`(`buf[2]=IA`、`buf[5]=UN`、`buf[6]=UA`);V0.1 上 8 路电气量分属两片转换器属硬件缺陷(`docs/任务规划/硬件改版登记.md` §1)→ **禁止**跨转换器做相位/功率/功率因数类运算
## 已知问题
+18
View File
@@ -57,8 +57,26 @@ void Error_Handler(void);
/* USER CODE END EFP */
/* Private defines -----------------------------------------------------------*/
#define IN_D4_Pin GPIO_PIN_2
#define IN_D4_GPIO_Port GPIOE
#define HC165_IN2_Pin GPIO_PIN_3
#define HC165_IN2_GPIO_Port GPIOE
#define IN_E4_Pin GPIO_PIN_4
#define IN_E4_GPIO_Port GPIOE
#define CH395_INT_Pin GPIO_PIN_5
#define CH395_INT_GPIO_Port GPIOE
#define KO6_Pin GPIO_PIN_14
#define KO6_GPIO_Port GPIOC
#define TRIP_LED_Pin GPIO_PIN_0
#define TRIP_LED_GPIO_Port GPIOF
#define ERT_LED_Pin GPIO_PIN_1
#define ERT_LED_GPIO_Port GPIOF
#define CLZ_LED_Pin GPIO_PIN_6
#define CLZ_LED_GPIO_Port GPIOF
#define HC165_LD_Pin GPIO_PIN_2
#define HC165_LD_GPIO_Port GPIOC
#define HC165_CLK_Pin GPIO_PIN_3
#define HC165_CLK_GPIO_Port GPIOC
#define ADC9_RES_Pin GPIO_PIN_0
#define ADC9_RES_GPIO_Port GPIOA
#define ADC10_IC_Pin GPIO_PIN_1
+16 -1
View File
@@ -337,7 +337,7 @@
<MiscControls>--diag_suppress=1,68,111,188,191,546,1293</MiscControls>
<Define>USE_HAL_DRIVER,STM32F407xx,NDEBUG</Define>
<Undefine />
<IncludePath>../Inc;../Drivers/STM32F4xx_HAL_Driver/Inc;../Drivers/STM32F4xx_HAL_Driver/Inc/Legacy;../Drivers/CMSIS/Device/ST/STM32F4xx/Include;../Drivers/CMSIS/Include;../Drivers/BSP;../Drivers/BSP/CH395F;../Drivers/BSP/GD5F2GQ5UE;../Drivers/BSP/TPAFE5160;../Drivers/BSP/SD2506;../Drivers/BSP/RS485;../Drivers/BSP/ScreenLink;../Drivers/BSP/NET;../Drivers/BSP/NET/lftpd;../Drivers/BSP/NETCFG;../App;../App/app;../App/algo;../App/cfg;../App/fs;../App/log;../App/sync;../App/task;../App/protocol/iec104;../App/util;../Middlewares/Third_Party/FreeRTOS/Source/include;../Middlewares/Third_Party/FreeRTOS/Source/CMSIS_RTOS_V2;../Middlewares/Third_Party/FreeRTOS/Source/portable/RVDS/ARM_CM4F;../Lib/dhara;../Lib/FatFs;../test/board;../Lib/lvgl;../Drivers/BSP/UI;../Lib;../Lib/coreSNTP/include</IncludePath>
<IncludePath>../Inc;../Drivers/STM32F4xx_HAL_Driver/Inc;../Drivers/STM32F4xx_HAL_Driver/Inc/Legacy;../Drivers/CMSIS/Device/ST/STM32F4xx/Include;../Drivers/CMSIS/Include;../Drivers/BSP;../Drivers/BSP/CH395F;../Drivers/BSP/GD5F2GQ5UE;../Drivers/BSP/TPAFE5160;../Drivers/BSP/SD2506;../Drivers/BSP/RS485;../Drivers/BSP/ScreenLink;../Drivers/BSP/NET;../Drivers/BSP/NET/lftpd;../Drivers/BSP/NETCFG;../Drivers/BSP/IOBOARD;../App;../App/app;../App/algo;../App/cfg;../App/fs;../App/log;../App/sync;../App/task;../App/protocol/iec104;../App/util;../Middlewares/Third_Party/FreeRTOS/Source/include;../Middlewares/Third_Party/FreeRTOS/Source/CMSIS_RTOS_V2;../Middlewares/Third_Party/FreeRTOS/Source/portable/RVDS/ARM_CM4F;../Lib/dhara;../Lib/FatFs;../test/board;../Lib/lvgl;../Drivers/BSP/UI;../Lib;../Lib/coreSNTP/include</IncludePath>
</VariousControls>
</Cads>
<Aads>
@@ -937,6 +937,11 @@
<FileType>1</FileType>
<FilePath>..\App\util\boot_stats.c</FilePath>
</File>
<File>
<FileName>ioboard_di.c</FileName>
<FileType>1</FileType>
<FilePath>..\App\util\ioboard_di.c</FilePath>
</File>
<File>
<FileName>vol_lock.c</FileName>
<FileType>1</FileType>
@@ -1653,6 +1658,16 @@
<FileType>1</FileType>
<FilePath>..\Drivers\BSP\ScreenLink\sb_link.c</FilePath>
</File>
<File>
<FileName>ioboard_bits.c</FileName>
<FileType>1</FileType>
<FilePath>..\Drivers\BSP\IOBOARD\ioboard_bits.c</FilePath>
</File>
<File>
<FileName>ioboard.c</FileName>
<FileType>1</FileType>
<FilePath>..\Drivers\BSP\IOBOARD\ioboard.c</FilePath>
</File>
<File>
<FileName>net_select.c</FileName>
<FileType>1</FileType>
+118 -71
View File
@@ -151,77 +151,86 @@ Mcu.IP9=SYS
Mcu.IPNb=16
Mcu.Name=STM32F407Z(E-G)Tx
Mcu.Package=LQFP144
Mcu.Pin0=PE5
Mcu.Pin1=PH0-OSC_IN
Mcu.Pin10=PA7
Mcu.Pin11=PC4
Mcu.Pin12=PC5
Mcu.Pin13=PB0
Mcu.Pin14=PB1
Mcu.Pin15=PB2
Mcu.Pin16=PF11
Mcu.Pin17=PF12
Mcu.Pin18=PG0
Mcu.Pin19=PG1
Mcu.Pin2=PH1-OSC_OUT
Mcu.Pin20=PB10
Mcu.Pin21=PB11
Mcu.Pin22=PB12
Mcu.Pin23=PB13
Mcu.Pin24=PB14
Mcu.Pin25=PB15
Mcu.Pin26=PG2
Mcu.Pin27=PG3
Mcu.Pin28=PG4
Mcu.Pin29=PG5
Mcu.Pin3=PA0-WKUP
Mcu.Pin30=PG6
Mcu.Pin31=PG7
Mcu.Pin32=PG8
Mcu.Pin33=PC6
Mcu.Pin34=PC7
Mcu.Pin35=PC8
Mcu.Pin36=PC9
Mcu.Pin37=PA8
Mcu.Pin38=PA9
Mcu.Pin39=PA10
Mcu.Pin4=PA1
Mcu.Pin40=PA11
Mcu.Pin41=PA12
Mcu.Pin42=PA13
Mcu.Pin43=PA14
Mcu.Pin44=PA15
Mcu.Pin45=PC10
Mcu.Pin46=PC11
Mcu.Pin47=PC12
Mcu.Pin48=PD2
Mcu.Pin49=PD5
Mcu.Pin5=PA2
Mcu.Pin50=PD6
Mcu.Pin51=PG9
Mcu.Pin52=PG10
Mcu.Pin53=PG11
Mcu.Pin54=PG12
Mcu.Pin55=PG13
Mcu.Pin56=PG14
Mcu.Pin57=PG15
Mcu.Pin58=PB3
Mcu.Pin59=PB4
Mcu.Pin6=PA3
Mcu.Pin60=PB5
Mcu.Pin61=PB6
Mcu.Pin62=PB7
Mcu.Pin63=PB8
Mcu.Pin64=PE0
Mcu.Pin65=PE1
Mcu.Pin66=VP_FREERTOS_VS_CMSIS_V2
Mcu.Pin67=VP_IWDG_VS_IWDG
Mcu.Pin68=VP_SYS_VS_tim7
Mcu.Pin69=VP_TIM3_VS_ClockSourceINT
Mcu.Pin7=PA4
Mcu.Pin8=PA5
Mcu.Pin9=PA6
Mcu.PinsNb=70
Mcu.Pin0=PE2
Mcu.Pin1=PE3
Mcu.Pin10=PC2
Mcu.Pin11=PC3
Mcu.Pin12=PA0-WKUP
Mcu.Pin13=PA1
Mcu.Pin14=PA2
Mcu.Pin15=PA3
Mcu.Pin16=PA4
Mcu.Pin17=PA5
Mcu.Pin18=PA6
Mcu.Pin19=PA7
Mcu.Pin2=PE4
Mcu.Pin20=PC4
Mcu.Pin21=PC5
Mcu.Pin22=PB0
Mcu.Pin23=PB1
Mcu.Pin24=PB2
Mcu.Pin25=PF11
Mcu.Pin26=PF12
Mcu.Pin27=PG0
Mcu.Pin28=PG1
Mcu.Pin29=PB10
Mcu.Pin3=PE5
Mcu.Pin30=PB11
Mcu.Pin31=PB12
Mcu.Pin32=PB13
Mcu.Pin33=PB14
Mcu.Pin34=PB15
Mcu.Pin35=PG2
Mcu.Pin36=PG3
Mcu.Pin37=PG4
Mcu.Pin38=PG5
Mcu.Pin39=PG6
Mcu.Pin4=PC14-OSC32_IN
Mcu.Pin40=PG7
Mcu.Pin41=PG8
Mcu.Pin42=PC6
Mcu.Pin43=PC7
Mcu.Pin44=PC8
Mcu.Pin45=PC9
Mcu.Pin46=PA8
Mcu.Pin47=PA9
Mcu.Pin48=PA10
Mcu.Pin49=PA11
Mcu.Pin5=PF0
Mcu.Pin50=PA12
Mcu.Pin51=PA13
Mcu.Pin52=PA14
Mcu.Pin53=PA15
Mcu.Pin54=PC10
Mcu.Pin55=PC11
Mcu.Pin56=PC12
Mcu.Pin57=PD2
Mcu.Pin58=PD5
Mcu.Pin59=PD6
Mcu.Pin6=PF1
Mcu.Pin60=PG9
Mcu.Pin61=PG10
Mcu.Pin62=PG11
Mcu.Pin63=PG12
Mcu.Pin64=PG13
Mcu.Pin65=PG14
Mcu.Pin66=PG15
Mcu.Pin67=PB3
Mcu.Pin68=PB4
Mcu.Pin69=PB5
Mcu.Pin7=PF6
Mcu.Pin70=PB6
Mcu.Pin71=PB7
Mcu.Pin72=PB8
Mcu.Pin73=PE0
Mcu.Pin74=PE1
Mcu.Pin75=VP_FREERTOS_VS_CMSIS_V2
Mcu.Pin76=VP_IWDG_VS_IWDG
Mcu.Pin77=VP_SYS_VS_tim7
Mcu.Pin78=VP_TIM3_VS_ClockSourceINT
Mcu.Pin8=PH0-OSC_IN
Mcu.Pin9=PH1-OSC_OUT
Mcu.PinsNb=79
Mcu.ThirdPartyNb=0
Mcu.UserConstants=
Mcu.UserName=STM32F407ZGTx
@@ -429,6 +438,20 @@ PC12.GPIO_Label=ST_TX1
PC12.Locked=true
PC12.Mode=Asynchronous
PC12.Signal=UART5_TX
PC14-OSC32_IN.GPIOParameters=GPIO_Label
PC14-OSC32_IN.GPIO_Label=KO6
PC14-OSC32_IN.Locked=true
PC14-OSC32_IN.Signal=GPIO_Output
PC2.GPIOParameters=GPIO_Speed,PinState,GPIO_Label
PC2.GPIO_Label=HC165_LD
PC2.GPIO_Speed=GPIO_SPEED_FREQ_VERY_HIGH
PC2.Locked=true
PC2.PinState=GPIO_PIN_SET
PC2.Signal=GPIO_Output
PC3.GPIOParameters=GPIO_Label
PC3.GPIO_Label=HC165_CLK
PC3.Locked=true
PC3.Signal=GPIO_Output
PC4.GPIOParameters=GPIO_Label
PC4.GPIO_Label=ADC17_UB
PC4.Locked=true
@@ -499,10 +522,30 @@ PE1.GPIO_Speed=GPIO_SPEED_FREQ_VERY_HIGH
PE1.Locked=true
PE1.PinState=GPIO_PIN_SET
PE1.Signal=GPIO_Output
PE2.GPIOParameters=GPIO_Label
PE2.GPIO_Label=IN_D4
PE2.Locked=true
PE2.Signal=GPIO_Input
PE3.GPIOParameters=GPIO_Label
PE3.GPIO_Label=HC165_IN2
PE3.Locked=true
PE3.Signal=GPIO_Input
PE4.GPIOParameters=GPIO_Label
PE4.GPIO_Label=IN_E4
PE4.Locked=true
PE4.Signal=GPIO_Input
PE5.GPIOParameters=GPIO_Label
PE5.GPIO_Label=CH395_INT
PE5.Locked=true
PE5.Signal=GPIO_Input
PF0.GPIOParameters=GPIO_Label
PF0.GPIO_Label=TRIP_LED
PF0.Locked=true
PF0.Signal=GPIO_Output
PF1.GPIOParameters=GPIO_Label
PF1.GPIO_Label=ERT_LED
PF1.Locked=true
PF1.Signal=GPIO_Output
PF11.GPIOParameters=GPIO_Speed,PinState,GPIO_PuPd,GPIO_Label
PF11.GPIO_Label=LED5
PF11.GPIO_PuPd=GPIO_PULLUP
@@ -517,6 +560,10 @@ PF12.GPIO_Speed=GPIO_SPEED_FREQ_HIGH
PF12.Locked=true
PF12.PinState=GPIO_PIN_SET
PF12.Signal=GPIO_Output
PF6.GPIOParameters=GPIO_Label
PF6.GPIO_Label=CLZ_LED
PF6.Locked=true
PF6.Signal=GPIO_Output
PG0.GPIOParameters=GPIO_Label
PG0.GPIO_Label=DB0
PG0.Locked=true
+33 -16
View File
@@ -46,16 +46,22 @@ void MX_GPIO_Init(void)
/* GPIO Ports Clock Enable */
__HAL_RCC_GPIOE_CLK_ENABLE();
__HAL_RCC_GPIOC_CLK_ENABLE();
__HAL_RCC_GPIOF_CLK_ENABLE();
__HAL_RCC_GPIOH_CLK_ENABLE();
__HAL_RCC_GPIOA_CLK_ENABLE();
__HAL_RCC_GPIOC_CLK_ENABLE();
__HAL_RCC_GPIOB_CLK_ENABLE();
__HAL_RCC_GPIOF_CLK_ENABLE();
__HAL_RCC_GPIOG_CLK_ENABLE();
__HAL_RCC_GPIOD_CLK_ENABLE();
/*Configure GPIO pin Output Level */
HAL_GPIO_WritePin(GPIOC, LED1_Pin|TP_RD_Pin, GPIO_PIN_SET);
HAL_GPIO_WritePin(GPIOC, KO6_Pin|HC165_CLK_Pin|TP_CONVST_Pin, GPIO_PIN_RESET);
/*Configure GPIO pin Output Level */
HAL_GPIO_WritePin(GPIOF, TRIP_LED_Pin|ERT_LED_Pin|CLZ_LED_Pin, GPIO_PIN_RESET);
/*Configure GPIO pin Output Level */
HAL_GPIO_WritePin(GPIOC, HC165_LD_Pin|LED1_Pin|TP_RD_Pin, GPIO_PIN_SET);
/*Configure GPIO pin Output Level */
HAL_GPIO_WritePin(GPIOB, LED2_Pin|LED3_Pin|LED4_Pin|CH395_SCS_Pin
@@ -64,20 +70,38 @@ void MX_GPIO_Init(void)
/*Configure GPIO pin Output Level */
HAL_GPIO_WritePin(GPIOF, LED5_Pin|LED6_Pin, GPIO_PIN_SET);
/*Configure GPIO pin Output Level */
HAL_GPIO_WritePin(TP_CONVST_GPIO_Port, TP_CONVST_Pin, GPIO_PIN_RESET);
/*Configure GPIO pin Output Level */
HAL_GPIO_WritePin(GPIOA, TP_OS2_Pin|TP_OS1_Pin|TP_OS0_Pin|ST_DIR4_Pin, GPIO_PIN_RESET);
/*Configure GPIO pin Output Level */
HAL_GPIO_WritePin(GPIOE, GD_CS_Pin|GD_HOLD_Pin, GPIO_PIN_SET);
/*Configure GPIO pin : CH395_INT_Pin */
GPIO_InitStruct.Pin = CH395_INT_Pin;
/*Configure GPIO pins : IN_D4_Pin HC165_IN2_Pin IN_E4_Pin CH395_INT_Pin */
GPIO_InitStruct.Pin = IN_D4_Pin|HC165_IN2_Pin|IN_E4_Pin|CH395_INT_Pin;
GPIO_InitStruct.Mode = GPIO_MODE_INPUT;
GPIO_InitStruct.Pull = GPIO_NOPULL;
HAL_GPIO_Init(CH395_INT_GPIO_Port, &GPIO_InitStruct);
HAL_GPIO_Init(GPIOE, &GPIO_InitStruct);
/*Configure GPIO pins : KO6_Pin HC165_CLK_Pin */
GPIO_InitStruct.Pin = KO6_Pin|HC165_CLK_Pin;
GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
GPIO_InitStruct.Pull = GPIO_NOPULL;
GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
HAL_GPIO_Init(GPIOC, &GPIO_InitStruct);
/*Configure GPIO pins : TRIP_LED_Pin ERT_LED_Pin CLZ_LED_Pin */
GPIO_InitStruct.Pin = TRIP_LED_Pin|ERT_LED_Pin|CLZ_LED_Pin;
GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
GPIO_InitStruct.Pull = GPIO_NOPULL;
GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
HAL_GPIO_Init(GPIOF, &GPIO_InitStruct);
/*Configure GPIO pins : HC165_LD_Pin TP_RD_Pin TP_CONVST_Pin */
GPIO_InitStruct.Pin = HC165_LD_Pin|TP_RD_Pin|TP_CONVST_Pin;
GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
GPIO_InitStruct.Pull = GPIO_NOPULL;
GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_VERY_HIGH;
HAL_GPIO_Init(GPIOC, &GPIO_InitStruct);
/*Configure GPIO pin : LED1_Pin */
GPIO_InitStruct.Pin = LED1_Pin;
@@ -131,13 +155,6 @@ void MX_GPIO_Init(void)
GPIO_InitStruct.Pull = GPIO_NOPULL;
HAL_GPIO_Init(TP_BUSY_GPIO_Port, &GPIO_InitStruct);
/*Configure GPIO pins : TP_RD_Pin TP_CONVST_Pin */
GPIO_InitStruct.Pin = TP_RD_Pin|TP_CONVST_Pin;
GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
GPIO_InitStruct.Pull = GPIO_NOPULL;
GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_VERY_HIGH;
HAL_GPIO_Init(GPIOC, &GPIO_InitStruct);
/*Configure GPIO pins : TP_OS2_Pin TP_OS0_Pin */
GPIO_InitStruct.Pin = TP_OS2_Pin|TP_OS0_Pin;
GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
+26
View File
@@ -44,6 +44,7 @@
#include "task_watchdog.h" /* task_wd_tick_probe():第 8b 轮时间源存活性取证 */
#include "adc_task.h" /* adc_tick_irq_notify():TIM3 采样节拍 → 唤醒 adcTask */
#include "sb_link.h" /* sb_link_ms_tick():TIM3 1 kHz 顺手做按键召唤延迟应答的毫秒时钟 */
#include "ioboard.h" /* ioboard_init():开入开出板上电确认(全释放 + 静止态) */
/* USER CODE END Includes */
/* Private typedef -----------------------------------------------------------*/
@@ -71,6 +72,13 @@
/* USER CODE BEGIN PV */
/* RS-485 实例与接收缓冲已收归 rs485.c(见 rs485.h 的 extern 导出) */
/*
* 开入开出板上电确认结果:0 = ioboard_init() 成功,1 = 失败。
* 只做取证用途,不参与任何控制决策——失败不阻断启动,理由见 main() 里
* 调用点的注释。放在 .noinit 之外(普通 .bss),每次上电由启动代码清零。
*/
uint8_t g_ioboard_init_rc;
/* USER CODE END PV */
/* Private function prototypes -----------------------------------------------*/
@@ -142,6 +150,24 @@ int main(void)
/* USER CODE BEGIN 2 */
HAL_Delay(100);
/*
* 开入开出板:在 app_main_init 之前把 4 路出口继电器钉在「全释放」。
*
* 为什么必须排在这里而不放进 app_main_init:
* 出口继电器由光耦驱动,一旦吸合就是一次真实的开关量输出。上电后到
* 应用层建立起自己状态之间的这段时间里,继电器不该处于任何「未定义」
* 位置。MX_GPIO_Init 给的初值已经是释放电平,本调用是把它**确认并锁存**
* 到影子寄存器,顺带把 74HC165 拉回静止态(SH/LD 高 + CLK 低),
* 让第一次 ioboard_di_read 不需要额外的补救动作。
*
* 为什么失败只记不拦:本函数返回错误说明引脚状态不符合预期(多半是
* 硬件问题),但这不该让整机停在上电阶段——网络、存储、采集仍要起来。
* 错误码留给开机自检与后续 ioboard_di_read 的失败计数去体现。
*/
if (ioboard_init() != BSP_OK) {
g_ioboard_init_rc = 1u; /* 供开机日志取证;不阻断启动 */
}
/* 应用层初始化(时间子系统优先,详见 app_main_init) */
app_main_init();
/* USER CODE END 2 */
+3 -3
View File
@@ -25,7 +25,7 @@ docs/
├── 环境与部署/ 环境搭建与部署核对清单
├── CI/ 远程 CI(Gitea Actions)唯一入口 —— **只涉及本机一台 runner,日常开发不必读**
├── UI设计/ UI 架构、页面设计、字体与模拟器
├── 硬件平台/ 网表分析报告与语义图
├── 硬件平台/ 网表分析报告与语义图 + ADC 通道映射 + 开入开出实施说明
├── 芯片手册/ 外部芯片数据手册转录(只读资料)
└── images/ 文档技术配图(SVG 产物,由脚本生成)
```
@@ -73,7 +73,7 @@ docs/
|---|---|
| [`项目架构总览.md`](架构设计/项目架构总览.md) | 系统全景:六层分层、启动时序、存储·网络·UI 栈、目录组织 |
| [`软件架构与运行时规格.md`](架构设计/软件架构与运行时规格.md) | 六层分层表 / 任务模型 / 就绪位表 / 启动时序图 / 线程通信机制表 / 工具链与工程约束——**位表、机制表、时序图以本档为准**(自产品需求档拆出,2026-10-30 再按软/硬拆分) |
| [`硬件规格与能力边界.md`](架构设计/硬件规格与能力边界.md) | 主控与内存 / V0.1 引脚分配表 / 存储器件 / 硬件版本兼容 / 能力边界 H1~H3——**引脚表与能力边界表以本档为准** |
| [`硬件规格与能力边界.md`](架构设计/硬件规格与能力边界.md) | 主控与内存 / V0.1 引脚分配表 / 存储器件 / 硬件版本兼容 / 能力边界 H1~H3——**引脚表与能力边界表以本档为准**;开入开出的实施细节见 [`硬件平台/开入开出实施说明.md`](硬件平台/开入开出实施说明.md) |
| [`STM32F4-Base存储架构说明.md`](架构设计/STM32F4-Base存储架构说明.md) | GD5F2GQ5UE SPI NAND 之上的三层存储软件栈(FTL / dhara / FatFs) |
| [`项目启动顺序管理.md`](架构设计/项目启动顺序管理.md) | CMSIS-RTOS v2 Event Flags 就绪屏障(`SYS_EVT_NET_READY` 等) |
| [`图形绘制流程.md`](架构设计/图形绘制流程.md) | 文档配图规范:SVG 生成器 / Mermaid 选型与检查清单 |
@@ -266,7 +266,7 @@ docs/
| 位置 | 内容 |
|---|---|
| [`任务规划/`](任务规划/README.md) | **两个文件**:`README.md` = 全项目推进顺序(唯一权威);`登记簿.md` = V0.1 硬件缺陷 → V0.2 改版要求。其余待办跟着所属模块走(各文档「已知限制 / 重开条件」节):采集数据可信度 → `docs/算法/采集与算法层设计说明.md` §13、台阶图 → `docs/硬件平台/ADC通道映射说明.md` §9、RS-485 → `docs/产品需求/产品需求设计文档.md` §5.10 |
| `硬件平台/` | 网表详细分析报告与语义图(V0.0 / V0.1);**[`ADC通道映射说明.md`](硬件平台/ADC通道映射说明.md)——V0.1 十七路 ADC 语义/网名/通道号权威映射表(固件取数、UI 显示、自检注入以此为准),含 §7 链路四段口径、§8 注入实测记录与 §9 数据可信五级台阶/波次退出判据** |
| `硬件平台/` | 网表详细分析报告与语义图(V0.0 / V0.1);**[`ADC通道映射说明.md`](硬件平台/ADC通道映射说明.md)——V0.1 十七路 ADC 语义/网名/通道号权威映射表(固件取数、UI 显示、自检注入以此为准),含 §7 链路四段口径、§8 注入实测记录与 §9 数据可信五级台阶/波次退出判据**;**[`开入开出实施说明.md`](硬件平台/开入开出实施说明.md)——74HC165 开入(8 路)与 4 路光耦继电器开出的接线、时序原理、软件分层与接口、上板验证步骤与已知限制** |
| `芯片手册/` | 外部芯片数据手册转录(CH395F / GD5F2GQ5UE / SD2506 / TPAFE5160 / RTL8305NBI 等) |
| `images/` | 文档技术配图(`.svg` 产物,由 `tools/arch_diagram/`、`tools/refgraph/` 生成) |
+1 -1
View File
@@ -44,7 +44,7 @@
| **1** | **端子 / 子板变比确认 → 多点标定** | 变比已按参数算定;标定未开工 | 缺标准源。开工前必须先拍板四件事(精度目标、变比来源、`eng=0` 期测频门处置、标定点数与分布),见 `docs/算法/采集与算法层设计说明.md` §13.13 |
| **2** | 标准源送检与第三方 104 主站验收 | 等待标定 | UA/IA 标定已完成;UN(零序电压 U0)本台架未接线,保护仍闭锁;送检窗口前 2 日冻结特性 |
| **3** | 定值 / 映射 / 遥测 / 软压板铺开 | 等排期 | 必须晚于标定,否则铺出去的全是 IV 点(两条不可颠倒的顺序见 `docs/产品需求/产品需求设计文档.md` §9.2) |
| **4** | 保护元件与采集增强 | 等待标准源或硬件改版 | 先给 UN 接 UZ+UN 并标定以解除闭锁;跨转换器相位 / 功率 / 对称分量类功能等 V0.2 硬件(缺陷见 `docs/任务规划/登记簿.md` §1) |
| **4** | 保护元件与采集增强 | 等待标准源或硬件改版 | 先给 UN 接 UZ+UN 并标定以解除闭锁;跨转换器相位 / 功率 / 对称分量类功能等 V0.2 硬件(缺陷见 `docs/任务规划/硬件改版登记.md` §1) |
| **5** | 其余结构与可靠性评估 | 排队 | 观察项的归属是各模块文档的「已知限制」节,不为清清单强做 |
| **6** | 验证窗口事项 | 逢条件顺带 | CI runner、PC peer、CH340、负向故障注入条件到位即执行 |
| **7** | 独立模块与暂缓项 | 当前不排 | 开入开出、104 文件传输单独立项;RS-485 见 `docs/产品需求/产品需求设计文档.md` §5.10;内存优化按自身重开条件(`docs/内存管理/RAM使用分析与优化方案.md`) |
@@ -7,3 +7,4 @@
|---|---|---|---|---|
| 双转换器无共同采样触发 | **8 路电气量分属两片转换器(V0.1 硬件缺陷,需下一版硬件修改)**——UA/UN/IA 走 TPAFE5160(16 位、8 通道同步、±5 V 双极性),UB/UC/IB/IC/IN 走 STM32 ADC(12 位、顺序扫描、0~3.3 V 单极性):① 两片转换器无共同采样触发 + STM32 侧顺序扫描(9 通道一轮 ≈ 67 µs)→ 跨转换器通道**无同一时刻性、相位关系不确定**,主板侧功率/功率因数/相角/对称分量类运算不成立;② 同族电气量精度与量程不一致(LSB ≈ 152.6 µV vs ≈ 806 µV,且 STM32 侧前端无中点偏置、负半周削顶);③ 语义与硬件归属交叉,固件映射/UI 通道序/自检注入须逐通道查表绕开 | 2026-10-10 定性更正(**撤销** 2026-10-09 建档时"有意分配、不要修正"的说法) | **V0.2 改版要求**:8 路电气量 UA/UB/UC/UN/IA/IB/IC/IN **全部接 TPAFE5160**,与 TPAFE 上 5 路备用路(AIN5/13/7/15/12)对调串联电阻在转换器一侧的目的地——元件数量与料号不变,属走线级改动。**V0.1 现板软件口径**:主板侧只做逐通道独立监视,禁止跨转换器做相位/功率/功率因数/矢量类运算(此类量取子板计量模块结果)。固件侧消费者已落地(ADC 采集链路,2026-10-10,按语义映射表取数)→ V0.2 改版只改映射表内容,上层语义与代码不动 | `../硬件平台/ADC通道映射说明.md` §1/§7;`../硬件平台/V0.1_网表详细分析报告.md` §1.4 V10、§6-3 |
| IA 前端差分滤波限制谐波带宽 | **IA 通道差分滤波电容 C35 = 100 nF 构成一阶低通 fc ≈ 796 Hz,谐波产品路线的硬件前置未清**——250 Hz 注入读数 −4.4 % 即前端真实衰减(板端读数忠实;R19/R21 各 1 k `docs/硬件平台/V0.1.tel`:49 + C35 跨接差分对,拓扑 FR-ADC-5 `docs/产品需求/产品需求设计文档.md`);工频测量不受影响,外推 5 次 −4.6 %、9 次 −13 %、15 次 −27 %、21 次(1050 Hz)−39.6 % | 2026-11-04(模型与实测数据 `docs/测试说明/测试数据/boot_log_data/20261104_ac_ia_rc_model.txt`) | **改版/改板方向**:C35 换 10 nF(fc≈8 kHz、21 次仅 −0.9 %;改板优先于软件逐阶修正——容差与温漂使修正表不可信,理由详 `docs/硬件平台/ADC通道映射说明.md` §8.2)+ **清点其余各路差分滤波电容容值**(网表无容值标注,C35 = 100 nF 系用户口头确认,其余各路未定);将来有示波器可按预测复核(250 Hz 差分分量额外滞后 ≈17°)。详述 `docs/硬件平台/ADC通道映射说明.md` §8.2 | `docs/测试说明/专项验证/ADC前端注入验证流程.md` 谐波记录 B 行;`docs/硬件平台/ADC通道映射说明.md` §8.2 |
| 开入开出板接线错误 | 端子接线错误 + 第二块 74HC165 数据输出未接回 MCU | ① 端子接线错误:C1应该接GND C2应该接VDD50 C15:RUN_LED C16:EXTKI1;② 两块 74HC165 级联、共用时钟 `HC165_CLK`=PC3 与装载脚 `HC165_LD`=PC2,但**第二块的数据输出(QH)在板上没有连到 MCU**——MCU 侧只有一路串行数据 `HC165_IN2`=PE3,故**实际只能读一块芯片的 8 位开入**(设计 16 路);`PE2`(IN_D4)/`PE4`(IN_E4) 为旧命名残留、硬件上无信号(用户 2026-11-16 口径);开入 8 路与 4 路光耦继电器出口的驱动已落地,业务层未接入 | 实施口径 `docs/硬件平台/开入开出实施说明.md`;能力边界 H3 见 `docs/架构设计/硬件规格与能力边界.md` |
@@ -47,10 +47,10 @@ dhara 失败类 +84;RO 另 +208,全是该失败类名表)→ `ER_IROM1`
<!-- MEM_SNAPSHOT:BEGIN generated by scripts/check_mem_numbers.py -->
| 区域 | 用量 | 容量 | 占比 |
|---|---|---|---|
| ER_IROM1 | 288,628 B (281.86 KB) | 1,048,576 B (1024 KB) | 27.5% |
| RW_IRAM1 | 97,248 B (94.97 KB) | 131,072 B (128 KB) | 74.2% |
| ER_IROM1 | 289,800 B (283.01 KB) | 1,048,576 B (1024 KB) | 27.6% |
| RW_IRAM1 | 97,368 B (95.09 KB) | 131,072 B (128 KB) | 74.3% |
| RW_CCM | 57,376 B (56.03 KB) | 65,280 B (64 KB) | 87.9% |
| **Flash (ROM 合计)** | **290,716 B (283.9 KB)** | 1,048,576 B (1024 KB) | **27.7%** |
| **Flash (ROM 合计)** | **291,904 B (285.1 KB)** | 1,048,576 B (1024 KB) | **27.8%** |
<!-- MEM_SNAPSHOT:END -->
各区的容量与常量来源:
+21 -4
View File
@@ -68,11 +68,27 @@
## 3. 链接规范
### 3.1 文档间互链:仓库根相对路径
### 3.1 文档间互链:两种形态,各有归属
文档之间引用**一律使用仓库根相对路径**(形如 `` `docs/xxx/yyy.md` `` 或 `[文本](docs/xxx/yyy.md)`),**不使用** `../` 相对链接。
文档之间引用**按形态分两种写法**,不能混用——`check_doc_links.py` 对两者的解析基准不同(见 §3.1b):
> 理由:根相对路径对文档所在层级不敏感,迁移子目录时**零改动**;`../` 形态在目录调整时会成片失效。
| 形态 | 写法 | 解析基准 | 用途 |
|---|---|---|---|
| **反引号路径**(推荐,全仓主导) | `` `docs/xxx/yyy.md` `` | **仓库根** | 正文里"指路"式的文档引用,不加链接文字时 |
| **markdown 链接** | `[文本](../xxx/yyy.md)` | **当前文档所在目录**(故必须用 `../`) | 需要可点击跳转时 |
**为什么反引号形态推荐根相对**:它对文档所在层级不敏感,迁移子目录时零改动;`../` 形态在目录调整时会成片失效。全仓 37 份文档用 `../` 形态只为可点击,正文指路一律走反引号根相对。
**为什么 markdown 链接只能用 `../`**:`check_doc_links.py` 的 A 类校验按 `path.parent / raw_path` 解析(相对当前文档目录),写成 `[文本](docs/xxx.md)` 会被解析成 `docs/当前目录/docs/xxx.md` 而不存在 → 门禁必红。**不要**为了让"看起来是根相对"而把 markdown 链接改成 `[文本](docs/xxx.md)`,那一定通不过。
### 3.1b 门禁怎么判这两类
| 类 | 形态 | 基准 | 校验器实现 |
|---|---|---|---|
| A 类「markdown 链接」 | `[文本](目标)` | 当前文档目录 → **必须 `../`** | `check_md_links()` |
| B 类「路径引用」 | `` `docs/xxx.md` `` | 仓库根 → **必须 `docs/` 开头** | `check_backtick_paths()` |
改文档链接前先判断自己写的是哪一类,再决定前缀,否则门禁报的错会指向一个"文件明明存在"的路径。
### 3.2 图片链接:文档所在目录相对
@@ -360,7 +376,8 @@
- [ ] 放在正确的子目录(目录名无空格)
- [ ] 文件名符合命名约定(无空格 / 主题词+类型后缀)
- [ ] UTF-8 无 BOM、LF 换行
- [ ] 互链用仓库根相对路径;图片用当前目录相对路径
- [ ] 反引号指路引用用仓库根相对(`docs/xxx.md`);markdown 可点击链接用当前目录相对(`../xxx.md`)——两类基准不同,见 §3.1
- [ ] 图片用当前目录相对路径
- [ ] 尚未创建/已删除的引用加 `[计划]` 或状态词
- [ ] 已在 [`README.md`](README.md) 对应章节登记一行(**否则视为未完成**)
- [ ] 若涉及任务表/栈,跑 `gen_task_table.py --check`
@@ -8,7 +8,7 @@
> 本档是**完整口径表**——**引脚分配表**与**硬件能力边界表(H1~H3)**以**本档为准**,
> 两处冲突以本档为准并回改总览。
> **硬件口径**:V0.1(`docs/硬件平台/V0.1_网表详细分析报告.md` + `Inc/main.h`)。
> **版本**:v1.0 **日期**:2026-10-30
> **版本**:v1.1 **日期**:2026-11-16
## 1. 主控与内存
@@ -37,6 +37,8 @@
| **USART2(RS-232 #3)** | UART | PD5 TX / PD6 RX | 经 U10 隔离 → U13 TPT3232E → CN1;固件目前未占用(日志实际走 UART5/RS232#1) |
| **UART5(RS-232 #1)** | UART | PC12 TX / PD2 RX | 经 U9 隔离 → U13 → CN1;**日志口**(115200,`/serial-boot-test` 采集通道) |
| **状态 LED ×6** | GPIO | PC5 / PB0 / PB1 / PB2 / PF11 / PF12 | **低电平点亮** |
| **74HC165 开入 ×8** | 串行移位 | **PC2 `SH/LD` / PC3 `CLK` / PE3 `QH`** | 两块级联、共用 PC2/PC3;**仅第一块的数据线接回 PE3**,故实际可读 8 路(第二块缺线,见 `../硬件平台/开入开出实施说明.md`)。PE2/PE4 为旧命名残留、硬件无信号 |
| **光耦继电器开出 ×4** | GPIO | **PC14 / PF0 / PF1 / PF6** | 每路驱动光耦二极管 → 继电器线圈;上电默认全释放 |
| SWD | — | PA13 SWDIO / PA14 SWCLK | V0.1 已修复 V0.0 的 SWCLK 引脚缺陷 |
| 调试口 | — | CN2(XH-3A,1=SWDIO/2=SWCLK/3=GND) | V0.1 由 H2 排针改为 XH 端子 |
@@ -66,10 +68,10 @@
## 5. V0.1 硬件能力边界(对产品的硬约束)
下列五条是**硬件事实**,不是软件缺陷;需求档 §5 的功能范围与 需求档 §9 的"等条件"项均由它们推导:
下列三条是**硬件事实**,不是软件缺陷;需求档 §5 的功能范围与 需求档 §9 的"等条件"项均由它们推导:
| # | 约束 | 具体内容 | 产品影响 | 解除条件 |
|---|---|---|---|---|
| H1 | **双转换器无共同采样触发** | 8 路电气量分属 TPAFE5160(16 位、8 通道同步、±5 V 双极性)与 STM32 ADC1(12 位、顺序扫描、0~3.3 V 单极性)两片;两片无共同触发,STM32 侧 9 通道一轮约 67 µs | 跨转换器的**相位 / 功率 / 功率因数 / 对称分量 / 三相同时刻判据**一律不成立 → 方向元件、PT/CT 断线、三相过流、零序过流延后 | **V0.2 硬件**:8 路电气量全部接 TPAFE(与备用路对调串联电阻,料号不变,走线级改动);固件只改映射表内容 |
| H2 | **STM32 侧无中点偏置** | 单极性 0~3.3 V,交流量负半周削顶 | `UB/UC/IB/IC/IN` 无有效值/相量,只能读码值**监视**;104 对应点恒置 IV | V0.2 补偏置 |
| H3 | **无出口继电器与开入回路** | 无跳闸/告警出口、无硬压板与开入遥信 | 保护动作只体现为**遥信 + 日志 + SOE**;104 遥控 `YK1~4/13/14` 否定确认 | 开入开出独立立项 + 硬件 |
| H3 | **出口继电器与开入回路已具备,业务层未接入** | 板上已实装 4 路光耦驱动继电器出口与 74HC165 开入回路(引脚见 §2;实施口径见 `../硬件平台/开入开出实施说明.md`)。**开入实际只有 8 路**:两块 74HC165 级联,但第二块的数据输出未接到 MCU,只能读一块芯片。驱动层(`Drivers/BSP/IOBOARD/`)为纯硬件抽象,不含业务判断 | 保护动作**仍**只体现为**遥信 + 日志 + SOE**(保护判据处未标定闭锁,无逻辑驱动开出);104 遥控 `YK1~4/13/14` 仍否定确认;4 路开出当前只可用于台架验证,**不得用于真实跳闸** | 业务层接入:保护判据标定解除闭锁、104 遥信点表接入开入、继电器动作语义(跳闸/告警/闭锁)定义 |
@@ -408,7 +408,7 @@ TPAFE 双极性补码可注负压;STM32 单极性负半周测不了。UA/UN/IA
| 注入分量 | 发生器设定 | UI 读数 (V) | 期望 (V) | 偏差 % | `phasor` 旁证 | 结论 |
|---|---|---|---|---|---|---|
| A 只注二次 | 100.00 Hz / Vpp 0.453 V | `Ia=0` / `Ia2=0.158` / `Ia5=0` | 0.160 / ≈0 | **−1.25 %** | —(A/B 步落在 18:22–18:28 日志盲区,心跳旁证未留) | **过**(±2 % 内;选择性成立——100 Hz 没漏进基波 / 五次桶) |
| B 只注五次 | 250.00 Hz / Vpp 0.453 V | `Ia=0` / `Ia2=0` / `Ia5=0.153`(2026-11-04 复测;11-02 初读 0.152) | ≈0 / 0.160 | **−4.4 %**(超 ±2 %) | —(两轮均未留 250 Hz 心跳旁证——带外信号 `meas:` 判不了,见上卡旁证行) | **过——已按「板端真实衰减」关闭(2026-11-04)**:−4.4 % = IA 前端差分滤波(C35 = 100 nF + R19/R21 各 1 k,一阶低通 fc ≈ 796 Hz)在 250 Hz 的真实衰减,**板端读数忠实,量与算都没错**(模型与数据 `docs/硬件平台/ADC通道映射说明.md` §8.2);工频 50 Hz 仅 −0.2 %,不受影响;选择性成立(基波 / 二次桶 = 0);谐波功能要板改(C35 换 10 nF)——登记 `docs/任务规划/登记簿.md` §1 |
| B 只注五次 | 250.00 Hz / Vpp 0.453 V | `Ia=0` / `Ia2=0` / `Ia5=0.153`(2026-11-04 复测;11-02 初读 0.152) | ≈0 / 0.160 | **−4.4 %**(超 ±2 %) | —(两轮均未留 250 Hz 心跳旁证——带外信号 `meas:` 判不了,见上卡旁证行) | **过——已按「板端真实衰减」关闭(2026-11-04)**:−4.4 % = IA 前端差分滤波(C35 = 100 nF + R19/R21 各 1 k,一阶低通 fc ≈ 796 Hz)在 250 Hz 的真实衰减,**板端读数忠实,量与算都没错**(模型与数据 `docs/硬件平台/ADC通道映射说明.md` §8.2);工频 50 Hz 仅 −0.2 %,不受影响;选择性成立(基波 / 二次桶 = 0);谐波功能要板改(C35 换 10 nF)——登记 `docs/任务规划/硬件改版登记.md` §1 |
| C 纯基波 | 50.00 Hz / Vpp 0.453 V(实际按 0.453 注,Vpp 2.263 那档未做) | `Ia=0.160` / `Ia2=0` / `Ia5=0`(2026-11-04 复测;11-02 初读 0.159) | ≈0 / ≈0 | 基波 **0.0 %**(对 0.160 读数;11-02 为 −0.6 %) | **有**:18:33:43 起串口可见窗 `C01 rms=1 / C04 rms=0 / C05 rms=0`,与 C 步工况吻合;2026-11-04 复测窗串口 `ia_mv=159↔160` 同刻印证屏显 | **过**(两谐波轨零值经串口旁证补认;基波读数两轮 ≤0.6 %,与幅值轮同档一致) |
| 叠加(原行,**本轮不做**) | 基波 + 二次 + 五次同段 | — | — | — | — | 发生器无谐波叠加 / ARB 功能 → 本轮不做·设备缺口·TC-PHASOR-006 单测覆盖(`test/host/phasor/phasor_test.c`,3 条谱线各 ±1 %,实跑 57/57 PASSED) |
@@ -263,6 +263,6 @@ test/host/adc_input/adc_input_test.c
### 4.3 不覆盖 V0.1 的硬件缺陷(双转换器无共同采样触发)
V0.1 上 8 路电气量分属两片转换器且**无共同采样触发**(`docs/任务规划/登记簿.md` §1),本层只做**逐通道独立监视**。
V0.1 上 8 路电气量分属两片转换器且**无共同采样触发**(`docs/任务规划/硬件改版登记.md` §1),本层只做**逐通道独立监视**。
"跨转换器相量合成"(线 / 负序 / 零序)不得在本层或 全周傅氏相量上做——属「线/负序/零序合成」且 V0.1 受限
(见 `docs/算法/继电保护功能复现规划.md` §1.6)。
+1 -1
View File
@@ -397,7 +397,7 @@ Q16 后是 1.0e10,而 int32 上限只有 2.147e9;UB/UC 走 STM32 更到 5.28
**观察项(都判读过、非缺陷)**:TPAFE 输入浮空读数钉在 ≈1743/1747 mV 静态(撤线后 UA/IA 出现——读 `meas:` 时先确认接线);未接线的 STM32 侧引脚码值随环境缓漂(UC/IC/IN/T),不消费即可;录波触发后 `drop` 涨一截是 SEALED 窗口设计内(`App/algo/wave_ring.c:50`,涨完冻结,判失败只看 `err`/`ovf`);采集链全程 Δ9998/10 s、`idle=0`、`adc1_err=0`(前置门 8 条全过)。
**IA 前端差分滤波 = 低通 fc ≈ 796 Hz**:C35 = 100 nF 跨接差分对,与 R19/R21 各 1 k([`V0.1.tel`](V0.1.tel):49)构成一阶低通;拓扑为 1 k 串联 + 1 k 接差分负端、不分压(`docs/产品需求/产品需求设计文档.md` FR-ADC-5)。**250 Hz 的 −4.4 % 就是这颗电容在该频点的真实衰减,板端读数忠实**,工频 50 Hz 仅 −0.2 % 不受影响。谐波测量不够用——同拓扑外推:5 次 ≈ −4.6 %(出 ±2 % 判据)、7 次 −8.5 %、9 次 −13.0 %、11 次 −17.7 %、13 次 −22.6 %、15 次 −27.2 %、21 次(1050 Hz)−39.6 %;C35 改 10 nF 则 fc ≈ 8 kHz、21 次仅 −0.9 %。**谐波功能产品化的硬件前置 = 板改小 C35 + 清点其余各路差分滤波电容容值**(登记 `docs/任务规划/登记簿.md` §1)。**为什么改板而不是软件逐阶修正**:修正系数依赖这颗电容的实际容值,而它有容差、随温度漂,每块板、每个温度都不一样,修正表跟不上;二次谐波制动这类“拿某次谐波幅值与基波比值”的判据,比值被前端畸变后判定就不可信。换 10 nF 后测量带内是平的,板端读数直接可信。证伪条件(有示波器再复核):该低通预测 250 Hz 差分分量额外滞后 ≈17°;模型与三点拟合 `docs/测试说明/测试数据/boot_log_data/20261104_ac_ia_rc_model.txt`。
**IA 前端差分滤波 = 低通 fc ≈ 796 Hz**:C35 = 100 nF 跨接差分对,与 R19/R21 各 1 k([`V0.1.tel`](V0.1.tel):49)构成一阶低通;拓扑为 1 k 串联 + 1 k 接差分负端、不分压(`docs/产品需求/产品需求设计文档.md` FR-ADC-5)。**250 Hz 的 −4.4 % 就是这颗电容在该频点的真实衰减,板端读数忠实**,工频 50 Hz 仅 −0.2 % 不受影响。谐波测量不够用——同拓扑外推:5 次 ≈ −4.6 %(出 ±2 % 判据)、7 次 −8.5 %、9 次 −13.0 %、11 次 −17.7 %、13 次 −22.6 %、15 次 −27.2 %、21 次(1050 Hz)−39.6 %;C35 改 10 nF 则 fc ≈ 8 kHz、21 次仅 −0.9 %。**谐波功能产品化的硬件前置 = 板改小 C35 + 清点其余各路差分滤波电容容值**(登记 `docs/任务规划/硬件改版登记.md` §1)。**为什么改板而不是软件逐阶修正**:修正系数依赖这颗电容的实际容值,而它有容差、随温度漂,每块板、每个温度都不一样,修正表跟不上;二次谐波制动这类“拿某次谐波幅值与基波比值”的判据,比值被前端畸变后判定就不可信。换 10 nF 后测量带内是平的,板端读数直接可信。证伪条件(有示波器再复核):该低通预测 250 Hz 差分分量额外滞后 ≈17°;模型与三点拟合 `docs/测试说明/测试数据/boot_log_data/20261104_ac_ia_rc_model.txt`。
**边界**:本节不证端子二次值(④ 段变比已算定、标定未做,`eng` 仍为 0,见 §7.2)/ 精度等级(要标准源)/ 跨转换器相位(V0.1 硬件缺陷)/ THD。
@@ -63,7 +63,7 @@
| V7 | **VCAP1/VCAP2(U17.71/106)旁路电容 C94/C79 值未标注**:数据手册要求 VCAP1/VCAP2 各接 1~4.7µF 低 ESR 陶瓷电容至 VSS(内部 1.2V LDO 稳定裕量) | 实测 C94/C79 容值(若为 100nF 则低于手册建议,168MHz 满负荷下 1.2V 轨纹量/稳定性需留意);值补录 BOM |
| V8 | **V15/J3/F3 子板 LED 3 线落在 PC13/PC14/PC15**(脚 7/8/9):备份域电源开关供电,手册 Note 3 限**灌流 ≤3mA、≤2MHz、不可作电流源** | 核子板 LED 驱动电流需求;超 3mA 则 V0.2 移足驱力脚或子板加三极管扩展 |
| V9 | **V0.1 主板 SDIO 固定引脚组全被占用**:PC6/PC7/PC8/PC9/PA8(TPAFE 控制)+ PA9(USART1)+ PC10/PC11/PC12/PD2(UART4/UART5)= SDIO 全部 10 脚(F407 SDIO 无重映射) | 架构约束备案:V0.1 主板**无 SDIO 能力**;当前设计不受影响(代码未启用 SDIO,FatFs 卷在 SPI NAND 上) |
| **V10** | **8 路电气量分属两片转换器(V0.1 硬件缺陷,V0.2 改版项)**:UA/UN/IA 走 TPAFE5160(16 位、同步、±5 V 双极性),UB/UC/IB/IC/IN 走 STM32 ADC(12 位、顺序扫描、0~3.3 V 单极性)→ 跨转换器通道**无同一时刻性**(相位关系不确定)、精度与量程不一致。详见 §6-3 与 [`ADC通道映射说明.md`](ADC通道映射说明.md) §1(2026-10-10 定性更正;缺陷登记在 `docs/任务规划/登记簿.md` §1) | **V0.2 改版**:8 路电气量 UA/UB/UC/UN/IA/IB/IC/IN **全部接 TPAFE5160**,与 TPAFE 上 5 路备用路(AIN5/13/7/15/12)对调串联电阻在转换器一侧的目的地——元件数量与料号不变,属走线级改动。V0.1 现板:主板侧只做逐通道监视,**不做**跨转换器的相位/功率/功率因数/矢量运算 |
| **V10** | **8 路电气量分属两片转换器(V0.1 硬件缺陷,V0.2 改版项)**:UA/UN/IA 走 TPAFE5160(16 位、同步、±5 V 双极性),UB/UC/IB/IC/IN 走 STM32 ADC(12 位、顺序扫描、0~3.3 V 单极性)→ 跨转换器通道**无同一时刻性**(相位关系不确定)、精度与量程不一致。详见 §6-3 与 [`ADC通道映射说明.md`](ADC通道映射说明.md) §1(2026-10-10 定性更正;缺陷登记在 `docs/任务规划/硬件改版登记.md` §1) | **V0.2 改版**:8 路电气量 UA/UB/UC/UN/IA/IB/IC/IN **全部接 TPAFE5160**,与 TPAFE 上 5 路备用路(AIN5/13/7/15/12)对调串联电阻在转换器一侧的目的地——元件数量与料号不变,属走线级改动。V0.1 现板:主板侧只做逐通道监视,**不做**跨转换器的相位/功率/功率因数/矢量运算 |
## 2. 元件级变化
@@ -246,7 +246,7 @@ VDD50、5V、C3.3V、CGND、AVDDL(成员同,仅 C3 封装变)、STM_VDDA
3. **ADC 通道映射表重写**(§6):**已落地** → [`docs/硬件平台/ADC通道映射说明.md`](ADC通道映射说明.md)(语义 UA/UB/UC/UN、IA/IB/IC/IN、V_ZL2=温度检测,其余 8 路备用;含 TPAFE `buf[0..7]` 下标映射、STM32 通道宏、自检注入口径)。STM32 侧 9 路中 8 路在 PA0~PA7(IN0~IN7),**网名 ADC17(pin 44 = PC4)实现时用 `ADC_CHANNEL_14`**——原文写的 `ADC_CHANNEL_12` 与"第 17 路 = V_ZL2"均已勘误:V0.1 中 **ADC17 网名承载 AIN2 = UB**,**V_ZL2 走 ADC14 = PA5 = `ADC12_IN5`**。当前代码未启用 STM32 ADC(`HAL_ADC_MODULE_ENABLED` 注释状态),属实现时的注意事项。
4. **裁剪**:删除/停用 LCD(H1 8080)与 KEY1~8 相关代码(若有);面板按键功能如仍需要,需另立需求(V0.1 已无板上按键,仅 SW1 复位保留)。
5. **13 条悬空 GPIO 线配置安全默认电平**(B3①):U18 桥 11 线(PE6/PC13/PC14/PC15/PF0/PF1/PF4/PF5/PF6/PC2/PC3,LED 灭/继电器断/告警静默)+ SPI 镜像 2 线(PF1/PF2);其中 3 线在 PC13/14/15,**只能灌流 ≤3mA**(V8)。
6. **EXTKI×3 读取(如启用)必须配在 PE2/PE3/PE4(脚 1/2/3)**——V0.0 §5.2 写的"PC13/14/15"是引脚搞错(那三脚在 V0.1 已被 V15/J3/F3 占用,见 §11.2);硬件通路(U18 A 侧→PE2/3/4)V0.1 未变。
6. **EXTKI×3 读取(如启用)必须配在 PE2/PE3/PE4(脚 1/2/3)**——V0.0 §5.2 写的"PC13/14/15"是引脚搞错(那三脚在 V0.1 已被 V15/J3/F3 占用,见 §11.2);硬件通路(U18 A 侧→PE2/3/4)V0.1 未变。**2026-11-16 现状更正**:本条前半句已不适用于新板——PE3 现为 74HC165 开入的串行数据线 `HC165_IN2`,PE2(`IN_D4`)/PE4(`IN_E4`) 为旧命名残留、硬件上无信号;开入开出实施口径见 [`开入开出实施说明.md`](开入开出实施说明.md)。
7. V0.0 §5.2 功能级断言照做(ADC 注入读回、RS485 回环、CH395F PHY 寄存器读回)。
## 10. 上板验证补充(在 V0.0 §5.1 基础上追加)
@@ -335,7 +335,7 @@ VDD50、5V、C3.3V、CGND、AVDDL(成员同,仅 C3 封装变)、STM_VDDA
- **电源脚**:VDD×12(17/30/39/52/62/72/84/95/108/121/131/144)→3.3V ✓;VSS×9(16/38/51/61/83/94/107/120/130)→GND ✓;VBAT(6)→3.3V(1.65~3.6V 范围内)✓;PDR_ON(143)→3.3V(片内 LDO 开启配置 ✓);VSSA(31)→AGND ✓;VREF+(32)→3.3V ✓(VREF+=VDDA 为标准接法);VCAP1(71)/VCAP2(106)→C94/C79→GND ✓(**值未标注,手册要求 1~4.7µF 低 ESR**,V7)
- **BOOT0(138)→GND** ✓(复位默认从 Flash 启动,配置正确)
- HSE:PH0/PH1(23/24)+12pF×2 ✓;CH395F INT:PE5(4) GPIO ✓;EXTKI×3:PE2/PE3/PE4(1/2/3) GPIO ✓
- HSE:PH0/PH1(23/24)+12pF×2 ✓;CH395F INT:PE5(4) GPIO ✓;EXTKI×3:PE2/PE3/PE4(1/2/3) GPIO ✓(**2026-11-16**:V0.1 主板的 PE2/PE3/PE4 现由开入开出板占用,PE3 = 74HC165 串行数据,见 [`开入开出实施说明.md`](开入开出实施说明.md))
- TPAFE 并口 DB0~15 = PG0~PG15(56/57/87~94/124~129/132)FT I/O ✓
- SPI1(NAND):PB3/4/5(133~135)=SCK/MISO/MOSI(AF5)✓,CS/HOLD/WP=PE0(141)/PE1(142)/PB8(139) GPIO ✓
- SPI2(CH395F):PB13/14/15(74~76)=SCK/MISO/MOSI(AF5)✓,CS=PB12(73) GPIO ✓
@@ -349,7 +349,7 @@ VDD50、5V、C3.3V、CGND、AVDDL(成员同,仅 C3 封装变)、STM_VDDA
1. **V0.1 的 U17 连接经数据手册核对全部电气成立**(AF/GPIO/ADC/SWD/电源/BOOT0 逐项无误),未发现"不可能连接";
2. V0.1 **修复了 V0.0 的 2 处真实设计缺陷**(B4:SWCLK 104→109——V0.0 实板 SWD 不通,实测飞线调通;B5:ADC17 46→44)——除接口裁剪外,这是本次改版最有实质的硬件收益;
3. 新核出 3 项关注点:**V7**(VCAP 电容值未标注)、**V8**(PC13/14/15 的 3mA 驱动限制 vs 子板 LED)、**V9**(V0.1 主板 SDIO 能力被完全占用——当前无碍,架构约束备案);
4. 代码侧同步项收敛为 4 条:TPAFE 控制 7 线迁移(§9-1)、13 条悬空 GPIO 安全电平(§9-5)、网名 ADC17(PC4)用 `ADC_CHANNEL_14`(§9-3,原写 `ADC_CHANNEL_12` 已勘误)、EXTKI 读 PE2/3/4 而非 PC13/14/15(§9-6);
4. 代码侧同步项收敛为 4 条:TPAFE 控制 7 线迁移(§9-1)、13 条悬空 GPIO 安全电平(§9-5)、网名 ADC17(PC4)用 `ADC_CHANNEL_14`(§9-3,原写 `ADC_CHANNEL_12` 已勘误)、EXTKI 读 PE2/3/4 而非 PC13/14/15(§9-6,**其中 PE2/PE3/PE4 已被 2026-11-16 开入开出板改写**——PE3 = 74HC165 数据线,PE2/PE4 无信号,见 [`开入开出实施说明.md`](开入开出实施说明.md));
5. V0.0 报告"引脚编号与数据手册不符"结论**撤销**,实物抽查项关闭,5 处文字表述追溯更正(§11.2)。
## 附录 A:比对方法
@@ -0,0 +1,381 @@
# 开入开出板实施说明
> **文档定位**:V0.1 主板「开入开出板」的**实施口径**——硬件接线、时序原理、软件分层与接口、上板验证步骤、已知限制。
> **一句话结论**:板上**能读 8 路开入、能控 4 路开出**;第二块 74HC165 的数据输出线在板上没接到 MCU,所以**开入是 8 路而不是设计的 16 路**。
> **相关文档**:引脚总表与能力边界 [`硬件规格与能力边界.md`](../架构设计/硬件规格与能力边界.md);
> 硬件缺陷登记 [`硬件改版登记.md`](../任务规划/硬件改版登记.md);V0.1 网表逐脚核对的出处 [`V0.1_网表详细分析报告.md`](V0.1_网表详细分析报告.md)。
> **版本**:v1.1 **日期**:2026-11-16
---
## 1. 这板子是干什么的、现在能不能用
**读这一节是为了在动手接线或写上层代码之前,先知道自己拿到的到底是一个"能用"的功能,还是"只有底座"的半成品。** 答案分三层:硬件实装了、驱动写好了、业务层还没接入——三层不能混为一谈。
### 1.1 干什么用
开入开出板给 DTU 补两类**开关量**能力(开关量指只有"通/断"两种状态、不含连续数值的信号,区别于 ADC 采的电压电流这类模拟量):
- **开入**(数字输入,DI):把断路器位置、隔离刀闸位置、硬压板投退这类**外部触点的通断状态**读进 MCU,供遥信、告警、联动判断使用。
- **开出**(数字输出,DO):由 MCU 输出电平,经**光耦**(把 MCU 侧的 3.3 V 弱电与继电器侧的强电隔开的光电器件)驱动**继电器线圈**,继电器触点再去控制外部回路。
### 1.2 现在能不能用——分三层看
| 层次 | 状态 | 依据 |
|---|---|---|
| **硬件** | ✅ 已具备 | 4 路光耦继电器出口 + 74HC165 开入回路在板上实装;引脚已由 CubeMX 配好并重生成(`Inc/main.h` 有宏、`Src/gpio.c` 的 `MX_GPIO_Init` 有初值) |
| **驱动(BSP 硬件抽象层)** | ✅ 已实现 | `Drivers/BSP/IOBOARD/` 下的纯逻辑层与 GPIO/时序层,只做引脚操作与位序组装,见本文「软件结构」一节 |
| **业务层** | ❌ 未接入 | 保护判据仍处**未标定闭锁**态;104 规约的遥信点表未接开入;继电器动作语义(哪路是跳闸、哪路是告警、哪路是闭锁)**尚未定义** |
**因此当前能做的**:用调试口读回 8 路开入的真实状态、单独驱动某一路继电器观察动作。
**当前不能做的**:让保护逻辑自动跳闸、把开入量作为 104 遥信上送、在 UI 上配置遥信点表。**即便开出通道能驱动,也不允许用它做真实跳闸**——保护判据未标定,误动的代价是断开一次真实负荷。
### 1.3 开入为什么只有 8 路
设计意图是两块 74HC165 级联、共 16 路开入。但**第二块芯片的数据输出线(QH)在板上没有连到 MCU**,MCU 侧只有 PE3 这一路串行数据输入。一次读操作移出的 8 位只能来自第一块芯片,第二块的 8 位**物理上到不了 MCU**。
这不是软件能绕开的问题——没有回传通路,读什么都是第一块芯片的数据。修法见本文「已知限制与后续」一节。
---
## 2. 硬件接线
**读这一节是为了照着接线、排查接线,以及在 CubeMX 重生成后核对引脚没有被改动。** 先看 MCU 侧的 7 根线,再看 74HC165 这一侧的两块芯片怎么接。
### 2.1 MCU 侧引脚表
| 引脚 | `Inc/main.h` 宏名 | 方向 | CubeMX 初值 | 接到哪里 |
|---|---|---|---|---|
| PC2 | `HC165_LD_Pin` | 推挽输出 | 高(移位态) | 两块 74HC165 的 `SH/LD`(装载脚),并联 |
| PC3 | `HC165_CLK_Pin` | 推挽输出 | 低 | 两块 74HC165 的 CLK,并联 |
| PE3 | `HC165_IN2_Pin` | 输入(无上下拉) | — | 第一块 74HC165 的 QH(串行输出) |
| PC14 | `KO6_Pin` | 推挽输出 | 见「开出极性」 | 光耦 → 第 1 路继电器线圈 |
| PF0 | `TRIP_LED_Pin` | 推挽输出 | 见「开出极性」 | 光耦 → 第 2 路继电器线圈 |
| PF1 | `ERT_LED_Pin` | 推挽输出 | 见「开出极性」 | 光耦 → 第 3 路继电器线圈 |
| PF6 | `CLZ_LED_Pin` | 推挽输出 | 见「开出极性」 | 光耦 → 第 4 路继电器线圈 |
宏名里的 `_LED` 是**历史命名**(这 4 个脚早期用作指示灯),现在驱动的是继电器线圈;`KO6` 里的 "KO" 是"开出"的拼音首字母缩写。
### 2.2 74HC165 侧:两块芯片共用两根控制线,数据线只有一根
- 两块芯片的 **CLK(PC3)并联**、**`SH/LD`(PC2)并联**。这意味着每一次装载、每一个移位拍,两块芯片的动作是**同时**的——时钟会把两块一起往前推。
- 但**只有第一块的 QH 接到了 MCU 的 PE3**;第二块的 QH 在板上**没有走线**,处在悬空。
- 正确级联的做法是"第一块 QH → 第二块的串行输入,第二块 QH → MCU"。板上的现况是这条链只接了前半段的一半,所以移出的 8 位始终来自第一块。
结论就是一句话:**级联的硬件骨架在,回传通路断了一截**,因此实际可读 8 路。补线方案见本文「已知限制与后续」。
### 2.3 旧命名残留:PE2 与 PE4
`Inc/main.h` 里还有 `IN_D4_Pin`(PE2)与 `IN_E4_Pin`(PE4)两个宏,`Src/gpio.c` 的 `MX_GPIO_Init` 也仍然把它们初始化成输入。但**这两根脚在硬件上没有信号**——是 V0.0 时代"三路外部开入 EXTKI 读取"方案留下的命名残留。
因此:
- **不要**把 PE2/PE4 当成可用的开入通道,读到什么都无意义;
- `Drivers/BSP/IOBOARD/` 的驱动**完全不碰这两根脚**(只初始化并在读操作里使用 PC2/PC3/PE3 与 4 根开出);
- 这两根脚的初始化留在 CubeMX 生成代码里,是历史遗留,不影响功能,但清理需要动 `USER CODE` 区之外的配置,**留给硬件改版时一并定夺**。
---
## 3. 时序原理
**读这一节是为了在读数和算例对不上时,能自己从头推一遍——而不是只能怀疑驱动。** 三个信号各司其职,先后顺序不是随意定的,是数据手册规定的。
### 3.1 三个信号各自干什么
| 信号 | 作用 |
|---|---|
| `SH/LD`(装载/移位选择) | **低电平 = 装载**:把 8 路并行输入(通道 A 到 H)一次性抄进芯片内部的 8 个触发器。**高电平 = 移位**:不再看并行输入,只在时钟沿上把内部数据往 QH 推 |
| CLK(时钟) | 只在 `SH/LD` 为高时有效。**上升沿**触发,每来一个沿,内部数据往前移一位,最后一位从 QH 出去 |
| QH(串行输出) | 芯片唯一的输出脚。装载完成后 QH 上就已经是 H 通道的电平 |
### 3.2 为什么顺序必须是「先拉低 CLK → LD 拉低装载 → LD 拉高 → 逐拍移位」
数据手册对这一步有明确要求:**`SH/LD` 由低升到高之前,CLK 必须已经是低**(原文 "CLK and CLK INH should be LOW before the LOW-to-HIGH transition of SH/LD to prevent shifting the data")——否则那次低到高的跳变会被当成一个时钟沿,把刚装载进来的数据当场推走一位,读出来整体错位。
所以驱动里固定的动作序列是:
1. 先把 CLK **拉低**(哪怕它本来就是低,也要显式置一次,保证前置条件成立);
2. 把 `SH/LD` **拉低**——此时并行数据被抄进内部寄存器;
3. 保持一小段延时,等数据稳定;
4. 把 `SH/LD` **拉高**——进入移位模式,此刻 QH 上已经是 H 通道的电平;
5. 读 QH(第 1 次)→ 打一个 CLK 上升沿 → 延时 → CLK 拉低 → 延时,重复 8 次。
### 3.3 为什么读出来的顺序是 H,G,F,E,D,C,B,A
因为装载是**并行同时**抄进去的,而移出只能一位一位从 QH 走:
- 装载完成、第一个时钟沿**之前**,QH 上已经是 **H**;
- 第 1 个时钟沿把 H 推出去,QH 变成 G;
- 第 2 个沿出 G,……第 8 个沿出 A;
- 所以**8 次读到的顺序是 H、G、F、E、D、C、B、A**,**A 是最先被推出去的,也就是最低位(LSB)**。
接口约定是「**bit0 = A、bit7 = H**」,与"读到的先后顺序"正好相反,所以组装时要把第 i 次读到的比特放进第 (7 − i) 位。
### 3.4 算例:只有 A 与 H 两路有信号
这个算例是**人工核对的第一依据**——台架读数与它不一致时,第一件事是照着这张表重算一遍,而不是去怀疑驱动。之所以选它,是因为它只有两个 1、位置一前一后,人脑推的时候不容易错。
**前提**:假设 8 路开入里只有通道 A 与通道 H 为高电平,其余 6 路为低。
| 时刻 | 动作 | 此刻 QH 上是 | 读到的值 | 该值最终落在 |
|---|---|---|---|---|
| 装载完成 | `SH/LD` 已拉低再拉高 | H | 1 | bit7 |
| 第 1 个 CLK 沿前 | — | G | 0 | bit6 |
| 第 2 个沿前 | — | F | 0 | bit5 |
| 第 3 个沿前 | — | E | 0 | bit4 |
| 第 4 个沿前 | — | D | 0 | bit3 |
| 第 5 个沿前 | — | C | 0 | bit2 |
| 第 6 个沿前 | — | B | 0 | bit1 |
| 第 7 个沿前 | — | A | 1 | bit0 |
- 读序列 = `[1, 0, 0, 0, 0, 0, 0, 1]`
- 组装(第 1 个 → bit7,第 8 个 → bit0):bit7 = 1、bit0 = 1,其余为 0
- **结果 mask = 0x81**
**这个算例已与实现核对一致**:`Drivers/BSP/IOBOARD/ioboard_bits.c` 的 `ioboard_di_assemble()` 用 `mask |= 1 << (7 - i)` 逐位放入,`i=0`(H)进 bit7、`i=7`(A)进 bit0,与上表完全吻合。同一结论也写在 `Drivers/BSP/IOBOARD/ioboard_bits.h` 的函数注释里。
**报告里只会看到十进制**:`0x81` 是十六进制写法(八位二进制 `1000_0001`),十进制是 **129**。调试口打印的若是十进制,看到 129 就是算例命中。
### 3.5 混合算例:多路同时有信号时怎么核对
只有一个 1 的图案容易读,**多路同时为 1 才是台架上真正会遇到的情况**,也最容易人工推错。下面三组图样按"从易到难"排列,前三组都用工具确认过(见本节末的核对方式),第四组专门用来说明**为什么不要自己临时心算**。
**混合算例一:H、G、B、A 四路有信号(推荐用它与 0x81 配对做人工核对)**
- 读序列 = `[1, 1, 0, 0, 0, 0, 1, 1]`(第 1、2、7、8 拍)
- 逐位落位:第 1 拍→bit7、第 2 拍→bit6、第 7 拍→bit1、第 8 拍→bit0
- **结果 mask = 0xC3**(十进制 195,二进制 `1100_0011`)
选它的理由:**非回文、非交替、也不是整段连续的 1**。它的 1 集中在两端、中间留空,既不会像交替图样那样在"正序/反序"之间产生互补值的巧合,也不会像 `0xF0`/`0x0F` 那样在"整体移位一位"的错误下看起来还像那么回事。
**交替算例:H、F、D、B 四路有信号**
- 读序列 = `[1, 0, 1, 0, 1, 0, 1, 0]`(第 1、3、5、7 拍)
- 逐位落位:→ bit7、bit5、bit3、bit1
- **结果 mask = 0xAA**(十进制 170,二进制 `1010_1010`)
它的反相版本(G、E、C、A 有信号,读序列 `[0,1,0,1,0,1,0,1]`)→ **0x55**(十进制 85)。这两条互为镜像,是很好的"方向判据":**如果读交替图样得到 0x5A 或 0xA5,说明组装时既没有整段反序、也没有整段正序,而是发生了某种位移或串位——先查时序,别急着改代码。**
这条图样有个必须提醒的来历:**2026-11-16 它在项目里先后被三个人算出 0xA5、0x5A、0xAA 三个值**。前两个都不是任何实现的输出,是人工推导时的正反序混淆与漏位。所以它虽然正确值已确认为 0xAA,但**不适合当人工核对的第一依据**——人工核对的顺序应当是:先用「只有 A → 0x01」「只有 H → 0x80」两条单比特用例,再用本节的 0x81 与 0xC3,最后才轮到交替图样。
**边界算例:全 0 与全 1**
- 全低 → 读序列全 0 → **mask = 0x00**
- 全高 → 读序列全 1 → **mask = 0xFF**
这两条对位序不敏感(反序、移位、串位都无法被发现),**只能用来证明"线通、能读到电平",不能用来证明位序对**。上板验证时先做这两条排除接线问题,再进位序核对。
**核对方式(为什么这几个数可以直接信)**:以上期望值不是凭手推写进文档的,而是与 `test/host/ioboard/` 的**主机侧单测**逐条对齐——该套件实测 **100/100 PASSED**。位序的主判据不是任何单一混合图样,而是:
1. **单比特两端**:「只有 A → 0x01」「只有 H → 0x80」两条。A 是最后移出的一位,若实现忘了反序,A 会落到 bit7;只测其中一个端点仍可能被"整体反序再取反"之类的等价变形骗过,两端同时钉住才能把"反序"这个动作本身锁死。
2. **八点双射穷举**:8 个位置分别单独放一个 1,断言结果恰好是 8 个互不相同的单比特、恰好覆盖 bit0 到 bit7 全部,且能摸到 bit7。这条覆盖了**完整的定义域**,单靠 A/H 两端抓不到"中间某两位合流到同一位"这类错误。
混合图样(0x81 / 0xC3 / 0xAA / 0x55)是在这两条主判据之上补充的**组合形态证据**,给人工在台架上做"一眼看得出对错"的对照用。
### 3.6 数据手册出处
三家厂商(TI、ST、Nexperia)的 74HC165 功能表一致,本节引用的行为都出自其中的"功能模式"真值表:
- TI SN74HC165:[https://www.ti.com/tw/lit/gpn/sn74hc165-q1](https://www.ti.com/tw/lit/gpn/sn74hc165-q1)
- ST M74HC165:[https://docs.rs-online.com/27f1/0900766b80ede7fe.pdf](https://docs.rs-online.com/27f1/0900766b80ede7fe.pdf)
---
## 4. 软件结构
**读这一节是为了在上层写代码时知道该调谁、mask 里的 1 到底代表什么、出错该看哪里。** 核心原则是:**BSP 只管引脚与位序,任何"这一路是跳闸还是告警""要不要动作"的判断都不在这一层。**
> 本节内容已与 `Drivers/BSP/IOBOARD/` 下的实际代码逐项核对(2026-11-16):接口签名与 `ioboard.h` 一致,时序顺序与 `ioboard.c` 的 `ioboard_di_shift()` 一致,位序组装与 `ioboard_bits.c` 的 `ioboard_di_assemble()` 一致。
### 4.1 分层
| 层 | 位置 | 职责 | 不做的事 |
|---|---|---|---|
| 纯逻辑层 | `Drivers/BSP/IOBOARD/ioboard_bits.c` | 把 8 个读到的比特组装成开入 mask | 不碰任何寄存器,不 include HAL / CMSIS / FreeRTOS,主机侧可直接编译单测 |
| 硬件时序层 | `Drivers/BSP/IOBOARD/ioboard.c` | 引脚读写、装载与移位时序、临界区、开出极性转换 | 不判断业务语义 |
| 业务层 | 保护判据 / 104 遥信 / UI | 去抖、点表映射、动作逻辑 | 不直接碰 GPIO |
**为什么要把位序组装单独拆成一个不依赖硬件的纯函数**:位序错了不报错,只是数据差一位;而"位序错一位"和"线接错一位"在台架上完全同形、无法归因。拆成纯函数后可以在 PC 上用假数据把位序钉死,台架只剩接线问题要查。
### 4.2 接口
| 接口 | 职责 | 参数语义 |
|---|---|---|
| `ioboard_init()` | 初始化:确认静止态、把 4 路开出置为全释放、清影子寄存器 | 无。返回 `BSP_ERR_STATE` 表示静止态确认失败(引脚被别人动过) |
| `ioboard_di_read(uint8_t *out_mask)` | 读一次 8 路开入(完整装载 — 8 拍移位 — 到位序反转) | `out_mask` 输出 bit0 = 通道 A … bit7 = 通道 H。任意上下文可调,内部自动选临界区 |
| `ioboard_di_read_from_isr(uint8_t *out_mask)` | 同上,专供中断上下文 | 语义相同,临界区换成中断版本 |
| `ioboard_do_write(uint8_t mask)` | 写一次 4 路开出 | mask 的 bit0 到 bit3 分别对应 4 路;**1 = 继电器吸合**,与硬件电平高低无关 |
| `ioboard_do_get(uint8_t *out_mask)` | 取软件影子寄存器里的当前开出 mask | 读的是驱动认为的状态,不读引脚 |
| `ioboard_do_read_level(uint8_t *out_level)` | 直接读 4 根开出引脚的**实际电平** | 用于极性核对:与 `ioboard_do_get()` 对不上,说明有人在驱动之外动过这 4 根脚 |
**mask 里 1 的含义**:开入 mask 的 1 = 该路**有信号**(触点闭合 / 压板投入);开出 mask 的 1 = 该路**继电器吸合**。两个方向的 1 都代表"该通道处于激活态",与硬件电平的高低**无关**——电平极性的换算在驱动内部完成。
### 4.3 极性约定
软件约定只有一个:**mask 的 1 = 继电器吸合**。硬件上是高电平吸合还是低电平吸合,由驱动内部的一层转换决定,上层完全看不到。
- 转换点只有一处:`Drivers/BSP/IOBOARD/ioboard.h` 的宏 `IOBOARD_DO_LEVEL_ACTIVE`;
- **要改极性就只改这一个宏**,千万不要在上层逐路取反;
- 当前取值按"高电平吸合"配置,**尚未在台架上实测核对**——上板验证时若发现"写 1 反而不吸合",先改这个宏,再怀疑硬件。
### 4.4 上电默认态
`ioboard_init()` 会把 4 路开出置为**全释放**并清影子寄存器。这是安全设计:上电默认所有出口不动作。
但要注意**从上电到 `ioboard_init()` 执行之间**有一段窗口,这期间引脚电平由 CubeMX 生成的初值决定(见「硬件接线」的引脚表),驱动管不到。因此上板验证时**务必观察上电瞬间有没有误吸合**,这是「开出:逐路验证继电器动作」一节的第一条。
### 4.5 时序实现要点
驱动里所有延时都是用**忙等计数**实现的(按 168 MHz 主频换算的循环次数),不是硬件定时器。这样做换来的是时序最短、最可预期,代价是这几微秒内 CPU 被独占。
因此:**整个装载加 8 拍移位全程在临界区里完成**,不允许被中断打断——一旦被打断,中断里若有耗时操作,移位时序被拉长,虽然 74HC165 本身对时钟频率下限没有苛刻要求,但会拖长读一次开入的总时间。驱动声明的上界是 `IOBOARD_DI_READ_MAX_US`(26 µs),业务层若对周期有要求,按这个上界估算预算。
### 4.6 去抖
**当前驱动不含去抖**,它只负责把"此刻 8 路是什么状态"如实读出来。机械触点在闭合瞬间会抖动数毫秒、产生多次跳变,若直接把每次读数都当作变位上送,会刷出一串假事件。
去抖与变位检测属于**业务层**职责,与本板卡驱动无关;接入位置与现状见本文「已知限制与后续」的「尚未接入的部分」。
---
## 5. 上板验证步骤
**读这一节是为了在第一次上电时按顺序把"线通不通 → 电平对不对 → 位序对不对 → 时序稳不稳"四件事逐级排除,而不是一上来就怀疑代码。** 整节所有判据均为**待台架验证**——本机无硬件,以下步骤的描述基于代码与数据手册推导,尚无一手的台架实测记录。
### 5.1 开入:逐路验证通道对应关系
**目的**:确认"第几个 bit 对应板上第几个端子"。
操作步骤(一次只动一路,其余保持原状):
1. 让设备上电运行,打开调试口日志(日志走 UART5,115200)。
2. 读一次开入,记下 mask 作为基线。若所有通道都悬空,基线可能是全 0 也可能是全 1——**先记下来,不预设**。
3. 把**第 1 路**的开入端子短接到 GND(或按该板的输入极性接到 24 V,取决于端子设计),稳定保持 2 秒以上。
4. 再读一次 mask。**判据**:只有 1 个 bit 发生变化,其余 7 位与基线相同。
5. 记录这个变化落在哪一位,然后恢复端子、换下一路重复。
**通道与 bit 的约定**:通道 A 必须落在 **bit0**(最低位),通道 H 落在 bit7。做这一步之前,先回「时序原理」一节把三条基本判据走一遍——**只有 A 动作 → 0x01**、**只有 H 动作 → 0x80**、**A 与 H 同时动作 → 0x81**。这三条通了再逐路扫其余 6 路。
**这一步的预期耗时**:8 路各做一遍,路与路之间要等机械触点稳定,实际不会很快;不要因为前两路顺就省略后面几路的核对——中间某两位"合流到同一位"这类错误,只测端点抓不到。
**状态**:待台架验证。
### 5.2 开出:逐路验证继电器动作
**目的**:确认"置哪一位,动的是哪一路继电器",以及上电时确实全释放。
1. **上电瞬间**:听/看 4 路继电器,**都不应有吸合动作**。判据:全部处于释放态。
2. 用万用表(通断档或电阻档)接在某一路继电器的**触点两端**,先确认释放态读数是常开(断路)或常闭(导通),记下来。
3. 只置 **bit0**(mask = 0x01),观察:该路继电器**有吸合声**、触点状态翻转;**其余 3 路不动**。
4. 逐位重复:mask = 0x02 / 0x04 / 0x08,确认每一路都只对应一个 bit。
5. 写 **全 1**(mask = 0x0F),确认 4 路**同时**吸合——这一步是「4 路开出分属两个端口」那条限制的现场确认。
6. 最后写 mask = 0x00,确认 4 路全部回到释放态。
**注意极性**:软件 mask 的 1 = 吸合,与硬件电平的高低无关,由驱动内部转换。若发现"写 1 反而不吸合",改 `Drivers/BSP/IOBOARD/ioboard.h` 的 `IOBOARD_DO_LEVEL_ACTIVE` 这一个宏即可,**不要在上层逐路取反**。判断当前极性是否正确的快捷办法:调 `ioboard_do_read_level()` 读实际引脚电平,再和 `ioboard_do_get()` 的影子寄存器对照——两者对不上说明有人在驱动之外动过这 4 根脚。
**状态**:待台架验证。
### 5.3 时序:有示波器时看什么
**目的**:在读数不对但又查不出接线问题时,用波形判断是不是时序错位。
探头接三根线:**PC2(`SH/LD`)、PC3(CLK)、PE3(数据)**,触发源设在 PC2 的下降沿。期望看到的波形顺序:
| 阶段 | `SH/LD`(PC2) | `CLK`(PC3) | PE3(数据) |
|---|---|---|---|
| 静止 | 高 | 低 | 不定(上一轮的残留) |
| 装载 | **低脉冲**(宽度微秒级量级,远大于手册要求的十几纳秒) | **保持低** | 装载完成时立即变成通道 H 的电平 |
| 移位 | 高 | **8 个脉冲**,周期为微秒级(约百 kHz 量级) | 每个脉冲上升沿之后更新 |
| 结束 | 高 | 低 | 不定 |
**关键判据**:装载期间(`SH/LD` 为低的那段时间)**CLK 必须一直是低**。若看到装载脉冲期间 CLK 还有跳变,说明"先拉低 CLK"这一步没做到,读出的数据一定错位。
**状态**:待台架验证。表中"微秒级""约百 kHz"为量级描述,精确值以驱动里的延时宏为准:时钟高/低各 `IOBOARD_HC165_CLK_PHASE_US`(1 µs),所以一位周期约 2 µs 再叠加采样等待,整个 8 位读一遍约 26 µs(`IOBOARD_DI_READ_MAX_US`)。
### 5.4 无示波器时的替代判据
没有示波器时,用**图案循环法**判断时序与位序:
1. 准备三种输入图案:**全低**、**全高**、**单路 A 动作**。
2. 在全低 → 全高 → 单路 A → 全低之间循环至少 5 轮,每轮之间稳定 2 秒。
3. **判据**:
- 三种图案的读数分别是 `0x00`、`0xFF`、`0x01`(以 A 在 bit0 为前提);
- 同类图案在每一轮的读数**完全相同**(说明没有随机错位);
- 切换过程中**不会出现多个 bit 同时跳变**。
若出现"某一路跳变时相邻路也跟着跳",或"同一图案两次读数不同",优先怀疑:装载期间 CLK 不是低(时序)、或 PE3 接触不良(接线)。
**这个方法的边界要记住**:全 0 与全 1 对位序**完全不敏感**——反序、移位、串位在这两个图案下读数都一样。所以图案循环法只能证明"线通、读得到、不随机",**不能证明位序对**。要证明位序,必须回到「时序原理」一节的单比特与混合算例,以及「开入:逐路验证通道对应关系」一节的逐路核对。
**状态**:待台架验证。
---
## 6. 已知限制与后续
**读这一节是为了知道哪些是"现在就这样、别白费力气去查"的限制,以及将来要补的时候该从哪里下手。**
### 6.1 第二块 74HC165 读不到(硬件限制)
**现象**:设计 16 路开入,实际只有 8 路可用。
**根因**:第二块芯片的 QH 输出线在板上没有连到 MCU,MCU 侧只有 PE3 一路串行数据输入。两块芯片共用 CLK(PC3) 与 `SH/LD`(PC2),时钟会把两块同时往前推,但只有第一块的结果能被读到。
**两条修法**:
| 修法 | 做法 | 代价 |
|---|---|---|
| 飞线(验证阶段可用) | 把第二块的 QH 飞线接到 MCU 的一个空闲 GPIO,并把级联顺序改为"第一块 QH → 第二块串行输入、第二块 QH → MCU"——**顺序要对**,否则两块数据依然串不起来 | 一根线 + 软件改动;不美观、不适合交付 |
| 改板(正式修法) | 在下一版硬件上补这根走线,按级联正确顺序接 | 需改版 |
**改好后的软件适配点**(这里只定位,不写实现):位序组装在 `Drivers/BSP/IOBOARD/ioboard_bits.c` 的 `ioboard_di_assemble()`——级联后一次要读 16 个比特、把 `IOBOARD_DI_COUNT` 改成 16 并按「最后一块的数据在低 8 位、第一块在高 8 位」重新映射;时序层在 `Drivers/BSP/IOBOARD/ioboard.c` 的 `ioboard_di_shift()` 里把循环次数跟着 `IOBOARD_DI_COUNT` 走,并把新增的数据 GPIO 纳入同一个临界区与同一次静止态确认。
### 6.2 4 路开出分属两个端口(同步性限制)
4 路开出里 PC14 在 GPIOC、PF0/PF1/PF6 在 GPIOF,所以要写两次 `BSRR`(每个端口各一次)。两次写之间相隔几条指令(约 10 ns 量级),业务层面不可观测;但如果将来对 4 路的**严格同时性**有要求,得在硬件上把这 4 路挪到同一个端口,软件侧无法再压缩。
### 6.3 继电器动作语义属业务层,本文档不定义
4 路开出分别对应"跳闸""告警""闭锁"还是别的含义,**不在本文档定义**。这是保护逻辑层的职责,去向:
- 保护判据与动作逻辑 → `docs/算法/采集与算法层设计说明.md`、`docs/算法/继电保护功能复现规划.md`
- 104 规约的遥信/遥控点表 → `docs/子系统设计/IEC104上行设计说明.md`
在业务层把这些定义清楚之前,**4 路开出只能用于台架验证,不得用于真实跳闸**。
### 6.4 保护判据未标定闭锁(承重限制)
保护判据目前处于**未标定闭锁**态:`adc_cal_prot_blocked()` 要求 UA/UN/IA 三路有效值齐备,而 UN 通道在本台架永久无数据(台架无接线),因此保护永久闭锁、不允许伪造有效值。详见仓库根 `AGENTS.md`「项目概况」。
这意味着:**即使开出通道完全可用,也没有任何保护逻辑会去驱动它**——这是设计上的安全状态,不是缺陷。解除条件见 [`硬件规格与能力边界.md`](../架构设计/硬件规格与能力边界.md) 的 H3 行。
### 6.5 尚未接入的部分
| 未接入项 | 现状 | 去向 |
|---|---|---|
| 开入去抖 | 未实现 | 业务层接线任务,落点在 `App/task/default_task.c` |
| 开入 → 104 遥信点表 | 未接入 | `docs/子系统设计/IEC104上行设计说明.md` |
| UI 遥信配置页(遥信类型/防抖/双点遥信) | 三叶未绑,原因是**缺数据源**而非缺硬件 | `docs/UI设计/页面补齐规划.md` |
---
## 附录:术语表
| 术语 | 含义 |
|---|---|
| 开入(DI) | 数字输入:读外部触点的通断状态 |
| 开出(DO) | 数字输出:驱动继电器等执行元件 |
| 74HC165 | 8 位并行输入、串行输出的移位寄存器芯片,用 3 根线读出 8 个开关量 |
| `SH/LD` | 74HC165 的移位/装载控制脚:低 = 装载,高 = 移位 |
| QH | 74HC165 的串行输出脚,一次输出一位 |
| LSB | 最低有效位(Least Significant Bit),本文指 mask 的 bit0 |
| 掩码 / mask | 一个整数的各位分别代表一路通道的状态 |
| 光耦 | 把 MCU 侧弱电与继电器侧强电隔开的光电隔离器件 |
| 遥信 | 电力系统术语,指把现场开关状态(位置、告警等)上送给主站 |
| SOE | 事件顺序记录(Sequence of Events),带毫秒级时间戳的变位记录 |
| BSP | 板级支持包,本文指只做引脚与时序、不含业务判断的驱动层 |
| 级联 | 多片移位寄存器首尾相接,扩展成更多位 |
| 去抖 | 消除机械触点抖动造成的重复变位 |
| 双射 | 一一对应:8 个输入位置恰好对应 8 个互不相同的输出位,既不重复也不遗漏 |
| BSRR | STM32 的"位设置/复位寄存器",一次写入即可原子地把若干位置 1 或清 0 |
| 临界区 | 一段禁止中断打断的代码区间,用来保证时序或数据不被并发改写 |
@@ -39,7 +39,7 @@
| 采样硬件 | TPAFE5160(16 位、8 通道**同步**、±5 V 双极性、并行 `GPIOG[15:0]`)+ STM32 内部 ADC1(12 位、9 通道**顺序**扫描、0~3.3 V 单极性) |
| 采样软件 | `Drivers/BSP/TPAFE5160/tpafe5160.h` 驱动就绪(原子快照 API);`App/task/adc_task.c` **已实现真实消费者(ADC 采集链路,2026-10-10)**——`tpafe5160_snapshot()` 取数 + 帧统计;**采样节拍由 TIM3 更新事件(1 kHz)硬件触发**(2026-10-10;同一事件经 TRGO 触发 ADC1 + DMA);STM32 侧 **`App/algo/adc_input.c` 已实现语义映射 + ADC1 DMA 乒乓帧消费(「STM32 ADC1 启动与扫描」,v2.0)**,`HAL_ADC_Start_DMA` 已出现 |
| 保护算法层 | **全周傅氏相量层已实现并台架闭环**(`App/algo/sample_ring.c` + `phasor.c`:全周傅氏 5 实例、双区交换、每 1 ms 刷新,2026-10-11 `/serial-boot-test`);**保护判据元件框架 + 过流/过负荷/过压/欠压/零序过压 + 定值模型软件侧完成**(`prot_elm.c` + `prot_set.c`,2026-10-11,57 项主机单测);**出口 / SOE 记录仍缺失**(P4) |
| 已知硬件缺陷 | `docs/任务规划/登记簿.md` §1:8 路电气量分属两片转换器 → V0.1 上禁止跨转换器做相位/功率/矢量运算 |
| 已知硬件缺陷 | `docs/任务规划/硬件改版登记.md` §1:8 路电气量分属两片转换器 → V0.1 上禁止跨转换器做相位/功率/矢量运算 |
### 1.3 复现范围界定
@@ -138,7 +138,7 @@
| # | 约束 | 出处 | 后果 |
| --- | --- | --- | --- |
| 双转换器无共同采样触发 | 8 路电气量分属 TPAFE5160 与 STM32 ADC1 **两片**,两片**无共同采样触发** | `ADC通道映射说明.md` §1、`docs/任务规划/登记簿.md` §1 | 跨转换器的相位 / 矢量 / 功率 / 功率因数 / 负序运算**不成立** |
| 双转换器无共同采样触发 | 8 路电气量分属 TPAFE5160 与 STM32 ADC1 **两片**,两片**无共同采样触发** | `ADC通道映射说明.md` §1、`docs/任务规划/硬件改版登记.md` §1 | 跨转换器的相位 / 矢量 / 功率 / 功率因数 / 负序运算**不成立** |
| R5 | STM32 侧**无中点偏置**(1k 串联 + 1k 到 `*_GND`),0~3.3 V 单极性 | `ADC通道映射说明.md` §1、§7 | STM32 侧交流量负半周**削顶** → 该侧**算不出有效值 / 相量** |
**(2)净效果:V0.1 只有 TPAFE 三路"测量有效"**
@@ -426,7 +426,7 @@
| --- | --- | --- | --- |
| AD 器件 | 专用同步采样 AD | TPAFE5160(16 位、8 通道同步、±5 V)+ STM32 ADC1(12 位、顺序、0~3.3 V) | 统一到"工程量"层,屏蔽码值差异 |
| 通道数 | 8 实通道(4U+4I,自产零序) | 8 路电气量(4U+4I)+ 温度 | 语义映射见 `docs/硬件平台/ADC通道映射说明.md` |
| 同一时刻性 | 单芯片同步 | **跨转换器无共同触发**(`docs/任务规划/登记簿.md` §1) | V0.1 只做逐通道独立监视 |
| 同一时刻性 | 单芯片同步 | **跨转换器无共同触发**(`docs/任务规划/硬件改版登记.md` §1) | V0.1 只做逐通道独立监视 |
| 量程/精度 | 一致 | TPAFE LSB ≈ 152.6 µV vs STM32 LSB ≈ 806 µV | 同族量不可统一算法处理 |
### 6.2 双转换器无共同采样触发:影响与降级口径
+2
View File
@@ -137,6 +137,8 @@ SIM_EXEMPT = [
("Drivers/BSP/NET/net_pending.c", "MCU 挂起 recv 模型(依赖 ch395f_* SPI 读出与 FreeRTOS 通知),模拟器另有 net_socket_sim.c 按外部语义模拟"),
("Drivers/BSP/NET/net_udp.c", "MCU UDP 数据面执行器与挂起 recv 槽(2026-11-03 UDP 队列化改造;依赖 ch395f_* SPI 读写、net_send_locked 与 FreeRTOS 通知),模拟器另有 net_socket_sim.c 按外部语义模拟"),
("Drivers/BSP/RS485/rs485.c", "MCU RS-485 驱动"),
("Drivers/BSP/IOBOARD/ioboard.c", "MCU 开入开出驱动(74HC165 GPIO 时序 + 光耦继电器 BSRR 写),依赖 main.h 引脚宏与 FreeRTOS 临界区,模拟器无对应;纯逻辑(位序组装)在 ioboard_bits.c"),
("Drivers/BSP/IOBOARD/ioboard_bits.c", "开入开出纯逻辑层(不依赖 HAL/RTOS),模拟器无消费路径;位序由主机侧单测直接编译覆盖于 test/host/ioboard"),
("Drivers/BSP/SD2506/sd2506.c", "MCU RTC 驱动"),
("Drivers/BSP/ScreenLink/sb_proto.c", "屏板链路协议层纯逻辑(帧 A 解析 / 帧 B 组帧 / CRC-16),消费者 = MCU 侧 USART1 收发起发(批 1/2),模拟器无消费路径;主机侧纯逻辑单测覆盖于 test/host/sb_proto"),
("Drivers/BSP/ScreenLink/sb_link.c", "屏板链路传输层(USART1 IDLE 中断收 + ORE 清除 + 统计),依赖 HAL 句柄与中断上下文,MCU 专属;主机侧单测以桩覆盖于 test/host/sb_link"),
+173 -131
View File
@@ -1,12 +1,12 @@
{
"files": {
"App/algo/adc_cal.c": {
"func_rate": 0.9412,
"funcs_covered": 16,
"funcs_valid": 17,
"line_rate": 0.9463,
"lines_covered": 141,
"lines_valid": 149
"func_rate": 0.9565,
"funcs_covered": 22,
"funcs_valid": 23,
"line_rate": 0.9637,
"lines_covered": 186,
"lines_valid": 193
},
"App/algo/adc_health.c": {
"func_rate": 1.0,
@@ -65,12 +65,12 @@
"lines_valid": 179
},
"App/algo/run_par.c": {
"func_rate": 0.9286,
"funcs_covered": 13,
"funcs_valid": 14,
"line_rate": 0.8837,
"lines_covered": 114,
"lines_valid": 129
"func_rate": 0.9333,
"funcs_covered": 14,
"funcs_valid": 15,
"line_rate": 0.8919,
"lines_covered": 132,
"lines_valid": 148
},
"App/algo/sample_ring.c": {
"func_rate": 1.0,
@@ -93,24 +93,24 @@
"funcs_covered": 15,
"funcs_valid": 15,
"line_rate": 0.9956,
"lines_covered": 225,
"lines_valid": 226
"lines_covered": 227,
"lines_valid": 228
},
"App/algo/wave_store.c": {
"func_rate": 1.0,
"funcs_covered": 29,
"funcs_valid": 29,
"line_rate": 0.9612,
"lines_covered": 446,
"lines_valid": 464
"funcs_covered": 30,
"funcs_valid": 30,
"line_rate": 0.9551,
"lines_covered": 468,
"lines_valid": 490
},
"App/cfg/cfg_file.c": {
"func_rate": 0.963,
"funcs_covered": 26,
"funcs_valid": 27,
"line_rate": 0.8882,
"lines_covered": 612,
"lines_valid": 689
"func_rate": 0.9643,
"funcs_covered": 27,
"funcs_valid": 28,
"line_rate": 0.878,
"lines_covered": 662,
"lines_valid": 754
},
"App/cfg/cfg_file_store_mcu.c": {
"func_rate": 1.0,
@@ -240,6 +240,14 @@
"lines_covered": 78,
"lines_valid": 81
},
"App/util/ioboard_di.c": {
"func_rate": 1.0,
"funcs_covered": 8,
"funcs_valid": 8,
"line_rate": 0.9358,
"lines_covered": 102,
"lines_valid": 109
},
"App/util/sha256.c": {
"func_rate": 1.0,
"funcs_covered": 7,
@@ -273,12 +281,20 @@
"lines_valid": 73
},
"Drivers/BSP/GD5F2GQ5UE/nand_ftl.c": {
"func_rate": 0.6364,
"funcs_covered": 14,
"funcs_valid": 22,
"line_rate": 0.4862,
"lines_covered": 123,
"lines_valid": 253
"func_rate": 0.8,
"funcs_covered": 20,
"funcs_valid": 25,
"line_rate": 0.6262,
"lines_covered": 191,
"lines_valid": 305
},
"Drivers/BSP/IOBOARD/ioboard_bits.c": {
"func_rate": 1.0,
"funcs_covered": 1,
"funcs_valid": 1,
"line_rate": 1.0,
"lines_covered": 8,
"lines_valid": 8
},
"Drivers/BSP/NET/lftpd/lftpd.c": {
"func_rate": 0.8077,
@@ -301,8 +317,8 @@
"funcs_covered": 9,
"funcs_valid": 9,
"line_rate": 1.0,
"lines_covered": 127,
"lines_valid": 127
"lines_covered": 128,
"lines_valid": 128
},
"Drivers/BSP/NET/lftpd/lftpd_io.c": {
"func_rate": 0.3846,
@@ -402,19 +418,19 @@
},
"Drivers/BSP/ScreenLink/sb_proto.c": {
"func_rate": 1.0,
"funcs_covered": 6,
"funcs_valid": 6,
"funcs_covered": 5,
"funcs_valid": 5,
"line_rate": 1.0,
"lines_covered": 75,
"lines_valid": 75
"lines_covered": 55,
"lines_valid": 55
},
"Drivers/BSP/UI/ui_data.c": {
"func_rate": 0.8235,
"func_rate": 0.8077,
"funcs_covered": 42,
"funcs_valid": 51,
"line_rate": 0.8692,
"funcs_valid": 52,
"line_rate": 0.8611,
"lines_covered": 372,
"lines_valid": 428
"lines_valid": 432
},
"Drivers/BSP/UI/ui_net_sink.c": {
"func_rate": 0.7692,
@@ -437,10 +453,10 @@
"modules": {
"adc_cal": {
"files": {
"App/algo/adc_cal.c": 149,
"App/cfg/cfg_file.c": 689
"App/algo/adc_cal.c": 193,
"App/cfg/cfg_file.c": 754
},
"lines_total": 838,
"lines_total": 947,
"ok": true
},
"adc_health": {
@@ -466,9 +482,9 @@
},
"cfg_file": {
"files": {
"App/cfg/cfg_file.c": 689
"App/cfg/cfg_file.c": 754
},
"lines_total": 689,
"lines_total": 754,
"ok": true
},
"cfg_file_store_mcu": {
@@ -511,21 +527,21 @@
},
"iec104": {
"files": {
"App/algo/adc_cal.c": 149,
"App/algo/adc_cal.c": 193,
"App/algo/freq.c": 130,
"App/algo/meas.c": 64,
"App/algo/phasor.c": 55,
"App/algo/prot_elm.c": 122,
"App/algo/prot_set.c": 179,
"App/algo/run_par.c": 129,
"App/algo/run_par.c": 148,
"App/algo/sample_ring.c": 41,
"App/cfg/cfg_file.c": 689,
"App/cfg/cfg_file.c": 754,
"App/protocol/iec104/iec104_asdu.c": 103,
"App/protocol/iec104/iec104_comm.c": 50,
"App/protocol/iec104/iec104_link.c": 405,
"App/protocol/iec104/iec104_pts.c": 255
},
"lines_total": 2371,
"lines_total": 2499,
"ok": true
},
"iec104_serv": {
@@ -535,6 +551,14 @@
"lines_total": 173,
"ok": true
},
"ioboard": {
"files": {
"App/util/ioboard_di.c": 109,
"Drivers/BSP/IOBOARD/ioboard_bits.c": 8
},
"lines_total": 117,
"ok": true
},
"lftpd": {
"files": {
"Drivers/BSP/NET/lftpd/lftpd.c": 473,
@@ -545,9 +569,9 @@
},
"lftpd_inet": {
"files": {
"Drivers/BSP/NET/lftpd/lftpd_inet.c": 127
"Drivers/BSP/NET/lftpd/lftpd_inet.c": 128
},
"lines_total": 127,
"lines_total": 128,
"ok": true
},
"lftpd_io": {
@@ -569,9 +593,9 @@
},
"nand_port": {
"files": {
"Drivers/BSP/GD5F2GQ5UE/nand_ftl.c": 253
"Drivers/BSP/GD5F2GQ5UE/nand_ftl.c": 305
},
"lines_total": 253,
"lines_total": 305,
"ok": true
},
"net_cfg": {
@@ -628,14 +652,14 @@
},
"prot_dim": {
"files": {
"App/algo/adc_cal.c": 149,
"App/algo/adc_cal.c": 193,
"App/algo/freq.c": 130,
"App/algo/phasor.c": 55,
"App/algo/prot_elm.c": 122,
"App/algo/prot_set.c": 179,
"App/algo/sample_ring.c": 41
},
"lines_total": 676,
"lines_total": 720,
"ok": true
},
"prot_elm": {
@@ -666,11 +690,11 @@
},
"run_par": {
"files": {
"App/algo/adc_cal.c": 149,
"App/algo/run_par.c": 129,
"App/cfg/cfg_file.c": 689
"App/algo/adc_cal.c": 193,
"App/algo/run_par.c": 148,
"App/cfg/cfg_file.c": 754
},
"lines_total": 967,
"lines_total": 1095,
"ok": true
},
"sb_led_map": {
@@ -683,16 +707,16 @@
"sb_link": {
"files": {
"Drivers/BSP/ScreenLink/sb_link.c": 243,
"Drivers/BSP/ScreenLink/sb_proto.c": 75
"Drivers/BSP/ScreenLink/sb_proto.c": 55
},
"lines_total": 318,
"lines_total": 298,
"ok": true
},
"sb_proto": {
"files": {
"Drivers/BSP/ScreenLink/sb_proto.c": 75
"Drivers/BSP/ScreenLink/sb_proto.c": 55
},
"lines_total": 75,
"lines_total": 55,
"ok": true
},
"sha256": {
@@ -756,10 +780,10 @@
},
"ui_data": {
"files": {
"Drivers/BSP/UI/ui_data.c": 428,
"Drivers/BSP/UI/ui_data.c": 432,
"Drivers/BSP/UI/ui_w_soe.c": 62
},
"lines_total": 490,
"lines_total": 494,
"ok": true
},
"ui_sink": {
@@ -792,25 +816,25 @@
},
"wave_ring": {
"files": {
"App/algo/wave_ring.c": 226,
"App/algo/wave_store.c": 464
"App/algo/wave_ring.c": 228,
"App/algo/wave_store.c": 490
},
"lines_total": 690,
"lines_total": 718,
"ok": true
},
"wave_store": {
"files": {
"App/algo/wave_store.c": 464
"App/algo/wave_store.c": 490
},
"lines_total": 464,
"lines_total": 490,
"ok": true
},
"wave_trig": {
"files": {
"App/algo/wave_ring.c": 226,
"App/algo/wave_store.c": 464
"App/algo/wave_ring.c": 228,
"App/algo/wave_store.c": 490
},
"lines_total": 690,
"lines_total": 718,
"ok": true
}
},
@@ -847,11 +871,13 @@
"App/sync/time_sync.c",
"App/task/iec104_serv.c",
"App/util/boot_stats.c",
"App/util/ioboard_di.c",
"App/util/sha256.c",
"App/util/sys_clock.c",
"App/util/task_prof.c",
"App/util/task_watchdog.c",
"Drivers/BSP/GD5F2GQ5UE/nand_ftl.c",
"Drivers/BSP/IOBOARD/ioboard_bits.c",
"Drivers/BSP/NET/lftpd/lftpd.c",
"Drivers/BSP/NET/lftpd/lftpd_auth.c",
"Drivers/BSP/NET/lftpd/lftpd_inet.c",
@@ -874,16 +900,16 @@
],
"totals": {
"files_generated_excluded": 5,
"files_tested": 54,
"files_untested": 177,
"func_rate": 0.929,
"funcs_covered": 641,
"funcs_valid": 690,
"line_rate": 0.901,
"lines_covered": 8552,
"lines_valid": 9492,
"modules_ok": 48,
"modules_total": 48
"files_tested": 56,
"files_untested": 181,
"func_rate": 0.9339,
"funcs_covered": 664,
"funcs_valid": 711,
"line_rate": 0.9027,
"lines_covered": 8848,
"lines_valid": 9802,
"modules_ok": 49,
"modules_total": 49
},
"untested_sources": [
{
@@ -891,23 +917,23 @@
"path": "Drivers/BSP/CH395F/ch395f.c"
},
{
"code_lines": 689,
"code_lines": 712,
"path": "Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c"
},
{
"code_lines": 570,
"code_lines": 597,
"path": "App/task/ui_task.c"
},
{
"code_lines": 466,
"code_lines": 539,
"path": "App/task/default_task.c"
},
{
"code_lines": 420,
"code_lines": 423,
"path": "App/app/ui_data_feed.c"
},
{
"code_lines": 369,
"code_lines": 375,
"path": "App/task/adc_task.c"
},
{
@@ -919,7 +945,7 @@
"path": "Drivers/BSP/UI/ui_w_setview.c"
},
{
"code_lines": 303,
"code_lines": 334,
"path": "Drivers/BSP/UI/ui_content_page.c"
},
{
@@ -930,20 +956,28 @@
"code_lines": 264,
"path": "Drivers/BSP/SD2506/sd2506.c"
},
{
"code_lines": 262,
"path": "Drivers/BSP/IOBOARD/ioboard.c"
},
{
"code_lines": 261,
"path": "Drivers/BSP/UI/ui_page_sntp.c"
},
{
"code_lines": 251,
"code_lines": 255,
"path": "Drivers/BSP/UI/ui_standby.c"
},
{
"code_lines": 253,
"path": "Drivers/BSP/UI/ui_page_wave_play.c"
},
{
"code_lines": 230,
"code_lines": 232,
"path": "Drivers/BSP/UI/ui_data.h"
},
{
"code_lines": 218,
"code_lines": 219,
"path": "Drivers/BSP/UI/ui_page_clock.c"
},
{
@@ -958,10 +992,6 @@
"code_lines": 205,
"path": "Drivers/BSP/UI/ui_page_net_cfg.c"
},
{
"code_lines": 204,
"path": "Drivers/BSP/UI/ui_standby.c"
},
{
"code_lines": 200,
"path": "Drivers/BSP/UI/ui_w_ytview.c"
@@ -971,11 +1001,11 @@
"path": "Drivers/BSP/TPAFE5160/tpafe5160.c"
},
{
"code_lines": 152,
"code_lines": 154,
"path": "Drivers/BSP/UI/ui_page_runreport.c"
},
{
"code_lines": 150,
"code_lines": 152,
"path": "App/algo/wave_store.h"
},
{
@@ -983,11 +1013,11 @@
"path": "Drivers/BSP/UI/ui_page_password.c"
},
{
"code_lines": 146,
"code_lines": 148,
"path": "Drivers/BSP/UI/ui_page_device_info.c"
},
{
"code_lines": 142,
"code_lines": 143,
"path": "App/app/app_main.c"
},
{
@@ -1015,7 +1045,7 @@
"path": "Drivers/BSP/UI/ui_page_action.c"
},
{
"code_lines": 112,
"code_lines": 114,
"path": "Drivers/BSP/UI/ui_page_ac.c"
},
{
@@ -1039,13 +1069,17 @@
"path": "Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.h"
},
{
"code_lines": 86,
"code_lines": 87,
"path": "Drivers/BSP/UI/ui_page_yx.c"
},
{
"code_lines": 84,
"path": "Drivers/BSP/RS485/rs485.c"
},
{
"code_lines": 78,
"path": "App/algo/wave_ring.h"
},
{
"code_lines": 77,
"path": "App/algo/prot_set.h"
@@ -1055,11 +1089,7 @@
"path": "Drivers/BSP/dbg_log.h"
},
{
"code_lines": 75,
"path": "App/algo/wave_ring.h"
},
{
"code_lines": 69,
"code_lines": 70,
"path": "Drivers/BSP/UI/ui_page_dc.c"
},
{
@@ -1102,6 +1132,10 @@
"code_lines": 46,
"path": "App/log/soe_rec.h"
},
{
"code_lines": 46,
"path": "Drivers/BSP/UI/ui_content_page.h"
},
{
"code_lines": 46,
"path": "Drivers/BSP/UI/ui_page_reset.c"
@@ -1114,10 +1148,6 @@
"code_lines": 44,
"path": "App/algo/adc_input.h"
},
{
"code_lines": 43,
"path": "Drivers/BSP/UI/ui_content_page.h"
},
{
"code_lines": 42,
"path": "App/cfg/cfg_file.h"
@@ -1151,12 +1181,16 @@
"path": "Drivers/BSP/UI/ui_page_deadband.c"
},
{
"code_lines": 38,
"path": "Drivers/BSP/UI/ui_page_wave_manual.c"
"code_lines": 39,
"path": "App/algo/adc_cal.h"
},
{
"code_lines": 36,
"path": "Drivers/BSP/ScreenLink/sb_proto.h"
"code_lines": 38,
"path": "App/util/ioboard_di.h"
},
{
"code_lines": 38,
"path": "Drivers/BSP/UI/ui_page_wave_manual.c"
},
{
"code_lines": 36,
@@ -1186,10 +1220,6 @@
"code_lines": 33,
"path": "Drivers/BSP/UI/ui_page_action.h"
},
{
"code_lines": 32,
"path": "App/algo/adc_cal.h"
},
{
"code_lines": 32,
"path": "App/util/boot_stats.h"
@@ -1202,6 +1232,14 @@
"code_lines": 31,
"path": "App/protocol/iec104/iec104_pts.h"
},
{
"code_lines": 31,
"path": "Drivers/BSP/IOBOARD/ioboard.h"
},
{
"code_lines": 31,
"path": "Drivers/BSP/ScreenLink/sb_proto.h"
},
{
"code_lines": 31,
"path": "Drivers/BSP/UI/ui_deco.c"
@@ -1230,6 +1268,14 @@
"code_lines": 27,
"path": "App/task/task_handles.h"
},
{
"code_lines": 27,
"path": "App/util/task_prof.h"
},
{
"code_lines": 27,
"path": "Drivers/BSP/GD5F2GQ5UE/nand_ftl.h"
},
{
"code_lines": 27,
"path": "Drivers/BSP/NET/net_pending.h"
@@ -1242,10 +1288,6 @@
"code_lines": 26,
"path": "App/algo/sb_led_map.h"
},
{
"code_lines": 26,
"path": "App/util/task_prof.h"
},
{
"code_lines": 26,
"path": "Drivers/BSP/UI/ui_port.h"
@@ -1264,11 +1306,11 @@
},
{
"code_lines": 23,
"path": "App/protocol/iec104/iec104_comm.h"
"path": "App/algo/run_par.h"
},
{
"code_lines": 22,
"path": "App/algo/run_par.h"
"code_lines": 23,
"path": "App/protocol/iec104/iec104_comm.h"
},
{
"code_lines": 22,
@@ -1366,6 +1408,10 @@
"code_lines": 15,
"path": "Drivers/BSP/UI/ui_standby.h"
},
{
"code_lines": 14,
"path": "Drivers/BSP/IOBOARD/ioboard_bits.h"
},
{
"code_lines": 14,
"path": "Drivers/BSP/UI/ui_style.c"
@@ -1398,10 +1444,6 @@
"code_lines": 12,
"path": "App/task/iec104_serv.h"
},
{
"code_lines": 12,
"path": "Drivers/BSP/GD5F2GQ5UE/nand_ftl.h"
},
{
"code_lines": 12,
"path": "Drivers/BSP/NET/lftpd/private/lftpd_io.h"
+9 -1
View File
@@ -60,6 +60,7 @@ include_directories(
${PROJECT_ROOT}/App/protocol/iec104 # iec104_comm.h([comm] 段契约头,供 IEC104_SOURCES 编译;道G task-8)
${PROJECT_ROOT}/App/log # sys_log.h(运行/自检记录引擎,双端共享核心)
${PROJECT_ROOT}/App/algo # prot_set.h(定值模型纯算法,双端共享核心;见 ALGO_SOURCES)
${PROJECT_ROOT}/App/util # ioboard_di.h(开入去抖与快照,双端共享核心)
${PROJECT_ROOT}/Drivers/BSP # dbg_log.h(使用 simulator 的 dbg_cfg.h 配置)
${SDL2_DIR}/include # SDL2 头文件
)
@@ -165,6 +166,13 @@ set(IEC104_SOURCES
${PROJECT_ROOT}/App/protocol/iec104/iec104_comm.c
)
# 开入去抖与快照(App/util/ioboard_di.c):零平台依赖纯逻辑(只 include <stdint.h>),
# 主机侧单测覆盖于 test/host/ioboard。按 check_registration 的双端注册门禁,新 .c 必须
# 两端都编译(不像 MCU 硬件驱动那样进 SIM_EXEMPT),所以在这里显式列出。
set(IOBOARD_SOURCES
${PROJECT_ROOT}/App/util/ioboard_di.c
)
# 网络后端(net_* 核心 API 的 Winsock 实现 + UI 推流平台后端;MCU 端另编 net_socket.c 与 _mcu 后端)
set(NET_SOURCES
sim/net_socket_sim.c
@@ -174,7 +182,7 @@ set(NET_SOURCES
#=============================================================================
# 构建可执行文件
#=============================================================================
add_executable(lvgl_sim WIN32 ${SIM_SOURCES} ${UI_SOURCES} ${NETCFG_SOURCES} ${SYSLOG_SOURCES} ${NET_SOURCES} ${ALGO_SOURCES} ${IEC104_SOURCES})
add_executable(lvgl_sim WIN32 ${SIM_SOURCES} ${UI_SOURCES} ${NETCFG_SOURCES} ${SYSLOG_SOURCES} ${NET_SOURCES} ${ALGO_SOURCES} ${IEC104_SOURCES} ${IOBOARD_SOURCES})
target_compile_definitions(lvgl_sim PRIVATE
LV_CONF_INCLUDE_SIMPLE # 让 lvgl.h 找到 lv_conf.h
+782
View File
@@ -0,0 +1,782 @@
/*
* 模块名称:开入去抖与快照(ioboard_di)主机侧单元测试
* 模块功能:在 PC 上离线验证 App/util/ioboard_di.c 的纯逻辑——通道去抖(窗口/边界/
* 回绕/抖动推迟)与双区快照(一致性、有效性、失败不写 0、饱和计数)。
*
* 被测对象:真实源文件 App/util/ioboard_di.c(#include 原样纳入)。
* 该单元只依赖 <stdint.h>,**无需任何桩**。
*
* 为什么值得单测(真机上这些判据要么测不出来、要么要等很久):
* 1. 去抖窗口的边界:板端只表现为"有时候多报一次变位 / 有时候少报一次",
* 靠现场遥信根本不知道是哪一拍差了 1 ms。这里有"19 ms 不翻、20 ms 翻"两条,
* 以及"持续抖动在抖动结束后才开始计时"(否则抖动会被当成一次真变位上报成 SOE)。
* 2. tick 回绕:板端要跑满 49.7 天才遇到一次;若写成 now >= t + window 的绝对比较,
* 回绕前后会静默冻结。这里用 0xFFFFFFF0 起的 32 拍扫过回绕点。
* 3. 失败语义(本项目 BSP 失败可观测性铁律):读失败**不得**把开入当全 0。
* 板端表现为"线松了十几秒、104 上开入全灭",与人眼看到的现场相反;
* 这里逐拍喂失败拍,断言 mask 保持上一有效值、valid 掉落、fail_count 递增。
* 4. 失败窗口内的真实变位不能丢:失败拍只丢"值"不丢"时间戳"——若不推进计时,
* 一次跨过整段失败窗口的变位会被永久吞掉,而没有任何迹象。
*
* 命名约定:docs/文档规范.md §7.1 —— 用例号 2026-10-27 起停发,用语义化函数名。
* 创建日期:2026-11-16
*/
#include <stdint.h>
#include <stdio.h>
#include "ioboard_di.h"
#include "ioboard_bits.h" /* 只为编译期静态断言"路数一致",不使用任何函数 */
#include "bsp_err.h"
#include "ioboard.h" /* 开出极性/语义位的宏契约(纯宏,主机侧可编译) */
/* 被测生产源(include_dirs 里有 Drivers/BSP/IOBOARD 与 App/util) */
#include "ioboard_bits.c" /* 74HC165 位序组装(纯函数,零依赖) */
#include "ioboard_di.c" /* 去抖 + 快照(纯逻辑,零依赖) */
static int s_pass;
static int s_fail;
#define CHECK(cond, name) \
do { \
if (cond) { \
s_pass++; \
} else { \
s_fail++; \
printf("FAIL: %s (line %d)\n", (name), __LINE__); \
} \
} while (0)
/* 编译期一致性:本模块自己的路数与 BSP 的路数必须是同一个数。
* 主机侧没有 MCU 的 static_assert,用"负数组长度"这条经典技巧(MSVC/ARMCC 都编译期报错)。 */
typedef char ioboard_di_ch_num_must_match_bsp[(IOBOARD_DI_CH_NUM == IOBOARD_DI_COUNT)
? 1 : -1];
#define WIN IOBOARD_DI_DEBOUNCE_MS
/* ---------------------------------------------------------------------------
* 一、74HC165 位序组装(ioboard_bits.c)
* -------------------------------------------------------------------------*/
/*
* 全零基线:8 拍全读到低电平 → mask 必须是 0。
* 为什么值得测:基线错(例如按取反存储)会让"全安静"误报成有开入变位——
* 台架上一片安静跟着报警,没人会怀疑到位序函数。
*/
static void di_assemble_all_zero(void)
{
static const uint8_t bits[IOBOARD_DI_COUNT] = { 0U, 0U, 0U, 0U, 0U, 0U, 0U, 0U };
CHECK(ioboard_di_assemble(bits) == 0x00U, "all-zero reads assemble to mask 0x00");
}
/*
* 全一 → 0xFF。为何值得测:防止逐位赋值被改成别的写法时漏掉一位——
* 漏掉的那一路现场表现为"某一路开入永远不来信号",最容易被当成外部接线问题。
*/
static void di_assemble_all_one(void)
{
static const uint8_t bits[IOBOARD_DI_COUNT] = { 1U, 1U, 1U, 1U, 1U, 1U, 1U, 1U };
CHECK(ioboard_di_assemble(bits) == 0xFFU, "all-one reads assemble to mask 0xFF");
}
/*
* A 位(手册的 A 输入,接口约定 bit0):只有第 8 个时钟沿之前读到的比特为 1。
* 为何值得测:位序核心判据。A 是最后被移出的一位,若实现直接 `mask |= bit << i`
* (不反序),A 会落在 bit7——台架上看不出,与"线接错一位"完全同形。
*/
static void di_assemble_a_channel_is_bit0(void)
{
static const uint8_t bits[IOBOARD_DI_COUNT] = { 0U, 0U, 0U, 0U, 0U, 0U, 0U, 1U };
CHECK(ioboard_di_assemble(bits) == 0x01U,
"only the 8th read (A channel) assembles to bit0 (0x01)");
}
/*
* H 位(手册的 H 输入,接口约定 bit7):只有第 1 个时钟沿之前读到的比特为 1。
* 为何值得测:与 A 位成对。单测 A 位仍可能被"整体反序后再取反"之类等价变形骗过,
* A/H 两端同时钉住才能把"反序"这个动作本身锁死。
*/
static void di_assemble_h_channel_is_bit7(void)
{
static const uint8_t bits[IOBOARD_DI_COUNT] = { 1U, 0U, 0U, 0U, 0U, 0U, 0U, 0U };
CHECK(ioboard_di_assemble(bits) == 0x80U,
"only the 1st read (H channel) assembles to bit7 (0x80)");
}
/*
* 混合 1,0,1,0,1,0,1,0 → **0xAA**(H/F/D/B 为 1,落在 bit7/5/3/1)。
*
* ⚠ 这是**辅助**用例,位序主判据是上面的单比特两端用例(只 A → 0x01、只 H → 0x80)。
* 来历(2026-11-16):同一组输入先后被三个人算出 0xA5、0x5A、0xAA 三个值,
* 说明该图样对人类不友好——人要把"第几拍"与"第几位"在脑子里同时倒着数。
* 保留它只为覆盖"多位同时有效"的组合形态,且把三个候选值都摆出来当路标:
* 0xAA = 正确实现(bit(7-i)) ← 本条断言的目标
* 0x55 = 不反序(mask |= bit << i) ← 这一类错误由 0x55 的反向用例与单比特用例拦住
* 0xA5 / 0x5A = 前两轮人工误算,不是任何实现的输出,引用前请先手推。
* 注意:本图样是回文的,正序/反序给出的是**互补**值而非同值,所以它确实能抓方向;
* 它能抓方向并不改变"位序主判据用单比特两端"这条安排。
*/
static void di_assemble_alternating_mixed(void)
{
static const uint8_t bits[IOBOARD_DI_COUNT] = { 1U, 0U, 1U, 0U, 1U, 0U, 1U, 0U };
CHECK(ioboard_di_assemble(bits) == 0xAAU,
"alternating reads: H,F,D,B high -> bits 7/5/3/1 (0xAA)");
}
/*
* 反向交替 0,1,0,1,0,1,0,1 → 0x55(G/E/C/A 为 1,落在 bit6/4/2/0)。
* 为何值得测:与上一条成对——两条的期望值互补(0xAA / 0x55),任一条与实现同向错时
* 另一条必红;单比特两端用例已锁死映射,这两条只是"多位组合"的补充证据。
*/
static void di_assemble_alternating_reverse_mixed(void)
{
static const uint8_t bits[IOBOARD_DI_COUNT] = { 0U, 1U, 0U, 1U, 0U, 1U, 0U, 1U };
CHECK(ioboard_di_assemble(bits) == 0x55U,
"reverse alternating reads: G,E,C,A high -> bits 6/4/2/0 (0x55)");
}
/*
* README 同款算例:只有 A 与 H 两路有信号 → reads = [1,0,0,0,0,0,0,1] → 0x81。
* 为何值得测:这是文档与实现之间的人工核对锚点;两边不一致说明已有一个人先错。
*/
static void di_assemble_a_and_h_is_0x81(void)
{
static const uint8_t bits[IOBOARD_DI_COUNT] = { 1U, 0U, 0U, 0U, 0U, 0U, 0U, 1U };
CHECK(ioboard_di_assemble(bits) == 0x81U,
"worked example: only A and H high assembles to 0x81");
}
/*
* 非 0 即高(接口契约:任何非 0 值视为高电平)。
* 为何值得测:将来若把读到的原始电平扩展成更宽的值(如带计数)直接灌进来,
* 断言 `bits[i] == 1` 的实现会把 0x03 当低——整路开入静默丢失。
*/
static void di_assemble_nonzero_means_high(void)
{
static const uint8_t bits[IOBOARD_DI_COUNT] = { 0xFFU, 0x02U, 0x80U, 0x00U,
0x00U, 0x01U, 0x00U, 0x02U };
const uint8_t expect = (uint8_t)(0x80U | 0x40U | 0x20U | 0x04U | 0x01U);
CHECK(ioboard_di_assemble(bits) == expect,
"any non-zero read counts as high");
}
/*
* 逐位置穷举:8 个位置各放一个 1,mask 必须恰好是互异的一位,且覆盖 bit0..bit7 全部。
* 为何值得测:这是"位序映射"这条契约在全部 8 个输入上的**完整定义域**;
* 写反、写漏、i 与 7-i 混用都会被它抓出(单靠 A/H 两端抓不到中间位的合流)。
*/
static void di_assemble_each_position_is_bijective(void)
{
uint8_t seen_bit[IOBOARD_DI_COUNT];
uint8_t hit_count[IOBOARD_DI_COUNT];
uint8_t bijective = 1U;
uint8_t reach_top = 0U;
uint8_t i;
for (i = 0U; i < (uint8_t)IOBOARD_DI_COUNT; i++) {
seen_bit[i] = 0U;
hit_count[i] = 0U;
}
for (i = 0U; i < (uint8_t)IOBOARD_DI_COUNT; i++) {
uint8_t bits[IOBOARD_DI_COUNT];
uint8_t mask;
uint8_t j;
for (j = 0U; j < (uint8_t)IOBOARD_DI_COUNT; j++) {
bits[j] = 0U;
}
bits[i] = 1U;
mask = ioboard_di_assemble(bits);
CHECK(mask == (uint8_t)(1U << ((uint8_t)(IOBOARD_DI_COUNT - 1U) - i)),
"single high at read i lands exactly on bit(7-i)");
for (j = 0U; j < (uint8_t)IOBOARD_DI_COUNT; j++) {
if ((mask & (uint8_t)(1U << j)) != 0U) {
seen_bit[j]++;
hit_count[i] = (uint8_t)(j + 1U); /* 1 基位号,0 = 没有任何位置命中 */
}
}
}
for (i = 0U; i < (uint8_t)IOBOARD_DI_COUNT; i++) {
if ((seen_bit[i] != 1U) || (hit_count[i] == 0U)) {
bijective = 0U;
}
if (hit_count[i] == (uint8_t)IOBOARD_DI_COUNT) {
reach_top = 1U;
}
}
CHECK(bijective == 1U, "read index -> mask bit is a one-to-one map over all 8 reads");
CHECK(reach_top == 1U, "the mapping reaches bit7 (nothing collapsed into the low half)");
}
/* ---------------------------------------------------------------------------
* 二、开出极性与语义位(ioboard.h 的宏契约)
*
* 说明:ioboard.h 没有独立的"mask -> GPIO 电平"转换函数(极性只由
* IOBOARD_DO_LEVEL_ACTIVE 一个宏决定,是唯一可改点),真实电平须上板用万用表验。
* 主机侧能替台架钉住的只有宏契约本身。
* -------------------------------------------------------------------------*/
/*
* 极性两档必须互补:ACTIVE 与 RELEASE 恰好一个是 1、一个是 0。
* 为何值得测:出口继电器误动是现场代价最高的一类缺陷。两个宏若被只改一个,
* "上电全释放"会变成"上电全吸合"——一条互补断言就拦住。
*/
static void do_polarity_macros_are_complementary(void)
{
const unsigned active = (unsigned)(IOBOARD_DO_LEVEL_ACTIVE);
const unsigned release = (unsigned)(IOBOARD_DO_LEVEL_RELEASE);
CHECK((active == 0U) || (active == 1U), "IOBOARD_DO_LEVEL_ACTIVE is a strict 1-bit level");
CHECK(active != release, "active and release levels are complementary");
CHECK((active + release) == 1U, "active + release == 1 (no third value can sneak in)");
}
/*
* 文档口径:当前硬件口径是"高电平 = 吸合"(用户 2026-11-16)。改成 0 本条即红——
* 这是有意的:改极性是**硬件事实变更**,必须同时改 README 与本条,不能悄悄翻过来。
*/
static void do_active_level_matches_documented_high(void)
{
CHECK(IOBOARD_DO_LEVEL_ACTIVE == 1U,
"active-high documented polarity still in force (change README together)");
}
/*
* 语义位:KO6=bit0、TRIP=bit1、ERT=bit2、CLZ=bit3,四位互异且恰好铺满 bit0..bit3。
* 为何值得测:这四个位就是出口通道号。互换两位 = 跳闸与告警出口对调,
* 台架上继电器照样"动",只有知道端子接线的人才会发现。
*/
static void do_semantic_bits_are_distinct_and_dense(void)
{
const uint8_t all = (uint8_t)(IOBOARD_DO_KO6 | IOBOARD_DO_TRIP
| IOBOARD_DO_ERT | IOBOARD_DO_CLZ);
CHECK(IOBOARD_DO_KO6 == 0x01U, "KO6 is bit0 (PC14)");
CHECK(IOBOARD_DO_TRIP == 0x02U, "TRIP is bit1 (PF0)");
CHECK(IOBOARD_DO_ERT == 0x04U, "ERT is bit2 (PF1)");
CHECK(IOBOARD_DO_CLZ == 0x08U, "CLZ is bit3 (PF6)");
CHECK(all == IOBOARD_DO_MASK_ALL, "the four channel bits exactly fill IOBOARD_DO_MASK_ALL");
CHECK(IOBOARD_DO_MASK_ALL == 0x0FU, "IOBOARD_DO_MASK_ALL is 0x0F (bit4..7 have no hardware)");
}
/*
* 路数常量:一片 74HC165 = 8 位。为何值得测:组装函数的移位用 IOBOARD_DI_COUNT 推导,
* 若有人为"将来两块级联 16 路"把它改成 16,返回值仍是 uint8_t,移位会溢出为未定义行为。
*/
static void counts_match_one_74hc165(void)
{
CHECK(IOBOARD_DI_COUNT == 8, "IOBOARD_DI_COUNT is 8 (one 74HC165)");
CHECK(IOBOARD_DI_MASK_ALL == 0xFFU, "IOBOARD_DI_MASK_ALL covers all 8 DI bits");
CHECK(IOBOARD_DO_COUNT == 4, "IOBOARD_DO_COUNT is 4 relay outputs");
}
/* ---------------------------------------------------------------------------
* 三、通道去抖(ioboard_di.c)
* -------------------------------------------------------------------------*/
/*
* 首拍直接确立:复位后第一拍读到 1,stable 立即为 1(不返回翻转)。
* 为何值得测:不这样做的话上电后要空等一个 20 ms 窗口,而 defaultTask 第一拍
* 恰好是 bring-up 完成之后——开入会在开机后短暂"不存在"。
*/
static void deb_first_sample_establishes_immediately(void)
{
ioboard_di_ch_t c;
ioboard_di_ch_reset(&c, 1U, 1000U);
CHECK(c.started == 0U, "reset leaves the channel unestablished");
CHECK(ioboard_di_ch_feed(&c, 1U, 1000U, WIN) == 0U, "first sample does not count as a flip");
CHECK(c.stable == 1U, "first sample sets the stable level immediately");
CHECK(c.started == 1U, "first sample marks the channel established");
}
/*
* 窗口内不翻:1 -> 0 后的第 19 ms 仍为稳定 1。
* 为何值得测:窗口差 1 ms 在板端只表现为"偶尔多报一次变位",现场遥信根本看不出。
*/
static void deb_flip_waits_full_window(void)
{
ioboard_di_ch_t c;
ioboard_di_ch_reset(&c, 1U, 0U);
(void)ioboard_di_ch_feed(&c, 1U, 0U, WIN);
(void)ioboard_di_ch_feed(&c, 0U, 100U, WIN); /* raw 变 0,计时从 100 开始 */
CHECK(ioboard_di_ch_feed(&c, 0U, 100U + WIN - 1U, WIN) == 0U,
"one ms short of the window: stable level does not flip");
CHECK(c.stable == 1U, "stable level still high at 19 ms");
}
/*
* 边界正好 20 ms:恰好满窗口即翻(>= 而不是 >)。
* 为何值得测:off-by-one 的另一种写法(>)会让每个窗口多等一拍;
* 在 50 ms 轮询下方向相同,但在更快节拍下会变成"永远差一拍"。
*/
static void deb_boundary_exactly_20ms_flips(void)
{
ioboard_di_ch_t c;
ioboard_di_ch_reset(&c, 1U, 0U);
(void)ioboard_di_ch_feed(&c, 1U, 0U, WIN);
(void)ioboard_di_ch_feed(&c, 0U, 500U, WIN);
CHECK(ioboard_di_ch_feed(&c, 0U, 500U + WIN, WIN) == 1U,
"exactly 20 ms of stable low: stable level flips (boundary is >=)");
CHECK(c.stable == 0U, "stable level is low after the boundary flip");
}
/*
* 抖动只推迟、不丢:在窗口内反复 1/0/1/0,每次变化都重置计时,稳定电平一次都不翻。
* 为何值得测:去抖失效的最坏后果不是"延迟",而是**把抖动当成真变位**上报——
* IEC 104 会因此刷出一串假 SOE,运维会去现场查根本不存在的动作。
*/
static void deb_chatter_does_not_flip(void)
{
ioboard_di_ch_t c;
uint32_t t;
uint8_t flips = 0U;
ioboard_di_ch_reset(&c, 1U, 0U);
(void)ioboard_di_ch_feed(&c, 1U, 0U, WIN);
/* 10 个周期、每 5 ms 翻一次(< 20 ms 窗口),共 50 ms */
for (t = 5U; t <= 50U; t += 5U) {
const uint8_t lvl = (((t / 5U) % 2U) == 0U) ? 1U : 0U;
flips = (uint8_t)(flips + ioboard_di_ch_feed(&c, lvl, t, WIN));
}
CHECK(flips == 0U, "chatter inside the window never flips the stable level");
CHECK(c.stable == 1U, "stable level still the original high after 50 ms of chatter");
}
/*
* 抖动结束后重新计时:最后一次抖动在 t=50,则 t=69 不翻、t=70 翻。
* 为何值得测:若实现用"第一次变化的时刻"而不是"最近一次变化的时刻"计时,
* 抖动结束后会**立刻**翻转,等于只在开始处滤了一次——现场表现为"每次开关都报两次"。
*/
static void deb_chatter_restarts_timer(void)
{
ioboard_di_ch_t c;
ioboard_di_ch_reset(&c, 1U, 0U);
(void)ioboard_di_ch_feed(&c, 1U, 0U, WIN);
(void)ioboard_di_ch_feed(&c, 0U, 10U, WIN);
(void)ioboard_di_ch_feed(&c, 1U, 20U, WIN);
(void)ioboard_di_ch_feed(&c, 0U, 50U, WIN); /* 最后一次抖动:计时从 50 起 */
CHECK(ioboard_di_ch_feed(&c, 0U, 50U + WIN - 1U, WIN) == 0U,
"timer restarts at the last edge (19 ms after it: no flip)");
CHECK(ioboard_di_ch_feed(&c, 0U, 50U + WIN, WIN) == 1U,
"timer restarts at the last edge (20 ms after it: flip)");
}
/*
* 窗口 0 = 不滤波:下一拍立即跟随。为何值得测:上层若要临时关掉滤波(例如标定时
* 要看到原始抖动),window=0 必须是真的"立即",而不是被实现悄悄当成默认 20。
*/
static void deb_zero_window_follows_next_sample(void)
{
ioboard_di_ch_t c;
ioboard_di_ch_reset(&c, 1U, 0U);
(void)ioboard_di_ch_feed(&c, 0U, 0U, 0U);
(void)ioboard_di_ch_feed(&c, 1U, 1U, 0U); /* raw 变 1,计时从 1 起 */
CHECK(ioboard_di_ch_feed(&c, 1U, 1U, 0U) == 1U, "window 0 flips on the very next sample");
CHECK(c.stable == 1U, "window 0: stable follows the raw level immediately");
}
/*
* tick 回绕:raw 在 0xFFFFFFF0 由 1 变 0,窗口 20 ms → 翻在 0x00000004。
* 为何值得测:板端要跑满 49.7 天才遇到一次;若写成 `now >= t + window` 的绝对比较,
* 回绕后 t + window 会溢出成小数,比较立刻为真 → 抖动被当成真变位。
* 这里先断言"回绕前差 1 ms 不翻"(若实现有溢出 bug,这一条会红)。
*/
static void deb_flip_across_tick_wraparound(void)
{
ioboard_di_ch_t c;
const uint32_t t0 = 0xFFFFFFF0U;
ioboard_di_ch_reset(&c, 1U, 0U);
(void)ioboard_di_ch_feed(&c, 1U, 0U, WIN);
(void)ioboard_di_ch_feed(&c, 0U, t0, WIN); /* 计时起点:距回绕 16 ms */
CHECK(ioboard_di_ch_feed(&c, 0U, 0x00000003U, WIN) == 0U,
"across wraparound: 19 ms after the edge does not flip");
CHECK(ioboard_di_ch_feed(&c, 0U, 0x00000004U, WIN) == 1U,
"across wraparound: exactly 20 ms after the edge flips");
}
/*
* 1 ms 步进扫过回绕点:翻转只发生一次,且发生在距边沿恰好 20 ms 的那一拍。
* 为何值得测:上一条只测两个点;这里把 15 拍的整段扫一遍,任何"提前翻 / 漏翻 /
* 连翻两次"都会被计数抓出(去抖是每个通道一次翻,多一次就是多一条假 SOE)。
*/
static void deb_wraparound_sweep_flips_once(void)
{
ioboard_di_ch_t c;
uint32_t t;
uint8_t flips = 0U;
uint32_t at_tick = 0U;
const uint32_t t0 = 0xFFFFFFF0U;
ioboard_di_ch_reset(&c, 1U, 0U);
(void)ioboard_di_ch_feed(&c, 1U, 0U, WIN);
(void)ioboard_di_ch_feed(&c, 0U, t0, WIN);
for (t = 0x00000001U; t <= 0x00000010U; t++) {
if (ioboard_di_ch_feed(&c, 0U, t, WIN) != 0U) {
flips++;
at_tick = t;
}
}
CHECK(flips == 1U, "sweep across wraparound: exactly one flip");
CHECK(at_tick == 0x00000004U, "sweep across wraparound: the flip lands at t0+20 ms");
}
/*
* 通道相互独立:8 个通道里只让第 3 路变,其它 7 路必须原地不动。
* 为何值得测:若实现把"计时起点"存成模块级静态而不是每通道一份,
* 任何一路抖动都会重置全组——现场表现为"动一路,旁边几路跟着报变位"。
*/
static void deb_channels_are_independent(void)
{
ioboard_di_ch_t ch[IOBOARD_DI_CH_NUM];
uint8_t i;
uint8_t flips_for_3 = 0U;
uint8_t flips_other = 0U;
ioboard_di_ch_reset(ch, (uint8_t)IOBOARD_DI_CH_NUM, 0U);
for (i = 0U; i < (uint8_t)IOBOARD_DI_CH_NUM; i++) {
(void)ioboard_di_ch_feed(&ch[i], 1U, 0U, WIN); /* 全是高 */
}
for (i = 0U; i < (uint8_t)IOBOARD_DI_CH_NUM; i++) {
const uint8_t lvl = (i == 3U) ? 0U : 1U;
uint8_t f = ioboard_di_ch_feed(&ch[i], lvl, 10U, WIN);
f = (uint8_t)(f + ioboard_di_ch_feed(&ch[i], lvl, 30U, WIN));
if (i == 3U) {
flips_for_3 = (uint8_t)(flips_for_3 + f);
} else {
flips_other = (uint8_t)(flips_other + f);
}
}
CHECK(flips_for_3 == 1U, "the channel that really changed flips exactly once");
CHECK(flips_other == 0U, "the other 7 channels never flip");
CHECK(ch[3].stable == 0U, "channel 3 is low after its window");
CHECK(ch[0].stable == 1U, "channel 0 untouched");
}
/* ---------------------------------------------------------------------------
* 四、双区快照(ioboard_di.c)
* -------------------------------------------------------------------------*/
/*
* 复位后快照"无效且无值":valid=0、change_seq=0,读出的值是 0 但返回 0。
* 为何值得测:消费者必须能区分"还没有任何开入值"与"开入全 0";
* 若复位后 valid 就是 1、change_seq 也是 0,104 会报一个从未发生过的"全 0 遥信"。
*/
static void snap_reset_is_invalid_and_empty(void)
{
ioboard_di_snapshot_t s;
uint8_t m = 0xEEU;
uint32_t q = 0xEEU;
ioboard_di_snap_reset(&s);
CHECK(s.valid == 0U, "after reset the snapshot is invalid");
CHECK(s.change_seq == 0U, "after reset change_seq is 0 (no baseline yet)");
CHECK(ioboard_di_snap_read(&s, &m, &q) == 0U, "reading an invalid snapshot returns 0");
CHECK(m == 0U, "an invalid snapshot carries mask 0 (must not be used as data)");
CHECK(q == 0U, "an invalid snapshot carries change_seq 0");
}
/*
* 首次发布即建立基线:返回 1、change_seq = 1、读得到一致值。
* 为何值得测:上位机用 change_seq 从 0 到 1 的日子判断"基线已建立";
* 若首次发布不算变化,收到全 0 开入(合法)时也无法与"没有数据"区分。
*/
static void snap_first_publish_establishes_baseline(void)
{
ioboard_di_snapshot_t s;
uint8_t m = 0U;
uint32_t q = 0U;
ioboard_di_snap_reset(&s);
CHECK(ioboard_di_snap_publish(&s, 0x00U, 1U, 1U) == 1U,
"first publish counts as a change (0 -> 1 baseline)");
CHECK(s.change_seq == 1U, "change_seq is 1 after the first publish");
CHECK(ioboard_di_snap_read(&s, &m, &q) == 1U, "a published snapshot reads back valid");
CHECK(m == 0x00U, "reads back the published mask");
CHECK(q == 1U, "reads back the published change_seq");
}
/*
* 值不变不算变化:连续发布同一 mask,change_seq 不涨。
* 为何值得测:change_seq 是 104 的变位判据;若每拍都涨,COV 上送会变成"每 50 ms 一帧",
* 把通道打通的是 104 链路带宽而不是真实变位。
*/
static void snap_same_mask_does_not_bump_change_seq(void)
{
ioboard_di_snapshot_t s;
ioboard_di_snap_reset(&s);
(void)ioboard_di_snap_publish(&s, 0x12U, 1U, 1U);
CHECK(ioboard_di_snap_publish(&s, 0x12U, 1U, 1U) == 0U, "same mask: not a change");
CHECK(s.change_seq == 1U, "same mask: change_seq unchanged");
CHECK(ioboard_di_snap_publish(&s, 0x13U, 1U, 1U) == 1U, "different mask: a change");
CHECK(s.change_seq == 2U, "different mask: change_seq incremented once");
}
/*
* 失败拍不把 mask 写成 0(本项目的铁律,核心断言):
* 先发布 0xA5,接下来连续 5 拍"读失败",mask 必须仍是 0xA5,valid 掉到 0,
* fail_count 涨到 5、fail_edges == 1(只记一次下降沿)。
* 为何值得测:板端表现为"线松了十几秒、104 上开入全灭",与人眼看到的现场相反;
* 运维会以为现场真断电。这是本项目 BSP 失败可观测性铁律的主机侧落点。
*/
static void snap_failure_keeps_last_valid_mask(void)
{
ioboard_di_snapshot_t s;
uint8_t m = 0U;
uint32_t q = 0U;
uint8_t i;
ioboard_di_snap_reset(&s);
(void)ioboard_di_snap_publish(&s, 0xA5U, 1U, 1U); /* 一次成功读 */
for (i = 0U; i < 5U; i++) {
(void)ioboard_di_snap_publish(&s, 0xA5U, 0U, 0U); /* 失败拍:传上一有效值 */
}
CHECK(s.mask == 0xA5U, "failure frames never rewrite mask to 0 (keep the last valid value)");
CHECK(s.valid == 0U, "failure frames mark the snapshot invalid");
CHECK(s.fail_count == 5, "fail_count counts every failed frame");
CHECK(s.fail_edges == 1U, "fail_edges counts one falling edge for a contiguous failure window");
CHECK(s.change_seq == 1U, "failure frames do not create a phantom change");
CHECK(ioboard_di_snap_read(&s, &m, &q) == 0U, "reader sees the snapshot as invalid during failure");
CHECK(m == 0xA5U, "reader still costs the last valid mask (but must not use it as new data)");
}
/*
* 恢复:失败窗口之后成功读一次,valid 回到 1,fail_edges 不再涨。
* 为何值得测:fail_edges 只在下降沿计数;若实现把恢复也当边沿,故障次数会被重复上报。
*/
static void snap_recovery_restores_valid(void)
{
ioboard_di_snapshot_t s;
ioboard_di_snap_reset(&s);
(void)ioboard_di_snap_publish(&s, 0x01U, 1U, 1U);
(void)ioboard_di_snap_publish(&s, 0x01U, 0U, 0U);
CHECK(ioboard_di_snap_publish(&s, 0x01U, 1U, 1U) == 0U, "recovery with the same mask is not a change");
CHECK(s.valid == 1U, "recovery restores valid");
CHECK(s.fail_edges == 1U, "recovery does not count as another falling edge");
CHECK(s.fail_count == 0, "recovery resets the consecutive-failure counter");
}
/*
* 失败期间的真实变位不丢:先成功读到 0x00,失败窗口里第 3 拍"实际变 0x01"(调用方
* 仍按上一有效值发布 0x00),恢复后第一拍发布 0x01 → change_seq 涨到 2。
* 为何值得测:这就是"失败拍只丢值、不丢时间戳与候选值"的意义(见 ioboard_di.h 的
* 失败语义说明)。若去抖/候选值在失败期间停摆,恢复后要重新走一个 20 ms 窗口,
* 一次短故障(< 20 ms)里的真实变位会被永久吞掉,且没有任何迹象。
*/
static void snap_real_change_across_failure_window_is_not_lost(void)
{
ioboard_di_snapshot_t s;
ioboard_di_snap_reset(&s);
(void)ioboard_di_snap_publish(&s, 0x00U, 1U, 1U);
(void)ioboard_di_snap_publish(&s, 0x00U, 1U, 1U);
CHECK(s.change_seq == 1U, "baseline established with change_seq 1");
(void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U); /* 失败第 1 拍 */
(void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U); /* 失败第 2 拍 */
(void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U); /* 失败第 3 拍(实际已变) */
CHECK(ioboard_di_snap_publish(&s, 0x01U, 1U, 1U) == 1U,
"the change that happened during the failure window surfaces on recovery");
CHECK(s.change_seq == 2U, "change_seq counts that change exactly once");
}
/*
* 失败计数:连续失败上不封顶地累加、到 CAP 饱和不绕负;**任何一次成功读即归零**。
* 为何值得测:一次断线跑满 24 天(2 147 483 647 ms)在长期服役的装置上是可能的;
* 若 int32 绕回负数,自检里"读失败帧数为负"意味着"一直失败"看起来像"从未失败"。
* 反过来,若成功读不归零,一次偶发失败会让计数永久停在上界,之后真正的断线
* 再也看不出来——"连续"二字的两个方向都要钉住。
*/
static void snap_fail_count_saturates_and_resets(void)
{
ioboard_di_snapshot_t s;
ioboard_di_snap_reset(&s);
(void)ioboard_di_snap_publish(&s, 0x00U, 1U, 1U);
(void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U); /* 进入失败态:一记下降沿 */
s.fail_count = (int32_t)IOBOARD_DI_FAIL_COUNT_CAP - 2; /* 抬到接近上界 */
(void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U);
(void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U);
CHECK(s.fail_count == (int32_t)IOBOARD_DI_FAIL_COUNT_CAP, "fail_count reaches CAP exactly");
(void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U);
(void)ioboard_di_snap_publish(&s, 0x00U, 0U, 0U);
CHECK(s.fail_count == (int32_t)IOBOARD_DI_FAIL_COUNT_CAP,
"fail_count saturates at CAP instead of wrapping negative");
CHECK(s.fail_edges == 1U, "a long failure window is still one edge");
(void)ioboard_di_snap_publish(&s, 0x00U, 1U, 1U); /* 一次成功读 */
CHECK(s.fail_count == 0, "one successful read resets fail_count (it counts CONSECUTIVE failures)");
}
/*
* 阅读一致性协议的边界:写者正在写(seq 为奇数)时读者不得出结论。
* 为何值得测:真并发在主机侧无法复现,但"奇数序号 = 写者正在写"这一条是可构造的——
* 把 seq 手动设成奇数,读者必须返回 0 而不是把半新半旧的 mask 当结果。
*/
static void snap_reader_rejects_odd_seq(void)
{
ioboard_di_snapshot_t s;
uint8_t m = 0xAAU;
uint32_t q = 0xAAU;
ioboard_di_snap_reset(&s);
(void)ioboard_di_snap_publish(&s, 0x3CU, 1U, 1U);
s.seq = 5U; /* 模拟"写者停在两次递增之间" */
s.mask = 0x00U; /* 半新半旧的值 */
CHECK(ioboard_di_snap_read(&s, &m, &q) == 0U,
"reader returns 0 while the writer holds an odd sequence");
CHECK(m == 0xAAU, "reader leaves out_mask untouched when it cannot get a consistent value");
s.mask = 0x3CU;
s.seq = 6U; /* 写者恢复 */
CHECK(ioboard_di_snap_read(&s, &m, &q) == 1U, "reader succeeds once the sequence is even again");
CHECK(q == 1U, "reader returns change_seq, not the raw sequence");
}
/*
* 发布后序号恒为偶数:每拍发布一次,seq 必须保持偶数(写者协议的对外承诺)。
* 为何值得测:若实现漏掉最后那次递增,读者永远读不到——开入从某个时刻起静默冻结。
*/
static void snap_seq_stays_even_after_publish(void)
{
ioboard_di_snapshot_t s;
uint32_t i;
ioboard_di_snap_reset(&s);
for (i = 0U; i < 10U; i++) {
(void)ioboard_di_snap_publish(&s, (uint8_t)i, 1U, 1U);
}
CHECK((s.seq & 1U) == 0U, "seq is even after every publish");
CHECK(s.seq == 20U, "each publish advances seq by 2 (odd then even)");
}
/*
* NULL 契约:所有 NULL 入参安全返回(不崩、不写)。
* 为何值得测:本层在 defaultTask 主循环里常驻调用,任何一次崩溃就是 IWDG 复位;
* 防御性 NULL 分支也要被走一遍,否则它就是"写了但从未执行过"的代码。
*/
static void di_null_inputs_are_safe(void)
{
ioboard_di_snapshot_t s;
uint8_t m = 0x5AU;
uint32_t q = 0x5AU;
ioboard_di_snap_reset(&s);
(void)ioboard_di_snap_publish(&s, 0x3CU, 1U, 1U); /* s 变成"有效且有值" */
ioboard_di_ch_reset(NULL, 1U, 0U);
CHECK(ioboard_di_ch_feed(NULL, 1U, 0U, WIN) == 0U, "feed with a NULL channel returns 0");
ioboard_di_snap_reset(NULL);
CHECK(ioboard_di_snap_publish(NULL, 0U, 1U, 1U) == 0U, "publish on a NULL snapshot returns 0");
CHECK(ioboard_di_snap_read(NULL, &m, &q) == 0U, "read on a NULL snapshot returns 0");
CHECK((m == 0U) && (q == 0U), "read on a NULL snapshot zeroes its outputs");
ioboard_di_snap_copy(NULL, &s);
ioboard_di_snap_copy(&s, NULL);
ioboard_di_snap_copy(NULL, NULL);
CHECK(s.valid == 1U, "copy with a NULL source leaves the destination untouched");
CHECK(ioboard_di_snap_read(&s, NULL, NULL) == 1U,
"reader tolerates NULL outputs (valid snapshot, values discarded)");
}
/*
* 诊断接口合同:snap_faults 取出的两个数与快照字段一致;NULL 源给 0。
* 为何值得测:defaultTask 用它在故障下降沿写 syslog;这里若读错字段,
* 日志会写成"失败帧数 = 故障次数"这类倒挂值,排查时被反着理解。
*/
static void snap_faults_accessor_matches_fields(void)
{
ioboard_di_snapshot_t s;
uint32_t edges = 0U;
int32_t fails = 0;
ioboard_di_snap_reset(&s);
(void)ioboard_di_snap_publish(&s, 0x01U, 1U, 1U);
(void)ioboard_di_snap_publish(&s, 0x01U, 0U, 0U);
(void)ioboard_di_snap_publish(&s, 0x01U, 0U, 0U);
ioboard_di_snap_faults(&s, &edges, &fails);
CHECK(edges == 1U, "faults accessor returns fail_edges");
CHECK(fails == 2, "faults accessor returns consecutive fail_count");
ioboard_di_snap_faults(&s, NULL, NULL); /* 两个输出都可省略 */
ioboard_di_snap_faults(NULL, &edges, &fails);
CHECK((edges == 0U) && (fails == 0), "faults accessor on a NULL snapshot yields zeros");
}
int main(void)
{
printf("-- ioboard unit tests --\n");
/* 一、74HC165 位序 */
di_assemble_all_zero();
di_assemble_all_one();
di_assemble_a_channel_is_bit0();
di_assemble_h_channel_is_bit7();
di_assemble_alternating_mixed();
di_assemble_alternating_reverse_mixed();
di_assemble_a_and_h_is_0x81();
di_assemble_nonzero_means_high();
di_assemble_each_position_is_bijective();
/* 二、开出极性 / 语义位 / 路数 */
do_polarity_macros_are_complementary();
do_active_level_matches_documented_high();
do_semantic_bits_are_distinct_and_dense();
counts_match_one_74hc165();
/* 三、通道去抖 */
deb_first_sample_establishes_immediately();
deb_flip_waits_full_window();
deb_boundary_exactly_20ms_flips();
deb_chatter_does_not_flip();
deb_chatter_restarts_timer();
deb_zero_window_follows_next_sample();
deb_flip_across_tick_wraparound();
deb_wraparound_sweep_flips_once();
deb_channels_are_independent();
/* 四、双区快照 */
snap_reset_is_invalid_and_empty();
snap_first_publish_establishes_baseline();
snap_same_mask_does_not_bump_change_seq();
snap_failure_keeps_last_valid_mask();
snap_recovery_restores_valid();
snap_real_change_across_failure_window_is_not_lost();
snap_fail_count_saturates_and_resets();
snap_reader_rejects_odd_seq();
snap_seq_stays_even_after_publish();
di_null_inputs_are_safe();
snap_faults_accessor_matches_fields();
printf("=== IO Board Tests: %d/%d PASSED ===\n", s_pass, s_pass + s_fail);
return (s_fail == 0) ? 0 : 1;
}
+60
View File
@@ -0,0 +1,60 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""开入开出板(ioboard)主机侧纯逻辑单元测试运行器(纯标准库)。
做什么:用本机 MSVC 离线编译 test/host/ioboard 下的测试单元 .c
(单元内部 #include 纳入生产源文件 Drivers/BSP/IOBOARD/ioboard_bits.c),
在 PC 上验证:
一、74HC165 位序组装(ioboard_bits.c 的 ioboard_di_assemble)
器件按 A→H→QH 移位,第一个时钟沿之前 QH 上已经是 H 位,所以软件读 8 次
拿到的是 H,G,F,E,D,C,B,A;接口约定 A 在 bit0,组装必须把 reads[0] 放 bit7。
二、开出极性与语义位的宏契约(ioboard.h 的 IOBOARD_DO_* 宏)
为什么非要主机侧单测(板级套件是**测不出来**的):
位序写反只会让「A 路信号出现在 bit7」,而台架上看到的仍然是「某一路开入有信号」——
与线接错一位完全同形,无法归因、无法判废。`docs/门禁说明/host-unit-tests.md` §6
第 5 条写明「时序与并发不在主机侧范围」,反过来说:**能在这里钉住的纯逻辑就必须
在这里钉住**,否则它就是裸奔上线。
被测对象为什么是 ioboard_bits.c 而不是 ioboard.c:
ioboard.c 里是真实的 GPIO/FreeRTOS 时序(HAL_GPIO_*、taskENTER_CRITICAL、DWT),
宿主 MSVC 编不过也不该编过。位序/极性已被拆成零依赖的编译单元(正交解法),
本运行器只 include 那一个单元——**不搭 HAL 桩**,所以不存在「桩与真实头不同步」
这类假绿(同一条限制,host-unit-tests.md §6 第 2 条)。
用法(仓库根目录):
& '.venv\\Scripts\\python.exe' test/host/ioboard/run_unit_test.py
退出码:0=PASS / 1=测试失败 / 2=环境错误。
设计依据:docs/门禁说明/host-unit-tests.md
创建日期:2026-11-16
"""
import os
import sys
HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(os.path.dirname(os.path.dirname(HERE)))
# harness 位于 test/host/common/
sys.path.insert(0, os.path.join(ROOT, "test", "host", "common"))
from unit_test_harness import TestBuild, run_host_unit_test # noqa: E402
IOBOARD_DIR = os.path.join(ROOT, "Drivers", "BSP", "IOBOARD")
# 测试单元内部 #include 生产源;HERE 在前,便于将来加本目录私有桩时不改顺序。
BUILD = TestBuild(
name="IO Board Tests",
src=os.path.join(HERE, "ioboard_test.c"),
include_dirs=[
HERE,
IOBOARD_DIR,
os.path.join(ROOT, "Drivers", "BSP"), # bsp_err.h(ioboard.h 的依赖)
os.path.join(ROOT, "App", "util"), # ioboard_di.c(去抖 + 快照纯逻辑)
],
summary_marker="=== IO Board Tests:",
)
if __name__ == "__main__":
sys.exit(run_host_unit_test(BUILD))