[RFC] dt-bindings: add a jsonschema binding example

Message ID 20180418222905.10414-1-robh@kernel.org
State New
Headers show
Series
  • [RFC] dt-bindings: add a jsonschema binding example
Related show

Commit Message

Rob Herring April 18, 2018, 10:29 p.m.
The current DT binding documentation format of freeform text is painful
to write, review, validate and maintain.

This is just an example of what a binding in the schema format looks
like. It's using jsonschema vocabulary in a YAML encoded document. Using
jsonschema gives us access to existing tooling. A YAML encoding gives us
something easy to edit.

This example is just the tip of the iceberg, but it the part most
developers writing bindings will interact with. Backing all this up
are meta-schema (to validate the binding schemas), some DT core schema,
YAML encoded DT output with dtc, and a small number of python scripts to
run validation. The gory details including how to run end-to-end
validation can be found here:

https://www.spinics.net/lists/devicetree-spec/msg00649.html

Signed-off-by: Rob Herring <robh@kernel.org>

---
Cc list,
You all review and/or write lots of binding documents. I'd like some feedback
on the format.

Thanks,
Rob

 .../devicetree/bindings/example-schema.yaml        | 149 +++++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/example-schema.yaml

--
2.14.1

Comments

Mark Brown April 20, 2018, 4:59 p.m. | #1
On Wed, Apr 18, 2018 at 05:29:05PM -0500, Rob Herring wrote:
> The current DT binding documentation format of freeform text is painful

> to write, review, validate and maintain.

> 

> This is just an example of what a binding in the schema format looks

> like. It's using jsonschema vocabulary in a YAML encoded document. Using

> jsonschema gives us access to existing tooling. A YAML encoding gives us

> something easy to edit.


It'd be useful to see some examples of how things like including by
reference other schema work.  It feels like something we should be able
to use more in a schema based thing but perhaps that's not viable with
realistic tooling.  In general this looks OK, especially with all the
meta comments about the language stripped out.

> +    description: |

> +      A variable number of interrupts warrants a description of what conditions


Like Stephen said the | looks odd.

> +  interrupt-names:

> +    # minItems must be specified here because the default would be 2

> +    minItems: 1

> +    items:

> +      - const: "tx irq"

> +      - const: "rx irq"


Any way to relate this to the interrupts property in the schema
language (eg, must have the less or equal number of elements)?

> +  # Property names starting with '#' must be quoted


That's awkward :/  Perhaps just by convention quote all property names
for simplicity?
Grant Likely April 23, 2018, 2:49 p.m. | #2
On 23/04/2018 15:38, Rob Herring wrote:
> On Mon, Apr 23, 2018 at 9:01 AM, Grant Likely <grant.likely@arm.com> wrote:

>> On 21/04/2018 00:41, Stephen Boyd wrote:

>>>

>>> Quoting Rob Herring (2018-04-20 11:15:04)

>>>>

>>>> On Fri, Apr 20, 2018 at 11:47 AM, Stephen Boyd <sboyd@kernel.org> wrote:

>>>>>

>>>>> Quoting Rob Herring (2018-04-18 15:29:05)

>>>>>>

>>>>>> diff --git a/Documentation/devicetree/bindings/example-schema.yaml

>>>>>> b/Documentation/devicetree/bindings/example-schema.yaml

>>>>>> new file mode 100644

>>>>>> index 000000000000..fe0a3bd1668e

>>>>>> --- /dev/null

>>>>>> +++ b/Documentation/devicetree/bindings/example-schema.yaml

>>

>> [...]

>>>>>>

>>>>>> +  interrupts:

>>>>>> +    # Either 1 or 2 interrupts can be present

>>>>>> +    minItems: 1

>>>>>> +    maxItems: 2

>>>>>> +    items:

>>>>>> +      - description: tx or combined interrupt

>>>>>> +      - description: rx interrupt

>>>>>> +

>>>>>> +    description: |

>>>>>

>>>>>

>>>>> The '|' is needed to make yaml happy?

>>>>

>>>>

>>>> Yes, this is simply how you do literal text blocks in yaml.

>>>>

>>>> We don't really need for this one really, but for the top-level

>>>> 'description' we do. The long term intent is 'description' would be

>>>> written in sphinx/rst and can be extracted into the DT spec (for

>>>> common bindings). Grant has experimented with that some.

>>>

>>>

>>> Ok. That sounds cool. Then we could embed links to datasheets and SVGs

>>> too.

>>

>>

>> I'd like it if we can define the description text blocks to be

>> reStructeredText markup. That makes it even easier to integrate with the

>> specification documentation.

>

> I think that's going to require thinking about how each binding is

> integrated into the spec. We're only talking about common bindings I

> presume, but still we have no model defined. For example, with

> properties, I'd assume we'd want to generate a table of properties and

> we wouldn't want the property descriptions in rST because the

> description becomes just a cell in the table. So we need some sort of

> template.

>

> Also, how do we validate that description contains valid rST? No point

> requiring it until we can validate it.


Indeed. Part of that was me thinking outloud. Need to actually get it
working before adding constraints.

g.
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

Patch

diff --git a/Documentation/devicetree/bindings/example-schema.yaml b/Documentation/devicetree/bindings/example-schema.yaml
new file mode 100644
index 000000000000..fe0a3bd1668e
--- /dev/null
+++ b/Documentation/devicetree/bindings/example-schema.yaml
@@ -0,0 +1,149 @@ 
+# SPDX-License-Identifier: 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 idenifier based on the filename
+$id: "http://devicetree.org/schemas/example-schema.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+# Only 1 version supported for now
+version: 1
+
+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.
+
+  The end of the description is marked by indentation less than the first line
+  in the description.
+
+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.
+
+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 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 is a string array
+    items:
+      - const: core
+      - const: aux
+
+  clocks:
+    # Only a single entry, so just need to set the max number of items.
+    maxItems: 1
+
+  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.
+
+  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: {}
+    # 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.
+
+  vendor,int-property:
+    description: Vendor specific properties must have a description
+    type: integer # A type is also required
+    enum: [2, 4, 6, 8, 10]
+
+  vendor,bool-property:
+    description: Vendor specific properties must have a description
+    type: boolean
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - interrupt-controller
+
+examples:
+  - |
+    /{
+          compatible = "vendor,soc4-ip", "vendor,soc1-ip";
+          reg = <0x1000 0x80>,
+                <0x3000 0x80>;
+          reg-names = "core", "aux";
+          interrupts = <10>;
+          interrupt-controller;
+    };