From patchwork Fri Oct 28 23:37:01 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Krzysztof Kozlowski X-Patchwork-Id: 619697 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7D760FA3741 for ; Fri, 28 Oct 2022 23:37:09 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229681AbiJ1XhI (ORCPT ); Fri, 28 Oct 2022 19:37:08 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:33008 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229635AbiJ1XhH (ORCPT ); Fri, 28 Oct 2022 19:37:07 -0400 Received: from mail-qt1-x82a.google.com (mail-qt1-x82a.google.com [IPv6:2607:f8b0:4864:20::82a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 00C43248CB1 for ; Fri, 28 Oct 2022 16:37:06 -0700 (PDT) Received: by mail-qt1-x82a.google.com with SMTP id r19so4458015qtx.6 for ; Fri, 28 Oct 2022 16:37:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=Qek8CJa1Lf5wEjUCizwM4dNQR7j2cqTQjO+0iv1r63c=; b=hk7vFQaNCWPnjqyN+pYrb5525vC9R4X7XMfyX7/BkSDIU5Tm3r/0v0+TWdK46WXvCl UY9Gm0ZlDLJtz3sF+mnLQNoELTfwY0ygkgYMVJioK4wjpvwXaT9IB4/yYR7WrtR4St+r 2czE5TuDN0hWLaY6gZIvsywcxQAP3XfW9pH+0/+S6VZAaOPHu8MvLwidnj9dM+zuplfb uCEBNT4Nn6I9a9bywLgOZd2hTEVHPdLWvI5zwc4VCUfc9amEXsrHX2KUAqtjSxiN0sGw YoU+iu8Q13rzOnei8nCEQTCZn8hNKCuU3sCzbIIF4qMpnxIBmqC7+kPZCcJ79NovaIHU ioHQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=Qek8CJa1Lf5wEjUCizwM4dNQR7j2cqTQjO+0iv1r63c=; b=2CiX8MralDTOAcWwOmoYHeDKW2vmmMSV+MmEAMT8zZ0LINwiS74S1km3ZZ1keKxUYS fbDCpi759+HdfrsacKhamMiz6srxpUZB5/ZtaHppfPFbB5anNRqy0TLi2++zZ7kBgjtP vj1rFb0ka2iuQ8j/nBv+PK/TZ0h0umMQefXhEmes3hwRYBfezUIGmGPNBQD1ZHKTCr+F VyFZ03OIaLFkNFLIrZINiL/Cx1FS9T3a7a+y/ey0ZjA6xpc175Qu18Ka+jQgBCBA6KaP MwH2r5jMscaA5bGkxD3is6/PGJr9Cz4AWYaYd22PPgxONWxEoj5mXJjPvhhdMSZa9bsy IWIQ== X-Gm-Message-State: ACrzQf1qnEXtb7fgh0QhSnokhHqmhwDZOAjHS2Kr7HmLvFMnuw5UiYSg VUex48Hq4F+F9f2BmNtKIqSwbIr7UXYPFg== X-Google-Smtp-Source: AMsMyM4oGOVw8wPLrUx3Hh65mu5pC5F3uf+DHCFGbjcpaH8B5SW6WXAiEl3L2y3fsnOR9cr/2TIm9A== X-Received: by 2002:a05:622a:284:b0:39c:cbec:e1f0 with SMTP id z4-20020a05622a028400b0039ccbece1f0mr1746595qtw.451.1667000226142; Fri, 28 Oct 2022 16:37:06 -0700 (PDT) Received: from krzk-bin.. ([64.57.193.93]) by smtp.gmail.com with ESMTPSA id c23-20020a05620a269700b006f84ee3a4f3sm26580qkp.48.2022.10.28.16.37.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 28 Oct 2022 16:37:05 -0700 (PDT) From: Krzysztof Kozlowski To: Rob Herring , Krzysztof Kozlowski , Matthias Brugger , devicetree@vger.kernel.org, linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-mediatek@lists.infradead.org Cc: Krzysztof Kozlowski Subject: [PATCH] dt-bindings: examples: add a list of templates and solutions Date: Fri, 28 Oct 2022 19:37:01 -0400 Message-Id: <20221028233701.572280-1-krzysztof.kozlowski@linaro.org> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.org It is useful to start from existing bindings when writing new ones, especially when one does not know that much DT schema. However we have several bindings which are not the best examples, so people tend to copy their issues into new bindings. Beginners also might not know how to achieve some more complex solutions in DT schema, e.g. how one of two properties should be required by the bindings. Some of such solutions are already in example-schema.yaml, but several other are missing. Add reference with such re-usable design-patterns. Signed-off-by: Krzysztof Kozlowski --- .../devicetree/bindings/examples.rst | 63 +++++++++++++++++++ Documentation/devicetree/bindings/index.rst | 1 + 2 files changed, 64 insertions(+) create mode 100644 Documentation/devicetree/bindings/examples.rst diff --git a/Documentation/devicetree/bindings/examples.rst b/Documentation/devicetree/bindings/examples.rst new file mode 100644 index 000000000000..710eea81d8b7 --- /dev/null +++ b/Documentation/devicetree/bindings/examples.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Examples of Devicetree Bindings to use a base +============================================= + +Following Devicetree Bindings in DT Schema are a known good starting point when +writing new bindings: + +1. Simple SPI device: + Documentation/devicetree/bindings/iio/adc/maxim,max11205.yaml + +2. PMIC (MFD) with several sub-devices: + Documentation/devicetree/bindings/mfd/mediatek,mt6370.yaml + +3. Battery charger (power supply): + Documentation/devicetree/bindings/power/supply/bq256xx.yaml + (but use vendor prefix in filename) + +4. Clock controller for several devices with different clock inputs: + Documentation/devicetree/bindings/clock/qcom,mmcc.yaml + +5. GPIO controller: + Documentation/devicetree/bindings/gpio/qcom,wcd934x-gpio.yaml + + +Re-usable design patterns when writing your own bindings +======================================================== + +Following bindings show how to use common pattern of writing bindings: + +1. Property required and present only for one variant. Property cannot appear + on other variants: + Documentation/devicetree/bindings/example-schema.yaml + Line: 212 + +2. Excluding properties, but none are required: + Documentation/devicetree/bindings/mfd/samsung,s5m8767.yaml + Line: 155 + +3. Excluding required properties, but one is required: + Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml + Line: 91 + +4. Array with numbers (items) from given range - min/max: + Documentation/devicetree/bindings/arm/l2c2x0.yaml + Line: 74 + +5. Array with numbers (items) from given range - enum: + Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml + Line: 101 + +6. Uint32 matrix, variable length of two-items: + Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml + Line: 278 + +7. Phandle to syscon with offset: + Documentation/devicetree/bindings/soc/samsung/exynos-usi.yaml + Line: 42 + +8. Variable length of array (e.g. clocks and clock-names) but narrowed to + specific variant: + Documentation/devicetree/bindings/clock/qcom,mmcc.yaml + Lines: 33 and 71 diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst index d9002a3a0abb..fb8fab7217af 100644 --- a/Documentation/devicetree/bindings/index.rst +++ b/Documentation/devicetree/bindings/index.rst @@ -4,6 +4,7 @@ :maxdepth: 1 ABI + examples writing-bindings writing-schema submitting-patches