02 设备树介绍

设备树是嵌入式Linux开发人员必备的技能，因为在现在的Linux版本中ARM相关的驱动几乎全部采用设备树的方式进行开发，当然包括本教程中使用到的RK3568Linux内核。可以这么说，设备树就是一张详细的开发板的硬件原理图在软件层的体现，不管是OpenHarmony还是Linux开发，这都是必需能看懂的板级描述文件，就好比做单片机的开发软件工程师必须要能看懂原理图！所以把设备树放在第一个学习章节，但是作为第一章可能有一定的难度，如果朋友们决定一下子不能理解，不妨先往后从GPIO开始学习，后续需要用到设备树时再返回来看~

不管什么外设驱动， GPIO 驱动基本都是必须的，而 pinctrl 和 gpio 子系统又是 GPIO 驱动必须使用的，所以就将 pintrcl 也放在这一章节进行讲解了，相信如果明白了设备树的原理，这两个部分就是手到擒来了。

1 设备树介绍

设备（Device Tree）的描述文件叫做DTS（Device Tree Source），DTS文件采用树形结构描述板级信息，以系统总线为中心，逐级进行发散，如下图所示：

设备树结构图

随着智能手机等嵌入式设备的发展，每年新出的 ARM架构芯片少说都在数十、甚至数百款， Linux 内核下板级信息文件将会成指数级增长！这些板级信息文件都是.c 或.h 文件，如果都被硬编码进 Linux 内核中，那Linux内核将充斥着很多无用的信息。

之后 ARM 社区就将这些描述板级硬件信息的内容都从 Linux 内中分离开来，用一个专属的文件格式来描述，这个专属的文件就叫做设备树，文件扩展名为.dts。 一个 SOC 可以作出很多不同的板子，这些不同的板子肯定是有共同的信息，将这些共同的信息提取出来作为一个通用的文件，其他的.dts 文件直接引用这个通用文件即可，这个通用文件就是.dtsi 文件，类似于 C 语言中的头文件。 一般来说，.dtsi 描述 SOC 级信息(也就是 SOC 有几个 CPU、主频是多少、各个外设控制器信息等)，.dts 描述板级信息(也就是板子上有哪些 IIC 设备、 SPI 设备等)。

提示

在本教程中，对应一些相对简单的外设，笔者将会带大家去查看设备树中的节点信息，并对DTS代码做一个简单的解析，从而了解到该外设的一些基本信息。帮助大家逐渐对设备树的语法以及结构做进一步了解

2 设备树语法

即使是Linux驱动开发人员，也不会拿到一个SOC以后从头到尾的写一个新的.dts文件出来，而是直接根据半导体厂家提供的.dts文件进行修改从而实现对自家板子的适配。

2.1 .dtsi头文件

一般.dtsi 文件用于描述 SOC 的内部外设信息，比如 CPU 架构、主频、外设寄存器地址范围，比如 UART、 IIC 等等。 通过"#include"进行引用，比如 rk3568.dtsi 就是描述 RK3568 芯片本身的外设信息， 截取内容如下：

注意

因为 OpenHarmony 为了保证源码的洁净，芯片厂家的修改统一通过patch打入
因此有两个方法获取完整的 rk3568.dtsi
方法一：编译一遍源码，在 out/kernel/src_tmp/linux-5.10/arch/arm64/boot/dts/rockchip 目录下即可获得。
方法二：通过指令将patch文件直接打入源码中，但这种代码会污染 OpenHarmony 的原始代码。

相关信息

rk3568.dtsi地址： out/kernel/src_tmp/linux-5.10/arch/arm64/boot/dts/rockchip

// SPDX-License-Identifier: (GPL-2.0+ OR MIT)
/*
 * Copyright (c) 2020 Rockchip Electronics Co., Ltd.
 */

#include <dt-bindings/clock/rk3568-cru.h>
#include <dt-bindings/interrupt-controller/arm-gic.h>
#include <dt-bindings/interrupt-controller/irq.h>
#include <dt-bindings/pinctrl/rockchip.h>
#include <dt-bindings/soc/rockchip,boot-mode.h>
#include <dt-bindings/phy/phy.h>
#include <dt-bindings/power/rk3568-power.h>
#include <dt-bindings/soc/rockchip-system-status.h>
#include <dt-bindings/suspend/rockchip-rk3568.h>
#include <dt-bindings/thermal/thermal.h>
#include "rk3568-dram-default-timing.dtsi"

