jetson-derive-carrier

jetson-derive-carrier

为自定义载板上的任意 customize-* 技能定制首次运行门禁。根据 target-platform-contract.md 解析当前目标。 如果没有 custom_carrier: 块，或者缺少 <source.root_path>/Linux_for_Tegra/.git，则拒绝（先运行 jetson-init-source）。模板文件创建／复制行会归入 单个 overlay-tracker 提交，并直接复制到重命名后的自定义载板目标路径——不会暂存以参考名称命名的原始文件（本地规则见 Fork plan，它优先于 工作流 中标准的原始文件与定制拆分）；conf 链发现遵循 按板级分派 conf。 不派生内核基础 DTB——载板差异作为 DT overlay，通过 OVERLAY_DTB_FILE 接入。

标识符（来自当前配置）：通过 目录中的 reference_devkit.module.id 获取 <chip>（未知时 → 警告，回退为 tegra234）；通过 reference_devkit.module 获取 <module-id>／<module-sku>；通过 reference_devkit.carrier 获取 <carrier-id>／<carrier-sku>；通过 custom_carrier 获取 <custom-id>／<custom-sku>／ <custom-flash-conf>。<real-conf> = readlink <bsp_image.root_path>/Linux_for_Tegra/<reference_devkit.flash_config> （NVIDIA 约定 <devkit>.conf → <carrier>-<module>-a<rev>.conf； 如果不是符号链接，则警告并将顶层文件视为真实文件，且跳过符号链接包装行）。

<custom-id> 是自定义载板的标识符，不一定是 NVIDIA 风格的 pNNNN ID。在短横线格式的文件名和 DT compatible 字符串中原样使用。若目标文件系列使用去掉 p 前缀的数字标记，则仅当 <custom-id> 符合 ^p[0-9]{4}$ 时，将 <custom-id-file-token> 派生为 NNNN；否则原样使用 <custom-id>。不要仅因自定义载板 ID 不以 p 开头而拒绝它。

Instructions

以下派生计划就是指令集：先进行一次发现，然后逐行派生按板级文件集；每次执行 git commit 前，都必须先通过提交消息预览门禁。

Fork 计划

此技能生成的每个 git commit——无论是在覆盖层跟踪仓库 （Linux_for_Tegra/）还是 hardware/ 源码仓库中——都必须经过 提交消息预览关卡。 向操作员展示已暂存文件列表和拟定的提交消息，并在每次 git commit 前要求其接受、编辑或取消；若选择 取消，则保留已暂存的索引，以便手动处理。

即使字节未发生变化，也要物化重命名后的 fork。 对每一行已接受的 fork 计划，都要创建并跟踪自定义载板目标路径； 若 fork 只是重命名／复制，或文件内容与参考文件完全相同，也不能跳过缺失的目标文件。这包括 BCT fork，例如 pinmux、 GPIO/GPIOINT、padvoltage/PMC、misc 和 MB2 misc。仅当 Acceptance 列允许跳过、源文件明确标记为警告后跳过，或预期目标路径 已经被跟踪时，才可跳过；最后一种情况下，将其报告为已派生，不要创建空提交。

模板文件的创建／复制行合并为一个覆盖层跟踪仓库提交，且绝不暂存参考名称的原始文件。 在覆盖层跟踪仓库中物化新文件（派生自模板）的所有行——board flash-conf、flash-conf 符号链接、MB1 BCT（pinmux、 GPIO/GPIOINT、padvoltage/PMC、misc）、MB2 BCT（misc）、BPMP DTB（选择启用时）、nvpmodel、nvfancontrol——都必须直接从 <bsp_image.root_path>/Linux_for_Tegra/<rel>/<reference-name> 复制到 <source.root_path>/Linux_for_Tegra/<rel>/<custom-name>，并在暂存前完成所有内容编辑。覆盖层跟踪仓库绝不暂存或提交参考名称 （以 <carrier-id>-<carrier-sku> 为键）的文件名，只跟踪重命名为自定义载板名称的文件。这覆盖了 覆盖层跟踪仓库中的提交批处理规定的标准“原始文件 + 自定义”拆分方式。所有此类行都纳入一个覆盖层跟踪仓库提交，其中添加：(i) 已应用内容的自定义载板名称文件及其目标路径，(ii) flash-conf 符号链接，以及 (iii) 重命名后的 flash-conf 中针对 PINMUX_CONFIG / GPIO_CONFIG / GPIOINT_CONFIG / PMC_CONFIG / MISC_CONFIG / MB2_BCT 的定向内容改写（若启用了 BPMP DTB，还包括 BPFDTB_FILE）。编辑现有上游文件而非创建模板的行——nvpower.sh 补丁——以及覆盖层接线（将 OVERLAY_DTB_FILE+= 追加到刚创建的 flash-conf fork；根据 提交批处理，将其视为时间上独立的阶段）仍按各自行内容分别提交。DT overlay 骨架提交位于 bsp_sources/hardware/，而非覆盖层跟踪仓库，因此不受影响。合并后的提交只触发一次提交消息预览关卡；警告后跳过的行不计入其中；若该批次中的每一行都已被跟踪，则完全省略该提交。

