Initialiser l'espace de travail de personnalisation BSP

Vue d'ensemble

Cette skill bootstrap l'espace de travail côté source dont dépendent les skills customize-* / build : le tracker overlay Linux_for_Tegra (repo git pour commits pristine + personnalisation), le mono-tree bsp_sources/ (kernel, OOT, nvgpu, display, hwpm, hardware DTs), et un prefix cross-compile NVIDIA Crosstool-NG fonctionnel. Elle ne possède que le bloc source: du profil actif et l'espace de travail source sur disque sous <source.root_path> (défaut : <workspace>/Source).

Responsabilités :

Enregistrer optionnellement un source.root_path non-défaut.
Créer ou monter le tracker overlay Linux_for_Tegra.
Matérialiser bsp_sources en utilisant la précédence de l'étape « Matérialiser la baseline BSP-sources ».
Résoudre et enregistrer source.toolchain.
Cloner les repos supplémentaires définis par l'utilisateur depuis source.repos:.

Quand invoquer

L'utilisateur demande de bootstrapper, initialiser, ou synchroniser l'espace de travail de personnalisation BSP.
Une skill de personnalisation en aval a refusé avec « no workspace tracker at <source.root_path>/Linux_for_Tegra/ ».
Après jetson-init-image (prochaine étape de Setup sur une cible fraîche).

Procédure

Mappage de pré-remplissage Quick-start

Suivez le contrat partagé quick_start_prefill. Cette skill a des mappages source-spécifiques :

quick_start_prefill.source.public_sources_archive mappe au candidat archive Branch-A.
quick_start_prefill.source.repos mappe aux propositions d'entrées source.repos: ; validez les clés réservées et l'exclusion mutuelle url: / archive: avant écriture.
quick_start_prefill.source.toolchain peut être un prefix cross-compile, un chemin gcc, un répertoire contenant bin/, un chemin d'archive x-tools.tbz2, ou skip.

Cette skill reste le seul propriétaire des écritures profil source.root_path, source.repos: et source.toolchain.

Résoudre la cible active + chemins

Résolvez le profil actif + les défauts workspace selon le contrat dans ../../context/target-platform-contract.md.

Refusez si <bsp_image.root_path> ne contient pas Linux_for_Tegra/ (BSP non extrait — routez vers /jetson-init-image).
Si le profil a source.root_path:, utilisez-le. Sinon <source.root_path> vaut par défaut <workspace>/Source ; utilisez ce défaut silencieusement et n'écrivez pas source.root_path: au profil. Demandez seulement un chemin personnalisé explicite, du contenu non lié au chemin défaut, ou un parent non-inscriptible.

Lisez source.repos: (si présent) dans une map indexée par nom d'entrée, chacune portant optionnellement url, ref, subdir, path. Clés réservées : Linux_for_Tegra (tracker overlay), bsp_sources (repo kernel-source). Chaque autre clé est un repo supplémentaire défini par l'utilisateur.

(Optionnel) inviter pour le remplacement `source.root_path`

Seulement quand source.root_path est absent du profil et l'une des conditions de remplacement ci-dessus s'applique :

source.root_path : défaut = <workspace>/Source. Appuyez sur Entrée pour accepter, ou entrez un chemin absolu pour remplacer.

Sur Entrée — conservez le défaut ; ne touchez pas le profil.
Sur chemin de remplacement — validez que le parent existant le plus proche est inscriptible ; refusez et re-demandez sinon. Éditez target-platform/<active>.yaml sur place pour ajouter/mettre à jour source.root_path:. Préservez tous les autres blocs, commentaires et guillemets — utilisez un chargeur YAML round-tripping (par ex. ruamel.yaml).

Se déclenche au maximum une fois par profil. Sinon créez <workspace>/Source selon les besoins et continuez sans inviter.

Matérialiser `Linux_for_Tegra`

Le chemin de montage est canonique : <source.root_path>/Linux_for_Tegra/.

