​使用自定义 Ubuntu 根文件系统重建 PWM 风扇控制，涵盖从 PL 到内核模块、设备树和用户空间工具

当为Kria KV260定制Ubuntu系统时，AMD官方Ubuntu镜像中包含的某些功能默认情况下并不具备。基于PWM的风扇控制就是其中之一，重建该功能清晰地展示了如何添加平台特定的功能。本项目记录了识别缺失组件、分析相关硬件和软件路径，并以结构化方式重新构建完整的PWM风扇控制链的过程。

引言

Kria SOM 及其他自适应 SoC 平台提供了预构建的操作系统，以简化初始开发。这些镜像可立即开始应用开发，无需重复搭建完整 Linux 环境所需的系统级准备工作。为此，已提供专为 Kria SOM 优化的 Ubuntu 镜像。

然而，在某些情况下，需要定制操作系统。这可能是出于安全考虑、特定应用程序的限制，或仅仅是为了了解系统是如何构建的。本文档的重点在于分析此类系统的结构，并以可控且透明的方式对其进行重建。

尽管可以使用 PetaLinux 或 Yocto 构建完整的 Linux 系统，且这些工具非常适合嵌入式应用，但在需要普通用户空间交互或 Ubuntu 特定工具时，其使用可能不够便捷。因此，本文重点介绍一个基于 Ubuntu 的定制系统，该系统可在 Kria KV260 SOM 上运行，同时保留 Ubuntu 环境的优势。

一种常用的方法依赖于三个组成部分：

•适用于 AArch64 的干净 Ubuntu 根文件系统

•由 PetaLinux 生成的内核

•以及Kria硬件平台。

这些元素结合在一起后，形成一个功能性的基础系统。随后需要进行额外的配置，以暴露特定于Kria的接口。内核、设备树和用户空间必须进行调整，以便相关驱动程序能够被加载，并使操作系统可以访问可编程逻辑。

以下文本以结构化且可重复的方式描述了该过程。

1：PL设计

在Zynq UltraScale+ MPSoC设备中，脉宽调制(PWM)波形由集成的三重定时器计数器(TTC)外设生成。每个TTC实例包含三个独立的16位定时器/计数器单元，即定时器/计数器1、定时器/计数器2和定时器/计数器3——每个单元均可作为通用定时器或波形发生器运行(更多详细信息请参见官方文档)。当配置为波形模式时，TTC单元会以可编程的周期和占空比切换其输出，从而可用作风扇转速调节等应用中的PWM信号源。TTC单元由处理系统提供时钟，并可通过EMIO(扩展多路复用I/O)将输出暴露给可编程逻辑，使生成的PWM信号可在PL中进行路由、缓冲或与额外逻辑组合使用。

对Kria KV260平台参考设计的分析显示，该基于TTC的PWM功能用于控制平台的冷却风扇。在原理图中，处理系统被配置为使TTC0将其波形输出暴露给PL。由于三个定时器/计数器单元均被导出，因此对应的PL信号是一个3位总线，尽管仅使用了定时器/计数器3来控制风扇。因此，所需的PWM信号通过切取TTC0波形输出的最高有效位，并将其经PL结构路由至专用的GPIO风格输出端口，从而驱动载板上的FAN_EN引脚获得。

该GPIO输出的物理引脚分配在XDC约束文件中定义。这种配置遵循AMD官方Kria参考平台的结构，其中TTC输出被用作风扇控制的主要PWM源，并通过标准Linux PWM子系统提供给操作系统使用。

XDC文件中描述风扇输出配置的片段：

2：PWM风扇支持的内核配置

本项目所使用的操作系统内核是基于 PetaLinux Tools 2024.2 构建的。之所以选择此版本，是因为已有完整的、功能健全的开发环境可供使用。尽管 PetaLinux 的工作流程正逐步被 AMD 推出的基于 Yocto 的新方法所取代，但对于需要与 Vivado 生成的硬件平台进行确定性集成的项目而言，PetaLinux 仍然完全适用。因此，本节所述的内核配置针对的是指定版本的 PetaLinux 项目，并基于前一节中讨论的设计所导出的 XSA 文件。

本文仅讨论与PWM风扇控制、硬件监控和TTC驱动器直接相关的内核选项。其他与无关功能相关的内核自定义设置不在本文讨论范围内。

