Personnaliser USB (activation / désactivation / rôle par port)

Objectif

Activer, désactiver ou modifier le rôle des ports USB2 / USB3 SS sur une carte mère personnalisée Jetson Thor (Tegra264) ou Orin (Tegra234). Capture le câblage par port (rôle, vitesse maximale, GPIOs VBUS-EN / OC, GPIOs CC1/CC2 pour Type-C, voie UPHY USB3 SS), résout le graphe companion SS vers USB2 à partir du DTB in-tree, puis génère une overlay kernel-DT autonome qui bascule chaque action de port en trois endroits de façon synchronisée (état de la voie, état du port, phys + phy-names xHCI hôte).

L'allocation de voie UPHY appartient à jetson-customize-uphy. Aucune édition ODMDATA. La sortie est un commit vers la .dts overlay personnalisée composite dans le repo matériel bsp_sources/.

Prérequis

Profil actif avec les blocs reference_devkit: + custom_carrier:.
<source.root_path>/Linux_for_Tegra/.git existe (/jetson-init-source).
/jetson-derive-carrier a été exécuté — fork flash-conf de la carte dans le tracker overlay.
/jetson-customize-uphy a été exécuté quand tout port USB3 SS activé a besoin d'une allocation de voie UPHY non standard. Son fichier JSON sidecar à <workspace>/target-platform/<profile-stem>.jetson-customize-uphy.json est consulté pour l'allocation de voie SS.
Docs de référence : Adaptation Guide §"Port the Universal Serial Bus", Module Design Guide §USB, SoC TRM (bloc xusb).
Quand custom_carrier: est présent, à la fois documents.custom_carrier_schematic ET documents.custom_carrier_pinmux_xls sont REQUIS. Refuser l'exécution si l'un des deux manque — le routage par port (GPIOs VBUS-EN / OC / CC, câblage de voie SS, fan-out hub) sur une carte personnalisée ne peut pas être deviné. Les profils reference-devkit uniquement ignorent cette vérification.
dtc, fdtoverlay sur PATH.

Aperçu

USB sur Tegra s'étend sur trois surfaces IP : le bloc xusb_padctl (PHYs USB2 OTG + USB3 SS), le contrôleur hôte xHCI tegra-xusb, et un contrôleur device tegra-xudc optionnel attaché au seul port USB2 capable OTG (usb2-0).

Une bascule par port DOIT toucher trois endroits du kernel-DT de façon synchronisée. Moins que cela écrase la sonde xHCI hôte et laisse lsusb vide sur chaque port (dégâts collatéraux aux ports sinon corrects) :

#	Endroit	Chemin	Ce qu'il contrôle
1	Voie (fournisseur PHY)	`xusb_padctl/pads/usb<2\\|3>/lanes/usb<2\\|3>-N`	Liaison matérielle PHY SS / OTG. `status="disabled"` arrête alors la voie de fournir un PHY.
2	Port (liaison contrôleur)	`xusb_padctl/ports/usb<2\\|3>-N`	Mode par port (host/device/otg), lien companion, références pins VBUS / OC / CC. `status="disabled"` supprime alors le port de la topologie exposée à l'utilisateur.
3	Liste phys xHCI hôte	`bus@0/usb@<addr>.phys` + `.phy-names`	Tableau de phandles + noms que le driver xHCI itère. Une référence à un PHY désactivé retourne `-ENODEV` et abandonne la sonde hôte entière.

Le stock-désactivé usb3-3 NVIDIA dans la DTB base Thor est le pattern canonique — les trois endroits basculent de façon synchronisée.

Deux règles supplémentaires s'appuient sur le pattern trois-endroits :

Règle A — appairage voie + port. Voie (endroit 1) et port correspondant (endroit 2) DOIVENT basculer ensemble.
Règle B — cascade companion. xusb_padctl/ports/usb3-N.nvidia,usb2-companion référence un phandle de port USB2. Désactiver cet USB2 sans cascader vers son companion SS produit alors tegra-xusb: failed to enable PHYs: -19.

Agentic, pas table-driven — chaque port, contrôleur, voie, lien companion, phandle, et recherche __symbols__ est résolu à runtime à partir des docs + DTB + pinmap de carte + schéma.

Quand invoquer

L'utilisateur dit « activer USB », « désactiver le hub USB », « configurer USB3 SS », « définir le rôle USB », « câbler VBUS-EN », « tegra-xusb / xudc / dr_mode », ou demande d'activer / désactiver un contrôleur USB sur une carte personnalisée.
Un connecteur USB sur la carte n'énumère pas après flash, OU les dégâts USB collatéraux (lsusb vide après une tentative précédente jetson-customize-usb) doivent être corrigés.
jetson-customize-uphy a réalloué des voies UPHY affectant les ports USB3 SS et la DT par port doit maintenant suivre.

