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 Device 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 - 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 193dependencies: 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 201required: 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. 215allOf: 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. 247additionalProperties: false 248 249examples: 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 }; 266