Files
STM32F4-Base/Drivers/BSP/IOBOARD/ioboard.h
T
wandering1 fd767d1dcd 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 根钩子全通过。
2026-11-16 18:30:31 +08:00

260 lines
15 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#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 */