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

[Rob Herring <robh@kernel.org>]

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