jetson-flash-image

BSP イメージのフラッシュ

目的

ツリー内の Linux_for_Tegra/ から NVIDIA のフラッシュツールチェーン（flash.sh または l4t_initrd_flash.sh）を実行して、プロモート済みの bsp_image を Jetson DUT に書き込みます。フラッシュ時、DUT は RCM（リカバリ）モードになっている必要があります。これは BSP オーバーレイのデプロイチェーン（/jetson-promote-image → /jetson-flash-image）のフラッシュ工程です。BSP オーバーレイのワークフローについては、../../context/bsp-customization-workflow.md を参照してください。

設計原則。 このスキルは、次の 4 つの不変条件に従います。それぞれを担当する手順のステップで詳しく説明します。

• ホスト側のフラッシュ変数（<board>、<boot-dev>、フローツール、ボードごとの .conf、boardctl）は、アクティブなプロファイルまたはツリー内の BSP から解決します。
• アーティファクトのパス（DTB_FILE、BPFDTB_FILE、パーティション XML、BCT、DRAM トレーニング）は、フラッシュ時に DUT の EEPROM から読み取った board_sku／board_FAB に基づいて、flash.sh／l4t_initrd_flash.sh 内で解決します。
• DUT の EEPROM を正とします。プロファイルは作成時点での予測であり、事前チェックで照合します。EEPROM の値が空でも有効であり、拒否の理由にはなりません。
• フラッシュの前に、表示された解決内容をユーザーが明示的に確認します。

対象外：BSP のカスタマイズ（/jetson-customize-* スキルを使用）、オーバーレイトラッカーの bsp_image へのプロモート（/jetson-promote-image を使用）、カスタムキャリア用フラッシュ設定の作成（/jetson-derive-carrier を使用）。

前提条件

• ../../context/target-platform-contract.md に従ってアクティブなターゲットプラットフォームプロファイルが解決されており、bsp_image: ブロックに値が設定されていること。存在しない場合は拒否し、/jetson-init-image に案内します。
• ホスト上に <bsp_image.root_path>/Linux_for_Tegra/ が存在し、apply_binaries.sh が実行済みであること（そうでない場合は /jetson-init-image に案内します）。
• アクティブブロックの優先順位ルール（custom_carrier.flash_config → reference_devkit.flash_config）に従って解決できる、ボードごとのフラッシュ .conf があること。存在しない場合は拒否し、/jetson-derive-carrier または /jetson-init-image に案内します。
• 先行するオーバーレイからイメージへの工程について、/jetson-promote-image がすでに実行済みであること（または、前回のフラッシュ以降にプロモートによる変更がない状態での単独再フラッシュであること）。
• boardctl を使用するか、手動でリカバリーモードにしてリセットボタンを操作することで RCM モードに移行できる DUT が、ホストに接続されていること。

呼び出すタイミング

• /jetson-promote-image によって bsp_image が更新され、目的のカスタマイズが反映された後。
• 前回のフラッシュ以降にプロモートによる変更がない状態での単独再フラッシュ。
• 呼び出し前に DUT が RCM モードになっている必要があります。

手順

ターゲットと bsp_image を解決する

../../context/target-platform-contract.md に従って、アクティブなプロファイルを解決します。 bsp_image: が存在しない場合、または <bsp_image.root_path>/Linux_for_Tegra/ が存在しない場合は拒否し、ユーザーを /jetson-init-image に案内します。

フラッシュ用 conf パスを解決する

target-platform-contract.md のアクティブブロック優先ルールに従って、ボードごとの .conf を選択します。 custom_carrier.flash_config が存在する場合はそれを使用し、存在しない場合は reference_devkit.flash_config を使用します。選択したファイルが <bsp_image.root_path>/Linux_for_Tegra/ の下に存在することを確認します。存在しない場合は処理を中止し、ユーザーを /jetson-derive-carrier（カスタムキャリアの場合）、または /jetson-promote-image / /jetson-init-image（リファレンス開発キットの場合）に案内します。

解決した .conf の拡張子 .conf を除いたベース名を <board> としてバインドします（例：jetson-agx-thor-devkit.conf → <board>=jetson-agx-thor-devkit）。「フラッシュの実行」ステップのコマンド形式は、このバインドを直接使用します。