/ {
	compatible = "rockchip,rk3568";

	interrupt-parent = <&gic>;
	#address-cells = <2>;
	#size-cells = <2>;

	aliases {
		csi2dphy0 = &csi2_dphy0;
		csi2dphy1 = &csi2_dphy1;
		csi2dphy2 = &csi2_dphy2;
		dsi0 = &dsi0;
		dsi1 = &dsi1;
		ethernet0 = &gmac0;
		ethernet1 = &gmac1;
		gpio0 = &gpio0;
		gpio1 = &gpio1;
		gpio2 = &gpio2;
		gpio3 = &gpio3;
		gpio4 = &gpio4;
		i2c0 = &i2c0;
		i2c1 = &i2c1;
		i2c2 = &i2c2;
		i2c3 = &i2c3;
		i2c4 = &i2c4;
		i2c5 = &i2c5;
		mmc0 = &sdhci;
		mmc1 = &sdmmc0;
		mmc2 = &sdmmc1;
		mmc3 = &sdmmc2;
		serial0 = &uart0;
		serial1 = &uart1;
		serial2 = &uart2;
		serial3 = &uart3;
		serial4 = &uart4;
		serial5 = &uart5;
		serial6 = &uart6;
		serial7 = &uart7;
		serial8 = &uart8;
		serial9 = &uart9;
		spi0 = &spi0;
		spi1 = &spi1;
		spi2 = &spi2;
		spi3 = &spi3;
	};

	cpus {
		#address-cells = <2>;
		#size-cells = <0>;

		cpu0: cpu@0 {
			device_type = "cpu";
			compatible = "arm,cortex-a55";
			reg = <0x0 0x0>;
			enable-method = "psci";
			clocks = <&scmi_clk 0>;
			operating-points-v2 = <&cpu0_opp_table>;
			cpu-idle-states = <&CPU_SLEEP>;
			#cooling-cells = <2>;
			dynamic-power-coefficient = <187>;
		};

		cpu1: cpu@100 {
			device_type = "cpu";
			compatible = "arm,cortex-a55";
			reg = <0x0 0x100>;
			enable-method = "psci";
			clocks = <&scmi_clk 0>;
			operating-points-v2 = <&cpu0_opp_table>;
			cpu-idle-states = <&CPU_SLEEP>;
		};

		cpu2: cpu@200 {
			device_type = "cpu";
			compatible = "arm,cortex-a55";
			reg = <0x0 0x200>;
			enable-method = "psci";
			clocks = <&scmi_clk 0>;
			operating-points-v2 = <&cpu0_opp_table>;
			cpu-idle-states = <&CPU_SLEEP>;
		};

		cpu3: cpu@300 {
			device_type = "cpu";
			compatible = "arm,cortex-a55";
			reg = <0x0 0x300>;
			enable-method = "psci";
			clocks = <&scmi_clk 0>;
			operating-points-v2 = <&cpu0_opp_table>;
			cpu-idle-states = <&CPU_SLEEP>;
		};

		idle-states {
			entry-method = "psci";
			CPU_SLEEP: cpu-sleep {
				compatible = "arm,idle-state";
				local-timer-stop;
				arm,psci-suspend-param = <0x0010000>;
				entry-latency-us = <100>;
				exit-latency-us = <120>;
				min-residency-us = <1000>;
			};
		};
	};
    ...
    ...
};

