# GPIO 实施计划契约

原理图或 GPIO List 导致 GPIO/Pinmux/DTS 变化时，在写代码前创建：

```text
doc/bsp_adaptation/inputs/gpio_plan.json
```

CSV 可作为附加审核视图，但不能替代该计划。计划顶层包含 `schema_version=1`、项目名、验证模式、来源、确认信息和 `signals`。每个信号至少包含：

- `function`：稳定的板级功能名；
- `pad`、`mux`；
- `gpio`：GPIO 时写 `A14`、`C17`、`PWR22` 等，非 GPIO 写 `null`；
- `direction`：`input`、`output`、`peripheral` 或 `none`；
- `active_level`：`high`、`low`、`paired`、`unknown` 或 `null`；
- `boot_value`：输出为 `0`/`1`，其他方向为 `null`；
- `runtime_owner`；
- `dts_consumers`：已知的旧/新消费者数组；
- `source_evidence`：带页码、表格行或文件位置的来源数组；芯片侧证据必须包含自动选中的内置表路径、SHA-256、工作表名和 Excel 行号；
- `decision`：`confirmed`、`inherited`、`no-gpio`、`provisional` 或 `blocked`；
- `note`。

执行：

```bash
python3 scripts/bsp/validate_gpio_plan.py <gpio_plan.json>
```

校验器检查字段、Pad/GPIO 重复、方向与启动值、GPIO/非 GPIO 语义和决策状态。写代码前向用户展示同一份实施表；用户确认后写入 `confirmation.confirmed=true`、确认时间和摘要，再次运行校验器。

只有 `confirmed`、`inherited` 和 `no-gpio` 行可以进入已确认实现。`provisional` 或 `blocked` 行必须先补证据或取得明确硬件决定。`no-gpio` 行不得生成虚构 GPIO 代码，应移除参考项目旧控制并留下包含功能名的注释。

对内置目录覆盖的 CV18 芯片，先按 [内置 GPIO 资料目录](builtin-gpio-pinout.md)运行 `query_builtin_pinout.py`，再建立计划。项目原理图或 GPIO List 负责说明板级连接与目标用途；内置表负责证明 Pad、脚号和 FMUX 能力，二者不能互相替代。