Message-ID: <20240928150905.2616313-1-crwulff@gmail.com>
Date: Sat, 28 Sep 2024 11:08:51 -0400
From: crwulff@...il.com
To: linux-usb@...r.kernel.org
Cc: Pavel Hofman <pavel.hofman@...tera.com>,
	Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
	James Gruber <jimmyjgruber@...il.com>,
	Jeff Johnson <quic_jjohnson@...cinc.com>,
	John Keeping <jkeeping@...usicbrands.com>,
	Jonathan Corbet <corbet@....net>,
	Lee Jones <lee@...nel.org>,
	Perr Zhang <perr@...7.net>,
	linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org
Subject: [PATCH RFC 00/14] usb: gadget: f_uac: Add support for alt mode settings

This patch series adds support for additional alternate settings for
UAC1/2 gadgets. See references [2] and [3] for discussions on the API.


*** Userspace API ***

* Add the ability to create c_alt.x and p_alt.x directories
  under the function with settings that are available per alternate mode.

  The existing API is preserved and used as defaults when creating c/p_alt.x.
  Subsequent changes to the function-wide settings don't change existing
  c/p_alt.x directories.

  If no directories for c/p_alt.1 exist, alternate setting 1 will continue
  to be created  from the function-wide settings.

  Settings that can be changed per-alt-mode (bAlternateSetting):
  - name               (iInterface     - Interface Descriptor name)
  - chmask             (wChannelConfig - Channel mask)
  - ssize              (bSubframeSize  - Sample size bytes)
  - terminal_type      (wTerminalType  - Terminal Type)
  - sync (OUT only)    (bmAttributes   - Endpoint Synch Type)
  - hs_bint            (bInterval      - Used for HS and above, 0=auto)
  - Terminal names     (see below)

* Add the ability to set terminal name strings. Defaults are the same as
  the hard-coded strings that were present in UAC1/2 functions. These are
  now present as p_/c_ function-wide variants and in p/c_alt.x directories.
  (Note: UAC1 defaults aren't the same as UAC2)
  These are now settable with:
  - it_name     (iTerminal     - Input Terminal name)
  - it_ch_name  (iChannelNames - Input Terminal first channel name)
  - fu_vol_name (iFeature      - Feature Unit, for mute/volume, name)
  - ot_name     (iTerminal     - Output Terminal name)

* UAC1 specific UAPI changes (to bring it up to parity with UAC2)
 - Added support for c_sync (support for USB Out ASYNC mode)
 - Added support for p/c_terminal_type (note that these DO correct the
   order from UAC2 so they follow the device centric view, and align with
   the other c/p options)
 - Added p/c_hs_bint


*** Descriptors ***

* Strings are now dynamically allocated as needed. For simplicity the
  algorithm is O(n^2) and allocates the maximum table size (256) (2KB on
  64-bit systems.) This allows multiple path descriptors to reuse the same
  string ids if they are all named the same.

* Path descriptors (Input Terminal -> <Feature Unit> -> Output Terminal)
  are now created based on differences in settings. Any differences in
  names or chmask will create a new set of terminals.

* Descriptors for each alternate setting are now attached to those settings
  and many global descriptors are removed. Maximum size for each alternate
  setting is calculated for its enpoints. All alternate settings use the
  same set of endpoint numbers though.

* Differences from previously created descriptors with the default settings
  - String IDs are allocated differently. Referenced strings all match but
    have different numbers.
  - Unit/Terminal IDs are allocated differently. Source IDs/Associated
    Terminal numbers are different, but reference the same terminals.
  - UAC2 Terminal descriptors are not quite in the same order.
    Old order was IT, FU, IT, FU, OT, OT. Now it is IT, FU, OT, IT, FU, OT.
    This change in order doesn't really matter, but will show up if you
    look at a diff between the two.
  - UAC1 Endpoint wMaxPacketSize was hard-coded to 200. Calcluated value
    is now 196 for default settings.

* UAC1 Specific Bug Fixes
  - LowSpeed interval is fixed (bInterval was 4 for all speeds)
  - SuperSpeed descriptors are fixed. The old implementation had only
    partial support for SuperSpeed and creates invalid descriptors in
    the default case. (Turning off volume/mute control is the only
    working case for SuperSpeed.)


*** Back-end Functionality ***

* Volume Mute Controls
  - When using a combination of alt modes that requires separate terminals
    the volume/mute functional unit must also be duplicated. This causes
    there to be multiple volume controls on the USB side. In this case,
    there is still only one volume/mute control on the ALSA side and
    all associated instances on the USB side are synchronized. (Changing
    any one of the associated volume/mute controls causes the others to
    be updated to the same value.)


*** Remaining Work ***

* Alternate settings aren't yet updating the u_audio back end so
  the function-wide settings are all that is used by the ALSA interface.
  This effectively means that changing any settings that affect the
  audio samples (ssize/chmask) won't yet pass good audio.

* Testing. Defaults and a few random combination have been tested with
  the Dummy HCD driver (with patch [1] to allow isochronous endpoints) but
  no audio testing has been done yet (just UAPI and descriptor testing.)

These are both pending my having a target that has an up-to-date kernel
for some real hardware testing. This is in-progress but may take a bit
to get working as my current device is running 4.19.168.


*** Deficiencies (not planned to fix) ***

* There appears to be no way to prevent removal of c_alt.x/p_alt.x
  while the function is bound. (This is not unique to these folders,
  as other folders may be removed after a function is bound and UDC set.)
  This doesn't appear to cause any critical failures, but removing
  c_alt.x/p_alt.x while the gadget is active will cause those alt modes
  to no longer function correctly.


*** References ***

[1] https://lore.kernel.org/linux-usb/20220126132249.2133168-1-m.grzeschik@pengutronix.de/

    Patch for partial ISOC support in dummy_hcd. As the patch mentions,
    this is only useful for validating non-ISOC parts of gadgets, but
    does allow them to bind for testing of descriptors at least.

[2] https://lore.kernel.org/linux-usb/CO1PR17MB54195BE778868AFDFE2DCB36E1112@CO1PR17MB5419.namprd17.prod.outlook.com/

    Discussion thread on UAPI for adding strings

[3] https://lore.kernel.org/linux-usb/35be4668-58d3-894a-72cf-de1afaacae45@ivitera.com/

    Discussion thread on UAPI for adding alt modes

Powered by blists - more mailing lists