Structures¶

structsnd_soc_usb

• list: list head for SND SoCstructlist

• component: reference to ASoC component

• connection_status_cb: callback to notify connection events

• update_offload_route_info: callback to fetch selected USB sound card/PCMdevice

• priv_data: driver data

The snd_soc_usb structure can be referenced using the ASoC platform carddevice, or a USB device (udev->dev). This is created by the ASoC BE DAIlink, and the USB sound entity will be able to pass information to theASoC BE DAI link using this structure.

structsnd_soc_usb_device

• card_idx: sound card index associated with USB sound device

• chip_idx: USB sound chip array index

• cpcm_idx: capture pcm device indexes associated with the USB sound device

• ppcm_idx: playback pcm device indexes associated with the USB sound device

• num_playback: number of playback streams

• num_capture: number of capture streams

• list: list head for the USB sound device list

Thestructsnd_soc_usb_device is created by the USB sound offload driver.This will carry basic parameters/limitations that will be used todetermine the possible offloading paths for this USB audio device.

Functions¶

int snd_soc_usb_find_supported_format(int card_idx,                struct snd_pcm_hw_params *params, int direction)

• card_idx: the index into the USB sound chip array.

• params: Requested PCM parameters from the USB DPCM BE DAI link

• direction: capture or playback

snd_soc_usb_find_supported_format() ensures that the requested audio profilebeing requested by the external DSP is supported by the USB device.

Returns 0 on success, and -EOPNOTSUPP on failure.

int snd_soc_usb_connect(struct device*usbdev, struct snd_soc_usb_device *sdev)

• usbdev: the usb device that was discovered

• sdev: capabilities of the device

snd_soc_usb_connect() notifies the ASoC USB DCPM BE DAI link of a USBaudio device detection. This can be utilized in the BE DAIdriver to keep track of available USB audio devices. This is intendedto be called by the USB offload driver residing in USB SND.

Returns 0 on success, negative error code on failure.

int snd_soc_usb_disconnect(struct device*usbdev, struct snd_soc_usb_device *sdev)

• usbdev: the usb device that was removed

• sdev: capabilities to free

snd_soc_usb_disconnect() notifies the ASoC USB DCPM BE DAI link of a USBaudio device removal. This is intended to be called by the USB offloaddriver that resides in USB SND.

void*snd_soc_usb_find_priv_data(struct device *usbdev)

• usbdev: the usb device to reference to find private data

snd_soc_usb_find_priv_data() fetches the private data saved to the SoC USBdevice.

Returns pointer to priv_data on success, NULL on failure.

int snd_soc_usb_setup_offload_jack(struct snd_soc_component *component,                                struct snd_soc_jack *jack)

• component: ASoC component to add the jack

• jack: jack component to populate

snd_soc_usb_setup_offload_jack() is a helper to add a sound jack control tothe platform sound card. This will allow for consistent naming to be used ondesigns that support USB audio offloading. Additionally, this will enable thejack to notify of changes.

Returns 0 on success, negative otherwise.

int snd_soc_usb_update_offload_route(struct device *dev, int card, int pcm,                                     int direction, enum snd_soc_usb_kctl path,                                     long *route)

• dev: USB device to look up offload path mapping

• card: USB sound card index

• pcm: USB sound PCM device index

• direction: direction to fetch offload routing information

• path: kcontrol selector - pcm device or card index

• route: mapping of sound card and pcm indexes for the offload path. This is

  an array of two integers that will carry the card and pcm device indexesin that specific order. This can be used as the array for the kcontroloutput.

snd_soc_usb_update_offload_route() calls a registered callback to the USB BE DAIlink to fetch the information about the mapped ASoC devices for executing USB audiooffload for the device.route may be a pointer to a kcontrol value output array,which carries values when the kcontrol is read.

Returns 0 on success, negative otherwise.

struct snd_soc_usb*snd_soc_usb_allocate_port(struct snd_soc_component *component,                void *data);

• component: DPCM BE DAI link component

• data: private data

snd_soc_usb_allocate_port() allocates a SoC USB device and populates standardparameters that is used for further operations.

Returns a pointer tostructsoc_usb on success, negative on error.

void snd_soc_usb_free_port(struct snd_soc_usb *usb);

• usb: SoC USB device to free

snd_soc_usb_free_port() frees a SoC USB device.

void snd_soc_usb_add_port(struct snd_soc_usb *usb);

• usb: SoC USB device to add

snd_soc_usb_add_port() add an allocated SoC USB device to the SOC USB framework.Once added, this device can be referenced by further operations.

void snd_soc_usb_remove_port(struct snd_soc_usb *usb);

