jetson-generate-kb

ターゲットナレッジベースの生成

概要

このスキルは、プロファイルごとの Markdown リファレンスを target-platform/<profile-stem>.md（プロファイル YAML と同じ階層）に生成します。今後の Claude セッション、またはユーザーがファイルシステムを再確認しなくてもアクティブなターゲットの構成を把握できるよう、次の3つを1つのファイルにまとめます。

1. BSP イメージのレイアウト — bsp_image.root_path 直下のディレクトリ、標準的なサブツリー（rootfs/、bootloader/、source/ など）の有無、アクティブなモジュール SKU に一致する nvpmodel バリアント。
2. ソースツリーのレイアウト — source.root_path 直下のサブツリー（kernel-jammy-src/、hardware/nvidia/、nvidia-oot/ など）と、チップファミリーに一致するデバイスツリーファイル。
3. ドキュメント — プロファイルに記録されている documents.* の参照。ローカルパスの存在確認と1行の説明を含みます。

ナレッジベースは、ヘッダーに日付が記録されたスナップショットです。元データが変更されたときは、このスキルを再実行してください。このスキルは再実行を前提としており、実行するたびに以前のナレッジベースを上書きします。

実行するタイミング

• 新しく作成したプロファイル向けに jetson-init-image で BSP を準備した後。
• BSP アーカイブを再展開した後、または bsp_image.root_path にパッチを適用した後。
• source.root_path のソースツリーを更新した後。
• プロファイル YAML の bsp_image.* または documents.* を編集した後。
• 後続のスキルが「この BSP の X はどこにありますか？」と尋ねたときに、ツリーを再確認するよりナレッジベースを参照したい場合。

手順

アクティブなターゲットを解決する

../../context/target-platform-contract.md の仕様に従ってアクティブなプロファイルを解決し、メモリーにキャッシュします。このスキルの残りの処理では、このプロファイルだけを使用します。<profile-stem>（拡張子 .yaml を除いたファイル名）を、ナレッジベースの出力ファイル名のステムとして記録します。

入力を検証する

フィールド	ナレッジベースに必須か	欠落している場合
bsp_image.root_path	はい	拒否します。スキャン対象の BSP ルートがないナレッジベースは YAML の言い換えにすぎません。ユーザーに jetson-init-image の実行、またはプロファイルの手動編集を案内します。
source.root_path	いいえ	ソースツリーのセクションを省略し、ナレッジベースに「source_root が記録されていません」と記載します。
documents.*	いいえ	空の Documents テーブルを出力し、「ドキュメントが記録されていません」という注記を付けます。

bsp_image.root_path が設定されていても、ディスク上にそのディレクトリが存在しない場合は、明確なメッセージを表示して拒否します。存在しないパスのレイアウトを捏造しないでください。

BSP の検出（bsp_image.root_path 配下）

次の負荷の小さい操作のみを実行します。再帰スキャンや、ディレクトリ一覧を超えるファイル内容の読み取りは行いません。

1. bsp_image.root_path に対して ls -1 を実行します（1階層のみ）。存在するディレクトリを記録します。
2. 次の標準サブツリーそれぞれについて、存在または不在を記録します。 rootfs/、bootloader/、kernel/、source/、tools/、nv_tegra/。
3. アクティブな flash_config ファイルが <bsp_image.root_path>/<flash_config> に存在することを確認します。そのパス、または (missing) を記録します。
4. rootfs/etc/nvpmodel/ を一覧表示し、nvpmodel_<module.id>_<module.sku>*.conf に一致するファイル名に絞り込みます。一致したファイルをそれぞれ記録します。小文字のモジュール ID（例：p3767）と、YAML で引用符付きの SKU 文字列（例：0001）を使用します。

ソースツリーの検出（source.root_path 配下）

source.root_path が NA または未設定の場合、この手順全体を省略します。それ以外の場合は、次の操作のみを実行します。

1. source.root_path に対して ls -1 を実行します（1階層のみ）。
2. 次の標準サブツリーそれぞれについて、存在または不在を記録します。 kernel-jammy-src/、hardware/nvidia/、nvidia-oot/、nvgpu/、nvethernetrm/、nvdisplay/、hwpm/、kernel-devicetree/。
3. kernel-devicetree/generic-dts/dts/ が存在する場合、<chip> がチップファミリーの数値プレフィックス（下記のチップファミリーマップを参照）となる tegra<chip>* に一致するファイル名を一覧表示します。一致した項目は最大30件まで記録します。それを超える場合は件数と「最初の30件を表示」という注記を記録します。

