jetson-customize-fan

修改 nvfancontrol 风扇配置文件（BSP 侧）

用途

编辑每块板卡对应的 nvfancontrol 配置，使设备启动时采用所需的风扇曲线／控制模式／调速器／默认配置文件。仅限 BSP 侧操作——所有写入都落在覆盖层跟踪仓库中，上游的 bsp_image 副本为只读。

此技能用于在 BSP 侧编辑每块板卡对应的 nvfancontrol 配置文件：添加或移除配置文件、编辑温度 → 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 = close_loop（驱动风扇达到目标 RPM，需要转速计）或 open_loop（直接写入 PWM）。
• FAN_DEFAULT_GOVERNOR = cont（连续插值）及其他特定系列的值；添加调速器时，请从现有的板卡配置文件中逐字复制。
• THERMAL_GROUP 将热区映射到控制器的输入。系数为 20 个元素的 CSV——请从现有条目中逐字复制；这些值因芯片系列和热区而异。
• <FAN N> 表示每个风扇索引对应的一个块（通常为 <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

该文件位于 两个根目录下；此技能会遍历这两个目录：

作用	位置	技能会写入吗？
检测 + 原始源文件	<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 — 载板 ID 可用于区分的 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 配置文件 — jetson-derive-carrier 为同一模块 SKU 上的自定义载板生成的每个 nvfancontrol_*.conf。

“应用相同的修改” ≠ 整体复制文件。 将已更改的 FAN_PROFILE／控制行移植到每个同级文件中；保留其他所有行。同级配置文件通常包含特定于载板的差异（针对不同散热方案的 THERMAL_GROUP 系数、不同的转速计 RPM 上限），这些内容必须保留 — 整体覆盖会导致这些载板上的风扇调校不当。只有在编辑前两个配置文件逐字节完全相同时，才可以整体复制。

覆盖层编辑步骤（在任何操作之前应用）

请遵循工作流文档中的规范 技能外编辑步骤——先导入原始文件，再提交自定义更改；两者都必须通过预览门禁。每次运行应用一次，覆盖本次运行涉及的所有板级文件（活动配置文件以及传播集中的所有同级文件）。

本技能的具体替换内容：

• <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 的数据结束，以定义超温时的行为。

示例框架：

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
   

剩余配置文件无需重命名。

操作 3 — 编辑现有风扇配置文件

先应用覆盖层编辑方案。

1. 在每块板的文件中，修改目标 FAN_PROFILE <name> 的曲线行。保持 4 列 TEMP HYST PWM RPM 的格式。
2. 保持 TEMP 按升序排列；根据需要插入或删除行。
3. 调整 HYST 以优化防振荡效果：过低 → 风扇在曲线点附近频繁波动；过高 → 风扇响应滞后于实际情况。
4. 按照操作 1 的规则进行验证。

修改 KICKSTART_PWM、FAN_CONTROL 中的 RPM_TOLERANCE，或 FAN_GOVERNOR 中的 STEP_SIZE，虽然不在配置文件中，但会调整同一风扇；同样适用于每块板的文件。

操作 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 必须引用二进制文件支持的值；更改时请从现有的每块板文件中复制。

操作 5 — 列出已定义的风扇配置文件

此操作为只读操作；无需设置覆盖层跟踪器。针对要检查的副本运行命令（原始状态使用 <bsp_image.root_path>/...，编辑后的状态使用 <source.root_path>/...）：

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

第一个命令会输出文件中的所有配置文件名称；第二个命令会输出启动默认值（控制方式 / 配置文件 / 调速器）。

限制

• 仅限 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_DEFAULT_PROFILE 设为同一个 <FAN N> 中现有的 FAN_PROFILE <name>。
风扇在曲线点附近反复波动	HYST 过低	提高受影响行的 HYST（通常为 2–5 °C）。
风扇响应滞后	HYST 过高	降低受影响行的 HYST。
高温时风扇始终不提速	曲线缺少高于 GROUP_MAX_TEMP 的行，或末尾的 0 0 导致曲线在环境温度以上被截断	添加一个 PWM/RPM 均非零的高温元组；仅在高于 GROUP_MAX_TEMP 时固定过温行。
守护进程报错，提示列数错误	曲线行不是 4 列的 TEMP HYST PWM RPM 格式	恢复为 4 列格式；删除尾随空格和多余列。
闭环控制中始终无法达到 RPM 目标	目标值高于转速计报告的最大值，或 FAN_CONTROL 设为 open_loop	将 RPM 降至风扇机械最大值以内，或将 FAN_DEFAULT_CONTROL 切换为 close_loop。
/jetson-init-image 重新提取后更改消失	更改写入了 <bsp_image.root_path>，而不是 <source.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 重新提取时，更改会被静默丢弃。