この段階ではディスパッチのプレビューを行いません。 アーティファクトの解決（DTB_FILE、 BPFDTB_FILE、パーティション XML、MB1 BCT、DRAM トレーニングテーブル）は、 イメージ生成中に flash.sh / l4t_initrd_flash.sh 内で実行されます。その際に使用されるのは、 プロファイルから入力された値ではなく、リカバリモードで DUT の EEPROM から読み取った board_sku と board_FAB です。プロファイルは作成時の予測であり、 フラッシュ時には DUT の EEPROM が正しい値となります。「事前チェック」ステップの EEPROM 照合では EEPROM を読み取り、プロファイルと EEPROM が一致しない場合はフラッシュを中止します。そのため、事前チェックに合格することが、フラッシュ時のディスパッチでプロファイルが想定するアーティファクトが選択されることを保証します。

フラッシュフロー以外の静的解析で、予測アーティファクトのパスが必要な場合（KB の生成や、編集対象ファイルの特定に customize-* スキルを使用する場合）は、 ボードごとの conf ディスパッチにあるスタンドアロンのスニペットを参照してください。このスニペットはBSP 側の解決には有効ですが、フラッシュ時のプレビューには使用できません。

<boot-dev> とフラッシュフローを選択する

<boot-dev> は意図的に解決するものであり、決めつけてはいけません。ソースの優先順位は次のとおりです。

1. アクティブなプロファイルにブートデバイスが記録されている場合は、それを使用します。
2. それ以外の場合は、ボードごとの conf が実際にサポートする選択肢（チップファミリーと conf のバリアントに応じて、internal、external、nvme0n1p1、mmcblk0p1 など）をユーザーに提示します。

以下の表からフロー用ツールを選択します。

チップファミリー	デフォルトのブートメディア	ツール
T234 / Orin	eMMC / SD	flash.sh
T234 / Orin	NVMe / USB	l4t_initrd_flash.sh
T264 / Thor	NVMe / UFS	l4t_initrd_flash.sh

Massflash と --flash-only による再実行でも同じツールを選択しますが、それぞれのフラグを追加します。

DUT をリカバリモードにする

ツリー内の boardctl を使用してデバイスをリカバリ状態にします（推奨）。または、リカバリボタンを押してからリセットボタンを手動で押します。

Linux_for_Tegra/ 内の boardctl の場所、-t ターゲットの一覧表示方法とターゲットの選び方（topo を推奨）、使用する正確な recovery 動詞、手動で行う代替手順については、 references/recovery-mode-boardctl.md に記載されています。

解決したバイナリパスを、このスキルの残りの手順で使用する <boardctl> としてバインドします。$PATH 上の boardctl に置き換えてはいけません。また、<boardctl> -h にないターゲット名を作ってはいけません。「事前チェック」ステップの DUT リカバリ確認では、どちらの方法でも DUT が実際に RCM モードになったことを確認します。

事前チェック

以下の事前チェックを指定された順序で実行し、いずれのチェックも省略してはいけません。ホスト側のチェックを先に実行し（ユーザーにリカバリ操作を依頼する前に、問題があれば早期に失敗させます）、ユーザーがデバイスを RCM モードにした後で DUT 側のチェックを実行します。EEPROM に依存するチェックは、リカバリチャネルを通じて初めて読み取りが可能になるため、RCM の検出後に行います。

5.1 bsp_image の準備状況（ホスト側）。

• ボードごとの conf は <bsp_image.root_path>/Linux_for_Tegra/<flash_config> にあります。
• 展開されたアーティファクトのサブツリー: kernel/dtb/、bootloader/、 bootloader/generic/BCT/、rootfs/。
• apply_binaries.sh が実行済みです — rootfs/etc/nv_tegra_release と、 チップの nvidia-l4t-bsp-* マーカーパッケージファイルの存在を確認してください。
• 正確に解決された DTB_FILE / BPFDTB_FILE / BCT のファイル名は、 ここでは意図的にチェックしていません — これらはフラッシュ時に EEPROM から 選択されます（「Resolve the flash conf path」ステップを参照）。
• カーネル Image ミラー不変条件。 <LFT_DST>/kernel/Image と <LFT_DST>/rootfs/boot/Image の両方が存在する場合、それらは バイト単位で同一（cmp -s）でなければなりません。不一致は /jetson-promote-image の Mirror ステップ がスキップされたことを意味します — 差し戻してください。Initramfs の存在。 l4t_initrd_flash.sh には <LFT_DST>/bootloader/l4t_initrd.img および <LFT_DST>/rootfs/boot/initrd が必要です。存在しない場合は /jetson-init-image へルーティングしてください。（ rootfs/lib/modules/<ver>/ との新しさの比較はここでは行いません — これは /jetson-promote-image の Refresh initramfs ステップが担当します。）

5.2 RCM モードの DUT。

