Générer la base de connaissances cible

Aperçu

Cette skill produit une référence markdown par profil à target-platform/<profile-stem>.md (voisine du YAML du profil). Elle regroupe trois éléments dans un seul fichier pour qu'une future session Claude — ou l'utilisateur — puisse voir la forme de la cible active sans réexplorer le système de fichiers :

1. Disposition de l'image BSP — répertoires de haut niveau sous bsp_image.root_path, présence de sous-arbres canoniques (rootfs/, bootloader/, source/, …), et les variantes nvpmodel correspondant au SKU du module actif.
2. Disposition de l'arborescence des sources — sous-arbres de haut niveau sous source.root_path (kernel-jammy-src/, hardware/nvidia/, nvidia-oot/, etc.) et fichiers devicetree correspondant à la famille de puces.
3. Documents — les références documents.* enregistrées dans le profil, avec vérifications d'existence de chemin local et descriptions d'une ligne.

La KB est un instantané, daté dans son en-tête. Réexécutez cette skill chaque fois que les données sous-jacentes changent — elle est intentionnellement réexécutable et écrase la KB précédente à chaque exécution.

Quand l'invoquer

• Après que jetson-init-image prépare le BSP pour un profil nouvellement créé.
• Après réextraction d'une archive BSP ou application de correctifs sous bsp_image.root_path.
• Après mise à jour de l'arborescence des sources à source.root_path.
• Après édition de bsp_image.* ou documents.* dans le YAML du profil.
• Quand une skill aval demande « où se trouve X dans ce BSP ? » et vous préférez vérifier la KB plutôt que de réexplorer l'arborescence.

Procédure

Résoudre la cible active

Résolvez le profil actif selon le contrat dans ../../context/target-platform-contract.md; mettez-le en cache en mémoire — le reste de la skill ne consomme que ce profil. Enregistrez <profile-stem> (le nom de fichier nu moins .yaml) comme stem du nom de fichier de sortie KB.

Valider les entrées

Si bsp_image.root_path est défini mais que le répertoire n'existe pas sur disque, refusez avec un message clair — ne fabriquez pas une disposition pour un chemin qui n'existe pas.

Découverte BSP (sous bsp_image.root_path)

Exécutez uniquement les opérations bon marché suivantes — pas d'analyses récursives, pas de lectures de contenu de fichier au-delà des listes de répertoires :

1. ls -1 de bsp_image.root_path (un niveau de profondeur). Enregistrez quels répertoires sont présents.
2. Pour chaque sous-arbre canonique ci-dessous, marquez présent/absent : rootfs/, bootloader/, kernel/, source/, tools/, nv_tegra/.
3. Vérifiez que le fichier flash_config actif existe à <bsp_image.root_path>/<flash_config>. Enregistrez son chemin ou (manquant).
4. Listez rootfs/etc/nvpmodel/ et filtrez les noms de fichiers correspondant à nvpmodel_<module.id>_<module.sku>*.conf. Enregistrez chaque correspondance. Utilisez l'id du module en minuscules (par ex. p3767) et la chaîne sku entre guillemets YAML (par ex. 0001).

Découverte de l'arborescence des sources (sous source.root_path)

Ignorez complètement cette étape si source.root_path est NA ou absent. Sinon, exécutez uniquement :

1. ls -1 de source.root_path (un niveau de profondeur).
2. Pour chaque sous-arbre canonique ci-dessous, marquez présent/absent : kernel-jammy-src/, hardware/nvidia/, nvidia-oot/, nvgpu/, nvethernetrm/, nvdisplay/, hwpm/, kernel-devicetree/.
3. Si kernel-devicetree/generic-dts/dts/ existe, listez les noms de fichiers correspondant à tegra<chip>* où <chip> est le préfixe numérique de la famille de puces (voir la table de famille de puces ci-dessous). Enregistrez jusqu'à 30 résultats ; s'il y en a plus, enregistrez le décompte et une note « affichage des 30 premiers ».