内核配置范围

内核通过标准的PetaLinux机制进行配置：

由于目标根文件系统是 Ubuntu，所需的驱动程序以可加载模块的形式启用，而不是直接编译进内核镜像中。这种方法在用户空间方面提供了灵活性，并与 Ubuntu 管理 PWM、HWMON 和 IIO 等内核子系统的方式保持一致。有关将这些模块集成到 Ubuntu 根文件系统中的详细信息，将在本文中进一步讨论。

此处提供的配置并非唯一有效的设置。许多必需选项是通过反复测试、与AMD参考Ubuntu镜像的对比，以及直接与Linux的PWM和HWMON子系统交互得出的。因此，该配置旨在作为实用参考，而非对所有可能内核配置的详尽或强制性定义。

必需的内核选项

要在 Kria KV260 平台上启用基于 PWM 的风扇控制，需要配置多个内核子系统协同工作：

•PWM驱动器

•AMS/XADC 传感器驱动器

•硬件监控接口

•TTC驱动程序

每个组件都提供了动态风扇调节所需功能的特定部分。以下子节概述了支持这些元素所需的内核选项。每组分别处理风扇控制路径中的不同方面，它们共同构成了在 Ubuntu 根文件系统下正确运行所必需的最小配置。

此外，值得注意的是，该项目支持FPGA Manager，可让fpgautil等工具在运行时加载PL位流;这一选项将在后续配置用户空间时变得相关。

PWM风扇驱动器

要在 Linux 系统下将风扇作为可控制的 PWM 设备暴露出来，必须启用以下驱动程序：

CONFIG_PWM_FAN

该模块提供了标准的 Linux PWM 风扇驱动程序，可与 HWMON 子系统集成，并允许用户空间工具(如 fancontrol)根据温度读数来调节风扇转速。

AMS 和 XADC 驱动程序

Kria KV260平台采用AMS(模拟混合信号)模块来暴露片上温度和电压传感器。AMS子系统集成了多种监控功能，包括访问XADC(Xilinx模拟-数字转换器)，该转换器提供温度和供电电压的实际数字化测量值。这两个组件对于基于温度的风扇控制都是必需的，因为PWM调节逻辑依赖于通过工业I/O(IIO)框架传输的传感器数据。

以下选项为必填项：

CONFIG_XILINX_AMS

CONFIG_XILINX_XADC

这些模块提供了对AMS子系统及底层XADC转换器的访问，确保温度和电压读数能够通过IIO接口提供给内核。

硬件监控(HWMON)集成

尽管AMS和XADC驱动程序通过IIO接口提供传感器数据，但大多数用于管理热行为的Linux用户空间工具(如传感器、pwmconfig和fancontrol)都是基于HWMON接口运行的。因此，需要在两个子系统之间建立一个桥梁。

以下内核选项提供了此项集成：

CONFIG_IIO_HWMON

CONFIG_SENSORS_IIO_HWMON

这些模块将选定的IIO传感器通道转换为标准HWMON输入，使风扇控制逻辑在计算PWM占空比时能够使用AMS温度读数。该桥接器对于基于芯片内热数据实现动态风扇调节至关重要。

TTC驱动器(PWM信号源)

用于风扇控制的PWM信号由处理系统中的TTC0定时器/计数器3生成。要在Linux下将该定时器作为可用的PWM源，必须在内核配置中启用Cadence TTC驱动程序。在PetaLinux内核菜单中，该驱动默认不可见;只有在通用设置部分启用额外选项后，才能选择该驱动。

以下内核选项是必需的：

CONFIG_COMPILE_TEST

启用此选项将暴露通常在构建特定架构时隐藏的额外驱动程序。一旦启用，即可选择TTC驱动程序：

CONFIG_CADENCE_TTC_TIMER

此选项可启用TTC驱动程序本身，使内核能够将TTC0定时器/计数器3配置为pwm-fan驱动所使用的PWM信号源。

CONFIG_WERROR(将被禁用)

当 CONFIG_COMPILE_TEST 启用时，内核会将某些警告(例如未使用的变量)视为破坏编译的错误。禁用 CONFIG_WERROR 可防止这些警告阻止编译，而当 CONFIG_COMPILE_TEST 启用时，这是必要的。

