dts/bindings/binding-template.yaml

title: Short description of the node

description: >
    Longer free-form description of the node.
    Can go over multiple lines.

# Bindings are often based on other bindings, which are given in 'inherits'.
# The resulting binding is the union of the inherited bindings and this binding
# (internally, it's a recursive dictionary merge).
#
# If a field appears both in this binding and in a binding it inherits, then
# the value in this binding takes precedence. This can be used to change a
# 'category: optional' from an inherited binding to a 'category: required' (see
# the 'properties' description below).
inherits:
    !include other.yaml # or [other1.yaml, other2.yaml]

# If the node describes a bus, then the bus type should be given, like below
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">

# 'sub-node' is used to simplify cases where a node has children that can all
# use the same binding. The contents of 'sub-node' becomes the binding for each
# child node.
#
# The example below is for a binding for pwm-leds where the child nodes are
# required to have a 'pwms' property.
sub-node:
    properties:
        pwms:
          type: compound
          category: required

# '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>:
#     category: <required | optional>
#     type: <string | int | boolean | array | uint8-array | string-array | phandle | compound>
#     description: <description of the property>
#     enum:
#       - <item1>
#       - <item2>
#       ...
#       - <itemN>
#
# '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.
#
# 'phandle' is for properties that are assigned a single phandle, like this:
#
#   foo = <&label>;
#
# 'compound' is a catch-all for more complex types, e.g.
#
#   foo = <&label1 1 2 &label2 7>;
properties:
    # An entry for 'compatible' must appear, as it's used to map nodes to
    # bindings
    compatible:
        constraint: "foo-company,bar-device"

    # Describes a property like 'current-speed = <115200>;'. We pretend that
    # it's obligatory for the example node and set 'category: required'.
    current-speed:
        type: int
        category: required
        description: Initial baud rate for bar-device

    # Describes an optional property like 'keys = "foo", "bar";'
    keys:
        type: string-array
        category: optional
        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
      category: optional
      description: Configures USB controllers to work up to a specific speed.
      enum:
         - "low-speed"
         - "full-speed"
         - "high-speed"
         - "super-speed"

# If the binding describes an interrupt controller, GPIO controller, pinmux
# device, or any other device referenced via a phandle plus a specifier (some
# additional data besides the phandle), then the cells in the specifier must be
# listed in '#cells', like below.
#
# 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.
#
# For example, say that some node has 'foo-gpios = <&gpio1 1 2>'. The <1 2>
# part of the property value is the specifier, with two cells. The node pointed
# at by &gpio1 is expected to have '#gpio-cells = <2>', and its binding should
# have two elements in '#cells', corresponding to the 1 and 2 values above.
"#cells":
  - cell0    # name of first cell
  - cell1    # name of second cell
  - cell2    # name of third cell
  - and so on and so forth