266 lines · yaml
1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)2# Copyright 2018 Linaro Ltd.3%YAML 1.24---5# All the top-level keys are standard json-schema keywords except for6# 'maintainers' and 'select'7 8# $id is a unique identifier based on the filename. There may or may not be a9# 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 Device15 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 by25 indentation less than the first line of the literal block. Lines also cannot26 begin with a tab character.27 28select: false29 # 'select' is a schema applied to a DT node to determine if this binding30 # schema should be applied to the node. It is optional and by default the31 # 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 schema37 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 there41 # 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 of46 # values is determined by the number of elements in the list.47 # Order in lists is significant, order in dicts is not48 # Must be one of the 1st enums followed by the 2nd enum49 #50 # Each element in items should be 'enum' or 'const'51 - enum:52 - vendor,soc4-ip53 - vendor,soc3-ip54 - vendor,soc2-ip55 - const: vendor,soc1-ip56 # additionalItems being false is implied57 # minItems/maxItems equal to 2 is implied58 - items:59 # 'const' is just a special case of an enum with a single possible value60 - const: vendor,soc1-ip61 62 reg:63 # The core schema already checks that reg values are numbers, so device64 # specific schema don't need to do those checks.65 # The description of each element defines the order and implicitly defines66 # the number of reg entries.67 items:68 - description: core registers69 - description: aux registers70 # minItems/maxItems equal to 2 is implied71 72 reg-names:73 # The core schema enforces this (*-names) is a string array74 items:75 - const: core76 - const: aux77 78 clocks:79 # Cases that have only a single entry just need to express that with maxItems80 maxItems: 181 description: bus clock. A description is only needed for a single item if82 there's something unique to add.83 The items should have a fixed order, so pattern matching names are84 discouraged.85 86 clock-names:87 # For single-entry lists in clocks, resets etc., the xxx-names often do not88 # bring any value, especially if they copy the IP block name. In such case89 # just skip the xxx-names.90 items:91 - const: bus92 93 interrupts:94 # Either 1 or 2 interrupts can be present95 minItems: 196 items:97 - description: tx or combined interrupt98 - description: rx interrupt99 description:100 A variable number of interrupts warrants a description of what conditions101 affect the number of interrupts. Otherwise, descriptions on standard102 properties are not necessary.103 The items should have a fixed order, so pattern matching names are104 discouraged.105 106 interrupt-names:107 # minItems must be specified here because the default would be 2108 minItems: 1109 items:110 - const: tx irq111 - const: rx irq112 113 # Property names starting with '#' must be quoted114 '#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: 2118 119 interrupt-controller: true120 # The core checks this is a boolean, so just have to list it here to be121 # valid for this binding.122 123 clock-frequency:124 # The type is set in the core schema. Per-device schema only need to set125 # constraints on the possible values.126 minimum: 100127 maximum: 400000128 # The value that should be used if the property is not present129 default: 200130 131 foo-gpios:132 maxItems: 1133 description: A connection of the 'foo' gpio line.134 135 # *-supply is always a single phandle, so nothing more to define.136 foo-supply: true137 138 # Vendor-specific properties139 #140 # Vendor-specific properties have slightly different schema requirements than141 # common properties. They must have at least a type definition and142 # 'description'.143 vendor,int-property:144 description: Vendor-specific properties must have a description145 $ref: /schemas/types.yaml#/definitions/uint32146 enum: [2, 4, 6, 8, 10]147 148 vendor,bool-property:149 description: Vendor-specific properties must have a description. Boolean150 properties are one case where the json-schema 'type' keyword can be used151 directly.152 type: boolean153 154 vendor,string-array-property:155 description: Vendor-specific properties should reference a type in the156 core schema.157 $ref: /schemas/types.yaml#/definitions/string-array158 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 suffix164 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-array171 minItems: 2172 maxItems: 3173 items:174 minimum: 0175 maximum: 8176 177 child-node:178 description: Child nodes are just another property from a json-schema179 perspective.180 type: object # DT nodes are json objects181 # Child nodes also need additionalProperties or unevaluatedProperties182 additionalProperties: false183 properties:184 vendor,a-child-node-property:185 description: Child node properties have all the same schema186 requirements.187 type: boolean188 189 required:190 - vendor,a-child-node-property191 192# Describe the relationship between different properties193dependencies:194 # 'vendor,bool-property' is only allowed when 'vendor,string-array-property'195 # is present196 vendor,bool-property: [ 'vendor,string-array-property' ]197 # Expressing 2 properties in both orders means all of the set of properties198 # must be present or none of them.199 vendor,string-array-property: [ 'vendor,bool-property' ]200 201required:202 - compatible203 - reg204 - interrupts205 - interrupt-controller206 207# if/then schema can be used to handle conditions on a property affecting208# another property. A typical case is a specific 'compatible' value changes the209# 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 split214# the binding into separate schema documents.215allOf:216 - if:217 properties:218 compatible:219 contains:220 const: vendor,soc2-ip221 then:222 required:223 - foo-supply224 else:225 # If otherwise the property is not allowed:226 properties:227 foo-supply: false228 # Altering schema depending on presence of properties is usually done by229 # dependencies (see above), however some adjustments might require if:230 - if:231 required:232 - vendor,bool-property233 then:234 properties:235 vendor,int-property:236 enum: [2, 4, 6]237 238# Ideally, the schema should have this line otherwise any other properties239# present are allowed. There's a few common properties such as 'status' and240# 'pinctrl-*' which are added automatically by the tooling.241#242# This can't be used in cases where another schema is referenced243# (i.e. allOf: [{$ref: ...}]).244# If and only if another schema is referenced and arbitrary children nodes can245# appear, "unevaluatedProperties: false" could be used. A typical example is246# an I2C controller where no name pattern matching for children can be added.247additionalProperties: false248 249examples:250 # Examples are now compiled with dtc and validated against the schemas251 #252 # Examples have a default #address-cells and #size-cells value of 1. This can253 # be overridden or an appropriate parent bus node should be shown (such as on254 # 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