内核配置摘要

上述内核配置为基于PWM的风扇控制准备了所有必需的子系统，并确保在运行时可用必要的驱动程序。这些设置完成了内核层面的先决条件;然而，风扇控制路径还依赖于正确的设备树定义，以将驱动程序绑定到底层硬件上。在完成内核选项设置后，下一步是相应地调整设备树，然后即可编译内核，以便与Ubuntu根文件系统集成。

3：设备树调整

内核准备就绪后，接下来要关注的是设备树——它将硬件定义与相应的驱动程序关联起来，并完成风扇控制的路径。

高层概述(整体概览)

设备树是硬件设计、内核配置与Linux用户空间之间的桥梁。它描述了处理系统和可编程逻辑中的硬件模块如何向操作系统暴露，并确定每个组件关联的驱动程序。在基于PWM的风扇控制中，设备树确保AMS传感器、XADC转换器和TTC定时器正确绑定到内核中启用的驱动程序。

PetaLinux 通过将 XSA 文件中硬件设计的定义与自身的平台模板相结合，生成一个基础设备树。该基础定义已包含 AMS 子系统、XADC 块以及 TTC0 定时器的相关节点。对于本项目而言，工作流程如下：先构建一次项目以获取初始的 system.dtb，检查相关节点，然后在 system-user.dtsi 中应用所需的覆盖层。这种方法提供了一种清晰且可重复的方式，用于扩展基础设备树，而无需直接修改自动生成的文件。完成这些调整后，即可重新构建内核和设备树，使最终的 system.dtb 包含更新后的绑定信息。

获取基础设备树(system.dtb)

在应用任何设备树调整之前，建议先生成初始的 system.dtb 文件，以便检查 PetaLinux 生成的定义。可以通过构建 PetaLinux 项目来完成此操作：

在此构建过程中，PetaLinux 通过将 XSA 文件中硬件设计提取的定义与平台模板和板级支持文件相结合，来组装设备树。生成的合并后的设备树作为构建输出的一部分被写入，并可在以下位置获取：

此基础设备树反映了从Vivado导出的处理系统配置、可编程逻辑地址映射以及外设定义。它已包含与风扇控制相关的节点，例如AMS子系统、XADC转换器和TTC0定时器，因为这些节点源自硬件设计。检查生成的system.dtb可以清晰地了解这些组件的表示方式，并为在system-user.dtsi中进行用户自定义调整提供基础。

检查基础设备树

一旦生成了初始的 system.dtb 文件，就可以对其进行检查，以了解 PetaLinux 如何表示与风扇控制相关的硬件模块。通常使用设备树编译器(DTC)将二进制的设备树块(Device Tree Blob)转换为可读的源代码形式。

检查生成的 system.dts 文件，可以了解源自硬件设计的各个节点。在本项目中，以下几个定义尤其值得关注：

•AMS子系统(包括XADC)——由地址0xFFA50000处的单个AMS节点表示，该节点封装了AMS基础设施和XADC转换器。该节点还可通过其兼容字符串(“xlnx, zynqmp-ams”)进行标识。XADC功能并未作为独立节点提供，而是通过ams-ps和ams-pl子节点访问，这些子节点分别代表AMS/XADC模块的PS侧和PL侧接口。图中展示了已识别的AMS设备树节点及其对应的设备树符号，该符号可用于后续设备树自定义中的phandle引用。

•TTC0定时器——由一个或多个对应TTC通道的节点表示，包括用于作为PWM信号源的通道。正确的节点可通过其基地址(0xFF110000)识别，如图中所示。对于进一步的调整，可参考在自动生成的设备树中定义的符号别名来引用该节点。

在基础设备树中识别这些节点，将建立用户提供的覆盖层中所使用的引用。现阶段的目标不是修改自动生成的定义，而是仅仅确认其存在、记录它们的标签或句柄，并了解PetaLinux如何为其命名和组织结构。这些信息为下一步在system-user.dtsi中进行的调整奠定了基础。

系统-用户.dtsi 的调整

system-user.dtsi 文件的目的是引入一组设备树修改，以启用未被自动生成定义覆盖的功能，或调整特定节点或驱动的配置。该文件位于

当PetaLinux项目配置时会自动创建。

