jetson-promote-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Promote BSP Image

推广BSP镜像

Purpose

目的

Stage every Customize-* and Build output into

bsp_image

so it is ready for

/jetson-flash-image

. This is the promote leg of Deploy — it copies files, never flashes and never builds.

将所有Customize-*和构建输出暂存到

bsp_image

中，使其为

/jetson-flash-image

做好准备。这是部署流程的推广环节——仅执行文件复制操作，绝不进行烧录或构建。

Prerequisites

前置条件

Active target-platform profile with both
```
source:
```
and
```
bsp_image:
```
resolved (run
```
/jetson-init-source
```
and
```
/jetson-init-image
```
first).
```
<source.root_path>/Linux_for_Tegra/
```
initialized as a git repo (overlay tracker) with a clean working tree.

<bsp_image.root_path>/Linux_for_Tegra/

extracted from a BSP tarball +

apply_binaries.sh

already run.

```
git
```
,
```
yq
```
,
```
cmp
```
, and
```
sudo
```
(for
```
rootfs/*
```
destinations) on the host.

<source.root_path>/.build-manifest.yaml

.build-state.yaml

from

/jetson-build-source

(required when kernel-side repos have customize-* commits).

已激活的目标平台配置文件，且
```
source:
```
和
```
bsp_image:
```
均已解析（需先运行
```
/jetson-init-source
```
和
```
/jetson-init-image
```
）。
```
<source.root_path>/Linux_for_Tegra/
```
已初始化为git仓库（覆盖跟踪器），且工作树干净。

<bsp_image.root_path>/Linux_for_Tegra/

已从BSP压缩包解压完成，且已执行

apply_binaries.sh

。

主机上已安装
```
git
```
、
```
yq
```
、
```
cmp
```
和
```
sudo
```
（用于
```
rootfs/*
```
目标路径）。
存在来自
```
/jetson-build-source
```
的
```
<source.root_path>/.build-manifest.yaml
```
+
```
.build-state.yaml
```
（当内核端仓库包含customize-*提交时为必需）。

Overview

概述

This is the promote leg of Deploy — see

../../context/bsp-customization-workflow.md

for the pipeline view. The two channels this skill walks are:

Channel	Source	Carrier	Owner
Overlay tracker	`<source.root_path>/Linux_for_Tegra/` (git repo at HEAD)	Customize-* outputs that don't require a build (e.g. `nvfancontrol.conf` , `nvpmodel.conf` , BPMP DTB hand-edits)	Customize `customize-*` skills commit here
Build manifest	`<source.root_path>/.build-manifest.yaml`	Rebuilt kernel `Image` , in-tree `.ko` , OOT `.ko` , NVIDIA DTBs	Build `jetson-build-source` writes here

The skill computes the union of files to copy and writes each into

<bsp_image.root_path>/Linux_for_Tegra/

with diff-aware skip-if-identical logic. When the copy pass touches the kernel

Image

or anything under

rootfs/lib/modules/

, it also rebuilds the initramfs via NVIDIA's

tools/l4t_update_initrd.sh

so the freshly promoted kernel + modules ship in the initrd the bootloader actually loads. After it returns,

bsp_image

carries every Customize and Build output. The skill does not flash and does not modify the workspace.

这是部署流程的推广环节——如需查看流水线视图，请参阅

../../context/bsp-customization-workflow.md

。本技能涉及两个渠道：

渠道	源路径	承载内容	维护方
覆盖跟踪器	`<source.root_path>/Linux_for_Tegra/` （处于HEAD状态的git仓库）	无需构建的Customize-*输出（例如 `nvfancontrol.conf` 、 `nvpmodel.conf` 、BPMP DTB手动编辑文件）	Customize类 `customize-*` 技能在此提交内容
构建清单	`<source.root_path>/.build-manifest.yaml`	重新构建的内核 `Image` 、内核内 `.ko` 文件、内核外 `.ko` 文件、NVIDIA DTB文件	Build类 `jetson-build-source` 负责写入此清单

本技能计算需要复制的文件集合，并将每个文件写入

<bsp_image.root_path>/Linux_for_Tegra/

，同时采用差异感知的“内容相同则跳过”逻辑。当复制操作涉及内核

Image

或

rootfs/lib/modules/

下的任何文件时，还会通过NVIDIA的

tools/l4t_update_initrd.sh

重新构建initramfs，确保新推广的内核和模块包含在引导加载程序实际加载的initrd中。执行完成后，

bsp_image

将包含所有Customize和Build输出。本技能绝不执行烧录操作，也绝不修改工作区。

When to invoke

调用时机

First leg of the typical Deploy chain

jetson-promote-image → jetson-flash-image → jetson-validate-image

Standalone, when the user wants
```
bsp_image
```
updated but isn't ready to flash yet (e.g. to inspect resolved files, run an out-of-band build that reads bsp_image, or hand bsp_image to a separate flashing host).

典型部署链的第一个环节：

jetson-promote-image → jetson-flash-image → jetson-validate-image

。

