tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
ASoC: doc: Add documentation for SOC USB
With the introduction of the soc-usb driver, add documentation highlighting
details on how to utilize the new driver and how it interacts with
different components in USB SND and ASoC. It provides examples on how to
implement the drivers that will need to be introduced in order to enable
USB audio offloading.
Signed-off-by: Wesley Cheng <quic_wcheng@quicinc.com>
Acked-by: Mark Brown <broonie@kernel.org>
Link: https://lore.kernel.org/r/20250409194804.3773260-20-quic_wcheng@quicinc.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
authored by
Wesley Cheng
and committed by
Greg Kroah-Hartman
6640c9bc
f98cd6ec
+483
+482
Documentation/sound/soc/usb.rst
+482
Documentation/sound/soc/usb.rst
···
1
+
================
2
+
ASoC USB support
3
+
================
4
+
5
+
Overview
6
+
========
7
+
In order to leverage the existing USB sound device support in ALSA, the
8
+
ASoC USB APIs are introduced to allow the subsystems to exchange
9
+
configuration information.
10
+
11
+
One potential use case would be to support USB audio offloading, which is
12
+
an implementation that allows for an alternate power-optimized path in the audio
13
+
subsystem to handle the transfer of audio data over the USB bus. This would
14
+
let the main processor to stay in lower power modes for longer duration. The
15
+
following is an example design of how the ASoC and ALSA pieces can be connected
16
+
together to achieve this:
17
+
18
+
::
19
+
20
+
USB | ASoC
21
+
| _________________________
22
+
| | ASoC Platform card |
23
+
| |_________________________|
24
+
| | |
25
+
| ___V____ ____V____
26
+
| |ASoC BE | |ASoC FE |
27
+
| |DAI LNK | |DAI LNK |
28
+
| |________| |_________|
29
+
| ^ ^ ^
30
+
| | |________|
31
+
| ___V____ |
32
+
| |SoC-USB | |
33
+
________ ________ | | |
34
+
|USB SND |<--->|USBSND |<------------>|________| |
35
+
|(card.c)| |offld |<---------- |
36
+
|________| |________|___ | | |
37
+
^ ^ | | | ____________V_________
38
+
| | | | | |IPC |
39
+
__ V_______________V_____ | | | |______________________|
40
+
|USB SND (endpoint.c) | | | | ^
41
+
|_________________________| | | | |
42
+
^ | | | ___________V___________
43
+
| | | |->|audio DSP |
44
+
___________V_____________ | | |_______________________|
45
+
|XHCI HCD |<- |
46
+
|_________________________| |
47
+
48
+
49
+
SoC USB driver
50
+
==============
51
+
Structures
52
+
----------
53
+
``struct snd_soc_usb``
54
+
55
+
- ``list``: list head for SND SoC struct list
56
+
- ``component``: reference to ASoC component
57
+
- ``connection_status_cb``: callback to notify connection events
58
+
- ``update_offload_route_info``: callback to fetch selected USB sound card/PCM
59
+
device
60
+
- ``priv_data``: driver data
61
+
62
+
The snd_soc_usb structure can be referenced using the ASoC platform card
63
+
device, or a USB device (udev->dev). This is created by the ASoC BE DAI
64
+
link, and the USB sound entity will be able to pass information to the
65
+
ASoC BE DAI link using this structure.
66
+
67
+
``struct snd_soc_usb_device``
68
+
69
+
- ``card_idx``: sound card index associated with USB sound device
70
+
- ``chip_idx``: USB sound chip array index
71
+
- ``cpcm_idx``: capture pcm device indexes associated with the USB sound device
72
+
- ``ppcm_idx``: playback pcm device indexes associated with the USB sound device
73
+
- ``num_playback``: number of playback streams
74
+
- ``num_capture``: number of capture streams
75
+
- ``list``: list head for the USB sound device list
76
+
77
+
The struct snd_soc_usb_device is created by the USB sound offload driver.
78
+
This will carry basic parameters/limitations that will be used to
79
+
determine the possible offloading paths for this USB audio device.
80
+
81
+
Functions
82
+
---------
83
+
.. code-block:: rst
84
+
85
+
int snd_soc_usb_find_supported_format(int card_idx,
86
+
struct snd_pcm_hw_params *params, int direction)
87
+
..
88
+
89
+
- ``card_idx``: the index into the USB sound chip array.
90
+
- ``params``: Requested PCM parameters from the USB DPCM BE DAI link
91
+
- ``direction``: capture or playback
92
+
93
+
**snd_soc_usb_find_supported_format()** ensures that the requested audio profile
94
+
being requested by the external DSP is supported by the USB device.
95
+
96
+
Returns 0 on success, and -EOPNOTSUPP on failure.
97
+
98
+
.. code-block:: rst
99
+
100
+
int snd_soc_usb_connect(struct device *usbdev, struct snd_soc_usb_device *sdev)
101
+
..
102
+
103
+
- ``usbdev``: the usb device that was discovered
104
+
- ``sdev``: capabilities of the device
105
+
106
+
**snd_soc_usb_connect()** notifies the ASoC USB DCPM BE DAI link of a USB
107
+
audio device detection. This can be utilized in the BE DAI
108
+
driver to keep track of available USB audio devices. This is intended
109
+
to be called by the USB offload driver residing in USB SND.
110
+
111
+
Returns 0 on success, negative error code on failure.
112
+
113
+
.. code-block:: rst
114
+
115
+
int snd_soc_usb_disconnect(struct device *usbdev, struct snd_soc_usb_device *sdev)
116
+
..
117
+
118
+
- ``usbdev``: the usb device that was removed
119
+
- ``sdev``: capabilities to free
120
+
121
+
**snd_soc_usb_disconnect()** notifies the ASoC USB DCPM BE DAI link of a USB
122
+
audio device removal. This is intended to be called by the USB offload
123
+
driver that resides in USB SND.
124
+
125
+
.. code-block:: rst
126
+
127
+
void *snd_soc_usb_find_priv_data(struct device *usbdev)
128
+
..
129
+
130
+
- ``usbdev``: the usb device to reference to find private data
131
+
132
+
**snd_soc_usb_find_priv_data()** fetches the private data saved to the SoC USB
133
+
device.
134
+
135
+
Returns pointer to priv_data on success, NULL on failure.
136
+
137
+
.. code-block:: rst
138
+
139
+
int snd_soc_usb_setup_offload_jack(struct snd_soc_component *component,
140
+
struct snd_soc_jack *jack)
141
+
..
142
+
143
+
- ``component``: ASoC component to add the jack
144
+
- ``jack``: jack component to populate
145
+
146
+
**snd_soc_usb_setup_offload_jack()** is a helper to add a sound jack control to
147
+
the platform sound card. This will allow for consistent naming to be used on
148
+
designs that support USB audio offloading. Additionally, this will enable the
149
+
jack to notify of changes.
150
+
151
+
Returns 0 on success, negative otherwise.
152
+
153
+
.. code-block:: rst
154
+
155
+
int snd_soc_usb_update_offload_route(struct device *dev, int card, int pcm,
156
+
int direction, enum snd_soc_usb_kctl path,
157
+
long *route)
158
+
..
159
+
160
+
- ``dev``: USB device to look up offload path mapping
161
+
- ``card``: USB sound card index
162
+
- ``pcm``: USB sound PCM device index
163
+
- ``direction``: direction to fetch offload routing information
164
+
- ``path``: kcontrol selector - pcm device or card index
165
+
- ``route``: mapping of sound card and pcm indexes for the offload path. This is
166
+
an array of two integers that will carry the card and pcm device indexes
167
+
in that specific order. This can be used as the array for the kcontrol
168
+
output.
169
+
170
+
**snd_soc_usb_update_offload_route()** calls a registered callback to the USB BE DAI
171
+
link to fetch the information about the mapped ASoC devices for executing USB audio
172
+
offload for the device. ``route`` may be a pointer to a kcontrol value output array,
173
+
which carries values when the kcontrol is read.
174
+
175
+
Returns 0 on success, negative otherwise.
176
+
177
+
.. code-block:: rst
178
+
179
+
struct snd_soc_usb *snd_soc_usb_allocate_port(struct snd_soc_component *component,
180
+
void *data);
181
+
..
182
+
183
+
- ``component``: DPCM BE DAI link component
184
+
- ``data``: private data
185
+
186
+
**snd_soc_usb_allocate_port()** allocates a SoC USB device and populates standard
187
+
parameters that is used for further operations.
188
+
189
+
Returns a pointer to struct soc_usb on success, negative on error.
190
+
191
+
.. code-block:: rst
192
+
193
+
void snd_soc_usb_free_port(struct snd_soc_usb *usb);
194
+
..
195
+
196
+
- ``usb``: SoC USB device to free
197
+
198
+
**snd_soc_usb_free_port()** frees a SoC USB device.
199
+
200
+
.. code-block:: rst
201
+
202
+
void snd_soc_usb_add_port(struct snd_soc_usb *usb);
203
+
..
204
+
205
+
- ``usb``: SoC USB device to add
206
+
207
+
**snd_soc_usb_add_port()** add an allocated SoC USB device to the SOC USB framework.
208
+
Once added, this device can be referenced by further operations.
209
+
210
+
.. code-block:: rst
211
+
212
+
void snd_soc_usb_remove_port(struct snd_soc_usb *usb);
213
+
..
214
+
215
+
- ``usb``: SoC USB device to remove
216
+
217
+
**snd_soc_usb_remove_port()** removes a SoC USB device from the SoC USB framework.
218
+
After removing a device, any SOC USB operations would not be able to reference the
219
+
device removed.
220
+
221
+
How to Register to SoC USB
222
+
--------------------------
223
+
The ASoC DPCM USB BE DAI link is the entity responsible for allocating and
224
+
registering the SoC USB device on the component bind. Likewise, it will
225
+
also be responsible for freeing the allocated resources. An example can
226
+
be shown below:
227
+
228
+
.. code-block:: rst
229
+
230
+
static int q6usb_component_probe(struct snd_soc_component *component)
231
+
{
232
+
...
233
+
data->usb = snd_soc_usb_allocate_port(component, 1, &data->priv);
234
+
if (!data->usb)
235
+
return -ENOMEM;
236
+
237
+
usb->connection_status_cb = q6usb_alsa_connection_cb;
238
+
239
+
ret = snd_soc_usb_add_port(usb);
240
+
if (ret < 0) {
241
+
dev_err(component->dev, "failed to add usb port\n");
242
+
goto free_usb;
243
+
}
244
+
...
245
+
}
246
+
247
+
static void q6usb_component_remove(struct snd_soc_component *component)
248
+
{
249
+
...
250
+
snd_soc_usb_remove_port(data->usb);
251
+
snd_soc_usb_free_port(data->usb);
252
+
}
253
+
254
+
static const struct snd_soc_component_driver q6usb_dai_component = {
255
+
.probe = q6usb_component_probe,
256
+
.remove = q6usb_component_remove,
257
+
.name = "q6usb-dai-component",
258
+
...
259
+
};
260
+
..
261
+
262
+
BE DAI links can pass along vendor specific information as part of the
263
+
call to allocate the SoC USB device. This will allow any BE DAI link
264
+
parameters or settings to be accessed by the USB offload driver that
265
+
resides in USB SND.
266
+
267
+
USB Audio Device Connection Flow
268
+
--------------------------------
269
+
USB devices can be hotplugged into the USB ports at any point in time.
270
+
The BE DAI link should be aware of the current state of the physical USB
271
+
port, i.e. if there are any USB devices with audio interface(s) connected.
272
+
connection_status_cb() can be used to notify the BE DAI link of any change.
273
+
274
+
This is called whenever there is a USB SND interface bind or remove event,
275
+
using snd_soc_usb_connect() or snd_soc_usb_disconnect():
276
+
277
+
.. code-block:: rst
278
+
279
+
static void qc_usb_audio_offload_probe(struct snd_usb_audio *chip)
280
+
{
281
+
...
282
+
snd_soc_usb_connect(usb_get_usb_backend(udev), sdev);
283
+
...
284
+
}
285
+
286
+
static void qc_usb_audio_offload_disconnect(struct snd_usb_audio *chip)
287
+
{
288
+
...
289
+
snd_soc_usb_disconnect(usb_get_usb_backend(chip->dev), dev->sdev);
290
+
...
291
+
}
292
+
..
293
+
294
+
In order to account for conditions where driver or device existence is
295
+
not guaranteed, USB SND exposes snd_usb_rediscover_devices() to resend the
296
+
connect events for any identified USB audio interfaces. Consider the
297
+
the following situation:
298
+
299
+
**usb_audio_probe()**
300
+
| --> USB audio streams allocated and saved to usb_chip[]
301
+
| --> Propagate connect event to USB offload driver in USB SND
302
+
| --> **snd_soc_usb_connect()** exits as USB BE DAI link is not ready
303
+
304
+
BE DAI link component probe
305
+
| --> DAI link is probed and SoC USB port is allocated
306
+
| --> The USB audio device connect event is missed
307
+
308
+
To ensure connection events are not missed, **snd_usb_rediscover_devices()**
309
+
is executed when the SoC USB device is registered. Now, when the BE DAI
310
+
link component probe occurs, the following highlights the sequence:
311
+
312
+
BE DAI link component probe
313
+
| --> DAI link is probed and SoC USB port is allocated
314
+
| --> SoC USB device added, and **snd_usb_rediscover_devices()** runs
315
+
316
+
**snd_usb_rediscover_devices()**
317
+
| --> Traverses through usb_chip[] and for non-NULL entries issue
318
+
| **connection_status_cb()**
319
+
320
+
In the case where the USB offload driver is unbound, while USB SND is ready,
321
+
the **snd_usb_rediscover_devices()** is called during module init. This allows
322
+
for the offloading path to also be enabled with the following flow:
323
+
324
+
**usb_audio_probe()**
325
+
| --> USB audio streams allocated and saved to usb_chip[]
326
+
| --> Propagate connect event to USB offload driver in USB SND
327
+
| --> USB offload driver **NOT** ready!
328
+
329
+
BE DAI link component probe
330
+
| --> DAI link is probed and SoC USB port is allocated
331
+
| --> No USB connect event due to missing USB offload driver
332
+
333
+
USB offload driver probe
334
+
| --> **qc_usb_audio_offload_init()**
335
+
| --> Calls **snd_usb_rediscover_devices()** to notify of devices
336
+
337
+
USB Offload Related Kcontrols
338
+
=============================
339
+
Details
340
+
-------
341
+
A set of kcontrols can be utilized by applications to help select the proper sound
342
+
devices to enable USB audio offloading. SoC USB exposes the get_offload_dev()
343
+
callback that designs can use to ensure that the proper indices are returned to the
344
+
application.
345
+
346
+
Implementation
347
+
--------------
348
+
349
+
**Example:**
350
+
351
+
**Sound Cards**:
352
+
353
+
::
354
+
355
+
0 [SM8250MTPWCD938]: sm8250 - SM8250-MTP-WCD9380-WSA8810-VA-D
356
+
SM8250-MTP-WCD9380-WSA8810-VA-DMIC
357
+
1 [Seri ]: USB-Audio - Plantronics Blackwire 3225 Seri
358
+
Plantronics Plantronics Blackwire
359
+
3225 Seri at usb-xhci-hcd.1.auto-1.1,
360
+
full sp
361
+
2 [C320M ]: USB-Audio - Plantronics C320-M
362
+
Plantronics Plantronics C320-M at usb-xhci-hcd.1.auto-1.2, full speed
363
+
364
+
**PCM Devices**:
365
+
366
+
::
367
+
368
+
card 0: SM8250MTPWCD938 [SM8250-MTP-WCD9380-WSA8810-VA-D], device 0: MultiMedia1 (*) []
369
+
Subdevices: 1/1
370
+
Subdevice #0: subdevice #0
371
+
card 0: SM8250MTPWCD938 [SM8250-MTP-WCD9380-WSA8810-VA-D], device 1: MultiMedia2 (*) []
372
+
Subdevices: 1/1
373
+
Subdevice #0: subdevice #0
374
+
card 1: Seri [Plantronics Blackwire 3225 Seri], device 0: USB Audio [USB Audio]
375
+
Subdevices: 1/1
376
+
Subdevice #0: subdevice #0
377
+
card 2: C320M [Plantronics C320-M], device 0: USB Audio [USB Audio]
378
+
Subdevices: 1/1
379
+
Subdevice #0: subdevice #0
380
+
381
+
**USB Sound Card** - card#1:
382
+
383
+
::
384
+
385
+
USB Offload Playback Card Route PCM#0 -1 (range -1->32)
386
+
USB Offload Playback PCM Route PCM#0 -1 (range -1->255)
387
+
388
+
**USB Sound Card** - card#2:
389
+
390
+
::
391
+
392
+
USB Offload Playback Card Route PCM#0 0 (range -1->32)
393
+
USB Offload Playback PCM Route PCM#0 1 (range -1->255)
394
+
395
+
The above example shows a scenario where the system has one ASoC platform card
396
+
(card#0) and two USB sound devices connected (card#1 and card#2). When reading
397
+
the available kcontrols for each USB audio device, the following kcontrols lists
398
+
the mapped offload card and pcm device indexes for the specific USB device:
399
+
400
+
``USB Offload Playback Card Route PCM#*``
401
+
402
+
``USB Offload Playback PCM Route PCM#*``
403
+
404
+
The kcontrol is indexed, because a USB audio device could potentially have
405
+
several PCM devices. The above kcontrols are defined as:
406
+
407
+
- ``USB Offload Playback Card Route PCM#`` **(R)**: Returns the ASoC platform sound
408
+
card index for a mapped offload path. The output **"0"** (card index) signifies
409
+
that there is an available offload path for the USB SND device through card#0.
410
+
If **"-1"** is seen, then no offload path is available for the USB SND device.
411
+
This kcontrol exists for each USB audio device that exists in the system, and
412
+
its expected to derive the current status of offload based on the output value
413
+
for the kcontrol along with the PCM route kcontrol.
414
+
415
+
- ``USB Offload Playback PCM Route PCM#`` **(R)**: Returns the ASoC platform sound
416
+
PCM device index for a mapped offload path. The output **"1"** (PCM device index)
417
+
signifies that there is an available offload path for the USB SND device through
418
+
PCM device#0. If **"-1"** is seen, then no offload path is available for the USB\
419
+
SND device. This kcontrol exists for each USB audio device that exists in the
420
+
system, and its expected to derive the current status of offload based on the
421
+
output value for this kcontrol, in addition to the card route kcontrol.
422
+
423
+
USB Offload Playback Route Kcontrol
424
+
-----------------------------------
425
+
In order to allow for vendor specific implementations on audio offloading device
426
+
selection, the SoC USB layer exposes the following:
427
+
428
+
.. code-block:: rst
429
+
430
+
int (*update_offload_route_info)(struct snd_soc_component *component,
431
+
int card, int pcm, int direction,
432
+
enum snd_soc_usb_kctl path,
433
+
long *route)
434
+
..
435
+
436
+
These are specific for the **USB Offload Playback Card Route PCM#** and **USB
437
+
Offload PCM Route PCM#** kcontrols.
438
+
439
+
When users issue get calls to the kcontrol, the registered SoC USB callbacks will
440
+
execute the registered function calls to the DPCM BE DAI link.
441
+
442
+
**Callback Registration:**
443
+
444
+
.. code-block:: rst
445
+
446
+
static int q6usb_component_probe(struct snd_soc_component *component)
447
+
{
448
+
...
449
+
usb = snd_soc_usb_allocate_port(component, 1, &data->priv);
450
+
if (IS_ERR(usb))
451
+
return -ENOMEM;
452
+
453
+
usb->connection_status_cb = q6usb_alsa_connection_cb;
454
+
usb->update_offload_route_info = q6usb_get_offload_dev;
455
+
456
+
ret = snd_soc_usb_add_port(usb);
457
+
..
458
+
459
+
Existing USB Sound Kcontrol
460
+
---------------------------
461
+
With the introduction of USB offload support, the above USB offload kcontrol
462
+
will be added to the pre existing list of kcontrols identified by the USB sound
463
+
framework. These kcontrols are still the main controls that are used to
464
+
modify characteristics pertaining to the USB audio device.
465
+
466
+
::
467
+
468
+
Number of controls: 9
469
+
ctl type num name value
470
+
0 INT 2 Capture Channel Map 0, 0 (range 0->36)
471
+
1 INT 2 Playback Channel Map 0, 0 (range 0->36)
472
+
2 BOOL 1 Headset Capture Switch On
473
+
3 INT 1 Headset Capture Volume 10 (range 0->13)
474
+
4 BOOL 1 Sidetone Playback Switch On
475
+
5 INT 1 Sidetone Playback Volume 4096 (range 0->8192)
476
+
6 BOOL 1 Headset Playback Switch On
477
+
7 INT 2 Headset Playback Volume 20, 20 (range 0->24)
478
+
8 INT 1 USB Offload Playback Card Route PCM#0 0 (range -1->32)
479
+
9 INT 1 USB Offload Playback PCM Route PCM#0 1 (range -1->255)
480
+
481
+
Since USB audio device controls are handled over the USB control endpoint, use the
482
+
existing mechanisms present in the USB mixer to set parameters, such as volume.