linux-kernel - [PATCH] dt-bindings: examples: add a list of templates and solutions

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-Id: <20221028233701.572280-1-krzysztof.kozlowski@linaro.org>
Date:   Fri, 28 Oct 2022 19:37:01 -0400
From:   Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>
To:     Rob Herring <robh+dt@...nel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@...aro.org>,
        Matthias Brugger <matthias.bgg@...il.com>,
        devicetree@...r.kernel.org, linux-kernel@...r.kernel.org,
        linux-arm-kernel@...ts.infradead.org,
        linux-mediatek@...ts.infradead.org
Cc:     Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>
Subject: [PATCH] dt-bindings: examples: add a list of templates and solutions

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 <krzysztof.kozlowski@...aro.org>
---
 .../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
-- 
2.34.1