jetson-customize-camera

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Customize camera (CSI / MIPI / GMSL sensor bring-up)

自定义摄像头（CSI/MIPI/GMSL传感器启用）

Overview

概述

Tegra264 (Thor) and Tegra234 (Orin) expose a single

tegra-capture-vi

controller fronted by NVCSI and a fixed set of CSI ports. Camera bring-up is:

Sensor selection — picked from the set NVIDIA ships in-tree
```
.dtsi
```
references for on the active platform.
Carrier + module support check — verified against the Camera Development Guide, Adaptation Guide §Camera, carrier schematic, Module TRM, and carrier pinmap.
Wiring — derived from the in-tree
```
tegra<soc>-camera-<sensor>*.dtsi
```
when one exists (the DTSI IS the wiring source of truth); captured per-sensor from the user when the sensor is custom.
Kernel-DT overlay — cpp-expand the in-tree DTSI, extract its
```
fragment@N
```
body, append into the composite custom overlay
```
.dts
```
for the active target (per
```
../../references/bsp-customization-kernel-dtb.md
```
), verify the composite with
```
fdtoverlay
```
.
```
/jetson-build-source
```
compiles the composite and owns the carrier conf's
```
OVERLAY_DTB_FILE+=
```
registration.

Agentic, not table-driven — sensor list is built at runtime by globbing in-tree per-sensor dtbos. No

_THOR_CAMERAS

dict, no

questions.json

, no Python renderer in the question path.

No ODMDATA edit — cameras don't consume UPHY lanes (CSI is a separate PHY pool). The skill emits only a kernel-DT overlay; the ODMDATA line in the carrier conf is untouched by this skill.

The output is one commit:

Camera
```
fragment@N
```
block (plus
```
jetson-header-name
```
on the composite root if not already present) appended to the composite custom overlay
```
.dts
```
per
```
../../references/bsp-customization-kernel-dtb.md
```
→ committed to the
```
bsp_sources/
```
hardware repo.
```
/jetson-build-source
```
compiles the composite to
```
.dtbo
```
and owns its Makefile + flash-conf registration.

Tegra264（Thor）和Tegra234（Orin）提供一个由NVCSI和一组固定CSI端口前置的

tegra-capture-vi

控制器。摄像头启用流程如下：

传感器选择 — 从NVIDIA针对当前平台提供的内核源码树内置
```
.dtsi
```
参考文件集中挑选。
载板+模块支持检查 — 对照《摄像头开发指南》、《适配指南·摄像头章节》、载板原理图、模块技术参考手册（TRM）和载板引脚映射表进行验证。
布线 — 若存在内核源码树内置的
```
tegra<soc>-camera-<sensor>*.dtsi
```
文件，则从中提取布线信息（DTSI是布线的权威来源）；若为自定义传感器，则从用户处收集每个传感器的布线信息。
Kernel-DT覆盖层 — 对内核源码树内置的DTSI进行cpp展开，提取其
```
fragment@N
```
主体，追加到针对当前目标的复合自定义覆盖层
```
.dts
```
中（遵循
```
../../references/bsp-customization-kernel-dtb.md
```
），并使用
```
fdtoverlay
```
验证复合文件。
```
/jetson-build-source
```
负责编译复合文件，并管理载板配置中的
```
OVERLAY_DTB_FILE+=
```
注册。

基于Agent机制，而非表格驱动 — 传感器列表在运行时通过匹配内核源码树内置的各传感器dtbo文件生成。无需

_THOR_CAMERAS

字典、

questions.json

或问题路径中的Python渲染器。

不修改ODMDATA — 摄像头不占用UPHY通道（CSI属于独立的PHY池）。本Skill仅生成Kernel-DT覆盖层；载板配置中的ODMDATA行不会被本Skill修改。

输出为一个提交记录：

摄像头
```
fragment@N
```
块（若复合根节点尚未包含
```
jetson-header-name
```
则一并添加）被追加到复合自定义覆盖层
```
.dts
```
中（遵循
```
../../references/bsp-customization-kernel-dtb.md
```
）→ 提交到
```
bsp_sources/
```
硬件仓库。
```
/jetson-build-source
```
将复合文件编译为
```
.dtbo
```
，并负责其Makefile和烧录配置的注册。

When to invoke

调用时机

