LXR linux/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
  14title: An example schema annotated with jsonschema details
  15
  16maintainers:
  17  - Rob Herring <robh@kernel.org>
  18
  19description: |
  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
  28select: 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
  35properties:
  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          - enum:
  56              - vendor,soc1-ip
  57        # additionalItems being false is implied
  58        # minItems/maxItems equal to 2 is implied
  59      - items:
  60          # 'const' is just a special case of an enum with a single possible value
  61          - const: vendor,soc1-ip
  62
  63  reg:
  64    # The core schema already checks that reg values are numbers, so device
  65    # specific schema don't need to do those checks.
  66    # The description of each element defines the order and implicitly defines
  67    # the number of reg entries.
  68    items:
  69      - description: core registers
  70      - description: aux registers
  71    # minItems/maxItems equal to 2 is implied
  72
  73  reg-names:
  74    # The core schema enforces this (*-names) is a string array
  75    items:
  76      - const: core
  77      - const: aux
  78
  79  clocks:
  80    # Cases that have only a single entry just need to express that with maxItems
  81    maxItems: 1
  82    description: bus clock. A description is only needed for a single item if
  83      there's something unique to add.
  84      The items should have a fixed order, so pattern matching names are
  85      discouraged.
  86
  87  clock-names:
  88    items:
  89      - const: bus
  90
  91  interrupts:
  92    # Either 1 or 2 interrupts can be present
  93    minItems: 1
  94    items:
  95      - description: tx or combined interrupt
  96      - description: rx interrupt
  97    description:
  98      A variable number of interrupts warrants a description of what conditions
  99      affect the number of interrupts. Otherwise, descriptions on standard
 100      properties are not necessary.
 101      The items should have a fixed order, so pattern matching names are
 102      discouraged.
 103
 104  interrupt-names:
 105    # minItems must be specified here because the default would be 2
 106    minItems: 1
 107    items:
 108      - const: tx irq
 109      - const: rx irq
 110
 111  # Property names starting with '#' must be quoted
 112  '#interrupt-cells':
 113    # A simple case where the value must always be '2'.
 114    # The core schema handles that this must be a single integer.
 115    const: 2
 116
 117  interrupt-controller: true
 118    # The core checks this is a boolean, so just have to list it here to be
 119    # valid for this binding.
 120
 121  clock-frequency:
 122    # The type is set in the core schema. Per device schema only need to set
 123    # constraints on the possible values.
 124    minimum: 100
 125    maximum: 400000
 126    # The value that should be used if the property is not present
 127    default: 200
 128
 129  foo-gpios:
 130    maxItems: 1
 131    description: A connection of the 'foo' gpio line.
 132
 133  # *-supply is always a single phandle, so nothing more to define.
 134  foo-supply: true
 135
 136  # Vendor specific properties
 137  #
 138  # Vendor specific properties have slightly different schema requirements than
 139  # common properties. They must have at least a type definition and
 140  # 'description'.
 141  vendor,int-property:
 142    description: Vendor specific properties must have a description
 143    $ref: /schemas/types.yaml#/definitions/uint32
 144    enum: [2, 4, 6, 8, 10]
 145
 146  vendor,bool-property:
 147    description: Vendor specific properties must have a description. Boolean
 148      properties are one case where the json-schema 'type' keyword can be used
 149      directly.
 150    type: boolean
 151
 152  vendor,string-array-property:
 153    description: Vendor specific properties should reference a type in the
 154      core schema.
 155    $ref: /schemas/types.yaml#/definitions/string-array
 156    items:
 157      - enum: [foo, bar]
 158      - enum: [baz, boo]
 159
 160  vendor,property-in-standard-units-microvolt:
 161    description: Vendor specific properties having a standard unit suffix
 162      don't need a type.
 163    enum: [ 100, 200, 300 ]
 164
 165  child-node:
 166    description: Child nodes are just another property from a json-schema
 167      perspective.
 168    type: object  # DT nodes are json objects
 169    properties:
 170      vendor,a-child-node-property:
 171        description: Child node properties have all the same schema
 172          requirements.
 173        type: boolean
 174
 175    required:
 176      - vendor,a-child-node-property
 177
 178# Describe the relationship between different properties
 179dependencies:
 180  # 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
 181  # is present
 182  vendor,bool-property: [ 'vendor,string-array-property' ]
 183  # Expressing 2 properties in both orders means all of the set of properties
 184  # must be present or none of them.
 185  vendor,string-array-property: [ 'vendor,bool-property' ]
 186
 187required:
 188  - compatible
 189  - reg
 190  - interrupts
 191  - interrupt-controller
 192
 193# if/then schema can be used to handle conditions on a property affecting
 194# another property. A typical case is a specific 'compatible' value changes the
 195# constraints on other properties.
 196#
 197# For multiple 'if' schema, group them under an 'allOf'.
 198#
 199# If the conditionals become too unweldy, then it may be better to just split
 200# the binding into separate schema documents.
 201allOf:
 202  - if:
 203      properties:
 204        compatible:
 205          contains:
 206            const: vendor,soc2-ip
 207    then:
 208      required:
 209        - foo-supply
 210  # Altering schema depending on presence of properties is usually done by
 211  # dependencies (see above), however some adjustments might require if:
 212  - if:
 213      required:
 214        - vendor,bool-property
 215    then:
 216      properties:
 217        vendor,int-property:
 218          enum: [2, 4, 6]
 219
 220# Ideally, the schema should have this line otherwise any other properties
 221# present are allowed. There's a few common properties such as 'status' and
 222# 'pinctrl-*' which are added automatically by the tooling.
 223#
 224# This can't be used in cases where another schema is referenced
 225# (i.e. allOf: [{$ref: ...}]).
 226# If and only if another schema is referenced and arbitrary children nodes can
 227# appear, "unevaluatedProperties: false" could be used.  A typical example is
 228# an I2C controller where no name pattern matching for children can be added.
 229additionalProperties: false
 230
 231examples:
 232  # Examples are now compiled with dtc and validated against the schemas
 233  #
 234  # Examples have a default #address-cells and #size-cells value of 1. This can
 235  # be overridden or an appropriate parent bus node should be shown (such as on
 236  # i2c buses).
 237  #
 238  # Any includes used have to be explicitly included.
 239  - |
 240    node@1000 {
 241          compatible = "vendor,soc4-ip", "vendor,soc1-ip";
 242          reg = <0x1000 0x80>,
 243                <0x3000 0x80>;
 244          reg-names = "core", "aux";
 245          interrupts = <10>;
 246          interrupt-controller;
 247    };
 248