jetson-customize-fan

nvfancontrol のファンプロファイルを変更する（BSP 側）

目的

ボードごとの nvfancontrol 設定を編集し、デバイスの起動時に目的のファンカーブ／制御モード／ガバナー／デフォルトプロファイルが適用されるようにします。BSP 側のみが対象です。すべての書き込みはオーバーレイトラッカーに反映され、上流の bsp_image コピーは読み取り専用です。

このスキルでは、ボードごとの nvfancontrol 設定ファイルを BSP 側で編集します。プロファイルの追加や削除、温度 → PWM／RPM カーブの編集、起動時のデフォルトプロファイル／制御モード／ガバナーの変更、定義済みプロファイルの一覧表示を行います。Jetson／Tegra プラットフォーム（T234 Orin、T264 Thor）が対象です。

ファイル形式（BSP ファイルヘッダーに基づく正式な形式）

POLLING_INTERVAL <seconds>

<FAN <index>>
    TMARGIN <ENABLED|DISABLED>
    FAN_GOVERNOR <type> {
        STEP_SIZE <int>
    }
    FAN_CONTROL <close_loop|open_loop> {
        RPM_TOLERANCE <rpm>
    }
    FAN_PROFILE <name> {
        # TEMP HYST PWM RPM
        <T0> <H0> <P0> <R0>
        ...
    }
    FAN_PROFILE <name> { ... }       # one or more profiles
    THERMAL_GROUP <id> {
        GROUP_MAX_TEMP <C>
        # zone-name <coeffs csv> <max-temp>
        <zone> <coeffs> <max-temp>
        ...
    }
    FAN_DEFAULT_CONTROL  <close_loop|open_loop>
    FAN_DEFAULT_PROFILE  <name>
    FAN_DEFAULT_GOVERNOR <type>
    KICKSTART_PWM <0..255>

ルール：

• プロファイルカーブのタプルは 4 列です：TEMP HYST PWM RPM。点は TEMP の昇順に並べます。デーモンはその間を補間します。
• PWM は 0..255（8 ビットのデューティサイクル）です。RPM は閉ループの目標回転速度です。末尾の 0 0 行を高温側に置くと、GROUP_MAX_TEMP を超えたときにファンが停止します。
• HYST はその点でのヒステリシス（°C）です。コントローラーは、カーブを下げる前に HYST 度冷却するまで待機します。
• FAN_DEFAULT_PROFILE は、同じ <FAN N> 内の既存の FAN_PROFILE ブロックを参照する必要があります。デフォルトに存在しないプロファイルを指定すると、nvfancontrol は起動に失敗します。
• FAN_DEFAULT_CONTROL は、目標 RPM に向けて制御する close_loop（タコメーターが必要）または PWM を直接書き込む open_loop です。
• FAN_DEFAULT_GOVERNOR は cont（連続補間）およびその他のファミリー固有の値です。新たに導入する場合は、既存のボードごとのファイルからそのままコピーしてください。
• THERMAL_GROUP は、サーマルゾーンをコントローラーの入力にマッピングします。係数は 20 要素の CSV です。チップファミリーやゾーンによって値が異なるため、既存のエントリーからそのままコピーしてください。
• <FAN N> はファンインデックスごとに 1 つのブロックです（一般的には <FAN 1>）。ブロックの境界 <...> と {...} は厳密です。隣接する行に合わせてインデントを維持してください。
• カーブは実測に基づいて設定し、創作しないでください。 そのプラットフォームの実際の熱・音響データを使ってカーブを追加または編集してください。隣接するプロファイルから補間したり、異なるチップファミリー間でコピーしたりしないでください。

前提条件

../../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/nvpower/nvfancontrol/nvfancontrol_<active-sku>.conf

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

役割	場所	スキルによる書き込み
検出＋変更前の元ファイル	<bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/	なし — 読み取り専用
オーバーレイ編集対象＋git コミット	<source.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/	あり

以降のセクションでボードごとのファイルという場合は、<source.root_path> 配下のオーバーレイコピーを指します。操作 1～4 はすべて、そのオーバーレイコピーを対象に読み取り、編集、保存します。<bsp_image.root_path> のコピーは、「<active-sku> の解決」検出ステップと、オーバーレイ編集レシピの変更前ファイル取り込みステップでそれぞれ一度読み取るだけで、その後は一切触れません。

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

ファイル名の規則は製品ファミリーによって異なります。