对于基于PWM的风扇控制，调整内容涉及上一步中识别出的AMS/XADC和TTC0节点，并通过操作系统pwm-fan驱动程序所期望的绑定，扩展了基础设备树。

请注意，本节中的设备树配置基于对Kria SOM官方Ubuntu镜像中提取的设备树进行逆向工程。相关节点与自动生成的设备树进行了对比，随后分析了特定节点和句柄。由此得出的调整结果即为本次工作成果。

以下更新已应用于系统-用户.dtsi：

•通过hwmon接口暴露AMS/XADC通道——引入了一个名为ams的新节点，用于通过标准Linux hwmon子系统暴露AMS/XADC测量数据。该节点被声明为iio-hwmon消费者，并通过io-channels属性引用现有的AMS/XADC提供程序(xilinx_ams)。列表中包含多个AMS通道(0–29)，使操作系统能够通过hwmon接口访问温度和电压读数，而无需修改自动生成的AMS节点。

•定义PWM控制的风扇设备——添加一个PWM风扇节点，用于描述风扇设备并将其绑定到TTC0 PWM信号源。该节点指定PWM通道(ttc0，通道2)、PWM周期以及所需的反向极性。极性调整可确保风扇正常工作，因为在分析的Kria Ubuntu镜像中，默认极性导致即使在最小占空比下风扇仍以全速运行(注意：假设参考的Kria Ubuntu镜像所使用的PL设计与逆向工程的版本不同)。

•启用 TTC0 作为 PWM 提供者——通过将状态属性设置为“okay”并定义 #pwm-cells = <3>，自动生成的 TTC0 节点被启用并声明为 PWM 提供者。这使得 TTC0 的通道可被 pwm-fan 驱动程序用作 PWM 输出。

设备树的调整可能包含额外的系统级配置更改，例如禁用PSGTR模块，并在主机模式下启用USB0和DWC3控制器。这些更改与风扇控制无直接关联，但已包含在完整的设备树中。

重建并验证最终设备树

在应用 system-user.dtsi 中的调整后，可重新构建项目，使更新后的设备树被整合到最终的 system.dtb 中。重建过程遵循本文档中之前描述的相同步骤，并基于自动生成的定义和用户提供的覆盖层，重新生成合并后的设备树。

虽然并非强制要求，但重新提取最终的 system.dtb 并检查其源码，有助于确认已按预期进行修改。这能清晰地显示叠加层是如何集成的，并帮助验证内核将加载正确的绑定。

验证步骤重点关注已添加或修改的节点：

•AMS/XADC hwmon 节点——ams 节点应出现在根目录下，且其兼容性设置为 "iio-hwmon"，并根据分配的 phandle(如图所示的 0x1C)列出所有引用 xilinx_ams 的 io-channel。这确认了 AMS/XADC 通道已通过 hwmon 接口暴露。

•pwm-fan 节点——pwm-fan 节点应包含预期的 pwms 属性，该属性需引用 &ttc0 频道 2，并包括已配置的周期和反相极性。这可验证风扇设备是否正确绑定到 TTC0 PWM 源(即如图所示的 phandle 0x1D)。

•TTC0 PWM 提供器——TTC0 节点应显示状态 = "okay" 且 #pwm-cells = <3>，表示 TTC0 通道已作为 PWM 输出暴露。

•额外的平台调整——任何与PWM无关的系统级更改(例如，禁用PSGTR、启用USB0、DWC3处于主机模式)也会出现在合并后的设备树中。

执行此验证可确保叠加层按预期工作，并且最终的设备树准确反映PWM风扇控制所需的配置。

4：为Ubuntu根文件系统准备内核模块

在使用 PetaLinux 构建的内核与 Ubuntu 根文件系统时，需将 PetaLinux 生成的内核模块复制到 Ubuntu 的根文件系统中，以便内核能够加载与硬件配置相对应的驱动程序。此步骤与所选的启动方式无关，仅需在系统启动前访问 Ubuntu 的根文件系统即可。

复制内核模块

PetaLinux 将内核模块放入归档中：

该存档包含完整内容：

与PetaLinux编译的内核对应的目录。要使Ubuntu根文件系统能够使用这些模块，需将整个目录复制到Ubuntu根文件系统的对应位置：