发现（单次批处理）

只运行一次发现流程；不要与暂存操作交错进行。不要截断列表——被扫描目录中的每个候选文件名都必须完整显示，以供匹配器检查。此步骤禁止使用 head、tail、| head -N、| tail -N 及任何其他限制行数的筛选器；使用未经截断的 ls -1 / find，或对完整输出运行 grep。截断可能导致匹配文件位于截断点之后时，被错误地标记为警告后跳过。捕获：

• Flash-conf 变量：DTB_FILE / TBCDTB_FILE / BPFDTB_FILE / PINMUX_CONFIG / PMC_CONFIG / GPIO_CONFIG / GPIOINT_CONFIG。 DTB_FILE / TBCDTB_FILE 仅供参考，以便 overlay 接线逻辑 推导 overlay 文件名中的 <dtb-stem>——此技能不会重写它们。
• BCT .dts 位于 bootloader/generic/BCT/；.dtsi 兄弟文件位于 上一级 bootloader/ 目录中——不在同一目录。
• nvpmodel：nvpmodel_<module-id>_<module-sku>*.conf。nvfancontrol： nvfancontrol_<module-id>_<module-sku>_<carrier-id>_<carrier-sku>.conf。
• nvpower.sh 中 (a)–(d) 的锚点：<carrier-id> cvb 分支、 <module-id>-<module-sku> SKU elif、tegra<chip> nvpmodel 级联、tegra<chip> nvfancontrol 级联。 | 文件 / 类别 | 发现方式 | 纳入规则 | 分叉规则 | |---|---|---|---| | 板级 flash 配置 | <real-conf> | 始终 | 文件名中将 <carrier-id>-<carrier-sku> 替换为 <custom-id>-<custom-sku>。内容替换是定向的，而非全面替换：仅重写其文件由此技能分叉的变量的 RHS——PINMUX_CONFIG、PMC_CONFIG、GPIO_CONFIG / GPIOINT_CONFIG、MISC_CONFIG、MB2_BCT。其他以载板为键的变量（DTB_FILE、TBCDTB_FILE、SCR_CONFIG、PMIC_CONFIG、DEVICEPROD_CONFIG、PROD_CONFIG、MINRATCHET_CONFIG、UPHY_CONFIG、动态的 OVERLAY_DTB_FILE+=）必须保留参考值——这里不会分叉它们对应的文件，全面执行 sed 会使这些变量指向不存在的文件。具体而言，DTB_FILE / TBCDTB_FILE：基础 DTB 不会分叉；叠加层行会改为追加新的 OVERLAY_DTB_FILE+= 行。BPFDTB_FILE：选择加入的额外提交。绝不修改 <chip>、<module-id>、xxxx。 | | Flash 配置符号链接 | 无条件 | 始终（若 <real-conf> 不是符号链接则跳过） | 新建符号链接 <custom-flash-conf> → 分叉后的 flash 配置 | | MB1 BCT pinmux | 遵循 ¶ 中的 PINMUX_CONFIG + #include | 始终 | 重命名规则 † | | MB1 BCT GPIO | 遵循 ¶ 中的 GPIO_CONFIG/GPIOINT_CONFIG + #include | 始终 | 重命名规则 † | | MB1 BCT padvoltage | 遵循 ¶ 中的 PMC_CONFIG + #include | 始终 | 重命名规则 † | | MB1 BCT misc | 遵循 ¶ 中的 MISC_CONFIG + #include | 始终 | 重命名规则 † | | MB2 BCT misc | 遵循 ¶ 中的 MB2_BCT + #include | 始终 | 重命名规则 † | | 内核 DTB + 源码 DTS | （仅供参考——见标题） | 绝不分叉 | 基础 DTB 保留为参考版本。叠加层跟踪器中不保留原始二进制副本；bsp_sources/hardware/ 中不分叉源代码 DTS。载板差异完全放在 DT 叠加层中（见下一行）。 | | DT 叠加层骨架（新增） | 无条件 | 始终 | 创建 <source.root_path>/hardware/nvidia/<chip>/nv-public/overlay/<chip>-<custom-id>-<custom-sku>+<module-id>-<module-sku>.dts（骨架 ‡）；在 hardware/ 中提交，并推送到 origin | | 每目录 Makefile 注册 | <source.root_path>/bsp_sources/hardware/nvidia/<chip>/nv-public/overlay/Makefile | 始终 | 在最后一个字面名称为 dtbo-y += 的条目后追加 dtbo-y += <chip>-<custom-id>-<custom-sku>+<module-id>-<module-sku>.dtbo（位于 $(addprefix $(makefile-path)/,$(dtbo-y)) 前缀块之前——插在 dtbo-y += $(old-dtbo) 后面会悄无声息地漏掉 .dtbo）。位置敏感的同类写法和代码片段见 composite slot 的 Makefile 补丁：../jetson-build-source/references/composite-registration.md#makefile-patch-idempotent-position-sensitive。在 hardware/ 中提交。若缺少此行，nvidia-dtbs 将不会生成下一行的 OVERLAY_DTB_FILE+= 所引用的 .dtbo，导致 flash.sh 在刷写中途因找不到文件而中止。 | | 叠加层接线 | 无条件 | 始终 | 在分叉后的 flash 配置中追加 OVERLAY_DTB_FILE+=",<chip>-<custom-id>-<custom-sku>+<module-id>-<module-sku>.dtbo"（额外提交） | | nvpmodel 配置 | rootfs/etc/nvpmodel/nvpmodel_<module-id-num>_<module-sku>.conf | 始终 | 文件名：追加 _<custom-id-file-token>_<custom-sku> | | nvfancontrol 配置 | rootfs/etc/nvpower/nvfancontrol/nvfancontrol_<module-id-num>_<module-sku>_<carrier-id-num>_<carrier-sku>.conf | 始终 | 文件名：替换载板部分（若源文件仅以模块为键，则追加 _<custom-id-file-token>_<custom-sku>） | | nvpower.sh 补丁 | rootfs/etc/systemd/nvpower.sh | 始终 | 原始文件 + 单个定制提交，共 4 处插入：(a) 在参考项之前加入 cvb 级联分支 elif [[ "${machine}" =~ "<custom-id>" ]]; then cvb="<custom-id-file-token>"；(b) 在模块 SKU 分支内设置 machine="<module-id>-<module-sku>-<custom-id>-<custom-sku>"；(c) 为复合 machine 键添加 nvpmodel 级联分支 → conf_file= 指向分叉后的 nvpmodel 配置；(d) 添加以 cvb 为键的 nvfancontrol 级联分支 → conf_file= 指向分叉后的 nvfancontrol 配置 | | BPMP DTB | 预编译文件位于 bootloader/generic/<BPFDTB_FILE>（备用命名：无 p 前缀、SKU 为 xxxx） | 选择加入 y/N，默认 N——模块级别，通常与参考版本共用 | 分叉二进制文件：原始文件 + 文件名中将 -<carrier-id-num>- 替换为 -<custom-id-file-token>-（内容不变）。在 flash 配置分叉上额外提交一次，将 BPFDTB_FILE 重写为重命名后的二进制文件。 | ¶ #include 跟踪。 扫描每个已捕获的 .dts，查找文件中任意位置的 #include "..." 指令（NVIDIA BSP 会将它们放在 BCT 节点主体内）；按载板键控的包含文件也加入分叉列表。 仅深入一层。

