Personnaliser le pinmux (SFIO / direction / état par broche)

Aperçu

La feuille de calcul Tegra pinmux (.xlsm) est la source de vérité pour chaque broche CVM : nom de broche SoC, SFIOs supportés, fonction sélectionnée par le client, direction et état initial. Cette compétence analyse l'XLSM, exécute une boucle interactive Q1–Q6 par broche, et émet les trois DTSIs BCT (pinmux, gpio, padvoltage) en une seule fois dans le suivi des overlays à <source.root_path>/Linux_for_Tegra/bootloader/.

Contrairement aux compétences sœurs jetson-customize-uphy / jetson-customize-pcie / jetson-customize-camera, pinmux n'a pas de surface overlay kernel-DT et pas d'édition ODMDATA. L'XLSM est la source de vérité ; les trois DTSIs émis arrivent au moment du flash via les références PINMUX_CONFIG= / GPIOINT_CONFIG= / PMC_CONFIG= de la conf du support (que /jetson-derive-carrier a mises en place).

Classification des pads (fixée au silicium) : seuls les pads BD* et BI* ont des attributs pull / drive / open-drain configurables. LP5XA_*, UPHYDS_*, DP_SINGLE_*, BDMIPI16X_*, BDUSB2_*, OSCI27_* sont des fonctions fixes et ignorent Q4–Q6 (configurable: no).

Le script bundlé scripts/modify_pinmux.py est le moteur : il analyse l'XLSM via openpyxl>=3.1, construit la pinmap JSON par support, capture les éditions de broches dans un shim de session, et (lors du generate) écrit les trois DTSIs.

Quand invoquer

• L'utilisateur dit « configurer une broche », « définir SFIO », « éditer DTSI pinmux », « définir la direction de la broche », « définir l'état initial », ou demande de réaffecter une broche CVM (par ex. basculer une broche entre GPIO et une fonction périphérique).
• Une compétence sœur (jetson-customize-camera, jetson-customize-pcie, jetson-customize-usb, jetson-customize-mgbe) signale une incompatibilité de broche HSIO via pin_verifier.py et l'utilisateur veut la corriger.
• L'utilisateur a pré-dérivé un support personnalisé avec /jetson-derive-carrier et souhaite maintenant créer le pinmux à partir d'un .xlsm fraîchement édité.

Prérequis :

• Profil actif sélectionné (target-platform/active_target.yml → <profile>.yaml avec reference_devkit: ET custom_carrier:).
• <source.root_path>/Linux_for_Tegra/ existe en tant que dépôt git (/jetson-init-source).
• /jetson-derive-carrier a s'exécuté — les trois DTSIs BCT côté pinmux (PINMUX_CONFIG, GPIOINT_CONFIG, références PMC_CONFIG dans la conf du support) existent dans le suivi des overlays.
• Un .xlsm pinmux est enregistré dans le profil actif à documents.custom_carrier_pinmux_xls (préféré quand spécifique au support personnalisé) ou documents.ref_devkit_pinmux_xls (fallback). Le modify_pinmux.py bundlé requiert openpyxl>=3.1.

Procédure

Voir references/procedure.md pour la procédure complète étape par étape (étapes 1–8). Résumé :

1. Résoudre la cible active + XLSM. Valider le profil actif, custom_carrier:, les prérequis du suivi des overlays ; résoudre le chemin .xlsm pinmux depuis documents.custom_carrier_pinmux_xls → documents.ref_devkit_pinmux_xls → XLSM unique sous documents.root_path → invite utilisateur.
2. Probe. Exécuter modify_pinmux.py probe pour analyser l'XLSM dans le scratch par compétence <KB>/pinmap/<custom-carrier>.json plus le shim session.json.
3. Lookup. Résoudre une requête utilisateur en forme libre (broche CVM, nom Verilog, signal, broche DT) via modify_pinmux.py lookup ; afficher la liste SFIO supportée, les valeurs par défaut et configurable: yes/no.
4. Set-pin (HARD GATE — Q1–Q6 via AskUserQuestion). Q1–Q3 (sfio / direction / initial_state) toujours posées ; Q4–Q6 (pull / drive_type / open_drain) uniquement quand configurable: yes. tristate et e_input sont dérivés de direction, jamais posés.
5. Generate. modify_pinmux.py generate --out-dir <source.root_path>/Linux_for_Tegra/bootloader/ (racine, pas bootloader/generic/BCT/ — les forks .dts de derive-carrier vivent là, ne colocalisez pas). Émet : tegra<soc>-mb1-bct-{pinmux,gpio,padvoltage}-<carrier-key>.dtsi. <carrier-key> provient de la référence PINMUX_CONFIG= de la conf du support, PAS du nom du support en kebab-case.
6. Commit (un seul commit groupé par règle de workflow). Les trois DTSIs sont une édition logique → un commit de personnalisation. Exécuter la porte de prévisualisation de commit avant chaque commit.
7. Sidecar run-state + shim de session. Écrire le sidecar <profile-stem>.jetson-customize-pinmux.json visible par l'utilisateur et le shim transitoire session.json sous <workspace>/target-platform/.
8. Résumé. Émettre le résumé standard une ligne + tableau.