• 「Put the DUT into recovery mode」ステップの結果を検証します（ユーザーが選択した <boardctl> -t <target> の呼び出し、または手動フォールバックのいずれか）。

• lsusb -d 0955: が、アクティブなチップファミリーのリカバリー VID:PID ペアに 一致するデバイスを少なくとも 1 つ報告する必要があります:

  チップファミリー	リカバリー VID:PID
  T23x / Orin	0955:7X23（X は任意の 16 進数 — モジュールバリアント）
  T26x / Thor	0955:7026

  T23x の場合は、末尾の 23 でマッチさせてください（例: lsusb -d 0955: | grep -E ' 0955:7.23 '）。リテラルの 0955:7023 チェックでは、有効な T23x バリアントを見逃します。

• 存在しない場合 → 「Put the DUT into recovery mode」ステップで boardctl を使用した場合は、 その出力を示して拒否してください。「Put the DUT into recovery mode」ステップで手動パスを使用した場合は、 ジャンパー / ボタンと電源の再投入を確認するようユーザーに再度促してください。

• これが下流のすべてに対するゲートです。 flash.sh の イメージ生成フェーズは、同じリカバリーチャネル経由で EEPROM を読み取ります。 ここで RCM に入っていないデバイスは、そこでも失敗します。

5.3 EEPROM とアクティブプロファイルのクロスチェック。

<bsp_image.root_path>/Linux_for_Tegra/ から sudo ./nvautoflash.sh --print_boardid を使用して、リカバリーモードの DUT の EEPROM から board_sku と board_FAB（およびアクティブなチップファミリーが使用する追加のディスパッチ入力）を 読み取ります。完全なリファレンス — サンプル出力、ラベルからディスパッチ入力へのマッピング、空値の セマンティクス、EEPROM とプロファイルの照合テーブル — は references/eeprom-cross-check.md にあります。

拒否のトリガーは実際の空でない不一致であり、値の欠落ではありません。空の EEPROM 値は有効であり、拒否のトリガーにはなりません。クロスチェックは、両側が不一致を検出するのに十分な情報を提供する場合に、誤ったターゲット / 誤った SKU クラスの障害に対する主要な防御となります。

5.4 デフォルトユーザーのステージング（ホスト側、対話型）。

新しく適用された bsp_image には、Linux ユーザーが事前にステージングされていません。 <bsp_image.root_path>/Linux_for_Tegra/rootfs/home/ と rootfs/etc/passwd の UID ≥ 1000 で検出します。存在しない場合は、4 つのクリック選択オプションを備えた AskUserQuestion を 1 回発行します: ubuntu / ubuntu、nvidia / nvidia、 custom（ユーザー名 + パスワードのサブプロンプト）、または skip（初回起動時の OEM ウィザード）。skip 以外を選択した場合は l4t_create_default_user.sh --autologin --accept-license を実行します。完全な 呼び出し方法と根拠は references/default-user-staging.md にあります。

「Confirm resolution」ステップで表示できるように、解決結果を記録してください。このステップは拒否ゲートでは ありません — ユーザーとの対話ポイントです。

解決内容の確認

解決済みのプランを表示し、明示的な承認を求めます。形式は解決内容であり、シェルコマンドではありません。ユーザーが承認するのは、何をフラッシュするかであり、実行される文字列ではありません。

Target:         <reference_devkit.name> [+ custom_carrier.name]
Profile:        target-platform/<active>.yaml
bsp_image:      <bsp_image.root_path>/Linux_for_Tegra  (version <X>)
Flash conf:     <flash_config>   (path verified in the "Resolve the flash conf path" step)

