Flasher l'image BSP

Objectif

Envoyer une bsp_image promue vers une DUT Jetson en exécutant la chaîne d'outils de flashage NVIDIA (flash.sh ou l4t_initrd_flash.sh) depuis le répertoire Linux_for_Tegra/ du dépôt. La DUT doit être en mode RCM (recovery) au moment du flashage. C'est l'étape de flashage de la chaîne de déploiement du BSP overlay (/jetson-promote-image → /jetson-flash-image) ; voir le workflow du BSP overlay à ../../context/bsp-customization-workflow.md.

Principe de conception. Quatre invariants gouvernent cette compétence ; chacun est entièrement expliqué dans l'étape Instructions qui en est propriétaire.

• Les variables de flashage côté hôte (<board>, <boot-dev>, outil de flux, .conf par carte, boardctl) sont résolues à partir du profil actif ou du BSP du dépôt.
• Les chemins d'artefacts (DTB_FILE, BPFDTB_FILE, XML de partition, BCT, entraînement DRAM) sont résolus à l'intérieur de flash.sh / l4t_initrd_flash.sh au moment du flashage, à partir de board_sku / board_FAB lus depuis l'EEPROM de la DUT.
• L'EEPROM de la DUT fait autorité ; le profil est une prédiction au moment de la création réconciliée par la vérification préalable. Les valeurs EEPROM vides sont valides, jamais des déclencheurs de refus.
• L'utilisateur confirme explicitement une résolution affichée avant de flasher.

Hors du périmètre : personnalisation du BSP (utilisez les compétences /jetson-customize-*), promotion du suivi overlay en bsp_image (utilisez /jetson-promote-image), et production du conf de flashage d'un carrier personnalisé (utilisez /jetson-derive-carrier).

Prérequis

• Profil de plateforme cible actif résolu selon ../../context/target-platform-contract.md avec un bloc bsp_image: rempli. Refusez et acheminez vers /jetson-init-image s'il manque.
• <bsp_image.root_path>/Linux_for_Tegra/ existe sur l'hôte et a été traité par apply_binaries.sh (acheminez vers /jetson-init-image sinon).
• Un .conf de flashage par carte résolvable via la règle de précédence du bloc actif (custom_carrier.flash_config → reference_devkit.flash_config). Refusez et acheminez vers /jetson-derive-carrier ou /jetson-init-image s'il manque.
• Pour l'étape précédente overlay → image : /jetson-promote-image a déjà été exécuté (ou re-flashage autonome sans modifications de promotion depuis le dernier flashage).
• Une DUT câblée à l'hôte qui peut être placée en mode RCM soit via boardctl du dépôt, soit par boutons de recovery + reset manuels.

Quand invoquer

• Après que /jetson-promote-image ait mis à jour bsp_image pour porter les personnalisations souhaitées.
• Re-flashage autonome sans modifications de promotion depuis le dernier flashage.
• La DUT doit être en mode RCM avant invocation.

Instructions

Résoudre la cible et bsp_image

Résolvez le profil actif selon ../../context/target-platform-contract.md. Refusez si bsp_image: manque ou si <bsp_image.root_path>/Linux_for_Tegra/ n'existe pas (acheminez l'utilisateur vers /jetson-init-image).

Résoudre le chemin du conf de flashage

Choisissez le .conf par carte en utilisant la règle de précédence du bloc actif depuis target-platform-contract.md : custom_carrier.flash_config quand présent, sinon reference_devkit.flash_config. Vérifiez que le fichier choisi existe sous <bsp_image.root_path>/Linux_for_Tegra/. Refusez s'il manque — acheminez l'utilisateur vers /jetson-derive-carrier (carrier personnalisé) ou /jetson-promote-image / /jetson-init-image (reference devkit).

Liez <board> comme le nom de base du .conf résolu sans le suffixe .conf (par exemple jetson-agx-thor-devkit.conf → <board>=jetson-agx-thor-devkit). La forme de la commande de l'étape "Invoquer le flashage" consomme cette liaison directement.

