【教程】Agilex 5 SOC FPGA的HPS端如何响应FPGA端中断（三）——设备树Overlay

设备树Overlay

介绍设备树Overlay之前，先了解设备树。

设备树

设备树（Device Tree）负责告诉Linux内核系统中存在哪些硬件设备、它们的地址、中断号以及驱动兼容性信息。

设备树是用于描述硬件的树形数据结构，其源文件为.dts（Device Tree Source）格式文本文件。文件以根节点（/）为顶层，向下延伸出 CPU、内存、总线、外设等各级子节点，节点对应各类硬件设备，每个节点通过属性记录硬件具体特征，包含寄存器地址、中断号、时钟频率等硬件相关信息。设备树源文件经过DTC（Device Tree Compiler）编译后，生成二进制的.dtb（Device Tree Blob）文件。系统启动时，Bootloader将.dtb加载到内存，内核在启动初期解析它，从而识别系统中的所有硬件。

如下是GHRD设备树部分节点内容（未列出GHRD的全部硬件节点）：

设备树参考源文件

设备树不需要从零开始构建，Linux源码中已经存在Altera的Agilex 5开发板设备树文件，比如Agilex SoC DK开发板的设备树socfpga_agilex5_socdk.dts。我们可以将此文件作为初始参考点来构建自己的设备树文件。友晶科技官方教程https://github.com/johnnyfan1979/public_doc/blob/main/documentation/DE25_Nano/DE25%20Nano%20Build%20Linux%20image%20from%20scratch.md里面的socfpga_agilex5_de25_nano.dts就是在socfpga_agilex5_socdk.dts的基础上进行修改得到的。

socfpga_agilex5_de25_nano.dts文件包含 socfpga_agilex5.dtsi 文件，它定义了 Agilex SoC 设备中HPS的最底层硬件信息，包含了 Linux 时钟框架所需的时钟结构，以及全部 HPS I/O 外设的绑定信息。该文件作为基础头文件，提供了 SoC 级别的通用硬件定义。

而socfpga_agilex5_de25_nano.dts`作为顶层板级设备树文件，负责描述该特定开发板的硬件实现细节。开发者除了在该文件中使能所需外设外，还需添加与板级相关的特定参数（如 PHY 地址、GPIO 映射等），必要时也可以覆盖或修改从.dtsi继承的绑定值，从而形成完整且精确的板级硬件描述，最终通过编译生成设备树二进制文件供内核使用。

设备树Overlay

设备树Overlay用于在主设备树的基础上添加或修改节点信息。它可以动态配置开发板特有的设备节点，使这些配置与 SoC 隔离，从而让配置与更新更加方便灵活。

当新增自定义外设且需要在设备树中添加节点时，可以选择直接新增到顶层设备树文件里面，也可以选择创建设备树叠加层（overlay）。

设备树Overlay源码格式如下：

设备树Overlay在主设备树的基础上修改节点信息：

设备树Overlay在主设备树的基础上添加节点信息：

主设备树源码以.dts为扩展名。设备树Overlay可以以.dts为扩展名，也可以以.dtso为扩展名，其实他们的文件格式是一样的，但是用不同的文件扩展名可以将设备树Overlay与主设备树区分开来。

跟设备树相关的文件有点多，下面用一个表格罗列出来，方便读者查阅：

|---------|----------------------------|----------------------------------------------------------------|
| 扩展名 | 专业术语 | 含义 |
| .dts | Device Tree Source | 主设备树源文件 |
| .dtsi | Device Tree Source Include | 设备树头文件/包含文件，供 .dts 包含（#include），通常用于存放 SoC（芯片）共通的内部硬件定义，以方便复用。 |
| .dtso | Device Tree Source Overlay | 设备树覆盖源文件，用于动态加载/卸载外设插件的源码 |
| .dtb | Device Tree Blob（或 Binary） | 设备树二进制文件，由 .dts 编译后生成的机器码，是 Bootloader 加载进内核的最终文件 |
| .dtbo | Device Tree Blob Overlay | 覆盖二进制文件，由 .dtso 编译生成，供内核动态加载 |

本教程将按键这个外设节点设计成设备树Overlay的形式进行加载，具体内容如下：

复制代码

// SPDX-License-Identifier: GPL-2.0/dts-v1/;/plugin/;
/ {    fragment@0 {        target-path = "/soc@0";        __overlay__ {            #address-cells = <1>;            #size-cells = <1>;
            button_gpio@20010060 {                compatible = "terasic,pio-button";                reg = <0x20010060 0x10>;                interrupts = <0 18 0>;                altr,ngpio = <2>;                #gpio-cells = <2>;                gpio-controller;                status = "okay";            };        };    };};

该节点描述的是 Altera FPGA 内2 通道 PIO GPIO 控制器，寄存器基地址为 0x20010060，占用 16 字节空间；中断号为 18，触发方式为保留；作为标准 GPIO 控制器提供 2 路按键输入，当前硬件状态为启用，专用于外部按键电路。

其中 interrupts = <0 18 0>; 描述中断号及触发方式，第 1 个值是中断类型，0 代表 SPI 共享外设中断；第 2 个值 18是中断编号，该 PIO 控制器绑定硬件中断 18；第 3 个值 2是中断触发方式，0 表示保留该中断线的默认触发类型（通常是硬件复位后的状态）；内核收到该中断后，进入 PIO 中断服务函数处理按键事件。

更多有关设备树内容的解释请参考<no title> --- The Linux Kernel documentation

或者是内核源码里面Documentation/devicetree/bindings/ 目录的文档。

设备树源码或者设备树Overlay源码通过设备树编译器dtc编译成可加载的二进制文件。使用如下命令编译设备树Overlay：

dtc -@ -I dts -O dtb -o socfpga_agilex5_de25_nano.dtbo socfpga_agilex5_de25_nano.dtso

本文参考：HOWTO Create a Devicetree for Agilex SoC | Documentation | RocketBoards.org

往期阅读：

【教程】Agilex 5 SOC FPGA的HPS端如何响应FPGA端中断（一）------GIC控制器介绍

【教程】Agilex 5 SOC FPGA的HPS端如何响应FPGA端中断（二）------修改Quartus工程（GHRD工程）