† 重命名规则。 按载板键控的源文件（例如 …-p3834-xxxx-p4071-0000.dts）→ 将文件名中的 <carrier-id>-<carrier-sku> 替换为 <custom-id>-<custom-sku>；在同一个自定义提交中，将 flash-conf 变量（例如 PINMUX_CONFIG）改为重命名后的文件名。模块部分逐字保留自原始文件——如果原始文件包含 p3834-xxxx，分叉文件就保留 p3834-xxxx；如果原始文件包含 p3834-0008，分叉文件就保留 p3834-0008。切勿自行固定模块 SKU。原始文件在载板 SKU 位置使用其他 xxxx 通配符时，也遵循相同规则（例如 p4071-xxxx → p1234-xxxx）。按模块键控的源文件（例如 …-p3767-dp-a03.dtsi）→ 追加 _<custom-id-file-token>_<custom-sku>（下划线格式）或 -<custom-id>-<custom-sku>（连字符格式），并且在 flash-conf 分叉中额外提交一次，将变量（例如 PINMUX_CONFIG）改为带后缀的名称。默认情况下不替换内容；如果内容中包含字面量载板 ID-SKU 自引用，则提示用户。

‡ Overlay 框架。 DT 插件 overlay（/plugin/;），包含一个 fragment@0，其 target-path = "/"；在 __overlay__ 中设置 model = "<custom_carrier.name> carrier board" 和 compatible = "nvidia,<custom-id>-<custom-sku>+<module-id>-<module-sku>", "nvidia,<chip>"。nvpower.sh 会根据 compatible 缩小机器范围。

