Promouvoir une image BSP

Objectif

Préparer chaque sortie Customize-* et Build dans bsp_image pour /jetson-flash-image. Il s'agit de la phase promote de Deploy — elle copie des fichiers, ne flashe jamais et ne construit jamais.

Prérequis

• Profil target-platform actif avec à la fois source: et bsp_image: résolus (exécutez d'abord /jetson-init-source et /jetson-init-image).
• <source.root_path>/Linux_for_Tegra/ initialisé comme un repo git (suivi overlay) avec un répertoire de travail propre.
• <bsp_image.root_path>/Linux_for_Tegra/ extrait d'une tarball BSP + apply_binaries.sh déjà exécuté.
• git, yq, cmp, et sudo (pour les destinations rootfs/*) sur l'hôte.
• <source.root_path>/.build-manifest.yaml + .build-state.yaml provenant de /jetson-build-source (requis quand les repos kernel-side ont des commits customize-*).

Aperçu

Il s'agit de la phase promote de Deploy — voir ../../context/bsp-customization-workflow.md pour la vue du pipeline. Les deux canaux que cette compétence emprunte sont :

La compétence calcule l'union des fichiers à copier et écrit chacun dans <bsp_image.root_path>/Linux_for_Tegra/ avec une logique de saut intelligente sensible aux différences. Quand la phase de copie touche le kernel Image ou quelque chose sous rootfs/lib/modules/, elle reconstruit aussi l'initramfs via tools/l4t_update_initrd.sh de NVIDIA afin que le kernel promu récemment + les modules soient livrés dans l'initrd que le bootloader charge réellement. Après son retour, bsp_image porte chaque sortie Customize et Build. La compétence ne flashe pas et ne modifie pas le workspace.

Quand l'invoquer

• Première phase de la chaîne Deploy typique jetson-promote-image → jetson-flash-image → jetson-validate-image.
• En autonome, quand l'utilisateur veut que bsp_image soit mis à jour mais n'est pas prêt à flasher (par exemple pour inspecter les fichiers résolus, exécuter un build hors-bande qui lit bsp_image, ou confier bsp_image à un hôte de flash séparé).

Procédure

Résoudre la cible active + chemins

Résolvez le profil actif selon le contrat dans ../../context/target-platform-contract.md.

Refusez et routez dans ces cas :

Résolvez les chemins :

• <workspace> = parent du répertoire target-platform/ du profil actif (découvert au chargement).
• <bsp_image.root_path> depuis bsp_image.root_path: s'il est présent, sinon <workspace>/Image.
• <source.root_path> depuis source.root_path: s'il est présent, sinon <workspace>/Source.

Liez des variables shell pour le reste de la procédure :

LFT_SRC="<source.root_path>/Linux_for_Tegra"   # overlay tracker
LFT_DST="<bsp_image.root_path>/Linux_for_Tegra"
MANIFEST="<source.root_path>/.build-manifest.yaml"   # build outputs

Valider les deux canaux

La compétence a besoin qu'au moins un canal soit peuplé. Refusez si le suivi overlay a des changements non commitées (status --porcelain non vide), si $MANIFEST existe mais ne s'analyse pas en YAML, ou si les deux canaux sont vides. Enregistre OVERLAY_HAS_COMMITS / OVERLAY_HEAD et MANIFEST_PRESENT pour les étapes ultérieures.

Voir references/copy-pass-snippets.md pour le snippet shell et les messages de refus.

Vérifier la fraîcheur de build-source

Refusez si .build-state.yaml montre n'importe quel repo kernel-side dans Source/bsp_sources/ modifié depuis le dernier /jetson-build-source — sinon la phase de copie livrerait silencieusement des artifacts périmés. Règles de détection + snippet shell dans references/build-source-freshness-gate.md. Enregistre BUILD_FRESH=1.

Vérification de collision avant promotion (overlay uniquement)

Quand l'overlay suit un remote, refusez si l'upstream a des commits non encore tirés. Contournez gracieusement quand aucun remote n'est configuré (le suivi vide par défaut git init provenant de jetson-init-source). Le canal manifeste n'a pas de concept de remote git — cette vérification concerne l'overlay uniquement. Enregistre COLLISION_CHECK pour le Résumé.

Voir references/copy-pass-snippets.md pour le snippet shell.

Énumérer les sources (les deux canaux)

Canal A — overlay : git ls-files contre $LFT_SRC est la source de vérité (transparent aux montages symlink quand source.repos.Linux_for_Tegra a été remplacé, exclut les fichiers non suivis / .gitignores). Chaque entrée mappe src = $LFT_SRC/<rel> → dst = $LFT_DST/<rel>.

Canal B — manifeste : analyser artifacts[].{src,dst} depuis $MANIFEST. Refusez si un quelconque src manque sur le disque (build interrompu, ou manifeste périmé — réexécutez /jetson-build-source). Le schéma du manifeste est écrit par jetson-build-source v0.2.0.

Voir references/copy-pass-snippets.md pour les deux snippets shell et le schéma YAML du manifeste.

Copie sensible aux différences dans bsp_image

Itérez l'union des fichiers overlay et des entrées manifeste. Pour chaque dst : s'il est identique en octets, sautez ; sinon cp -p (avec sudo pour les destinations rootfs/*, où le sample rootfs a été extrait en tant que root). Marquez INITRD_DIRTY=1 à chaque écriture rootfs/lib/modules/* ou kernel/Image — l'étape « Rafraîchir initramfs » se gère sur ce drapeau. Les comptages / FIRST / LAST sont enregistrés pour le Résumé.

Arrêt rapide : si un quelconque cp échoue, exposez le chemin échoué et arrêtez. bsp_image peut être laissé partiellement mis à jour — relancer après correction du problème reprend via le saut sensible aux différences. Ordre des canaux : overlay d'abord, puis manifeste : sur une collision dst le manifeste l'emporte (l'artifact fraîchement construit bat la copie overlay plus ancienne).

Voir references/copy-pass-snippets.md pour la fonction copy_one() et les deux boucles motrices.

Mettre en miroir le kernel Image dans rootfs (quand le kernel change)

Le kernel Image vit dans deux chemins à l'intérieur de bsp_image : <LFT_DST>/kernel/Image (lu par l'outil de flash) et <LFT_DST>/rootfs/boot/Image (la copie côté rootfs, visible comme /boot/Image de l'intérieur du chroot rootfs que l'outil de refresh exécutera). Le manifeste de build ne porte que la destination kernel/Image, donc cette étape met en miroir kernel/Image → rootfs/boot/Image (sensible aux différences, no-op quand déjà synchronisé) pour que l'outil de refresh chrooté résolve le kernel contre le binaire promu récemment, pas la copie rootfs périmée. Le miroir règle aussi INITRD_DIRTY=1 afin qu'une promotion kernel uniquement (sans écritures rootfs/lib/modules/*) déclenche toujours le refresh.

Voir references/kernel-image-and-initramfs.md pour le snippet shell, le mode défaillance que ceci prévient, et la corner case INITRD_DIRTY.

Rafraîchir initramfs (quand le kernel ou les modules changent)

Exécutez tools/l4t_update_initrd.sh depuis <LFT_DST>/ quand INITRD_DIRTY=1 (défini par la copie sensible aux différences ou l'étape miroir ci-dessus). L'outil chroote dans rootfs/, exécute nv-update-initrd de NVIDIA, et écrit à la fois <LFT_DST>/bootloader/l4t_initrd.img (utilisé par l'outil de flash) et <LFT_DST>/rootfs/boot/initrd (/boot/initrd sur la DUT). Idempotent ; ~30 s. Sautez quand INITRD_DIRTY=0 (éditions overlay uniquement). Les contournements côté DUT (update-initramfs -u + cp manuel) sont hors de portée — corrigez l'écart ici pour que le flash livre une image cohérente.

Voir references/kernel-image-and-initramfs.md pour le snippet shell, les chemins de refus, les modes défaillance « module shadowing » et « vermagic skew » que la reconstruction ferme, et pourquoi bootloader/initrd (un fichier différent) est laissé tranquille.

Résumé

Rapportez :

• Portée overlay : overlay HEAD ($OVERLAY_HEAD) ou « (vide) ».
• Portée manifeste : mode=<...>, bsp_version=<...>, rebuilt_at=<...>, N artifacts ou « (absent) ».
• Vérification de collision : $COLLISION_CHECK.
• Comptages :
  • overlay : $COPIED_OVERLAY copiés, $IDENTICAL_OVERLAY identiques
  • manifeste : $COPIED_MANIFEST copiés, $IDENTICAL_MANIFEST identiques
• Miroir du kernel Image : $KIMG_MIRRORED et initramfs : $INITRD_STATUS (copied … / rebuilt quand déclenché par les écritures kernel/Image ou rootfs/lib/modules/* ; skipped … sinon).
• Premiers / derniers chemins copiés (omettez si les deux totaux COPIED sont 0).
• <source.root_path> et <bsp_image.root_path> résolus.
• Étape suivante : /jetson-flash-image (ou /jetson-validate-image si l'utilisateur voulait seulement rafraîchir bsp_image pour inspection / validation statique).

Limitations

• Deux canaux, une destination. bsp_image/Linux_for_Tegra/ est écrit par les deux phases. L'overlay porte les sorties customize- (éditions overlay uniquement comme nvfancontrol.conf) ; le manifeste porte les binaires reconstruits (kernel/OOT/DT). Les deux sont intentionnellement disjoints par construction : les sorties de build ne vont pas dans l'overlay, et les éditions customize- aux fichiers non-build n'entrent pas le manifeste.
• Le manifeste de build est le contrat trace-to-dirty. N'importe quoi dans le manifeste provient d'un repo source modifié (per la politique de trace de l'étape « Write the build manifest » de jetson-build-source). Promouvoir le manifeste est donc sûr : chaque entrée est un artifact porteur de customisation, pas du bruit de divergence toolchain. La compétence ne re-dérive pas la trace — elle fait confiance au manifeste.
• Les entrées du manifeste peuvent survivre à leurs sorties de build. Si l'utilisateur efface Source/.build/ ou les artifacts de build de bsp_sources/ entre jetson-build-source et jetson-promote-image, le manifeste référencera des fichiers manquants. L'étape « Enumerate sources (both channels) » refuse dans ce cas et oriente l'utilisateur vers /jetson-build-source pour rebuilder.
• L'absence de manifeste est fine quand seules les éditions overlay se sont produites. Une customisation purement overlay (p. ex. customize-fan) ne produit aucune sortie de build et n'écrit aucun manifeste — l'étape « Enumerate sources (both channels) » est un no-op, l'étape « Diff-aware copy into bsp_image » promeut seulement les fichiers overlay. La compétence imprime « manifesto : (absent) » dans le résumé et continue.
• Sensible aux différences, idempotent. Relancer sans commits overlay ni changements manifeste depuis la dernière promotion est un no-op (tous les fichiers identiques). Utilisez ceci pour confirmer que bsp_image est synchronisé sans effets secondaires.
• Transparence du montage symlink. Quand source.repos.Linux_for_Tegra a été remplacé dans jetson-init-source, le montage canonique est un symlink dans <source.root_path>/.repos/Linux_for_Tegra/<subdir>. git -C, cp -p, et cmp -s le suivent tous de manière transparente — aucun traitement spécial nécessaire à cette couche. Les chemins src du manifeste sont absolus, donc les symlinks sous bsp_sources/ ne comptent pas pour le canal manifeste.
• sudo est limité aux destinations rootfs/. Les fichiers sous rootfs/ ont été extraits avec sudo tar xpjf par jetson-init-image, donc ils portent la propriété root et les bits de mode spéciaux que la chaîne d'outils de flash relit. sudo cp -p les préserve. Tout le reste (bootloader/, kernel/, kernel/dtb/, tools/, etc.) est possédé par l'utilisateur et ne nécessite pas sudo. Ceci s'applique aux deux canaux.
• Précédence de chevauchement de canal. Si la même dst apparaît dans overlay et manifeste, le manifeste l'emporte (plus tard dans la boucle de l'étape « Diff-aware copy into bsp_image »). C'est la sémantique désirée — les entrées du manifeste sont fraîchement construites, les entrées overlay peuvent être de l'état plus ancien. L'édition manuelle de fichiers binaires dans l'overlay est déconseillée (le travail de Build est de les rebuilder) ; la règle de précédence rend telles erreurs récupérables.
• bsp_image est en lecture seule en dehors de Deploy. Cette compétence est l'unique écrivain dans le flux normal (correspond à l'invariant workflow). Les éditions manuelles de <bsp_image.root_path>/Linux_for_Tegra/ en dehors de Deploy seront silencieusement écrasées lors du prochain run de promote si le même chemin existe dans un quelconque canal ; inversement elles ne seront pas annulées si aucune entrée ne les masque. Les deux comportements sont mauvais pour la trace de diff — n'éditez jamais manuellement en amont.
• La portée est overlay HEAD uniquement (canal A). Les tags nommés / manifestes / plages de commits sont différés (voir ci-dessous). Pour promouvoir un état historique, faites d'abord git -C $LFT_SRC checkout <ref>, puis relancez. Le canal manifeste n'a pas de portée en plage — il reflète ce que le dernier run de jetson-build-source a produit.
• Pas de rollback automatique sur défaillance partielle. Si cp échoue partiellement, bsp_image est laissé dans un état intermédiaire. Corrigez la cause sous-jacente (généralement permissions / disque plein) et relancez — l'étape « Diff-aware copy into bsp_image » reprendra en sautant les fichiers déjà promus.
• Miroir de kernel Image + refresh d'initramfs. Gardienné sur les écritures de phase de copie à kernel/Image ou rootfs/lib/modules/* ; le miroir alimente le chroot du refresh. Les deux sont sensibles aux différences et sautés sur les éditions purement overlay. tools/l4t_update_initrd.sh doit exister dans bsp_image (livré avec apply_binaries.sh) ; un outil manquant refuse et route vers /jetson-init-image. Voir references/kernel-image-and-initramfs.md pour le contrat complet et les modes défaillance.

Dépannage

État de la spécification

Verrouillé pour v0.2.0 :

• Portée à deux canaux — overlay HEAD + manifeste de build, tous deux sensibles aux différences, tous deux copiant dans <bsp_image.root_path>/Linux_for_Tegra/.
• Précédence de chevauchement de canal — le manifeste l'emporte sur collision dst.
• Vérification de collision repo-source — overlay uniquement ; le manifeste n'a pas de concept de remote et les repos source sous bsp_sources/ ne sont pas tirés (leur état a été scellé quand jetson-build-source a écrit le manifeste).
• Atomicité — arrêt rapide, pas de rollback. La copie sensible aux différences rend la reprise naturelle.
• Trace d'audit — stdout uniquement au moment de la promotion. Le log git du suivi overlay est l'enregistrement canonique pour le canal A ; le manifeste lui-même est l'enregistrement canonique pour le canal B.
• Miroir kernel Image + refresh initramfs. Verrouillé en tant qu'étape appairée. Le miroir copie kernel/Image → rootfs/boot/Image quand la phase de copie a touché kernel/Image ; le refresh exécute tools/l4t_update_initrd.sh quand kernel/Image ou un quelconque rootfs/lib/modules/* a été promu, reconstruisant à la fois bootloader/l4t_initrd.img et rootfs/boot/initrd. Inséparable car le refresh chroote dans rootfs/ et résout le kernel via /boot/Image — le miroir doit s'exécuter d'abord. Ferme à la fois les modes défaillance module-shadowing et vermagic-skew ; tous deux sensibles aux différences, tous deux sautés sur les éditions overlay uniquement. Contrat complet dans references/kernel-image-and-initramfs.md.

Toujours différés :

• Portée tag-nommé / plage-commit pour le canal overlay. Revisitez quand un cas d'usage « promote release X » apparaît.
• Historique du manifeste. Actuellement seul le manifeste de la dernière build existe ; si un utilisateur veut restaurer bsp_image à un état de build antérieur, il faudrait relancer /jetson-build-source au commit antérieur. Une archive du manifeste (sauvegardée par-mode-build ou par-commit) permettrait le rollback sans rebuild.
• Manifeste auxiliaire dans bsp_image. Revisitez quand la promotion se produit sur un hôte qui n'a pas accès au repo du suivi overlay (ou au fichier manifeste du workspace).

Références

• references/kernel-image-and-initramfs.md — contrat complet pour le miroir kernel Image + refresh l4t_update_initrd.sh : snippets shell, modes défaillance, sémantique outil, noms de fichiers de sortie.
• ../../context/target-platform-contract.md — contrat target-platform.
• ../../context/bsp-customization-workflow.md — protocole édition workspace (cette compétence est la phase promote de Deploy).
• ../jetson-init-source/SKILL.md — Setup ; matérialise le suivi overlay que cette compétence lit (canal A) et authored source.toolchain.
• ../jetson-build-source/SKILL.md — Builder de Build ; écrit le .build-manifest.yaml que cette compétence lit (canal B).
• ../jetson-flash-image/SKILL.md — phase suivante ; flashe le bsp_image fraîchement promu vers la DUT.
• ../jetson-validate-image/SKILL.md — phase finale ; validation statique + sur-cible.