Personnaliser MGBE / 25G QSFP

Aperçu

Thor T264 expose mgbe0..mgbe3. Sur un carrier personnalisé, la cage QSFP 25G (ou le chemin fiber 10G / 1G) est câblée à l'un d'eux via SerDes — avec ou sans PHY MDIO externe devant la cage. Cette skill génère l'overlay kernel-DT qui associe l'allocation BPMP avec le status="okay" côté kernel + le câblage PHY sur &mgbeN.

Hors du périmètre :

• Allocation des voies UPHY — gérée par /jetson-customize-uphy. Refuser si le uphy1-config-N choisi n'alloue pas le MGBE cible.
• Tous les tokens ODMDATA (mgbeN-speed-*, sous-nœud mgbeN_status=*) — gérés par /jetson-customize-uphy dans son commit ODMDATA atomique unique. Cette skill NE DOIT PAS toucher ODMDATA=.

La sortie est un commit vers l'overlay personnalisé composite .dts dans le repo matériel bsp_sources/. /jetson-build-source compile le composite en .dtbo et possède son Makefile + l'enregistrement flash-conf.

Quand invoquer

• L'utilisateur dit « activer 25G », « configurer QSFP », « définir le mode PHY MGBE », « câbler MGBE à QSFP », ou demande d'activer un chemin fiber 10G / 1G.
• Le démarrage à froid réussit mais ip link show mgbe<N> rapporte state DOWN ou NO-CARRIER sur le contrôleur configuré, OU le contrôleur n'apparaît jamais.
• jetson-customize-uphy a été exécuté avec uphy1-config-8 (ou une autre config allouant MGBE) et vous devez maintenant activer le côté par contrôleur.

Prérequis :