• nvfancontrol_<module.id>_<module.sku>.conf — ほとんどの Orin パーツ（例：nvfancontrol_p3767_0000.conf、nvfancontrol_p3701_0008.conf）。
• nvfancontrol_<module.id>_<module.sku>_<carrier.id>_<carrier.sku>.conf — キャリアによって区別される Thor のバリアント（例：nvfancontrol_p3834_0008_p4071_0000.conf）。
• nvfancontrol_<carrier>_<sku>_<rev>.conf — IGX のリビジョンバリアント（例：nvfancontrol_p3740_0002_b01.conf）。

nvfancontrol デーモンは、起動時に起動したハードウェアの DT compatible とボード ID に基づいて適切なファイルを解決します（ヘルパースクリプトはなく、バイナリ内部で処理されます）。実行中のターゲットがない状態で BSP 側を照合するには、<bsp_image.root_path> を対象に次の手順を実行します。

1. <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/ を一覧表示します。
2. アクティブプロファイルの <module.id>_<module.sku> を含むファイル名に絞り込みます。
3. 候補が複数残る場合は、<carrier.id>_<carrier.sku> と（該当する場合は）キャリアのリビジョンタグでさらに絞り込みます。
4. それでも曖昧な場合は、ボードごとのフラッシュ設定ファイルのディスパッチチェーンを実行して、カーネル DTB の compatible を読み取り、解決したボード／キャリアと名前が一致するファイルを選びます。
5. 選択したファイルが <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/ に実際に存在することを確認します。

ファイル名を推測で組み立てないでください。命名規則は製品ファミリーによって異なります。

伝播対象 — 同期する設定ファイル

カスタマイズを適用すべき設定ファイルは、アクティブ SKU のファイルだけとは限りません。編集後は、変更がどのモジュール／ベースボード SKU で起動しても維持されるよう、伝播対象内のすべての兄弟ファイルに同じ編集を適用してください。

• リファレンスプラットフォームの nvfancontrol 設定ファイル — アクティブファイルの元となった上流の設定ファイルです（アクティブプロファイルの reference_devkit、または jetson-derive-carrier のフォーク履歴から解決します）。派生キャリアがなくリファレンスのみを含む BSP では、アクティブファイルと同じファイルのため、この規則は何もしません。
• キャリア派生の nvfancontrol 設定ファイルすべて — 同じモジュール SKU 上のカスタムキャリア向けに jetson-derive-carrier が生成した各 nvfancontrol_*.conf です。

「同じ編集を適用する」ことは、ファイル全体を一律にコピーすることではありません。 変更した FAN_PROFILE／制御行を各兄弟ファイルに反映し、その他の行はすべて保持します。兄弟の設定ファイルには、キャリア固有の差分（異なる熱設計に対応する異なる THERMAL_GROUP 係数、異なるタコメーターの RPM 上限など）が含まれていることが多く、これらは維持する必要があります。ファイル全体を上書きすると、そのキャリアでファンの調整が不適切になるおそれがあります。ファイル全体のコピーが安全なのは、編集前の両方の設定ファイルがバイト単位で同一だった場合に限られます。

オーバーレイ編集レシピ（いずれの操作よりも先に適用）

ワークフロードキュメントにある正規の スキル外の編集レシピ に従ってください。プレビューゲートを通過させたうえで、クリーンなインポートとカスタマイズのコミットをペアで行います。実行ごとに一度適用し、その実行で変更するボードごとのすべてのファイル（対象の conf と 同期を保つ伝播セットに含まれるすべての同類ファイル）を対象とします。

このスキルでの具体的な置換内容は次のとおりです。

• <rel>/<file> は rootfs/etc/nvpower/nvfancontrol/<conf> です。
• クリーンなインポートの推奨メッセージ： import pristine: <comma-separated rel paths of imported confs>、 本文 Source: <bsp_image.root_path>/Linux_for_Tegra/ (BSP <bsp_image.version>)。
• カスタマイズコミットの推奨ヘッダー： jetson-customize-fan: <summary>、 本文には次のような行を記載します。nvfancontrol_p3767_0000.conf: added FAN_PROFILE static (open-loop, PWM=255 flat), FAN_DEFAULT_CONTROL close_loop -> open_loop, FAN_DEFAULT_PROFILE quiet -> static

手順

ユーザーの意図に合った操作を選び、該当するサブセクションに従ってください。書き込みを行うすべての操作（1～4）では、まずオーバーレイ編集レシピを適用する必要があります。