比如上述节选代码段主要描述了系统配置，外设接口别名映射，CPU配置，详细信息如下：

  • 系统配置

    • compatible: 标识这是RK3568芯片
    • interrupt-parent: 指定中断控制器为GIC
    • #address-cells 和 #size-cells: 定义64位地址空间

  • 外设接口别名定义 文件定义了丰富的外设别名映射，方便引用各种硬件接口包括：

    接口
    摄像头接口• 3个CSI2 DPHY接口
    显示接口• 2个DSI接口
    网络接口• 2个以太网接口（GMAC）
    GPIO• 5组GPIO（gpio0-gpio4）
    I2C总线• 6个I2C接口（i2c0-i2c5）
    存储接口• 4个MMC/SD卡接口
    串口通信• 10个UART串口（serial0-serial9）
    SPI总线• 4个SPI接口（spi0-spi3）

  • CPU配置

    • CPU架构 : ARM Cortex-A55四核处理器
    • CPU核心 : 4个CPU核心（cpu0-cpu3）
    • 地址映射 : 每个核心有独立的寄存器地址
    • 电源管理 : 支持PSCI（Power State Coordination Interface）
    • 时钟管理 : 使用SCMI时钟框架
    • 功耗管理 : 支持CPU睡眠状态，包括进入/退出延迟配置
    • 热管理 : CPU0支持动态功耗系数和冷却单元

rk3568.dtsi 完整代码对应的描述信息，需开发者自行学习，该教程只会教学部分代码的信息

2.2 设备节点

设备树是采用树形结构来描述板子上的设备信息的文件，每个设备都是一个节点，叫做设备节点，每个节点都通过一些属性信息来描述节点信息，属性就是键—值对。

还是以2.1的代码段进行解释，第5行的"/"是根节点，每个设备树只有一个根节点，aliases和cpus是根节点的子节点，cpu0、cpu1、cpu2、cpu3 是cpus的子节点。

节点的常见命名方式为：

label: node-name@unit-address
  • label 是节点标签，可以直接通过 &label 来访问这个节点
  • node-name 是节点名字，为ASCII编码，用于清晰的描述节点的功能
  • unit-address 是设备的地址或寄存器首地址

以节点 cpu2: cpu@200 为例，标签为cpu2表示第三个cpu，完整的设备名称是cpu@200，表示单元地址为@200的cpu。

2.3 标准属性

节点是一个个具体的设备，每个设备都有各自的属性，除了用户自定义的属性外，用的最多的是标准属性。下面将逐一进行介绍：

1. compatible 属性

是一个字符串列表，compatible 属性用于将设备和驱动绑定起来，选择设备所要使用的驱动程序。常见格式为：

compatible = "manufacturer,model";

属性值为厂商名加对应的驱动模块名。举个例子：

compatible = "sony,imx415";
// 日本sony 公司生产的imx415相机传感器模块

2. model 属性

是一个字符串，描述板子的名字或者设备模块信息，比如：

model = "Rockchip rk3568 EVB DDR4 V10 Board";
// 由瑞芯微推出的，基于 RK3568 芯片，搭载DDR4 内存，硬件版本为V1.0的板子

3. status 属性

是一个字符串，用于描述设备状态信息。常见的状态值包括：

状态值描述
"okay" 或 "ok"设备可操作
"disabled"设备当前不可操作，但在将来可能变为可操作
"fail"设备不可操作，设备中检测到了严重错误
"fail-sss"设备不可操作，设备中检测到了严重错误，sss部分是特定于设备的附加信息

4. #address-cells 和 #size-cells 属性

uint32类型，用于描述子节点的地址信息：

属性名描述
#address-cells定义了地址部分需要用几个32位整数（cell）来表示
#size-cells定义了大小部分需要用几个32位整数（cell）来表示

5. reg 属性

用于描述设备地址空间资源信息或者设备地址信息，reg 属性的值一般是(address, length)对，即（地址，大小）。

以rk3568.dtsi关于uart5的描述为例：

uart5: serial@fe690000 {
    xxxxxx
    reg = <0x0 0xfe690000 0x0 0x100>;
    xxxxxx
}
  • 第一个0x0：高32位地址（64位系统中为0）
  • 0xfe690000：低32位基地址
  • 第三个0x0：高32位大小（64位系统中为0）
  • 0x100：低32位大小（256字节）

6. name 属性

字符串用于记录节点名字，不常见。

2.4 修改节点内容

