[v2,3/3] ASoC: da7213: Add bindings documentation for codec driver

Signed-off-by: Adam Thomson <Adam.Thomson.Opensource@diasemi.com>
---
 Documentation/devicetree/bindings/sound/da7213.txt | 41 ++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/sound/da7213.txt

--
1.9.3

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

On Wed, Oct 7, 2015 at 8:27 AM, Adam Thomson
<Adam.Thomson.Opensource@diasemi.com> wrote:
> Signed-off-by: Adam Thomson <Adam.Thomson.Opensource@diasemi.com>
> ---
>  Documentation/devicetree/bindings/sound/da7213.txt | 41 ++++++++++++++++++++++
>  1 file changed, 41 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/sound/da7213.txt
>
> diff --git a/Documentation/devicetree/bindings/sound/da7213.txt b/Documentation/devicetree/bindings/sound/da7213.txt
> new file mode 100644
> index 0000000..7280e82
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/sound/da7213.txt
> @@ -0,0 +1,41 @@
> +Dialog Semiconductor DA7213 Audio Codec bindings
> +
> +======
> +
> +Required properties:
> +- compatible : Should be "dlg,da7213"
> +- reg: Specifies the I2C slave address
> +
> +Optional properties:
> +- clocks : phandle and clock specifier for codec MCLK.
> +- clock-names : Clock name string for 'clocks' attribute, should be "mclk".
> +
> +- 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).

> +- dlg,dmic-data-sel : DMIC channel select based on clock edge.
> +       ["lrise_rfall", "lfall_rrise"]
> +- dlg,dmic-samplephase : When to sample audio from DMIC.
> +       ["on_clkedge", "between_clkedge"]

How about boolean for these two.

> +- dlg,dmic-clkrate : DMIC clock frequency (MHz).
> +       [<1500000>, <3000000>]

So 1.5GHz or 3GHz?

Add units (-hz).

> +
> +======
> +
> +Example:
> +
> +       codec_i2c: da7213@1a {
> +               compatible = "dlg,da7213";
> +               reg = <0x1a>;
> +
> +               clocks = <&clks 201>;
> +               clock-names = "mclk";
> +
> +               dlg,micbias1-lvl = <2500>;
> +               dlg,micbias2-lvl = <2500>;
> +
> +               dlg,dmic-data-sel = "lrise_rfall";
> +               dlg,dmic-samplephase = "between_clkedge";
> +               dlg,dmic-clkrate = <3000000>;
> +       };
> --
> 1.9.3
>
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

On Thu, Oct 8, 2015 at 3:42 AM, Opensource [Adam Thomson]
<Adam.Thomson.Opensource@diasemi.com> wrote:
> On October 07, 2015 17:22, 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.

>>
>> > +- dlg,dmic-data-sel : DMIC channel select based on clock edge.
>> > +       ["lrise_rfall", "lfall_rrise"]
>> > +- dlg,dmic-samplephase : When to sample audio from DMIC.
>> > +       ["on_clkedge", "between_clkedge"]
>>
>> How about boolean for these two.
>
> Wanted these to be explicit, hence not choosing boolean. Would prefer to keep
> them as is.
>
>>
>> > +- 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.

Rob
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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.