# 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 Device 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 - const: 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: # For single-entry lists in clocks, resets etc., the xxx-names often do not # bring any value, especially if they copy the IP block name. In such case # just skip the xxx-names. items: - const: bus interrupts: # Either 1 or 2 interrupts can be present minItems: 1 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 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 ] vendor,int-array-variable-length-and-constrained-values: description: Array might define what type of elements might be used (e.g. their range). $ref: /schemas/types.yaml#/definitions/uint32-array minItems: 2 maxItems: 3 items: minimum: 0 maximum: 8 child-node: description: Child nodes are just another property from a json-schema perspective. type: object # DT nodes are json objects # Child nodes also need additionalProperties or unevaluatedProperties, where # 'false' should be used in most cases (see 'child-node-with-own-schema' # below). additionalProperties: false properties: vendor,a-child-node-property: description: Child node properties have all the same schema requirements. type: boolean required: - vendor,a-child-node-property child-node-with-own-schema: description: | Child node with their own compatible and device schema which ends in 'additionalProperties: false' or 'unevaluatedProperties: false' can mention only the compatible and use here 'additionalProperties: true'. type: object additionalProperties: true properties: compatible: const: vendor,sub-device # Describe the relationship between different propertiesdependencies: # '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 unwieldy, 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 else: # If otherwise the property is not allowed: properties: foo-supply: false # 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. Use 4-space indentation. - | node@1000 { compatible = "vendor,soc4-ip", "vendor,soc1-ip"; reg = <0x1000 0x80>, <0x3000 0x80>; reg-names = "core", "aux"; interrupts = <10>; interrupt-controller; #interrupt-cells = <2>; };
# 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 Device
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
- const: 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:
# For single-entry lists in clocks, resets etc., the xxx-names often do not
# bring any value, especially if they copy the IP block name. In such case
# just skip the xxx-names.
items:
- const: bus
interrupts:
# Either 1 or 2 interrupts can be present
minItems: 1
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
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 ]
vendor,int-array-variable-length-and-constrained-values:
description: Array might define what type of elements might be used (e.g.
their range).
$ref: /schemas/types.yaml#/definitions/uint32-array
minItems: 2
maxItems: 3
items:
minimum: 0
maximum: 8
child-node:
description: Child nodes are just another property from a json-schema
perspective.
type: object # DT nodes are json objects
# Child nodes also need additionalProperties or unevaluatedProperties, where
# 'false' should be used in most cases (see 'child-node-with-own-schema'
# below).
additionalProperties: false
properties:
vendor,a-child-node-property:
description: Child node properties have all the same schema
requirements.
type: boolean
required:
- vendor,a-child-node-property
child-node-with-own-schema:
description: |
Child node with their own compatible and device schema which ends in
'additionalProperties: false' or 'unevaluatedProperties: false' can
mention only the compatible and use here 'additionalProperties: true'.
type: object
additionalProperties: true
properties:
compatible:
const: vendor,sub-device
# 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 unwieldy, 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
else:
# If otherwise the property is not allowed:
properties:
foo-supply: false
# 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. Use 4-space indentation.
- |
node@1000 {
compatible = "vendor,soc4-ip", "vendor,soc1-ip";
reg = <0x1000 0x80>,
<0x3000 0x80>;
reg-names = "core", "aux";
interrupts = <10>;
interrupt-controller;
#interrupt-cells = <2>;
};