[PATCH] ASoC: docs: add clocking examples for DAI formats

[PATCH] ASoC: docs: add clocking examples for DAI formats

[Peter Rosin]

Provide *our* view of what the rules are for the different DAI formats,
so that we do not have to trust external interpretations for this
crucial bit of interoperability.

Signed-off-by: Peter Rosin <peda@axentia.se>
---
 Documentation/sound/alsa/soc/clocking.txt | 110 +++++++++++++++++++++++++++++-
 1 file changed, 108 insertions(+), 2 deletions(-)

Now, the reason for me writing this is that I once again had to go hunting
the internet to find the rules for these things. And like last time, I
found no definitive source and sometimes strange things as well. So, I don't
know if the above is 100% good, but it is my understanding of the subject.

Please enlighten me on any errors.

Cheers,
Peter

diff --git a/Documentation/sound/alsa/soc/clocking.txt b/Documentation/sound/alsa/soc/clocking.txt
index b1300162e01c..8b498d610e10 100644
--- a/Documentation/sound/alsa/soc/clocking.txt
+++ b/Documentation/sound/alsa/soc/clocking.txt
@@ -47,5 +47,111 @@ rate, number of channels and word size) to save on power.
 It is also desirable to use the codec (if possible) to drive (or master) the
 audio clocks as it usually gives more accurate sample rates than the CPU.
 
-
-
+The below diagrams all have BCLK as the first signal, LRC as the second signal
+and DATA as the third. Below that is an indication about which DATA bits belong
+in what channel.
+
+A "..." marking as DATA indicates that there may be more bits that are not
+shown. Also, all DATA bits marked X may or may not be present. DAI
+transmitters must add them should LRC not match the word size exactly and DAI
+receivers must be prepared to ignore them. DAI transmitters must insert
+zeros for I2S, Left and Right Justified modes, and preferably not drive DATA
+for the DSP modes for these extra X bits.
+
+
+I2S
+ .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
+-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
+---.                               .-------------------------------.
+   '-------------------------------'                               '-----
+---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
+   |   |MSB|   |...|   |LSB| X |...| X |MSB|   |...|   |LSB| X |...| X |
+---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
+       | Left channel                  | Right channel                 |
+
+
+Left Justified (aka MSB)
+ .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
+-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
+   .-------------------------------.                               .-----
+---'                               '-------------------------------'
+---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
+   |MSB|   |...|   |LSB| X |...| X |MSB|   |...|   |LSB| X |...| X |   |
+---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
+   | Left channel                  | Right channel                 |
+
+
+Right Justified (aka LSB)
+ .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
+-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
+   .-------------------------------.                               .-----
+---'                               '-------------------------------'
+---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
+   | X |...| X |MSB|   |...|   |LSB| X |...| X |MSB|   |...|   |LSB|   |
+---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
+   | Left channel                  | Right channel                 |
+
+
+DSP mode A
+ .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
+-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
+      -.                                                          -.
+       '-                                                          '-
+---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
+   |   |MSB|   |...|   |LSB|MSB|   |...|   |LSB| X |   |...|   | X |   |
+---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
+       | Left channel      | Right channel     |                   |
+
+LRC examples for DSP mode A
+   .---.                                                       .---.
+---'   '-------------------------------------------------------'   '-----
+     .-.                                                         .-.
+-----' '---------------------------------------------------------' '-----
+-------. .---------------------------------------------------------. .---
+       '-'                                                         '-'
+
+
+DSP mode B
+ .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
+-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
+   .-                                                          .-
+  -'                                                          -'
+---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
+   |MSB|   |...|   |LSB|MSB|   |...|   |LSB| X |   |...|   | X |   |   |
+---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
+   | Left channel      | Right channel     |                   |
+
+LRC examples for DSP mode B
+   .---.                                                       .---.
+---'   '-------------------------------------------------------'   '-----
+-. .---------------------------------------------------------. .---------
+ '-'                                                         '-'
+
+
+The above diagrams show normal BCLK and LRC clocking where DAI transmitters
+change DATA on the falling edge of BCLK and DAI receivers read DATA on the
+rising edge. For inverted BCLK it is naturally the other way around. Inverted
+LRC is just that. Note that DSP mode A is compatible with DSP mode B with
+inverted LRC, and vice versa.
+
+
+Left Justified, inverted BCLK
+-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-
+ '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-'
+   .-------------------------------.                               .-----
+---'                               '-------------------------------'
+---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
+   |MSB|   |...|   |LSB| X |...| X |MSB|   |...|   |LSB| X |...| X |   |
+---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
+   | Left channel                  | Right channel                 |
+
+
+Left Justified, inverted LRC
+ .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
+-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
+---.                               .-------------------------------.
+   '-------------------------------'                               '-----
+---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
+   |MSB|   |...|   |LSB| X |...| X |MSB|   |...|   |LSB| X |...| X |   |
+---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
+   | Left channel                  | Right channel                 |
-- 
2.1.4