Pas d'aperçu de dispatch à ce stade. La résolution d'artefacts (DTB_FILE, BPFDTB_FILE, XML de partition, BCT MB1, tables d'entraînement DRAM) se produit à l'intérieur de flash.sh / l4t_initrd_flash.sh pendant la génération d'image, en utilisant board_sku et board_FAB lus depuis l'EEPROM de la DUT en mode recovery — pas les valeurs saisies du profil. Le profil est une prédiction au moment de la création ; l'EEPROM de la DUT est faisant autorité au moment du flashage. La vérification croisée EEPROM de l'étape "Vérifications préalables" lit l'EEPROM et refuse le flashage sur désaccord profil / EEPROM, donc passer la vérification préalable est ce qui garantit que le dispatch au moment du flashage sélectionnera les artefacts attendus par le profil.

Pour les analyses statiques en dehors du flux de flashage qui ont besoin de chemins d'artefacts prédits (génération KB, compétences customize-* localisant des fichiers à éditer), voir l'extrait autonome dans dispatch du conf par carte — cet extrait est valide pour la résolution côté BSP mais pas comme aperçu au moment du flashage.

Sélectionner <boot-dev> et le flux de flashage

<boot-dev> est résolu délibérément, jamais supposé. Ordre des sources :

1. Si le profil actif enregistre le dispositif de démarrage, utilisez-le.
2. Sinon, invitez l'utilisateur avec les choix que le conf par carte supporte réellement (internal, external, nvme0n1p1, mmcblk0p1, etc., selon la famille de puce et la variante du conf).

Choisissez l'outil de flux dans la matrice ci-dessous :

Le flashage en masse et les réexécutions --flash-only utilisent la même sélection d'outil mais ajoutent leurs drapeaux respectifs.

Placer la DUT en mode recovery

Placez l'appareil en recovery via boardctl du dépôt (préféré) ou en appuyant manuellement sur le bouton de recovery suivi du bouton de reset.

La procédure complète — où trouver boardctl sous Linux_for_Tegra/, comment énumérer les cibles -t et en choisir une (recommandez topo), l'exact verbe recovery à utiliser, et le repli manuel — se trouve dans references/recovery-mode-boardctl.md.

Liez le chemin binaire résolu comme <boardctl> pour le reste de cette compétence. Ne substituez jamais un boardctl de $PATH, n'inventez jamais de nom de cible absent de <boardctl> -h. La vérification de récupération DUT de l'étape "Vérifications préalables" couvre — pour les deux chemins — que la DUT a réellement atteint le mode RCM.

Vérifications préalables

En effectuant les vérifications préalables suivantes dans l'ordre spécifié, et ne sautez jamais chaque vérification. Les vérifications côté hôte s'exécutent d'abord (échouez tôt avant de demander à l'utilisateur de basculer recovery), puis les vérifications côté DUT une fois que l'utilisateur a placé l'appareil en mode RCM. Les vérifications dépendant d'EEPROM viennent après la détection RCM, puisque le canal recovery est ce qui rend la lecture possible.

5.1 Préparation de bsp_image (côté hôte).

• Le conf par carte existe à <bsp_image.root_path>/Linux_for_Tegra/<flash_config>.
• Sous-arbres d'artefacts remplis : kernel/dtb/, bootloader/, bootloader/generic/BCT/, rootfs/.
• apply_binaries.sh a été exécuté — vérifiez rootfs/etc/nv_tegra_release et les fichiers de paquet marqueur nvidia-l4t-bsp-* de la puce.
• Les noms de fichier DTB_FILE / BPFDTB_FILE / BCT exactement résolus ne sont intentionnellement pas vérifiés ici — ceux-ci sont sélectionnés à partir d'EEPROM au moment du flashage (voir l'étape "Résoudre le chemin du conf de flashage").
• Invariant de miroir kernel Image. Quand <LFT_DST>/kernel/Image et <LFT_DST>/rootfs/boot/Image existent tous les deux, ils doivent être byte-identiques (cmp -s) ; la dérive signifie que l'étape Mirror de /jetson-promote-image a été sautée — acheminez en arrière. Présence d'Initramfs. l4t_initrd_flash.sh nécessite <LFT_DST>/bootloader/l4t_initrd.img et <LFT_DST>/rootfs/boot/initrd ; absent → acheminez vers /jetson-init-image. (La fraîcheur vs. rootfs/lib/modules/<ver>/ n'est pas vérifiée ici — propriétaire de l'étape Refresh initramfs de /jetson-promote-image.)

5.2 DUT en mode RCM.

• Vérifie le résultat de l'étape "Placer la DUT en mode recovery" (soit l'invocation <boardctl> -t <target> sélectionnée par l'utilisateur, soit le repli manuel).

