jetson-customize-nvpmodel

nvpmodel の電力モードを変更する（BSP 側）

目的

ボードごとの nvpmodel 設定を編集し、デバイスの起動時に目的の電力モードセット、CPU／GPU／EMC／TPC のクランプ、およびデフォルトモードが適用されるようにします。BSP 側のみを対象とします。すべての書き込みはオーバーレイトラッカーに反映され、上流の bsp_image のコピーは読み取り専用です。

このスキルは、ボードごとの nvpmodel 設定ファイルに対する BSP 側の編集を扱います。モードの追加や削除、CPU／GPU／EMC／TPC のクランプの編集、起動時のデフォルトの変更が可能です。Jetson／Tegra プラットフォーム（T234 Orin、T264 Thor）が対象です。

ファイル形式（BSP ファイルヘッダーに準拠）

# 1. PARAM definitions — declare named knobs and their sysfs paths
< PARAM TYPE=FILE  NAME=<param_name> >
<arg_name> </absolute/sysfs/path>
...
< PARAM TYPE=CLOCK NAME=<param_name> >
FREQ_TABLE        </sysfs/.../available_frequencies>
MAX_FREQ          </sysfs/.../max_freq>
MIN_FREQ          </sysfs/.../min_freq>
FREQ_TABLE_KNEXT  </sysfs/.../available_frequencies>     # kernel-NEXT variant
MAX_FREQ_KNEXT    </sysfs/.../max_freq>
MIN_FREQ_KNEXT    </sysfs/.../min_freq>

# 2. POWER_MODEL definitions — one block per profile
< POWER_MODEL ID=<int> NAME=<string> >
PARAM_NAME ARG_NAME <value>
...

# 3. PM_CONFIG — mandatory; selects boot default
< PM_CONFIG DEFAULT=<id> >

ルール：

• TYPE=FILE の場合、<value> は文字列です（0、1、on、auto など）。
• TYPE=CLOCK の場合、<value> は整数です（クロックは Hz、マスクは生の整数）。
• CLOCK 値の -1 は INT_MAX（上限なし）を意味します。
• ヘッダーの < … > 行は、列 0 から始まり、< の後と > の前にスペースを入れる必要があります。厳守してください。
• POWER_MODEL で参照されるすべての PARAM_NAME は、あらかじめ宣言されている必要があります。
• **周波数値は、そのクロックのカーネルの available_frequencies テーブルにある値を使用してください。**テーブルにない値は、通知されずに近い値へ丸められます。
• CORE_0 をオフラインにすることはできません。どのプロファイルでも、少なくとも 1 つの CPU コアをオンラインにしておく必要があります。
• **PARAM 名は、ボードごとのファイル内にある既存の POWER_MODEL ブロックから、そのままコピーしてください。**チップファミリーによって異なります（T234 Orin は CPU クラスターに CPU_A78_<n> を使用し、T264 Thor は別の規則を使用します）。推測で作成しないでください。

前提条件

../../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 に案内します。

パスを特定します。

• <bsp_image.root_path> は、bsp_image.root_path: が存在する場合はその値を使用し、存在しない場合は <workspace>/Image を使用します。
• <source.root_path> は、source.root_path: が存在する場合はその値を使用し、存在しない場合は <workspace>/Source を使用します。

このスキルでは、<bsp_image.root_path> は読み取り専用です。すべての書き込みは <source.root_path> の下に反映されます（オーバーレイトラッカー）。これは ../../context/bsp-customization-workflow.md#workflow-invariants に記載されたワークフロー上の不変条件です。上流ファイルを手動で編集すると、差分の記録がひそかに失われ、/jetson-promote-image が何もしなくなります。

ボードごとのファイル

このスキルが編集する設定ファイルの相対パスは次のとおりです。

Linux_for_Tegra/rootfs/etc/nvpmodel/nvpmodel_<active-sku>.conf

このファイルは2 つのルートに存在し、スキルは両方を確認します。

役割	場所	スキルによる書き込み
検出と変更前のソース	<bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/	いいえ — 読み取り専用
オーバーレイの編集対象と git コミット	<source.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/	はい

