0001 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
0002 # Copyright 2018 Linaro Ltd.
0003 %YAML 1.2
0004 ---
0005 # All the top-level keys are standard json-schema keywords except for
0006 # 'maintainers' and 'select'
0007
0008 # $id is a unique identifier based on the filename. There may or may not be a
0009 # file present at the URL.
0010 $id: http://devicetree.org/schemas/example-schema.yaml#
0011 # $schema is the meta-schema this schema should be validated with.
0012 $schema: http://devicetree.org/meta-schemas/core.yaml#
0013
0014 title: An example schema annotated with jsonschema details
0015
0016 maintainers:
0017 - Rob Herring <robh@kernel.org>
0018
0019 description: |
0020 A more detailed multi-line description of the binding.
0021
0022 Details about the hardware device and any links to datasheets can go here.
0023
0024 Literal blocks are marked with the '|' at the beginning. The end is marked by
0025 indentation less than the first line of the literal block. Lines also cannot
0026 begin with a tab character.
0027
0028 select: false
0029 # 'select' is a schema applied to a DT node to determine if this binding
0030 # schema should be applied to the node. It is optional and by default the
0031 # possible compatible strings are extracted and used to match.
0032
0033 # In this case, a 'false' schema will never match.
0034
0035 properties:
0036 # A dictionary of DT properties for this binding schema
0037 compatible:
0038 # More complicated schema can use oneOf (XOR), anyOf (OR), or allOf (AND)
0039 # to handle different conditions.
0040 # In this case, it's needed to handle a variable number of values as there
0041 # isn't another way to express a constraint of the last string value.
0042 # The boolean schema must be a list of schemas.
0043 oneOf:
0044 - items:
0045 # items is a list of possible values for the property. The number of
0046 # values is determined by the number of elements in the list.
0047 # Order in lists is significant, order in dicts is not
0048 # Must be one of the 1st enums followed by the 2nd enum
0049 #
0050 # Each element in items should be 'enum' or 'const'
0051 - enum:
0052 - vendor,soc4-ip
0053 - vendor,soc3-ip
0054 - vendor,soc2-ip
0055 - enum:
0056 - vendor,soc1-ip
0057 # additionalItems being false is implied
0058 # minItems/maxItems equal to 2 is implied
0059 - items:
0060 # 'const' is just a special case of an enum with a single possible value
0061 - const: vendor,soc1-ip
0062
0063 reg:
0064 # The core schema already checks that reg values are numbers, so device
0065 # specific schema don't need to do those checks.
0066 # The description of each element defines the order and implicitly defines
0067 # the number of reg entries.
0068 items:
0069 - description: core registers
0070 - description: aux registers
0071 # minItems/maxItems equal to 2 is implied
0072
0073 reg-names:
0074 # The core schema enforces this (*-names) is a string array
0075 items:
0076 - const: core
0077 - const: aux
0078
0079 clocks:
0080 # Cases that have only a single entry just need to express that with maxItems
0081 maxItems: 1
0082 description: bus clock. A description is only needed for a single item if
0083 there's something unique to add.
0084 The items should have a fixed order, so pattern matching names are
0085 discouraged.
0086
0087 clock-names:
0088 items:
0089 - const: bus
0090
0091 interrupts:
0092 # Either 1 or 2 interrupts can be present
0093 minItems: 1
0094 items:
0095 - description: tx or combined interrupt
0096 - description: rx interrupt
0097 description:
0098 A variable number of interrupts warrants a description of what conditions
0099 affect the number of interrupts. Otherwise, descriptions on standard
0100 properties are not necessary.
0101 The items should have a fixed order, so pattern matching names are
0102 discouraged.
0103
0104 interrupt-names:
0105 # minItems must be specified here because the default would be 2
0106 minItems: 1
0107 items:
0108 - const: tx irq
0109 - const: rx irq
0110
0111 # Property names starting with '#' must be quoted
0112 '#interrupt-cells':
0113 # A simple case where the value must always be '2'.
0114 # The core schema handles that this must be a single integer.
0115 const: 2
0116
0117 interrupt-controller: true
0118 # The core checks this is a boolean, so just have to list it here to be
0119 # valid for this binding.
0120
0121 clock-frequency:
0122 # The type is set in the core schema. Per-device schema only need to set
0123 # constraints on the possible values.
0124 minimum: 100
0125 maximum: 400000
0126 # The value that should be used if the property is not present
0127 default: 200
0128
0129 foo-gpios:
0130 maxItems: 1
0131 description: A connection of the 'foo' gpio line.
0132
0133 # *-supply is always a single phandle, so nothing more to define.
0134 foo-supply: true
0135
0136 # Vendor-specific properties
0137 #
0138 # Vendor-specific properties have slightly different schema requirements than
0139 # common properties. They must have at least a type definition and
0140 # 'description'.
0141 vendor,int-property:
0142 description: Vendor-specific properties must have a description
0143 $ref: /schemas/types.yaml#/definitions/uint32
0144 enum: [2, 4, 6, 8, 10]
0145
0146 vendor,bool-property:
0147 description: Vendor-specific properties must have a description. Boolean
0148 properties are one case where the json-schema 'type' keyword can be used
0149 directly.
0150 type: boolean
0151
0152 vendor,string-array-property:
0153 description: Vendor-specific properties should reference a type in the
0154 core schema.
0155 $ref: /schemas/types.yaml#/definitions/string-array
0156 items:
0157 - enum: [foo, bar]
0158 - enum: [baz, boo]
0159
0160 vendor,property-in-standard-units-microvolt:
0161 description: Vendor-specific properties having a standard unit suffix
0162 don't need a type.
0163 enum: [ 100, 200, 300 ]
0164
0165 vendor,int-array-variable-length-and-constrained-values:
0166 description: Array might define what type of elements might be used (e.g.
0167 their range).
0168 $ref: /schemas/types.yaml#/definitions/uint32-array
0169 minItems: 2
0170 maxItems: 3
0171 items:
0172 minimum: 0
0173 maximum: 8
0174
0175 child-node:
0176 description: Child nodes are just another property from a json-schema
0177 perspective.
0178 type: object # DT nodes are json objects
0179 properties:
0180 vendor,a-child-node-property:
0181 description: Child node properties have all the same schema
0182 requirements.
0183 type: boolean
0184
0185 required:
0186 - vendor,a-child-node-property
0187
0188 # Describe the relationship between different properties
0189 dependencies:
0190 # 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
0191 # is present
0192 vendor,bool-property: [ 'vendor,string-array-property' ]
0193 # Expressing 2 properties in both orders means all of the set of properties
0194 # must be present or none of them.
0195 vendor,string-array-property: [ 'vendor,bool-property' ]
0196
0197 required:
0198 - compatible
0199 - reg
0200 - interrupts
0201 - interrupt-controller
0202
0203 # if/then schema can be used to handle conditions on a property affecting
0204 # another property. A typical case is a specific 'compatible' value changes the
0205 # constraints on other properties.
0206 #
0207 # For multiple 'if' schema, group them under an 'allOf'.
0208 #
0209 # If the conditionals become too unweldy, then it may be better to just split
0210 # the binding into separate schema documents.
0211 allOf:
0212 - if:
0213 properties:
0214 compatible:
0215 contains:
0216 const: vendor,soc2-ip
0217 then:
0218 required:
0219 - foo-supply
0220 else:
0221 # If otherwise the property is not allowed:
0222 properties:
0223 foo-supply: false
0224 # Altering schema depending on presence of properties is usually done by
0225 # dependencies (see above), however some adjustments might require if:
0226 - if:
0227 required:
0228 - vendor,bool-property
0229 then:
0230 properties:
0231 vendor,int-property:
0232 enum: [2, 4, 6]
0233
0234 # Ideally, the schema should have this line otherwise any other properties
0235 # present are allowed. There's a few common properties such as 'status' and
0236 # 'pinctrl-*' which are added automatically by the tooling.
0237 #
0238 # This can't be used in cases where another schema is referenced
0239 # (i.e. allOf: [{$ref: ...}]).
0240 # If and only if another schema is referenced and arbitrary children nodes can
0241 # appear, "unevaluatedProperties: false" could be used. A typical example is
0242 # an I2C controller where no name pattern matching for children can be added.
0243 additionalProperties: false
0244
0245 examples:
0246 # Examples are now compiled with dtc and validated against the schemas
0247 #
0248 # Examples have a default #address-cells and #size-cells value of 1. This can
0249 # be overridden or an appropriate parent bus node should be shown (such as on
0250 # i2c buses).
0251 #
0252 # Any includes used have to be explicitly included. Use 4-space indentation.
0253 - |
0254 node@1000 {
0255 compatible = "vendor,soc4-ip", "vendor,soc1-ip";
0256 reg = <0x1000 0x80>,
0257 <0x3000 0x80>;
0258 reg-names = "core", "aux";
0259 interrupts = <10>;
0260 interrupt-controller;
0261 };
