[06/10] ASoC: dt-bindings: Document dl_mask property
diff mbox series

Message ID 20190722124833.28757-7-daniel.baluta@nxp.com
State Not Applicable
Headers show
Series
  • Add support for new SAI IP version
Related show

Checks

Context Check Description
snowpatch_ozlabs/checkpatch success total: 0 errors, 0 warnings, 0 checks, 11 lines checked
snowpatch_ozlabs/apply_patch success Successfully applied on branch next (f3365d1a959d5c6527efe3d38276acc9b58e3f3f)

Commit Message

Daniel Baluta July 22, 2019, 12:48 p.m. UTC
SAI supports up to 8 data lines. This property let the user
configure how many data lines should be used per transfer
direction (Tx/Rx).

Signed-off-by: Daniel Baluta <daniel.baluta@nxp.com>
---
 Documentation/devicetree/bindings/sound/fsl-sai.txt | 5 +++++
 1 file changed, 5 insertions(+)

Comments

Lucas Stach July 22, 2019, 12:56 p.m. UTC | #1
Am Montag, den 22.07.2019, 15:48 +0300 schrieb Daniel Baluta:
> SAI supports up to 8 data lines. This property let the user
> configure how many data lines should be used per transfer
> direction (Tx/Rx).
> 
> > Signed-off-by: Daniel Baluta <daniel.baluta@nxp.com>
> ---
>  Documentation/devicetree/bindings/sound/fsl-sai.txt | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt
> index 2e726b983845..59f4d965a5fb 100644
> --- a/Documentation/devicetree/bindings/sound/fsl-sai.txt
> +++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt
> @@ -49,6 +49,11 @@ Optional properties:
>  
> >    - big-endian		: Boolean property, required if all the SAI
> >  			  registers are big-endian rather than little-endian.
> > +  - fsl,dl_mask		: list of two integers (bitmask, first for RX, second
> > +			  for TX) representing enabled datalines. Bit 0
> > +			  represents first data line, bit 1 represents second
> > +			  data line and so on. Data line is enabled if
> > +			  corresponding bit is set to 1.

No underscores in property names, please. Also this should document the
default value used by the driver when the property is absent.

Regards,
Lucas
Nicolin Chen July 24, 2019, 11:13 p.m. UTC | #2
On Mon, Jul 22, 2019 at 03:48:29PM +0300, Daniel Baluta wrote:
> SAI supports up to 8 data lines. This property let the user
> configure how many data lines should be used per transfer
> direction (Tx/Rx).
> 
> Signed-off-by: Daniel Baluta <daniel.baluta@nxp.com>
> ---
>  Documentation/devicetree/bindings/sound/fsl-sai.txt | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt
> index 2e726b983845..59f4d965a5fb 100644
> --- a/Documentation/devicetree/bindings/sound/fsl-sai.txt
> +++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt
> @@ -49,6 +49,11 @@ Optional properties:

> +  - fsl,dl_mask		: list of two integers (bitmask, first for RX, second

Not quite in favor of the naming here; And this patch should
be sent to the devicetree maillist and add DT maintainers --
they would give some good naming advice.

From my point of view, I feel, since data lines are enabled
consecutively, probably it'd be clear just to have something
like "fsl,num-datalines = <2 2>", corresponding to "dl_mask
= <0x3 0x3>". I believe there're examples in the existing DT
bindings, so let's see how others suggest.

> +			  for TX) representing enabled datalines. Bit 0
> +			  represents first data line, bit 1 represents second
> +			  data line and so on. Data line is enabled if
> +			  corresponding bit is set to 1.

Would be better to mention: "as a default use case, if this
property is absent, only the first data line will be enabled
for both TX and RX", since it's an optional property.

And one more extension(?) of it could be what if there's no
data line being physically connected for one direction, for
example "dl_mask = <0x0 0x1>", indicating that SAI enables
one single TX line only, so driver would disable RX feature.
What do you think?
Daniel Baluta July 25, 2019, 6:08 a.m. UTC | #3
On Thu, Jul 25, 2019 at 2:14 AM Nicolin Chen <nicoleotsuka@gmail.com> wrote:
>
> On Mon, Jul 22, 2019 at 03:48:29PM +0300, Daniel Baluta wrote:
> > SAI supports up to 8 data lines. This property let the user
> > configure how many data lines should be used per transfer
> > direction (Tx/Rx).
> >
> > Signed-off-by: Daniel Baluta <daniel.baluta@nxp.com>
> > ---
> >  Documentation/devicetree/bindings/sound/fsl-sai.txt | 5 +++++
> >  1 file changed, 5 insertions(+)
> >
> > diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt
> > index 2e726b983845..59f4d965a5fb 100644
> > --- a/Documentation/devicetree/bindings/sound/fsl-sai.txt
> > +++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt
> > @@ -49,6 +49,11 @@ Optional properties:
>
> > +  - fsl,dl_mask              : list of two integers (bitmask, first for RX, second
>
> Not quite in favor of the naming here; And this patch should
> be sent to the devicetree maillist and add DT maintainers --
> they would give some good naming advice.
>
> From my point of view, I feel, since data lines are enabled
> consecutively, probably it'd be clear just to have something
> like "fsl,num-datalines = <2 2>", corresponding to "dl_mask
> = <0x3 0x3>". I believe there're examples in the existing DT
> bindings, so let's see how others suggest.
>

Your suggestion looks good to me. Anyhow, after reading again the
documentation it seems that datalines are not always required to
be consecutive.

The need to be consecutive only when FIFO combine mode is enabled.
Will fix the documentation in the next version.

Patch
diff mbox series

diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt
index 2e726b983845..59f4d965a5fb 100644
--- a/Documentation/devicetree/bindings/sound/fsl-sai.txt
+++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt
@@ -49,6 +49,11 @@  Optional properties:
 
   - big-endian		: Boolean property, required if all the SAI
 			  registers are big-endian rather than little-endian.
+  - fsl,dl_mask		: list of two integers (bitmask, first for RX, second
+			  for TX) representing enabled datalines. Bit 0
+			  represents first data line, bit 1 represents second
+			  data line and so on. Data line is enabled if
+			  corresponding bit is set to 1.
 
 Optional properties (for mx6ul):