Procédure (résumé)

La procédure complète étape par étape vit dans references/procedure.md.

Étape 1 — résoudre la cible active + ouvrir les docs source-of-truth.
Étape 2 — construire la topologie USB + graphe companion à partir de la DTB in-tree.
Étape 3 — AskUserQuestion pour le(s) port(s) à activer / désactiver ; surface cascade companion + fan-out hub on-carrier explicitement.
Étape 4 — vérification par port (module + carte + voie UPHY) et capture du câblage (GPIOs VBUS-EN / OC / CC via pin_verifier.py).
Étape 5 — rendre l'overlay kernel-DT utilisant le pattern trois-endroits, ajouter des fragments (usb:padctl, usb:xhci, usb:xudc optionnel) à la .dts overlay personnalisée composite, exécuter fdtoverlay + les trois invariants post-merge, commit à bsp_sources/.
Étape 6 — écrire le JSON sidecar run-state (forme dans references/run-state-sidecar.md), émettre le titre, puis piloter la chaîne next-step en aval via des prompts AskUserQuestion séquentiels par references/procedure.md Étape 6. Ne jamais substituer une ligne « Étape suivante : … » imprimée aux prompts.

Voir references/gotchas.md pour les modes de défaillance load-bearing.

Limitations

Possède overlay kernel-DT uniquement. ODMDATA n'expose pas un bouton USB status par port ; ne pas l'éditer.
N'alloue PAS les voies UPHY — jetson-customize-uphy possède cela. Refuser de committer une activation SS jusqu'à ce que l'état run-state uphy montre la voie allouée.
N'édite PAS directement la DTSI pinmux — route les désaccords SFIO à /jetson-customize-pinmux set-pin.
N'compile PAS la .dtbo ou n'enregistre pas OVERLAY_DTB_FILE+= — /jetson-build-source possède la registration build + flash-conf.
Invariant plateforme Tegra : seul usb2-0 est capable OTG ; xudc s'attache là uniquement. Tous les autres ports USB2 et tous les ports USB3 SS sont host-only.

Dépannage

lsusb vide sur chaque port, USB-eth à 192.168.55.1 toujours actif : l'hôte xHCI a échoué ; le synchronisme trois-endroits était rompu. Inspecter la DTB fusionnée ; vérifier les invariants post-merge dans references/procedure.md Étape 5d.
tegra-xusb: failed to enable PHYs: -19 : cascade companion (Règle B) violée — un USB2 a été désactivé sans son companion SS.
no port found ou Requested PHY is disabled : Règle A violée — l'état de voie et l'état de port sont dépareillés.
FDT_ERR_NOTFOUND de fdtoverlay : un fragment a utilisé target = <&label> pour un nœud dont le label n'est pas dans __symbols__ (typique pour hôte xHCI / tegra-xudc). Basculer à target-path = "/bus@0/usb@<addr>".
Avertissement dtc phys_property: cell 0 is not a phandle reference : bénin ; attendu lors de l'utilisation de phandles entiers bruts dans l'override phys hôte.
Port démarre mais VBUS ne s'affirme jamais : vbus-supply référence un nœud parent régulateur qui n'existe pas. S'assurer que le nœud régulateur fixe est présent avant de le référencer.
xHCI lie le mauvais port au démarrage : l'ordre des éléments phys hôte n'a pas été préservé. Élider uniquement les entrées désactivées ; ne jamais réordonner les conservées.

Références

references/procedure.md — procédure complète étape par étape.
references/gotchas.md — modes de défaillance load-bearing.
references/run-state-sidecar.md — forme JSON run-state.
references/usb-architecture.md — notes d'architecture IP USB Tegra (xusb_padctl, tegra-xusb, xudc).
references/usb-dt-bindings.md — feuille de triche liaison DT USB (formes voie / port / phys-list).
../../scripts/pin_verifier.py — vérificateur pin HSIO partagé.
../../references/platform_template.yaml — bloc documents: consommé par l'Étape 1.
../../context/bsp-customization-workflow.md — protocole édition overlay.
../../references/bsp-customization-kernel-dtb.md — protocole append overlay composite.
../jetson-customize-uphy/SKILL.md — skill sœur qui possède l'allocation de voie UPHY.
../jetson-customize-pinmux/SKILL.md — skill sœur pour les corrections SFIO VBUS-EN / OC / CC.
../jetson-derive-carrier/SKILL.md — doit s'exécuter en premier.
../jetson-init-source/SKILL.md — produit le tracker overlay + repo bsp_sources.