Personnaliser PCIe (statut par contrôleur / lanes / vitesse)

Vue d'ensemble

PCIe sur Tegra264 (Thor, pcie@C0..C5) et Tegra234 (Orin, pcie@C0..C10) est réparti sur plusieurs contrôleurs qui partagent le pool de lanes UPHY avec USB3 / MGBE / UFS. Le comportement d'exécution de chaque contrôleur est déterminé par deux surfaces, toutes deux obligatoires :

Sauter l'overlay kernel sur une désactivation laisse le kernel tester une PHY non alimentée (timeouts de lien dans dmesg). Sauter le token ODMDATA sur une désactivation laisse BPMP garder la PHY active.

Agentique, non piloté par table — pas de table de contrôleurs, pas de questions.json. Chaque contrôleur, largeur de lane, réceptacle routé sur schéma, et adresse de nœud DT responsable est découverte à l'exécution à partir de la documentation + DTB + pinmap du support.

La sortie est un commit overlay kernel-DT uniquement. Des blocs fragment@N par contrôleur sont ajoutés au .dts d'overlay personnalisé composite selon ../../references/bsp-customization-kernel-dtb.md et validés dans le repo matériel bsp_sources/. /jetson-build-source compile le composite en .dtbo et possède son Makefile + enregistrement flash-conf.

