From patchwork Wed Apr 18 22:29:05 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Rob Herring X-Patchwork-Id: 133674 Delivered-To: patch@linaro.org Received: by 10.46.66.142 with SMTP id h14csp396492ljf; Wed, 18 Apr 2018 15:29:13 -0700 (PDT) X-Google-Smtp-Source: AIpwx4+UQtVkG836/LLhqMGTdsTZBbX5r1XsEvtYIZtISJDCOJwIWt2XXXylctly8OpiplJVmLFF X-Received: by 10.98.200.152 with SMTP id i24mr3511044pfk.35.1524090553175; Wed, 18 Apr 2018 15:29:13 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1524090553; cv=none; d=google.com; s=arc-20160816; b=CSLwKylKiHpptmdrkE2BrfIEHlLHQaGrS+y/LLsTG0jyLnMupsO7k1QendTY6/LEy/ Enjrbzrg7Ee7oO03iN/AtJtNbSN6x7eRcF2CTYFUKgiuxBmCBrRddat7f2R1n6uILwGB hsKw/0LZSyx3QKqZ62ukafMaO0HdVwYAYaQ71wYNGKJRy1y9qUHHDcx1FM1OVZN/5Fsn RYo5VQ4JB8vsnEY1B/UPQ05TmoW83utfW8AebJMhukfwg0Vk9nb4WKq+26B8FJvbkS95 qiSFkXz6mcTVex3QResK5msKf2fSxBIqhrI+f9sKx4OrFwOsdg0hM9ulMxflwLyFyoVd w+bw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:message-id:date:subject:cc:to:from :arc-authentication-results; bh=DdxWSUpTVxHSo+Q3r8tF8Ay4gQP/jkCkPDs7i0titrE=; b=BZA4Orh8HTbZ0zKzWfu5yp1afnigd/+wDRyKNRi5M5DUViqHqx0uCuowE/edhMgxHk ZOpV62OtuNc4osxJohLOB5gfS8z6sbZsU7iqjMlkJUxCe637pcjPGh5Z9ugTi4zUKRe+ KtIss9qy4axgGZAIDSQJiRbutyZzBGy2WpHVvingJzOeYmeiLastVOyA+VgfqFExpVFD bRKLAyQu8UxUSUgNjBEPddYnR3d4lY7+m58T7vyktbxYTrokz3zb+tLmQUdvwjjT7duV 0WoFs7DDOqfkiqXzTK+Vd3+fWgO79kpAQueyy4Qffwh8NupRGTOkPuOohwTF1ku2NT9J CAgg== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id a15si1878486pfo.358.2018.04.18.15.29.12; Wed, 18 Apr 2018 15:29:13 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752941AbeDRW3J (ORCPT + 29 others); Wed, 18 Apr 2018 18:29:09 -0400 Received: from mail-oi0-f66.google.com ([209.85.218.66]:33536 "EHLO mail-oi0-f66.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752687AbeDRW3I (ORCPT ); Wed, 18 Apr 2018 18:29:08 -0400 Received: by mail-oi0-f66.google.com with SMTP id 126-v6so3096222oig.0; Wed, 18 Apr 2018 15:29:07 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=DdxWSUpTVxHSo+Q3r8tF8Ay4gQP/jkCkPDs7i0titrE=; b=LpAf7AHjE5zPpjlDg4yBYaBcgFT1s0R4erxqnZCrc3v/BQfHydUpQDHBPpJdkH15kV PgFUXJnngBT2oIoR1HAY43hOb9CU4RKFGhsW9ELTrhgG4bSR1tRlF3tFXbgPrbPMOB1v vqs022OIZDiqi+nwCBtGafSTNaWVM8c/lZNs3U5/dPxrpXlpCLBmotFXdJJXX7Gq1SYR BtEGsT9ppMXerE4T/ZxBjHFaUDdKPqz1lSvNsuKijCaHWW53ea7HXYBOqfWmtqF8k9W1 2V8d8e2fDVf0X9mpcSME64w0WSjCfxO+6OWXr8izvEVjPjC0e97R+VIQ+fnqDkeDzAaN P+8A== X-Gm-Message-State: ALQs6tD4GIGrQdCf9meeVgkY6QIDzHIRs4msCYEgtpP0he6hS8b6EO5W m0Tvk4FcYGrVyE4+F8rpCMp0g5o= X-Received: by 2002:aca:aa4c:: with SMTP id t73-v6mr2171864oie.225.1524090547007; Wed, 18 Apr 2018 15:29:07 -0700 (PDT) Received: from xps15.herring.priv (216-188-254-6.dyn.grandenetworks.net. [216.188.254.6]) by smtp.googlemail.com with ESMTPSA id 124-v6sm780160oif.42.2018.04.18.15.29.05 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 18 Apr 2018 15:29:06 -0700 (PDT) From: Rob Herring To: devicetree@vger.kernel.org, devicetree-spec@vger.kernel.org, linux-kernel@vger.kernel.org Cc: grant.likely@arm.com, frowand.list@gmail.com, mark.rutland@arm.com, Geert Uytterhoeven , Linus Walleij , Thierry Reding , Mark Brown , shawnguo@kernel.org, Bjorn Andersson , Arnd Bergmann , Stephen Boyd , Jonathan Cameron Subject: [RFC PATCH] dt-bindings: add a jsonschema binding example Date: Wed, 18 Apr 2018 17:29:05 -0500 Message-Id: <20180418222905.10414-1-robh@kernel.org> X-Mailer: git-send-email 2.14.1 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 --- 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 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 + +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; + };