jetson-generate-kb

Generate Target Knowledge Base

Overview

This skill produces a per-profile markdown reference at target-platform/<profile-stem>.md (sibling to the profile YAML). It bundles three things into one file so a future Claude session — or the user — can see the shape of the active target without re-walking the filesystem:

1. BSP image layout — top-level directories under bsp_image.root_path, presence of canonical subtrees (rootfs/, bootloader/, source/, …), and the nvpmodel variants matching the active module SKU.
2. Source tree layout — top-level subtrees under source.root_path (kernel-jammy-src/, hardware/nvidia/, nvidia-oot/, etc.) and devicetree files matching the chip family.
3. Documents — the documents.* references recorded in the profile, with local-path existence checks and one-line descriptions.

The KB is a snapshot, dated in its header. Re-run this skill whenever the underlying data changes — it is intentionally re-runnable and overwrites the previous KB on each run.

When to invoke

• After jetson-init-image prepares the BSP for a freshly authored profile.
• After re-extracting a BSP archive or applying patches under bsp_image.root_path.
• After updating the source tree at source.root_path.
• After editing bsp_image.* or documents.* in the profile YAML.
• When a downstream skill asks "where is X in this BSP?" and you'd rather check the KB than re-walk the tree.

Procedure

Resolve the active target

Resolve the active profile per the contract in ../../context/target-platform-contract.md; cache it in memory — the rest of the skill consumes only this profile. Record <profile-stem> (the bare filename minus .yaml) as the KB output filename stem.

Validate inputs

If bsp_image.root_path is set but the directory does not exist on disk, refuse with a clear message — do not fabricate a layout for a path that isn't there.

BSP discovery (under bsp_image.root_path)

Run only the following cheap operations — no recursive scans, no file content reads beyond directory listings:

1. ls -1 of bsp_image.root_path (one level deep). Record which directories are present.
2. For each canonical subtree below, mark present/absent: rootfs/, bootloader/, kernel/, source/, tools/, nv_tegra/.
3. Verify the active flash_config file exists at <bsp_image.root_path>/<flash_config>. Record its path or (missing).
4. List rootfs/etc/nvpmodel/ and filter to filenames matching nvpmodel_<module.id>_<module.sku>*.conf. Record each match. Use the lower-case module id (e.g. p3767) and the YAML-quoted sku string (e.g. 0001).

Source tree discovery (under source.root_path)

Skip this step entirely if source.root_path is NA or missing. Otherwise, run only:

1. ls -1 of source.root_path (one level deep).
2. For each canonical subtree below, mark present/absent: kernel-jammy-src/, hardware/nvidia/, nvidia-oot/, nvgpu/, nvethernetrm/, nvdisplay/, hwpm/, kernel-devicetree/.
3. If kernel-devicetree/generic-dts/dts/ exists, list filenames matching tegra<chip>* where <chip> is the chip-family numeric prefix (see chip-family map below). Record up to 30 hits; if more, record the count and a "showing first 30" note.

Chip-family map (used in the "BSP discovery" and "Source tree discovery" steps)

Derive <chip> from module.id:

If module.id is not in this table, record the chip as unknown (module.id=<value>) and skip the chip-prefixed devicetree filter.

Documents pass

For each field in documents.* from the loaded profile:

1. Classify the value as URL (starts with http://, https://, or ftp://) or local path (anything else).
2. For URLs: record verbatim. Do not fetch the URL — KB generation must remain offline. (A future skill can promote to deep indexing.)
3. For local paths: check os.path.exists. Record the path; if missing on disk, append (missing).

The one-line description for each field comes from the marker in ../../references/platform_template.yaml — strip the <OPTIONAL: …> wrapper and use the inner text.

If the profile has no documents: block, render the section with a single line: _No documents recorded — run jetson-link-docs or hand-edit the profile to add references._

Render and write the KB

Render the markdown using the structure below. Use today's date (YYYY-MM-DD) in the header. Always overwrite any existing KB file at the destination — do not prompt before overwriting; re-runs are the intended use.

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

Rendered structure

# 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.

Confirm

Print a short summary:

• Output path: target-platform/<profile-stem>.md.
• BSP top-level directory count and which canonical subtrees were present / absent.
• nvpmodel match count for the active SKU.
• Source-tree section: rendered or skipped (and why).
• Documents: count of recorded fields, count of local paths flagged (missing).

If a downstream skill triggered this run, tell the user to re-issue their original request.

Gotchas

• The KB is a snapshot, not a live view. The dated header is authoritative — if it doesn't match today, the BSP/source/docs may have changed underneath. Re-run on demand.
• Always overwrites. No prompt before clobbering the previous KB at target-platform/<profile-stem>.md. This is intentional — re-runnability is the whole point. Tell the user not to hand-edit the file; edit profile YAML or the BSP and regenerate.
• Refuses on bsp_image.root_path = NA. A profile with no BSP path produces a content-free KB. Do not write one — instead, point the user at the profile YAML to fill in.
• No URL fetching. Document URLs are recorded verbatim. Promoting to deep indexing (HTTP HEAD, PDF parsing) is out of scope for v0.1.
• No recursive scans. Discovery is one level deep per directory, with at most one targeted glob (nvpmodel + devicetree). Never walk the entire BSP — it's huge and slow.
• Cap devicetree listings at 30 entries to keep the KB readable. Show "first 30 of N" when truncating.
• Don't auto-invoke from setup skills. Setup may suggest running this skill in its summary, but the user opts in. Auto-running hides the I/O step and surprises users whose BSP/doc paths are incomplete.
• Filename collision risk. The KB sits at target-platform/<stem>.md next to <stem>.yaml. Don't accidentally read .md files in the profile-listing logic of jetson-set-target (it already filters to *.yaml, but check before adding new file types).
• Chip-family map is short. If a future module SKU is added that isn't in the map, the devicetree filter step is skipped — the KB will note chip: unknown rather than fabricate a <chip> prefix. Update this skill's chip-family table when a new chip lands.

Prerequisites

• Active target profile resolved per ../../context/target-platform-contract.md.
• bsp_image: recorded by /jetson-init-image; this is the only required on-disk tree. If source.root_path is missing, render the KB without the source-tree section.
• Optional: /jetson-init-source already resolved source: when the user wants source-tree discovery included.
• Optional but recommended: /jetson-link-docs already wrote the documents: block.

Limitations

• Read-only against the BSP and source trees; never edits the profile YAML or rewrites source files.
• Devicetree-file enumeration depends on the chip-family table inside this skill; an unknown module SKU lands in the KB as chip: unknown rather than a fabricated prefix.
• Filename layout is fixed at target-platform/<stem>.md to stay next to the profile YAML; renaming the YAML invalidates the link.

Troubleshooting

• bsp_image.root_path not found — re-run /jetson-init-image so the BSP is extracted and the path is recorded before regenerating the KB.
• Source tree walk picks up wrong subtrees — source.root_path override is stale; rerun /jetson-init-source or correct the profile field.
• documents: block missing from the KB — /jetson-link-docs was never run; the KB falls back to "no documents bound" rather than guessing paths.
• Devicetree section short / empty — chip-family table doesn't cover the active SoC; update the table and rerun.

References

• ../../context/target-platform-contract.md — read-order contract this skill follows.
• ../../context/bsp-customization-workflow.md — origin of the canonical BSP/source subtree list.
• ../../references/platform_template.yaml — source of the documents-field one-line descriptions.
• ../jetson-init-target/SKILL.md — sibling skill that authors the active target identity.
• ../jetson-init-image/SKILL.md — sibling skill that authors the BSP image metadata this skill scans.
• ../jetson-set-target/SKILL.md — sibling skill that flips the active pointer this skill resolves.