Défaut (pas d'entrée source.repos.Linux_for_Tegra) :

LFT="<source.root_path>/Linux_for_Tegra"
mkdir -p "$LFT"
[ -d "$LFT/.git" ] || git -C "$LFT" init

Tracker vide. N'engagez rien ici — les imports pristine se font fichier par fichier quand les skills de personnalisation tournent.

Remplacement (url, ref, subdir optionnel) :

# Clonez le repo de l'utilisateur à un emplacement côté, puis montez
# l'arborescence attendue (subdir ou racine du repo) au chemin canonique.
CLONE="<source.root_path>/.repos/Linux_for_Tegra"
git clone <url> -b <ref> "$CLONE"
ln -s "$CLONE/<subdir or .>" "<source.root_path>/Linux_for_Tegra"

Si le montage existe déjà avec un état git valide, sautez ; refusez s'il existe avec du contenu non lié.

Matérialiser la baseline BSP-sources

Trois branches, dispatched en ordre de précédence contre l'entrée profil source.repos.bsp_sources :

Ordre	État du profil	Branche
1	`url:` défini	C. Clone git client (le remplacement explicite gagne toujours)
2	`archive:` défini, OU entrée absente ET `<workspace>/Downloads/public_sources.tbz2` existe	A. Extraction d'archive locale (défaut)
3	Entrée absente ET pas d'archive locale	B. `source_sync.sh` (secours)

url: et archive: sont mutuellement exclusifs — refusez si les deux sont définis dans la même entrée.

La branche A est le défaut préféré car elle contourne entièrement la sortie git NVIDIA (le mode d'échec Setup le plus courant). La branche B existe pour les nouveaux espaces de travail sans tarball pré-téléchargée. La branche C est pour les forks client de toute la mise en page BSP.

Branche A — Extraction d'archive locale (défaut)

Branche par défaut : extrayez un public_sources.tbz2 pré-téléchargé dans <source.root_path>/bsp_sources/ comme un mono-repo unique (git init + commit pristine). Consultez references/branch-a-extraction.md pour la forme d'archive complète, les règles de résolution de chemin, et le script d'extraction (incluant la solution de contournement du Makefile Tegra OOT pour R36.x).

Les branches B et C peuvent produire des repos par composant à la place ; la logique de build en aval marche toujours sur les chemins canoniques sous <source.root_path>/bsp_sources/.

Branche B — `source_sync.sh` (secours)

S'exécute seulement quand aucune archive locale n'est trouvée et aucun url: n'est défini. Créez le répertoire de montage bsp_sources/ sous <source.root_path> et exécutez source_sync.sh depuis le BSP extrait avec deux drapeaux :

mkdir -p "<source.root_path>/bsp_sources"
bash "<bsp_image.root_path>/Linux_for_Tegra/source/source_sync.sh" \
     -d "<source.root_path>/bsp_sources" \
     -t "jetson_<major.minor>"

-d <source.root_path>/bsp_sources — écrivez les clones dans le sous-répertoire bsp_sources/ de l'espace de travail, pour que le dossier sur disque corresponde à la clé de schéma. Sans -d, le script écrit sous son propre répertoire (le BSP lui-même) — mauvais pour le modèle overlay.
-t jetson_<major.minor> — épinglez le tag à la ligne de sortie BSP. Dérivez de bsp_image.version en tronquant aux deux premiers composants pointés : "38.4.0" → jetson_38.4. Secours format-tag : s'il est rejeté, essayez jetson_<bsp_image.version> (l'ancien L4T utilise parfois la forme complète). Si cela échoue aussi, remontez l'erreur et arrêtez — ne retombez jamais silencieusement sur « latest ».

Refusez si source_sync.sh n'existe pas : relancez /jetson-init-image pour repeupler Linux_for_Tegra/source/.

source_sync.sh quitte 0 même quand chaque clone a échoué — vérifiez en comptant les lignes « Failed to clone » dans sa sortie et refusez si non-zéro. La cause la plus probable d'échec universel est une sortie git bloquée vers gitlab.com/nvidia/nv-tegra / nv-tegra.nvidia.com ; remontez cela explicitement et routez l'utilisateur pour télécharger public_sources.tbz2 via /quick-start pour la branche A.

Branche C — Clone git client (`url:` remplacement)

Déclenché par un champ url: explicite. Clonez le repo client une fois et exposez ses chemins canoniques kernel-side sous <source.root_path>/bsp_sources/. La liste canonique de sous-chemins est lue depuis SOURCE_INFO de source_sync.sh à runtime — ne la codez pas en dur, pour que les ajouts/suppressions NVIDIA futurs se propagent automatiquement :

# Analysez les chemins canoniques depuis SOURCE_INFO de source_sync.sh
# (seulement les entrées kernel-side marquées `k:` dans le second champ).
SUBPATHS=$(grep -oP '^\s*k:[^:]+:' \
  "<bsp_image.root_path>/Linux_for_Tegra/source/source_sync.sh" \
  | sed 's/^\s*k://; s/:$//')

mkdir -p "<source.root_path>/bsp_sources"
CLONE="<source.root_path>/.repos/bsp_sources"
git clone <url> -b <ref> "$CLONE"
ROOT="$CLONE/<subdir or .>"
for SUB in $SUBPATHS; do
  [ -d "$ROOT/$SUB" ] && \
    ln -s "$ROOT/$SUB" "<source.root_path>/bsp_sources/$SUB"
done

Signalez tout chemin canonique attendu pour la famille chip active mais absent à l'intérieur du repo client (avertissez, ne refusez pas — le client peut légalement ne pas avoir tous les repos).

Résoudre la chaîne d'outils cross-compile

Le jetson-build-source en aval lit source.toolchain de ce profil et l'exporte comme CROSS_COMPILE. Cette étape doit aboutir à un prefix valide avant que init-source retourne, ou tout build kernel / OOT / DT ultérieur refusera.

La Chaîne d'outils Crosstool-NG gcc officielle NVIDIA est la chaîne d'outils canonique pour L4T. jetson-download-bsp possède tout fetch réseau de x-tools.tbz2 ; cette skill ne découvre, extrait, valide et écrit que le prefix résolu. La résolution suit une échelle à trois étapes :

Découverte automatique

Cherchez sous <workspace>/toolchain/x-tools/ pour la mise en page Crosstool-NG — typiquement l'un de :

<workspace>/toolchain/x-tools/aarch64-none-linux-gnu/bin/aarch64-none-linux-gnu-gcc
<workspace>/toolchain/x-tools/aarch64-buildroot-linux-gnu/bin/aarch64-buildroot-linux-gnu-gcc

Glob : <workspace>/toolchain/x-tools/aarch64-*-linux-gnu/bin/aarch64-*-linux-gnu-gcc. S'il y a exactement une correspondance, liez :

TC_PREFIX=<absolute path to that .../bin/<triple>->   # trailing dash mandatory

Sautez à « Écrire au profil » ci-dessous. S'il y a zéro correspondances, passez à « Auto-extraire depuis Downloads/x-tools.tbz2 » ci-dessous. S'il y en a plusieurs, refusez avec la liste et demandez à l'utilisateur de supprimer les indésirables (nous ne choisissons jamais silencieusement parmi des installations ambiguës — différentes saveurs Crosstool-NG produisent des binaires ABI-incompatibles).

Auto-extraire depuis `Downloads/x-tools.tbz2`

Si <workspace>/Downloads/x-tools.tbz2 existe (reflète le motif Branch-A public_sources.tbz2 de l'étape « Matérialiser la baseline BSP-sources » — utilisateurs air-gappés / sans sortie laissent les archives là) :

file -b "<workspace>/Downloads/x-tools.tbz2" | grep -q "bzip2 compressed" || \
  refuse "<workspace>/Downloads/x-tools.tbz2 is not a bzip2 tarball"
mkdir -p "<workspace>/toolchain"
tar xjf "<workspace>/Downloads/x-tools.tbz2" -C "<workspace>/toolchain"

Relancez ensuite la passe « Découverte automatique » ci-dessus. Refusez si l'extraction réussit mais aucun x-tools/aarch64-*-linux-gnu/bin/ n'est produit (le contenu d'archive ne correspond pas à la mise en page Crosstool-NG).

Inviter l'utilisateur

Si Découverte automatique et Auto-extraire sont venus à vide tous les deux, demandez :

Aucune chaîne d'outils Crosstool-NG trouvée à <workspace>/toolchain/ ou dans <workspace>/Downloads/x-tools.tbz2.

Répondez avec l'un de :

chemin absolu vers votre binaire aarch64-*-linux-gnu-gcc ou son répertoire bin/ contenant,

cancel pour abandonner.

Pour chercher l'archive à la place, annulez cette exécution, exécutez /jetson-download-bsp, puis relancez /jetson-init-source.

Pour une réponse de chemin, validez via [ -f "${TC_PREFIX}gcc" ]. Refusez et re-demandez en cas d'échec.

Écrire au profil

Une fois que $TC_PREFIX se résout et ${TC_PREFIX}gcc existe, écrivez-le dans le profil actif en utilisant un chargeur YAML round-tripping :

source:
  toolchain: <TC_PREFIX>   # absolute, with trailing dash

Si source: est autrement vide (pas de remplacement root_path, pas d'entrées repos:), le bloc source: est maintenant non-vide et reste dans le profil. Les futurs runs jetson-init-source sautent l'étape « Résoudre la chaîne d'outils cross-compile » si source.toolchain est déjà défini et pointe sur un gcc fonctionnel.

Cloner les repos supplémentaires définis par l'utilisateur

Pour chaque entrée sous source.repos: dont le nom n'est pas Linux_for_Tegra ou bsp_sources :

MOUNT="<source.root_path>/<entry.path or entry.name>"
if [ -n "<entry.subdir>" ]; then
  CLONE="<source.root_path>/.repos/<entry.name>"
  git clone <entry.url> -b <entry.ref> "$CLONE"
  ln -s "$CLONE/<entry.subdir>" "$MOUNT"
else
  git clone <entry.url> -b <entry.ref> "$MOUNT"
fi

Refusez si un chemin de montage existe déjà avec du contenu non lié.

Résumé

Imprimez :

<workspace> résolu, <bsp_image.root_path>, et <source.root_path>.
Pour chaque composant matérialisé : créé, réutilisé, sauté, ou refusé.
Pour bsp_sources : branche sélectionnée plus preuve clé (chemin archive, compte d'échec source_sync.sh, ou URL clone/ref).
Prefix toolchain, source de résolution, et première ligne de ${TC_PREFIX}gcc --version.
Rappel que les skills customize-* font stage des édits BSP futures dans <source.root_path>/Linux_for_Tegra/ ; promote est ce qui copie ultérieurement les changements d'overlay engagés dans bsp_image.

Si une skill en aval a déclenché ce run, dites à l'utilisateur de rééditer sa demande d'origine.

Pièges

Les chemins de montage Linux_for_Tegra et bsp_sources sont canoniques. path: s'applique seulement aux repos supplémentaires définis par l'utilisateur.
Le tracker Linux_for_Tegra par défaut est intentionnellement vide ; ne le pré-populez pas.
La précédence bsp_sources est url: → archive: → Downloads/public_sources.tbz2 auto-découvert → source_sync.sh. url: et archive: sont mutuellement exclusifs.
La découverte automatique Branch A n'invite pas et n'est pas écrite au profil. Persistez-la seulement avec source.repos.bsp_sources.archive:.
Collision $DEST/Makefile Branch A. Les tarballs internes dans public_sources.tbz2 livrent deux fichiers nommés Makefile : l'orchestrateur Tegra (kernel_oot_modules_src.tbz2) et le Makefile propriétaire dGPU/OpenRM (nvidia_kernel_display_driver_source_without_root_dir.tbz2). L'ordre d'extraction alphabétique laisse gagner le dGPU sur R36.x ; les cross-builds arm64 en aval échouent alors avec '-mlittle-endian' unrecognized. L'étape 3a force-remplace depuis <bsp_image>/Linux_for_Tegra/source/Makefile quand la signature Tegra modules: hwpm nvidia-oot nvgpu nvidia-display manque. Les extractions R38+ correspondent déjà ; la vérification est une no-op là.
Les repos clients Branch C doivent exposer la mise en page canonique source_sync.sh sous-chemin, optionnellement décalée par subdir:.
Dérivez le tag source_sync.sh depuis bsp_image.version comme jetson_<major.minor> d'abord ; ne retombez jamais sur un latest non-épinglé.
jetson-download-bsp possède les téléchargements réseau de public_sources.tbz2 et x-tools.tbz2 ; cette skill consomme seulement les archives locales.
source.toolchain doit être un prefix NVIDIA Crosstool-NG avec trailing dash et un ${prefix}gcc fonctionnel. N'utilisez jamais silencieusement $PATH.
Utilisez un writer YAML round-tripping pour les édits profil.

Prérequis

Profil cible actif résolu selon ../../context/target-platform-contract.md.
/jetson-init-image déjà exécuté pour que bsp_image.version soit enregistré (le tag Branch B source_sync.sh en dérive).
Pour Branch A : un public_sources.tbz2 local (et optionnellement x-tools.tbz2) stagé sous Downloads/.
Pour Branch C : accès Git client au repo URL de remplacement.

Limitations

Possède seulement le bloc source: ; n'édite jamais bsp_image, reference_devkit, custom_carrier, ou documents.
Sortie réseau seulement pour Branch B (source_sync.sh) et Branch C (clone Git client) ; Branch A est entièrement hors ligne.
Refuse de silencieusement substituer une chaîne d'outils système — le prefix NVIDIA Crosstool-NG doit être présent ou extractible.

Dépannage

${toolchain}gcc non trouvé — re-stagez x-tools.tbz2 sous Downloads/ et relancez, ou passez un chemin prefix absolu vérifié.
source_sync.sh ne peut pas résoudre le tag jetson_<major.minor> — le bsp_image.version enregistré est mauvais ; relancez /jetson-init-image pour le rafraîchir.
Linux_for_Tegra/.git affiche des édits manuels non engagés — abandonnez et demandez à l'utilisateur de committer ou stash ; cette skill s'attend à un tracker propre.
Clone Branch C manquant les chemins canoniques sous-traités — la mise en page repo ne correspond pas à source_sync.sh ; réglez subdir: sur la bonne sous-racine ou retombez sur des remplacements multi-repo sous source.repos:.

Références

../../references/platform_template.yaml — schéma source:, incluant la map repos:.
../../context/target-platform-contract.md — contrat target-platform.
../../context/bsp-customization-workflow.md — protocole édition Workspace.
../jetson-init-target/SKILL.md — crée le profil que cette skill consomme.
../jetson-init-image/SKILL.md — extrait le BSP et remplissage arriéré bsp_image.version ; exécutez avant cette skill.