独立调用场景：用户希望更新
```
bsp_image
```
但暂不准备烧录时（例如检查解析后的文件、运行读取bsp_image的离线构建，或将bsp_image交付给单独的烧录主机）。

Procedure

操作步骤

Resolve active target + paths

解析激活的目标与路径

Resolve the active profile per the contract in

../../context/target-platform-contract.md

Refuse and route in these cases:

Condition	Refuse with
No active profile, or `active: NA`	Route to `/jetson-set-target` or `/jetson-init-target` .
Profile lacks `bsp_image:`	Route to `/jetson-init-image` .
`<bsp_image.root_path>/Linux_for_Tegra/` missing	Route to `/jetson-init-image` .
`<source.root_path>/Linux_for_Tegra/` missing or not a git repo	Route to `/jetson-init-source` .

Resolve paths:

```
<workspace>
```
= parent of the active profile's
```
target-platform/
```
directory (discovered at load time).

<bsp_image.root_path>

from

bsp_image.root_path:

if present, else

<workspace>/Image

<source.root_path>

from

source.root_path:

if present, else

<workspace>/Source

Bind shell variables for the rest of the procedure:

bash

LFT_SRC="<source.root_path>/Linux_for_Tegra"   # overlay tracker
LFT_DST="<bsp_image.root_path>/Linux_for_Tegra"
MANIFEST="<source.root_path>/.build-manifest.yaml"   # build outputs

根据

../../context/target-platform-contract.md

中的约定解析激活的配置文件。

在以下情况下拒绝执行并引导用户操作：

条件	拒绝提示
无激活配置文件，或 `active: NA`	引导至 `/jetson-set-target` 或 `/jetson-init-target` 。
配置文件缺少 `bsp_image:`	引导至 `/jetson-init-image` 。
`<bsp_image.root_path>/Linux_for_Tegra/` 不存在	引导至 `/jetson-init-image` 。
`<source.root_path>/Linux_for_Tegra/` 不存在或未初始化为git仓库	引导至 `/jetson-init-source` 。

解析路径：

```
<workspace>
```
= 激活配置文件的
```
target-platform/
```
目录的父目录（加载时自动发现）。

<bsp_image.root_path>

：若配置中存在

bsp_image.root_path:

则使用该值，否则为

<workspace>/Image

。

<source.root_path>

：若配置中存在

source.root_path:

则使用该值，否则为

<workspace>/Source

。

为后续步骤绑定shell变量：

bash

LFT_SRC="<source.root_path>/Linux_for_Tegra"   # 覆盖跟踪器
LFT_DST="<bsp_image.root_path>/Linux_for_Tegra"
MANIFEST="<source.root_path>/.build-manifest.yaml"   # 构建输出

Validate the two channels

验证两个渠道

The skill needs at least one channel populated. Refuse if the overlay tracker has uncommitted changes (

status --porcelain

non-empty), if

$MANIFEST

exists but doesn't parse as YAML, or if both channels are empty. Records

OVERLAY_HAS_COMMITS

OVERLAY_HEAD

and

MANIFEST_PRESENT

for downstream steps.

See

references/copy-pass-snippets.md

for the shell snippet and refuse messages.

本技能需要至少一个渠道包含内容。若覆盖跟踪器存在未提交的更改（

status --porcelain

输出非空）、

$MANIFEST

存在但无法解析为YAML，或两个渠道均为空，则拒绝执行。记录

OVERLAY_HAS_COMMITS

OVERLAY_HEAD

和

MANIFEST_PRESENT

供后续步骤使用。

有关shell代码片段和拒绝提示，请参阅

references/copy-pass-snippets.md

。

Verify build-source freshness

验证构建源的新鲜度

Refuse if

.build-state.yaml

shows any kernel-side repo in

Source/bsp_sources/

dirty since the last

/jetson-build-source

— otherwise the copy pass would silently ship stale artifacts. Detection rules + shell snippet in

references/build-source-freshness-gate.md

. Records

BUILD_FRESH=1

若

.build-state.yaml

显示

Source/bsp_sources/

下的任何内核端仓库自上次运行

/jetson-build-source

后发生更改，则拒绝执行——否则复制操作会静默交付过时的产物。检测规则和shell代码片段请参阅

references/build-source-freshness-gate.md

。记录

BUILD_FRESH=1

。

Pre-promote collision check (overlay only)

推广前冲突检查（仅覆盖渠道）

When the overlay tracks a remote, refuse if upstream has commits not yet pulled. Skip gracefully when no remote is configured (the default

git init

empty tracker from

jetson-init-source

). Manifest channel has no git remote concept — this check is overlay-only. Records

COLLISION_CHECK

for the Summary.

See

references/copy-pass-snippets.md

for the shell snippet.

当覆盖跟踪器关联远程仓库时，若上游存在未拉取的提交则拒绝执行。当未配置远程仓库时（

jetson-init-source

默认创建的空git跟踪器），则跳过此检查。构建清单渠道无git远程仓库概念——此检查仅适用于覆盖渠道。记录

COLLISION_CHECK

供摘要使用。

有关shell代码片段，请参阅