• lsusb -d 0955: doit rapporter au moins un appareil correspondant à la paire VID:PID de recovery de la famille de puces active :

  Famille de puces	Recovery VID:PID
  T23x / Orin	0955:7X23 (X est n'importe quel chiffre hexadécimal — variante de module)
  T26x / Thor	0955:7026

  Pour T23x, correspondez sur le 23 final (par exemple lsusb -d 0955: | grep -E ' 0955:7.23 ') ; une vérification littérale 0955:7023 manquera les variantes T23x valides.

• Absent → si l'étape "Placer la DUT en mode recovery" a utilisé boardctl, exposez sa sortie et refusez ; si l'étape "Placer la DUT en mode recovery" a utilisé le chemin manuel, re-invitez l'utilisateur à confirmer le jumper / bouton et à faire un power-cycle.

• C'est la porte pour tout ce qui suit. La phase de génération d'image de flash.sh lit l'EEPROM sur le même canal recovery ; un appareil qui n'est pas en RCM ici échouera aussi là.

5.3 Vérification croisée EEPROM vs. profil actif.

Lisez board_sku et board_FAB (et toute entrée de dispatch supplémentaire que la famille de puces active utilise) depuis l'EEPROM de la DUT en mode recovery en utilisant sudo ./nvautoflash.sh --print_boardid depuis <bsp_image.root_path>/Linux_for_Tegra/. La référence complète — exemple de sortie, mappage étiquette-à-entrée-dispatch, sémantique valeur-vide, et table de réconciliation EEPROM-vs-profil — se trouve dans references/eeprom-cross-check.md.

Le déclencheur de refus est un vrai désaccord non-vide, jamais une valeur manquante. Les valeurs EEPROM vides sont valides et ne sont pas un déclencheur de refus. La vérification croisée est la défense principale contre la classe de défaillances wrong-target / wrong-SKU chaque fois que les deux côtés fournissent assez d'information pour être en désaccord.

5.4 Préparation d'utilisateur par défaut (côté hôte, interactif).

Une bsp_image fraîchement appliquée n'a pas d'utilisateur Linux pré-préparé. Détectez via <bsp_image.root_path>/Linux_for_Tegra/rootfs/home/ et UID ≥ 1000 dans rootfs/etc/passwd. Si aucun, émettez une AskUserQuestion avec quatre options à sélection par clic : ubuntu / ubuntu, nvidia / nvidia, custom (sous-invite pour nom d'utilisateur + mot de passe), ou skip (assistant OEM au premier démarrage). Les sélections autres que skip exécutent l4t_create_default_user.sh --autologin --accept-license. L'invocation complète + justification dans references/default-user-staging.md.

Enregistrez la résolution afin que l'étape "Confirmer la résolution" puisse l'afficher. Cette étape n'est pas une porte de refus — c'est un point d'interaction utilisateur.

Confirmer la résolution

Affichez le plan résolu et exigez une acceptation explicite. Le format est la résolution, pas la commande shell — l'utilisateur approuve ce qui sera flashé, pas la chaîne qui sera exécutée :

Cible :         <reference_devkit.name> [+ custom_carrier.name]
Profil :        target-platform/<active>.yaml
bsp_image :     <bsp_image.root_path>/Linux_for_Tegra  (version <X>)
Conf de flashage :  <flash_config>   (chemin vérifié dans l'étape "Résoudre le chemin du conf de flashage")

EEPROM DUT  →   board_sku=<valeur-ou-(vide)>  board_FAB=<valeur-ou-(vide)>
Profil     →    module.sku=<valeur-ou-(any)>    module.revision=<valeur-ou-(any)>
                (réconciliés selon la vérification croisée EEPROM de l'étape "Vérifications préalables")

Dispositif de démarrage :  <boot-dev>
Outil de flux :     flash.sh  |  l4t_initrd_flash.sh
boardctl :          <bsp_image.root_path>/Linux_for_Tegra/tools/board_automation/boardctl
                    (ou le chemin que l'étape "Placer la DUT en mode recovery" a résolu)
Entrée RCM :        <boardctl> -t <target-sélectionné-utilisateur> recovery  |  boutons de recovery + reset manuels
Post-flashage :     <boardctl> -t <target-sélectionné-utilisateur> reset   (T26x / Thor)
                    non requis — l'outil de flashage réinitialise en interne    (T23x / Orin)
Utilisateur par défaut :  <username> (autologin)
                        | déjà préparé dans rootfs (conservé)
                        | aucun — assistant de configuration OEM au premier démarrage

Les chemins d'artefacts (DTB_FILE, BPFDTB_FILE, XML de partition, BCT) ne sont pas affichés — ils sont résolus par flash.sh à partir d'EEPROM au moment du flashage, pas par cette compétence. La vérification croisée EEPROM de l'étape "Vérifications préalables" est ce qui garantit que ces sélections au moment du flashage s'aligneront avec ce que le profil attend.

C'est la porte d'acceptation utilisateur. Refusez de basculer vers un flux "collez cette commande" brut — ce chemin est comment les extraits de doc obsolètes, les mauvais tirets et les artefacts de collage de caractères de prompt se retrouvent dans les flashages de production.

Invoquer le flashage

Construisez la commande à partir des variables résolues — n'acceptez jamais une commande littérale de l'utilisateur, de la documentation ou de la mémoire :

cd <bsp_image.root_path>/Linux_for_Tegra
sudo ./<flow-tool> [<drapeaux-résolus>] <board> <boot-dev>

Abandonnez et exposez l'étape échouée à la première sortie non-zéro. Ne réessayez pas automatiquement sur les erreurs USB passagères.

Reset post-flashage (T26x / Thor uniquement)

Les plateformes T26x ne re-démarrent pas automatiquement à partir de l'image fraîchement flashée quand flash.sh / l4t_initrd_flash.sh retourne. Exécutez, en utilisant le <boardctl> résolu dans l'étape "Placer la DUT en mode recovery" et la même cible que l'utilisateur a sélectionnée pour l'entrée RCM :

<boardctl> -t <target-sélectionné-utilisateur> reset

T23x / Orin émet le reset en interne ; sautez cette étape sur Orin. Si l'étape "Placer la DUT en mode recovery" a utilisé le chemin manuel, invitez l'utilisateur à retirer le jumper / bouton de force-recovery et à faire un power-cycle manuellement. Portez cette étape sur la famille de puces résolue depuis le profil actif.

Résumé

Signalez : ligne(s) de commande utilisée(s) (flashage + reset post-flashage s'il s'est exécuté), code de sortie, emplacement du log (s'il a été fusionné). Persistez le plan résolu et le résultat où la validation peut les relire.

Limitations

• La DUT doit être en mode RCM. La génération d'image (lecture EEPROM) et le flashage lui-même utilisent tous deux le canal USB recovery ; not-in-RCM à la porte fait échouer la génération d'image aussi.
• Chemins d'artefacts résolus au moment du flashage. DTB_FILE, BPFDTB_FILE, XML de partition, BCT, entraînement DRAM sont sélectionnés à partir d'EEPROM (board_sku / board_FAB) par flash.sh / l4t_initrd_flash.sh ; cette compétence valide seulement l'échafaudage côté hôte.
• EEPROM fait autorité sur le profil. Le désaccord non-vide réel refuse ; les valeurs EEPROM vides sont valides.
• Pas de contournement de commande brute. Refuse de basculer vers "collez cette commande" fournie par l'utilisateur — ce chemin est comment les extraits de doc obsolètes et les artefacts de collage de caractères de prompt atteignent les flashages de production.
• Pas de réessai automatique sur erreur passagère. Les hoquet USB abandonnent ; re-entrez RCM et re-invoquez.
• T26x nécessite un reset post-flashage explicite. T26x ne redémarre pas automatiquement à partir d'une image fraîchement flashée ; <boardctl> -t <target> reset (ou power-cycle manuel) requis. T23x réinitialise en interne.
• Flashage en masse / --flash-only utilisent la même sélection d'outil + drapeaux respectifs ; la configuration de topologie du flashage en masse est hors du périmètre ici.

Dépannage

Références

• references/recovery-mode-boardctl.md — localiser le boardctl du dépôt, énumérer les cibles, invoquer recovery / reset, repli manuel (détails des étapes "Placer la DUT en mode recovery" / "Reset post-flashage").
• references/eeprom-cross-check.md — exemple de nvautoflash.sh --print_boardid, mappage étiquette-à-entrée-dispatch, table de réconciliation EEPROM-vs-profil (utilisée par l'étape "Vérifications préalables").
• references/default-user-staging.md — invocation l4t_create_default_user.sh + justification des drapeaux (utilisée par l'étape "Vérifications préalables").
• ../../context/target-platform-contract.md — contrat de plateforme cible.
• ../../context/bsp-customization-workflow.md — Protocole d'édition Workspace (cette compétence est l'étape de flashage de Deploy).
• Dispatch du conf par carte — résolution <board>, DTB et BCT depuis le profil actif.
• ../jetson-promote-image/SKILL.md — étape antérieure ; copie overlay → bsp_image.
• ../jetson-derive-carrier/SKILL.md — produit le conf de flashage du carrier personnalisé consommé par l'étape "Résoudre le chemin du conf de flashage".