Documentation/devicetree/bindings/example-schema.yaml - linux - Git at Google

 # 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
     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 ]

   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;
     };
	# 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
	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 ]

	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;
	};