references/copy-pass-snippets.md

。

Enumerate sources (both channels)

枚举源文件（两个渠道）

Channel A — overlay:

git ls-files

against

$LFT_SRC

is the source of truth (transparent to symlink mounts when

source.repos.Linux_for_Tegra

was overridden, excludes untracked /

.gitignore

d files). Each entry maps

src = $LFT_SRC/<rel>

→

dst = $LFT_DST/<rel>

Channel B — manifest: parse

artifacts[].{src,dst}

from

$MANIFEST

. Refuse if any

src

is missing on disk (build was interrupted, or manifest stale — re-run

/jetson-build-source

). The manifest schema is written by

jetson-build-source

v0.2.0.

See

references/copy-pass-snippets.md

for both shell snippets and the manifest YAML schema.

渠道A — 覆盖：以

$LFT_SRC

为目标执行

git ls-files

作为事实来源（当

source.repos.Linux_for_Tegra

被覆盖时，对符号链接挂载透明，排除未跟踪或被

.gitignore

忽略的文件）。每个条目映射为

src = $LFT_SRC/<rel>

→

dst = $LFT_DST/<rel>

。

渠道B — 构建清单：从

$MANIFEST

解析

artifacts[].{src,dst}

。若任何

src

在磁盘上不存在（构建中断或清单过时），则拒绝执行并提示用户重新运行

/jetson-build-source

。清单 schema 由

jetson-build-source

v0.2.0定义。

有关两个渠道的shell代码片段和清单YAML schema，请参阅

references/copy-pass-snippets.md

。

Diff-aware copy into bsp_image

差异感知复制到bsp_image

Iterate the union of overlay files and manifest entries. For each

dst

: if byte-identical, skip; otherwise

cp -p