这确保了Ubuntu系统能够访问PetaLinux构建的内核所需的所有驱动程序，包括用于PWM、IIO及其他子系统的驱动。

启动系统并重新生成模块元数据

复制模块后，Kria 系统即可启动。此时模块已存在于文件系统中，但其依赖元数据尚未重新生成。应使用以下命令重建依赖文件：

此操作会更新 modules.dep、modules.alias 及相关的元数据，以便内核能够正确解析模块依赖关系。

重启与验证

重启Kria板可确保所有模块在更新后的依赖结构下正确加载。重启后，可通过以下命令列出已安装的模块来确认其存在：

可选：验证内核配置

可以使用以下命令查看构建运行内核时所使用的内核配置：

这有助于确认哪些驱动是内建的，哪些是模块化的，以及内核配置是否与从PetaLinux复制的模块匹配。

5：用户空间集成与风扇控制设置

在内核和设备树准备就绪后，下一步是验证在运行的Kria系统上，暴露的接口是否能在用户空间可见，并配置风扇控制服务。此阶段确认PWM接口、硬件监控(hwmon)子系统以及AMS/XADC测量功能已正确注册于内核中，并且所需的用户空间工具能够与这些接口进行交互。

安装所需的用户空间工具

要与内核提供的PWM和硬件监控接口进行交互，必须在Ubuntu根文件系统上安装若干用户空间工具。这些工具可提供温度读数、hwmon数据以及风扇控制功能的访问：

•lm-sensors — 提供通过 hwmon 子系统获取的传感器数据，包括 AMS/XADC 温度读数。

•fancontrol — 使用 PWM 和 hwmon 接口实现基于温度的风扇控制。

这些工具是验证暴露接口和配置风扇控制服务的基础。在讨论PL比特流加载时，后续将介绍fpgautil等其他实用工具。

验证 hwmon 设备

启动系统后，硬件监控接口将显示在以下位置：

hwmon设备的编号无法保证，且可能因操作系统配置不同而有所差异。对于风扇控制设置，目标是识别出与此用例相关的两个接口：

•PWM风扇驱动器(pwmfan)

•AMS/XADC 传感器接口(ams)

每个hwmon设备都会暴露一个名称文件，用于显示其身份：

一个典型的系统可能会显示：

实际编号可能有所不同;重要的是名称，而非索引。

创建 /etc/fancontrol 配置文件时需要这些名称。

检查与交互PWM子系统

TTC0外设提供的PWM接口可通过内核的调试文件系统进行查看：

输出显示：

•TTC0 PWM器件的存在

•已配置的时期

•当前占空比

•该通道是否已启用

建议在启用自动风扇控制前进行手动操作：

这证实了：

•PWM输出处于激活状态

•风扇对占空比调整有反应

•极性和周期设置的行为符合预期

重要提示：PWM 的行为取决于 PL 设计。如果位流尚未加载，PWM 输出可能无法到达风扇引脚。因此建议在进行功能测试前先加载位流。

配置风扇控制

在识别了PWM和hwmon接口后，即可配置风扇控制服务。该配置存储在：

如果文件不存在，可以手动创建。由于hwmon编号不固定，配置必须引用之前发现的实际hwmon目录。

模板(占位符必须替换)：

此配置定义了：

•温度输入(AMS/XADC)

•PWM输出(pwmfan)

•风扇启动的温度阈值

•最小/最大冷却的PWM值

•可选平滑处理，避免风扇转速快速波动

配置文件设置完成后，启用并启动服务：

运行服务确认PWM接口功能正常，AMS/XADC温度输入可读，且配置已成功解析。

使用 fpgautil 配置可编程逻辑(PL)

此时，内核和设备树已准备就绪，用户空间接口也已可见。然而，可编程逻辑(PL)可能尚未配置完成。如果PL比特流未被加载，则通过PL传输的PWM信号将无法到达风扇引脚。

如果内核中启用了FPGA管理器支持，则必须使用fpgautil工具手动配置PL。

安装 fpgautil

上传PL位流

移除现有的PL配置：

加载位流：

位流文件通常位于：

或者，根据项目工作流程，也可以直接从Vivado工具链导出。

验证PL配置

验证PL是否正确配置的一个实用方法是手动操作PWM输出(如果已启用，需禁用fancontrol服务)：

