blob: 1cceb6b0c171f89d34817282fbe625a3fea8f359 [file] [log] [blame]
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.