On Thu, Sep 26, 2024 at 05:37:18PM -0500, Rob Herring wrote: > On Thu, Sep 26, 2024 at 03:42:18PM +0200, Krzysztof Kozlowski wrote: > > Same Devicetree binding can be expressed multiple ways thus no wonder > > we have multiple variants of similar concept. All such code could be > > cleaned up, but even then new contributor might not be able to find > > good, existing binding solving their case. > > > > Add subdirectory with two Devicetree schema examples (GPIO hog and > > variable lists like clocks), hoping it will grow with reference-designs. > > All these bindings use valid compatibles, although with "test" vendor > > prefix, so they will be validated by DT schema. > > > > Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@xxxxxxxxxx> > > > > --- > > > > If approach is accepted, I will come with more ideas, as commented > > during LPC DT BoF to creates examples based on review. > > > > Cc: Nishanth Menon <nm@xxxxxx> > > Cc: Bjorn Andersson <andersson@xxxxxxxxxx> > > --- > > .../devicetree/bindings/example-schema.yaml | 2 + > > .../examples/gpio-controller-and-hogs.yaml | 72 ++++++++++++ > > .../multiple-variants-and-variable-lists.yaml | 110 ++++++++++++++++++ > > .../devicetree/bindings/writing-schema.rst | 6 +- > > 4 files changed, 189 insertions(+), 1 deletion(-) > > create mode 100644 Documentation/devicetree/bindings/examples/gpio-controller-and-hogs.yaml > > create mode 100644 Documentation/devicetree/bindings/examples/multiple-variants-and-variable-lists.yaml > > > > diff --git a/Documentation/devicetree/bindings/example-schema.yaml b/Documentation/devicetree/bindings/example-schema.yaml > > index a41f9b9a196b..0aece1823fde 100644 > > --- a/Documentation/devicetree/bindings/example-schema.yaml > > +++ b/Documentation/devicetree/bindings/example-schema.yaml > > @@ -25,6 +25,8 @@ description: | > > indentation less than the first line of the literal block. Lines also cannot > > begin with a tab character. > > > > + See also examples/ subdirectory for more detailed code snippets. > > + > > select: false > > # 'select' is a schema applied to a DT node to determine if this binding > > # schema should be applied to the node. It is optional and by default the > > diff --git a/Documentation/devicetree/bindings/examples/gpio-controller-and-hogs.yaml b/Documentation/devicetree/bindings/examples/gpio-controller-and-hogs.yaml > > new file mode 100644 > > index 000000000000..597a847daa12 > > --- /dev/null > > +++ b/Documentation/devicetree/bindings/examples/gpio-controller-and-hogs.yaml > > @@ -0,0 +1,72 @@ > > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) > > +%YAML 1.2 > > +--- > > +$id: http://devicetree.org/schemas/examples/gpio-controller-and-hogs.yaml# > > +$schema: http://devicetree.org/meta-schemas/core.yaml# > > + > > +title: An Example GPIO Controller with Hogs > > + > > +maintainers: > > + - Rob Herring <robh@xxxxxxxxxx> > > + - Krzysztof Kozlowski <krzk@xxxxxxxxxx> > > + - Conor Dooley <conor@xxxxxxxxxx> > > + > > +properties: > > + compatible: > > + const: test,gpio-controller-and-hogs > > + > > + gpio-controller: true > > + > > + "#gpio-cells": > > + const: 2 > > + > > + gpio-line-names: > > + minItems: 1 > > + maxItems: 32 > > + > > + gpio-ranges: > > + minItems: 1 > > + maxItems: 16 > > + > > + # Not every GPIO controller is an interrupt-controller > > + interrupt-controller: true > > + > > + "#interrupt-cells": > > + const: 2 > > + > > +patternProperties: > > + "-hog(-[0-9]+)?$": > > + type: object > > + required: > > + - gpio-hog > > The best way to ensure this is done right is eliminate the need rather > than adding examples to be ignored. > > I think we need to make gpio provider bindings reference gpio.yaml and > then handle hogs there. Generally, the pattern is that providers which > just list properties don't have a $ref to the provider schema and are > always applied. Schemas that have child nodes like bus schemas are > referenced by the specific controller schemas. GPIO started out as the > former, but the addition of hogs made it more like the latter. That of > course means that every GPIO provider can have hogs, but I think that's > the right answer even though I'd really prefer no hogs at all. > > Always applying schemas like gpio.yaml has some benefits over relying > on applying it via $ref, but that's diminished once everything has a > schema. Of course, we can do both at the expense of applying the schema > twice. Ack, I will take a look at applying gpio.yaml to all controllers. At least looking at Linux, all GPIO chips and pinctrl with GPIO chip code go via generic of_gpiochip_add() which later goes via children for_each_available_child_of_node_scoped() to add hogs, so adding hogs to each schema seems matching reality. Best regards, Krzysztof
