jetson-customize-pinmux

自定义 pinmux（逐引脚 SFIO / 方向 / 状态）

概述

Tegra pinmux 电子表格（.xlsm）是每个 CVM 焊球的事实来源：SoC 引脚名称、支持的 SFIO、客户选择的功能、方向和初始状态。此技能会解析该 XLSM，逐引脚执行 Q1–Q6 交互流程，并一次性将三个 BCT DTSI（pinmux、gpio、padvoltage）写入 <source.root_path>/Linux_for_Tegra/bootloader/ 中的覆盖层跟踪目录。

与相关技能 jetson-customize-uphy / jetson-customize-pcie / jetson-customize-camera 不同，pinmux 没有内核 DT 覆盖层，也不编辑 ODMDATA。XLSM 是事实来源；生成的三个 DTSI 会在刷写时通过载板配置文件中的 PINMUX_CONFIG= / GPIOINT_CONFIG= / PMC_CONFIG= 引用生效（这些引用由 /jetson-derive-carrier 设置）。

焊盘分类（硅片固定）： 只有 BD* 和 BI* 焊盘具有可配置的上拉/下拉、驱动和开漏属性。LP5XA_*、UPHYDS_*、DP_SINGLE_*、BDMIPI16X_*、BDUSB2_*、OSCI27_* 均为固定功能，跳过 Q4–Q6（configurable: no）。

随附的 scripts/modify_pinmux.py 是核心工具：它通过 openpyxl>=3.1 解析 XLSM，构建逐载板引脚映射 JSON，将引脚编辑捕获到会话 shim 中，并在执行 generate 时写入三个 DTSI。

何时调用

• 用户说“配置引脚”“设置 SFIO”“编辑 pinmux DTSI”“设置引脚方向”“设置初始状态”，或要求重新配置某个 CVM 焊球（例如在 GPIO 和外设功能之间切换引脚）。
• 相关技能（jetson-customize-camera、jetson-customize-pcie、jetson-customize-usb、jetson-customize-mgbe）通过 pin_verifier.py 报告 HSIO 引脚不匹配，且用户希望修复。
• 用户通过 /jetson-derive-carrier 预先派生了自定义载板，现在希望基于新编辑的 .xlsm 编写 pinmux。

前提条件：

• 已选择活动配置文件（target-platform/active_target.yml → <profile>.yaml，其中包含 reference_devkit: 和 custom_carrier:）。
• <source.root_path>/Linux_for_Tegra/ 已存在并且是 git 仓库（/jetson-init-source）。
• 已运行 /jetson-derive-carrier，覆盖层跟踪目录中存在三个 pinmux 侧的 BCT DTSI（载板配置文件中的 PINMUX_CONFIG、GPIOINT_CONFIG、PMC_CONFIG 引用）。
• 活动配置文件中已注册 pinmux .xlsm：documents.custom_carrier_pinmux_xls（自定义载板专用时优先使用），或 documents.ref_devkit_pinmux_xls（备用）。随附的 modify_pinmux.py 需要 openpyxl>=3.1。

流程

完整的分步流程（步骤 1–8）请参阅 references/procedure.md。摘要：

1. 解析当前目标和 XLSM。 验证当前配置、custom_carrier: 和 overlay-tracker 前提条件；按以下顺序解析 pinmux .xlsm 路径： documents.custom_carrier_pinmux_xls → documents.ref_devkit_pinmux_xls → documents.root_path 下唯一的 XLSM → 提示用户。
2. 探测。 运行 modify_pinmux.py probe，将 XLSM 解析到每项技能的暂存目录 <KB>/pinmap/<custom-carrier>.json，并生成 session.json 适配文件。
3. 查找。 通过 modify_pinmux.py lookup 解析用户的自由格式查询（CVM 球位、Verilog 名称、信号、DT 引脚）；显示支持的 SFIO 列表、默认值和 configurable: yes/no。
4. 设置引脚（硬性门槛 — 通过 AskUserQuestion 提出 Q1–Q6）。 始终询问 Q1–Q3（sfio / direction / initial_state）；仅当 configurable: yes 时询问 Q4–Q6（pull / drive_type / open_drain）。tristate 和 e_input 根据 direction 推导，不询问。
5. 生成。 运行 modify_pinmux.py generate --out-dir <source.root_path>/Linux_for_Tegra/bootloader/（根目录，不是 bootloader/generic/BCT/ — derive-carrier .dts 分支文件位于该目录中，不要将文件放在同一目录下）。生成： tegra<soc>-mb1-bct-{pinmux,gpio,padvoltage}-<carrier-key>.dtsi。 <carrier-key> 来自载板配置文件中的 PINMUX_CONFIG= 引用，而非以连字符分隔的载板名称。
6. 提交（每个工作流规则只进行一次批量提交）。 三个 DTSI 文件属于同一逻辑编辑 → 一次自定义提交。每次提交前运行提交预览门控。
7. 运行状态旁文件和会话适配文件。 写入面向用户的 <profile-stem>.jetson-customize-pinmux.json 旁文件，以及位于 <workspace>/target-platform/ 下的临时 session.json 适配文件。
8. 摘要。 输出标准的单行摘要和表格摘要。