Re: [PATCH] ASoC: docs: add clocking examples for DAI formats

[Mark Brown]

[-- Attachment #1.1: Type: text/plain, Size: 631 bytes --]

On Mon, Apr 18, 2016 at 11:39:50AM +0200, Peter Rosin wrote:

> +I2S
> + .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
> +-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-

There is an actual spec for I2S which is going to be clearer than ASCII
art:

   https://www.sparkfun.com/datasheets/BreakoutBoards/I2SBUS.pdf

is the first hit on google (there's a bunch of electrical stuff in there
that gets roundly ignord these days but the clocking stuff is in there).

In general I'd rather have some words rather than just pictures, ASCII
art as the only thing is pretty hard to read.

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 473 bytes --]

[-- Attachment #2: Type: text/plain, Size: 0 bytes --]

Re: [PATCH] ASoC: docs: add clocking examples for DAI formats

[Peter Rosin]

Mark Brown wrote:
> On Mon, Apr 18, 2016 at 11:39:50AM +0200, Peter Rosin wrote:
> 
> > +I2S
> > + .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
> > +-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
> 
> There is an actual spec for I2S which is going to be clearer than ASCII
> art:
> 
>    https://www.sparkfun.com/datasheets/BreakoutBoards/I2SBUS.pdf
> 
> is the first hit on google (there's a bunch of electrical stuff in there
> that gets roundly ignord these days but the clocking stuff is in there).

Yes, but where are the equivalent docs for the other formats?

> In general I'd rather have some words rather than just pictures, ASCII
> art as the only thing is pretty hard to read.

I'll post a v2 with some words about each format. Or will you reject
anything with ASCII art?

Cheers,
Peter

Re: [PATCH] ASoC: docs: add clocking examples for DAI formats

[Mark Brown]

[-- Attachment #1: Type: text/plain, Size: 891 bytes --]

On Mon, Apr 18, 2016 at 12:55:23PM +0000, Peter Rosin wrote:
> Mark Brown wrote:

> > There is an actual spec for I2S which is going to be clearer than ASCII
> > art:

> >    https://www.sparkfun.com/datasheets/BreakoutBoards/I2SBUS.pdf

> > is the first hit on google (there's a bunch of electrical stuff in there
> > that gets roundly ignord these days but the clocking stuff is in there).

> Yes, but where are the equivalent docs for the other formats?

There aren't any (beyond the usual references to the Wolfson datasheets
which I'd suggest should be in here) but that doesn't mean we should
ignore this spec when we have it.

> > In general I'd rather have some words rather than just pictures, ASCII
> > art as the only thing is pretty hard to read.

> I'll post a v2 with some words about each format. Or will you reject
> anything with ASCII art?

So long as it's comprehensible.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 473 bytes --]

SV: [PATCH] ASoC: docs: add clocking examples for DAI formats

[Peter Rosin]

Mark Brown wrote:
> On Mon, Apr 18, 2016 at 12:55:23PM +0000, Peter Rosin wrote:
> > Mark Brown wrote:
> 
> > > There is an actual spec for I2S which is going to be clearer than ASCII
> > > art:
> 
> > >    https://www.sparkfun.com/datasheets/BreakoutBoards/I2SBUS.pdf
> 
> > > is the first hit on google (there's a bunch of electrical stuff in there
> > > that gets roundly ignord these days but the clocking stuff is in there).
> 
> > Yes, but where are the equivalent docs for the other formats?
> 
> There aren't any (beyond the usual references to the Wolfson datasheets
> which I'd suggest should be in here) but that doesn't mean we should
> ignore this spec when we have it.

This is exactly the problem. For an outsider, it's impossible to know that
wolfson has the correct definition of the modes. Why should wolfson datasheets
trumph nxp or ti datasheets (or whatever), if there is an inconsistency?

We need to specify somewhere exactly what Linux means with the different
modes. Because there are bugs in this area, where DAIs claim to support
the same format but are not actually compatible. Which one is buggy then?
And this is not about flank timings or such details, it's about what bits go
where in relation to flanks etc.

> > > In general I'd rather have some words rather than just pictures, ASCII
> > > art as the only thing is pretty hard to read.
> 
> > I'll post a v2 with some words about each format. Or will you reject
> > anything with ASCII art?
> 
> So long as it's comprehensible.

Ok

Cheers,
Peter

Re: SV: [PATCH] ASoC: docs: add clocking examples for DAI formats

[Mark Brown]

[-- Attachment #1: Type: text/plain, Size: 671 bytes --]

On Mon, Apr 18, 2016 at 01:18:47PM +0000, Peter Rosin wrote:
> Mark Brown wrote:

> > 
> > There aren't any (beyond the usual references to the Wolfson datasheets
> > which I'd suggest should be in here) but that doesn't mean we should
> > ignore this spec when we have it.

> This is exactly the problem. For an outsider, it's impossible to know that
> wolfson has the correct definition of the modes. Why should wolfson datasheets
> trumph nxp or ti datasheets (or whatever), if there is an inconsistency?

I'm not quite sure what your concern is here?  I'm saying that where
there are specs we should link to them.  I'm not saying we can't add
to that.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 473 bytes --]

Re: [PATCH] ASoC: docs: add clocking examples for DAI formats

[Peter Rosin]

On 2016-04-18 17:11, Mark Brown wrote:
> On Mon, Apr 18, 2016 at 01:18:47PM +0000, Peter Rosin wrote:
>> Mark Brown wrote:
> 
>>>
>>> There aren't any (beyond the usual references to the Wolfson datasheets
>>> which I'd suggest should be in here) but that doesn't mean we should
>>> ignore this spec when we have it.
> 
>> This is exactly the problem. For an outsider, it's impossible to know that
>> wolfson has the correct definition of the modes. Why should wolfson datasheets
>> trumph nxp or ti datasheets (or whatever), if there is an inconsistency?
> 
> I'm not quite sure what your concern is here?  I'm saying that where
> there are specs we should link to them.  I'm not saying we can't add
> to that.

I'm just saying that I don't know which specs to trust.

E.g. a random wolfson datasheet (wm8778) says that DSP mode B will have BCLK and
LRC like this when it is clk master

 .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
       .---.                                                       .---.
-------'   '-------------------------------------------------------'   '-----

and that it will accept the negative LRC flank later when it is clk slave,
with a figure showing this as the extreme:

 .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
---.   .-------------------------------------------------------.   .-----
   '---'                                                       '---'

Then we have the tfa9879 datasheet from nxp which has this for its long sync
format:

-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-
 '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-'
-----. .---------------------------------------------------------. .-----
     '-'                                                         '-'

This is all very difficult to match up for someone who doesn't work with this
on a day-to-day basis and know it by heart. Why should I go to some random
wolfson datasheet for info?

I don't know if the nxp long sync format is compatible with DSP mode B with
inverted BCLK, but it certainly looks like it might be. The LRC is low for
only half a cycle and that is not acceptable according to the wolfson
datasheet, but is that a limitation in wm8778 or is the tfa9879 problematic?
How would you suppose I figure out if the tfa9879 driver should declare
compatibility with DSP mode B with inverted BCLK if there is no documentation
of what *ASoC* thinks that DSP mode B really is?

This info is desperately missing, that is all that I'm saying.

With this background, I'm a bit reluctant to add links to some datasheet,
because they tend to describe how the chip in question behaves, and not the
protocol as such. But sure, the I2S spec is something else as it's independent
from any particular chip.

BTW, I found out that I had misunderstood DSP mode A in v1/v2 of the patch, so
a v3 is coming up where I'll also add a link to the I2S spec. If there is any
particular link that you think I should add for any other format spec, please
holler.

Cheers,
Peter