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

[Krzysztof Kozlowski]

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