Construire la source BSP

Objectif

Reconstruire les artefacts côté noyau (DTBs, modules OOT, modules in-tree, noyau Image) impliqués par les changements sous <source.root_path>/bsp_sources/, et écrire un manifeste que /jetson-promote-image lit pour intégrer ces sorties dans l'image BSP. Cette compétence n'écrit jamais directement dans <bsp_image.root_path>.

Prérequis

• Profil de plateforme cible actif avec bsp_image: et source.toolchain: résolus (exécutez d'abord /jetson-init-image et /jetson-init-source).
• <source.root_path>/bsp_sources/ rempli avec la disposition d'extraction côté noyau que /jetson-init-source matérialise.
• <bsp_image.root_path>/Linux_for_Tegra/source/kernel_src_build_env.sh présent (extrait de public_sources.tbz2).
• Paquets hôte : flex, bison, libssl-dev (obligatoires) ; git, build-essential, bc, zstd (avertissement uniquement).
• Chaîne d'outils croisée à ${source.toolchain}gcc résoluble sur disque.

Aperçu

Cette compétence est l'étape Build du workflow — voir ../../context/bsp-customization-workflow.md pour son rôle dans le pipeline Setup → Customize → Build → Deploy et ce qui la déclenche. La compétence prend les commits de personnalisation côté source, reconstruit les artefacts impliqués, et enregistre lesquels ont été reconstruits dans un manifeste. Les sorties restent in-tree sous <source.root_path>/bsp_sources/ ; jetson-promote-image lit le manifeste lors du déploiement pour copier chaque artefact reconstruit vers le chemin correspondant sous <bsp_image.root_path>/Linux_for_Tegra/.

Les modifications overlay uniquement (nvpmodel.conf, nvfancontrol.conf, BPMP DTB) contournent Build — les étapes customize-* les envoient directement au suivi overlay ; BPMP DTB utilise la boucle dtc décompile → édite → recompile dans ../../references/bsp-customization-bpmp-dtb.md.

Propriété de l'emplacement overlay personnalisé. Les personnalisations kernel-DT de chaque compétence customize-* se collectent en un seul tegra<soc>-<carrier-id-sku>+<module-id>-xxxx-custom.dts composite par cible active — voir ../../references/bsp-customization-kernel-dtb.md pour le protocole nom fichier / localisation / ajout. Cette compétence est le seul propriétaire de l'enregistrement Makefile par répertoire du composite (dtbo-y += <name>.dtbo) et de la ligne OVERLAY_DTB_FILE+= de la conf flash porteuse (l'étape « Enregistrer l'overlay personnalisé composite »).

Quatre modes de construction alignés sur le profil dirty-repo :

Sélection du mode : auto (défaut — invoquez /jetson-build-source sans argument) parcourt l'ensemble dirty-repo ; forcez un mode spécifique en le passant comme argument de compétence.

Principe de conception : déléguer à l'upstream. Chaque primitive de construction existe déjà dans <bsp_image.root_path>/Linux_for_Tegra/source/ — le fichier env, le Makefile de haut niveau (nvidia-dtbs / modules / modules_install), le Makefile du noyau (kernel / install). La compétence pilote ces primitives contre <source.root_path>/bsp_sources/ — ne duplique jamais leur logique en shell.

Quand invoquer

• Auto-enchaîné à la fin d'une invocation Customize customize-* chaque fois que Customize s'est engagé à un repo source côté noyau.
• Ré-exécution manuelle via /jetson-build-source [<mode>] quand :
  • la construction auto-enchaînée a été interrompue,
  • des commits source arrivent via git pull d'autres utilisateurs,
  • l'utilisateur veut forcer une reconstruction sans édition fraîche,
  • l'utilisateur veut un mode spécifique (par ex. consolidation install pour un déploiement scp manuel vers un DUT).

Instructions

Résoudre la cible active + chemins + env upstream

Résolvez le profil actif selon ../../context/target-platform-contract.md. Refusez et routez dans ces cas :

Liez :

WORKSPACE=<parent of target-platform/>
BSP_SRC=<bsp_image.root_path>/Linux_for_Tegra/source   # primitives NVIDIA
KS=<source.root_path>/bsp_sources                      # notre extraction côté noyau
KOUT=<source.root_path>/.build/kernel-out              # répertoire build out-of-tree mode DT
STAGE=<source.root_path>/.build/install-stage          # consolidation install (full mode / opt-in)
STATE=<source.root_path>/.build-state.yaml             # repère par-repo
MANIFEST=<source.root_path>/.build-manifest.yaml       # liste artefacts reconstruits pour jetson-promote-image

Sourcez l'env build NVIDIA pour hériter des noms canoniques — ne codez jamais en dur kernel-noble, la liste des modules OOT, ou KERNEL_DEF_CONFIG :

source "$BSP_SRC/kernel_src_build_env.sh"
# Maintenant en scope : KERNEL_SRC_DIR (par ex. kernel-noble), KERNEL_DEF_CONFIG,
# OOT_SOURCE_LIST, kernel_name (par ex. noble), KERNEL_MODULAR_BUILD

Refusez si $KS/kernel/$KERNEL_SRC_DIR/ manque ou si un nom quelconque dans $OOT_SOURCE_LIST manque sous $KS/. Routez vers /jetson-init-source.

Résoudre la chaîne d'outils (lecture seule)

Lisez source.toolchain du profil actif (créé par jetson-init-source). Validez :

export ARCH=arm64
export CROSS_COMPILE=<source.toolchain>   # tiret final obligatoire
[ -f "${CROSS_COMPILE}gcc" ] || refuse \
  "source.toolchain points at ${CROSS_COMPILE}gcc which does not exist. Re-run /jetson-init-source."

Un tiret final sur CROSS_COMPILE est obligatoire — kbuild le traite comme préfixe (${CROSS_COMPILE}gcc) ; un tiret manquant se casse avec command not found. Le contrôle [ -f ] l'attrape avant tout make.

Cette compétence ne demande jamais la chaîne d'outils ou ne tente jamais d'en résoudre une manquante — c'est la responsabilité exclusive de jetson-init-source. Un champ manquant est une lacune Setup ; routez là.

Vérifiez les prérequis build-hôte une seule fois :

for p in flex bison libssl-dev; do
  dpkg -s "$p" >/dev/null 2>&1 || refuse "host package missing: $p"
done
for p in git build-essential bc zstd; do
  dpkg -s "$p" >/dev/null 2>&1 || warn "host package missing: $p"
done

Détecter les repos source dirty

Le fichier repère $STATE enregistre le dernier commit construit avec succès par repo côté noyau. La liste des repos est dérivée à runtime de OOT_SOURCE_LIST + kernel/$KERNEL_SRC_DIR. Pour chaque repo : HEAD ≠ repère → dirty ; éditions non engagées (git diff --quiet non-zéro) → aussi dirty.

Note Branch-A : quand bsp_sources/ est un mono-repo avec un unique .git, chaque sous-chemin canonique partage le même HEAD — le schéma repère clé toujours par sous-chemin et l'ensemble dirty fonctionne toujours (tout changement quelconque inverse le HEAD de chaque sous-chemin).

Si STATE est absent (première construction), traitez tous les repos comme propres à moins que le contexte auto-chaîn dise « Customize vient de s'engager ». Si DIRTY est vide et aucun argument mode n'a été passé : rapportez « rien à construire » et retournez.

Choisir le mode de construction

Mappez l'ensemble dirty à un mode (auto), ou honorez l'argument mode :

Les modes sont unionables : full exécute kernel → oot → dt dans cet ordre (kernel produit les en-têtes dont OOT a besoin ; nvidia-dtbs utilise les mêmes en-têtes générés). Un argument mode passé manuellement contourne la détection auto.

Exécuter la construction

Configuration commune + extraits de construction par mode

La configuration commune (valider les Makefiles orchestrateur, cd $KS) et les invocations make exactes pour chaque mode (dt, oot, kernel, full) plus la passe consolidation install optionnelle vivent dans references/build-modes.md. Pilotez l'extrait du mode pertinent contre les liaisons depuis l'étape « Résoudre la cible active + chemins + env upstream ».

Enregistrer l'overlay personnalisé composite (dt + full uniquement)

Ignorez si le mode sélectionné n'est pas dt ou full. L'emplacement overlay composite est documenté dans ../../references/bsp-customization-kernel-dtb.md ; cette sous-étape possède le côté build / Makefile / flash-conf.

Résolvez le chemin composite pour la cible active ($COMPOSITE_BASE, $COMPOSITE_DTS, $COMPOSITE_MK) en utilisant la famille chip, l'ID/SKU porteuse, et l'ID module du profil actif — extrait complet dans references/composite-registration.md.

Portail (symétrique). $COMPOSITE_DTS pilote les deux directions : présent → appliquez les deux patches idempotents ci-dessous ; absent → exécutez la passe cleanup pour retirer toute ligne stale dtbo-y += / OVERLAY_DTB_FILE+= d'une exécution antérieure. Chaque chemin garde OVERLAY_DTB_FILE+= de référencer un .dtbo non construit — l'application build-time de la règle pas d'édits DT in-tree directs.

1. Makefile par répertoire — ajoutez dtbo-y += <name>.dtbo après la dernière entrée dtbo-y += littéralement nommée. Insérer après la ligne merge-back $(old-dtbo) contourne la passe préfixe $(addprefix makefile-path/,…) et la construction abandonne silencieusement le composite. Engagez au mono-repo bsp_sources/. Extrait complet + justification : references/composite-registration.md.
2. Conf flash porteuse — ajoutez OVERLAY_DTB_FILE+=",<name>.dtbo" avec import pristine au premier contact sur le suivi overlay. Sur un espace de travail frais le suivi est git-init vide ; importez la conf de bsp_image et engagez comme pristine: avant le commit customization (contrat workflow). Extrait complet : references/composite-registration.md.

Le flip de HEAD du sous-repo parent du composite pendant un ajout customize-* est ce que la détection dirty de l'étape « Détecter les repos source dirty » consomme — aucune tenue de livres supplémentaire requise ici.

Auto-vérification avant d'invoquer nvidia-dtbs :

grep -qxF "dtbo-y += ${COMPOSITE_BASE}.dtbo" "$COMPOSITE_MK" \
  || refuse "Composite Makefile registration missing after patch."
grep -qxF "$line" "$FLASH_CONF" \
  || refuse "Composite flash-conf registration missing after patch."

Écrire le manifeste de construction

Parcourez l'ensemble DIRTY et émettez une entrée manifeste par artefact impliqué, suivant la politique trace-to-dirty — seulement les artefacts traçables à un repo source dirty. Promouvoir le bruit baseline-divergence l'attribuerait à la piste audit d'une customization (interdit).

Le mapping complet source → kbuild → destination, le schéma YAML, et les règles de filtre vivent dans references/manifest-schema.md.

Écriture atomique : envoyez en staging vers ${MANIFEST}.tmp, puis mv -f.

Mettre à jour le repère + résumé

Sur succès, réécrivez $STATE avec les nouveaux HEADs par-repo, chaîne d'outils, bsp_image.version, et dernier mode exécution (schéma dans references/manifest-schema.md).

Rapportez :

• Chaîne d'outils (depuis source.toolchain).
• Mode construction : <dt|oot|kernel|full> (auto-sélectionné ou forcé par argument compétence).
• Repos dirty et leurs nouveaux HEADs.
• Artefacts construits : décomptes par type (.dtb, .ko in-tree, .ko OOT, Image).
• Chemin manifeste + nombre d'entrées.
• Chemin étape install consolidée (si l'étape « Consolidation install » a exécuté).
• Prochaine étape : /jetson-promote-image.

Si une compétence Customize a déclenché cette exécution, invitez l'utilisateur à rééditer sa requête originale.

Limitations

Le tier supérieur — modes défaillance qui bloquent une construction ou produisent silencieusement les mauvais artefacts. Voir references/long-tail-gotchas.md pour les invariants, patterns déploiement, et conseils performance.

• La résolution chaîne d'outils est le job de jetson-init-source. Cette compétence lit seulement source.toolchain et exporte CROSS_COMPILE. Champ manquant → refusez et routez, ne résolvez jamais in-skill.
• Collision $KS/Makefile Branch-A R36.x. Le public_sources.tbz2 de R36.x peut laisser le Makefile propriétaire dGPU/OpenRM à $KS/Makefile au lieu de l'orchestrateur Tegra ; sa cible modules recurse dans kernel-open/ + src/nvidia/, tire les en-têtes hôte /lib/modules, et casse les cross-builds arm64 avec '-mlittle-endian' unrecognized. Les extractions R38+ sont non affectées. L'étape 3a de /jetson-init-source est la défense primaire (temps extraction) ; le contrôle « Configuration commune » ici est le filet de sécurité. Ne relaxez pas la regex.
• Changements Kernel-DT : overlay-composite-uniquement, propriété split. Les édits directs aux fichiers .dts / .dtsi in-tree sous bsp_sources/ sont interdits pour les compétences customize-* — chaque changement kernel-DT atterrit comme fragment dans l'emplacement overlay composite (règle + justification). Le contenu .dts composite est possédé par chaque compétence customize-* ; l'enregistrement build / Makefile / flash-conf est possédé par cette compétence (porté sur l'existence du .dts composite — donc OVERLAY_DTB_FILE+= ne peut pas référencer un .dtbo non construit).
• Le point d'insertion Makefile de l'étape « Enregistrer l'overlay personnalisé composite » importe. Insérez après la dernière entrée dtbo-y += littéralement nommée ; insérer après $(old-dtbo) contourne la passe préfixe $(addprefix makefile-path/,…) et la construction abandonne silencieusement votre .dtbo. La regex ^dtbo-y *+= *[a-zA-Z0-9] filtre correctement ; ne la relaxez pas.
• L'étape « Enregistrer l'overlay personnalisé composite » first-touch a besoin d'import pristine. Sur un espace de travail frais le suivi overlay est git-init vide — la conf flash porteuse est importée de bsp_image et engagée comme pristine: avant le commit customization. Les deux commits passent la porte d'acceptation workflow.
• Évitez $0 nu dans les extraits shell à l'intérieur de ce SKILL.md. Quand invoqué avec un argument, le harnais expande le $0 body-compétence contre le $0 de l'appelant avant de passer le prompt rendu au modèle. Utilisez le splice ligne basé sed ou awk -v ROW="$0". Voir references/composite-registration.md.
• Pas d'étape overlay. Les sorties construction restent où la construction les a mises ; le manifeste est le contrat vers jetson-promote-image. Divergence délibérée de l'indirection originale overlay→promote — garde l'ensemble complet sortie construction hors de l'historique git du suivi overlay.
• KERNEL_HEADERS vs KERNEL_OUTPUT en mode DT. Sémantiques différentes (srctree vs objtree) ; ne les collapsiez pas. L'extrait l'étape « DT-only » est correct tel écrit.
• Prérequis mode OOT : en-têtes noyau précédemment construits. Une invocation oot manuelle contre un arbre jamais construit refuse avec « exécutez kernel (ou full) d'abord » plutôt que de produire une erreur build confuse.

Exemples

Auto-détecter le mode depuis l'arbre source dirty (invocation typique) :

/jetson-build-source

Forcer un mode unique (contourne auto-détect) :

/jetson-build-source dt       # reconstruire DTBs NVIDIA seulement
/jetson-build-source oot      # reconstruire modules OOT seulement
/jetson-build-source kernel   # reconstruire noyau Image + modules in-tree
/jetson-build-source full     # reconstruire tout + consolidation install

Chaîne typique après qu'une compétence customize- s'engage à un repo côté noyau (la compétence customize- appelle ceci automatiquement) :

/jetson-customize-pcie ...   # s'engage à hardware/nvidia/.../nv-public
   ↓
/jetson-build-source         # auto-sélectionne `dt` depuis l'ensemble dirty
   ↓
/jetson-promote-image        # lit .build-manifest.yaml, envoie en staging vers bsp_image
   ↓
/jetson-flash-image          # flashe

Dépannage

Voir aussi

• references/build-modes.md — extraits make par mode + consolidation install.
• references/manifest-schema.md — schémas .build-manifest.yaml + .build-state.yaml.
• references/composite-registration.md — extraits complets étape « Enregistrer l'overlay personnalisé composite » + justification.
• references/long-tail-gotchas.md — invariants, patterns déploiement, conseils performance.
• references/upstream-recipe.md — recette NVIDIA verbatim, divergences, statut spec.
• ../../context/bsp-customization-workflow.md — protocole édition espace de travail.
• ../../references/bsp-customization-kernel-dtb.md — contrat overlay customisé composite.
• ../../references/bsp-customization-bpmp-dtb.md — contrat édition BPMP-DTB (routé autour cette compétence).
• ../jetson-init-source/SKILL.md — Setup ; crée source.toolchain.
• ../jetson-promote-image/SKILL.md — Promoteur Deploy ; lit le manifeste de cette compétence.