Personnaliser l'allocation de voies UPHY

Objectif

Sélectionner une allocation de voies UPHY sur un carrier personnalisé Jetson et éditer le ODMDATA="..." du fork de la conf flash du carrier pour appliquer le ou les token(s) uphyX-config-N choisi(s) (plus le clear UPHY_CONFIG="" requis pour uphy0-config-6). L'alignement Kernel-DT par contrôleur n'est pas fait ici — après que le commit ODMDATA soit intégré, cette skill dispatch vers les skills par contrôleur (/jetson-customize-pcie, /jetson-customize-mgbe, /jetson-customize-usb), dont chacun doit comparer l'allocation choisie contre le nœud de référence du kernel DTB nœud par nœud et émettre un fragment overlay uniquement quand la valeur K-stock diffère de l'allocation choisie. La découverte est agentic : options, voies et contrôleurs proviennent du Guide d'adaptation, du schéma du carrier, et du Module / SoC TRM au moment de l'exécution — jamais en dur. Chaque étape visible par l'utilisateur rend ses données sous forme de tableau markdown, et le résumé final inclut un tableau de résumé des modifications.

Prérequis

• Profil de plateforme cible actif avec reference_devkit: et custom_carrier:.
• <source.root_path>/Linux_for_Tegra/.git initialisé (/jetson-init-source).
• Fork de conf du carrier présent (/jetson-derive-carrier).
• Guide d'adaptation accessible via documents.adaptation_guide -> documents.bsp_developer_guide -> web fetch -> fallback de prompt Step-1.
• Quand custom_carrier: est présent, documents.custom_carrier_schematic ET documents.custom_carrier_pinmux_xls sont REQUIS. La skill refuse de s'exécuter si l'un d'eux manque — les décisions de routage pour le carrier personnalisé ne peuvent pas être devinées. Les profils reference-devkit uniquement (sans bloc custom_carrier:) ne les requièrent pas.

Aperçu

UPHY (unified PHY) est le pool PHY haut débit partagé sur Tegra264 (Thor) et Tegra234 (Orin). L'allocation de voies est sélectionnée par les tokens ODMDATA (uphy0-config-N, Thor aussi uphy1-config-N) parsés au moment du flash par tegraflash_impl_t264.py::tegraflash_update_bpmp_dtb() et écrits dans /uphy/uphy{0,1}-config du BPMP DTB.

La sortie est un unique commit ODMDATA atomique dans <source.root_path>/Linux_for_Tegra/ contenant le ou les token(s) uphyX-config-N choisi(s), le clear UPHY_CONFIG="" (pour uphy0-config-6), ET chaque token ODMDATA par contrôleur dérivé de l'allocation choisie (pcie@N_status=*, mgbeN-speed-*, tokens USB SS par port). Les sub-skills (/jetson-customize-pcie, /jetson-customize-mgbe, /jetson-customize-usb) possèdent uniquement les fragments overlay du kernel-DT — elles NE DOIVENT PAS toucher ODMDATA. Tous les commits suivent le pattern batched pristine + customization dans ../../context/bsp-customization-workflow.md. Le BSP upstream à <bsp_image.root_path>/ n'est jamais édité.

Quand invoquer

• L'utilisateur dit « configurer UPHY », « allocation de voies uphy », « fixer uphy0-config-N », « changer la vitesse MGBE », ou demande de remapper PCIe / MGBE / USB3 / UFS sur un carrier personnalisé.
• Un contrôleur alimenté par UPHY n'énumère pas après le flash, OU le démarrage froid meurt en BL31 SError / BPMP firmware is not ready.
• Une skill en aval signale une faute FMON ou une incompatibilité de voies BPMP-DTB.

Procédure (résumé)

Huit étapes ; détails complets dans references/procedure.md.

1. Résoudre la cible + docs. Refuser sans profil actif, carrier personnalisé, git de l'arborescence source, ou conf du carrier forké. Résoudre le Guide d'adaptation / schéma / Module Design Guide / SoC TRM.

2. Localiser « Configure the UPHY Lane » dans le Guide d'adaptation (PDF / miroir HTML / WebFetch). Vérifier le Module Design Guide + SoC TRM.

3. Recouper avec le schéma du carrier. Citer les noms de nets UPHY (MGBE2_TX_P/N, PEX5_LN0+-, etc.). Zéro net correspondant = non routé.

4. Énumérer les options UPHY correspondantes. Afficher tous les index uphy0-config-N documentés (et Thor uphy1-config-N).

5. Demander à l'utilisateur quelle config (HARD GATE). Imprimer les tableaux d'abord, puis AskUserQuestion — un par surface UPHY, plus confirmation de routage du carrier si une voie allouée est non routée. Persister les réponses dans le sidecar JSON (references/run-state-sidecar.md).