以降のセクションでボードごとのファイルとは、<source.root_path> の下にあるオーバーレイのコピーを指します。操作 1～4 はすべて、このオーバーレイのコピーを読み取り、編集し、保存します。<bsp_image.root_path> のコピーは、「<active-sku> の特定」検出手順で一度と、オーバーレイの編集手順 の変更前ファイルのインポート手順で一度読み取られ、その後は一切触れられません。

<active-sku> の解決 — どのファイルを編集するか

ファイル名が常に module.id + "_" + module.sku であるとは限りません。以下のようなバリアントが存在します。

• nvpmodel_p3767_0000_super.conf (スーパーモード SKU バリアント)
• nvpmodel_igx_orin.conf、nvpmodel_igx_orin_safety.conf (IGX、SKU 番号なし)

起動時に、nvpower.sh (Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh) がカーネル DTB のルート compatible 文字列を読み取り、それにスーパー/セーフティ状態を加味して nvpmodel のファイル名にマッピングします。そのマッピングを BSP 側で、<bsp_image.root_path> に対して再現してください。

1. <bsp_image.root_path>/Linux_for_Tegra/ 配下で SKU に正しいカーネル DTB を解決し、そのルート compatible を読み取ります (アクティブなフラッシュ conf からカーネル DTB を検出します)。
2. <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh を読み取り、compatible 文字列 → conf のマッピングを見つけ、前の手順で得た compatible に適用します (スーパー/セーフティフラグを考慮します)。
3. 解決された nvpmodel_<...>.conf が <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/ 配下に存在することを確認します。

ショートカット: <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/ を nvpmodel_<module.id>_<module.sku>*.conf でフィルタリングします。スーパーモードのフラッシュ設定の場合は _super バリアントを選びます。曖昧さがない場合にのみ使用し、それ以外の場合は DTB 方式にフォールバックしてください。

nvpmodel_<id>_<sku>.conf を盲目的に組み立てないでください — ファイルが実際に存在することを確認してください。

伝播セット — 同期を保つべき conf

アクティブ SKU のファイルだけがカスタマイズを反映すべき唯一の conf であることはほとんどありません。それを編集した後は、伝播セット内のすべての兄弟ファイルに同じ編集を適用して、どのモジュール / ベースボード SKU で起動しても変更が維持されるようにしてください。

• 参照プラットフォームの nvpmodel conf — アクティブなファイルがフォーク元とした上流の conf です (アクティブなプロファイルの reference_devkit、または jetson-derive-carrier のフォーク系統から解決します)。参照のみを含む BSP (派生キャリアなし) の場合、これはアクティブなファイルと同じであり、このルールは実質的に何もしないのと同じになります。
• すべてのキャリア派生 nvpmodel conf — 同じモジュール SKU 上にカスタムキャリア向けに jetson-derive-carrier が生成した各 nvpmodel_*.conf です。
• 存在する場合の _super 兄弟ファイル (例: nvpmodel_p3767_0000_super.conf) — 構造的な編集 (新しい POWER_MODEL ブロック、削除されたブロック、PM_CONFIG DEFAULT= の反転、NAME の変更) を適用しますが、super conf のより高い MAX_FREQ / MIN_FREQ の上限は保持してください。これらの引き上げられた上限こそが _super バリアントが存在する理由であり、非 super ファイルからの一律の内容上書きは super エンベロープを気付かないうちに平坦化してしまいます。

「同じ編集を適用する」≠ 一律のファイルコピー。 変更した POWER_MODEL / PARAM 行を各兄弟ファイルに移植し、その他のすべての行は保持してください。一律コピーが安全なのは、編集前に両方の conf がバイト単位で同一だった場合のみです。それ以外の場合は、各ターゲットでルールに従って再検証してください (クロック値の available-frequencies テーブル、ID の一意性、PM_CONFIG DEFAULT= が存在する ID を参照していること) — 兄弟 conf はアクティブなファイルの周波数値を受け付けない SKU 固有の available_frequencies テーブルを持っている可能性があります。

