jetson-customize-camera

カメラのカスタマイズ（CSI／MIPI／GMSL センサーの立ち上げ）

概要

Tegra264（Thor）と Tegra234（Orin）は、NVCSI と固定の CSI ポート群が前段に接続された単一の tegra-capture-vi コントローラーを備えています。カメラの立ち上げは次のとおりです。

1. センサーの選択 — 対象のプラットフォームで使用する、NVIDIA がツリー内に用意している .dtsi 参照群から選択します。
2. キャリアとモジュールのサポート確認 — Camera Development Guide、Adaptation Guide §Camera、キャリアの回路図、 Module TRM、キャリアのピンマップを照合して確認します。
3. 配線 — ツリー内に存在する場合は、tegra<soc>-camera-<sensor>*.dtsi から導きます（配線の正解は DTSI です）。カスタムセンサーの場合は、センサーごとにユーザーから情報を取得します。
4. カーネル DT オーバーレイ — ツリー内の DTSI を cpp で展開し、その fragment@N 本体を抽出して、対象プラットフォーム用の複合カスタムオーバーレイ .dts に追加します（ ../../references/bsp-customization-kernel-dtb.md を参照）。fdtoverlay で複合オーバーレイを検証します。 /jetson-build-source が複合オーバーレイをコンパイルし、キャリア conf の OVERLAY_DTB_FILE+= 登録を管理します。

テーブル駆動ではなく、エージェント主導です — センサーの一覧は、ツリー内のセンサーごとの dtbo を実行時にグロブして作成します。_THOR_CAMERAS 辞書も、questions.json も、質問フローで使う Python レンダラーもありません。

ODMDATA は編集しません — カメラは UPHY レーンを使用しません（CSI は独立した PHY プールです）。このスキルが生成するのはカーネル DT オーバーレイのみです。キャリア conf の ODMDATA 行はこのスキルでは変更されません。

出力は1 つのコミットです。

• カメラの fragment@N ブロック（複合オーバーレイのルートにまだない場合は jetson-header-name も）を、対象プラットフォーム用の複合カスタムオーバーレイ .dts に追加します（ ../../references/bsp-customization-kernel-dtb.md を参照）。 → bsp_sources/ ハードウェアリポジトリにコミットします。 /jetson-build-source が複合オーバーレイを .dtbo にコンパイルし、Makefile と flash-conf への登録を管理します。

呼び出すタイミング

• ユーザーが「カメラを有効化」「CSI を設定」「Hawk／Owl／IMX センサーを配線」「MIPI カメラ」「GMSL カメラ」と言う場合、またはカスタムキャリアで tegra-capture-vi／NVCSI を立ち上げるよう依頼した場合。
• フラッシュ後に起動するものの、v4l2-ctl --list-devices に tegra-capture-vi チャネルが表示されない場合、または新しいドーターカード上でセンサーが認識されるか確認する必要がある場合。
• すでに有効になっているセンサーに加えて、別のセンサーを追加したい場合（マルチセンサーの立ち上げ）。

前提条件：

• reference_devkit: と custom_carrier: ブロックを含むアクティブなプロファイルがあること。
• <source.root_path>/Linux_for_Tegra/.git が存在すること（/jetson-init-source）。
• /jetson-derive-carrier が実行済みで、キャリアの flash-conf フォークがオーバーレイトラッカーに含まれていること。
• <source.root_path>/bsp_sources/hardware/nvidia/<chip-dir>/nv-public/overlay/ が存在し、ツリー内のセンサーごとの .dtsi ファイルが含まれていること（/jetson-init-source の Branch A アーカイブ展開で取得します）。
• <source.root_path>/bsp_sources/kernel/kernel-noble/include/dt-bindings/ に cpp が必要とするマクロヘッダーが含まれていること（Branch B を使用した場合は source_sync.sh の実行が必要な場合があります。以下の Step 5a.i を参照）。
• 信頼できる情報源となるドキュメントが登録済み、またはプロンプトで提供されていること：Camera Development Guide（bsp_developer_guide ミラー内または別のパス）、Adaptation Guide §Camera、キャリアの回路図、SoC TRM、Module Design Guide。
• dtc、cpp、fdtoverlay が PATH 上にあること。

手順

すべての表、コードブロック、ゲートを含む詳細な手順（ステップ 1～7）は、 references/procedure.md に記載されています。概要：

1. ステップ 1 — アクティブなターゲットを特定し、信頼できる一次資料のドキュメントを開きます。
2. ステップ 2 — プラットフォームごとのカメラ用 dtbo をリポジトリ内で glob 検索し、対応センサーを列挙して、DPHY 直結／GMSL／カスタムに分類します。センサーを捏造してはいけません。
3. ステップ 3／3a — キャリアボードとモジュールのサポート状況を、DTSI、Camera Development Guide、Adaptation Guide §Camera、SoC TRM、Module Design Guide、回路図、キャリアボードのピンマップと照合します。配線表を先に表示してから、確認またはカスタマイズのゲートを提示します。
4. ステップ 4（カスタム経路のみ）— キャリアボードのピンマップから自動入力した、センサーごとの配線に関する質問をまとめて提示します。
5. ステップ 5 — 合成カスタムオーバーレイ .dts に /* custom-bsp: camera:<sensor> */ フラグメントを正確に 1 つ追加します（../../references/bsp-customization-kernel-dtb.md を参照）。 クローン経路ではリポジトリ内の DTSI を cpp で展開し、カスタム経路ではステップ 4 の回答とモードテーブルをその場で挿入します。合成ルートに jetson-header-name を冪等に設定します。 dtc と fdtoverlay で検証します（コンパイル前は単一フラグメントのゲート、コンパイル後はディープツリーの一意性ゲート）。ワークフローのコミットメッセージプレビューゲートを通じてコミットします。
6. ステップ 6 — 補助的な CAM ピンの SFIO（cam_i2c_*、extperiph<m>_clk、reset／PWDN／PWR_EN GPIO）を pin_verifier.py で検証し、不一致があれば /jetson-customize-pinmux に回します。
7. ステップ 7 — <workspace>/target-platform/<profile-stem>.jetson-customize-camera.json に実行状態の JSON サイドカーをアトミックに書き込み、見出しを出力します。その後、references/procedure.md のステップ 7 に従い、AskUserQuestion プロンプトを順番に表示して、後続の次のステップへのチェーンを進めます。このチェーンは明記されたワークフローゲートであり、確認質問ではありません。自動モードでも省略できません。 プロンプトの代わりに「次のステップ：…」という行を表示してはいけません。

