tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation: soundwire: Add more documentation
This adds documentation for error handling, locking and streams.
Signed-off-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
Signed-off-by: Sanyog Kale <sanyog.r.kale@intel.com>
Signed-off-by: Shreyas NC <shreyas.nc@intel.com>
Signed-off-by: Vinod Koul <vkoul@kernel.org>
authored by
Sanyog Kale
and committed by
Vinod Koul
89634f99
fce45d11
+546
+65
Documentation/driver-api/soundwire/error_handling.rst
+65
Documentation/driver-api/soundwire/error_handling.rst
···
1
+
========================
2
+
SoundWire Error Handling
3
+
========================
4
+
5
+
The SoundWire PHY was designed with care and errors on the bus are going to
6
+
be very unlikely, and if they happen it should be limited to single bit
7
+
errors. Examples of this design can be found in the synchronization
8
+
mechanism (sync loss after two errors) and short CRCs used for the Bulk
9
+
Register Access.
10
+
11
+
The errors can be detected with multiple mechanisms:
12
+
13
+
1. Bus clash or parity errors: This mechanism relies on low-level detectors
14
+
that are independent of the payload and usages, and they cover both control
15
+
and audio data. The current implementation only logs such errors.
16
+
Improvements could be invalidating an entire programming sequence and
17
+
restarting from a known position. In the case of such errors outside of a
18
+
control/command sequence, there is no concealment or recovery for audio
19
+
data enabled by the SoundWire protocol, the location of the error will also
20
+
impact its audibility (most-significant bits will be more impacted in PCM),
21
+
and after a number of such errors are detected the bus might be reset. Note
22
+
that bus clashes due to programming errors (two streams using the same bit
23
+
slots) or electrical issues during the transmit/receive transition cannot
24
+
be distinguished, although a recurring bus clash when audio is enabled is a
25
+
indication of a bus allocation issue. The interrupt mechanism can also help
26
+
identify Slaves which detected a Bus Clash or a Parity Error, but they may
27
+
not be responsible for the errors so resetting them individually is not a
28
+
viable recovery strategy.
29
+
30
+
2. Command status: Each command is associated with a status, which only
31
+
covers transmission of the data between devices. The ACK status indicates
32
+
that the command was received and will be executed by the end of the
33
+
current frame. A NAK indicates that the command was in error and will not
34
+
be applied. In case of a bad programming (command sent to non-existent
35
+
Slave or to a non-implemented register) or electrical issue, no response
36
+
signals the command was ignored. Some Master implementations allow for a
37
+
command to be retransmitted several times. If the retransmission fails,
38
+
backtracking and restarting the entire programming sequence might be a
39
+
solution. Alternatively some implementations might directly issue a bus
40
+
reset and re-enumerate all devices.
41
+
42
+
3. Timeouts: In a number of cases such as ChannelPrepare or
43
+
ClockStopPrepare, the bus driver is supposed to poll a register field until
44
+
it transitions to a NotFinished value of zero. The MIPI SoundWire spec 1.1
45
+
does not define timeouts but the MIPI SoundWire DisCo document adds
46
+
recommendation on timeouts. If such configurations do not complete, the
47
+
driver will return a -ETIMEOUT. Such timeouts are symptoms of a faulty
48
+
Slave device and are likely impossible to recover from.
49
+
50
+
Errors during global reconfiguration sequences are extremely difficult to
51
+
handle:
52
+
53
+
1. BankSwitch: An error during the last command issuing a BankSwitch is
54
+
difficult to backtrack from. Retransmitting the Bank Switch command may be
55
+
possible in a single segment setup, but this can lead to synchronization
56
+
problems when enabling multiple bus segments (a command with side effects
57
+
such as frame reconfiguration would be handled at different times). A global
58
+
hard-reset might be the best solution.
59
+
60
+
Note that SoundWire does not provide a mechanism to detect illegal values
61
+
written in valid registers. In a number of cases the standard even mentions
62
+
that the Slave might behave in implementation-defined ways. The bus
63
+
implementation does not provide a recovery mechanism for such errors, Slave
64
+
or Master driver implementers are responsible for writing valid values in
65
+
valid registers and implement additional range checking if needed.
+3
Documentation/driver-api/soundwire/index.rst
+3
Documentation/driver-api/soundwire/index.rst
+106
Documentation/driver-api/soundwire/locking.rst
+106
Documentation/driver-api/soundwire/locking.rst
···
1
+
=================
2
+
SoundWire Locking
3
+
=================
4
+
5
+
This document explains locking mechanism of the SoundWire Bus. Bus uses
6
+
following locks in order to avoid race conditions in Bus operations on
7
+
shared resources.
8
+
9
+
- Bus lock
10
+
11
+
- Message lock
12
+
13
+
Bus lock
14
+
========
15
+
16
+
SoundWire Bus lock is a mutex and is part of Bus data structure
17
+
(sdw_bus) which is used for every Bus instance. This lock is used to
18
+
serialize each of the following operations(s) within SoundWire Bus instance.
19
+
20
+
- Addition and removal of Slave(s), changing Slave status.
21
+
22
+
- Prepare, Enable, Disable and De-prepare stream operations.
23
+
24
+
- Access of Stream data structure.
25
+
26
+
Message lock
27
+
============
28
+
29
+
SoundWire message transfer lock. This mutex is part of
30
+
Bus data structure (sdw_bus). This lock is used to serialize the message
31
+
transfers (read/write) within a SoundWire Bus instance.
32
+
33
+
Below examples show how locks are acquired.
34
+
35
+
Example 1
36
+
---------
37
+
38
+
Message transfer.
39
+
40
+
1. For every message transfer
41
+
42
+
a. Acquire Message lock.
43
+
44
+
b. Transfer message (Read/Write) to Slave1 or broadcast message on
45
+
Bus in case of bank switch.
46
+
47
+
c. Release Message lock ::
48
+
49
+
+----------+ +---------+
50
+
| | | |
51
+
| Bus | | Master |
52
+
| | | Driver |
53
+
| | | |
54
+
+----+-----+ +----+----+
55
+
| |
56
+
| bus->ops->xfer_msg() |
57
+
<-------------------------------+ a. Acquire Message lock
58
+
| | b. Transfer message
59
+
| |
60
+
+-------------------------------> c. Release Message lock
61
+
| return success/error | d. Return success/error
62
+
| |
63
+
+ +
64
+
65
+
Example 2
66
+
---------
67
+
68
+
Prepare operation.
69
+
70
+
1. Acquire lock for Bus instance associated with Master 1.
71
+
72
+
2. For every message transfer in Prepare operation
73
+
74
+
a. Acquire Message lock.
75
+
76
+
b. Transfer message (Read/Write) to Slave1 or broadcast message on
77
+
Bus in case of bank switch.
78
+
79
+
c. Release Message lock.
80
+
81
+
3. Release lock for Bus instance associated with Master 1 ::
82
+
83
+
+----------+ +---------+
84
+
| | | |
85
+
| Bus | | Master |
86
+
| | | Driver |
87
+
| | | |
88
+
+----+-----+ +----+----+
89
+
| |
90
+
| sdw_prepare_stream() |
91
+
<-------------------------------+ 1. Acquire bus lock
92
+
| | 2. Perform stream prepare
93
+
| |
94
+
| |
95
+
| bus->ops->xfer_msg() |
96
+
<-------------------------------+ a. Acquire Message lock
97
+
| | b. Transfer message
98
+
| |
99
+
+-------------------------------> c. Release Message lock
100
+
| return success/error | d. Return success/error
101
+
| |
102
+
| |
103
+
| return success/error | 3. Release bus lock
104
+
+-------------------------------> 4. Return success/error
105
+
| |
106
+
+ +
+372
Documentation/driver-api/soundwire/stream.rst
+372
Documentation/driver-api/soundwire/stream.rst
···
1
+
=========================
2
+
Audio Stream in SoundWire
3
+
=========================
4
+
5
+
An audio stream is a logical or virtual connection created between
6
+
7
+
(1) System memory buffer(s) and Codec(s)
8
+
9
+
(2) DSP memory buffer(s) and Codec(s)
10
+
11
+
(3) FIFO(s) and Codec(s)
12
+
13
+
(4) Codec(s) and Codec(s)
14
+
15
+
which is typically driven by a DMA(s) channel through the data link. An
16
+
audio stream contains one or more channels of data. All channels within
17
+
stream must have same sample rate and same sample size.
18
+
19
+
Assume a stream with two channels (Left & Right) is opened using SoundWire
20
+
interface. Below are some ways a stream can be represented in SoundWire.
21
+
22
+
Stream Sample in memory (System memory, DSP memory or FIFOs) ::
23
+
24
+
-------------------------
25
+
| L | R | L | R | L | R |
26
+
-------------------------
27
+
28
+
Example 1: Stereo Stream with L and R channels is rendered from Master to
29
+
Slave. Both Master and Slave is using single port. ::
30
+
31
+
+---------------+ Clock Signal +---------------+
32
+
| Master +----------------------------------+ Slave |
33
+
| Interface | | Interface |
34
+
| | | 1 |
35
+
| | Data Signal | |
36
+
| L + R +----------------------------------+ L + R |
37
+
| (Data) | Data Direction | (Data) |
38
+
+---------------+ +-----------------------> +---------------+
39
+
40
+
41
+
Example 2: Stereo Stream with L and R channels is captured from Slave to
42
+
Master. Both Master and Slave is using single port. ::
43
+
44
+
45
+
+---------------+ Clock Signal +---------------+
46
+
| Master +----------------------------------+ Slave |
47
+
| Interface | | Interface |
48
+
| | | 1 |
49
+
| | Data Signal | |
50
+
| L + R +----------------------------------+ L + R |
51
+
| (Data) | Data Direction | (Data) |
52
+
+---------------+ <-----------------------+ +---------------+
53
+
54
+
55
+
Example 3: Stereo Stream with L and R channels is rendered by Master. Each
56
+
of the L and R channel is received by two different Slaves. Master and both
57
+
Slaves are using single port. ::
58
+
59
+
+---------------+ Clock Signal +---------------+
60
+
| Master +---------+------------------------+ Slave |
61
+
| Interface | | | Interface |
62
+
| | | | 1 |
63
+
| | | Data Signal | |
64
+
| L + R +---+------------------------------+ L |
65
+
| (Data) | | | Data Direction | (Data) |
66
+
+---------------+ | | +-------------> +---------------+
67
+
| |
68
+
| |
69
+
| | +---------------+
70
+
| +----------------------> | Slave |
71
+
| | Interface |
72
+
| | 2 |
73
+
| | |
74
+
+----------------------------> | R |
75
+
| (Data) |
76
+
+---------------+
77
+
78
+
79
+
Example 4: Stereo Stream with L and R channel is rendered by two different
80
+
Ports of the Master and is received by only single Port of the Slave
81
+
interface. ::
82
+
83
+
+--------------------+
84
+
| |
85
+
| +--------------+ +----------------+
86
+
| | || | |
87
+
| | Data Port || L Channel | |
88
+
| | 1 |------------+ | |
89
+
| | L Channel || | +-----+----+ |
90
+
| | (Data) || | L + R Channel || Data | |
91
+
| Master +----------+ | +---+---------> || Port | |
92
+
| Interface | | || 1 | |
93
+
| +--------------+ | || | |
94
+
| | || | +----------+ |
95
+
| | Data Port |------------+ | |
96
+
| | 2 || R Channel | Slave |
97
+
| | R Channel || | Interface |
98
+
| | (Data) || | 1 |
99
+
| +--------------+ Clock Signal | L + R |
100
+
| +---------------------------> | (Data) |
101
+
+--------------------+ | |
102
+
+----------------+
103
+
104
+
SoundWire Stream Management flow
105
+
================================
106
+
107
+
Stream definitions
108
+
------------------
109
+
110
+
(1) Current stream: This is classified as the stream on which operation has
111
+
to be performed like prepare, enable, disable, de-prepare etc.
112
+
113
+
(2) Active stream: This is classified as the stream which is already active
114
+
on Bus other than current stream. There can be multiple active streams
115
+
on the Bus.
116
+
117
+
SoundWire Bus manages stream operations for each stream getting
118
+
rendered/captured on the SoundWire Bus. This section explains Bus operations
119
+
done for each of the stream allocated/released on Bus. Following are the
120
+
stream states maintained by the Bus for each of the audio stream.
121
+
122
+
123
+
SoundWire stream states
124
+
-----------------------
125
+
126
+
Below shows the SoundWire stream states and state transition diagram. ::
127
+
128
+
+-----------+ +------------+ +----------+ +----------+
129
+
| ALLOCATED +---->| CONFIGURED +---->| PREPARED +---->| ENABLED |
130
+
| STATE | | STATE | | STATE | | STATE |
131
+
+-----------+ +------------+ +----------+ +----+-----+
132
+
^
133
+
|
134
+
|
135
+
v
136
+
+----------+ +------------+ +----+-----+
137
+
| RELEASED |<----------+ DEPREPARED |<-------+ DISABLED |
138
+
| STATE | | STATE | | STATE |
139
+
+----------+ +------------+ +----------+
140
+
141
+
NOTE: State transition between prepare and deprepare is supported in Spec
142
+
but not in the software (subsystem)
143
+
144
+
NOTE2: Stream state transition checks need to be handled by caller
145
+
framework, for example ALSA/ASoC. No checks for stream transition exist in
146
+
SoundWire subsystem.
147
+
148
+
Stream State Operations
149
+
-----------------------
150
+
151
+
Below section explains the operations done by the Bus on Master(s) and
152
+
Slave(s) as part of stream state transitions.
153
+
154
+
SDW_STREAM_ALLOCATED
155
+
~~~~~~~~~~~~~~~~~~~~
156
+
157
+
Allocation state for stream. This is the entry state
158
+
of the stream. Operations performed before entering in this state:
159
+
160
+
(1) A stream runtime is allocated for the stream. This stream
161
+
runtime is used as a reference for all the operations performed
162
+
on the stream.
163
+
164
+
(2) The resources required for holding stream runtime information are
165
+
allocated and initialized. This holds all stream related information
166
+
such as stream type (PCM/PDM) and parameters, Master and Slave
167
+
interface associated with the stream, stream state etc.
168
+
169
+
After all above operations are successful, stream state is set to
170
+
``SDW_STREAM_ALLOCATED``.
171
+
172
+
Bus implements below API for allocate a stream which needs to be called once
173
+
per stream. From ASoC DPCM framework, this stream state maybe linked to
174
+
.startup() operation.
175
+
176
+
.. code-block:: c
177
+
int sdw_alloc_stream(char * stream_name);
178
+
179
+
180
+
SDW_STREAM_CONFIGURED
181
+
~~~~~~~~~~~~~~~~~~~~~
182
+
183
+
Configuration state of stream. Operations performed before entering in
184
+
this state:
185
+
186
+
(1) The resources allocated for stream information in SDW_STREAM_ALLOCATED
187
+
state are updated here. This includes stream parameters, Master(s)
188
+
and Slave(s) runtime information associated with current stream.
189
+
190
+
(2) All the Master(s) and Slave(s) associated with current stream provide
191
+
the port information to Bus which includes port numbers allocated by
192
+
Master(s) and Slave(s) for current stream and their channel mask.
193
+
194
+
After all above operations are successful, stream state is set to
195
+
``SDW_STREAM_CONFIGURED``.
196
+
197
+
Bus implements below APIs for CONFIG state which needs to be called by
198
+
the respective Master(s) and Slave(s) associated with stream. These APIs can
199
+
only be invoked once by respective Master(s) and Slave(s). From ASoC DPCM
200
+
framework, this stream state is linked to .hw_params() operation.
201
+
202
+
.. code-block:: c
203
+
int sdw_stream_add_master(struct sdw_bus * bus,
204
+
struct sdw_stream_config * stream_config,
205
+
struct sdw_ports_config * ports_config,
206
+
struct sdw_stream_runtime * stream);
207
+
208
+
int sdw_stream_add_slave(struct sdw_slave * slave,
209
+
struct sdw_stream_config * stream_config,
210
+
struct sdw_ports_config * ports_config,
211
+
struct sdw_stream_runtime * stream);
212
+
213
+
214
+
SDW_STREAM_PREPARED
215
+
~~~~~~~~~~~~~~~~~~~
216
+
217
+
Prepare state of stream. Operations performed before entering in this state:
218
+
219
+
(1) Bus parameters such as bandwidth, frame shape, clock frequency,
220
+
are computed based on current stream as well as already active
221
+
stream(s) on Bus. Re-computation is required to accommodate current
222
+
stream on the Bus.
223
+
224
+
(2) Transport and port parameters of all Master(s) and Slave(s) port(s) are
225
+
computed for the current as well as already active stream based on frame
226
+
shape and clock frequency computed in step 1.
227
+
228
+
(3) Computed Bus and transport parameters are programmed in Master(s) and
229
+
Slave(s) registers. The banked registers programming is done on the
230
+
alternate bank (bank currently unused). Port(s) are enabled for the
231
+
already active stream(s) on the alternate bank (bank currently unused).
232
+
This is done in order to not disrupt already active stream(s).
233
+
234
+
(4) Once all the values are programmed, Bus initiates switch to alternate
235
+
bank where all new values programmed gets into effect.
236
+
237
+
(5) Ports of Master(s) and Slave(s) for current stream are prepared by
238
+
programming PrepareCtrl register.
239
+
240
+
After all above operations are successful, stream state is set to
241
+
``SDW_STREAM_PREPARED``.
242
+
243
+
Bus implements below API for PREPARE state which needs to be called once per
244
+
stream. From ASoC DPCM framework, this stream state is linked to
245
+
.prepare() operation.
246
+
247
+
.. code-block:: c
248
+
int sdw_prepare_stream(struct sdw_stream_runtime * stream);
249
+
250
+
251
+
SDW_STREAM_ENABLED
252
+
~~~~~~~~~~~~~~~~~~
253
+
254
+
Enable state of stream. The data port(s) are enabled upon entering this state.
255
+
Operations performed before entering in this state:
256
+
257
+
(1) All the values computed in SDW_STREAM_PREPARED state are programmed
258
+
in alternate bank (bank currently unused). It includes programming of
259
+
already active stream(s) as well.
260
+
261
+
(2) All the Master(s) and Slave(s) port(s) for the current stream are
262
+
enabled on alternate bank (bank currently unused) by programming
263
+
ChannelEn register.
264
+
265
+
(3) Once all the values are programmed, Bus initiates switch to alternate
266
+
bank where all new values programmed gets into effect and port(s)
267
+
associated with current stream are enabled.
268
+
269
+
After all above operations are successful, stream state is set to
270
+
``SDW_STREAM_ENABLED``.
271
+
272
+
Bus implements below API for ENABLE state which needs to be called once per
273
+
stream. From ASoC DPCM framework, this stream state is linked to
274
+
.trigger() start operation.
275
+
276
+
.. code-block:: c
277
+
int sdw_enable_stream(struct sdw_stream_runtime * stream);
278
+
279
+
SDW_STREAM_DISABLED
280
+
~~~~~~~~~~~~~~~~~~~
281
+
282
+
Disable state of stream. The data port(s) are disabled upon exiting this state.
283
+
Operations performed before entering in this state:
284
+
285
+
(1) All the Master(s) and Slave(s) port(s) for the current stream are
286
+
disabled on alternate bank (bank currently unused) by programming
287
+
ChannelEn register.
288
+
289
+
(2) All the current configuration of Bus and active stream(s) are programmed
290
+
into alternate bank (bank currently unused).
291
+
292
+
(3) Once all the values are programmed, Bus initiates switch to alternate
293
+
bank where all new values programmed gets into effect and port(s) associated
294
+
with current stream are disabled.
295
+
296
+
After all above operations are successful, stream state is set to
297
+
``SDW_STREAM_DISABLED``.
298
+
299
+
Bus implements below API for DISABLED state which needs to be called once
300
+
per stream. From ASoC DPCM framework, this stream state is linked to
301
+
.trigger() stop operation.
302
+
303
+
.. code-block:: c
304
+
int sdw_disable_stream(struct sdw_stream_runtime * stream);
305
+
306
+
307
+
SDW_STREAM_DEPREPARED
308
+
~~~~~~~~~~~~~~~~~~~~~
309
+
310
+
De-prepare state of stream. Operations performed before entering in this
311
+
state:
312
+
313
+
(1) All the port(s) of Master(s) and Slave(s) for current stream are
314
+
de-prepared by programming PrepareCtrl register.
315
+
316
+
(2) The payload bandwidth of current stream is reduced from the total
317
+
bandwidth requirement of bus and new parameters calculated and
318
+
applied by performing bank switch etc.
319
+
320
+
After all above operations are successful, stream state is set to
321
+
``SDW_STREAM_DEPREPARED``.
322
+
323
+
Bus implements below API for DEPREPARED state which needs to be called once
324
+
per stream. From ASoC DPCM framework, this stream state is linked to
325
+
.trigger() stop operation.
326
+
327
+
.. code-block:: c
328
+
int sdw_deprepare_stream(struct sdw_stream_runtime * stream);
329
+
330
+
331
+
SDW_STREAM_RELEASED
332
+
~~~~~~~~~~~~~~~~~~~
333
+
334
+
Release state of stream. Operations performed before entering in this state:
335
+
336
+
(1) Release port resources for all Master(s) and Slave(s) port(s)
337
+
associated with current stream.
338
+
339
+
(2) Release Master(s) and Slave(s) runtime resources associated with
340
+
current stream.
341
+
342
+
(3) Release stream runtime resources associated with current stream.
343
+
344
+
After all above operations are successful, stream state is set to
345
+
``SDW_STREAM_RELEASED``.
346
+
347
+
Bus implements below APIs for RELEASE state which needs to be called by
348
+
all the Master(s) and Slave(s) associated with stream. From ASoC DPCM
349
+
framework, this stream state is linked to .hw_free() operation.
350
+
351
+
.. code-block:: c
352
+
int sdw_stream_remove_master(struct sdw_bus * bus,
353
+
struct sdw_stream_runtime * stream);
354
+
int sdw_stream_remove_slave(struct sdw_slave * slave,
355
+
struct sdw_stream_runtime * stream);
356
+
357
+
358
+
The .shutdown() ASoC DPCM operation calls below Bus API to release
359
+
stream assigned as part of ALLOCATED state.
360
+
361
+
In .shutdown() the data structure maintaining stream state are freed up.
362
+
363
+
.. code-block:: c
364
+
void sdw_release_stream(struct sdw_stream_runtime * stream);
365
+
366
+
Not Supported
367
+
=============
368
+
369
+
1. A single port with multiple channels supported cannot be used between two
370
+
streams or across stream. For example a port with 4 channels cannot be used
371
+
to handle 2 independent stereo streams even though it's possible in theory
372
+
in SoundWire.