dt-bindings: example-schema: Add some additional examples and commentary

# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

# Copyright 2018 Linaro Ltd.

%YAML 1.2

---

    # minItems/maxItems equal to 2 is implied

  reg-names:

    # The core schema enforces this is a string array

    # 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

    description: bus clock. A description is only needed for a single item if

      there's something unique to add.

  clock-names:

    items:

    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

    # 'allOf' is the json-schema way of subclassing a schema. Here the base

      - enum: [2, 4, 6, 8, 10]

  vendor,bool-property:

    description: Vendor specific properties must have a description

    # boolean properties is one case where the json-schema 'type' keyword

    # can be used directly

    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:

          - enum: [ foo, bar ]

          - enum: [ baz, boo ]

  vendor,property-in-standard-units-microvolts:

    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.

if:

  properties:

    compatible:

      contains:

        const: vendor,soc2-ip

then:

  required:

    - foo-supply

# 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: ...}]).

additionalProperties: false

examples:

  # Examples are now compiled with dtc

  # 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";