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@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

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