jetson-customize-clocks

クロックをカスタマイズする

目的

イメージを書き込む前に Linux_for_Tegra/ 以下のファイルを編集して、Jetson ターゲット上の CPU、GPU、EMC のクロック動作をカスタマイズします。対象となるレイヤーは次の 2 つです。

• Linux_for_Tegra/bootloader/<BPFDTB_FILE> にある BPMP DTB — クロックごとの max-rate-custom 上限と、EMC DVFS ゲート（すべての SoC で bwmgr + cactmon、T26x のみ osp-controller）。
• Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh にある nvpower.sh — cpufreq / devfreq ガバナーと、（任意で）起動時に sysfs へ書き込むデバイスごとの最小 / 最大 / 固定レート。

よくあるトリガー：「CPU/GPU/EMC の周波数を固定する」、「GPU を Fmax に固定する」、「EMC を MAXN に固定する」、「EMC DVFS を無効化／有効化する」、「CPU DVFS を無効化／有効化する」、「CPU/GPU の最大レートを設定する」、「cpufreq ガバナーを変更する」。

対象外：稼働中のターゲットでのランタイムクロック調整（フラッシュ手順なし）、nvpmodel の電力モード編集（兄弟スキル /jetson-customize-nvpmodel を使用）、およびシリコン上限のオーバーライド（max-rate-maxn は読み取り専用です）。

前提条件

../../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> は読み取り専用です。すべての書き込み（Operation 1 の BPMP DTB と Operation 2 の nvpower.sh）は <source.root_path>（オーバーレイトラッカー）以下に行います。これは ../../context/bsp-customization-workflow.md#workflow-invariants に記載されたワークフロー上の不変条件です。上流のファイルを手動編集すると、差分の追跡が知らないうちに失われ、/jetson-promote-image が何もしなくなります。

手順

1. 上記の前提条件（アクティブプロファイル、展開済みの BSP イメージ、初期化済みのソースオーバーレイトラッカー）を解決します。
2. 以下の表から操作を選択します。
3. リンク先の手順セクション（Operation 1（BPMP DTB）、Operation 2（nvpower.sh）、または両方を対象とする MAXN レシピ）に従います。
4. 各 Operation のコミット規約に従って、オーバーレイトラッカー内で編集をコミットします。
5. /jetson-promote-image → /jetson-flash-image でデプロイします。新しい BPMP DTB と nvpower.sh は次回の起動時に有効になります。

対応している操作

操作	編集箇所	手順セクション
CPU / GPU クロックを特定のレートに固定する	クロックノードの BPMP DTB max-rate-custom + nvpower.sh の performance ガバナー	「コンテンツの編集：max-rate-custom」+「編集内容を選択」
EMC を初期レートに固定する（EMC DVFS を無効化する）	BPMP DTB：bwmgr.enabled = 0、cactmon.enabled = 0、T26x のみ /delete-node/ osp-controller	「コンテンツの編集：EMC DVFS の無効化／有効化」
EMC DVFS を再有効化する	BPMP DTB：bwmgr.enabled = 1、cactmon.enabled = 1、T26x では osp-controller を復元	「コンテンツの編集：EMC DVFS の無効化／有効化」
ストレステスト実行時にすべてを MAXN に固定する	上記を組み合わせ、nvpmodel の MAXN を起動時のデフォルトに設定	レシピを参照
クロックを固定せずにハード上限を下げる	BPMP DTB max-rate-custom のみ	「コンテンツの編集：max-rate-custom」
固定せずにデバイスのレートを制限する	sysfs を介した nvpower.sh の最小／最大値	「編集内容を選択」

操作 1 — BPMP DTB の編集

../../references/bsp-customization-bpmp-dtb.md に記載された BPMP-DTB カスタマイズプロトコルに従ってください。 プロトコルでは、初回変更時の未変更ファイルのインポート、dtc による逆コンパイル、再コンパイル、健全性チェック、コミットといった手順を扱います。このスキルで扱うのは、クロック固有の内容（プロトコルの「DTS の編集」手順で編集するノードとプロパティ）のみです。

