/jetson-customize-pinmux

name: jetson-customize-pinmux
description: >-
  Per-pin SFIO / direction / initial-state configurator for a Jetson
  Orin or Thor custom carrier from the pinmux XLSM. Do NOT use for
  kernel-DT overlay or ODMDATA edits.
version: 0.0.1
license: "Apache-2.0"
metadata:
  data-classification: public
  author: "Jetson Team"
  tags:
    - bsp
    - phase-2
    - io
    - pinmux
  domain: meta

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

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.

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`.

Procedure

See [`references/procedure.md`](references/procedure.md) for the full step-by-step procedure (Steps 1–8). Summary:

1. **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. 2. **Probe.** Run `modify_pinmux.py probe` to parse the XLSM into the per-skill scratch `<KB>/pinmap/<custom-carrier>.json` plus `session.json` shim. 3. **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`. 4. **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. 5. **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.** 6. **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. 7. **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/`. 8. **Summary.** Emit the standard one-line + table summary.

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