如果风扇对这些变化作出响应，则PL已正确配置，PWM信号也已正确传输。如果风扇保持恒定转速或无反应，则可能是PL位流未加载，或使用了错误的位流。

这完成了PL配置步骤，并确保PWM路径在启用自动风扇控制前已正常工作。

6：在启动时自动配置PL位流

自动PL配置可确保系统启动后，比特流中定义的PWM路由立即可用。如果没有这一步骤，风扇可能仍保持固定转速，或无法响应基于温度的控制，即使内核接口和风扇控制服务看起来正常运行。

此处采用的方法依赖于FPGA Manager和fpgautil，它们为启动时加载比特流提供了一种简单可靠的方式。该方法与最小化的Ubuntu根文件系统无缝集成，并与本文档中描述的工作流程高度契合。

将位流放置在持久性系统位置

为确保比特流在重启后仍可访问，将其放置于一个持久性、系统级别的目录中。管理员安装的固件资源的一个合适且被社区接受的位置是：

比特流(通常为 system.bit)可以复制到此目录中：

这为 systemd 服务提供了一个稳定且可预测的引用位置。

为PL配置创建systemd服务

专用的 systemd 单元可确保在启动时自动配置 PL。可以创建以下服务文件：

包含以下内容：

服务设计说明：

•After=multi-user.target 确保该服务在启动序列中以安全点运行，而不会产生顺序循环。

•由于 systemd 不继承交互式 shell 的 $PATH，因此需要完整路径 /usr/sbin/fpgautil。

•RemainAfterExit=yes 表示服务完成后的状态为活动状态，这对于状态检查非常有用。

启用服务：

启用服务后，PL将在每次启动时自动配置。

验证自动PL配置

在此阶段，PWM接口和风扇控制服务均已配置完成。因此，验证的重点在于观察风扇的预期行为：

•风扇不应再以固定速度运行

•风扇应能响应温度变化

•风扇控制所报告的占空比值应对应风扇转速的可听或可测量的变化。

如果风扇运行正常，则在启动时PL已正确配置。

(可选)负载下的观测系统行为

在配置好PL、暴露PWM接口并启用风扇控制服务后，最后一步是观察系统在实际运行条件下的表现。这包括监控：

•来自AMS/XADC接口的温度读数

•风扇控制服务所应用的PWM占空比值

•粉丝的回应，既可听见，又可衡量

本节演示了如何生成持续的负载，并实时观察热功耗和PWM行为。

生成CPU负载

为了以可控且可重复的方式提高系统温度，可以使用合成负载来保持所有CPU核心处于工作状态。为此，一个便捷的工具是stress-ng，它提供了多种CPU密集型方法，适用于性能基准测试和热测试。

然后可以开始执行完整的核心工作负载：

这模拟了一个繁重的计算任务，而无需任何特定的应用程序代码。

监测温度和PWM值

在另一个终端中，可以使用 watch 命令观察系统的温度和 PWM 行为。请将前面识别出的实际 hwmon 目录替换为：

这提供了系统热状态和风扇控制服务响应的实时、每秒一次的视图。当工作负载运行时：

•温度应逐渐升高

•风扇控制服务应根据配置的阈值调整PWM占空比

•风扇在占空比增加时，应能听觉上或可测量地改变转速。

解读结果

Kria平台的冷却解决方案效果显著。在典型的环境条件下，即使持续进行CPU密集型工作负载，芯片温度的上升也可能较为缓慢，且通常仍低于触发更高风扇转速所需的阈值。为了测试目的，可能需要施加长时间的合成负载或暂时降低气流，以观察完整的PWM响应曲线。这种行为表明：

•热传导路径高效

•风扇控制阈值已得到遵守

•PWM 和 hwmon 接口运行正常

系统在实际工作负载下能保持稳定的温度。

一旦温度超过设定的阈值，PWM占空比应相应上升，以确认整个控制链按预期运行。

结论

本指南旨在提供一种清晰且实用的方法，用于在系统各个层面自定义Kria平台。其目的并非聚焦于任何单一组件，而是展示硬件设计、内核配置、设备树、根文件系统和用户空间如何协同构成一个完整且功能健全的整体。

本文编译自hackster.io