产品开发过程中可能面临着频繁的需求更改，一旦硬件修改了，我们就要同步的修改设备树文件，毕竟设备树是描述板子硬件信息的文件，但是就会引入一个问题，比如我在.dtsi文件的i2c5节点上增加了一个ICM45686的子节点，但是别的板子不需要这部分内容。所以这里再介绍一下在.dtsi文件中追加内容的方式。

以在i2c5节点上增加了一个ICM45686的子节点为例

&i2c5 {
    status = "okay";
    clock-frequency = <400000>;

    ICM45686@1e {
        compatible = "TDK,ICM45686";
        reg = <0x1e>;
    };
};

&i2c5 表示要访问 i2c5 这个 label 所对应的节点，比如 rk3568.dtsi 中的"i2c5: i2c@fe5e0000"。在i2c5下的子节点ICM45686里面描述ICM45686芯片的相关信息，就不会对这颗SOC的其他板子造成影响。

3 在内核中查看设备树

Linux下一切皆文件，使用HDC进入开发板的终端，进入路径 /proc/device-tree 可以看到根节点下的所有属性和子节点以文件的形式存在。

设备树根节点

各个节点表现为文件，文件内包含的内容为节点的属性，可以通过cat，vim等方式进行查看。

比如在根节点进入cpus子节点，可以看到cpus节点的属性和各个子节点：

cpus子节点

再进入cpu@100 节点，可以对其属性进行查看：

cpu@100节点

4 Pinctrl子系统

4.1 Pinctrl子系统介绍

现在的芯片随着外设资源的不断完善，不仅引脚数量非常的多，引脚可以复用的功能也非常的多，pinctrl子系统就是用来统一管理这些引脚复用和配置的工具。

4.2 Pinctrl在设备树中的体现

pinctrl在设备树中的描述通常分为2部分，一部分写一些复用选项，另一部分使用其中的一个复用选项。

在Pinctrl节点中定义"状态"：

在SoC的.dtsi文件中，会有一个pinctrl节点，其中定义了多种可用的引脚功能组合，称为"状态"。

// 在soc的.dtsi文件中
&pinctrl {
    // 定义一种状态：i2c1_default，表示I2C1的默认引脚配置
    i2c1_default: i2c1-default-state {
        // 配置这两组引脚的功能为I2C1，并设置上拉
        pins = "GPIO0_5", "GPIO0_6";
        function = "i2c1";
        bias-pull-up;
    };

    // 定义另一种状态：gpio5_state，将GPIO0_5配置为GPIO输入
    gpio5_state: gpio5-state {
        pins = "GPIO0_5";
        function = "gpio";
        input-enable;
    };
};

在设备节点中引用状态：

在你的板级.dts文件中，当为一个设备（如I2C控制器）节点时，需要通过 pinctrl-names 和 pinctrl-0 属性来指定使用哪种状态。

&i2c1 { // 引用i2c1节点
    status = "okay";
    pinctrl-names = "default";         // 状态名为"default"
    pinctrl-0 = <&i2c1_default>;       // 使用之前定义的i2c1_default状态
    clock-frequency = <100000>;
};

4.3 Pinctrl使用示例

下面在rk3568平台下以添加一个LED的pinctrl为例进行举例：

假设想要使用GPIO0_D5控制一个LED，先查阅手册，确认GPIO0_D5的复用选项，在预先定义好的复用功能中选择复用为GPIO（RK_FUNC_GPIO)，再设置其对应的电气属性如不进行上拉和下拉（&pcfg_pull_none)。

// 1. 定义LED的pinctrl配置集

&pinctrl {
    led_pin: led-pin {
        rockchip,pins = <0 RK_PD5 RK_FUNC_GPIO &pcfg_pull_none>;
    };
};

然后在板级文件 .dts中引用该复用的定义即可：

// 2. 在LED节点中引用（假设使用gpio-leds驱动）

/ {
    leds {
        compatible = "gpio-leds";
        pinctrl-names = "default";
        pinctrl-0 = <&led_pin>; // 引用上面定义的配置

        my_led: led@0 {
            label = "my_led";
            gpios = <&gpio0 RK_PD5 GPIO_ACTIVE_HIGH>; // 注意：这里也要和pinctrl定义的引脚一致
            default-state = "off";
        };
    };
};