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
+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)→ **禁止**跨转换器做相位/功率/功率因数类运算
## 已知问题