オーバーレイ編集レシピ (任意の Operation の前に適用)

ワークフロー文書の正規の Off-skill edits レシピ に従ってください — pristine インポート + カスタマイズコミットのペアで、どちらもプレビューゲートで制御されます。実行ごとに 1 回適用し、その実行が触れるすべてのボード単位のファイル (アクティブな conf と、伝播セット 内のすべての兄弟ファイル) を対象にしてください。

このスキル向けの具体的な置き換えは以下のとおりです。

• <rel>/<file> は rootfs/etc/nvpmodel/<conf> です。
• pristine インポートのメッセージ案: import pristine: <インポートされた conf のカンマ区切りの rel パス>、 本文 Source: <bsp_image.root_path>/Linux_for_Tegra/ (BSP <bsp_image.version>)。
• カスタマイズコミットのヘッダー案: jetson-customize-nvpmodel: <summary>、 本文の行は nvpmodel_p3767_0001.conf: PM_CONFIG DEFAULT 2 -> 0 (MAXN) のようにします。

手順

ユーザーの意図に合った操作を選び、該当するサブセクションに従ってください。すべての書き込み操作（1～4）では、最初にオーバーレイ編集の手順を適用してください。

• 操作 1 — 新しい電力モードを追加します（NVIDIA Power Estimator を使用します）。
• 操作 2 — 電力モードを削除します。
• 操作 3 — 既存の電力モードを編集します（クランプ、コアのオンライン状態、NAME）。
• 操作 4 — 起動時のデフォルトを変更します（PM_CONFIG DEFAULT=）。
• 操作 5 — 定義されている電力モードを一覧表示します（読み取り専用）。

書き込み操作の後は、デバイスに変更を反映するため、デプロイチェーン（## Deploy）を実行してください。

例

Power Estimator のエクスポートから新しい 30 W の電力モードを追加し、P3767-0001 ターゲットの起動時デフォルトに設定します。

/jetson-customize-nvpmodel
> add a new POWER_MODEL from ~/Downloads/nvpmodel_30W.conf as ID 8 NAME "30W_CUSTOM"
> set PM_CONFIG DEFAULT to 8

起動時のデフォルトを切り替えて、Thor ターゲットを MAXN 電力エンベロープに制限します（エンベロープの調整は不要です）。

/jetson-customize-nvpmodel
> set PM_CONFIG DEFAULT to the MAXN profile's ID

現在アクティブな SKU で定義されている電力モードと、起動時のデフォルトを一覧表示します。

/jetson-customize-nvpmodel
> list defined power modes

操作 1 — 新しい電力モードを追加する

最初にオーバーレイ編集の手順を適用してください。

Power Estimator でプロファイルを生成する

電力を推定するために、既存のプロファイルから周波数を補間または外挿してはいけません。

標準構成以外の電力エンベロープ（カスタムの電力予算、カスタムのワークロード）には、NVIDIA Power Estimator を使用してください。https://jetson-tools.nvidia.com/powerestimator/

• 正確なモジュール SKU と JetPack リリースを選択します。
• ワークロード（CPU コア、GPU 使用率、EMC、コーデック、カメラ、ディスプレイ）を入力します。
• 電力予算を推定します。
• カスタムの nvpmodel.conf をダウンロードします。
• ダウンロードした nvpmodel.conf のファイルパスを共有します。

POWER_MODEL ブロックを追加する

ボードごとのファイルで、新しいブロックを最後の < PARAM … > 宣言の後（POWER_MODEL は宣言済みの PARAM を参照する必要があります）、最後の < PM_CONFIG ... > 行の前に挿入します。ブロックの構造は、上記のファイル形式に従います。周波数の値には、Power Estimator の出力を使用します（「Power Estimator でプロファイルを生成する」を参照）。

ID が一意であることを確認してください。NAME は大文字で、空白を含めないでください。数値の MAX_FREQ / MIN_FREQ は、それぞれ available_frequencies の規則を満たす必要があります（「ルール」を参照）。このモードを起動時のデフォルトにする場合は、操作 4 に従ってください。