Pièges

• Pas d'overlay kernel-DT ; pas d'édition OVERLAY_DTB_FILE ; pas de transfert render_conf.py. Cette compétence s'arrête aux trois DTSIs BCT — la conf du support les référence déjà via PINMUX_CONFIG= / GPIOINT_CONFIG= / PMC_CONFIG= (mise en place par /jetson-derive-carrier).
• Re-pointer le #include du wrapper .dts après generate. /jetson-derive-carrier fork les wrappers .dts à bootloader/generic/BCT/, mais leurs lignes #include peuvent toujours tirer le .dtsi devkit en amont (par ex. …-p3834-xxxx-p4071-0000.dtsi). Après que generate écrive le nouveau <CARRIER_KEY>.dtsi à la racine de bootloader/, éditer chaque #include du wrapper vers le nouveau nom — par nom de base nu (#include "tegra<soc>-mb1-bct-pinmux-<CARRIER_KEY>.dtsi"), pas ../../… relatif au système de fichiers. Le build BCT cpp -I bootloader/ résout les noms de base nus ; c'est la convention que chaque autre include BCT dans l'arbre suit. Fusionner les éditions du wrapper dans le même commit de personnalisation que les trois DTSIs. Voir references/procedure.md étape 5 (« Sanity-check the carrier .dts wrapper »).
• Q4–Q6 gated on configurable: yes. Demander pull / drive_type / opendrain sur un pad de fonction fixe (`LP5XA,UPHYDS_,BDMIPI16X_*, etc.) est silencieusement supprimé par le script et confond l'utilisateur.lookupafficheconfigurable: yes/no` — toujours le vérifier avant de demander Q4–Q6.
• tristate et e_input sont dérivés, jamais posés. unused → tristate=ENABLE ; input / bidirectional → enable-input=ENABLE. Les exposer comme des invites séparées produit des DTSIs incohérents.
• sfio=gpio requiert une entrée gpio=GPIOn_PD.NN analysable dans la liste sfio de la ligne de pinmap. Les broches sans une ne sont pas compatibles GPIO silicium ; set-pin rejette l'appel. Afficher le rejet — ne pas tomber silencieusement en arrière vers un SFIO non-GPIO.
• Idempotence des marqueurs. Chaque édition par broche porte // custom-bsp: pinmux sur l'accolade fermante ; les entrées de default-state gpio portent le même marqueur comme commentaire final. Réexécuter generate doit détecter et mettre à jour — jamais dupliquer.
• modify_pinmux.py est inchangé du framework original — il lit son propre shim session.json sous --kb-dir. Le shim est régénéré chaque fois depuis le profil actif + le sidecar visible par l'utilisateur. Ne pas éditer manuellement le shim ; il est transitoire.
• Variantes multiples de DTSI pinmux par SKU de module Thor. Certaines broches du support vivent dans une variante DTSI différente de celle que la conf du support référence. modify_pinmux.py commit (flux patch-in-place hérité) tolère les blocs per-pin manquants via pinmux.warnings[] plutôt que d'échouer. Afficher l'avertissement ; pointer vers la variante DTSI alternative.
• Ne touchez pas au BSP en amont à <bsp_image.root_path>. Tous les édits arrivent dans <source.root_path>/Linux_for_Tegra/bootloader/ selon le motif pristine + customization commit.

Scripts disponibles

Invoquer depuis le corps de la compétence comme un sous-processus via 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/

Références

• references/procedure.md — prose de procédure complète étapes 1–8.
• questions.json — schéma de demande Q1–Q6 consommé par l'étape 4.
• ../../references/platform_template.yaml — bloc documents: (ref_devkit_pinmux_xls, custom_carrier_pinmux_xls).
• ../../context/bsp-customization-workflow.md — protocole édition overlay (un commit par fork DTSI).
• ../jetson-derive-carrier/SKILL.md — doit s'exécuter en premier ; produit les forks DTSI pinmux / gpio / padvoltage que cette compétence édite, et réécrit les lignes PINMUX_CONFIG= / GPIOINT_CONFIG= / PMC_CONFIG= de la conf du support pour les pointer.
• ../jetson-init-source/SKILL.md — produit le suivi des overlays dans lequel cette compétence commite.
• ../jetson-link-docs/SKILL.md — auteur du bloc documents: du profil, incluant les liaisons XLSM pinmux.