Re: [PATCH v26 16/33] ASoC: doc: Add documentation for SOC USB

[Wesley Cheng <quic_wcheng@xxxxxxxxxxx>]

On 8/30/2024 2:03 AM, Pierre-Louis Bossart wrote:
>> diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
>> index e57df2dab2fd..8bed8f8f48da 100644
>> --- a/Documentation/sound/soc/index.rst
>> +++ b/Documentation/sound/soc/index.rst
>> @@ -18,3 +18,4 @@ The documentation is spilt into the following sections:-
>>     jack
>>     dpcm
>>     codec-to-codec
>> +   usb
>> diff --git a/Documentation/sound/soc/usb.rst b/Documentation/sound/soc/usb.rst
>> new file mode 100644
>> index 000000000000..bd3d9eb86b07
>> --- /dev/null
>> +++ b/Documentation/sound/soc/usb.rst
>> @@ -0,0 +1,429 @@
>> +================
>> +ASoC USB support
>> +================
>> +
>> +Overview
>> +========
>> +In order to leverage the existing USB sound device support in ALSA, the
>> +ASoC USB APIs are introduced to allow for the entities to communicate
>> +with one another.
> nit-pick: entities is rather vague and an overloaded term in USB audio.
> Maybe "allow the subsystems to exchange configuration information"
Sure, will make that change.
>> +One potential use case would be to support USB audio offloading, which is
>> +an implementation that allows for an external DSP on the SoC to handle the
> nit-pick: not sure about the reference to an 'external DSP'. "external"
> would usually to a stand-alone device and there's no real need for DSP
> capabilities for USB offload, e.g. a regular embedded core would do just
> fine.
>
> maybe "allows for an alternate power-optimized path in the audio
> subsystem to handle the transfer of audio data over the USB bus"
Yeah, I guess external doesn't make sense, its just another core within the SoC.
>> +transfer of audio data over the USB bus.  This would let the main
>> +processor to stay in lower power modes for longer duration.  The following
>> +is an example design of how the ASoC and ALSA pieces can be connected
>> +together to achieve this:
>> +	int snd_soc_usb_update_offload_route(struct device *dev, int card, int pcm,
>> +					     int direction, 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
>> +  - ``route``: mapping of sound card and pcm indexes for the offload path
> nit-pick: again explain how the card and pcm indices are handled.
>
Will do.
>> +--------------------------------
>> +USB devices can be hotplugged into the USB root hub at any point in time.
> "root hub" really?
>
> Is this really required? I would think the entire framework would work
> just fine if the device is connected to any hub at any level, not just
> "the" root hub.

Yes, you're right. Will clarify this as well.  My test set up for this involves doing audio transfers on multiple devices over an external 4port USB hub.

Thanks

Wesley Cheng

>