FreeBSD/Linux Kernel Cross Reference
sys/contrib/device-tree/Bindings/example-schema.yaml

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

Cache object: 7d551709ac2de2cda7c025071fbf2718