# Pinmux 派生 CSV 数据结构与验收规范

本规范只约束按需生成的审核 CSV。BSP 代码修改仍以经确认的 GPIO/Pinmux 需求、自动选择并校验的内置目标芯片资料、参考项目源码和实际构建引用为依据。

## 规范化 JSON

导出脚本接收 UTF-8 JSON 对象：

```json
{
  "project_name": "项目名称",
  "rows": [
    {
      "pin_number": "A12",
      "function_name": "CAM_RST0",
      "pin_name": "PAD_MIPI_TXM4",
      "is_gpio": true,
      "active_level": "低有效",
      "fmux_register": "0x030010A4",
      "fmux_current": "3",
      "fmux_default": "0",
      "fmux_list": "0:XGPIOA_20; 1:CAM_MCLK0; 3:GPIOA_20; MIPI:TXM4"
    }
  ]
}
```

| JSON 字段 | 最终列 | 规则 |
|---|---|---|
| `pin_number` | 引脚号 | BGA 球位优先；非 BGA 填封装脚号 |
| `function_name` | 功能名称 | 原理图网络名或经核实的板级用途 |
| `pin_name` | 引脚名称 | 芯片手册中的 Pad 名 |
| `is_gpio` | 不输出 | 当前用途是否为通用 GPIO，不是 Pad 是否支持 GPIO |
| `active_level` | 有效电平 | GPIO 为 `高有效`、`低有效`或`待确认`；非 GPIO 为 `null` |
| `fmux_register` | FMUX寄存器 | 完整地址或手册定义的寄存器名 |
| `fmux_current` | FMUX当前值 | 当前用途对应编号；不确定填 `待确认` |
| `fmux_default` | FMUX默认值 | 手册复位默认值；不确定填 `待确认` |
| `fmux_list` | FMUX_list | `编号:功能`，以 `; ` 分隔；可保留特殊模式说明 |

## 资料提取

- 先定位主芯片全部分单元页面和封装表，再沿导线、网络标签、页间端口及器件连接确认每个信号脚用途。
- 芯片 XLSX 由 [内置 GPIO 资料目录](builtin-gpio-pinout.md)自动选择并使用 `query_builtin_pinout.py` 解析；禁止绕过 manifest 的型号映射和 SHA-256 校验直接借用相近表格。
- PDF 优先使用保布局文本提取；文本层错位或原理图密集时，将关键页面转为图像核查。
- 为候选 Pad 保留来源页码或工作表行号，至少覆盖型号、封装、球位、Pad、FMUX 地址、默认值、编号映射和特殊模式。

## 有效电平判定

仅在 `is_gpio=true` 时判定：

- GPIO 直接连接使能、复位、LED、按键或驱动器时，依据器件逻辑及真实电流路径判断。
- 奇数级 NPN/NMOS 共射或共源级通常造成逻辑反相；P 沟道高边电路还要结合栅极驱动方向。
- 上拉且按下接地的按键通常低有效；`RSTN`、`RESET#`、`CS_N` 是低有效线索，但仍需核对中间反相级。
- 上下拉可能只定义上电安全态，不能单独作为有效电平结论。
- 证据冲突或信号链不完整时填 `待确认`，并说明缺少的证据。

非 GPIO 当前用途必须填 `null`，即使该 Pad 可以复用为 GPIO。

## 多 FMUX 筛选

`FMUX_list` 中，以字符串开头或 `; ` 后出现的 `0:` 到 `7:` 为编号选项。至少有两个不同编号才输出。

- 保留：`0:GPIOA_1; 2:PWM_1; 3:UART1_TX`
- 排除：`0:GPIOA_1; MIPI:RX0`

## 验收清单

- 文件名为安全化的 `<项目名称>_pinmux.csv`，编码为 UTF-8 BOM。
- 表头严格为八列，顺序不变。
- 每个球位最多一行，且每行至少有两个不同编号 FMUX 选项。
- GPIO 有效电平不是 `null`；非 GPIO 有效电平恰为 `null`。
- `FMUX当前值`为编号时，该编号存在于 `FMUX_list`。
- 球位、Pad、寄存器和默认值来自匹配型号及封装的资料。
- `待确认`、`UNKNOWN` 和功能冲突均在交付信息中逐项列出；型号或封装不匹配时禁止生成最终 CSV，只交付差异与冲突清单。
- 不包含电源、地、EPAD、NC 或未连接脚。