• usb: SoC USB device to remove

snd_soc_usb_remove_port() removes a SoC USB device from the SoC USB framework.After removing a device, any SOC USB operations would not be able to reference thedevice removed.

How to Register to SoC USB¶

The ASoC DPCM USB BE DAI link is the entity responsible for allocating andregistering the SoC USB device on the component bind. Likewise, it willalso be responsible for freeing the allocated resources. An example canbe shown below:

static int q6usb_component_probe(struct snd_soc_component *component){        ...        data->usb = snd_soc_usb_allocate_port(component, 1, &data->priv);        if (!data->usb)                return -ENOMEM;        usb->connection_status_cb = q6usb_alsa_connection_cb;        ret = snd_soc_usb_add_port(usb);        if (ret < 0) {                dev_err(component->dev, "failed to add usb port\n");                goto free_usb;        }        ...}static void q6usb_component_remove(struct snd_soc_component *component){        ...        snd_soc_usb_remove_port(data->usb);        snd_soc_usb_free_port(data->usb);}static const struct snd_soc_component_driver q6usb_dai_component = {        .probe = q6usb_component_probe,        .remove = q6usb_component_remove,        .name = "q6usb-dai-component",        ...};

BE DAI links can pass along vendor specific information as part of thecall to allocate the SoC USB device. This will allow any BE DAI linkparameters or settings to be accessed by the USB offload driver thatresides in USB SND.

USB Audio Device Connection Flow¶

USB devices can be hotplugged into the USB ports at any point in time.The BE DAI link should be aware of the current state of the physical USBport, i.e. if there are any USB devices with audio interface(s) connected.connection_status_cb() can be used to notify the BE DAI link of any change.

This is called whenever there is a USB SND interface bind or remove event,usingsnd_soc_usb_connect() orsnd_soc_usb_disconnect():

static void qc_usb_audio_offload_probe(struct snd_usb_audio *chip){        ...        snd_soc_usb_connect(usb_get_usb_backend(udev), sdev);        ...}static void qc_usb_audio_offload_disconnect(struct snd_usb_audio *chip){        ...        snd_soc_usb_disconnect(usb_get_usb_backend(chip->dev), dev->sdev);        ...}

In order to account for conditions where driver or device existence isnot guaranteed, USB SND exposessnd_usb_rediscover_devices() to resend theconnect events for any identified USB audio interfaces. Consider thethe following situation:

usb_audio_probe()

--> USB audio streams allocated and saved to usb_chip[]

--> Propagate connect event to USB offload driver in USB SND

-->snd_soc_usb_connect() exits as USB BE DAI link is not ready

BE DAI link component probe

--> DAI link is probed and SoC USB port is allocated

--> The USB audio device connect event is missed

To ensure connection events are not missed,snd_usb_rediscover_devices()is executed when the SoC USB device is registered. Now, when the BE DAIlink component probe occurs, the following highlights the sequence:

BE DAI link component probe

--> DAI link is probed and SoC USB port is allocated

--> SoC USB device added, andsnd_usb_rediscover_devices() runs

snd_usb_rediscover_devices()

--> Traverses through usb_chip[] and for non-NULL entries issue

connection_status_cb()

In the case where the USB offload driver is unbound, while USB SND is ready,thesnd_usb_rediscover_devices() is called during module init. This allowsfor the offloading path to also be enabled with the following flow:

usb_audio_probe()

--> USB audio streams allocated and saved to usb_chip[]

--> Propagate connect event to USB offload driver in USB SND

--> USB offload driverNOT ready!

BE DAI link component probe

--> DAI link is probed and SoC USB port is allocated

--> No USB connect event due to missing USB offload driver

USB offload driver probe

-->qc_usb_audio_offload_init()

--> Callssnd_usb_rediscover_devices() to notify of devices

Details¶

A set of kcontrols can be utilized by applications to help select the proper sounddevices to enable USB audio offloading. SoC USB exposes theget_offload_dev()callback that designs can use to ensure that the proper indices are returned to theapplication.

Implementation¶

Example:

Sound Cards:

0 [SM8250MTPWCD938]: sm8250 - SM8250-MTP-WCD9380-WSA8810-VA-D                                      SM8250-MTP-WCD9380-WSA8810-VA-DMIC1 [Seri           ]: USB-Audio - Plantronics Blackwire 3225 Seri                                      Plantronics Plantronics Blackwire                                      3225 Seri at usb-xhci-hcd.1.auto-1.1,                                      full sp2 [C320M          ]: USB-Audio - Plantronics C320-M            Plantronics Plantronics C320-M at usb-xhci-hcd.1.auto-1.2, full speed

