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 根钩子全通过。
683 lines
28 KiB
C
683 lines
28 KiB
C
/*
|
||
* 模块名称:开入开出板 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;
|
||
}
|