Documentation/devicetree/bindings/example-schema.yaml

   1 # SPDX-License-Identifier: (GPL-2.0 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 idenifier 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 schema annotated with jsonschema details
  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           - 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 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
  83
  84   clock-names:
  85     items:
  86       - const: bus
  87
  88   interrupts:
  89     # Either 1 or 2 interrupts can be present
  90     minItems: 1
  91     maxItems: 2
  92     items:
  93       - description: tx or combined interrupt
  94       - description: rx interrupt
  95     description:
  96       A variable number of interrupts warrants a description of what conditions
  97       affect the number of interrupts. Otherwise, descriptions on standard
  98       properties are not necessary.
  99
 100   interrupt-names:
 101     # minItems must be specified here because the default would be 2
 102     minItems: 1
 103     maxItems: 2
 104     items:
 105       - const: tx irq
 106       - const: rx irq
 107
 108   # Property names starting with '#' must be quoted
 109   '#interrupt-cells':
 110     # A simple case where the value must always be '2'.
 111     # The core schema handles that this must be a single integer.
 112     const: 2
 113
 114   interrupt-controller: true
 115     # The core checks this is a boolean, so just have to list it here to be
 116     # valid for this binding.
 117
 118   clock-frequency:
 119     # The type is set in the core schema. Per device schema only need to set
 120     # constraints on the possible values.
 121     minimum: 100
 122     maximum: 400000
 123     # The value that should be used if the property is not present
 124     default: 200
 125
 126   foo-gpios:
 127     maxItems: 1
 128     description: A connection of the 'foo' gpio line.
 129
 130   vendor,int-property:
 131     description: Vendor specific properties must have a description
 132     # 'allOf' is the json-schema way of subclassing a schema. Here the base
 133     # type schema is referenced and then additional constraints on the values
 134     # are added.
 135     allOf:
 136       - $ref: /schemas/types.yaml#/definitions/uint32
 137       - enum: [2, 4, 6, 8, 10]
 138
 139   vendor,bool-property:
 140     description: Vendor specific properties must have a description
 141     # boolean properties is one case where the json-schema 'type' keyword
 142     # can be used directly
 143     type: boolean
 144
 145   vendor,string-array-property:
 146     description: Vendor specific properties should reference a type in the
 147       core schema.
 148     allOf:
 149       - $ref: /schemas/types.yaml#/definitions/string-array
 150       - items:
 151           - enum: [ foo, bar ]
 152           - enum: [ baz, boo ]
 153
 154 required:
 155   - compatible
 156   - reg
 157   - interrupts
 158   - interrupt-controller
 159
 160 examples:
 161   # Examples are now compiled with dtc
 162   - |
 163     node@1000 {
 164           compatible = "vendor,soc4-ip", "vendor,soc1-ip";
 165           reg = <0x1000 0x80>,
 166                 <0x3000 0x80>;
 167           reg-names = "core", "aux";
 168           interrupts = <10>;
 169           interrupt-controller;
 170     };