PCM Devices:

card 0: SM8250MTPWCD938 [SM8250-MTP-WCD9380-WSA8810-VA-D], device 0: MultiMedia1 (*) []Subdevices: 1/1Subdevice #0: subdevice #0card 0: SM8250MTPWCD938 [SM8250-MTP-WCD9380-WSA8810-VA-D], device 1: MultiMedia2 (*) []Subdevices: 1/1Subdevice #0: subdevice #0card 1: Seri [Plantronics Blackwire 3225 Seri], device 0: USB Audio [USB Audio]Subdevices: 1/1Subdevice #0: subdevice #0card 2: C320M [Plantronics C320-M], device 0: USB Audio [USB Audio]Subdevices: 1/1Subdevice #0: subdevice #0

USB Sound Card - card#1:

USB Offload Playback Card Route PCM#0   -1 (range -1->32)USB Offload Playback PCM Route PCM#0    -1 (range -1->255)

USB Sound Card - card#2:

USB Offload Playback Card Route PCM#0   0 (range -1->32)USB Offload Playback PCM Route PCM#0    1 (range -1->255)

The above example shows a scenario where the system has one ASoC platform card(card#0) and two USB sound devices connected (card#1 and card#2). When readingthe available kcontrols for each USB audio device, the following kcontrols liststhe mapped offload card and pcm device indexes for the specific USB device:

USBOffloadPlaybackCardRoutePCM#*

USBOffloadPlaybackPCMRoutePCM#*

The kcontrol is indexed, because a USB audio device could potentially haveseveral PCM devices. The above kcontrols are defined as:

• USBOffloadPlaybackCardRoutePCM#(R): Returns the ASoC platform soundcard index for a mapped offload path. The output“0” (card index) signifiesthat there is an available offload path for the USB SND device through card#0.If“-1” is seen, then no offload path is available for the USB SND device.This kcontrol exists for each USB audio device that exists in the system, andits expected to derive the current status of offload based on the output valuefor the kcontrol along with the PCM route kcontrol.

• USBOffloadPlaybackPCMRoutePCM#(R): Returns the ASoC platform soundPCM device index for a mapped offload path. The output“1” (PCM device index)signifies that there is an available offload path for the USB SND device throughPCM device#0. If“-1” is seen, then no offload path is available for the USBSND device. This kcontrol exists for each USB audio device that exists in thesystem, and its expected to derive the current status of offload based on theoutput value for this kcontrol, in addition to the card route kcontrol.

USB Offload Playback Route Kcontrol¶

In order to allow for vendor specific implementations on audio offloading deviceselection, the SoC USB layer exposes the following:

int (*update_offload_route_info)(struct snd_soc_component *component,                                 int card, int pcm, int direction,                                 enum snd_soc_usb_kctl path,                                 long *route)

These are specific for theUSB Offload Playback Card Route PCM# andUSBOffload PCM Route PCM# kcontrols.

When users issue get calls to the kcontrol, the registered SoC USB callbacks willexecute the registered function calls to the DPCM BE DAI link.

Callback Registration:

static int q6usb_component_probe(struct snd_soc_component *component){...usb = snd_soc_usb_allocate_port(component, 1, &data->priv);if (IS_ERR(usb))        return -ENOMEM;usb->connection_status_cb = q6usb_alsa_connection_cb;usb->update_offload_route_info = q6usb_get_offload_dev;ret = snd_soc_usb_add_port(usb);

Existing USB Sound Kcontrol¶

With the introduction of USB offload support, the above USB offload kcontrolwill be added to the pre existing list of kcontrols identified by the USB soundframework. These kcontrols are still the main controls that are used tomodify characteristics pertaining to the USB audio device.

Number of controls: 9ctl     type    num     name                                    value0       INT     2       Capture Channel Map                     0, 0 (range 0->36)1       INT     2       Playback Channel Map                    0, 0 (range 0->36)2       BOOL    1       Headset Capture Switch                  On3       INT     1       Headset Capture Volume                  10 (range 0->13)4       BOOL    1       Sidetone Playback Switch                On5       INT     1       Sidetone Playback Volume                4096 (range 0->8192)6       BOOL    1       Headset Playback Switch                 On7       INT     2       Headset Playback Volume                 20, 20 (range 0->24)8       INT     1       USB Offload Playback Card Route PCM#0   0 (range -1->32)9       INT     1       USB Offload Playback PCM Route PCM#0    1 (range -1->255)

Since USB audio device controls are handled over the USB control endpoint, use theexisting mechanisms present in the USB mixer to set parameters, such as volume.