123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249 |
- # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
- # Copyright 2018 Linaro Ltd.
- %YAML 1.2
- ---
- # All the top-level keys are standard json-schema keywords except for
- # 'maintainers' and 'select'
- # $id is a unique identifier based on the filename. There may or may not be a
- # file present at the URL.
- $id: http://devicetree.org/schemas/example-schema.yaml#
- # $schema is the meta-schema this schema should be validated with.
- $schema: http://devicetree.org/meta-schemas/core.yaml#
- title: An example schema annotated with jsonschema details
- maintainers:
- - Rob Herring <robh@kernel.org>
- description: |
- A more detailed multi-line description of the binding.
- Details about the hardware device and any links to datasheets can go here.
- Literal blocks are marked with the '|' at the beginning. The end is marked by
- indentation less than the first line of the literal block. Lines also cannot
- begin with a tab character.
- select: false
- # 'select' is a schema applied to a DT node to determine if this binding
- # schema should be applied to the node. It is optional and by default the
- # possible compatible strings are extracted and used to match.
- # In this case, a 'false' schema will never match.
- properties:
- # A dictionary of DT properties for this binding schema
- compatible:
- # More complicated schema can use oneOf (XOR), anyOf (OR), or allOf (AND)
- # to handle different conditions.
- # In this case, it's needed to handle a variable number of values as there
- # isn't another way to express a constraint of the last string value.
- # The boolean schema must be a list of schemas.
- oneOf:
- - items:
- # items is a list of possible values for the property. The number of
- # values is determined by the number of elements in the list.
- # Order in lists is significant, order in dicts is not
- # Must be one of the 1st enums followed by the 2nd enum
- #
- # Each element in items should be 'enum' or 'const'
- - enum:
- - vendor,soc4-ip
- - vendor,soc3-ip
- - vendor,soc2-ip
- - enum:
- - vendor,soc1-ip
- # additionalItems being false is implied
- # minItems/maxItems equal to 2 is implied
- - items:
- # 'const' is just a special case of an enum with a single possible value
- - const: vendor,soc1-ip
- reg:
- # The core schema already checks that reg values are numbers, so device
- # specific schema don't need to do those checks.
- # The description of each element defines the order and implicitly defines
- # the number of reg entries.
- items:
- - description: core registers
- - description: aux registers
- # minItems/maxItems equal to 2 is implied
- reg-names:
- # The core schema enforces this (*-names) is a string array
- items:
- - const: core
- - const: aux
- clocks:
- # Cases that have only a single entry just need to express that with maxItems
- maxItems: 1
- description: bus clock. A description is only needed for a single item if
- there's something unique to add.
- The items should have a fixed order, so pattern matching names are
- discouraged.
- clock-names:
- items:
- - const: bus
- interrupts:
- # Either 1 or 2 interrupts can be present
- minItems: 1
- maxItems: 2
- items:
- - description: tx or combined interrupt
- - description: rx interrupt
- description:
- A variable number of interrupts warrants a description of what conditions
- affect the number of interrupts. Otherwise, descriptions on standard
- properties are not necessary.
- The items should have a fixed order, so pattern matching names are
- discouraged.
- interrupt-names:
- # minItems must be specified here because the default would be 2
- minItems: 1
- maxItems: 2
- items:
- - const: tx irq
- - const: rx irq
- # Property names starting with '#' must be quoted
- '#interrupt-cells':
- # A simple case where the value must always be '2'.
- # The core schema handles that this must be a single integer.
- const: 2
- interrupt-controller: true
- # The core checks this is a boolean, so just have to list it here to be
- # valid for this binding.
- clock-frequency:
- # The type is set in the core schema. Per device schema only need to set
- # constraints on the possible values.
- minimum: 100
- maximum: 400000
- # The value that should be used if the property is not present
- default: 200
- foo-gpios:
- maxItems: 1
- description: A connection of the 'foo' gpio line.
- # *-supply is always a single phandle, so nothing more to define.
- foo-supply: true
- # Vendor specific properties
- #
- # Vendor specific properties have slightly different schema requirements than
- # common properties. They must have at least a type definition and
- # 'description'.
- vendor,int-property:
- description: Vendor specific properties must have a description
- $ref: /schemas/types.yaml#/definitions/uint32
- enum: [2, 4, 6, 8, 10]
- vendor,bool-property:
- description: Vendor specific properties must have a description. Boolean
- properties are one case where the json-schema 'type' keyword can be used
- directly.
- type: boolean
- vendor,string-array-property:
- description: Vendor specific properties should reference a type in the
- core schema.
- $ref: /schemas/types.yaml#/definitions/string-array
- items:
- - enum: [foo, bar]
- - enum: [baz, boo]
- vendor,property-in-standard-units-microvolt:
- description: Vendor specific properties having a standard unit suffix
- don't need a type.
- enum: [ 100, 200, 300 ]
- child-node:
- description: Child nodes are just another property from a json-schema
- perspective.
- type: object # DT nodes are json objects
- properties:
- vendor,a-child-node-property:
- description: Child node properties have all the same schema
- requirements.
- type: boolean
- required:
- - vendor,a-child-node-property
- # Describe the relationship between different properties
- dependencies:
- # 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
- # is present
- vendor,bool-property: [ 'vendor,string-array-property' ]
- # Expressing 2 properties in both orders means all of the set of properties
- # must be present or none of them.
- vendor,string-array-property: [ 'vendor,bool-property' ]
- required:
- - compatible
- - reg
- - interrupts
- - interrupt-controller
- # if/then schema can be used to handle conditions on a property affecting
- # another property. A typical case is a specific 'compatible' value changes the
- # constraints on other properties.
- #
- # For multiple 'if' schema, group them under an 'allOf'.
- #
- # If the conditionals become too unweldy, then it may be better to just split
- # the binding into separate schema documents.
- allOf:
- - if:
- properties:
- compatible:
- contains:
- const: vendor,soc2-ip
- then:
- required:
- - foo-supply
- # Altering schema depending on presence of properties is usually done by
- # dependencies (see above), however some adjustments might require if:
- - if:
- required:
- - vendor,bool-property
- then:
- properties:
- vendor,int-property:
- enum: [2, 4, 6]
- # Ideally, the schema should have this line otherwise any other properties
- # present are allowed. There's a few common properties such as 'status' and
- # 'pinctrl-*' which are added automatically by the tooling.
- #
- # This can't be used in cases where another schema is referenced
- # (i.e. allOf: [{$ref: ...}]).
- # If and only if another schema is referenced and arbitrary children nodes can
- # appear, "unevaluatedProperties: false" could be used. A typical example is
- # an I2C controller where no name pattern matching for children can be added.
- additionalProperties: false
- examples:
- # Examples are now compiled with dtc and validated against the schemas
- #
- # Examples have a default #address-cells and #size-cells value of 1. This can
- # be overridden or an appropriate parent bus node should be shown (such as on
- # i2c buses).
- #
- # Any includes used have to be explicitly included.
- - |
- node@1000 {
- compatible = "vendor,soc4-ip", "vendor,soc1-ip";
- reg = <0x1000 0x80>,
- <0x3000 0x80>;
- reg-names = "core", "aux";
- interrupts = <10>;
- interrupt-controller;
- };
|