• 操作 1 — 新しいファンプロファイルを追加します。
• 操作 2 — ファンプロファイルを削除します。
• 操作 3 — 既存のファンプロファイルを編集します（カーブ、ヒステリシス）。
• 操作 4 — 起動時のデフォルトを変更します（制御／プロファイル／ガバナー）。
• 操作 5 — 定義済みのファンプロファイルを一覧表示します（読み取り専用）。

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

例

P3767-0000（Orin Nano 開発キット）ターゲットに強力なプロファイルを追加し、起動時のデフォルトに設定します。

/jetson-customize-fan
> add a profile called "aggressive" with the curve {0:255, 40:150, 80:0}
> set FAN_DEFAULT_PROFILE to aggressive

既存の quiet プロファイルのファン回転の立ち上がりを緩やかにします（HYST を上げ、中間 PWM を下げます）。

/jetson-customize-fan
> edit FAN_PROFILE quiet — raise HYST to 5 from 30 °C up, drop PWM at 60 °C to 80

現在の SKU で定義されているプロファイルと、起動時のデフォルトを一覧表示します。

/jetson-customize-fan
> list defined fan profiles

操作 1 — 新しいファンプロファイルを追加する

まずオーバーレイ編集レシピを適用してください。

1. ボードごとのファイルで、<FAN N> ブロック内の既存プロファイルの間に、新しい FAN_PROFILE <name> { ... } を追加します。デーモンの解析順序は関係ありませんが、同類のプロファイルとまとめるとファイルを確認しやすくなります。
2. <name> は空白を含まない小文字にします（例：quiet、cool、aggressive）。
3. カーブテーブルを入力します。4 列の TEMP HYST PWM RPM タプルを TEMP の昇順に並べます。過熱時の動作を定義するため、GROUP_MAX_TEMP を超える行を少なくとも 1 行最後に追加します。

スケルトンの例：

FAN_PROFILE aggressive {
    #TEMP HYST PWM RPM
    0    0    255 6000
    20   2    255 6000
    40   2    150 3500
    60   2    50  1500
    80   0    0   0
    105  0    0   0
}

検証します（ルールを参照）。

• すべての TEMP が THERMAL_GROUP の 0..GROUP_MAX_TEMP の範囲内にあること。
• PWM ∈ [0, 255]、RPM ≤ プラットフォームのタコメーター報告による最大値（ファン部品によって異なります）。
• タプルが TEMP の昇順に並んでいること。

新しいプロファイルを起動時のデフォルトにする場合は、操作 4 に従ってください。

操作 2 — ファンプロファイルを削除する

まずオーバーレイ編集レシピを適用してください。

1. ボードごとのファイルから、曲線のすべての行と閉じ波括弧 } を含め、FAN_PROFILE <name> { ... } ブロック全体を削除します。
2. 削除した <name> が末尾の FAN_DEFAULT_PROFILE と一致する場合、FAN_DEFAULT_PROFILE を残っているプロファイルに設定します。そうしないと、デーモンが起動に失敗します。
3. 変更が安全だと判断する前に、rootfs 内でハードコードされた参照を検索します。

   grep -rn "nvfancontrol.*profile\|FAN_PROFILE" \
     Linux_for_Tegra/rootfs/etc 2>/dev/null
   

残りのプロファイルの名前を変更する必要はありません。

Operation 3 — 既存のファンプロファイルを編集する

まず、オーバーレイ編集の手順を適用します。

1. ボードごとのファイルで、対象のFAN_PROFILE <name>のカーブ行を変更します。4 列のTEMP HYST PWM RPM形式を維持してください。
2. TEMPの昇順を維持し、必要に応じて行を追加または削除します。
3. 振動を抑えるためにHYSTを調整します。値が低すぎると、カーブのポイント付近でファンが頻繁に回転数を変えます。高すぎると、実際の温度変化への追従が遅れます。
4. Operation 1 のルールに従って検証します。

KICKSTART_PWM、FAN_CONTROL内のRPM_TOLERANCE、またはFAN_GOVERNOR内のSTEP_SIZEを編集する場合、これらはプロファイル外にありますが、同じファンを調整します。ファイルは同じボードごとのファイルです。

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

まず、オーバーレイ編集の手順を適用します。

<FAN N>ブロック内の末尾にあるデフォルト行を編集します。

FAN_DEFAULT_CONTROL  <close_loop|open_loop>
FAN_DEFAULT_PROFILE  <name>
FAN_DEFAULT_GOVERNOR <type>