チップファミリーの対応表（「BSP discovery」および「Source tree discovery」の手順で使用）

module.id から <chip> を導き出します。

module.id	チップファミリー	<chip> の接頭辞
p3701、p3767	T234 — Orin	234
p3834	T264 — Thor	264

module.id がこの表にない場合は、チップを unknown (module.id=<value>) と記録し、チップ接頭辞によるデバイスツリーの フィルターをスキップします。

ドキュメントの処理

読み込んだプロファイルの documents.* にある各フィールドについて、次の処理を行います。

1. 値をURL（http://、https://、 ftp:// で始まる）またはローカルパス（それ以外）に分類します。
2. URL の場合：そのまま記録します。URL を取得しないでください — KB の生成はオフラインのままにする必要があります。（将来、詳細なインデックス作成に拡張できます。）
3. ローカルパスの場合：os.path.exists を確認します。パスを記録し、ディスク上に 存在しない場合は (missing) を追加します。

各フィールドの1行の説明は、 ../../references/platform_template.yaml のマーカーから取得します — <OPTIONAL: …> のラッパーを取り除き、中のテキストを使用します。

プロファイルに documents: ブロックがない場合は、次の1行だけでセクションを描画します。 _ドキュメントは記録されていません — jetson-link-docs を実行するか、プロファイルを手動編集して参照を追加してください。_

KB を描画して書き込む

以下の構造で Markdown を描画します。ヘッダーには今日の日付 （YYYY-MM-DD）を使用します。出力先に既存の KB ファイルがあれば、必ず上書きしてください — 上書き前に確認を求めないでください。再実行を想定しています。

出力先：target-platform/<profile-stem>.md。

描画する構造

# Target knowledge base — <profile-stem>

> Generated <YYYY-MM-DD> from `<bsp_image.root_path>` (BSP version `<bsp_image.version>`).
> Re-run `jetson-generate-kb` after extracting a new BSP, applying
> patches, or editing profile fields. This file is a regenerated
> snapshot — do not hand-edit.

## Profile facts

- **Reference devkit:** `<reference_devkit.name>`
- **Module:** `<module.id>-<module.sku>` (`<chip family label>`)
- **Reference carrier:** `<carrier.id>-<carrier.sku>`
- **Custom carrier:** `<custom_carrier.name>` (`<custom_carrier.id>-<custom_carrier.sku>`)  _← omit this row if Case 1_
- **Active flash conf:** `<flash_config>`
- **BSP path:** `<bsp_image.root_path>`
- **BSP version:** `<bsp_image.version>`
- **Source root:** `<source.root_path>`  _← or "_not recorded_" if NA_

## BSP image layout

Top-level directories under `<bsp_image.root_path>`:

| Directory | Present | Purpose |
|---|---|---|
| `rootfs/`     | ✓ / ✗ | userspace rootfs (nvpmodel, nvfan, systemd units, etc.) |
| `bootloader/` | ✓ / ✗ | firmware blobs, BCT, MB1/MB2 dts |
| `kernel/`     | ✓ / ✗ | prebuilt kernel + modules |
| `source/`     | ✓ / ✗ | BSP source tree (kernel, OOT drivers, DT) |
| `tools/`      | ✓ / ✗ | flashing helpers, jetson-io, kernel_flash |
| `nv_tegra/`   | ✓ / ✗ | nvidia firmware tarballs, kernel-supplements |

Active flash conf `<flash_config>`: present at
`<bsp_image.root_path>/<flash_config>` _or_ `(missing — verify before flashing)`.

### nvpmodel files matching the active SKU

Filtered from `rootfs/etc/nvpmodel/` by `nvpmodel_<module.id>_<module.sku>*.conf`:

- `<each match, one per line>`

The active variant at boot is selected by `nvpower.sh` from
`/proc/device-tree/compatible` plus super / safety state — see
`jetson-customize-nvpmodel` for the resolution rules.

## Source tree layout

