Documentation/devicetree/bindings/example-schema.yaml

   1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2 # Copyright 2018 Linaro Ltd.
   3 %YAML 1.2
   4 ---
   5 # All the top-level keys are standard json-schema keywords except for
   6 # 'maintainers' and 'select'
   7
   8 # $id is a unique identifier based on the filename. There may or may not be a
   9 # file present at the URL.
  10 $id: http://devicetree.org/schemas/example-schema.yaml#
  11 # $schema is the meta-schema this schema should be validated with.
  12 $schema: http://devicetree.org/meta-schemas/core.yaml#
  13
  14 title: An Example Device
  15
  16 maintainers:
  17   - Rob Herring <robh@kernel.org>
  18
  19 description: |
  20   A more detailed multi-line description of the binding.
  21
  22   Details about the hardware device and any links to datasheets can go here.
  23
  24   Literal blocks are marked with the '|' at the beginning. The end is marked by
  25   indentation less than the first line of the literal block. Lines also cannot
  26   begin with a tab character.
  27
  28 select: false
  29   # 'select' is a schema applied to a DT node to determine if this binding
  30   # schema should be applied to the node. It is optional and by default the
  31   # possible compatible strings are extracted and used to match.
  32
  33   # In this case, a 'false' schema will never match.
  34
  35 properties:
  36   # A dictionary of DT properties for this binding schema
  37   compatible:
  38     # More complicated schema can use oneOf (XOR), anyOf (OR), or allOf (AND)
  39     # to handle different conditions.
  40     # In this case, it's needed to handle a variable number of values as there
  41     # isn't another way to express a constraint of the last string value.
  42     # The boolean schema must be a list of schemas.
  43     oneOf:
  44       - items:
  45           # items is a list of possible values for the property. The number of
  46           # values is determined by the number of elements in the list.
  47           # Order in lists is significant, order in dicts is not
  48           # Must be one of the 1st enums followed by the 2nd enum
  49           #
  50           # Each element in items should be 'enum' or 'const'
  51           - enum:
  52               - vendor,soc4-ip
  53               - vendor,soc3-ip
  54               - vendor,soc2-ip
  55           - const: vendor,soc1-ip
  56         # additionalItems being false is implied
  57         # minItems/maxItems equal to 2 is implied
  58       - items:
  59           # 'const' is just a special case of an enum with a single possible value
  60           - const: vendor,soc1-ip
  61
  62   reg:
  63     # The core schema already checks that reg values are numbers, so device
  64     # specific schema don't need to do those checks.
  65     # The description of each element defines the order and implicitly defines
  66     # the number of reg entries.
  67     items:
  68       - description: core registers
  69       - description: aux registers
  70     # minItems/maxItems equal to 2 is implied
  71
  72   reg-names:
  73     # The core schema enforces this (*-names) is a string array
  74     items:
  75       - const: core
  76       - const: aux
  77
  78   clocks:
  79     # Cases that have only a single entry just need to express that with maxItems
  80     maxItems: 1
  81     description: bus clock. A description is only needed for a single item if
  82       there's something unique to add.
  83       The items should have a fixed order, so pattern matching names are
  84       discouraged.
  85
  86   clock-names:
  87     # For single-entry lists in clocks, resets etc., the xxx-names often do not
  88     # bring any value, especially if they copy the IP block name.  In such case
  89     # just skip the xxx-names.
  90     items:
  91       - const: bus
  92
  93   interrupts:
  94     # Either 1 or 2 interrupts can be present
  95     minItems: 1
  96     items:
  97       - description: tx or combined interrupt
  98       - description: rx interrupt
  99     description:
 100       A variable number of interrupts warrants a description of what conditions
 101       affect the number of interrupts. Otherwise, descriptions on standard
 102       properties are not necessary.
 103       The items should have a fixed order, so pattern matching names are
 104       discouraged.
 105
 106   interrupt-names:
 107     # minItems must be specified here because the default would be 2
 108     minItems: 1
 109     items:
 110       - const: tx irq
 111       - const: rx irq
 112
 113   # Property names starting with '#' must be quoted
 114   '#interrupt-cells':
 115     # A simple case where the value must always be '2'.
 116     # The core schema handles that this must be a single integer.
 117     const: 2
 118
 119   interrupt-controller: true
 120     # The core checks this is a boolean, so just have to list it here to be
 121     # valid for this binding.
 122
 123   clock-frequency:
 124     # The type is set in the core schema. Per-device schema only need to set
 125     # constraints on the possible values.
 126     minimum: 100
 127     maximum: 400000
 128     # The value that should be used if the property is not present
 129     default: 200
 130
 131   foo-gpios:
 132     maxItems: 1
 133     description: A connection of the 'foo' gpio line.
 134
 135   # *-supply is always a single phandle, so nothing more to define.
 136   foo-supply: true
 137
 138   # Vendor-specific properties
 139   #
 140   # Vendor-specific properties have slightly different schema requirements than
 141   # common properties. They must have at least a type definition and
 142   # 'description'.
 143   vendor,int-property:
 144     description: Vendor-specific properties must have a description
 145     $ref: /schemas/types.yaml#/definitions/uint32
 146     enum: [2, 4, 6, 8, 10]
 147
 148   vendor,bool-property:
 149     description: Vendor-specific properties must have a description. Boolean
 150       properties are one case where the json-schema 'type' keyword can be used
 151       directly.
 152     type: boolean
 153
 154   vendor,string-array-property:
 155     description: Vendor-specific properties should reference a type in the
 156       core schema.
 157     $ref: /schemas/types.yaml#/definitions/string-array
 158     items:
 159       - enum: [foo, bar]
 160       - enum: [baz, boo]
 161
 162   vendor,property-in-standard-units-microvolt:
 163     description: Vendor-specific properties having a standard unit suffix
 164       don't need a type.
 165     enum: [ 100, 200, 300 ]
 166
 167   vendor,int-array-variable-length-and-constrained-values:
 168     description: Array might define what type of elements might be used (e.g.
 169       their range).
 170     $ref: /schemas/types.yaml#/definitions/uint32-array
 171     minItems: 2
 172     maxItems: 3
 173     items:
 174       minimum: 0
 175       maximum: 8
 176
 177   child-node:
 178     description: Child nodes are just another property from a json-schema
 179       perspective.
 180     type: object  # DT nodes are json objects
 181     # Child nodes also need additionalProperties or unevaluatedProperties
 182     additionalProperties: false
 183     properties:
 184       vendor,a-child-node-property:
 185         description: Child node properties have all the same schema
 186           requirements.
 187         type: boolean
 188
 189     required:
 190       - vendor,a-child-node-property
 191
 192 # Describe the relationship between different properties
 193 dependencies:
 194   # 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
 195   # is present
 196   vendor,bool-property: [ 'vendor,string-array-property' ]
 197   # Expressing 2 properties in both orders means all of the set of properties
 198   # must be present or none of them.
 199   vendor,string-array-property: [ 'vendor,bool-property' ]
 200
 201 required:
 202   - compatible
 203   - reg
 204   - interrupts
 205   - interrupt-controller
 206
 207 # if/then schema can be used to handle conditions on a property affecting
 208 # another property. A typical case is a specific 'compatible' value changes the
 209 # constraints on other properties.
 210 #
 211 # For multiple 'if' schema, group them under an 'allOf'.
 212 #
 213 # If the conditionals become too unweldy, then it may be better to just split
 214 # the binding into separate schema documents.
 215 allOf:
 216   - if:
 217       properties:
 218         compatible:
 219           contains:
 220             const: vendor,soc2-ip
 221     then:
 222       required:
 223         - foo-supply
 224     else:
 225       # If otherwise the property is not allowed:
 226       properties:
 227         foo-supply: false
 228   # Altering schema depending on presence of properties is usually done by
 229   # dependencies (see above), however some adjustments might require if:
 230   - if:
 231       required:
 232         - vendor,bool-property
 233     then:
 234       properties:
 235         vendor,int-property:
 236           enum: [2, 4, 6]
 237
 238 # Ideally, the schema should have this line otherwise any other properties
 239 # present are allowed. There's a few common properties such as 'status' and
 240 # 'pinctrl-*' which are added automatically by the tooling.
 241 #
 242 # This can't be used in cases where another schema is referenced
 243 # (i.e. allOf: [{$ref: ...}]).
 244 # If and only if another schema is referenced and arbitrary children nodes can
 245 # appear, "unevaluatedProperties: false" could be used.  A typical example is
 246 # an I2C controller where no name pattern matching for children can be added.
 247 additionalProperties: false
 248
 249 examples:
 250   # Examples are now compiled with dtc and validated against the schemas
 251   #
 252   # Examples have a default #address-cells and #size-cells value of 1. This can
 253   # be overridden or an appropriate parent bus node should be shown (such as on
 254   # i2c buses).
 255   #
 256   # Any includes used have to be explicitly included. Use 4-space indentation.
 257   - |
 258     node@1000 {
 259         compatible = "vendor,soc4-ip", "vendor,soc1-ip";
 260         reg = <0x1000 0x80>,
 261               <0x3000 0x80>;
 262         reg-names = "core", "aux";
 263         interrupts = <10>;
 264         interrupt-controller;
 265         #interrupt-cells = <2>;
 266     };