jetson-customize-pinmux

pinmux をカスタマイズする（ピンごとの SFIO／方向／状態）

概要

Tegra の pinmux スプレッドシート（.xlsm）は、すべての CVM ボールについて、SoC のピン名、対応する SFIO、顧客が選択した機能、方向、初期状態の正となる情報源です。このスキルはその XLSM を解析し、ピンごとの Q1～Q6 の対話型ループを実行して、3 つの 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 が正となる情報源です。出力された 3 つの DTSI は、キャリア conf の 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 時に）3 つの 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 → reference_devkit: と custom_carrier: を含む <profile>.yaml）。
• <source.root_path>/Linux_for_Tegra/ が Git リポジトリとして存在する（/jetson-init-source）。
• /jetson-derive-carrier が実行済みである。3 つの pinmux 側 BCT DTSI（キャリア conf 内の PINMUX_CONFIG、GPIOINT_CONFIG、PMC_CONFIG の各参照）がオーバーレイトラッカーに存在する。
• アクティブなプロファイルの documents.custom_carrier_pinmux_xls（カスタムキャリア固有の場合に優先）または documents.ref_devkit_pinmux_xls（フォールバック）に pinmux .xlsm が登録されている。同梱の 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 が 1 つだけの場合 → ユーザーに確認します。
2. プローブします。 modify_pinmux.py probe を実行して XLSM を解析し、スキルごとのスクラッチ領域 <KB>/pinmap/<custom-carrier>.json と session.json shim を作成します。
3. 検索します。 modify_pinmux.py lookup を使用して、自由形式のユーザークエリ（CVM ball、Verilog 名、信号、DT ピン）を解決します。対応する SFIO の一覧、デフォルト値、および configurable: yes/no を提示します。
4. ピンを設定します（HARD GATE — AskUserQuestion で Q1～Q6）。 Q1～Q3（sfio／direction／initial_state）は必ず確認します。Q4～Q6（pull／drive_type／open_drain）は configurable: yes の場合のみ確認します。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> は kebab-case にしたキャリア名ではなく、キャリア conf の PINMUX_CONFIG= 参照から取得します。
6. コミットします（ワークフロールールに従い、まとめて 1 回コミットします）。 3 つの DTSI は 1 つの論理的な編集であるため、カスタマイズコミットは 1 回です。各コミットの前にコミットプレビューゲートを実行します。
7. 実行状態のサイドカーとセッション shim。 ユーザー向けの <profile-stem>.jetson-customize-pinmux.json サイドカーと、一時的な session.json shim を <workspace>/target-platform/ 配下に書き込みます。
8. 概要。 標準の 1 行概要と表を出力します。

注意事項

• カーネルの DT オーバーレイはありません。OVERLAY_DTB_FILE の編集も、render_conf.py への引き渡しも不要です。 このスキルは 3 つの BCT DTSI で完了します。キャリアの conf からは、/jetson-derive-carrier によって設定済みの PINMUX_CONFIG= / GPIOINT_CONFIG= / PMC_CONFIG= を通じて、すでにこれらが参照されています。
• 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 インクルードで使われている規約です。ラッパーの編集は、3 つの 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 shim を読み込みます。この shim は、アクティブなプロファイルとユーザー向けのサイドカーから、実行のたびに再生成されます。shim を手動で編集しないでください。一時ファイルです。
• 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/ に適用します。

利用可能なスクリプト

スクリプト	用途	引数
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() 経由で呼び出します。

# 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 — Step 1～8 の手順の全文です。
• questions.json — Step 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 — pinmux XLSM のバインディングを含む、プロファイルの documents: ブロックを作成します。