Received: by 10.192.165.148 with SMTP id m20csp566609imm; Fri, 20 Apr 2018 11:19:02 -0700 (PDT) X-Google-Smtp-Source: AIpwx499HOyxfoP1W0JwnXVDzPJF5ycSEmUrwBOMeS4hlxGQQp7PD02tDiTtK2MAi4v5FiZMK7yY X-Received: by 10.101.97.130 with SMTP id c2mr9577602pgv.219.1524248342344; Fri, 20 Apr 2018 11:19:02 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1524248342; cv=none; d=google.com; s=arc-20160816; b=YiYT9yZL8lrbKNE4nygbUdVkwOyMjB3LLBZhVuIW/e/gIqjHCgbG1VHGLX6EBKIuAt klgjI6yLT8hD6S4ETbD4bPinhXIdZv3Iv3gXR+M/byRvpiGQW24U5jU7gRLUUEW7+PhV 6+QgHggoK8XKaaTDtJKOxruA3MUzlreOd67sDK11w5ndn1xzomYAcgz0Zzgyg1TbkjFp p+gfxZV7KvS9upDwQcVgkXRIAe6u0QhjvSakJbcywQmm9W4NUgGmRwtJ+EW4ZKTzotSF h+VUg1zDScKvqamvhj3plqo1CSAUCTtrg+sN5xizDcso7d7uPw4GGqknzxAuwYc5T5vS h7uQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:cc:to:subject:message-id:date:from :references:in-reply-to:mime-version:dmarc-filter :arc-authentication-results; bh=N4XmXFOBWIDCd+Qw5ArEElXmryvGX9MfnCUTEHsdHa0=; b=VV8rnIuR32/HmBrfge/cUHpamsLQgnrtiKwPzEzuI6cqemzkekvqZESmV382YqTHu3 172+FWGq1POi6P6VgPSauDhnMWkZhlqih0B42dDgkCOB0FyS76FcDLnU5SZ+VQdiorxq cz/jmxnKvCvzgFNRexB4JDRE0SAR40Ubqf5m/2Ha01So5Yja17Jn/Ao92B6sVZzr7NaO mAaVCMu81bhGAZK0iGFc2yB4t+uQCoXjpUwVDXscr1YqfYN54BQSCminbmgUveYzdyhI uYQbZPRERNEJr2eRwIEiY4/jk/aWTpwc+7AYhn76TP3uwjPcUv5id6TCX++eRWNqFzVf FPGA== 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 f14si5133311pgt.115.2018.04.20.11.18.24; Fri, 20 Apr 2018 11:19:02 -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 S1753626AbeDTSP2 (ORCPT + 99 others); Fri, 20 Apr 2018 14:15:28 -0400 Received: from mail.kernel.org ([198.145.29.99]:41832 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753158AbeDTSP0 (ORCPT ); Fri, 20 Apr 2018 14:15:26 -0400 Received: from mail-qt0-f177.google.com (mail-qt0-f177.google.com [209.85.216.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 97FB9217D3; Fri, 20 Apr 2018 18:15:25 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 97FB9217D3 Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=robh@kernel.org Received: by mail-qt0-f177.google.com with SMTP id f16-v6so7001895qth.0; Fri, 20 Apr 2018 11:15:25 -0700 (PDT) X-Gm-Message-State: ALQs6tDRvlK2JKKwyFrEc3+0M3h6n5hzVR9DOwJ6H+R6GpQzKtfECSjv zbt06Ttw6OJ+ZuiumWQ94uMmeda/QGKkHNFxIA== X-Received: by 2002:ac8:1e18:: with SMTP id n24-v6mr12650840qtl.118.1524248124670; Fri, 20 Apr 2018 11:15:24 -0700 (PDT) MIME-Version: 1.0 Received: by 10.12.163.228 with HTTP; Fri, 20 Apr 2018 11:15:04 -0700 (PDT) In-Reply-To: <152424282214.46528.2511757264045171935@swboyd.mtv.corp.google.com> References: <20180418222905.10414-1-robh@kernel.org> <152424282214.46528.2511757264045171935@swboyd.mtv.corp.google.com> From: Rob Herring Date: Fri, 20 Apr 2018 13:15:04 -0500 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: [RFC PATCH] dt-bindings: add a jsonschema binding example To: Stephen Boyd Cc: devicetree-spec@vger.kernel.org, devicetree@vger.kernel.org, "linux-kernel@vger.kernel.org" , Grant Likely , Frank Rowand , Mark Rutland , Geert Uytterhoeven , Linus Walleij , Thierry Reding , Mark Brown , Shawn Guo , Bjorn Andersson , Arnd Bergmann , Jonathan Cameron Content-Type: text/plain; charset="UTF-8" Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Fri, Apr 20, 2018 at 11:47 AM, Stephen Boyd 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 >> @@ -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. > > Can we get a concrete example here? select: true :) Which is apply to every node. A better one is from the memory node schema ('$nodename' gets added : select: required: ["$nodename"] properties: $nodename: oneOf: - pattern: "^memory@[0-9a-f]*" - const: "memory" # 'memory' only allowed for selecting I expect the vast majority of device bindings will not use select at all and rely on compatible string matching. >> + >> +properties: > [...] >> + >> + 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. >> + 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: {} > > Does '{}' mean nothing to see here? Yes. It's just an empty schema that's always valid. >> + # 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 >> + > > The 'default' field is neat. I look forward to the compiler using the > schema to insert defaults into the dtb if the properties aren't present > in the input file. That wasn't really my intention, but it's what the OS should use if property is not present. But at least for required properties, we could certainly do as you suggest. >> + 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 > > Can the required or optional parts go under each property instead of > having a different section? No, because then it is not json-schema language. > Or does that make the schema parser > difficult to implement? Yes, because then we have to implement a schema parser. > It may also make sense to negate this and > specify only the optional properties, or to require both optional and > required lists to make things more explicit at the cost of some > verbosity. > >> + >> +examples: >> + - | >> + /{ > > Is the first slash required here? No, just leftover from being the root node in the example. Thanks for taking a look. >> + compatible = "vendor,soc4-ip", "vendor,soc1-ip"; >> + reg = <0x1000 0x80>, >> + <0x3000 0x80>; >> + reg-names = "core", "aux"; >> + interrupts = <10>; >> + interrupt-controller; >> + };