編集した .dtb は <source.root_path>/Linux_for_Tegra/ オーバーレイトラッカーに配置されます。/jetson-promote-image のチャネル A はトラッカーを走査し、ファイルを bsp_image にコピーします。<bsp_image.root_path>/Linux_for_Tegra/bootloader/<bpmp-dtb> を直接編集しないでください。これはプロモートの出力先であり、入力元ではありません。

SKU に適合する BPMP DTB の解決

プロトコルの「アクティブな BPMP DTB の解決」セクションに従い、アクティブなフラッシュ設定から BPFDTB_FILE を読み取ります。一般的な Thor／単一 SKU の設定形式では、ボードごとの .conf にある静的な BPFDTB_FILE=... 行を使用します。この値がそのまま正となります。

SKU 多重化された設定形式（update_flash_args_common を介して board_sku／board_FAB ごとに異なる BPMP DTB を選択する Orin AGX 開発キットの設定チェーン。詳しくは ../../context/bsp-customization-software-layers.md#per-board-conf-dispatch--update_flash_args_common を参照）では、アクティブなプロファイルの board_sku=<module.sku> と board_FAB=<module.revision or empty> を使ってディスパッチチェーンをたどり、ディスパッチ出力から BPFDTB_FILE を読み取ってください。ボードごとの .conf にある静的な行からは読み取らないでください。多重化されていない設定では静的な値とディスパッチ後の値は一致しますが、設定チェーンで BPFDTB_FILE が条件付きで上書きされる場合は、ディスパッチが必須です。

有効な最大レートの一覧表示（調査）

max-rate-custom の値を決める前に、実行時の上限を構成する両方のレイヤーを調査してください。詳しくは references/clock-control-model.md#effective-runtime-ceiling を参照してください。

BPMP 側の逆コンパイルと grep、nvpmodel 側の起動時デフォルトモードに対する awk を使った調査手順は、references/bpmp-dtb-clock-edits.md#inspection-cookbook にあります。

nvpmodel レイヤーについては、/jetson-customize-nvpmodel を参照してください。

この手順では状態を変更しません。「内容の編集：名前付きクロックノードの max-rate-custom」手順で編集値を決めるための事前条件です。

内容の編集：名前付きクロックノードの max-rate-custom

プロトコルの「DTS の編集」手順では、名前付きクロックノード内のプロパティを変更してください。lateinit は変更しないでください。max-rate-custom は、クロックのハード上限（定義されている場合は max-rate-maxn、それ以外は同じチップ／SKU の実行中ターゲットにおける現在の max_rate）を厳密に下回る必要があります。

DTS の編集形式、意味、および nvpmodel と BPMP のクロックノードの対応関係については、references/bpmp-dtb-clock-edits.md を参照してください。

その後、プロトコルに作業を引き継いでください。「再コンパイル」、「再コンパイルした blob の健全性チェック」、「オーバーレイトラッカーへのステージング」、「クリーンアップ」の手順で残りを行います。 プロトコルに従ったコミットメッセージの形式： <BPMP_BASENAME>: jetson-customize-clocks — <clock-node> max-rate-custom = <value>。

コンテンツの編集：EMC DVFS の無効化／有効化

デフォルトの動作（EMC DVFS は有効）では、編集は不要です。EMC DVFS を無効にするには、プロトコルの同じ「DTS の編集」ステップ内で適用する複数ノードの編集が必要です。bwmgr の切り替えではありません。

#	編集	対象範囲
1	bwmgr.enabled = <0x00>	すべての SoC で必須
2	cactmon.enabled = <0x00>	すべての SoC で必須
3	/delete-node/ osp-controller	T26x（Thor）では必須 — T23x（Orin）にはこのノードがないため、スキップ

判定方法：dtc -I dtb -O dts <bpmp-dtb> | grep -c osp-controller — 該当なし ⇒ T23x の手順です。DTS の完全なスニペット、経路が残った場合の失敗モード、再有効化の手順については references/emc-dvfs-disable.md を参照してください。