注意点

• 2 つのフラグメントに関する落とし穴です。 カメラタグ付きの fragment@N を、コンポジットに正確に 1 つだけ追加してください。ステータスオーバーライドを含む 2 つ目のフラグメントを追加すると、dtc のディープマージがトリガーされ、兄弟サブツリーが重複します（例：2 つの tca9546@70）。その結果、実行時の最初の一致処理で dtsi から提供されたディープツリーが破棄され、カメラが何も表示せずに列挙されなくなります。このスキル固有のマーカーだけで判定してください（Step 5c）。
• コンポジットルートの compatible は、このスキルではなく全体で管理します。 ツリー内のセンサーごとの dtbo の compatible（devkit SKU による制限）を根拠に、適用範囲を広げないでください。必要に応じてコンポジットルートを修正してください。
• ツリー内のセンサーごとの dtbo にある jetson-header-name を使用します。 これはキャリアに依存しない固定値です。一度読み取り、メタデータルートに貼り付けてください。
• ツリー内のセンサーごとの dtbo を OVERLAY_DTB_FILE にも追加しないでください。 レンダリングしたオーバーレイと、ツリー内の tegra<soc>-p3971-camera-<sensor>-overlay.dtbo の両方を登録すると、ファントム subdev バインドが発生し、カメラの列挙が壊れます。
• スタブオーバーレイは既知の落とし穴です。 ポート、センサー、nvcsi の本体がない状態で tegra-capture-vi { status="okay"; num-channels=<N>; } をコミットすると、カメラが壊れます（all channel init failed）。cpp + dtc を使ってセンサー本体をすべて組み込んでください。
• センサーのモードテーブルは手書きせず、組み込んでください。 mode<N>、sensor_modes、pixel_phase は、最も近いツリー内の DTSI からそのままコピーしてください。
• camera_common_regulator_get (null) ERR: -EINVAL は、avdd-reg／iovdd-reg／dvdd-reg 文字列が不足していることを示します。センサー本体をすべて組み込んでください。常時オンの電源レールはダミーレギュレーターにフォールバックします。
• 外部の &label 参照は、ベース DTB の __symbols__ に存在する必要があります。 ラベルがない場合は target-path = "/tegra-capture-vi" を使用してください。そうしないと fdtoverlay は FDT_ERR_NOTFOUND で終了します。
• cpp で dt-bindings/gpio/gpio.h: No such file が発生する場合、L4T ソースツリーがステージングされていません。/jetson-init-source を再実行してください（Branch B の source_sync.sh がヘッダーを取得します）。マクロ展開を捏造しないでください。
• ODMDATA もフラッシュ設定も編集しないでください。 カメラは UPHY レーンを使用しません。キャリア設定ファイルの ODMDATA="..." は変更しません。OVERLAY_DTB_FILE+= は /jetson-build-source の Step 5.0a が管理します。このスキルではキャリアのフラッシュ設定ファイルには一切触れません。
• <bsp_image.root_path> にあるアップストリーム BSP には触れないでください。 すべての編集は、既存状態の維持とカスタマイズのコミットを組み合わせるパターンに従い、<source.root_path>/Linux_for_Tegra/（オーバーレイトラッカー）と <source.root_path>/bsp_sources/（オーバーレイ .dts）に適用してください。

参考資料

• references/procedure.md — Step 1～7 の手順全体（この SKILL.md から抽出）。
• references/csi-dt-bindings.md — CSI／nvcsi／vi の DT バインディングに関する参考情報。
• references/overlay-template.md — メタデータルート＋クローン本体のオーバーレイ構成に関するガイダンス。
• references/camera-overlay-templates/ — スターター用 .dts.tmpl テンプレート：dphy-direct.dts.tmpl、 gmsl-serdes.dts.tmpl。
• ../../scripts/pin_verifier.py — 共有 HSIO ピン検証ツール（Step 6）。
• ../../references/platform_template.yaml — Step 1 で使用する documents: ブロック。
• ../../context/bsp-customization-workflow.md — オーバーレイ編集プロトコル。
• ../jetson-customize-pinmux/SKILL.md — Step 6 で自動的に呼び出され、HSIO ピンの SFIO 不一致（CAM I²C、MCLK、リセット GPIO）を修正する関連スキル。
• ../jetson-derive-carrier/SKILL.md — 最初に実行する必要があります。このスキルのコンポジットがその後に重ねるキャリアベースオーバーレイ（*-dynamic.dtbo）を生成します。
• ../jetson-init-source/SKILL.md — オーバーレイトラッカーと bsp_sources リポジトリ（このスキルが読み取り、コミットする hardware/nvidia/<chip-dir>/ のセンサーごとの DTSI ツリーを含む）を生成します。