Re: [PATCH v3 05/15] dt_bindings: mfd: Add ROHM BD71815 PMIC

[Rob Herring]

On Tue, Mar 9, 2021 at 5:51 AM Matti Vaittinen
<matti.vaittinen@xxxxxxxxxxxxxxxxx> wrote:
>
> Hello Rob,
>
> On Mon, 2021-03-08 at 10:39 -0700, Rob Herring wrote:
> > On Mon, 08 Mar 2021 12:40:50 +0200, Matti Vaittinen wrote:
> > > Document DT bindings for ROHM BD71815.
> > >
> > > BD71815 is a single-chip power management IC mainly for battery-
> > > powered
> > > portable devices. The IC integrates 5 bucks, 7 LDOs, a boost driver
> > > for
> > > LED, a battery charger with a Coulomb counter, a real-time clock, a
> > > 32kHz
> > > clock and two general-purpose outputs although only one is
> > > documented by
> > > the data-sheet.
> > >
> > > Signed-off-by: Matti Vaittinen <matti.vaittinen@xxxxxxxxxxxxxxxxx>
> > > Reviewed-by: Rob Herring <robh@xxxxxxxxxx>
> > > ---
> > >  .../bindings/mfd/rohm,bd71815-pmic.yaml       | 201
> > > ++++++++++++++++++
> > >  1 file changed, 201 insertions(+)
> > >  create mode 100644
> > > Documentation/devicetree/bindings/mfd/rohm,bd71815-pmic.yaml
> > >
> >
> > My bot found errors running 'make dt_binding_check' on your patch:
>
> I am sorry to bother but I've spent a while trying to reproduce this.
> For some reason I can't trigger the error from
>
> 'make dt_binding_check' or
> 'make dt_binding_check
> DT_SCHEMA_FILES=Documentation/devicetree/bindings/mfd/rohm,bd71815-
> pmic.yaml'
>
> even after I ran
>
> 'pip3 install dtschema --upgrade --user'.
>
> I should also have yamllint installed.
>
> >
> > yamllint warnings/errors:
> >
> > dtschema/dtc warnings/errors:
> > Unknown file referenced: [Errno 2] No such file or directory:
> > '/usr/local/lib/python3.8/dist-
> > packages/dtschema/schemas/regulator/rohm,bd71815-regulator.yaml'
>
> This bothers me slightly. The patch 04/15 should bring-in the
> rohm,bd71815-regulator.yaml. Does this error indicate that file is
> missing or is my $ref somehow invalid?

Then it's simply a false positive. I usually check these and try to
only send the email if the dependency is not in the series so the
dependency is clear. It's a balance of replying quickly and my time
reviewing the errors.

> *** opinion follows - not sure if it just me but... ***
>
> I know I should probably keep my mouth shut but... I am more and more
> thinking that the yaml bindings are yet another 'excessive unit-test'
> type solution. Tooling which should "force doing things correctly" is
> eventually hindering development and causing the end result being sub-
> optimal.

It's about validating DTS files actually do what the bindings say.
It's pretty clear that the free form text bindings left a lot of
things ambiguous.

How would you propose we can check every property in a DTS file has a
definition (minimally of it's type)? Freeform text can simply never do
that.

> I mean that creating binding docs takes way too much time from someone
> like me who is "yaml-illiterate". And when I eventually get yaml done -
> the end result is far less descriptive for human eyes than the "good
> old" free-text format would've been. I know one can add comments - but
> I don't see much of them in the binding docs...

Because people do the minimum? The only comments/description I object
to are duplicating generic descriptions of common properties.

There's certainly lots of things we could do. There are tools which
generate pretty docs out of json-schema. Not sure how useful they
would be OOTB. But I simply don't have the bandwidth to look into
them. I can barely keep up with reviews...

Rob