操作 2 — 電力モードを削除する

最初にオーバーレイ編集の手順を適用してください。

1. ボードごとのファイルで、< POWER_MODEL ID=<n> NAME=... > ブロック全体と、そのすべてのパラメーター行を削除します。次の < POWER_MODEL ... > または < PM_CONFIG ... > マーカーの直前までを削除してください。
2. 削除する ID が末尾の < PM_CONFIG … > 行にある現在の DEFAULT=<id> 値と一致する場合は、DEFAULT= を残りの ID に設定してください。そうしないと、nvpmodel が起動時にデフォルトを適用できません。
3. 変更が安全であると判断する前に、rootfs スクリプト内にハードコードされた参照がないか検索します。

   grep -rn "nvpmodel -m" \
     Linux_for_Tegra/rootfs/etc \
     Linux_for_Tegra/rootfs/opt 2>/dev/null
   

ID に欠番があっても問題ありません。残りのモードの ID を振り直す必要はありません。

操作 3 — 既存の電力モードを編集する

最初にオーバーレイ編集の手順を適用してください。

1. ボードごとのファイルで、ブロック内のパラメーター行を編集します。<param> と <arg> の名前は、PARAM 宣言と正確に一致させてください。
2. 編集によって電力エンベロープが変わる場合（CPU/GPU/EMC/PVA/DLA の MAX_FREQ / MIN_FREQ、周波数制限モードのコアオンライン数、または TPC マスクの変更）、新しい周波数を実際のコンポーネントごとのモデルに基づいた値にするため、NVIDIA Power Estimator を再実行します（「Power Estimator でプロファイルを生成する」を参照）。隣接するモードから補間しないでください。
3. 「ルール」にある available_frequencies の規則に従って、クロック値を検証します。

すでに検証済みのエンベロープ内でコアのオンラインフラグのみを切り替える編集、または NAME= のみを変更する編集では、Power Estimator を実行する必要はありません。

Operation 4 — 起動時のデフォルトを変更する

まず、オーバーレイ編集レシピを適用します。

ボードごとのファイルの末尾にある < PM_CONFIG DEFAULT=<id> > の行を編集します。

<id> は、同じファイル内にある既存の < POWER_MODEL ID=<id> … > ブロックを参照する必要があります。未定義の ID を指定すると、nvpmodel は起動時に適用できません。

Operation 5 — 定義済みの電力モードを一覧表示する

これは読み取り専用の操作です。オーバーレイトラッカーのセットアップは必要ありません。調査するコピー（元の状態なら <bsp_image.root_path>/...、編集後の状態なら <source.root_path>/...）に対して実行します：

grep -E '^< POWER_MODEL ' <per-board file>
grep -E '^< PM_CONFIG '   <per-board file>

1つ目のコマンドはすべての ID／NAME を出力し、2つ目のコマンドは現在の起動時デフォルトを出力します。実行中のターゲットでは、nvpmodel -p --verbose（または nvpmodel -q）が正確な情報を示します。

制限事項

• BSP 側の範囲に限られます。このスキルが実行中のターゲットで nvpmodel -m を実行することはありません。稼働中のモード切り替えには、Deploy による再起動、または ## Deploy で説明されているサイドチャネルの scp + nvpmodel -m フローが必要です。
• 編集は <source.root_path> 配下のオーバーレイコピーにのみ反映されます。<bsp_image.root_path> のコピーは読み取り専用であり、/jetson-promote-image によって書き換えられます。bsp_image を手動編集しても、次回の /jetson-init-image による再抽出時に何も通知されず失われます。
• 周波数の値は、対象のクロックについてカーネルの available_frequencies テーブルにある値を使う必要があります。テーブルにない値は、通知されずに最も近い値に丸められます。このスキルは実行中のターゲットのテーブルに照らした検証を行いません。ボードごとのファイルにある既存の値と Power Estimator の出力を信頼してください。
• エンベロープの大幅な編集（CPU／GPU／EMC／PVA／DLA の MAX_FREQ／MIN_FREQ の変更）には NVIDIA Power Estimator（https://jetson-tools.nvidia.com/powerestimator/）が必要です。既存のモード間での補間や外挿はサポートされていません。
• 子ボード間への反映は、意図的に一部のみとなっています。変更された POWER_MODEL／PARAM の行だけが反映され、ファイル全体が一括で上書きされることはありません。これは、_super の子ボードが持つ引き上げられた MAX_FREQ／MIN_FREQ の上限を維持するためです。
• PARAM 名はチップファミリーによって異なります（例：T234 では CPU_A78_<n>、T264 では異なる名称）。既存の POWER_MODEL ブロックからそのままコピーしてください。独自に作成した名称は、通知されずに適用に失敗します。

