fd767d1dcd
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 根钩子全通过。
260 lines
15 KiB
C
260 lines
15 KiB
C
#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 */
|