(with

sudo

for

rootfs/*

destinations, where the sample rootfs was extracted as root). Tag

INITRD_DIRTY=1

on any

rootfs/lib/modules/*

kernel/Image

write — the "Refresh initramfs" step gates on this flag. Counts /

FIRST

LAST

are recorded for the Summary.

Fail-fast: if any

cp

fails, surface the failed path and stop.

bsp_image

may be left partially updated — re-running after fixing the cause resumes via the diff-aware skip. Channel order is overlay first, then manifest: on a

dst

collision the manifest wins (freshly built artifact beats the older overlay copy).

See

references/copy-pass-snippets.md

for the

copy_one()

function and the two driving loops.

遍历覆盖文件和清单条目的并集。对于每个

dst

：若内容字节相同则跳过；否则执行

cp -p

（对于

rootfs/*

目标路径使用

sudo

，因为示例根文件系统是以root权限解压的）。当写入

rootfs/lib/modules/*

或

kernel/Image

时标记

INITRD_DIRTY=1

——“刷新initramfs”步骤将基于此标志触发。记录复制计数、

FIRST

和

LAST

供摘要使用。

快速失败：若任何

cp

操作失败，则显示失败路径并停止。

bsp_image

可能处于部分更新状态——修复问题后重新运行，差异感知复制会跳过已推广的文件。渠道顺序：先覆盖渠道，再构建清单渠道：当

dst

路径冲突时，构建清单渠道优先（新构建的产物优于旧的覆盖副本）。

有关

copy_one()

函数和两个驱动循环，请参阅

references/copy-pass-snippets.md

。

Mirror kernel Image into rootfs (when kernel changed)

将内核Image镜像到rootfs（当内核更改时）

The kernel

Image

lives in two paths inside

bsp_image

<LFT_DST>/kernel/Image

(read by the flash tool) and

<LFT_DST>/rootfs/boot/Image

(the rootfs-side copy, visible as

/boot/Image

from inside the rootfs chroot the refresh tool will run in). The build manifest only carries the

kernel/Image

dst, so this step mirrors

kernel/Image

→

rootfs/boot/Image

(diff-aware, no-op when already in sync) so the chrooted refresh tool resolves the kernel against the freshly promoted binary, not the stale rootfs copy. The mirror also sets

INITRD_DIRTY=1

so a kernel-only promote (no

rootfs/lib/modules/*

writes) still triggers the refresh.

See

references/kernel-image-and-initramfs.md

for the shell snippet, the failure mode this prevents, and the

INITRD_DIRTY

corner case.

内核

Image

在

bsp_image

中有两个路径：

<LFT_DST>/kernel/Image

（供烧录工具读取）和

<LFT_DST>/rootfs/boot/Image

（根文件系统侧副本，在刷新工具将运行的根文件系统chroot中可见为

/boot/Image

）。构建清单仅包含

kernel/Image

目标路径，因此此步骤将

kernel/Image

镜像到

rootfs/boot/Image

（差异感知，内容同步时无操作），确保chroot环境下的刷新工具使用新推广的二进制文件，而非过时的根文件系统副本。镜像操作还会设置

INITRD_DIRTY=1

，因此仅推广内核（未写入

rootfs/lib/modules/*

）时仍会触发刷新。

有关shell代码片段、此步骤避免的故障模式以及

INITRD_DIRTY

的边界情况，请参阅

references/kernel-image-and-initramfs.md

。

Refresh initramfs (when kernel or modules changed)

刷新initramfs（当内核或模块更改时）

Run

tools/l4t_update_initrd.sh

from

<LFT_DST>/

whenever

INITRD_DIRTY=1

(set by the diff-aware copy or the mirror step above). The tool chroots into

rootfs/

, runs NVIDIA's

nv-update-initrd

, and writes both

<LFT_DST>/bootloader/l4t_initrd.img

(used by the flash tool) and

<LFT_DST>/rootfs/boot/initrd

(

/boot/initrd

on the DUT). Idempotent; ~30 s. Skip when

INITRD_DIRTY=0

(overlay-only edits). DUT-side workarounds (

update-initramfs -u

+ manual

cp

) are out of scope — fix the gap here so flash ships a coherent image.

See

references/kernel-image-and-initramfs.md

for the shell snippet, refuse paths, the "module shadowing" and "vermagic skew" failure modes the rebuild closes, and why

bootloader/initrd

(a different file) is left alone.

每当

INITRD_DIRTY=1

（由差异感知复制或上述镜像步骤设置）时，从

<LFT_DST>/

运行

tools/l4t_update_initrd.sh

。该工具chroot到

rootfs/

中，运行NVIDIA的

nv-update-initrd

，并写入

<LFT_DST>/bootloader/l4t_initrd.img

（供烧录工具使用）和

<LFT_DST>/rootfs/boot/initrd

（DUT上的

/boot/initrd

）。此操作具有幂等性，耗时约30秒。当

INITRD_DIRTY=0

（仅覆盖编辑）时跳过。DUT侧的解决方法（

update-initramfs -u

+ 手动

cp

）不在本技能范围内——在此处修复问题，确保烧录交付一致的镜像。

有关shell代码片段、拒绝场景、此重建操作解决的“模块遮蔽”和“版本魔数不匹配”故障模式，以及为何不修改

bootloader/initrd

（另一个文件）的原因，请参阅

references/kernel-image-and-initramfs.md

。

Summary

摘要

Report:

Overlay scope:
```
overlay HEAD ($OVERLAY_HEAD)
```
or "(empty)".

Manifest scope:

mode=<...>, bsp_version=<...>, rebuilt_at=<...>, N artifacts

or "(absent)".

Collision check:
```
$COLLISION_CHECK
```
.

Counts:

overlay:

$COPIED_OVERLAY copied, $IDENTICAL_OVERLAY identical

manifest:

$COPIED_MANIFEST copied, $IDENTICAL_MANIFEST identical

Kernel Image mirror:

$KIMG_MIRRORED

and initramfs:

$INITRD_STATUS

(

copied …

rebuilt

when triggered by

kernel/Image

rootfs/lib/modules/*

writes;

skipped …

otherwise).

First / last paths copied (omit if both
```
COPIED
```
totals are 0).
Resolved
```
<source.root_path>
```
,
```
<bsp_image.root_path>
```
.
Next step:
```
/jetson-flash-image
```
(or
```
/jetson-validate-image
```
if the user only wanted bsp_image refreshed for inspection / static validation).

报告内容包括：

覆盖范围：
```
overlay HEAD ($OVERLAY_HEAD)
```
或“(空)”。

构建清单范围：

mode=<...>, bsp_version=<...>, rebuilt_at=<...>, N artifacts

或“(不存在)”。

冲突检查：
```
$COLLISION_CHECK
```
。
计数：
- 覆盖渠道：
```
$COPIED_OVERLAY
```
  个已复制，
```
$IDENTICAL_OVERLAY
```
  个内容相同
- 构建清单渠道：
```
$COPIED_MANIFEST
```
  个已复制，
```
$IDENTICAL_MANIFEST
```
  个内容相同
内核Image镜像：
```
$KIMG_MIRRORED
```
，以及initramfs状态：
```
$INITRD_STATUS
```
（当由
```
kernel/Image
```
或
```
rootfs/lib/modules/*
```
写入触发时显示
```
copied …
```
/
```
rebuilt
```
；否则显示
```
skipped …
```
）。
第一个/最后一个复制的路径（若
```
COPIED
```
总数均为0则省略）。
已解析的
```
<source.root_path>
```
和
```
<bsp_image.root_path>
```
。
下一步操作：
```
/jetson-flash-image
```
（若用户仅需刷新bsp_image用于检查/静态验证，则为
```
/jetson-validate-image
```
）。

Limitations

限制

Two channels, one destination.
```
bsp_image/Linux_for_Tegra/
```
is written by both passes. Overlay carries customize-* outputs (overlay-only edits like nvfancontrol.conf); manifest carries rebuilt binaries (kernel/OOT/DT). The two are intentionally disjoint by construction: build outputs don't go into the overlay, and customize-* edits to non-build files don't enter the manifest.
Build manifest is the trace-to-dirty contract. Anything in the manifest came from a dirty source repo (per
```
jetson-build-source
```
's "Write the build manifest" step trace policy). Promoting the manifest is therefore safe: every entry is a customization-bearing artifact, not toolchain-divergence noise. The skill does not re-derive the trace — it trusts the manifest.
Manifest entries can outlive their build outputs. If the user wipes
```
Source/.build/
```
or
```
bsp_sources/
```
's build artifacts between
```
jetson-build-source
```
and
```
jetson-promote-image
```
, the manifest will reference missing files. The "Enumerate sources (both channels)" step refuses in that case and points the user at
```
/jetson-build-source
```
to rebuild.
Manifest absence is fine when only overlay edits happened. A purely overlay-side customization (e.g.
```
customize-fan
```
) produces no build outputs and writes no manifest — the "Enumerate sources (both channels)" step is a no-op, the "Diff-aware copy into bsp_image" step promotes only overlay files. The skill prints "manifest: (absent)" in the summary and continues.
Diff-aware, idempotent. Re-running with no overlay commits or manifest changes since the last promote is a no-op (all files identical). Use this to confirm bsp_image is in sync without side effects.
Symlink-mount transparency. When
```
source.repos.Linux_for_Tegra
```
was overridden in
```
jetson-init-source
```
, the canonical mount is a symlink into
```
<source.root_path>/.repos/Linux_for_Tegra/<subdir>
```
.
```
git -C
```
,
```
cp -p
```
, and
```
cmp -s
```
all follow it transparently — no special handling needed at this layer. Manifest
```
src
```
paths are absolute, so symlinks under
```
bsp_sources/
```
don't matter for the manifest channel.
sudo
is scoped to
rootfs/
destinations. Files under
```
rootfs/
```
were extracted with
```
sudo tar xpjf
```
by
```
jetson-init-image
```
, so they carry root ownership and special mode bits the flashing toolchain reads back.
```
sudo cp -p
```
preserves them. Everything else (
```
bootloader/
```
,
```
kernel/
```
,
```
kernel/dtb/
```
,
```
tools/
```
, etc.) is user-owned and does not need
```
sudo
```
. This applies to both channels.
Channel-overlap precedence. If the same
```
dst
```
appears in both overlay and manifest, manifest wins (later in the "Diff-aware copy into bsp_image" step's loop). This is the desired semantic — manifest entries are freshly built, overlay entries may be older state. Hand-editing binary files into the overlay is discouraged (Build's job is to rebuild them); the precedence rule makes such mistakes recoverable.
bsp_image
is read-only outside Deploy. This skill is the only writer in the normal flow (matches the workflow invariant). Hand-edits to
```
<bsp_image.root_path>/Linux_for_Tegra/
```
outside Deploy will be silently overwritten on the next promote run if the same path exists in either channel; conversely they will not be reverted if no entry shadows them. Both behaviors are wrong for the diff trail — never hand-edit upstream.
Scope is overlay HEAD only (channel A). Named tags / manifests / commit ranges are deferred (see below). To promote a historical state,
```
git -C $LFT_SRC checkout <ref>
```
first, then re-run. The manifest channel has no ranged scope — it reflects whatever
```
jetson-build-source
```
's last run produced.
No automatic rollback on partial failure. If
```
cp
```
fails partway through,
```
bsp_image
```
is left in an intermediate state. Fix the underlying cause (usually permissions / disk full) and re-run — the "Diff-aware copy into bsp_image" step will resume by skipping already-promoted files.
Kernel
Image
mirror + initramfs refresh. Gated on copy-pass writes to
```
kernel/Image
```
or
```
rootfs/lib/modules/*
```
; the mirror feeds the refresh's chroot. Both are diff-aware and skipped on pure-overlay edits.
```
tools/l4t_update_initrd.sh
```
must exist in
```
bsp_image
```
(ships with
```
apply_binaries.sh
```
); a missing tool refuses and routes to
```
/jetson-init-image
```
. See
```
references/kernel-image-and-initramfs.md
```
for the full contract and failure modes.

两个渠道，一个目标。
```
bsp_image/Linux_for_Tegra/
```
由两个渠道写入。覆盖渠道承载customize-*输出（仅覆盖编辑，如nvfancontrol.conf）；构建清单渠道承载重新构建的二进制文件（内核/内核外模块/DTB）。两者在设计上有意不重叠：构建输出不会进入覆盖渠道，对非构建文件的customize-*编辑也不会进入构建清单。
构建清单是脏迹跟踪约定。清单中的所有内容均来自脏源仓库（根据
```
jetson-build-source
```
的“写入构建清单”步骤跟踪策略）。因此推广清单是安全的：每个条目都是包含定制内容的产物，而非工具链差异产生的冗余内容。本技能不会重新推导跟踪信息——信任清单内容。
清单条目可能比构建输出存在更久。若用户在
```
jetson-build-source
```
和
```
jetson-promote-image
```
之间删除
```
Source/.build/
```
或
```
bsp_sources/
```
下的构建产物，清单将引用不存在的文件。“枚举源文件（两个渠道）”步骤会在此情况下拒绝执行，并提示用户重新运行
```
/jetson-build-source
```
进行重建。
仅覆盖编辑时，清单不存在是允许的。纯覆盖侧定制（例如
```
customize-fan
```
）不会产生构建输出，也不会写入清单——“枚举源文件（两个渠道）”步骤无操作，“差异感知复制到bsp_image”步骤仅推广覆盖文件。本技能会在摘要中显示“manifest: (不存在)”并继续执行。
差异感知，幂等性。自上次推广后，若覆盖渠道无提交且构建清单无更改，重新运行本技能无任何操作（所有文件内容相同）。可用于确认bsp_image已同步且无副作用。
符号链接挂载透明。当
```
jetson-init-source
```
中
```
source.repos.Linux_for_Tegra
```
被覆盖时，标准挂载是指向
```
<source.root_path>/.repos/Linux_for_Tegra/<subdir>
```
的符号链接。
```
git -C
```
、
```
cp -p
```
和
```
cmp -s
```
均会透明跟随符号链接——此层无需特殊处理。构建清单的
```
src
```
路径为绝对路径，因此
```
bsp_sources/
```
下的符号链接对构建清单渠道无影响。
sudo
仅作用于
rootfs/
目标路径。
```
rootfs/
```
下的文件由
```
jetson-init-image
```
通过
```
sudo tar xpjf
```
解压，因此它们具有root所有权和烧录工具链需要读取的特殊权限位。
```
sudo cp -p
```
会保留这些属性。其他所有路径（
```
bootloader/
```
、
```
kernel/
```
、
```
kernel/dtb/
```
、
```
tools/
```
等）均为用户所有，无需
```
sudo
```
。此规则适用于两个渠道。
渠道重叠优先级。若同一
```
dst
```
路径同时出现在覆盖渠道和构建清单渠道中，构建清单渠道优先（在“差异感知复制到bsp_image”步骤的循环中后执行）。这是预期的语义——构建清单条目是新构建的产物，覆盖渠道条目可能是旧状态。不鼓励手动编辑二进制文件到覆盖渠道（构建的职责是重新构建它们）；优先级规则使此类错误可恢复。
bsp_image
在部署流程外为只读。在正常流程中，本技能是唯一的写入者（符合工作流不变量）。在部署流程外手动编辑
```
<bsp_image.root_path>/Linux_for_Tegra/
```
，若同一路径存在于任一渠道中，下次推广运行时会被静默覆盖；反之，若没有条目遮蔽该路径，则不会被还原。两种行为都会破坏差异跟踪——绝不要手动编辑上游内容。
范围仅为覆盖渠道的HEAD（渠道A）。命名标签/清单/提交范围功能已推迟（见下文）。若要推广历史状态，请先执行
```
git -C $LFT_SRC checkout <ref>
```
，然后重新运行本技能。构建清单渠道无范围概念——它反映
```
jetson-build-source
```
上次运行的结果。
部分失败时无自动回滚。若
```
cp
```
操作中途失败，
```
bsp_image
```
将处于中间状态。修复根本原因（通常是权限/磁盘已满）并重新运行——“差异感知复制到bsp_image”步骤会跳过已推广的文件，继续执行。
内核
Image
镜像 + initramfs刷新。由复制操作写入
```
kernel/Image
```
或
```
rootfs/lib/modules/*
```
触发；镜像操作为刷新的chroot环境提供文件。两者均为差异感知，纯覆盖编辑时会跳过。
```
tools/l4t_update_initrd.sh
```
必须存在于
```
bsp_image
```
中（随
```
apply_binaries.sh
```
一起提供）；若工具缺失则拒绝执行并引导至
```
/jetson-init-image
```
。完整约定和故障模式请参阅
```
references/kernel-image-and-initramfs.md
```
。

Troubleshooting

故障排除

Error	Cause	Solution
`Overlay has uncommitted changes at <LFT_SRC>`	Customize-* edits not committed before promote	Run `git -C $LFT_SRC commit` (or stash), then re-run.
`origin has N unpulled commits on <upstream>`	Remote overlay diverged from local	`git -C $LFT_SRC pull` , resolve conflicts, then re-run.
`Both overlay and manifest are empty — nothing to promote`	No Customize-* commits and no Build manifest	Run a customize-* skill or `/jetson-build-source` first.
`Kernel-side source(s) changed since last /jetson-build-source`	Freshness gate detected unprocessed customize-* edits under `Source/bsp_sources/`	Commit pending edits, run `/jetson-build-source` , re-run promote.
`Manifest entry references missing build output: <src>`	`bsp_sources/` build outputs wiped or stale manifest	Re-run `/jetson-build-source` to regenerate.
`Build manifest at <MANIFEST> is not valid YAML`	Manifest hand-edited or partially written	Re-run `/jetson-build-source` to rewrite the manifest.
`cp: permission denied` under `rootfs/`	Missing `sudo` privilege on the host	Run on an account that can `sudo cp` ; re-run resumes via diff-aware copy.
Profile lacks `bsp_image:` / `source:`	Workspace not bootstrapped	Run `/jetson-init-image` and/or `/jetson-init-source` .
`tool not found at <LFT_DST>/tools/l4t_update_initrd.sh`	`tools/` was pruned, or bsp_image extracted from a non-NVIDIA tarball	Re-run `/jetson-init-image` to repopulate.
`l4t_update_initrd.sh exited non-zero`	Insufficient sudo, broken rootfs (missing `lib/modules/<ver>/modules.dep` ), or out-of-space `/tmp`	Run `depmod -a -b <LFT_DST>/rootfs <ver>` against the rootfs first; verify `/tmp` headroom; rerun promote.
DUT boots with stale kernel / modules after promote, modules fail to load with `disagrees about version of symbol …` , or initramfs ships pre-customize modules even after the refresh ran	The mirror / refresh gate didn't fire (manual hand-edit under `<LFT_DST>` outside the skill), or `rootfs/boot/Image` drifted from `kernel/Image` so the chrooted refresh built against the stale kernel	Force the gate by `sudo touch <LFT_DST>/kernel/Image` + re-run promote, or run the two steps manually: `sudo cp -p <LFT_DST>/kernel/Image <LFT_DST>/rootfs/boot/Image && cd <LFT_DST> && sudo ./tools/l4t_update_initrd.sh` . Then re-flash. See `references/kernel-image-and-initramfs.md` .

错误	原因	解决方案
`Overlay has uncommitted changes at <LFT_SRC>`	Customize-*编辑未在推广前提交	运行 `git -C $LFT_SRC commit` （或stash），然后重新运行。
`origin has N unpulled commits on <upstream>`	远程覆盖仓库与本地仓库分歧	`git -C $LFT_SRC pull` ，解决冲突，然后重新运行。
`Both overlay and manifest are empty — nothing to promote`	无Customize-*提交且无构建清单	先运行customize-*技能或 `/jetson-build-source` 。
`Kernel-side source(s) changed since last /jetson-build-source`	新鲜度检测到 `Source/bsp_sources/` 下存在未处理的customize-*编辑	提交待处理的编辑，运行 `/jetson-build-source` ，重新运行推广。
`Manifest entry references missing build output: <src>`	`bsp_sources/` 下的构建产物已删除或清单过时	重新运行 `/jetson-build-source` 重新生成。
`Build manifest at <MANIFEST> is not valid YAML`	清单被手动编辑或仅部分写入	重新运行 `/jetson-build-source` 重写清单。
`cp: permission denied` under `rootfs/`	主机缺少 `sudo` 权限	使用可执行 `sudo cp` 的账户运行；重新运行时差异感知复制会继续执行。
配置文件缺少 `bsp_image:` / `source:`	工作区未初始化	运行 `/jetson-init-image` 和/或 `/jetson-init-source` 。
`tool not found at <LFT_DST>/tools/l4t_update_initrd.sh`	`tools/` 被删除，或bsp_image从非NVIDIA压缩包解压	重新运行 `/jetson-init-image` 重新填充。
`l4t_update_initrd.sh exited non-zero`	sudo权限不足、根文件系统损坏（缺少 `lib/modules/<ver>/modules.dep` ），或 `/tmp` 空间不足	先对根文件系统运行 `depmod -a -b <LFT_DST>/rootfs <ver>` ；验证 `/tmp` 空间；重新运行推广。
推广后DUT启动时使用过时的内核/模块，模块加载失败并提示 `disagrees about version of symbol …` ，或即使运行了刷新，initramfs仍包含定制前的模块	镜像/刷新触发条件未生效（在本技能外手动编辑 `<LFT_DST>` ），或 `rootfs/boot/Image` 与 `kernel/Image` 不一致，导致chroot环境下的刷新基于过时内核构建	通过 `sudo touch <LFT_DST>/kernel/Image` 强制触发条件并重新运行推广，或手动执行两个步骤： `sudo cp -p <LFT_DST>/kernel/Image <LFT_DST>/rootfs/boot/Image && cd <LFT_DST> && sudo ./tools/l4t_update_initrd.sh` 。然后重新烧录。详情请参阅 `references/kernel-image-and-initramfs.md` 。

Spec status

规范状态

Locked in for v0.2.0:

Two-channel scope — overlay HEAD + build manifest, both diff-aware, both copying into
```
<bsp_image.root_path>/Linux_for_Tegra/
```
.
Channel-overlap precedence — manifest wins on
```
dst
```
collision.
Source-repo collision check — overlay only; manifest has no remote concept and source repos under
```
bsp_sources/
```
are not fetched (their state was sealed when
```
jetson-build-source
```
wrote the manifest).
Atomicity — fail-fast, no rollback. Diff-aware copy makes resume natural.
Audit trail — stdout-only at promote time. The overlay tracker's git log is the canonical record for channel A; the manifest itself is the canonical record for channel B.
Kernel Image mirror + initramfs refresh. Locked in as a paired step. The mirror copies
```
kernel/Image
```
→
```
rootfs/boot/Image
```
whenever the copy pass touched
```
kernel/Image
```
; the refresh runs
```
tools/l4t_update_initrd.sh
```
whenever
```
kernel/Image
```
or any
```
rootfs/lib/modules/*
```
was promoted, rebuilding both
```
bootloader/l4t_initrd.img
```
and
```
rootfs/boot/initrd
```
. Inseparable because the refresh chroots into
```
rootfs/
```
and resolves the kernel through
```
/boot/Image
```
— the mirror has to run first. Closes both module-shadowing and vermagic-skew failure modes; both diff-aware, both skipped on overlay-only edits. Full contract in
```
references/kernel-image-and-initramfs.md
```
.

Still deferred:

Named-tag / commit-range scope for the overlay channel. Revisit when a "promote release X" use case appears.
Manifest history. Currently only the last build's manifest exists; if a user wants to roll bsp_image back to a previous build state, they'd need to re-run
```
/jetson-build-source
```
at the prior commit. A manifest archive (saved per-build-mode or per-commit) would enable rollback without rebuild.
Sidecar manifest in
bsp_image
. Revisit when promotion happens on a host that does not have access to the overlay tracker repo (or the workspace's manifest file).

v0.2.0已锁定：

双渠道范围——覆盖渠道HEAD + 构建清单，均采用差异感知，均写入
```
<bsp_image.root_path>/Linux_for_Tegra/
```
。
渠道重叠优先级——
```
dst
```
路径冲突时构建清单渠道优先。
源仓库冲突检查——仅覆盖渠道；构建清单渠道无远程概念，
```
bsp_sources/
```
下的源仓库不会被拉取（其状态在
```
jetson-build-source
```
写入清单时已固定）。
原子性——快速失败，无回滚。差异感知复制使恢复操作自然。
审计跟踪——仅在推广时输出到标准输出。覆盖跟踪器的git日志是渠道A的规范记录；构建清单本身是渠道B的规范记录。
内核Image镜像 + initramfs刷新。作为配对步骤锁定。每当复制操作触及
```
kernel/Image
```
时，镜像操作将
```
kernel/Image
```
复制到
```
rootfs/boot/Image
```
；每当推广
```
kernel/Image
```
或任何
```
rootfs/lib/modules/*
```
时，刷新操作运行
```
tools/l4t_update_initrd.sh
```
，重新构建
```
bootloader/l4t_initrd.img
```
和
```
rootfs/boot/initrd
```
。两者不可分离，因为刷新操作chroot到
```
rootfs/
```
中并通过
```
/boot/Image
```
解析内核——必须先运行镜像操作。解决了模块遮蔽和版本魔数不匹配两种故障模式；两者均为差异感知，纯覆盖编辑时会跳过。完整约定请参阅
```
references/kernel-image-and-initramfs.md
```
。

仍推迟实现：

覆盖渠道的命名标签/提交范围功能。当出现“推广版本X”的用例时再重新考虑。
构建清单历史。当前仅存在最后一次构建的清单；若用户希望将bsp_image回滚到之前的构建状态，需在先前的提交上重新运行
```
/jetson-build-source
```
。按构建模式或提交保存的清单归档将无需重建即可实现回滚。
```
bsp_image
```
中的辅助清单。当推广操作在无法访问覆盖跟踪器仓库（或工作区的清单文件）的主机上执行时再重新考虑。

References

参考资料

```
references/kernel-image-and-initramfs.md
```
— full contract for the kernel
```
Image
```
mirror +
```
l4t_update_initrd.sh
```
refresh: shell snippets, failure modes, tool semantics, output filenames.

../../context/target-platform-contract.md

— target-platform contract.

```
../../context/bsp-customization-workflow.md
```
— workspace edit protocol (this skill is the promote leg of Deploy).
```
../jetson-init-source/SKILL.md
```
— Setup; materializes the overlay tracker this skill reads (channel A) and authors
```
source.toolchain
```
.
```
../jetson-build-source/SKILL.md
```
— Build builder; writes the
```
.build-manifest.yaml
```
this skill reads (channel B).
```
../jetson-flash-image/SKILL.md
```
— next leg; flashes the just-promoted bsp_image to the DUT.
```
../jetson-validate-image/SKILL.md
```
— final leg; static + on-target validation.

```
references/kernel-image-and-initramfs.md
```
——内核
```
Image
```
镜像 +
```
l4t_update_initrd.sh
```
刷新的完整约定：shell代码片段、故障模式、工具语义、输出文件名。

../../context/target-platform-contract.md

——目标平台约定。

```
../../context/bsp-customization-workflow.md
```
——工作区编辑协议（本技能是部署流程的推广环节）。
```
../jetson-init-source/SKILL.md
```
——初始化；生成本技能读取的覆盖跟踪器（渠道A）并编写
```
source.toolchain
```
。
```
../jetson-build-source/SKILL.md
```
——构建工具；编写本技能读取的
```
.build-manifest.yaml
```
（渠道B）。
```
../jetson-flash-image/SKILL.md
```
——下一个环节；将刚推广的bsp_image烧录到DUT。
```
../jetson-validate-image/SKILL.md
```
——最后一个环节；静态+目标端验证。