| title: Short description of the node |
| |
| description: > |
| Longer free-form description of the node. |
| Can go over multiple lines. |
| |
| # Used to map nodes to bindings |
| compatible: "manufacturer,device" |
| |
| # The 'compatible' above would match this node: |
| # |
| # device { |
| # compatible = "manufacturer,device"; |
| # ... |
| # }; |
| # |
| # Assuming no binding has 'compatible: "manufacturer,device-v2"', it would also |
| # match this node: |
| # |
| # device { |
| # compatible = "manufacturer,device-v2", "manufacturer,device"; |
| # ... |
| # }; |
| # |
| # Strings in 'compatible' properties on nodes are tried from left to right, and |
| # the first binding found is used. |
| # |
| # If more than one binding for a compatible is found, an error is raised. |
| |
| # Many bindings have common fields. These are stored in files given in |
| # 'include', which are merged into the binding (with a recursive dictionary |
| # merge). |
| # |
| # If a key appears both in the binding and in a file it includes, then the |
| # value in the binding takes precedence. This can be used to change a |
| # 'required: false' from an inherited file to a 'required: true' (see the |
| # 'properties' description below). |
| # |
| # An error is raised if this binding has 'required: false' for some property |
| # for which the included file(s) have 'required: true'. Bindings can only |
| # "strengthen" requirements from files they include. This is meant to keep the |
| # organization clean. |
| # |
| # When including multiple files, any overlapping 'required' keys on properties |
| # in the included files are ORed together. This makes sure that a |
| # 'required: true' is always respected. |
| include: other.yaml # or [other1.yaml, other2.yaml] |
| |
| # If the node describes a bus, then the bus type should be given, like below. |
| # The name has "child" in it since it describes the bus children of the node |
| # appear on. |
| child-bus: <string describing bus type, e.g. "i2c"> |
| |
| # If the node appears on a bus, then the bus type should be given, like below. |
| # |
| # When looking for a binding for a node, the code checks if the binding for the |
| # parent node contains 'child-bus: <bus type>'. If it does, then only bindings |
| # with a matching 'parent-bus: <bus type>' are considered. This allows the same |
| # type of device to have different bindings depending on what bus it appears |
| # on. |
| parent-bus: <string describing bus type, e.g. "i2c"> |
| |
| # 'properties' describes properties on the node, e.g. |
| # |
| # reg = <1 2>; |
| # current-speed = <115200>; |
| # label = "foo"; |
| # |
| # This is used to check that required properties appear, and to |
| # control the format of output generated for them. Except for some |
| # special-cased properties like 'reg', only properties listed here will |
| # generate output. |
| # |
| # A typical property entry looks like this: |
| # |
| # <property name>: |
| # required: <true | false> |
| # type: <string | int | boolean | array | uint8-array | string-array | |
| # phandle | phandles | phandle-array | compound> |
| # description: <description of the property> |
| # enum: |
| # - <item1> |
| # - <item2> |
| # ... |
| # - <itemN> |
| # const: <string | int> |
| # default: <default> |
| # |
| # 'type: boolean' is for properties used as flags that don't take a value, e.g. |
| # 'hw-flow-control;'. The macro generated for the property gets set to 1 if the |
| # property exists on the node, and to 0 otherwise. When combined with |
| # 'required: true', this type just forces the flag to appear on the node, |
| # though the output will always be the same in that case (1). |
| # |
| # 'type: uint8-array' is for what the device tree specification calls |
| # 'bytestring'. Properties of type 'uint8-array' should be set like this: |
| # |
| # foo = [89 AB CD]; |
| # |
| # Each value is a byte in hex. |
| # |
| # 'type: phandle' is for properties that are assigned a single phandle, like |
| # this: |
| # |
| # foo = <&label>; |
| # |
| # 'type: phandles' is for properties that are assigned a list of (just) |
| # phandles, like this: |
| # |
| # foo = <&label1 &label2 ...>; |
| # |
| # 'type: phandle-array' is for properties that are assigned a list of phandles |
| # and (possibly) 32-bit numbers, like this: |
| # |
| # foo = <&label1 1 2 &label2 3 4 ...>; |
| # |
| # 'type: compound' is a catch-all for more complex types, e.g. |
| # |
| # foo = <&label1>, [01 02]; |
| # |
| # 'type: array' and the other array types also allow splitting the value into |
| # several <> blocks, e.g. like this: |
| # |
| # foo = <1 2>, <3 4>; // Okay for 'type: array' |
| # foo = <&label1 &label2>, <&label3 &label4>; // Okay for 'type: phandles' |
| # foo = <&label1 1 2>, <&label2 3 4>; // Okay for 'type: phandle-array' |
| # etc. |
| # |
| # The optional 'default:' setting gives a value that will be used if the |
| # property is missing from the device tree node. If 'default: <default>' is |
| # given for a property <prop> and <prop> is missing, then the output will be as |
| # if '<prop> = <default>' had appeared (except YAML data types are used for the |
| # default value). |
| # |
| # Note that it only makes sense to combine 'default:' with 'required: false'. |
| # Combining it with 'required: true' will raise an error. |
| # |
| # See below for examples of 'default:'. Putting 'default:' on any property type |
| # besides those used in the examples will raise an error. |
| properties: |
| # Describes a property like 'current-speed = <115200>;'. We pretend that |
| # it's obligatory for the example node and set 'required: true'. |
| current-speed: |
| type: int |
| required: true |
| description: Initial baud rate for bar-device |
| |
| # Describes an optional property like 'keys = "foo", "bar";' |
| keys: |
| type: string-array |
| required: false |
| description: Keys for bar-device |
| |
| # Describes an optional property like 'maximum-speed = "full-speed"; |
| # the enum specifies known values that the string property may take |
| maximum-speed: |
| type: string |
| required: false |
| description: Configures USB controllers to work up to a specific speed. |
| enum: |
| - "low-speed" |
| - "full-speed" |
| - "high-speed" |
| - "super-speed" |
| |
| # Describes a required property '#address-cells = <1>'; the const |
| # specifies that the value for the property is expected to be the value 1 |
| "#address-cells": |
| type: int |
| required: true |
| const: 1 |
| |
| int-with-default: |
| type: int |
| required: false |
| default: 123 |
| |
| array-with-default: |
| type: array |
| required: false |
| default: [1, 2, 3] # Same as 'array-with-default = <1 2 3>' |
| |
| string-with-default: |
| type: string |
| required: false |
| default: "foo" |
| |
| string-array-with-default: |
| type: string-array |
| required: false |
| default: ["foo", "bar"] # Same as 'string-array-with-default = "foo", "bar"' |
| |
| uint8-array-with-default: |
| type: uint8-array |
| required: false |
| default: [0x12, 0x34] # Same as 'uint8-array-with-default = [12 34]' |
| |
| # 'child-binding' can be used when a node has children that all share the same |
| # properties. Each child gets the contents of 'child-binding' as its binding |
| # (though an explicit 'compatible = ...' on the child node takes precedence, if |
| # a binding is found for it). |
| # |
| # The example below is for a binding for PWM LEDs, where the child nodes are |
| # required to have a 'pwms' property. It corresponds to this .dts structure |
| # (assuming the binding has 'compatible: "pwm-leds"'): |
| # |
| # pwmleds { |
| # compatible = "pwm-leds"; |
| # |
| # red_pwm_led { |
| # pwms = <&pwm3 4 15625000>; |
| # }; |
| # green_pwm_led { |
| # pwms = <&pwm3 0 15625000>; |
| # }; |
| # ... |
| # }; |
| child-binding: |
| title: PWM LED |
| description: LED that uses PWM |
| |
| properties: |
| pwms: |
| type: phandle-array |
| required: true |
| |
| # 'child-binding' also works recursively. For example, the binding below would |
| # provide a binding for the 'grandchild' node in this .dts (assuming |
| # 'compatible: "foo"'): |
| # |
| # parent { |
| # compatible = "foo"; |
| # child { |
| # grandchild { |
| # prop = <123>; |
| # }; |
| # }; |
| # } |
| # |
| # WARNING: Due to implementation issues with legacy code, only up to two levels |
| # of 'child-binding:' nesting (like below) is supported. This restriction will |
| # go away in Zephyr 2.2. |
| child-binding: |
| title: ... |
| description: ... |
| |
| ... |
| |
| child-binding: |
| title: ... |
| description: ... |
| |
| properties: |
| prop: |
| type: int |
| required: true |
| |
| # If the binding describes an interrupt controller, GPIO controller, pinmux |
| # device, or any other node referenced by other nodes, then #cells should be |
| # given. |
| # |
| # To understand the purpose of #cells, assume that some node has |
| # |
| # foo-gpios = <&gpio-ctrl 1 2>; |
| # |
| # , where &gpio-ctrl refers to a node whose binding is this file. |
| # |
| # The <1 2> part of the property value is called a *specifier* (this |
| # terminology is from the devicetree specification), and contains additional |
| # data associated with the GPIO. Here, the specifier has two cells, and the |
| # node pointed at by &gpio-ctrl is expected to have '#gpio-cells = <2>'. |
| # |
| # #cells gives a name to each cell in the specifier. These names are used |
| # when generating identifiers. |
| # |
| # In this example, assume that 1 refers to a pin and that 2 is a flag value. |
| # This gives a #cells assignment like below. |
| "#cells": |
| - pin # name of first cell |
| - flag # name of second cell |
| |
| # If the specifier is empty (e.g. '#clock-cells = <0>'), then #cells can either |
| # be omitted (recommended) or set to an empty array. Note that an empty array |
| # is specified as '"#cells": []' in YAML. |