Files
STM32F4-Base/Drivers/BSP/IOBOARD/ioboard.c
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

683 lines
28 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.
/*
* 模块名称:开入开出板 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;
}