From patchwork Thu Oct 17 19:49:16 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Rob Herring \(Arm\)" X-Patchwork-Id: 176739 Delivered-To: patch@linaro.org Received: by 2002:a92:7e96:0:0:0:0:0 with SMTP id q22csp1403945ill; Thu, 17 Oct 2019 12:49:22 -0700 (PDT) X-Google-Smtp-Source: APXvYqxA6hd4TUiiCODh5JNcLvnbRBJhvoj6T/UXGfNuIHDyrz03Detj3MK72aeq5oRj6fuPbMhv X-Received: by 2002:a05:6402:698:: with SMTP id f24mr5735556edy.172.1571341762826; Thu, 17 Oct 2019 12:49:22 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1571341762; cv=none; d=google.com; s=arc-20160816; b=Jz4E0Nts3iCCUgR521h3+2QODa5KrCOxFifN+eXJcsHII/MAvr5KK3D2LeFfjCZCV7 gumhnZ6Jq2Yww/N+jUBy4BltoLApq/mqeM39+ke9Gza5uq+8W3BnQXa/o91AzOBzZGtE 7vyBRFUGg+0bc6CczBpyHi2kbWZOvDq899wze2dnSuQIfzi5a1a/+v0YtQLOhW4eifD4 zZgxjjE7D/fcWJtt2KAYYUx0nuKsY842GNqgdyGHTG4V1oqFuPD9BDh5b9fMM2aKDY+e 1n9wsX9KqAGMnOhpdybTRY89tTJg2cPnSdCuhfV26KYYYLeKBx0W0+FedGGGHAf1XkuS OTsQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :message-id:date:subject:cc:to:from; bh=rKf+TvXQTdvhCSr97ET7nrM7ndk5bzLwGtaQj1lzb7w=; b=Y4TrAZjfJtTD5AkGl0/ejzv+Z1Xy/Brw3iSJCLPFhW7fpQNIsz3mZ7/chYVX3/mp9S G7Wx9VtX/xzT0jjb53K4iSlGGkvcM/T4oJyo0sH3aHJ8g5usvbpXpSYWFofbPY63gczj yw656RPnsEMQvYwx3SIVMsJ0pfM7CgbQHOcZXHd/8hgNY4zsubRkC1G8GIcd+nD1jENt 8Y47HaPuzmMiOZQWTQXwU18j+Mwyk+Rr5qr872iN13lV+PlWwmZNHT94i2y6NRzTV/70 2Z6YPBnsPnaHWHB8h35gISs0tKEMWlhUs/LWHBMvvK9d/tPoMVD/k1huIfqYm/Laujbf zeLA== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of devicetree-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=devicetree-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id wq10si1955224ejb.423.2019.10.17.12.49.22; Thu, 17 Oct 2019 12:49:22 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of devicetree-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 devicetree-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=devicetree-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2394690AbfJQTtW (ORCPT + 8 others); Thu, 17 Oct 2019 15:49:22 -0400 Received: from mail-ot1-f51.google.com ([209.85.210.51]:37156 "EHLO mail-ot1-f51.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2389032AbfJQTtV (ORCPT ); Thu, 17 Oct 2019 15:49:21 -0400 Received: by mail-ot1-f51.google.com with SMTP id k32so2968177otc.4; Thu, 17 Oct 2019 12:49:20 -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:mime-version :content-transfer-encoding; bh=rKf+TvXQTdvhCSr97ET7nrM7ndk5bzLwGtaQj1lzb7w=; b=cVc4Ivqb5Ui6FPtR8JVxo1PM8nY6Ux0ToP0uZW4lVOThMBn1ciVr6FFsDSAVnJ2atk d8Mk67ao5Os75tzTKbb7tgRG5lea+0q2xQiJRQD1kakcW5fbn7YcbNtD/J6Xx9puu+Lf z5c3NdYEvjPRGPz2PD/PKzoUC8TXoejFB709ZKbA/N5ryXz5ew8khIIwtUdvBl/IdyUJ PiGzcdm3cY8a6FNaJ9t9K41uepmpbmsj3ZXZ41EjxfE6y4qmPT17LuD+TwGQqcmDvYzr SckvZ2u8/jdlWObytwblTLN4BC7nbRmnjIGN0Nn1WC8W24BcqjBHYJR1dcwESeDWl3gd pdyA== X-Gm-Message-State: APjAAAXC9x68S4EozRWSghFf9u596cjcGrOJdjALyDsYZUR6Sjggi+EM SKw6k6u3t7ZmfENGWViXsSoB7F0= X-Received: by 2002:a9d:286:: with SMTP id 6mr4590504otl.192.1571341759884; Thu, 17 Oct 2019 12:49:19 -0700 (PDT) Received: from xps15.herring.priv (24-155-109-49.dyn.grandenetworks.net. [24.155.109.49]) by smtp.googlemail.com with ESMTPSA id i4sm841448oto.43.2019.10.17.12.49.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 17 Oct 2019 12:49:18 -0700 (PDT) From: Rob Herring To: devicetree@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH] dt-bindings: example-schema: Add some additional examples and commentary Date: Thu, 17 Oct 2019 14:49:16 -0500 Message-Id: <20191017194916.10166-1-robh@kernel.org> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Sender: devicetree-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.org Add examples for properties with standard units, child nodes, dependencies, and if/then schema. Also, make some minor updates based on common questions and review issues. Signed-off-by: Rob Herring --- .../devicetree/bindings/example-schema.yaml | 81 +++++++++++++++++-- 1 file changed, 74 insertions(+), 7 deletions(-) -- 2.20.1 diff --git a/Documentation/devicetree/bindings/example-schema.yaml b/Documentation/devicetree/bindings/example-schema.yaml index c43819c2783a..4ddcf709cc3c 100644 --- a/Documentation/devicetree/bindings/example-schema.yaml +++ b/Documentation/devicetree/bindings/example-schema.yaml @@ -1,4 +1,4 @@ -# 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 --- @@ -71,7 +71,7 @@ properties: # 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 @@ -79,7 +79,8 @@ properties: 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: @@ -127,6 +128,14 @@ properties: 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 @@ -137,9 +146,9 @@ properties: - 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: @@ -151,14 +160,72 @@ properties: - 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 ] + + 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";