DUT EEPROM  →   board_sku=<value-or-(empty)>  board_FAB=<value-or-(empty)>
Profile     →   module.sku=<value-or-(any)>    module.revision=<value-or-(any)>
                (reconciled per the "Preflight checks" step's EEPROM cross-check)

Boot device:    <boot-dev>
Flow tool:      flash.sh  |  l4t_initrd_flash.sh
boardctl:       <bsp_image.root_path>/Linux_for_Tegra/tools/board_automation/boardctl
                (or the path the "Put the DUT into recovery mode" step resolved)
RCM entry:      <boardctl> -t <user-selected target> recovery  |  manual recovery + reset buttons
Post-flash:     <boardctl> -t <user-selected target> reset   (T26x / Thor)
                not required — flash tool resets internally    (T23x / Orin)
Default user:   <username> (autologin)
              | already staged in rootfs (kept)
              | none — OEM config wizard on first boot

成果物のパス（DTB_FILE、BPFDTB_FILE、パーティション XML、BCT）は表示されません。フラッシュ時に flash.sh が EEPROM から解決するものであり、このスキルでは解決しません。「事前チェック」ステップで EEPROM と照合することで、フラッシュ時に選ばれるファイルがプロファイルの想定と一致することを保証します。

ここがユーザー承認のゲートです。生の「このコマンドを貼り付けてください」というワークフローへのフォールバックは拒否してください。この経路では、古くなったドキュメントの断片、誤ったダッシュ、プロンプト文字の貼り付けによる不具合が、本番環境でのフラッシュに入り込む可能性があります。

フラッシュの実行

解決済みの変数からコマンドを構築します。ユーザー、ドキュメント、または記憶からのコマンドを、そのまま受け入れてはいけません。

cd <bsp_image.root_path>/Linux_for_Tegra
sudo ./<flow-tool> [<resolved flags>] <board> <boot-dev>

ゼロ以外の終了コードが返されたら、最初に失敗したステップで中止し、そのステップを提示してください。一時的な USB エラーが発生しても、自動再試行はしないでください。

フラッシュ後のリセット（T26x / Thor のみ）

T26x プラットフォームでは、flash.sh / l4t_initrd_flash.sh の終了後、フラッシュしたイメージから自動的に再起動しません。「DUT をリカバリモードにする」ステップで解決した <boardctl> と、ユーザーが RCM に入るために選択したものと同じターゲットを使って実行してください。

<boardctl> -t <user-selected target> reset

T23x / Orin では内部でリセットが実行されます。Orin ではこのステップをスキップしてください。「DUT をリカバリモードにする」ステップで手動の方法を使った場合は、フォースリカバリ用ジャンパー／ボタンを外し、手動で電源を入れ直すようユーザーに促してください。このステップは、アクティブなプロファイルから解決したチップファミリーに基づいて実行可否を判断してください。

概要

使用したコマンドライン（フラッシュと、実行した場合はフラッシュ後のリセット）、終了コード、ログの場所（tee を使用した場合）を報告します。検証時に再読み込みできるよう、解決済みのプランと結果を保存します。

制限事項

• DUT は RCM モードである必要があります。 イメージ生成（EEPROM の読み取り）とフラッシュのどちらもリカバリ用 USB チャネルを使用するため、ゲートで RCM モードになっていない場合はイメージ生成も失敗します。
• 成果物のパスはフラッシュ時に解決されます。 DTB_FILE、BPFDTB_FILE、パーティション XML、BCT、DRAM トレーニングは、flash.sh / l4t_initrd_flash.sh が EEPROM（board_sku / board_FAB）から選択します。このスキルが検証するのはホスト側の準備のみです。
• プロファイルより EEPROM が優先されます。 実際の空でない値に不一致があれば拒否します。空の EEPROM 値は有効です。
• 生コマンドによる迂回はできません。 ユーザーが指定した「このコマンドを貼り付けてください」へのフォールバックは拒否します。この経路では、古くなったドキュメントの断片やプロンプト文字の貼り付けによる不具合が、本番環境でのフラッシュに入り込む可能性があります。
• 一時的なエラーの自動再試行はしません。 USB の一時的な不具合が発生した場合は中止し、再度 RCM に入れてから実行し直してください。
• T26x ではフラッシュ後の明示的なリセットが必要です。 T26x はフラッシュしたばかりのイメージから自動的に再起動しないため、<boardctl> -t <target> reset（または手動での電源の入れ直し）が必要です。T23x は内部でリセットします。
• Massflash / --flash-only では同じツールの選択と、それぞれに対応するフラグを使用します。Massflash のトポロジ設定は対象範囲外です。

トラブルシューティング

エラー	原因	解決方法
lsusb -d 0955: を実行しても、0955:7X23（T23x）または 0955:7026（T26x）に一致するものが表示されない	DUT が RCM モードに入っていません。boardctl recovery が失敗したか、手動でのリカバリーとリセットの手順が正しく行われていません。	boardctl を使用した場合は、その出力を表示して再度プロンプトを出します。手動の場合は、リカバリー用ジャンパー／ボタンを再確認し、電源を入れ直します。「DUT が RCM モード」の事前チェックを再実行します。
事前チェックの EEPROM 照合で、board_sku／board_FAB がプロファイルと一致せず拒否される	EEPROM に、アクティブなプロファイルの module.sku／module.revision と一致しない、実際の空でない値が保持されています。	プロファイル（/jetson-set-target または /jetson-init-target）を修正し、DUT の実際の EEPROM に合わせます。プロファイルから EEPROM を上書きしないでください。EEPROM が正となります。
「per-board conf not found」というエラーで事前チェックが拒否される	アクティブなプロファイルが、<bsp_image.root_path>/Linux_for_Tegra/ 内に存在しない flash_config を参照しています。	カスタムキャリアの場合は、/jetson-derive-carrier を実行して conf を生成します。リファレンス開発キットの場合は、/jetson-promote-image／/jetson-init-image を再実行して BSP イメージを再度生成します。
rootfs/etc/nv_tegra_release が見つからず、事前チェックが拒否される	<bsp_image.root_path>/Linux_for_Tegra/ に対して apply_binaries.sh が実行されていません。	/jetson-init-image（apply_binaries.sh を実行します）を再実行するか、Linux_for_Tegra/ から apply_binaries.sh を手動で実行します。
boardctl -t <target> recovery がエラーになる、または効果がない	誤った boardctl（インツリーのものではなく、$PATH 内のバイナリ）を使用しているか、<boardctl> -h で列挙されていないターゲット名を指定しています。	インツリーの <bsp_image.root_path>/Linux_for_Tegra/tools/board_automation/boardctl を使用し、<boardctl> -h に表示されるターゲットを選択します。必要に応じて、手動でのリカバリーとリセットボタンの操作に切り替えます。
T26x でフラッシュは成功するものの、DUT がリカバリーモードのまま、または新しいイメージで起動しない	flash.sh／l4t_initrd_flash.sh の終了後、T26x はリカバリーモードから自動でリセットされません。	RCM モードへの移行時と同じターゲットを指定して、<boardctl> -t <target> reset を実行します。手動の場合は、force-recovery ジャンパー／ボタンを解除し、電源を入れ直します。T23x／Orin では追加の手順は不要です。
自動ログインを想定していたのに、初回起動で Ubuntu の OEM 設定ウィザードが表示される	フラッシュ前に、デフォルトユーザーが rootfs に準備されていません。	l4t_create_default_user.sh --autologin --accept-license を使ってユーザーを準備してから再フラッシュします（デフォルトユーザーの準備手順を参照）。または、今回だけ DUT 上で OEM ウィザードを完了します。
アーティファクトが見つからないエラーで flash.sh がゼロ以外の終了コードを返す（DTB／BPFDTB／パーティション XML）	EEPROM に基づくディスパッチによって解決されたファイル名が bsp_image に存在しません。通常、/jetson-promote-image でカスタマイズされたアーティファクトがコピーされなかったか、EEPROM の SKU が BSP でサポートされていません。	/jetson-promote-image を再実行します。SKU がサポートされていない場合、DUT には別バージョンの BSP が必要です。
kernel/Image と rootfs/boot/Image の不一致、bootloader/l4t_initrd.img／rootfs/boot/initrd の欠落、または DUT 上で modprobe が「disagrees about version of symbol …」と表示する	/jetson-promote-image のミラー／更新手順が省略されたか、Deploy の外部で bsp_image が手動編集されました。	/jetson-promote-image を再実行してから再フラッシュします。initramfs ファイルがすべて存在しない場合は、先に /jetson-init-image を実行します。手動で対処する方法については、promote-image のカーネルイメージと initramfs のリファレンスを参照してください。

参考資料

• references/recovery-mode-boardctl.md — ツリー内の boardctl の場所を特定し、ターゲットを列挙して、recovery / reset を実行します。手動での代替手順（「Put the DUT into recovery mode」ステップ／「Post-flash reset」ステップの詳細）。
• references/eeprom-cross-check.md — nvautoflash.sh --print_boardid のサンプル、ラベルからディスパッチ入力への対応表、EEPROM とプロファイルの照合表（「Preflight checks」ステップで使用）。
• references/default-user-staging.md — l4t_create_default_user.sh の呼び出しとフラグの理由（「Preflight checks」ステップで使用）。
• ../../context/target-platform-contract.md — ターゲットプラットフォームの契約。
• ../../context/bsp-customization-workflow.md — ワークスペースの編集プロトコル（このスキルは Deploy のフラッシュ工程です）。
• ボードごとの conf ディスパッチ — アクティブなプロファイルから <board>、DTB、BCT を解決します。
• ../jetson-promote-image/SKILL.md — 先行工程。オーバーレイを bsp_image にコピーします。
• ../jetson-derive-carrier/SKILL.md — 「Resolve the flash conf path」ステップで使用する、カスタムキャリアのフラッシュ conf を生成します。