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 会编译组合文件，并负责在载板配置文件中注册 OVERLAY_DTB_FILE+=。

由 Agent 执行，而非由表格驱动 — 运行时通过 glob 匹配树内各传感器的 dtbo 来构建传感器列表。没有 _THOR_CAMERAS 字典，没有 questions.json，提问流程中也没有 Python 渲染器。

不修改 ODMDATA — 摄像头不使用 UPHY 通道（CSI 使用单独的 PHY 池）。此工具仅生成内核 DT 覆盖层；载板配置文件中的 ODMDATA 行不受此工具影响。

输出为一个提交：

• 将摄像头 fragment@N 块（如果组合根节点中尚不存在 jetson-header-name，则一并添加）追加到组合式自定义覆盖层 .dts 中，参见 ../../references/bsp-customization-kernel-dtb.md → 提交到 bsp_sources/ 硬件仓库。 /jetson-build-source 会将组合文件编译为 .dtbo，并负责其 Makefile 和刷写配置注册。

何时调用

• 用户提出“启用摄像头”“配置 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 — 参见下文 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 — 通过对树内各平台的 camera dtbo 执行 glob，列出受支持的传感器；分类为 DPHY-direct / GMSL / custom。切勿虚构传感器。
3. 步骤 3 / 3a — 根据 DTSI、Camera Development Guide、Adaptation Guide §Camera、SoC TRM、Module Design Guide、原理图和载板引脚映射表，交叉核对载板与模组的支持情况。先呈现接线表，再发出确认或自定义门控。
4. 步骤 4（仅限自定义路径）— 按传感器分批提问接线问题，并根据载板引脚映射表自动填入答案。
5. 步骤 5 — 在组合后的自定义 overlay .dts 中追加且仅追加一个 /* custom-bsp: camera:<sensor> */ 片段（参见 ../../references/bsp-customization-kernel-dtb.md）。 克隆路径会对树内 DTSI 执行 cpp 展开；自定义路径会在原位插入步骤 4 的答案和模式表。以幂等方式在组合根节点上设置 jetson-header-name。使用 dtc + fdtoverlay 验证（编译前执行单片段门控；编译后执行深层树唯一性门控）。通过工作流的提交消息预览门控进行提交。
6. 步骤 6 — 使用 pin_verifier.py 验证辅助 CAM 引脚的 SFIO（cam_i2c_*、extperiph<m>_clk、reset/PWDN/PWR_EN GPIO）；将路由不匹配项转至 /jetson-customize-pinmux。
7. 步骤 7 — 将运行状态 JSON 旁文件原子写入 <workspace>/target-platform/<profile-stem>.jetson-customize-camera.json 并输出标题，然后按照 references/procedure.md 的步骤 7，通过依次发出的 AskUserQuestion 提示推进后续步骤链。**该链是文档规定的工作流门控，不是澄清问题——自动模式也不能跳过。**切勿用一行打印的“Next step: …”代替这些提示。

易踩的坑

• 双片段陷阱。 只向复合覆盖层贡献一个带摄像头标记的 fragment@N。如果第二个片段也带有状态覆盖，就会触发 dtc 深度合并 → 产生重复的同级子树 （例如两个 tca9546@70）→ 运行时首次匹配会丢弃 dtsi 提供的深层树 → 摄像头不会被枚举，且没有明显提示。仅以 此技能的标记作为门控条件（步骤 5c）。
• 复合覆盖层根节点的 compatible 由全局管理，而非此技能管理。 不要根据任何树内单传感器 dtbo 的 compatible（受 devkit SKU 限制）扩大兼容范围。必要时修复复合覆盖层根节点。
• 从任何树内单传感器 dtbo 获取 jetson-header-name。 该值固定且与载板无关；读取一次，然后粘贴到元数据根节点。
• 也不要将树内单传感器 dtbo 追加到 OVERLAY_DTB_FILE。 同时注册渲染后的覆盖层和树内的 tegra<soc>-p3971-camera-<sensor>-overlay.dtbo 会产生幽灵子设备绑定，导致摄像头无法枚举。
• 存根覆盖层是已知的陷阱。 提交没有端口、传感器或 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（分支 B 的 source_sync.sh 会获取这些头文件）。切勿伪造宏展开结果。
• 不修改 ODMDATA，不修改 flash-conf。 摄像头不使用 UPHY 通道。载板配置中的 ODMDATA="..." 保持不变。 OVERLAY_DTB_FILE+= 由 /jetson-build-source 的步骤 5.0a 管理——此技能绝不修改载板 flash 配置。
• 不要修改 <bsp_image.root_path> 中的上游 BSP。 所有修改都应遵循先提交原始内容、再提交定制内容的模式，落在 <source.root_path>/Linux_for_Tegra/（覆盖层跟踪器）和 <source.root_path>/bsp_sources/（覆盖层 .dts）中。

参考资料

• references/procedure.md — 步骤 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 引脚验证器（步骤 6）。
• ../../references/platform_template.yaml — 步骤 1 使用的 documents: 块。
• ../../context/bsp-customization-workflow.md — 覆盖层修改流程。
• ../jetson-customize-pinmux/SKILL.md — 步骤 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 树），此技能会读取并提交到该仓库中。