• Profil actif sélectionné avec les blocs reference_devkit: (Thor) + custom_carrier:.
• <source.root_path>/Linux_for_Tegra/.git existe (/jetson-init-source).
• /jetson-derive-carrier a été exécuté — le fork flash-conf du carrier est dans le tracker overlay.
• /jetson-customize-uphy a choisi une config UPHY qui alloue les voies du contrôleur MGBE cible (uphy1-config-8 sur Thor pour MGBE0..3 25G).
• Docs source-of-truth enregistrés ou fournis à l'invite : Adaptation Guide, Module Design Guide, SoC TRM.
• Quand custom_carrier: est présent, BOTH documents.custom_carrier_schematic ET documents.custom_carrier_pinmux_xls sont OBLIGATOIRES. Refuser l'exécution si l'un manque — le routage MGBE sur un carrier personnalisé ne peut pas être deviné. Les profils reference-devkit uniquement ignorent cette vérification.
• dtc sur PATH.

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 + documents. Valider le profil actif, custom_carrier, tracker overlay ; localiser le chapitre Adaptation Guide pertinent et la pinmap.
2. Boucle de questions par contrôleur. AskUserQuestion dirigée par questions.json (controller, phy_mode, attach kind, bus/addr I²C, GPIO reset, compatible_list).
3. Dériver max-speed à partir de phy_mode. Décompiler la DTB BPMP pour choisir la grammaire du sous-nœud vs token top-level ; citer l'inspection dans les notes.
4. Vérifier les broches HSIO + auto-correction. Exécuter pin_verifier.py pour MDC/MDIO/RESET/INT ; mettre en surface les non-correspondances et router vers /jetson-customize-pinmux.
5. (pas d'édits ODMDATA.) Les tokens ODMDATA MGBE sont émis par /jetson-customize-uphy. L'étape 5 enregistre uniquement l'inspection du token-form de la DTB BPMP (sous-nœud vs top-level) dans notes[] pour audit.
6. Ajouter les fragments composite-overlay. Écrire un fragment par contrôleur dans l'overlay personnalisé composite .dts ; respecter le contrat du marqueur /* custom-bsp: mgbe:mgbe... */ ; exécuter le pré-vol cpp/dtc/fdtoverlay.
7. (Réservé.) Ordre des skills sœurs / validation cross-cutting.
8. Sidecar run-state + résumé + chaîne d'étapes suivantes. Écrire <profile-stem>.jetson-customize-mgbe.json et émettre le résumé sur une ligne + tableau, puis conduire la chaîne en aval via des prompts AskUserQuestion séquentiels par references/procedure.md Étape 8. Ne jamais substituer une ligne « Étape suivante : … » imprimée aux prompts.

Pièges

• La DTB BPMP Thor stock n'a pas de sous-arborescence /mgbe/mgbe@N — seulement mgbe<N>-speed sous /uphy. Le token de sous-nœud mgbe<N>_status=disabled est silencieusement rejeté sur ces versions ; la ligne ODMDATA entière est alors supprimée au flash. Toujours décompiler la DTB BPMP (Étape 3) avant d'émettre ; utiliser la forme tiretée top-level (mgbe<N>-speed-del pour supprimer, mgbe<N>-speed-25G pour définir) quand le sous-nœud n'est pas là. Même surface d'échec de forme invalide que jetson-customize-uphy.
• L'enfant mdio a besoin de BOTH #address-cells = <1> ET #size-cells = <0> quand phy_attach_kind=="phy". Manquer l'un ou l'autre → kernel rejette la propriété reg de phy@<addr> au probe ; MGBE ne s'active jamais.
• Le compatible root overlay doit intersecter le compatible live DT. Le plugin-manager UEFI filtre par correspondance compatible. Un overlay non-correspondant est silencieusement ignoré — le flash réussit, MGBE reste désactivé, pas d'erreur dans dmesg. Toujours vérifier contre /proc/device-tree/compatible sur un DUT reference démarré.
• L'ordre OVERLAY_DTB_FILE est le problème de jetson-build-source, pas celui de cette skill. Cette skill ne touche jamais au carrier flash conf. L'overlay personnalisé composite est enregistré (par /jetson-build-source Étape 5.0a) APRÈS la plateforme *-dynamic.dtbo, ce qui est l'ordre correct. Si vous vous trouvez à ajouter OVERLAY_DTB_FILE+= dans cette skill, vous dupliquez la propriété — arrêtez et laissez la skill de construction le faire.
• L'allocation des voies UPHY est le travail de jetson-customize-uphy. Si le uphy1-config-N choisi n'alloue pas les voies pour le contrôleur MGBE cible, BL31 SError (fmon_update_config: detected fault 0x80) au démarrage froid. Toujours exécuter /jetson-customize-uphy en premier ; citer le uphy1-config-N choisi dans le notes[] du résumé d'exécution de cette skill.
• Ne pas désactiver un contrôleur stock-okay via ODMDATA seul. Même règle que jetson-customize-uphy : mgbe<N>_status=disabled pour un contrôleur déjà désactivé dans la DTB BPMP est un no-op que le parseur peut traiter comme ambigu → supprime le reste de la ligne ODMDATA. Désactiver via l'overlay kernel-DT (status="disabled") uniquement.
• Ne pas toucher au BSP upstream à <bsp_image.root_path>. Tous les édits atterrissent dans le tracker overlay / le mono-repo bsp_sources sous le motif de commit pristine + customization.
• Le sidecar JSON est un état structuré, pas une autorité. Même avertissement que jetson-customize-uphy : ODMDATA + overlay .dts + deux commits git sont les sorties orientées appareil ; le sidecar est pour l'outillage et l'idempotence uniquement.

Références

• questions.json — schéma prompt Q-1..Q-8 consommé par l'Étape 2.
• ../../scripts/pin_verifier.py — vérificateur de broches HSIO partagé (Étape 4).
• ../../references/platform_template.yaml — bloc documents: consommé par l'Étape 1.
• ../../context/bsp-customization-workflow.md — protocole d'édition overlay (commit pristine + customization par batch).
• ../jetson-customize-uphy/SKILL.md — skill sœur qui possède l'allocation des voies UPHY. Doit s'exécuter avant cette skill pour définir uphy1-config-N pour les configurations allouées MGBE.
• ../jetson-customize-pinmux/SKILL.md — skill sœur invoquée par l'Étape 4 (avec confirmation de l'opérateur) pour corriger les non-correspondances SFIO de broches.
• ../jetson-derive-carrier/SKILL.md — doit s'exécuter en premier ; produit le fork flash-conf du carrier édité à l'Étape 5 et l'overlay de base du carrier que cette skill ordonne après.
• ../jetson-init-source/SKILL.md — produit le tracker overlay + le repo bsp_sources dans lequel cette skill commite.