トラブルシューティング

エラー	原因	解決策
起動時に nvpmodel がデフォルト設定を適用できない	PM_CONFIG DEFAULT=<id> が、削除済みまたは存在しない POWER_MODEL ID を参照している	同じファイル内にある既存の < POWER_MODEL ID=<n> ... > を DEFAULT= に指定してください。
周波数の値が適用されず、何も通知されない	そのクロックについて、カーネルの available_frequencies テーブルに値がない	実行中のターゲットの available_frequencies（または Power Estimator の出力）から、最も近い有効な値に置き換えてください。
MAX_FREQ -1 を指定しても何も起きない	TYPE=FILE の PARAM で -1 を指定している（TYPE=CLOCK でのみ有効）	-1 は CLOCK パラメーターでのみ使用してください。FILE パラメーターでは、sysfs ノードが想定する実際の文字列を指定してください。
編集後にモジュールが停止する／起動できなくなる	CORE_0 がオフラインになった、またはモードがプラットフォームの最小静止エンベロープを下回った	CORE_0 はオンラインのままにし、SKU の Power Estimator で最も低消費電力のプロファイルを基準に MIN_FREQ の下限を設定してください。
実行時に nvpmodel -m <id> が "ID not found" を返す	モード ID が削除または変更されたが、rootfs のスクリプトが古い ID を参照している	grep -rn 'nvpmodel -m' rootfs/etc rootfs/opt を実行し、古い参照を更新または削除してください。
/jetson-init-image による再展開後に変更が消えた	編集が <source.root_path> オーバーレイではなく、<bsp_image.root_path> に反映された	オーバーレイ編集手順に従って再適用し、変更がオーバーレイトラッカーに記録されるようにしてください。
伝播後に _super の兄弟設定で強化された上限が失われた	ファイル全体のコピーにより、_super のより高い MAX_FREQ／MIN_FREQ が上書きされた	構造上の変更のみを反映し、伝播対象のセットに従って _super の上限を維持してください。
パーサーが新しい POWER_MODEL ブロックを拒否する	ヘッダー < … > が列 0 にない、< の後または > の前にスペースがない、または PARAM が事前に宣言されていない	ヘッダーの厳密な書式に戻してください。参照するすべての PARAM_NAME が、それより上にある < PARAM ... > ブロックで宣言されていることを確認してください。

デプロイ

オーバーレイトラッカー内のカスタマイズコミットは、それだけではデバイスに反映されません。デプロイの手順は次のとおりです。

1. /jetson-promote-image — オーバーレイ内の追跡対象ファイルをすべて <bsp_image.root_path>/Linux_for_Tegra/ にコピーします。差分を確認し、バイト単位で同一のファイルはスキップします。rootfs/* のコピー先には sudo cp -p を使用します。
2. /jetson-flash-image — 更新した bsp_image をデバイスにフラッシュします。
3. （フラッシュしない場合）<source.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/<conf> を実行中のターゲットの /etc/nvpmodel/<conf> に直接コピーし、その後 sudo nvpmodel -m <id> を実行します（新しい DEFAULT= を反映するには再起動してください）。

変更をコミットせずに <source.root_path>/... を編集した場合、または <bsp_image.root_path>/... を直接編集した場合、/jetson-promote-image には反映されず、次の /jetson-init-image による再展開時に通知なく失われます。