Table de famille de puces (utilisée dans les étapes « Découverte BSP » et « Découverte de l'arborescence des sources »)

Dérivez <chip> de module.id :

Si module.id n'est pas dans cette table, enregistrez la puce comme unknown (module.id=<value>) et ignorez le filtre devicetree préfixé par puce.

Passage des documents

Pour chaque champ dans documents.* du profil chargé :

1. Classifiez la valeur comme URL (commence par http://, https://, ou ftp://) ou chemin local (autre chose).
2. Pour les URLs : enregistrez verbatim. Ne récupérez pas l'URL — la génération KB doit rester hors ligne. (Une skill future peut promouvoir à l'indexation profonde.)
3. Pour les chemins locaux : vérifiez os.path.exists. Enregistrez le chemin ; s'il manque sur disque, ajoutez (manquant).

La description d'une ligne pour chaque champ provient du marqueur dans ../../references/platform_template.yaml — supprimez le wrapper <OPTIONAL: …> et utilisez le texte interne.

Si le profil n'a pas de bloc documents:, rendez la section avec une seule ligne : _Aucun document enregistré — exécutezjetson-link-docs ou éditez manuellement le profil pour ajouter des références._

Rendre et écrire la KB

Rendez le markdown en utilisant la structure ci-dessous. Utilisez la date d'aujourd'hui (YYYY-MM-DD) dans l'en-tête. Écrasez toujours tout fichier KB existant à la destination — ne demandez pas avant d'écraser ; les réexécutions sont l'utilisation prévue.

Destination : target-platform/<profile-stem>.md.

Structure rendue

# Base de connaissances cible — <profile-stem>

> Généré <YYYY-MM-DD> à partir de `<bsp_image.root_path>` (version BSP `<bsp_image.version>`).
> Réexécutez `jetson-generate-kb` après l'extraction d'un nouveau BSP, l'application
> de correctifs, ou l'édition des champs du profil. Ce fichier est un
> instantané régénéré — ne l'éditez pas manuellement.

## Faits du profil

- **Kit de développement de référence :** `<reference_devkit.name>`
- **Module :** `<module.id>-<module.sku>` (`<chip family label>`)
- **Carte support de référence :** `<carrier.id>-<carrier.sku>`
- **Carte support personnalisée :** `<custom_carrier.name>` (`<custom_carrier.id>-<custom_carrier.sku>`)  _← omettez cette ligne si Cas 1_
- **Configuration flash active :** `<flash_config>`
- **Chemin BSP :** `<bsp_image.root_path>`
- **Version BSP :** `<bsp_image.version>`
- **Racine des sources :** `<source.root_path>`  _← ou « non enregistré » si NA_

## Disposition de l'image BSP

Répertoires de haut niveau sous `<bsp_image.root_path>` :

| Répertoire | Présent | Objectif |
|---|---|---|
| `rootfs/`     | ✓ / ✗ | rootfs userspace (nvpmodel, nvfan, unités systemd, etc.) |
| `bootloader/` | ✓ / ✗ | blobs firmware, BCT, dts MB1/MB2 |
| `kernel/`     | ✓ / ✗ | kernel précompilé + modules |
| `source/`     | ✓ / ✗ | arborescence source BSP (kernel, pilotes OOT, DT) |
| `tools/`      | ✓ / ✗ | assistants flash, jetson-io, kernel_flash |
| `nv_tegra/`   | ✓ / ✗ | tarballs firmware nvidia, kernel-supplements |

Configuration flash active `<flash_config>` : présente à
`<bsp_image.root_path>/<flash_config>` _ou_ `(manquant — vérifiez avant le flash)`.

### Fichiers nvpmodel correspondant au SKU actif

Filtrés de `rootfs/etc/nvpmodel/` par `nvpmodel_<module.id>_<module.sku>*.conf` :

- `<chaque correspondance, une par ligne>`

La variante active au démarrage est sélectionnée par `nvpower.sh` à partir de
`/proc/device-tree/compatible` plus l'état super / sécurité — voir
`jetson-customize-nvpmodel` pour les règles de résolution.

## Disposition de l'arborescence des sources

(omettez cette section entière si `source.root_path` est `NA`/absent)

Sous-arbres de haut niveau sous `<source.root_path>` :

| Sous-arbre | Présent | Objectif |
|---|---|---|
| `kernel-jammy-src/`   | ✓ / ✗ | sources kernel 5.x mainline |
| `hardware/nvidia/`    | ✓ / ✗ | DTs plateforme NVIDIA (par famille de puces) |
| `nvidia-oot/`         | ✓ / ✗ | modules kernel out-of-tree NVIDIA |
| `nvgpu/`              | ✓ / ✗ | pilote GPU |
| `nvethernetrm/`       | ✓ / ✗ | pilote ethernet |
| `nvdisplay/`          | ✓ / ✗ | pilote affichage |
| `hwpm/`               | ✓ / ✗ | moniteur performance matériel |
| `kernel-devicetree/`  | ✓ / ✗ | sources devicetree |

### Fichiers devicetree pour la famille de puces `<chip>`

(omettez si `kernel-devicetree/generic-dts/dts/` est absent)

Fichiers correspondant à `tegra<chip>*` sous `kernel-devicetree/generic-dts/dts/` :

- `<chaque correspondance, une par ligne — limité à 30, puis une note « premiers 30 de N »>`

## Documents

| Champ | Référence |
|---|---|
| Dossier racine des documents                    | `<doc_root>`                    _ou_ _non enregistré_ |
| Guide développeur BSP / Jetson Linux            | `<bsp_developer_guide>`         _ou_ _non enregistré_ |
| Manuel technique de référence Tegra SoC         | `<soc_tech_ref_manual>`         _ou_ _non enregistré_ |
| Fiche technique du module Jetson                | `<module_data_sheet>`           _ou_ _non enregistré_ |
| Guide de conception du module Jetson (PDG)      | `<module_design_guide>`         _ou_ _non enregistré_ |
| Guide thermique du module Jetson (TDG)          | `<module_thermal_design_guide>` _ou_ _non enregistré_ |
| Schéma du module Jetson                         | `<module_schematic>`            _ou_ _non enregistré_ |
| Spécification de la carte support de référence  | `<carrier_board_spec>`          _ou_ _non enregistré_ |
| Schéma de la carte support de référence         | `<carrier_schematic>`           _ou_ _non enregistré_ |
| Schéma de la carte support personnalisée        | `<custom_carrier_schematic>`    _ou_ _non enregistré / N/A (pas de carte support personnalisée)_ |
| Feuille de calcul pinmux du kit de référence    | `<ref_devkit_pinmux_xls>`       _ou_ _non enregistré_ |
| Feuille de calcul pinmux de la carte personnalisée | `<custom_carrier_pinmux_xls>`   _ou_ _non enregistré / N/A (pas de carte support personnalisée)_ |

(Les chemins locaux sont marqués ` (manquant)` s'ils sont absents sur disque. Les URLs sont
enregistrées verbatim et ne sont pas récupérées. Si `doc_root` est défini, marquez aussi
` (manquant)` s'il a disparu — cela signale que l'auto-mappage dans `jetson-link-docs`
ne fonctionnera pas à la réexécution.)

## Comment actualiser ce fichier

Réexécutez `jetson-generate-kb` chaque fois que l'un des éléments suivants change :

- le BSP à `bsp_image.root_path` est réextrait, corrigé ou mis à niveau,
- l'arborescence des sources à `source.root_path` change,
- les champs `bsp_image.*` ou `documents.*` du profil actif sont édités.

Ce fichier est écrasé à chaque exécution. Ne l'éditez pas manuellement — éditez
les données source (YAML du profil ou l'arborescence BSP) et réexécutez plutôt.

Confirmer

Imprimez un résumé court :

• Chemin de sortie : target-platform/<profile-stem>.md.
• Décompte des répertoires de haut niveau BSP et quels sous-arbres canoniques étaient présents / absents.
• Décompte des correspondances nvpmodel pour le SKU actif.
• Section arborescence-source : rendue ou ignorée (et pourquoi).
• Documents : décompte des champs enregistrés, décompte des chemins locaux marqués (manquant).

Si une skill aval a déclenché cette exécution, demandez à l'utilisateur de rémettre sa demande originale.

Pièges

• La KB est un instantané, pas une vue en direct. L'en-tête daté est autoritaire — s'il ne correspond pas à aujourd'hui, le BSP/sources/docs peuvent avoir changé en dessous. Réexécutez à la demande.
• Écrase toujours. Pas de demande avant de clobbrer la KB précédente à target-platform/<profile-stem>.md. C'est intentionnel — la réexécutabilité est tout l'intérêt. Demandez à l'utilisateur de ne pas éditer manuellement le fichier ; éditez le YAML du profil ou le BSP et régénérez.
• Refuse si bsp_image.root_path = NA. Un profil sans chemin BSP produit une KB sans contenu. Ne l'écrivez pas — pointez plutôt l'utilisateur vers le YAML du profil à remplir.
• Aucune récupération d'URL. Les URLs des documents sont enregistrées verbatim. La promotion à l'indexation profonde (HTTP HEAD, analyse PDF) dépasse le scope pour v0.1.
• Aucune analyse récursive. La découverte est un niveau de profondeur par répertoire, avec au maximum un glob ciblé (nvpmodel + devicetree). N'explorez jamais l'ensemble du BSP — c'est énorme et lent.
• Limitez les listes devicetree à 30 entrées pour garder la KB lisible. Affichez « premiers 30 de N » lors de la troncature.
• N'invoquez pas automatiquement à partir des skills de setup. Le setup peut suggérer l'exécution de cette skill dans son résumé, mais l'utilisateur opte pour cela. L'exécution automatique cache l'étape E/S et surprend les utilisateurs dont les chemins BSP/doc sont incomplets.
• Risque de collision de nom de fichier. La KB se trouve à target-platform/<stem>.md à côté de <stem>.yaml. N'accidentellement lisez pas les fichiers .md dans la logique de listing de profil de jetson-set-target (elle filtre déjà les *.yaml, mais vérifiez avant d'ajouter de nouveaux types de fichiers).
• La table de famille de puces est courte. Si un futur SKU de module est ajouté qui n'est pas dans la table, l'étape de filtre devicetree est ignorée — la KB notera chip: unknown plutôt que de fabriquer un préfixe <chip>. Mettez à jour la table de famille de puces de cette skill quand une nouvelle puce arrive.

Prérequis

• Profil cible actif résolu selon ../../context/target-platform-contract.md.
• bsp_image: enregistré par /jetson-init-image ; c'est le seul arborescence sur disque requise. Si source.root_path manque, rendez la KB sans la section arborescence-source.
• Optionnel : /jetson-init-source a déjà résolu source: quand l'utilisateur veut que la découverte d'arborescence-source soit incluse.
• Optionnel mais recommandé : /jetson-link-docs a déjà écrit le bloc documents:.

Limitations

• Lecture seule contre les arbres BSP et source ; n'édite jamais le YAML du profil ou ne réécrit les fichiers source.
• L'énumération des fichiers devicetree dépend de la table de famille de puces à l'intérieur de cette skill ; un SKU de module inconnu atterrit dans la KB comme chip: unknown plutôt qu'un préfixe fabriqué.
• La disposition des noms de fichiers est fixe à target-platform/<stem>.md pour rester à côté du YAML du profil ; renommer le YAML invalide le lien.

Dépannage

• bsp_image.root_path non trouvé — réexécutez /jetson-init-image pour que le BSP soit extrait et le chemin enregistré avant de régénérer la KB.
• La marche d'arborescence source capte les mauvais sous-arbres — le remplacement source.root_path est obsolète ; réexécutez /jetson-init-source ou corrigez le champ du profil.
• Bloc documents: manquant de la KB — /jetson-link-docs n'a jamais été exécuté ; la KB revient à « aucun document lié » plutôt que de deviner les chemins.
• Section devicetree courte / vide — la table de famille de puces ne couvre pas le SoC actif ; mettez à jour la table et réexécutez.

Références

• ../../context/target-platform-contract.md — contrat d'ordre de lecture que cette skill suit.
• ../../context/bsp-customization-workflow.md — origine de la liste canonique des sous-arbres BSP/source.
• ../../references/platform_template.yaml — source des descriptions d'une ligne du champ documents.
• ../jetson-init-target/SKILL.md — skill voisine qui rédige l'identité cible active.
• ../jetson-init-image/SKILL.md — skill voisine qui rédige les métadonnées d'image BSP que cette skill analyse.
• ../jetson-set-target/SKILL.md — skill voisine qui bascule le pointeur actif que cette skill résout.