FAN_DEFAULT_PROFILEは、同じ<FAN N>ブロック内に存在するFAN_PROFILEを参照する必要があります。FAN_DEFAULT_CONTROLとFAN_DEFAULT_GOVERNORには、バイナリがサポートする値を指定する必要があります。変更する場合は、既存のボードごとのファイルからコピーしてください。

Operation 5 — 定義済みのファンプロファイルを一覧表示する

これは読み取り専用の操作のため、オーバーレイトラッカーのセットアップは不要です。調査するコピー（初期状態の場合は<bsp_image.root_path>/...、編集後の状態の場合は<source.root_path>/...）に対して実行します。

grep -E '^[[:space:]]*FAN_PROFILE ' <per-board file>
grep -E '^[[:space:]]*FAN_DEFAULT_'  <per-board file>

1 つ目のコマンドはファイル内のすべてのプロファイル名を出力し、2 つ目のコマンドは起動時のデフォルト（コントロール／プロファイル／ガバナー）を出力します。

制限事項

• 対象は BSP 側のみです。このスキルが、稼働中のターゲットの/etc/nvpower/nvfancontrol/を直接変更することはありません。実機での調整には、Deploy 経由での再起動、または## Deployで説明されているサイドチャネルのscp + systemctl restartの手順が必要です。
• 編集は<source.root_path>内のオーバーレイコピーにのみ反映されます。<bsp_image.root_path>のコピーは読み取り専用で、/jetson-promote-imageによって書き換えられます。bsp_imageを手動編集すると、次回の/jetson-init-imageによる再抽出時に変更が黙って失われます。
• カーブのタプルには、プラットフォームで特性評価された熱・音響データを反映する必要があります。このスキルは、チップファミリーをまたいだカーブの補間やコピーは行いません。
• 同じモジュール SKU を使用する兄弟キャリア間の反映は、設計上、一部に限られます。変更されたFAN_PROFILE／コントロール行のみを移植し、ファイル全体の上書きは行いません。兄弟側の設定ファイルには、キャリア固有のTHERMAL_GROUPや RPM 上限が含まれている場合があるためです。
• カーブポイントの上限はファミリーごとに異なります。新しいTHERMAL_GROUP係数やFAN_DEFAULT_GOVERNOR値を追加する場合は、既存の設定ファイルからそのままコピーしてください。

トラブルシューティング

エラー	原因	解決策
編集後に nvfancontrol.service が起動しない	FAN_DEFAULT_PROFILE が、削除または名前変更されたプロファイルを参照している	同じ <FAN N> 内にある既存の FAN_PROFILE <name> を FAN_DEFAULT_PROFILE に設定します。
カーブのポイント付近でファンが激しく変動する	HYST が低すぎる	該当する行の HYST を大きくします（通常は 2～5 °C）。
ファンの動作が実際の温度変化に遅れる	HYST が高すぎる	該当する行の HYST を小さくします。
高温時にファンがまったく回転しない	カーブに GROUP_MAX_TEMP を超える行がない、または末尾の 0 0 によって周囲温度を超える範囲が切り捨てられている	PWM/RPM が 0 以外の高温用タプルを追加します。過温度行を固定するのは GROUP_MAX_TEMP を超える範囲に限ります。
列数に関するデーモンの解析エラーが発生する	カーブの行が 4 列の TEMP HYST PWM RPM になっていない	4 列の形式に戻し、末尾の空白や余分な列を削除します。
close-loop で RPM の目標値に達しない	目標値がタコメーターで報告される最大値を超えている、または FAN_CONTROL が open_loop に設定されている	RPM をファンの機械的な最大値以下にするか、FAN_DEFAULT_CONTROL を close_loop に切り替えます。
/jetson-init-image による再展開後に変更が消えている	編集が <source.root_path> オーバーレイではなく、<bsp_image.root_path> に反映されている	オーバーレイ編集手順に従って再適用し、変更をオーバーレイトラッカーにコミットします。
変更の反映後、別のキャリアボードでタコメーターの上限が誤って設定されて起動する	ファイルを一括コピーしたことで、キャリアボード固有の THERMAL_GROUP / RPM 行が上書きされている	同期を維持する設定ファイルに従って、変更した行だけを反映し、キャリアボードの元の THERMAL_GROUP を復元します。

デプロイ

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

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/nvpower/nvfancontrol/<conf> を実行中のターゲットの /etc/nvpower/nvfancontrol/<conf> に直接コピーし、その後 sudo systemctl restart nvfancontrol.service を実行します（または再起動します）。

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