Re: [RFC PATCH v2 02/13] dt-bindings: mfd: Document ROHM BD71828 bindings

[Rob Herring <robh@xxxxxxxxxx>]

On Fri, Nov 1, 2019 at 7:52 AM Vaittinen, Matti
<Matti.Vaittinen@xxxxxxxxxxxxxxxxx> wrote:
>
>
> On Thu, 2019-10-31 at 12:50 -0500, Rob Herring wrote:
> > On Thu, Oct 31, 2019 at 7:54 AM Vaittinen, Matti
> > <Matti.Vaittinen@xxxxxxxxxxxxxxxxx> wrote:
> > >
> > > On Wed, 2019-10-30 at 14:22 -0500, Rob Herring wrote:
> > > > On Wed, Oct 30, 2019 at 3:27 AM Vaittinen, Matti
> > > > <Matti.Vaittinen@xxxxxxxxxxxxxxxxx> wrote:
> > > > > On Tue, 2019-10-29 at 14:34 -0500, Rob Herring wrote:
> > > > > > On Fri, Oct 25, 2019 at 05:49:17AM +0000, Vaittinen, Matti
> > > ...which brings me here. I looked at the
> > > Documentation/devicetree/bindings folder and did read the 'writing-
> > > bindings.txt' and 'submitting-patches.txt' from there. Then I also
> > > checked the Documentation/devicetree/usage-model.txt None of which
> > > helped me out. I did also open the 'writing-schema.rst' but I
> > > didn't
> > > read it carefully enough. Probably because I thought after reading
> > > the
> > > opening chapter that this described how to do actual dts in yaml.
> >
> > Things are a bit scattered around I'll admit. I feel like we need a
> > 'start here', but the challenge is people have different starting
> > points.
>
> cross-referencing? =)
>
> I guess that if yaml is what is expected to be used as patch format,
> then we should probably mention this in submitting-patches.txt and
> writing-bindings.txt.

I've actually added that to submitting-patches.txt already and
checkpatch.pl now warns for non-schema bindings. Both are pending for
5.5.

> Actyually, I think that writing-bindings.txt
> could be combined with writing-schema.rst - they are about the same
> thing, right?

Not really. writing-bindings.txt is about how to design bindings. It's
the DO's and DON'Ts that I give in review comments over and over and
over. Mostly an attempt to ensure I'm saying things that are
documented somewhere. Probably need to come up with better names, but
naming is hard(TM).


> > > > There is some notion to convert the DT spec to schema and then
> > > > generate the spec from the schema. Take properties, their type,
> > > > and
> > > > descriptions and put that back into tables for example. Would
> > > > love to
> > > > have someone work on that. :)
> > >
> > > I am glad to hear you have developed / are developing such tooling.
> >
> > TBC, I have not and am not. It's just an idea. There's been nothing
> > done beyond experimenting if rST could be embedded into yaml.
> >
> > > I
> > > really appreciate it. What comes to giving a helping hand - I'd
> > > better
> > > to stick the simple C drivers for now ;) But if I ever get the
> > > feeling
> > > that I don't know what to do I'll keep this in mind :] Let me do
> > > some
> > > calculus... Only 11 years and my youngest son will probably leave
> > > our
> > > house - do you think 2030 is a bit too late? Just let me know if
> > > this
> > > is still relevant then - and I'll buy you a beer or write a tool
> > > (of
> > > some kind) xD
> >
> > I've scheduled you in for 2030. :)
>
> Fine. Let's see if it is a beer or a tool then :]
>
> > > Meanwhile... I have tried to convert the BD71828 DT doc from the
> > > RFC
> > > patch to yaml - and I am having hard time. Especially with the
> > > regulators node - which I would like to place in
> > > Documentation/devicetree/bindings/regulator/rohm,bd71828-
> > > regulator.yaml
> > >
> > > My problem is the
> > > regulators {
> > > buck1: BUCK1 {
> > >                     regulator-name = "buck1";
> > >                     regulator-min-microvolt = <500000>;
> > >                     regulator-max-microvolt = <2000000>;
> > >                     regulator-ramp-delay = <2500>;
> > >                     rohm,dvs-runlvl-ctrl;
> > >                     rohm,dvs-runlevel0-voltage = <500000>;
> > >                     rohm,dvs-runlevel1-voltage = <506250>;
> > >                     rohm,dvs-runlevel2-voltage = <512500>;
> > >                     rohm,dvs-runlevel3-voltage = <518750>;
> > >                     regulator-boot-on;
> > >     };
> > >     ...
> > > };
> > > node which only contains BUCKX and LDOX sub-nodes. It has no own
> > > properties.
> > >
> > > From MFD yaml I did try:
> > >
> > >   regulators:
> > >     $ref: ../regulator/rohm,bd71828-regulator.yaml
> > >     description:
> > >       List of child nodes that specify the regulators.
> > >
> > > and in rohm,bd71828-regulator.yaml
> > >
> > > I tried doing:
> > >
> > > patternProperties:
> > >   "^BUCK[1-7]$":
> > >     type: object
> > >     description:
> > >       Properties for single regulator.
> > >     properties:
> > >         ...
> > >
> > > but this fails validation as properties: is not given.
> > >
> > > [mvaittin@localhost linux]$ dt-doc-validate
> > > Documentation/devicetree/bindings/regulator/rohm,bd71828-
> > > regulator.yaml
> > > /home/mvaittin/torvalds/linux/Documentation/devicetree/bindings/reg
> > > ulat
> > > or/rohm,bd71828-regulator.yaml: 'properties' is a required property
> > >
> > > If I try and add:
> > >
> > > properties:
> > >   foo: true
> > >
> > > patternProperties:
> > >     "^BUCK[1-7]$":
> > >       type: object
> > >       description:
> > >         Properties for single regulator.
> > >       properties:
> > >         ...
> >
> > That's a case of needing to adjust the meta-schema (the schema that
> > checks the schemas). It's a bit overly restrictive just to try to
> > contain what's allowed. I've fixed it now. Update dtschema and it
> > should work now.
>
> Thanks. At least the make dt_binding_check passed now. dt-doc-validate
> is not able to locate the regulator.yaml and errors out - but it does
> no longer complain about missing 'properties:'.

Either look at how Kbuild calls dt-doc-validate or just use 'make
dt_binding_check'. (It needs the base path to the schema passed in.)

Rob