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

On 01/11/2022 09:07, Rob Herring wrote:
> 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... 

Yes, I agree. The problem I want to solve is some folks copy-paste some
existing schema as starting point and then are surprised when receive
basic style feedback.

Of course the optimal solution would be to make all schemas in same
(proper) style, but this is going take some time...

How to solve this problem other way? I don't know.

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

I am afraid the example-schema will grow too big for folks to look into.
It's already quite complicated, with explanations of the dtschema
behavior itself.

How about then RST file with small code snippets?

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

I can do this as well.

The problem with my approach above (and adding these to writing-schema)
is that examples above can change, lines can be inadequate.

Best regards,
Krzysztof

On Fri, Nov 04, 2022 at 10:52:22AM -0400, Krzysztof Kozlowski wrote:
> On 01/11/2022 09:07, Rob Herring wrote:
> > 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... 
> 
> Yes, I agree. The problem I want to solve is some folks copy-paste some
> existing schema as starting point and then are surprised when receive
> basic style feedback.
> 
> Of course the optimal solution would be to make all schemas in same
> (proper) style, but this is going take some time...
> 
> How to solve this problem other way? I don't know.

shrug


> >> 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.
> 
> I am afraid the example-schema will grow too big for folks to look into.
> It's already quite complicated, with explanations of the dtschema
> behavior itself.

How about splitting up the top-level descriptions and property examples?

> How about then RST file with small code snippets?

Then they don't validate.

> 
> > Also, perhaps a reference to this from writing-schema.rst.
> 
> I can do this as well.
> 
> The problem with my approach above (and adding these to writing-schema)
> is that examples above can change, lines can be inadequate.

I just meant a link in writing-schema.rst to this doc. We already have 
that for example-schema.yaml.

Rob

On 04/11/2022 22:47, Rob Herring wrote:
>>>> +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.
>>
>> I am afraid the example-schema will grow too big for folks to look into.
>> It's already quite complicated, with explanations of the dtschema
>> behavior itself.
> 
> How about splitting up the top-level descriptions and property examples?

You mean splitting up to separate YAML files? I guess this could work
and still be concise - few examples showing different concepts.

> 
>> How about then RST file with small code snippets?
> 
> Then they don't validate.
> 
>>
>>> Also, perhaps a reference to this from writing-schema.rst.
>>
>> I can do this as well.
>>
>> The problem with my approach above (and adding these to writing-schema)
>> is that examples above can change, lines can be inadequate.
> 
> I just meant a link in writing-schema.rst to this doc. We already have 
> that for example-schema.yaml.


Best regards,
Krzysztof