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

[Rob Herring <robh@kernel.org>]

On Fri, Oct 28, 2022 at 07:37:01PM -0400, Krzysztof Kozlowski wrote:
> 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.

My main concern here is what's a good example today is not tomorrow... 


> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.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

It seems like some of these that are just a single property we could add 
to example-schema.yaml.


Also, perhaps a reference to this from writing-schema.rst.

Rob