[alsa-devel] [PATCH v2 3/3] ASoC: da7213: Add bindings documentation for codec driver

[Opensource [Adam Thomson]]

On October 08, 2015 14:16, Rob Herring wrote:

> >> > +- dlg,micbias1-lvl : Voltage (mV) for Mic Bias 1
> >> > +       [<1600>, <2200>, <2500>, <3000>]
> >> > +- dlg,micbias2-lvl : Voltage (mV) for Mic Bias 2
> >> > +       [<1600>, <2200>, <2500>, <3000>]
> >>
> >> Please append the units (-microvolt).
> >
> > Given that a user needs to read the bindings document to understand what is
> > available, and what they're for, this seems a little unnecessary.
> 
> You may think so, but it is standard practice.
 
I can find a number of situations in the kernel, where this just isn't followed,
for device specific bindings. What percentage have to follow this for it to be
'standard'? Is this documented somewhere so it's clear for those writing
drivers which need to use DT bindings? I had a quick look and couldn't find
anything on this.

> >>
> >> > +- dlg,dmic-clkrate : DMIC clock frequency (MHz).
> >> > +       [<1500000>, <3000000>]
> >>
> >> So 1.5GHz or 3GHz?
> >>
> >> Add units (-hz).
> >
> > Agreed, the description of MHz is misleading so will update to Hz. Thanks.
> > Again though, I don't see what the suffix gives you, and would prefer to leave
> > the binding as is.
> 
> It tells someone reading the dts what the units are without having to
> find the documentation and helps prevent people using properties with
> differing units.

For a lot of device specific bindings, you will need to read the associated
documentation, and possibly the datasheet, to understand what it's for, and what
values are valid. I don't see this suffix really saving you any time. For
standard frameworks ok, but here it seems overkill.