Zephyr Devicetree详解 Devicetree绑定property语法

properties 链接到标题

Devicetree绑定中properties:关键字描述与绑定匹配的节点的所有属性，属性关键字下会有多个属性条目，每个属性条目下有多个关键字来描述限定属性，下面是一个属性绑定的示例，表示该一个节点下有current-speed和maximum-speed两个属性

properties:
    # 描述一个 'current-speed = <115200>;' 的属性。类型为int型
    # 设置 'required: true'。表示对示例节点是必需的。
    current-speed:
        type: int
        required: true
        description: Initial baud rate for bar-device


    # 描述一个 'maximum-speed = "full-speed";' 属性，类型为string
    # 对示例节点是可选的。属性值只能在enum中选择
    # the enum specifies known values that the string property may take
    maximum-speed:
        type: string
        description: Configures USB controllers to work up to a specific speed.
        enum:
            - "low-speed"
            - "full-speed"
            - "high-speed"
            - "super-speed"

可以看到在properties下面有两个属性条目，每个属性条目有自己的语法定义。

properties条目链接到标题

属性条目的语法如下：

<property name>:
required: <true | false>
type: <string | int | boolean | array | uint8-array | string-array |
        phandle | phandles | phandle-array | path | compound>
deprecated: <true | false>
default: <default>
description: <description of the property>
enum:
    - <item1>
    - <item2>
    ...
    - <itemN>
const: <string | int | array | uint8-array | string-array>
specifier-space: <space-name>

required 链接到标题

required 描述属性的必须性

当required: true时，写Devicetree时必须包含该属性
当requeied: false时，写Devicetree时该属性是可选的，如果绑定内不写required: false表示属性是可选的

type 链接到标题

type 描述属性值的类型

Type 类型	Description 描述	Example in DTS DTS 中的示例
string	字符串	status = “disabled”;
int	32bit int型	current-speed = <115200>;
boolean	布尔型，在设备树中体现为有这个属性为true或没这个属性为false	hw-flow-control;
array	0个或多个32bit值	offsets = <0x100 0x200 0x300>;
uint8-array	0个或多个字节，以十六进制表示	local-mac-address = [de ad be ef 12 34];
string-array	0个或多个字符串	dma-names = “tx”, “rx”;
phandle	一个节点引用	interrupt-parent = <&gic>;
phandles	0个或多个节点引用	pinctrl-0 = <&usart2_tx_pd5 &usart2_rx_pd6>;
phandle-array	节点引用列表	dmas = <&dma0 2>, <&dma0 3>;
path	phandle 路径引用或路径字符串的节点路径	zephyr,bt-c2h-uart = &uart0; 或 foo = “/path/to/some/node”;
compound	更复杂类型（不会生成宏）	foo = <&label>, [01 02];

deprecated 链接到标题

带有 deprecated: true 的属性向用户和工具表明该属性将被逐步淘汰。如果设备树包含标记deprecated: true的属性，构建过程中工具将警告。

default 链接到标题

default：为属性提供一个default值，例如

properties:
foo:
    type: int
    default: 3

当Devicetree中节点不写foo时，则相当于用foo=<3>，需要注意的是default和requires:true不能同时出现。

description：链接到标题

description：用于说明该属性的作用

enum 链接到标题

enum: 是属性可能包含的值列表。如果 DTS 中的属性值不在绑定的 enum: 列表中，则会引发错误。例如下面的clock-source就只能有PCLK32M，PCLK32M_HFXO，ACLK三种取值

# zephyr/dts/bindings/i2s/nordic,nrf-i2s.yaml
properties:
  reg:
    required: true

  interrupts:
    required: true

  pinctrl-0:
    required: true

  clock-source:
    type: string
    default: "PCLK32M_HFXO"
    description: |
      Clock source to be used by the I2S peripheral for the master clock
    enum:
      - "PCLK32M"
      - "PCLK32M_HFXO"
      - "ACLK"

const 链接到标题

const: 指定属性必须采用的常量值。它主要用于约束特定硬件的公共属性值。例如

properties:
"#address-cells":
    required: true
    const: 1

"#size-cells":
    required: true
    const: 0

在DTS中就只能写：

node{
#address-cells"=<1>;
#size-cells"=<0>
}

specifier-space 链接到标题

specifier-space：如果当前属性是phandle-array类型，specifier-space为其关联specifier space,例如下面ambiq,pwrcf属性的specifier space就是pwrcfg

# zephyr/dts/bindings/power/ambiq-pwrcfg.yaml
description: Ambiq peripheral power configuration

properties:

ambiq,pwrcfg:
    type: phandle-array
    specifier-space: pwrcfg
    description: Power configuration

需要找到specifier cell，也就匹配*-cell, 这里*就是pwrcfg, 找到pwrcfg-cells所在的绑定

# zephyr/dts/bindings/power/ambiq,pwrctrl.yaml
description: Ambiq power control

compatible: "ambiq,pwrctrl"

include: base.yaml

properties:
reg:
    required: true

"#pwrcfg-cells":
    type: int
    required: true
    const: 2
    description: Number of items to expect in a power configuration

pwrcfg-cells:
- offset
- mask

也就是ambiq,pwrcfg属性需要引用compatible为ambiq,pwrctrl的节点。在dts中uart节点含有ambiq,pwrcfg属性

# zephyr/dts/arm/ambiq/ambiq_apollo4p_blue.dtsi
uart0: uart@4001c000 {
        compatible = "ambiq,uart", "arm,pl011";
        reg = <0x4001c000 0x1000>;
        interrupts = <15 0>;
        interrupt-names = "UART0";
        status = "disabled";
        clocks = <&uartclk>;
        ambiq,pwrcfg = <&pwrcfg 0x4 0x200>;
    };

其引用了节点pwrcfg，其compatible应该为ambiq,pwrctrl

pwrcfg: pwrcfg@40021000 {
        compatible = "ambiq,pwrctrl";
        reg = <0x40021000 0x400>;
        #pwrcfg-cells = <2>;
    };

对照到zephyr/dts/bindings/power/ambiq,pwrctrl.yaml的内容得到参数的含义

pwrcfg-cells:
- offset
- mask

可以知道ambiq,pwrcfg = <&pwrcfg 0x4 0x200>;表达了引用pwrcfg节点，offset为0x4,mask为0x400

参考链接到标题

https://docs.zephyrproject.org/3.7.0/build/dts/bindings-syntax.html#properties