The user says "enable camera", "configure CSI", "wire a Hawk / Owl / IMX sensor", "MIPI camera", "GMSL camera", or asks to bring up
```
tegra-capture-vi
```
/ NVCSI on a custom carrier.
Flash boots but
```
v4l2-ctl --list-devices
```
shows no
```
tegra-capture-vi
```
channels, OR sensor enumeration on a fresh daughter-card needs to be confirmed.
A sensor was previously enabled and the user wants to add another (multi-sensor bring-up).

Prerequisites:

Active profile with
```
reference_devkit:
```
+
```
custom_carrier:
```
blocks.

<source.root_path>/Linux_for_Tegra/.git

exists (

/jetson-init-source

```
/jetson-derive-carrier
```
has run — the carrier flash-conf fork is in the overlay tracker.

<source.root_path>/bsp_sources/hardware/nvidia/<chip-dir>/nv-public/overlay/

exists and contains the in-tree per-sensor

.dtsi

files (sourced by

/jetson-init-source

's Branch A archive extract).

```
<source.root_path>/bsp_sources/kernel/kernel-noble/include/dt-bindings/
```
contains the macro headers cpp needs (
```
source_sync.sh
```
may need to run if Branch B was used — see Step 5a.i below).
Source-of-truth docs registered or supplied at prompt: Camera Development Guide (in
```
bsp_developer_guide
```
mirror or separate path), Adaptation Guide §Camera, carrier schematic, SoC TRM, Module Design Guide.
```
dtc
```
,
```
cpp
```
,
```
fdtoverlay
```
on PATH.

用户提及“启用摄像头”、“配置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
```
已运行 — 载板烧录配置分支已加入覆盖层追踪器。

<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
```
— 见下文步骤5a.i）。
已注册或在提示时提供权威文档：《摄像头开发指南》（位于
```
bsp_developer_guide
```
镜像或独立路径）、《适配指南·摄像头章节》、载板原理图、SoC技术参考手册（TRM）、模块设计指南。
```
dtc
```
、
```
cpp
```
、
```
fdtoverlay
```
已添加到系统PATH中。

Procedure

流程

Detailed step-by-step procedure (Steps 1–7, with all tables, code blocks, and gates) lives in

references/procedure.md

. Summary:

Step 1 — Resolve active target + open source-of-truth docs.
Step 2 — Enumerate supported sensors by globbing in-tree per-platform camera dtbos; classify as DPHY-direct / GMSL / custom. Never invent sensors.
Step 3 / 3a — Cross-check carrier + module support against DTSI, Camera Development Guide, Adaptation Guide §Camera, SoC TRM, Module Design Guide, schematic, and carrier pinmap. Render the wiring table FIRST, then issue the confirm-or-customize gate.
Step 4 (custom path only) — Batched per-sensor wiring questions auto-filled from the carrier pinmap.
Step 5 — Append exactly ONE
```
/* custom-bsp: camera:<sensor> */
```
fragment to the composite custom overlay
```
.dts
```
(see
```
../../references/bsp-customization-kernel-dtb.md
```
). Clone path cpp-expands the in-tree DTSI; custom path splices Step-4 answers + mode tables in-place. Idempotently set
```
jetson-header-name
```
on the composite root. Verify with
```
dtc
```
+
```
fdtoverlay
```
(pre-compile single-fragment gate; post-compile deep-tree uniqueness gate). Commit via the workflow's commit-message preview gate.
Step 6 — Verify ancillary CAM pin SFIOs (
```
cam_i2c_*
```
,
```
extperiph<m>_clk
```
, reset/PWDN/PWR_EN GPIOs) via
```
pin_verifier.py
```
; route mismatches to
```
/jetson-customize-pinmux
```
.
Step 7 — Atomic-write run-state JSON sidecar at
```
<workspace>/target-platform/<profile-stem>.jetson-customize-camera.json
```
and emit the headline, then drive the downstream next-step chain via sequential
```
AskUserQuestion
```
prompts per
```
references/procedure.md
```
Step 7. The chain is a documented workflow gate, not a clarifying question — auto-mode does NOT exempt it. Never substitute a printed "Next step: …" line for the prompts.

详细的分步流程（步骤1–7，包含所有表格、代码块和校验点）见

references/procedure.md

。摘要：

步骤1 — 确定当前目标平台并打开权威文档。
步骤2 — 通过匹配当前平台的内核源码树内置摄像头dtbo文件枚举支持的传感器；分类为DPHY直连/GMSL/自定义类型。禁止自行虚构传感器。
步骤3/3a — 对照DTSI、《摄像头开发指南》、《适配指南·摄像头章节》、SoC技术参考手册、模块设计指南、原理图和载板引脚映射表，交叉检查载板+模块的兼容性。先生成布线表，再进入确认或自定义校验点。
步骤4（仅自定义路径） — 基于载板引脚映射表自动填充批量传感器布线问题。
步骤5 — 向复合自定义覆盖层
```
.dts
```
中追加恰好一个
```
/* custom-bsp: camera:<sensor> */
```
片段（见
```
../../references/bsp-customization-kernel-dtb.md
```
）。克隆路径会对内核源码树内置的DTSI进行cpp展开；自定义路径会将步骤4的答案和模式表直接插入。幂等性地为复合根节点设置
```
jetson-header-name
```
。使用
```
dtc
```
+
```
fdtoverlay
```
进行验证（预编译单片段校验点；编译后深层树唯一性校验点）。通过工作流的提交信息预览校验点完成提交。
步骤6 — 通过
```
pin_verifier.py
```
验证辅助CAM引脚SFIO（
```
cam_i2c_*
```
、
```
extperiph<m>_clk
```
、复位/PWDN/PWR_EN GPIO）；若存在不匹配则调用
```
/jetson-customize-pinmux
```
处理。
步骤7 — 在
```
<workspace>/target-platform/<profile-stem>.jetson-customize-camera.json
```
处原子写入运行状态JSON辅助文件并输出标题，然后根据
```
references/procedure.md
```
步骤7的要求，通过连续的
```
AskUserQuestion
```
提示驱动下游后续步骤链。该步骤链是文档化的工作流校验点，而非澄清问题 — 自动模式也不能跳过此步骤。禁止用打印的“下一步：…”语句替代提示。

Gotchas

常见陷阱

Dual-fragment trap. Contribute exactly ONE camera-tagged
```
fragment@N
```
to the composite. A second one carrying status overrides triggers dtc deep-merge → duplicate sibling subtrees (e.g. two
```
tca9546@70
```
) → runtime first-match drops the dtsi- supplied deep tree → camera silently doesn't enumerate. Gate on this skill's marker only (Step 5c).
Composite root
compatible
is owned globally, not by this skill. Don't widen from any in-tree per-sensor dtbo's
```
compatible
```
(devkit-SKU-gated). Fix the composite root if needed.
jetson-header-name
from any in-tree per-sensor dtbo. Fixed, carrier-agnostic; read once, paste onto the metadata root.
DO NOT also append the in-tree per-sensor dtbo to
OVERLAY_DTB_FILE
. Registering both your rendered overlay AND the in-tree
```
tegra<soc>-p3971-camera-<sensor>-overlay.dtbo
```
produces a phantom subdev bind that bricks camera enumeration.
Stub overlay is a known footgun. Committing
```
tegra-capture-vi { status="okay"; num-channels=<N>; }
```
with no ports / sensor / nvcsi body bricks the camera (
```
all channel init failed
```
). Splice the FULL sensor body via cpp + dtc.
Sensor mode tables must be spliced, never hand-authored.
```
mode<N>
```
,
```
sensor_modes
```
,
```
pixel_phase
```
— copy verbatim from the closest in-tree DTSI.
camera_common_regulator_get (null) ERR: -EINVAL
= missing
```
avdd-reg
```
/
```
iovdd-reg
```
/
```
dvdd-reg
```
strings — splice the FULL sensor body; always-on rails fall back to dummy regulator.
External
&label
refs must exist in base DTB's
__symbols__
. Use
```
target-path = "/tegra-capture-vi"
```
when the label is absent;
```
fdtoverlay
```
exits non-zero with
```
FDT_ERR_NOTFOUND
```
otherwise.
cpp
failure on
dt-bindings/gpio/gpio.h: No such file
= L4T source tree isn't staged. Re-run
```
/jetson-init-source
```
(Branch B's
```
source_sync.sh
```
fetches the headers). Never fabricate the macro expansion.
No ODMDATA edit, no flash-conf edit. Camera doesn't consume UPHY lanes. The carrier conf's
```
ODMDATA="..."
```
is untouched.
```
OVERLAY_DTB_FILE+=
```
is owned by
```
/jetson-build-source
```
Step 5.0a — this skill never touches the carrier flash conf.
Don't touch the upstream BSP at
<bsp_image.root_path>
. All edits land in
```
<source.root_path>/Linux_for_Tegra/
```
(overlay tracker) and
```
<source.root_path>/bsp_sources/
```
(overlay
```
.dts
```
) under the pristine + customization commit pattern.

双片段陷阱 — 仅向复合文件中添加一个带摄像头标记的
```
fragment@N
```
。若添加第二个包含状态覆盖的片段，会触发dtc深层合并 → 重复的兄弟子树（例如两个
```
tca9546@70
```
）→ 运行时首次匹配会丢弃DTSI提供的深层树 → 摄像头无法枚举且无提示。仅通过本Skill的标记进行校验（步骤5c）。
复合根节点的
compatible
属性为全局所有，不由本Skill管理。请勿扩展内核源码树内置传感器dtbo中的
```
compatible
```
属性（受开发板SKU限制）。若需要则修复复合根节点。
jetson-header-name
来自内核源码树内置的传感器dtbo。该值固定且与载板无关；读取一次后粘贴到元数据根节点即可。
请勿同时将内核源码树内置的传感器dtbo追加到
OVERLAY_DTB_FILE
中。同时注册您生成的覆盖层和内核源码树内置的
```
tegra<soc>-p3971-camera-<sensor>-overlay.dtbo
```
会产生虚假子设备绑定，导致摄像头枚举失败。
** stub覆盖层是已知隐患**。提交仅包含
```
tegra-capture-vi { status="okay"; num-channels=<N>; }
```
的内容而无端口/传感器/nvcsi主体，会导致摄像头故障（提示
```
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
```
步骤5.0a管理 — 本Skill绝不修改载板烧录配置。
请勿修改
<bsp_image.root_path>
处的上游BSP。所有编辑均在
```
<source.root_path>/Linux_for_Tegra/
```
（覆盖层追踪器）和
```
<source.root_path>/bsp_sources/
```
（覆盖层
```
.dts
```
）中进行，遵循“原始+定制”的提交模式。

References

参考资料

```
references/procedure.md
```
— full step-by-step Steps 1–7 procedure (extracted from this SKILL.md).
```
references/csi-dt-bindings.md
```
— CSI / nvcsi / vi DT binding reference notes.
```
references/overlay-template.md
```
— guidance on the metadata-root + clone-body overlay shape.

references/camera-overlay-templates/

— starter

.dts.tmpl

templates:

dphy-direct.dts.tmpl

gmsl-serdes.dts.tmpl

```
../../scripts/pin_verifier.py
```
— shared HSIO pin verifier (Step 6).

../../references/platform_template.yaml

—

documents:

block consumed by Step 1.

../../context/bsp-customization-workflow.md

— overlay edit protocol.

```
../jetson-customize-pinmux/SKILL.md
```
— sibling skill auto-invoked by Step 6 to fix HSIO pin SFIO mismatches (CAM I²C, MCLK, reset GPIOs).
```
../jetson-derive-carrier/SKILL.md
```
— must run first; produces the carrier base overlay (the
```
*-dynamic.dtbo
```
) this skill's composite stacks after.
```
../jetson-init-source/SKILL.md
```
— produces the overlay tracker +
```
bsp_sources
```
repo (with the
```
hardware/nvidia/<chip-dir>/
```
per-sensor DTSI tree) this skill reads and commits into.

```
references/procedure.md
```
— 完整的分步流程（步骤1–7，提取自本SKILL.md）。
```
references/csi-dt-bindings.md
```
— CSI/nvcsi/vi设备树绑定参考说明。
```
references/overlay-template.md
```
— 元数据根节点+克隆主体覆盖层格式指南。

references/camera-overlay-templates/

— 初始

.dts.tmpl

模板：

dphy-direct.dts.tmpl

、

gmsl-serdes.dts.tmpl

。

```
../../scripts/pin_verifier.py
```
— 共享HSIO引脚验证工具（步骤6）。

../../references/platform_template.yaml

— 步骤1使用的

documents:

块。

../../context/bsp-customization-workflow.md

— 覆盖层编辑协议。

```
../jetson-customize-pinmux/SKILL.md
```
— 步骤6自动调用的兄弟Skill，用于修复HSIO引脚SFIO不匹配问题（CAM I²C、MCLK、复位GPIO）。
```
../jetson-derive-carrier/SKILL.md
```
— 必须先运行；生成载板基础覆盖层（
```
*-dynamic.dtbo
```
），本Skill的复合覆盖层会堆叠在其后。
```
../jetson-init-source/SKILL.md
```
— 生成覆盖层追踪器+
```
bsp_sources
```
仓库（包含
```
hardware/nvidia/<chip-dir>/
```
下的各传感器DTSI树），本Skill会读取并提交到该仓库。