# CV18 GPIO、Pinmux 与 Kernel DTS

## 适用范围

CV180*、CV181*、CV182*、CV183*、CV184* 项目先以实际 `buildEnvConfig.sh` 和配置布局确认芯片与有效文件。目录名和相近项目只能作为线索。

CV18 项目的 GPIO 复用、方向和启动安全初值通常由实际生效的 `cvi_board_init.c` 实现；Kernel DTS/DTSI 仍可能在 Linux 启动后声明同一 IO，必须同时检查。

## 内置 GPIO 资料查询

按 [内置 GPIO 资料目录](builtin-gpio-pinout.md)从项目 `buildEnvConfig.sh` 的 `EP_CHIP` 自动选择设计表，不要求用户重复提供已覆盖芯片的 PINOUT 文档。对 GPIO List 或原理图中的每个目标 Pad/GPIO/FMUX 执行 `scripts/bsp/query_builtin_pinout.py`，用返回的 Excel 行、Pad、Bank/Bit 复用项、FMUX 寄存器和默认值建立芯片侧证据。内置资料没有覆盖、查询无匹配或封装脚号冲突时停止；不得根据项目目录名或相近芯片猜测。

## `cvi_board_init.c` 语义

修改前读取整个相关函数，保留原有签名、调用阶段和代码风格：

- `PINMUX_CONFIG(pad, function)`：选择 Pad 复用功能；
- `Gpio_Set_Dir(base, bit, 1)`：按现有 CV18 实现配置输出；
- `Gpio_Set_Dir(base, bit, 0)`：按现有 CV18 实现配置输入；
- `Gpio_Set_Value(base, bit, value)`：设置输出状态或安全初值；
- `Gpio_Get_Value(base, bit)`：读取输入状态；
- `cvi_board_init()`：启动期复用、方向和初值；
- `cvi_update_led_control*()`、`cvi_get_key_status()` 等：运行期业务钩子，只修改与其功能相符的 GPIO；
- `ep_flash_bootidx()` 等启动钩子：只有需求确实涉及其 GPIO 时修改。

不得只按函数名或文本位置替换。对每个目标信号建立：功能名、Pad、复用功能、Bank/Bit、方向、有效电平、启动初值、运行期钩子和来源证据。

## 新增、移除与“无 GPIO”

- 参考项目没有、目标项目需要：只有 Pad、复用功能、Bank/Bit、方向和初值完整时才新增真实代码。
- 目标项目明确“无 GPIO”“未装配”或“不需要控制”：移除参考项目的旧复用、方向、初值及运行期控制，并在对应位置留下包含功能名的说明，例如：

  ```c
  // IR_LED: no GPIO on this board; no initialization required.
  ```

- 信息不完整时禁止猜测寄存器、Bank/Bit 或初始电平；在报告中列为阻塞。

## Kernel DTS/DTSI 占用检查

先按 [调查范围与验证模式](scope-and-validation-modes.md)确定验证模式。两种模式都从实际构建使用的板级 `.dts` 开始，递归读取允许范围内的有效 `.dts`/`.dtsi`，不能扫描无关项目后把非生效引用当成冲突。

完整 DTS 审核模式下，SDK include 文件或条件编译上下文不可读时，不能得出“Kernel 未占用该 GPIO”的结论，并阻塞完整审核通过。EmxRes 配置模式下，只核对项目 Overlay 并明确降低验证等级；它不阻塞配置项目最终化，但在统一编译及最终 DTB 核对前不能声明 Kernel GPIO 占用已验证。

按 GPIO Bank/Bit 检查：

- `*-gpio`、`*-gpios` 和厂商自定义 GPIO 属性；
- `scl-pinmux`、`sda-pinmux` 等厂商 Pinmux 属性；
- 节点覆盖、子设备和 `status`；
- 被条件编译或注释掉的定义，区分生效与非生效；
- 新旧消费者和 `cvi_board_init.c` 之间的用途与有效电平。

## 释放旧消费者

优先最小化释放，沿用项目现有 Device Tree 语法：

1. 只冲突单个 GPIO 属性时，在最接近板级的有效节点覆盖中使用 `/delete-property/`，保留模块其他功能。
2. 软件 I2C 等成组配置中，相关 `scl/sda-pinmux` 与 `scl/sda-gpios` 必须成对处理，不能留下半套声明。
3. 只有用户明确不使用整个模块，或释放 IO 后模块已经无法成立时，才设置 `status = "disabled"`。
4. 只停用总线下某个设备时，禁用对应子节点，不牺牲整个控制器。
5. 若模块仍有必要功能且无法安全释放单个 IO，停止并报告冲突。

示例：

```dts
/* Release GPIOC_13 for LCD_DC; old board used it as display reset. */
&old_display {
    /delete-property/ reset-gpios;
};
```

若新 GPIO 只用于 U-Boot 启动期初始化，DTS 只解除旧消费者，不虚构新设备节点。若它属于 Kernel 驱动管理的新设备，则在释放旧消费者后声明给正确新节点。

## 验证

逐个目标信号确认：

- Pad 复用与 GPIO Bank/Bit 一致；
- 输入没有无意义的输出初值，输出有明确安全初值；
- 同一 Pad 或 GPIO 没有重复用途；
- 运行期函数与启动期初始化引用一致；
- 明确无 GPIO 的功能没有残留旧控制代码；
- 项目 Overlay 与 SDK 的完整有效 DTS/DTSI include 链中，旧消费者、Pinmux 和 GPIO 属性已解除；
- 新 Kernel 消费者与 U-Boot 的用途和极性不冲突。

完整 DTS 审核模式检查整个有效 include 链；EmxRes 配置模式检查项目 Overlay，并在统一构建后尽量从最终 DTB 核对。不能执行对应验证时记录准确的未验证项，不得声称 Kernel 已验证。