Cette skill NE DOIT PAS éditer ODMDATA="...". Tous les tokens ODMDATA (pcie@N_status=…, pcie@N_max-link-speed, pcie@N_pcie-mode, pcie@N_clk-scheme, pcie-cN-endpoint-enable, plus les tokens surface uphyX-config-N et le clear UPHY_CONFIG="") sont émis par /jetson-customize-uphy dans un commit atomique unique sur le fork flash-conf du support. La table d'allocation que cette skill consomme du sidecar UPHY indique déjà à l'opérateur quels contrôleurs sont okay / disabled / dimensionnés par lane ; cette skill traduit simplement cette table en fragments overlay kernel-DT et vérifie que l'overlay s'accorde avec les ODMDATA déjà validés par customize-uphy (vérification de cohérence à l'étape 8 — le désaccord est signalé, non corrigé silencieusement).

Quand invoquer

• L'utilisateur dit « configurer PCIe », « activer contrôleur PCIe », « définir PCIe num-lanes », « modifier vitesse de lien PCIe », ou demande de basculer un token pcie@N_status.
• Un slot PCIe ou réceptacle M.2 spécifique n'énumère pas après flash, OU le lien s'établit à la mauvaise largeur / vitesse.
• jetson-customize-uphy a tourné et réalloué des lanes entre contrôleurs PCIe (ex. basculé de uphy0-config-7 à uphy0-config-6 en activant PCIe C3) ; le côté par contrôleur doit maintenant être activé.
• jetson-customize-mgbe signale que le chemin QSFP est câblé mais le kernel ne teste pas son compagnon PCIe (rare ; configurations XFI).

Prérequis :

• Profil actif avec blocs reference_devkit: + custom_carrier:.
• <source.root_path>/Linux_for_Tegra/.git existe (/jetson-init-source).
• /jetson-derive-carrier a tourné — fork flash-conf du support est dans le tracker d'overlay.
• /jetson-customize-uphy a tourné — son sidecar JSON à <workspace>/target-platform/<profile-stem>.jetson-customize-uphy.json pilote la décision enable par contrôleur.
• Docs sources de vérité enregistrées ou fournies à l'invite : Adaptation Guide, Module Design Guide, SoC TRM.
• Quand custom_carrier: est présent, les deux documents.custom_carrier_schematic ET documents.custom_carrier_pinmux_xls sont OBLIGATOIRES. Refuser l'exécution si l'un manque — le routage sur un support personnalisé ne peut être deviné. Les profils devkit-only ignorent cette vérification.
• dtc sur PATH.

Procédure (résumé)

La procédure complète étape par étape se trouve dans references/procedure.md. Flux haut niveau :

1. Résoudre la cible active + ouvrir les documents sources de vérité (incl. <carrier-pinmap>, <ref-dtb>, <uphy-state>). Refuser si <uphy-state> manque.
2. Différentiel topologie PCIe — devkit vs support personnalisé — en décompilant <ref-dtb> et grep du schéma pour les étiquettes de net PEX<N>_*.
3. AskUserQuestion (multiSelect) — quels contrôleurs personnaliser.
4. Vérification par contrôleur : pinmap + schéma + pin_verifier.py pour PE<N>_CLKREQ_L, PE<N>_RST_L, PE<N>_WAKE_L optionnel.
5. Dériver auto le plan par contrôleur (enable de <uphy-state>, lanes / speed d'Adaptation Guide, mode verrouillé dur à "rc") → portail de confirmation ou personnalisation obligatoire.
6. Ajouter des blocs fragment@N par contrôleur (marqueur /* custom-bsp: pcie:pcie@<addr> */) au .dts overlay personnalisé composite dans bsp_sources/. Pré-vol dtc + fdtoverlay. Valider via le portail preview du workflow. Ne pas éditer ODMDATA — /jetson-customize-uphy a déjà émis pcie@N_status=…, pcie@N_max-link-speed, pcie@N_pcie-mode, pcie@N_clk-scheme, et pcie-cN-endpoint-enable dans son commit ODMDATA atomique unique. Cette skill traduit seulement le plan par contrôleur en fragments overlay kernel-DT.
7. (Étape repliée dans l'étape 6 — émission overlay uniquement.)
8. Vérifier la cohérence ODMDATA vs overlay. Sur une ligne contradictoire, arrêter et demander à l'utilisateur comment récupérer les deux commits. Ne jamais exécuter git reset --hard de façon autonome.
9. Écrire le sidecar JSON d'état d'exécution à <workspace>/target-platform/<profile-stem>.jetson-customize-pcie.json + résumé, puis piloter la chaîne d'étapes suivantes en aval via des prompts AskUserQuestion séquentiels par references/procedure.md étape 9. Ne jamais substituer une ligne imprimée « Étape suivante : … » aux prompts.

Limitations

• Mode verrouillé dur à RC. Le mode Endpoint n'est émis que quand l'opérateur passe mode_override="ep" à l'étape 5c.
• enable est dérivé, non demandé. Les contrôleurs alloués UPHY sont mandatoirement okay ; les non alloués sont mandatoirement disabled.
• Aucune édition BSP upstream. La sortie atterrit dans Linux_for_Tegra/ + bsp_sources/ uniquement.
• La fusion d'overlay pré-vol est un test de cohérence, non la build production. /jetson-build-source est responsable.
• L'enregistrement d'overlay flash-conf est hors scope. Possédé par /jetson-build-source étape 5.0a.

Dépannage

• <uphy-state> manque → exécuter /jetson-customize-uphy d'abord.
• Slot n'énumère pas après flash → vérifier dmesg | grep pcie ; re-vérifier que les ODMDATA pcie@<N>_status=okay et le fragment overlay s'accordent (tableau étape 8 dans references/procedure.md).
• Lien s'établit à mauvaise largeur → confirmer que la config UPHY dans <uphy-state> alloue le nombre de lanes attendu ; le num-lanes du fragment kernel doit correspondre.
• Mismatch compatible → corriger la racine composite, non le fragment. Le gestionnaire de plugin UEFI saute silencieusement en cas de mismatch.
• Ligne ODMDATA-vs-overlay contradictoire → demander à l'utilisateur ; ne pas auto-git reset --hard. Voir les pièges.
• Pièges courants — voir references/gotchas.md (verrouillage RC, sourçage d'adresse de nœud, contrôleurs stock-désactivés, handoff intra-fichier avec jetson-customize-uphy).

Références

• references/procedure.md — procédure complète neuf étapes (différentiel topologie, dérivation plan, ajout overlay, vérification croisée ODMDATA, sidecar).
• references/gotchas.md — modes de défaillance + invariants (verrouillage RC, sourçage d'adresse, handoff BPMP).
• ../../scripts/pin_verifier.py — vérificateur de pin HSIO partagé (étape 4).
• ../../references/platform_template.yaml — bloc documents: consommé par l'étape 1.
• ../../context/bsp-customization-workflow.md — protocole d'édition overlay + portail preview de message de commit.
• ../../references/bsp-customization-kernel-dtb.md — nom overlay composite / skeleton / protocole d'ajout.
• ../jetson-customize-uphy/SKILL.md — skill sœur qui possède l'allocation des lanes UPHY ; son sidecar pilote la décision enable par contrôleur.
• ../jetson-customize-pinmux/SKILL.md — skill sœur invoquée par l'étape 4 (avec confirmation opérateur) pour corriger les mismatch SFIO de pin HSIO.
• ../jetson-customize-mgbe/SKILL.md — skill sœur pour contrôleurs MGBE ; partage le motif deux surfaces (ODMDATA + overlay).
• ../jetson-derive-carrier/SKILL.md — doit tourner d'abord ; produit le fork flash-conf du support édité à l'étape 6.
• ../jetson-init-source/SKILL.md — produit le tracker d'overlay + repo bsp_sources dans lequel cette skill valide.