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

["Vaittinen, Matti" <Matti.Vaittinen@fi.rohmeurope.com>]

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@fi.rohmeurope.com> 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@fi.rohmeurope.com> 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. Actyually, I think that writing-bindings.txt
could be combined with writing-schema.rst - they are about the same
thing, right?

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

> BTW, what you will also need is to reference the common schema:
> 
> "^BUCK[1-7]$":
>   type: object
>   allOf:
>     - $ref: regulator.yaml#
>   properties:
>    rohm,dvs-runlvl-ctrl:
>      type: boolean
>      description: ...
>    ...

Thanks for the pointers ;) I just submitted the RFC v3 :)

Br,
	Matti Vaittinen