複数ノードの編集を適用したら、プロトコルの「再コンパイル」から「クリーンアップ」までのステップを実行します。コミットメッセージの規約： <BPMP_BASENAME>: jetson-customize-clocks — EMC DVFS disable (bwmgr + cactmon[+ osp-controller])。

無効にするとアイドル時の消費電力が増加します。本番環境のルートファイルシステムではなく、ストレステスト／パフォーマンステスト向けです。

再実行と冪等性

プロトコルの「再実行可能性」セクションに従い、同じ目標値でこのスキルを再実行すると、変更のないコミットが作成されます。異なる値で再実行すると、同じプロパティが書き換えられます。git log -- $BPMP_REL で実行ごとの履歴を確認できます。クロックを max-rate-maxn の上限に戻すには、DTS を編集して max-rate-custom の行を削除し、再コンパイルしてください。

操作 2 — nvpower.sh の編集

起動時に nvpower.service 経由で実行され、cpufreq／devfreq のガバナーとレートを設定する nvpower.sh を編集します。

スクリプトごとのファイル

この操作で編集するスクリプトの相対パスは次のとおりです。

Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh

このファイルは2 つのルートに存在します。この操作では両方を処理します。

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

以降のサブステップでスクリプトごとのファイルという場合は、<source.root_path> 以下のオーバーレイコピーを指します。<bsp_image.root_path> のコピーは、以下の変更前インポート手順で一度読み取られ、その後は一切変更されません。

オーバーレイ編集の手順（nvpower.sh の編集前に適用）

ワークフロードキュメントにある標準の スキル外編集の手順に従ってください。変更前のインポートとカスタマイズのコミットを組み合わせ、どちらもプレビューゲートで実行可否を判定します。nvpower.sh は伝播対象がない単一ファイルのため、変更全体を変更前のコミット 1 つとカスタマイズのコミット 1 つで網羅できます。

このスキルでの具体的な置き換え：

• <rel>/<file> は rootfs/etc/systemd/nvpower.sh です。
• 変更前インポートに推奨するメッセージ： import pristine: rootfs/etc/systemd/nvpower.sh、 本文 Source: <bsp_image.root_path>/Linux_for_Tegra/ (BSP <bsp_image.version>)。
• カスタマイズのコミットヘッダーに推奨する内容： jetson-customize-clocks: nvpower.sh <summary>、 本文の行は set_cpufreq_governor: desired_cpufreq_gov "schedutil" -> "performance" のようにします。

編集内容を選択する

関数の場所（set_cpufreq_governor、set_devfreq_governor）、一般的な編集手順（Fmax に固定、静的レート、最小値／最大値の境界）、および nvidia-l4t-init パッケージのアップグレードに関する注意事項については、references/nvpower-sh-edits.md を参照してください。

デプロイ

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