6. Éditer le fork de conf flash du carrier (commit ODMDATA atomique). Cette skill possède chaque token ODMDATA pour l'exécution. Une ligne ODMDATA="...", un commit, tous les tokens. Les sub-skills NE DOIVENT PAS toucher ODMDATA.

   Décompiler le BPMP DTB à <bsp_image.root_path>/Linux_for_Tegra/bootloader/generic/<BPFDTB_FILE> (BPFDTB_FILE depuis la conf du carrier) pour snapshotter l'état stock, puis émettre les tokens dans cet ordre :

   a. Tokens de surface UPHY — chaque uphyX-config-N choisi (Thor : les deux surfaces, même si l'une égale la valeur par défaut du guide). Ordre uphy0 puis uphy1 ; séparateur ,. b. Tokens par contrôleur — un par ligne dont l'état du plan diffère du stock BPMP. Les lignes correspondantes n'obtiennent pas de token (les tokens redondants peuvent supprimer la ligne entière).

   • PCIe : pcie@N_status=okay|disabled.
   • MGBE : mgbeN-speed-<rate> sur allocation, mgbeN-speed-del sur désactivation. FMON s'arme sur les horloges propres du contrôleur indépendamment de l'allocation UPHY — del manquant ⇒ boucle de redémarrage BL31 SError. Défaillance post-flash la plus commune sur Thor.
   • USB SS : tokens par port quand la grammaire SoC les expose. c. Clear UPHY_CONFIG="" quand uphy0-config-6 est sélectionné (clear du pinmux BCT per Guide d'adaptation).

7. Construire la table d'allocation par contrôleur et dispatcher. Dériver une ligne par contrôleur alimenté par UPHY (PCIe / MGBE / USB SS / UFS) avec {class, instance, allocated?, BPMP-stock, K-stock, routed?, Desired K state}. Cette table pilote à la fois (a) les tokens ODMDATA de l'étape 6 et (b) les fragments overlay des sub-skills — la construire avant de commiter l'étape 6.

   Ensuite invoquer /jetson-customize-pcie, /jetson-customize-mgbe, et /jetson-customize-usb pour les fragments overlay du kernel-DT uniquement (pas d'édits ODMDATA — l'étape 6 possède la ligne). Chaque sub-skill relit K-stock depuis <bsp_image.root_path>/Linux_for_Tegra/kernel/dtb/tegra<soc>-*-nv.dtb et omet l'émission quand K-stock correspond à Desired K state. La gestion UFS reste inline ici (pas de sub-skill UFS).

   Invoquer les trois chaque fois que leur classe de contrôleur est présente sur ce SoC (par ex. sauter MGBE sur Orin). Demander à l'opérateur d'abord ; sur yes, exécuter la sub-skill inline.

8. Résumé + chaîne next-step. Titre, ventilation, table des choix (surface UPHY | config choisie | résumé des voies | clear UPHY_CONFIG), table de résumé des modifications (fichier | repo | SHA du commit | résumé d'une ligne couvrant le commit de cette skill + chaque commit de sub-skill dispatchée), puis pilotter la chaîne en aval (plus d'I/O ? construire et promouvoir ? flasher ? valider ?) via les prompts AskUserQuestion séquentiels per references/procedure.md étape 8. Ne jamais substituer une ligne « Next step: … » imprimée pour les prompts.

Limitations

• Ne supporte que les surfaces UPHY Tegra234 (Orin) et Tegra264 (Thor).
• N'édite pas le pinmux, les propriétés DT PCIe uniquement absentes du BPMP DTB (num-lanes, pcie-mode), ou les fichiers BSP upstream.
• Ne flashe pas, ne construit pas, ne promeut pas — chaîner dans /jetson-build-source et les skills en aval.
• Les tables d'options en dur sont interdites ; si aucune source du Guide d'adaptation ne résout, la skill refuse plutôt que deviner.
• Non table-driven entre les releases : chaque exécution relit le Guide pour la version BSP active.

Dépannage

• Boucle de redémarrage au démarrage froid / BL31 plat_setup.c:726 / BPMP firmware is not ready après uphy0-config-6 : une ligne ^UPHY_CONFIG= ultérieure dans la conf du carrier a réécrasé le clear. La commenter (voir references/procedure.md étape 6).
• wait-for-device failed au flash, BPMP DTB inchangé : un token ODMDATA avait la mauvaise forme (par ex. mgbe0-speed-0). Un mauvais token supprime la ligne entière ODMDATA="...". Inspecter la grammaire dans references/procedure.md.
• Boucle de redémarrage BL31 SError après désactivation d'un MGBE : mgbeN-speed-del manquant. FMON s'arme sur les horloges propres du contrôleur indépendamment de l'allocation UPHY.
• Le contrôleur nouvellement routé n'énumère pas : le kernel DTB stock avait status="disabled". L'overlay doit émettre status="okay" (ligne de matrice 4 dans references/procedure.md).
• Delta pinmap=0 mais la carte se comporte mal quand même : les paires différentielles UPHY sont absentes du pinmux .xlsm. Piloter les décisions sur les noms de nets du schéma, pas la pinmap.
• Fragments pcie@<addr> dupliqués : une autre skill (jetson-customize-pcie) possède déjà ce nœud. Scoper cette skill à MGBE / UFS / USB3 SS / PCIe-status-only et citer l'autre overlay.

Références

• references/procedure.md — procédure complète à huit étapes.
• references/gotchas.md — pièges transversaux.
• references/run-state-sidecar.md — schéma sidecar JSON + idempotence.
• ../../references/platform_template.yaml — schéma documents:.
• ../../context/bsp-customization-workflow.md — protocole d'édition d'overlay.
• ../../references/bsp-customization-kernel-dtb.md — protocole filename / append d'overlay composite.
• ../jetson-derive-carrier/SKILL.md — produit la conf que cette skill édite.
• ../jetson-init-source/SKILL.md — produit les deux repos git dans lesquels cette skill commite.
• ../jetson-generate-kb/SKILL.md — KB consulté pour la famille de puces + emplacements de fichiers.