注意事项

• 不生成 kernel-DT overlay；不编辑 OVERLAY_DTB_FILE；不移交给 render_conf.py。 此技能仅生成三个 BCT DTSI——载板 conf 已通过 PINMUX_CONFIG= / GPIOINT_CONFIG= / PMC_CONFIG= 引用它们（由 /jetson-derive-carrier 设置）。
• 运行 generate 后，重新指向 .dts 包装文件中的 #include。 /jetson-derive-carrier 会在 bootloader/generic/BCT/ 下派生 .dts 包装文件，但其中的 #include 行可能仍会引入上游开发套件的 .dtsi（例如 …-p3834-xxxx-p4071-0000.dtsi）。generate 将新的 <CARRIER_KEY>.dtsi 写入 bootloader/ 根目录后，编辑每个包装文件中的 #include，改为新文件名——使用不带路径的基本文件名（#include "tegra<soc>-mb1-bct-pinmux-<CARRIER_KEY>.dtsi"），而不是相对于文件系统的 ../../…。BCT 构建的 cpp -I bootloader/ 会解析不带路径的基本文件名；树中的其他 BCT include 都遵循这一惯例。将包装文件的编辑与三个 DTSI 一并纳入同一个定制提交。请参阅 references/procedure.md 第 5 步（“检查载板 .dts 包装文件”）。
• Q4–Q6 仅适用于 configurable: yes。 对固定功能焊盘（LP5XA_*、UPHYDS_*、BDMIPI16X_* 等）询问 pull / drive_type / open_drain，脚本会静默忽略这些设置，并让用户感到困惑。lookup 会打印 configurable: yes/no——在询问 Q4–Q6 前务必先检查。
• tristate 和 e_input 是派生值，不应询问。 unused → tristate=ENABLE；input / bidirectional → enable-input=ENABLE。将它们作为单独的问题会导致 DTSI 不一致。
• sfio=gpio 要求引脚映射表行的 sfio 列表中包含可解析的 gpio=GPIOn_PD.NN 条目。 不含此类条目的引脚不具备 GPIO 功能，set-pin 会拒绝调用。应明确提示拒绝原因——不要静默回退到非 GPIO SFIO。
• 标记的幂等性。 每个单引脚编辑都会在右花括号处带有 // custom-bsp: pinmux；gpio 默认状态条目则以相同标记作为尾随注释。重新运行 generate 时必须检测并更新，绝不能重复添加。
• modify_pinmux.py 与原始框架保持不变——它通过 --kb-dir 读取自身的 session.json 适配文件。每次运行时，都会根据当前配置和面向用户的 sidecar 重新生成该适配文件。不要手动编辑适配文件；它是临时文件。
• 同一 Thor 模块 SKU 可能有多个 pinmux DTSI 变体。 某些载板引脚位于与载板 conf 所引用的不同 DTSI 变体中。modify_pinmux.py commit（旧版原位打补丁流程）遇到缺失的单引脚块时，会通过 pinmux.warnings[] 发出警告，而不是失败。应明确提示警告，并指出备用 DTSI 变体。
• 不要修改位于 <bsp_image.root_path> 的上游 BSP。 所有编辑都应落在 <source.root_path>/Linux_for_Tegra/bootloader/ 下，并遵循先 pristine、后定制提交的模式。

可用脚本

脚本	用途	参数
scripts/modify_pinmux.py	XLSM 解析器和单引脚 DTSI 生成器。通过 Step 3-6 中的 run_script() 调用，并使用当前阶段对应的子命令。	probe | lookup | set-pin | apply | generate | commit [...]（参见 --help）
scripts/generate_dtsi.py	根据捆绑的会话状态生成 pinmux/GPIO/padvoltage DTSI 片段。由 modify_pinmux.py generate 调用。	--session <path> --out-dir <dir>

在技能正文中，将其作为子进程通过 run_script() 调用：

# run_script: probe the carrier pinmux XLSM and write a session state
scripts/modify_pinmux.py probe --xlsm carrier.xlsm --session .pinmux-session.json

# run_script: render DTSI fragments from the final session state
scripts/modify_pinmux.py generate --session .pinmux-session.json --out-dir bsp_sources/pinmux/

参考资料

• references/procedure.md — 完整的步骤 1–8 流程说明。
• questions.json — 供步骤 4 使用的 Q1–Q6 提示词架构。
• ../../references/platform_template.yaml — documents: 块（ref_devkit_pinmux_xls、custom_carrier_pinmux_xls）。
• ../../context/bsp-customization-workflow.md — 覆盖层编辑协议（每个 DTSI 分支单独提交一次）。
• ../jetson-derive-carrier/SKILL.md — 必须先运行；生成此技能要编辑的 pinmux / gpio / padvoltage DTSI 分支，并重写载板 conf 中的 PINMUX_CONFIG= / GPIOINT_CONFIG= / PMC_CONFIG= 行，使其指向这些分支。
• ../jetson-init-source/SKILL.md — 生成此技能要提交到的覆盖层跟踪文件。
• ../jetson-link-docs/SKILL.md — 编写配置文件的 documents: 块，包括 pinmux XLSM 绑定。