1. /jetson-promote-image — オーバーレイ内で追跡されているすべてのファイルを <bsp_image.root_path>/Linux_for_Tegra/ にコピーします。差分を考慮し、バイト単位で同一のファイルはスキップします。rootfs/* のコピー先には sudo cp -p を使用します。
2. /jetson-flash-image — 更新した bsp_image をデバイスにフラッシュします。次回の起動時に nvpower.service が新しいスクリプトを実行します。
3. （フラッシュしない場合の代替手順）<source.root_path>/Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh を実行中のターゲットの /etc/systemd/nvpower.sh に直接コピーしてから、sudo systemctl restart nvpower.service を実行します（または再起動します）。

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

手順 — ストレステスト／パフォーマンス実行ですべてを MAXN に固定する

操作 1 と 2 を組み合わせます。操作 1 の BPMP 編集はすべて、プロトコルを一度だけ実行して反映します（単一の逆コンパイル／複数ノードの編集／再コンパイル／コミットのサイクルです。同じ .dtb に対してプロトコルを二度実行しないでください）。

1. BPMP DTB（「コンテンツ編集：名前付きクロックノードの max-rate-custom」の手順）— すべての CPU／GPU／EMC クロックで max-rate-custom を未設定のままにし、上限を引き下げる既存の max-rate-custom 行を削除します。
2. BPMP DTB（「コンテンツ編集：EMC DVFS の無効化／有効化」の手順）— EMC を初期化時のレートに固定します。bwmgr.enabled = 0、cactmon.enabled = 0 を設定し、T26x では /delete-node/ osp-controller を追加します（T23x では不要です）。
3. 両方のコンテンツ編集を、プロトコルの「DTS を編集」ステップ内で実行してから、残りのプロトコル手順（再コンパイル、整合性確認、両方のコンテンツ編集を含む単一のカスタマイズコミット）を実行します。
4. nvpower.sh（操作 2）— desired_cpufreq_gov="performance" と desired_devfreq_gov="performance" を無条件に設定し、set_devfreq_governor 内の GPU／nvjpg スキップを削除します。操作 2 のオーバーレイ編集手順（「nvpower.sh を編集する前に適用するオーバーレイ編集手順」）を使って適用します。これは、rootfs スクリプトに対する別個のオーバーレイトラッカーの初期状態コミットとカスタマイズコミットのペアであり、BPMP-DTB プロトコルのコミットとは別です。
5. /jetson-customize-nvpmodel を使って、起動時のデフォルト nvpmodel モードを MAXN に設定します。BPMP DTB の内容にかかわらず、クロックごとの nvpmodel 上限により max-rate-maxn より低い値に制限されます。

次回のフラッシュ時に、新しい BPMP DTB（オーバーレイトラッカー経由）と編集済みの nvpower.sh（同じオーバーレイトラッカー経由）が反映されるよう、/jetson-promote-image → /jetson-flash-image の順に実行します。

制限事項

• イメージのビルド時のみ対応します。 すべての編集は <source.root_path>/Linux_for_Tegra/ 以下に適用され、デバイスに反映されるのは /jetson-promote-image → /jetson-flash-image を経由する場合のみです。稼働中のターゲットの調整は対象外です。
• max-rate-custom は上限を引き下げる場合にのみ使用できます。 max-rate-maxn より厳密に低くする必要があります。シリコンの上限を引き上げることはサポートされていません。
• 実効上限は2層で決まります。 実行時の上限は min(BPMP cap, active-nvpmodel-mode cap) です。nvpmodel の上限は /jetson-customize-nvpmodel が管理します。このスキルでは編集しません。
• EMC DVFS の無効化には SoC に応じたゲートがあります。 EMC DVFS を無効にするには、T23x（bwmgr + cactmon）と T26x（bwmgr + cactmon + osp-controller の削除）で異なるノードセットを編集する必要があります。検出を誤ると、動作は未定義になります。
• T23x の GPU 上限は複数のノードにまたがります。 GPU クロックは nafll_gpusys とすべての nafll_gpcX に分かれているため、すべてに適用した場合にのみ上限が有効になります。
• nvpower.sh はパッケージで管理されています。 nvidia-l4t-init に含まれており、パッケージをアップグレードすると、直接編集した内容は上書きされます。長期運用では、systemd のドロップインまたは隣接するヘルパーを使用してください。
• ODMDATA が優先されます。 ODMDATA トークンがプロパティを対象としている場合、フラッシュ時にそのトークンが BPMP DTS の直接編集より優先されます。NVIDIA のどのトークンも対象としないプロパティには、BPMP DTS の直接編集をフォールバックとして使用します。
• max-rate-maxn と lateinit は変更禁止です。 max-rate-maxn はシリコンの上限であり、読み取り専用です。lateinit は起動時のクロック初期化用で、上限の上書きには使用しません。どちらにも手を加えないでください。
• BPMP DTB は SKU によって切り替わる場合があります。 複合またはディスパッチ型のフラッシュ設定（Orin AGX 開発キットのチェーンなど）では、update_flash_args_common を介して board_sku / board_FAB に基づき BPFDTB_FILE が選択されます。チェーン条件によって上書きされる場合、静的な BPFDTB_FILE= の行を読むのは誤りです。ディスパッチを使って解決してください。

トラブルシューティング

エラー	原因	解決策
T23x GPU で max-rate-custom を設定しても、クロックが max-rate-maxn まで上昇する	nafll_gpusys のみが制限されており、nafll_gpcX パーティションは max-rate-maxn で動作し、実効上限を決定しています。	grep -nE '^\s*nafll_gpc[0-9]+\s*:' <decompiled.dts> で列挙される nafll_gpusys およびすべての nafll_gpcX ノードに、同じ max-rate-custom を適用します。
T26x で EMC DVFS の無効化が適用されたように見えても、EMC のスケーリングが続く	bwmgr.enabled = <0x00> のみが設定されており、osp-controller が残って QoS 経由で周波数変更を再発行しています。	同じ「DTS を編集する」手順内に編集 #2（cactmon.enabled = <0x00>）と #3（/delete-node/ osp-controller）を追加します。dtc -I dtb -O dts <bpmp-dtb> | grep -c osp-controller で osp-controller を確認します。結果は 0 になるはずです。
T23x で EMC DVFS の無効化が「node not found」で拒否される（osp-controller）	T23x（Orin）の BPMP DTB には osp-controller が含まれていないため、T23x では編集 #3 を省略する必要があります。	grep -c osp-controller の手順で SoC ファミリーを判定し、カウントが 1 以上の場合にのみ #3 を適用します。
編集後、BPMP が DTB の読み込みを拒否する：max-rate-custom >= max-rate-maxn	max-rate-custom がシリコンの上限以上に設定されています。	max-rate-custom を max-rate-maxn より厳密に小さい値にします。ノードに max-rate-maxn がない場合は、実行中のターゲットで cat /sys/kernel/debug/bpmp/debug/clk/<clock>/max_rate を実行して、現在の上限を確認します。
status = "disabled" の後に osp-controller が再び現れる	status = "disabled" ではデバイスツリーからノードが削除されず、BPMP は引き続きそのノードを走査します。	/delete-node/ osp-controller; に置き換えます。BPMP にその経路をスキップさせるには、ノード自体が存在してはなりません。
apt upgrade 後に nvpower.sh の編集が失われる	nvpower.sh は nvidia-l4t-init deb が所有しており、アップグレード時に上書きされます。	長期的に使用するテスト環境では、nvpower.sh を直接編集するのではなく、編集内容を systemd のドロップイン、または nvpower.sh から参照する別のヘルパーファイルにまとめます。
BPMP DTB の編集後、/jetson-promote-image が何も実行しない	編集が <bsp_image.root_path>/Linux_for_Tegra/ に適用されていますが、これは /jetson-promote-image の入力ではなく出力です。	編集を <source.root_path>/Linux_for_Tegra/bootloader/<BPFDTB_FILE>（オーバーレイトラッカー）に移し、BPMP-DTB プロトコルを通じてコミットします。
初回起動では上限が適用されるように見えるが、電源モード変更後にリセットされる	アクティブな nvpmodel モードのクロックごとの上限が、max-rate-custom より低い値に制限しています。	両方のレイヤーを確認します。nvpmodel が制約となっている場合は、/jetson-customize-nvpmodel を使って nvpmodel の上限を引き上げる（または削除する）必要があります。BPMP の上限だけでは実行時の上限は決まりません。

参考資料

• ../../references/bsp-customization-bpmp-dtb.md — BPMP-DTB のカスタマイズに関する標準プロトコル（未変更状態でのインポート、逆コンパイル、編集、再コンパイル、健全性チェック、コミット）。このスキルの操作 1 はコンテンツのみを扱い、手順の詳細はプロトコルに従います。
• references/clock-control-model.md — レイヤースタック、2 つの上限の概要、実効実行時上限の計算式。
• references/bpmp-dtb-clock-edits.md — 2 つの上限の意味、DTS の編集形式、nvpmodel と BPMP クロックノードの対応、調査手順。
• references/emc-dvfs-disable.md — DTS スニペット、検出、再有効化を含む、SoC 条件付き EMC DVFS 無効化の全手順。
• references/nvpower-sh-edits.md — nvpower.sh の関数の場所、一般的な編集レシピ、パッケージアップグレードに関する注意点。
• /jetson-customize-nvpmodel — 関連スキル：nvpmodel の電源モード。アクティブなモードのクロックごとの上限は、BPMP DTB の上限より低い値に制限します。