158fbe999SRob Herring# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) 200ce8a80SRob Herring# Copyright 2018 Linaro Ltd. 300ce8a80SRob Herring%YAML 1.2 400ce8a80SRob Herring--- 500ce8a80SRob Herring# All the top-level keys are standard json-schema keywords except for 600ce8a80SRob Herring# 'maintainers' and 'select' 700ce8a80SRob Herring 843c63c15SSimon Horman# $id is a unique identifier based on the filename. There may or may not be a 900ce8a80SRob Herring# file present at the URL. 10*238415f7SGeert Uytterhoeven$id: http://devicetree.org/schemas/example-schema.yaml# 1100ce8a80SRob Herring# $schema is the meta-schema this schema should be validated with. 12*238415f7SGeert Uytterhoeven$schema: http://devicetree.org/meta-schemas/core.yaml# 1300ce8a80SRob Herring 1400ce8a80SRob Herringtitle: An example schema annotated with jsonschema details 1500ce8a80SRob Herring 1600ce8a80SRob Herringmaintainers: 1700ce8a80SRob Herring - Rob Herring <robh@kernel.org> 1800ce8a80SRob Herring 1900ce8a80SRob Herringdescription: | 2000ce8a80SRob Herring A more detailed multi-line description of the binding. 2100ce8a80SRob Herring 2200ce8a80SRob Herring Details about the hardware device and any links to datasheets can go here. 2300ce8a80SRob Herring 2400ce8a80SRob Herring Literal blocks are marked with the '|' at the beginning. The end is marked by 2500ce8a80SRob Herring indentation less than the first line of the literal block. Lines also cannot 2600ce8a80SRob Herring begin with a tab character. 2700ce8a80SRob Herring 2800ce8a80SRob Herringselect: false 2900ce8a80SRob Herring # 'select' is a schema applied to a DT node to determine if this binding 3000ce8a80SRob Herring # schema should be applied to the node. It is optional and by default the 3100ce8a80SRob Herring # possible compatible strings are extracted and used to match. 3200ce8a80SRob Herring 3300ce8a80SRob Herring # In this case, a 'false' schema will never match. 3400ce8a80SRob Herring 3500ce8a80SRob Herringproperties: 3600ce8a80SRob Herring # A dictionary of DT properties for this binding schema 3700ce8a80SRob Herring compatible: 3800ce8a80SRob Herring # More complicated schema can use oneOf (XOR), anyOf (OR), or allOf (AND) 3900ce8a80SRob Herring # to handle different conditions. 4000ce8a80SRob Herring # In this case, it's needed to handle a variable number of values as there 4100ce8a80SRob Herring # isn't another way to express a constraint of the last string value. 4200ce8a80SRob Herring # The boolean schema must be a list of schemas. 4300ce8a80SRob Herring oneOf: 4400ce8a80SRob Herring - items: 4500ce8a80SRob Herring # items is a list of possible values for the property. The number of 4600ce8a80SRob Herring # values is determined by the number of elements in the list. 4700ce8a80SRob Herring # Order in lists is significant, order in dicts is not 4800ce8a80SRob Herring # Must be one of the 1st enums followed by the 2nd enum 4900ce8a80SRob Herring # 5000ce8a80SRob Herring # Each element in items should be 'enum' or 'const' 5100ce8a80SRob Herring - enum: 5200ce8a80SRob Herring - vendor,soc4-ip 5300ce8a80SRob Herring - vendor,soc3-ip 5400ce8a80SRob Herring - vendor,soc2-ip 5500ce8a80SRob Herring - enum: 5600ce8a80SRob Herring - vendor,soc1-ip 5700ce8a80SRob Herring # additionalItems being false is implied 5800ce8a80SRob Herring # minItems/maxItems equal to 2 is implied 5900ce8a80SRob Herring - items: 6000ce8a80SRob Herring # 'const' is just a special case of an enum with a single possible value 6100ce8a80SRob Herring - const: vendor,soc1-ip 6200ce8a80SRob Herring 6300ce8a80SRob Herring reg: 6400ce8a80SRob Herring # The core schema already checks that reg values are numbers, so device 6500ce8a80SRob Herring # specific schema don't need to do those checks. 6600ce8a80SRob Herring # The description of each element defines the order and implicitly defines 6700ce8a80SRob Herring # the number of reg entries. 6800ce8a80SRob Herring items: 6900ce8a80SRob Herring - description: core registers 7000ce8a80SRob Herring - description: aux registers 7100ce8a80SRob Herring # minItems/maxItems equal to 2 is implied 7200ce8a80SRob Herring 7300ce8a80SRob Herring reg-names: 7458fbe999SRob Herring # The core schema enforces this (*-names) is a string array 7500ce8a80SRob Herring items: 7600ce8a80SRob Herring - const: core 7700ce8a80SRob Herring - const: aux 7800ce8a80SRob Herring 7900ce8a80SRob Herring clocks: 8000ce8a80SRob Herring # Cases that have only a single entry just need to express that with maxItems 8100ce8a80SRob Herring maxItems: 1 8258fbe999SRob Herring description: bus clock. A description is only needed for a single item if 8358fbe999SRob Herring there's something unique to add. 8400ce8a80SRob Herring 8500ce8a80SRob Herring clock-names: 8600ce8a80SRob Herring items: 8700ce8a80SRob Herring - const: bus 8800ce8a80SRob Herring 8900ce8a80SRob Herring interrupts: 9000ce8a80SRob Herring # Either 1 or 2 interrupts can be present 9100ce8a80SRob Herring minItems: 1 9200ce8a80SRob Herring maxItems: 2 9300ce8a80SRob Herring items: 9400ce8a80SRob Herring - description: tx or combined interrupt 9500ce8a80SRob Herring - description: rx interrupt 9600ce8a80SRob Herring description: 9700ce8a80SRob Herring A variable number of interrupts warrants a description of what conditions 9800ce8a80SRob Herring affect the number of interrupts. Otherwise, descriptions on standard 9900ce8a80SRob Herring properties are not necessary. 10000ce8a80SRob Herring 10100ce8a80SRob Herring interrupt-names: 10200ce8a80SRob Herring # minItems must be specified here because the default would be 2 10300ce8a80SRob Herring minItems: 1 10400ce8a80SRob Herring maxItems: 2 10500ce8a80SRob Herring items: 10600ce8a80SRob Herring - const: tx irq 10700ce8a80SRob Herring - const: rx irq 10800ce8a80SRob Herring 10900ce8a80SRob Herring # Property names starting with '#' must be quoted 11000ce8a80SRob Herring '#interrupt-cells': 11100ce8a80SRob Herring # A simple case where the value must always be '2'. 11200ce8a80SRob Herring # The core schema handles that this must be a single integer. 11300ce8a80SRob Herring const: 2 11400ce8a80SRob Herring 11500ce8a80SRob Herring interrupt-controller: true 11600ce8a80SRob Herring # The core checks this is a boolean, so just have to list it here to be 11700ce8a80SRob Herring # valid for this binding. 11800ce8a80SRob Herring 11900ce8a80SRob Herring clock-frequency: 12000ce8a80SRob Herring # The type is set in the core schema. Per device schema only need to set 12100ce8a80SRob Herring # constraints on the possible values. 12200ce8a80SRob Herring minimum: 100 12300ce8a80SRob Herring maximum: 400000 12400ce8a80SRob Herring # The value that should be used if the property is not present 12500ce8a80SRob Herring default: 200 12600ce8a80SRob Herring 12700ce8a80SRob Herring foo-gpios: 12800ce8a80SRob Herring maxItems: 1 12900ce8a80SRob Herring description: A connection of the 'foo' gpio line. 13000ce8a80SRob Herring 13158fbe999SRob Herring # *-supply is always a single phandle, so nothing more to define. 13258fbe999SRob Herring foo-supply: true 13358fbe999SRob Herring 13458fbe999SRob Herring # Vendor specific properties 13558fbe999SRob Herring # 13658fbe999SRob Herring # Vendor specific properties have slightly different schema requirements than 13758fbe999SRob Herring # common properties. They must have at least a type definition and 13858fbe999SRob Herring # 'description'. 13900ce8a80SRob Herring vendor,int-property: 14000ce8a80SRob Herring description: Vendor specific properties must have a description 14100ce8a80SRob Herring # 'allOf' is the json-schema way of subclassing a schema. Here the base 14200ce8a80SRob Herring # type schema is referenced and then additional constraints on the values 14300ce8a80SRob Herring # are added. 14400ce8a80SRob Herring allOf: 14500ce8a80SRob Herring - $ref: /schemas/types.yaml#/definitions/uint32 14600ce8a80SRob Herring - enum: [2, 4, 6, 8, 10] 14700ce8a80SRob Herring 14800ce8a80SRob Herring vendor,bool-property: 14958fbe999SRob Herring description: Vendor specific properties must have a description. Boolean 15058fbe999SRob Herring properties are one case where the json-schema 'type' keyword can be used 15158fbe999SRob Herring directly. 15200ce8a80SRob Herring type: boolean 15300ce8a80SRob Herring 15400ce8a80SRob Herring vendor,string-array-property: 15500ce8a80SRob Herring description: Vendor specific properties should reference a type in the 15600ce8a80SRob Herring core schema. 15700ce8a80SRob Herring allOf: 15800ce8a80SRob Herring - $ref: /schemas/types.yaml#/definitions/string-array 15900ce8a80SRob Herring - items: 16000ce8a80SRob Herring - enum: [ foo, bar ] 16100ce8a80SRob Herring - enum: [ baz, boo ] 16200ce8a80SRob Herring 1632fa0a530SRob Herring vendor,property-in-standard-units-microvolt: 16458fbe999SRob Herring description: Vendor specific properties having a standard unit suffix 16558fbe999SRob Herring don't need a type. 16658fbe999SRob Herring enum: [ 100, 200, 300 ] 16758fbe999SRob Herring 16858fbe999SRob Herring child-node: 16958fbe999SRob Herring description: Child nodes are just another property from a json-schema 17058fbe999SRob Herring perspective. 17158fbe999SRob Herring type: object # DT nodes are json objects 17258fbe999SRob Herring properties: 17358fbe999SRob Herring vendor,a-child-node-property: 17458fbe999SRob Herring description: Child node properties have all the same schema 17558fbe999SRob Herring requirements. 17658fbe999SRob Herring type: boolean 17758fbe999SRob Herring 17858fbe999SRob Herring required: 17958fbe999SRob Herring - vendor,a-child-node-property 18058fbe999SRob Herring 18158fbe999SRob Herring# Describe the relationship between different properties 18258fbe999SRob Herringdependencies: 18358fbe999SRob Herring # 'vendor,bool-property' is only allowed when 'vendor,string-array-property' 18458fbe999SRob Herring # is present 18558fbe999SRob Herring vendor,bool-property: [ vendor,string-array-property ] 18658fbe999SRob Herring # Expressing 2 properties in both orders means all of the set of properties 18758fbe999SRob Herring # must be present or none of them. 18858fbe999SRob Herring vendor,string-array-property: [ vendor,bool-property ] 18958fbe999SRob Herring 19000ce8a80SRob Herringrequired: 19100ce8a80SRob Herring - compatible 19200ce8a80SRob Herring - reg 19300ce8a80SRob Herring - interrupts 19400ce8a80SRob Herring - interrupt-controller 19500ce8a80SRob Herring 19658fbe999SRob Herring# if/then schema can be used to handle conditions on a property affecting 19758fbe999SRob Herring# another property. A typical case is a specific 'compatible' value changes the 19858fbe999SRob Herring# constraints on other properties. 19958fbe999SRob Herring# 20058fbe999SRob Herring# For multiple 'if' schema, group them under an 'allOf'. 20158fbe999SRob Herring# 20258fbe999SRob Herring# If the conditionals become too unweldy, then it may be better to just split 20358fbe999SRob Herring# the binding into separate schema documents. 20458fbe999SRob Herringif: 20558fbe999SRob Herring properties: 20658fbe999SRob Herring compatible: 20758fbe999SRob Herring contains: 20858fbe999SRob Herring const: vendor,soc2-ip 20958fbe999SRob Herringthen: 21058fbe999SRob Herring required: 21158fbe999SRob Herring - foo-supply 21258fbe999SRob Herring 21358fbe999SRob Herring# Ideally, the schema should have this line otherwise any other properties 21458fbe999SRob Herring# present are allowed. There's a few common properties such as 'status' and 21558fbe999SRob Herring# 'pinctrl-*' which are added automatically by the tooling. 21658fbe999SRob Herring# 21758fbe999SRob Herring# This can't be used in cases where another schema is referenced 21858fbe999SRob Herring# (i.e. allOf: [{$ref: ...}]). 21958fbe999SRob HerringadditionalProperties: false 22058fbe999SRob Herring 22100ce8a80SRob Herringexamples: 22258fbe999SRob Herring # Examples are now compiled with dtc and validated against the schemas 22358fbe999SRob Herring # 22458fbe999SRob Herring # Examples have a default #address-cells and #size-cells value of 1. This can 22558fbe999SRob Herring # be overridden or an appropriate parent bus node should be shown (such as on 22658fbe999SRob Herring # i2c buses). 22758fbe999SRob Herring # 22858fbe999SRob Herring # Any includes used have to be explicitly included. 22900ce8a80SRob Herring - | 23000ce8a80SRob Herring node@1000 { 23100ce8a80SRob Herring compatible = "vendor,soc4-ip", "vendor,soc1-ip"; 23200ce8a80SRob Herring reg = <0x1000 0x80>, 23300ce8a80SRob Herring <0x3000 0x80>; 23400ce8a80SRob Herring reg-names = "core", "aux"; 23500ce8a80SRob Herring interrupts = <10>; 23600ce8a80SRob Herring interrupt-controller; 23700ce8a80SRob Herring }; 238