jetson-customize-pinmux

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Customize pinmux (per-pin SFIO / direction / state)

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

Overview

概述

The Tegra pinmux spreadsheet (

.xlsm

) is the ground truth for every CVM ball: SoC pin name, supported SFIOs, customer-selected function, direction, and initial state. This skill parses that XLSM, runs a per-pin Q1–Q6 interactive loop, and emits the three BCT DTSIs (

pinmux

gpio

padvoltage

) in one shot into the overlay tracker at

<source.root_path>/Linux_for_Tegra/bootloader/

Unlike sibling skills

jetson-customize-uphy

jetson-customize-pcie

jetson-customize-camera

, pinmux has no kernel-DT overlay surface and no ODMDATA edit. The XLSM is the source of truth; the three emitted DTSIs land at flash time via the carrier conf's

PINMUX_CONFIG=

GPIOINT_CONFIG=

PMC_CONFIG=

references (which

/jetson-derive-carrier

set up).

Pad classification (silicon-fixed): only

BD*

and

BI*

pads have configurable pull / drive / open-drain attributes.

LP5XA_*

UPHYDS_*

DP_SINGLE_*

BDMIPI16X_*

BDUSB2_*

OSCI27_*

are fixed-function and skip Q4–Q6 (

configurable: no

The bundled

scripts/modify_pinmux.py

is the workhorse: it parses the XLSM via

openpyxl>=3.1

, builds the per-carrier pinmap JSON, captures pin edits into a session shim, and (on

generate

) writes the three DTSIs.

Tegra pinmux电子表格（

.xlsm

）是所有CVM引脚的权威来源：包含SoC引脚名称、支持的SFIO、用户选择的功能、方向和初始状态。本Skill会解析该XLSM文件，运行单引脚Q1–Q6交互式流程，并一次性生成三个BCT DTSI文件（

pinmux

、

gpio

、

padvoltage

），输出到

<source.root_path>/Linux_for_Tegra/bootloader/

路径下的overlay追踪器中。

与同系列Skill

jetson-customize-uphy

jetson-customize-pcie

jetson-customize-camera

不同，pinmux无需内核-DT overlay层，也无需编辑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，将引脚编辑内容捕获到会话垫片中，并在执行

generate

命令时写入三个DTSI文件。

When to invoke

调用场景

The user says "configure pin", "set SFIO", "edit pinmux DTSI", "set pin direction", "set initial state", or asks to repurpose a CVM ball (e.g. flip a pin between GPIO and a peripheral function).

A sibling skill (

jetson-customize-camera

jetson-customize-pcie

jetson-customize-usb

jetson-customize-mgbe

) reports an HSIO pin mismatch via

pin_verifier.py

and the user wants to fix it.

The user pre-derived a custom carrier with
```
/jetson-derive-carrier
```
and now wants to author the pinmux from a freshly-edited
```
.xlsm
```
.

Prerequisites:

Active profile selected (

target-platform/active_target.yml

→

<profile>.yaml

with

reference_devkit:

AND

custom_carrier:

<source.root_path>/Linux_for_Tegra/

exists as a git repo (

/jetson-init-source

```
/jetson-derive-carrier
```
has run — the three pinmux-side BCT DTSIs (
```
PINMUX_CONFIG
```
,
```
GPIOINT_CONFIG
```
,
```
PMC_CONFIG
```
references in the carrier conf) exist in the overlay tracker.
A pinmux
```
.xlsm
```
is registered in the active profile at
```
documents.custom_carrier_pinmux_xls
```
(preferred when custom-carrier- specific) or
```
documents.ref_devkit_pinmux_xls
```
(fallback). The bundled
```
modify_pinmux.py
```
requires
```
openpyxl>=3.1
```
.

用户提及“配置引脚”、“设置SFIO”、“编辑pinmux DTSI”、“设置引脚方向”、“设置初始状态”，或要求重新分配CVM引脚用途（例如在GPIO和外设功能之间切换引脚）。

同系列Skill（

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

→ 包含

reference_devkit:

和

custom_carrier:

的

<profile>.yaml

）。

<source.root_path>/Linux_for_Tegra/

路径已作为git仓库存在（由

/jetson-init-source

创建）。

已运行
```
/jetson-derive-carrier
```
—— 载板配置文件中引用的三个pinmux侧BCT DTSI文件（
```
PINMUX_CONFIG
```
、
```
GPIOINT_CONFIG
```
、
```
PMC_CONFIG
```
）已存在于overlay追踪器中。
激活配置文件中已注册pinmux
```
.xlsm
```
文件，优先使用
```
documents.custom_carrier_pinmux_xls
```
（自定义载板专属）， fallback使用
```
documents.ref_devkit_pinmux_xls
```
。内置的
```
modify_pinmux.py
```
需要依赖
```
openpyxl>=3.1
```
。

Procedure

操作流程

See

references/procedure.md

for the full step-by-step procedure (Steps 1–8). Summary:

Resolve active target + XLSM. Validate active profile,
```
custom_carrier:
```
, overlay-tracker prerequisites; resolve the pinmux
```
.xlsm
```
path from
```
documents.custom_carrier_pinmux_xls
```
→
```
documents.ref_devkit_pinmux_xls
```
→ single XLSM under
```
documents.root_path
```
→ user prompt.

Probe. Run

modify_pinmux.py probe

to parse the XLSM into the per-skill scratch

<KB>/pinmap/<custom-carrier>.json

plus

session.json

shim.

Lookup. Resolve a free-form user query (CVM ball, Verilog name, signal, DT pin) via
```
modify_pinmux.py lookup
```
; surface supported SFIO list, defaults, and
```
configurable: yes/no
```
.
Set-pin (HARD GATE — Q1–Q6 via
AskUserQuestion
). Q1–Q3 (
```
sfio
```
/
```
direction
```
/
```
initial_state
```
) always asked; Q4–Q6 (
```
pull
```
/
```
drive_type
```
/
```
open_drain
```
) only when
```
configurable: yes
```
.
```
tristate
```
and
```
e_input
```
are derived from
```
direction
```
, never asked.

Generate.

modify_pinmux.py generate --out-dir <source.root_path>/Linux_for_Tegra/bootloader/

(root, not

bootloader/generic/BCT/

— derive-carrier

.dts

forks live there, do not colocate). Emits:

tegra<soc>-mb1-bct-{pinmux,gpio,padvoltage}-<carrier-key>.dtsi

. <carrier-key>
comes from the carrier conf's
PINMUX_CONFIG=
reference, NOT the kebab-cased carrier name.

Commit (single batched commit per workflow rule). All three DTSIs are one logical edit → one customization commit. Run the commit-preview gate before each commit.
Run-state sidecar + session shim. Write the user-facing
```
<profile-stem>.jetson-customize-pinmux.json
```
sidecar and the transient
```
session.json
```
shim under
```
<workspace>/target-platform/
```
.
Summary. Emit the standard one-line + table summary.

完整的分步流程（步骤1–8）请参考

references/procedure.md

。流程摘要：

解析激活目标 + XLSM文件。验证激活配置文件、
```
custom_carrier:
```
、overlay追踪器前置条件；按优先级
```
documents.custom_carrier_pinmux_xls
```
→
```
documents.ref_devkit_pinmux_xls
```
→
```
documents.root_path
```
下的单个XLSM文件 → 用户提示，解析pinmux
```
.xlsm
```
文件路径。
探测。运行
```
modify_pinmux.py probe
```
命令，将XLSM文件解析为Skill专属临时文件
```
<KB>/pinmap/<custom-carrier>.json
```
和
```
session.json
```
会话垫片。
查询。通过
```
modify_pinmux.py lookup
```
命令解析用户自由格式查询（CVM引脚、Verilog名称、信号、DT引脚）；展示支持的SFIO列表、默认值以及
```
configurable: yes/no
```
状态。
设置引脚（严格校验 —— 通过
AskUserQuestion
执行Q1–Q6）。Q1–Q3（
```
sfio
```
/
```
direction
```
/
```
initial_state
```
）始终会询问；Q4–Q6（
```
pull
```
/
```
drive_type
```
/
```
open_drain
```
）仅在
```
configurable: yes
```
时询问。
```
tristate
```
和
```
e_input
```
由
```
direction
```
推导得出，不会单独询问。
生成。执行
```
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=
引用，而非短横线分隔的载板名称。
提交（每个工作流规则对应一次批量提交）。三个DTSI文件属于同一逻辑编辑 → 对应一次定制提交。每次提交前需运行提交预览校验。
运行状态副文件 + 会话垫片。在
```
<workspace>/target-platform/
```
路径下写入用户可见的
```
<profile-stem>.jetson-customize-pinmux.json
```
副文件和临时
```
session.json
```
会话垫片。
总结。输出标准的单行摘要 + 表格摘要。

Gotchas

注意事项

No kernel-DT overlay; no
OVERLAY_DTB_FILE
edit; no
render_conf.py
hand-off. This skill ends at the three BCT DTSIs — the carrier conf already references them via
```
PINMUX_CONFIG=
```
/
```
GPIOINT_CONFIG=
```
/
```
PMC_CONFIG=
```
(set up by
```
/jetson-derive-carrier
```
).
Re-point the
.dts
wrapper's
#include
after
generate
.
```
/jetson-derive-carrier
```
forks the
```
.dts
```
wrappers at
```
bootloader/generic/BCT/
```
, but their
```
#include
```
lines may still pull the upstream devkit
```
.dtsi
```
(e.g.
```
…-p3834-xxxx-p4071-0000.dtsi
```
). After
```
generate
```
writes the new
```
<CARRIER_KEY>.dtsi
```
to
```
bootloader/
```
root, edit each wrapper's
```
#include
```
to the new filename — by bare basename (
```
#include "tegra<soc>-mb1-bct-pinmux-<CARRIER_KEY>.dtsi"
```
), not
```
../../…
```
filesystem-relative. The BCT build's
```
cpp -I bootloader/
```
resolves bare basenames; that's the convention every other BCT include in the tree follows. Roll the wrapper edits into the same customization commit as the three DTSIs. See
```
references/procedure.md
```
Step 5 ("Sanity-check the carrier
```
.dts
```
wrapper").
Q4–Q6 gated on
configurable: yes
. Asking pull / drive_type / open_drain on a fixed-function pad (
```
LP5XA_*
```
,
```
UPHYDS_*
```
,
```
BDMIPI16X_*
```
, etc.) is silently dropped by the script and confuses the user.
```
lookup
```
prints
```
configurable: yes/no
```
— always check it before prompting Q4–Q6.
tristate
and
e_input
are derived, never asked.
```
unused
```
→ tristate=ENABLE;
```
input
```
/
```
bidirectional
```
→ enable-input=ENABLE. Exposing them as separate prompts produces inconsistent DTSIs.
sfio=gpio
requires a parseable
gpio=GPIOn_PD.NN
entry in the pinmap row's
sfio
list. Pins without one are GPIO-incapable silicon;
```
set-pin
```
rejects the call. Surface the rejection — don't silently fall back to a non-GPIO SFIO.
Marker idempotency. Every per-pin edit carries
```
// custom-bsp: pinmux
```
on the closing brace; gpio default-state entries carry the same marker as a trailing comment. Re-running
```
generate
```
must detect and update — never duplicate.
modify_pinmux.py
is unchanged from the original framework — it reads its own
```
session.json
```
shim under
```
--kb-dir
```
. The shim is regenerated each run from the active profile + the user-facing sidecar. Do not hand-edit the shim; it's transient.
Multiple pinmux DTSI variants per Thor module SKU. Some carrier pins live in a different DTSI variant than the one the carrier conf references.
```
modify_pinmux.py commit
```
(legacy patch-in-place flow) tolerates missing per-pin blocks via
```
pinmux.warnings[]
```
rather than failing. Surface the warning; point at the alternate DTSI variant.
Don't touch the upstream BSP at
<bsp_image.root_path>
. All edits land in
```
<source.root_path>/Linux_for_Tegra/bootloader/
```
under the pristine + customization commit pattern.

无需内核-DT overlay；无需编辑
OVERLAY_DTB_FILE
；无需移交
render_conf.py
。本Skill的输出仅为三个BCT DTSI文件 —— 载板配置文件已通过
```
PINMUX_CONFIG=
```
/
```
GPIOINT_CONFIG=
```
/
```
PMC_CONFIG=
```
引用它们（由
```
/jetson-derive-carrier
```
配置）。
生成后需更新
.dts
包装文件的
#include
路径。
```
/jetson-derive-carrier
```
会在
```
bootloader/generic/BCT/
```
目录下生成
```
.dts
```
包装文件，但它们的
```
#include
```
行可能仍引用上游开发板的
```
.dtsi
```
文件（例如
```
…-p3834-xxxx-p4071-0000.dtsi
```
）。生成新的
```
<CARRIER_KEY>.dtsi
```
文件到
```
bootloader/
```
根目录后，需编辑每个包装文件的
```
#include
```
路径为新文件名 —— 使用纯文件名（
```
#include "tegra<soc>-mb1-bct-pinmux-<CARRIER_KEY>.dtsi"
```
），而非
```
../../…
```
这类文件系统相对路径。BCT构建时的
```
cpp -I bootloader/
```
会解析纯文件名；这是该目录下所有其他BCT引用遵循的约定。将包装文件的编辑内容与三个DTSI文件的编辑内容合并到同一次定制提交中。详情请参考
```
references/procedure.md
```
步骤5（“校验载板
```
.dts
```
包装文件”）。
Q4–Q6仅在
configurable: yes
时触发。对固定功能引脚（
```
LP5XA_*
```
、
```
UPHYDS_*
```
、
```
BDMIPI16X_*
```
等）询问上拉/驱动类型/开漏属性会被脚本静默忽略，导致用户困惑。
```
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
```
会话垫片。该垫片每次运行时都会根据激活配置文件和用户可见副文件重新生成。请勿手动编辑该垫片；它是临时文件。
Thor模块SKU可对应多个pinmux DTSI变体。部分载板引脚所在的DTSI变体可能与载板配置文件引用的变体不同。
```
modify_pinmux.py commit
```
（旧版原地补丁流程）会通过
```
pinmux.warnings[]
```
容忍缺失的单引脚块，而非直接失败。需展示该警告；并指向替代DTSI变体。
请勿修改
<bsp_image.root_path>
路径下的上游BSP。所有编辑内容需按照“纯净版+定制提交”模式，写入
```
<source.root_path>/Linux_for_Tegra/bootloader/
```
路径下。

Available Scripts

可用脚本

Script	Purpose	Arguments
`scripts/modify_pinmux.py`	XLSM parser + per-pin DTSI generator. Invoked via `run_script()` from Steps 3-6 with the subcommand of the current phase.	`probe \| lookup \| set-pin \| apply \| generate \| commit [...]` (see `--help` )
`scripts/generate_dtsi.py`	Renders pinmux/GPIO/padvoltage DTSI fragments from the bundled session state. Called by `modify_pinmux.py generate` .	`--session <path> --out-dir <dir>`

Invoke from the skill body as a subprocess via

run_script()

bash

undefined

脚本	用途	参数
`scripts/modify_pinmux.py`	XLSM解析器 + 单引脚DTSI生成器。在步骤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()

从Skill主体中以子进程方式调用：

bash

undefined

run_script: probe the carrier pinmux XLSM and write a session state

run_script: 探测载板pinmux XLSM并写入会话状态

scripts/modify_pinmux.py probe --xlsm carrier.xlsm --session .pinmux-session.json

run_script: render DTSI fragments from the final session state

run_script: 基于最终会话状态渲染DTSI片段

scripts/modify_pinmux.py generate --session .pinmux-session.json --out-dir bsp_sources/pinmux/

undefined

scripts/modify_pinmux.py generate --session .pinmux-session.json --out-dir bsp_sources/pinmux/

undefined

References

参考资料

```
references/procedure.md
```
— full Step 1–8 procedure prose.
```
questions.json
```
— Q1–Q6 prompt schema consumed by Step 4.

../../references/platform_template.yaml

—

documents:

block (

ref_devkit_pinmux_xls

custom_carrier_pinmux_xls

```
../../context/bsp-customization-workflow.md
```
— overlay edit protocol (single-commit per DTSI fork).
```
../jetson-derive-carrier/SKILL.md
```
— must run first; produces the pinmux / gpio / padvoltage DTSI forks this skill edits, and rewrites the carrier conf's
```
PINMUX_CONFIG=
```
/
```
GPIOINT_CONFIG=
```
/
```
PMC_CONFIG=
```
lines to point at them.
```
../jetson-init-source/SKILL.md
```
— produces the overlay tracker this skill commits into.
```
../jetson-link-docs/SKILL.md
```
— author the profile's
```
documents:
```
block, including the pinmux XLSM bindings.

```
references/procedure.md
```
—— 完整的步骤1–8流程说明。
```
questions.json
```
—— 步骤4使用的Q1–Q6提示 schema。

../../references/platform_template.yaml

——

documents:

块（

ref_devkit_pinmux_xls

、

custom_carrier_pinmux_xls

）。

```
../../context/bsp-customization-workflow.md
```
—— overlay编辑协议（每个DTSI分支对应一次提交）。
```
../jetson-derive-carrier/SKILL.md
```
—— 必须先运行该Skill；它会生成本Skill需要编辑的pinmux / gpio / padvoltage DTSI分支，并修改载板配置文件的
```
PINMUX_CONFIG=
```
/
```
GPIOINT_CONFIG=
```
/
```
PMC_CONFIG=
```
行以指向这些分支。
```
../jetson-init-source/SKILL.md
```
—— 生成本Skill用于提交的overlay追踪器。
```
../jetson-link-docs/SKILL.md
```
—— 编写配置文件的
```
documents:
```
块，包括pinmux XLSM绑定。