编辑验证

每次执行 sed / 补丁后都要重新 grep。sed 在未匹配时会静默地不执行任何操作； 退出代码为 0 并不能证明任何事情。多行替换：使用 Python str.replace(old, new)，不要使用多行 sed（容易因空白差异而出错， 且未匹配时会静默地不执行任何操作）。验证未通过时拒绝提交。

摘要。 按仓库列出分叉（数量 + 提交 SHA）、BPMP-DTB 决策、警告并跳过的行（此 BSP 缺少必需源文件——不要因此让运行失败）以及写入的 overlay 路径。

示例

操作人员可能会使用的触发语句：

derive custom carrier
bootstrap custom carrier
fork carrier board from reference devkit

技能预期在活动配置文件中找到的最简 custom_carrier: 块：

custom_carrier:
  id: p1234            # any token; need not be NVIDIA pNNNN style
  sku: 0000
  flash_config: p1234.conf
  name: Acme Custom Carrier

用途

为新的载板定制每板文件集，使下游 customize-* 技能、nvpower.sh 和启动链都指向自定义载板，而非参考开发套件。基础 DTB 保持不变；载板差异放在 DT overlay 中，这样针对新的参考 BSP 重新派生时，只需重新运行此技能。

前提条件

• 根据 target-platform-contract.md 解析活动配置文件，其中包含 custom_carrier: 块（id、sku、flash-conf、友好名称）。
• 已初始化 source.root_path/Linux_for_Tegra/.git — 首先运行 /jetson-init-source；如果缺少 overlay 跟踪文件，此技能会拒绝运行。
• 已由 /jetson-init-image 填充 bsp_image.root_path，以便解析参考 flash-conf 符号链接。
• 已填充 reference_devkit:（模块 + 载板），以便重命名规则有可供替换的载板 ID/SKU 标记。

限制

• 不会分叉内核基础 DTB 及其源 DTS — 载板差异必须通过由 OVERLAY_DTB_FILE 接入的 DT overlay 分层处理。
• BPMP DTB 分叉为可选项（默认关闭）。大多数载板替换都会共用 参考 BPMP DTB；只有当板卡电源／时钟拓扑不同时才选择分叉。
• Flash-conf 内容替换是针对性的，并非全面替换。本技能不会分叉其文件的变量 （DTB_FILE、TBCDTB_FILE、SCR_CONFIG、PMIC_CONFIG、DEVICEPROD_CONFIG、PROD_CONFIG、 MINRATCHET_CONFIG、UPHY_CONFIG、动态 OVERLAY_DTB_FILE+=） 保持参考值不变 — 重写这些变量会使其指向不存在的文件。
• 自定义载板 ID 不必遵循 NVIDIA pNNNN 格式；只有当 ID 匹配 ^p[0-9]{4}$ 时，才会去掉前缀 p 并提取数字标记。
• 不会自定义模块级文件。对于 pinmux、时钟、风扇曲线、 nvpmodel、PCIe、UPHY、USB、MGBE 或摄像头差异，请使用相应的 jetson-customize-* 技能。

故障排除

• 因“no custom_carrier: block”而拒绝执行 — 请先在 当前配置文件中声明该块，然后重新运行；技能不会自行推断。
• 因“Linux_for_Tegra/ 中缺少 .git”而拒绝执行 — overlay 跟踪器尚未初始化。请先运行 /jetson-init-source。
• “<real-conf> 不是符号链接” — NVIDIA 的惯例是让 <devkit>.conf 符号链接指向 <carrier>-<module>-a<rev>.conf；如果顶层文件是真实配置文件，技能会发出警告、将其视为真实文件，并跳过符号链接包装器这一行。这不是错误。
• sed 报告成功，但编辑未生效 — 未匹配时 sed 会静默地不执行任何操作。每次补丁后，技能都会重新运行 grep；验证未通过时会拒绝提交。对于多行替换，请改用 Python str.replace。
• “chip: unknown”／回退到 tegra234 — 模块 ID 不在目录中；请更新目录，而不是在配置文件中覆盖。
• 提交消息预览提示阻止运行 — 这是提交批处理所要求的关卡； 请接受、编辑或取消。取消后，索引会保留在暂存状态，以便手动处理。
• 此 BSP 缺少必需的源文件 — 摘要中会将该行记录为警告并跳过；运行的其余部分仍会完成。