(omit this whole section if `source.root_path` is `NA`/missing)

Top-level subtrees under `<source.root_path>`:

| Subtree | Present | Purpose |
|---|---|---|
| `kernel-jammy-src/`   | ✓ / ✗ | mainline 5.x kernel sources |
| `hardware/nvidia/`    | ✓ / ✗ | NVIDIA platform DTs (per chip family) |
| `nvidia-oot/`         | ✓ / ✗ | NVIDIA out-of-tree kernel modules |
| `nvgpu/`              | ✓ / ✗ | GPU driver |
| `nvethernetrm/`       | ✓ / ✗ | ethernet driver |
| `nvdisplay/`          | ✓ / ✗ | display driver |
| `hwpm/`               | ✓ / ✗ | hardware performance monitor |
| `kernel-devicetree/`  | ✓ / ✗ | devicetree sources |

### Devicetree files for chip family `<chip>`

(omit if `kernel-devicetree/generic-dts/dts/` is absent)

Files matching `tegra<chip>*` under `kernel-devicetree/generic-dts/dts/`:

- `<each match, one per line — cap at 30, then a "first 30 of N" note>`

## Documents

| Field | Reference |
|---|---|
| Documents root folder                    | `<doc_root>`                    _or_ _not recorded_ |
| BSP / Jetson Linux developer guide       | `<bsp_developer_guide>`         _or_ _not recorded_ |
| Tegra SoC Technical Reference Manual     | `<soc_tech_ref_manual>`         _or_ _not recorded_ |
| Jetson module data sheet                 | `<module_data_sheet>`           _or_ _not recorded_ |
| Jetson module design guide (PDG)         | `<module_design_guide>`         _or_ _not recorded_ |
| Jetson module thermal design guide (TDG) | `<module_thermal_design_guide>` _or_ _not recorded_ |
| Jetson module schematic                  | `<module_schematic>`            _or_ _not recorded_ |
| Reference carrier board specification    | `<carrier_board_spec>`          _or_ _not recorded_ |
| Reference carrier schematic              | `<carrier_schematic>`           _or_ _not recorded_ |
| Custom carrier schematic                 | `<custom_carrier_schematic>`    _or_ _not recorded / N/A (no custom carrier)_ |
| Reference-devkit pinmux spreadsheet      | `<ref_devkit_pinmux_xls>`       _or_ _not recorded_ |
| Custom-carrier pinmux spreadsheet        | `<custom_carrier_pinmux_xls>`   _or_ _not recorded / N/A (no custom carrier)_ |

(Local paths are tagged ` (missing)` if absent on disk. URLs are
recorded verbatim and not fetched. If `doc_root` is set, also tag
` (missing)` on it if the directory itself is gone — that signals
auto-mapping in `jetson-link-docs` won't work on a re-run.)

## How to refresh this file

Re-run `jetson-generate-kb` whenever any of the following changes:

- the BSP at `<bsp_image.root_path>` is re-extracted, patched, or upgraded,
- the source tree at `<source.root_path>` changes,
- the active profile's `bsp_image.*` or `documents.*` fields are edited.

This file is overwritten on every run. Do not hand-edit it — edit the
source data (profile YAML or the BSP tree) and re-run instead.

確認

次の概要を簡潔に表示します。

• 出力パス：target-platform/<profile-stem>.md。
• BSP のトップレベルディレクトリ数と、存在した／しなかった正規サブツリー。
• アクティブな SKU に一致した nvpmodel の件数。
• ソースツリーのセクション：描画したか、スキップしたか（その理由も含む）。
• ドキュメント：記録したフィールド数、(missing) としてフラグ付けしたローカルパス数。

下流のスキルによってこの実行が開始された場合は、元のリクエストを再度実行するようユーザーに伝えてください。

注意事項

• KB はスナップショットであり、ライブ表示ではありません。 日付入りヘッダーが基準となります — 今日の日付と一致しない場合、BSP／ソース／ドキュメントの内容がその後変わっている可能性があります。必要に応じて再実行してください。
• 常に上書きします。 target-platform/<profile-stem>.md にある前回の KB を上書きする前に確認を求めません。これは意図した動作です — 再実行可能であることが目的です。ユーザーにはファイルを手動編集せず、プロファイル YAML または BSP を編集して再生成するよう伝えてください。
• bsp_image.root_path = NA の場合は処理しません。 BSP パスのないプロファイルからは内容のない KB が生成されます。書き込まず、プロファイル YAML に値を入力するようユーザーに案内してください。
• URL は取得しません。 ドキュメントの URL はそのまま記録します。詳細なインデックス作成（HTTP HEAD、PDF の解析）への拡張は v0.1 の範囲外です。
• 再帰スキャンは行いません。 各ディレクトリの検出は1階層までで、対象を絞った glob（nvpmodel とデバイスツリー）は最大1つです。BSP 全体を走査しないでください — 非常に大きく、時間がかかります。
• デバイスツリーの一覧は30件までに制限し、KB を読みやすく保ってください。切り詰める場合は「全 N 件中、先頭30件」と表示します。
• セットアップスキルから自動実行しないでください。 セットアップ時に概要でこのスキルの実行を提案することはできますが、実行するかどうかはユーザーに委ねます。自動実行すると I/O の手順が隠れ、BSP／ドキュメントのパスが不完全なユーザーを驚かせます。
• ファイル名の衝突リスク。 KB は <stem>.yaml の隣にある target-platform/<stem>.md に保存されます。jetson-set-target のプロファイル一覧処理で .md ファイルを誤って読み込まないようにしてください（現状は *.yaml のみに絞り込んでいますが、新しいファイル形式を追加する前に確認してください）。
• チップファミリーの対応表は短いものです。 対応表にない新しいモジュール SKU が追加された場合、デバイスツリーのフィルター処理はスキップされます — KB には <chip> の接頭辞を捏造せず、chip: unknown と記録されます。新しいチップが追加されたら、このスキルのチップファミリー対応表を更新してください。

前提条件

• ../../context/target-platform-contract.mdに従って、アクティブなターゲットプロファイルが解決されていること。
• /jetson-init-imageによってbsp_image:が記録されていること。これがディスク上で必要な唯一のツリーです。source.root_pathがない場合、ソースツリーのセクションを含めずにKBを生成します。
• 任意：ユーザーがソースツリーの検出を含めたい場合は、/jetson-init-sourceによってsource:がすでに解決されていること。
• 任意（推奨）：/jetson-link-docsによってdocuments:ブロックがすでに書き込まれていること。

制限事項

• BSPツリーとソースツリーに対して読み取り専用で動作します。プロファイルのYAMLを編集したり、ソースファイルを書き換えたりすることはありません。
• デバイスツリーファイルの列挙は、このスキル内のチップファミリーテーブルに依存します。不明なモジュールSKUは、推測したプレフィックスではなく、chip: unknownとしてKBに登録されます。
• ファイル名の配置先は、プロファイルYAMLの隣に置くためtarget-platform/<stem>.mdで固定されています。YAMLの名前を変更すると、リンクが無効になります。

トラブルシューティング

• bsp_image.root_pathが見つからない — BSPを展開し、KBを再生成する前にパスを記録するため、/jetson-init-imageを再実行してください。
• ソースツリーの走査で誤ったサブツリーが取得される — source.root_pathのオーバーライドが古くなっています。/jetson-init-sourceを再実行するか、プロファイルのフィールドを修正してください。
• KBにdocuments:ブロックがない — /jetson-link-docsがまだ実行されていません。KBはパスを推測せず、「ドキュメントが紐付けられていません」として処理します。
• デバイスツリーのセクションが短い／空 — チップファミリーテーブルがアクティブなSoCに対応していません。テーブルを更新して再実行してください。

参照

• ../../context/target-platform-contract.md — このスキルが従う読み取り順序の契約です。
• ../../context/bsp-customization-workflow.md — 正式なBSP／ソースのサブツリー一覧の出典です。
• ../../references/platform_template.yaml — documentsフィールドの1行説明の出典です。
• ../jetson-init-target/SKILL.md — アクティブなターゲットの識別情報を作成する兄弟スキルです。
• ../jetson-init-image/SKILL.md — このスキルがスキャンするBSPイメージのメタデータを作成する兄弟スキルです。
• ../jetson-set-target/SKILL.md — このスキルが解決するアクティブポインターを切り替える兄弟スキルです。