Re: [RFC PATCH v5 8/8] Documentation: sound: add the Babyface Pro proprietary-mode design doc

[Randy Dunlap]

Hi,
Just one nit below...

On 9/18/26 4:39 AM, Ismaïl Bahloul wrote:
> A big-picture companion to the patch series, for human reviewers:
> why the proprietary mode needs a standalone driver instead of a
> snd-usb-audio quirk, the vendor protocol's write-only/no-readback
> shape and what that forces onto the driver, the asynchronous stream
> model, why the mixer state has to be cached and replayed, and why
> the driver has to emulate TotalMix's own role for the front panel.
> 
> Requested by Takashi Iwai's v4 review: documentation for reviewers,
> not restating what the code comments already say inline.
> 
> Signed-off-by: Ismaïl Bahloul <i.bahloul01@xxxxxxxxx>
> ---
>  Documentation/sound/cards/babyface-pro.rst | 163 +++++++++++++++++++++
>  Documentation/sound/cards/index.rst        |   1 +
>  2 files changed, 164 insertions(+)
>  create mode 100644 Documentation/sound/cards/babyface-pro.rst
> 
> diff --git a/Documentation/sound/cards/babyface-pro.rst b/Documentation/sound/cards/babyface-pro.rst
> new file mode 100644
> index 000000000..d67f8c6fe
> --- /dev/null
> +++ b/Documentation/sound/cards/babyface-pro.rst
> @@ -0,0 +1,163 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=================================================
> +RME Babyface Pro / Pro FS (snd-usb-babyface-pro)
> +=================================================
> +
> +This document describes the design of the ``snd-usb-babyface-pro``
> +driver for reviewers who need the big picture before reading the
> +patches - what problem the driver solves, why it is a standalone
> +driver instead of a snd-usb-audio quirk, and the four design
> +decisions (stream model, protocol shape, mixer-state persistence,
> +front-panel emulation) that shape most of the code.  The patch series
> +itself is split by feature (core+PCM, then masters+crosspoint,
> +preamp, routing flags, suspend/resume, front panel, DSP EQ, in that
> +order) so each patch can be read and built on its own; this document
> +does not repeat what each patch's own commit message already covers.
> +
> +Two USB personalities, one device
> +==================================
> +
> +The RME Babyface Pro and Babyface Pro FS present two different USB
> +configurations depending on a physical/firmware switch: a
> +class-compliant one, already handled by ``snd-usb-audio``, and a
> +proprietary one (USB ID ``2a39:3fc0``) that this driver covers.  The
> +two hardware models share the same USB ID, ``bcdDevice`` and
> +``iProduct`` string shape; nothing in the descriptors tells them
> +apart, and the driver runs unmodified on both.
> +
> +In proprietary mode, interface 5 carries the PCM stream on two
> +INTERRUPT endpoints (``0x01`` OUT, ``0x82`` IN) instead of the
> +isochronous endpoints the USB Audio Class specifies.  Isochronous
> +transfers are rejected there with ``-EINVAL``.  ``snd-usb-audio`` has
> +no interrupt-PCM transport, so this mode cannot be a quirk on top of
> +it; the driver is standalone, modelled on ``snd-usb-caiaq`` (another
> +interrupt-streaming RME/NI-style device).
> +
> +Why interrupt endpoints and not isochronous is a hardware/firmware
> +choice on RME's side, not something this driver can change - the
> +class-compliant mode already exists on the same device for users who
> +want a fully standard, quirk-free path with a subset of the
> +functionality (no mixer, no front panel).  This driver is for users
> +who want the full mixer, routing matrix, and hardware DSP EQ that
> +only the proprietary mode exposes.
> +
> +The vendor protocol: writes only, no readback
> +==============================================
> +
> +Every mixer and clock function is one of a handful of USB vendor
> +control requests (``bmRequestType 0x40``, i.e. host-to-device,
> +vendor, device-recipient), each identified by its request number and
> +a 16-bit value/index pair - there is no larger command structure.
> +The commonly used ones are:
> +
> +======  ========================================
> +0x10    settings word / stream start trigger
> +0x12    16-bit crosspoint and output-master writes
> +0x16    cold-init register clear
> +0x17    front-panel + preamp state (read and write)
> +0x1a    8-bit gain / output-master companion writes
> +0x1b    clock DDS quads (base rate and varispeed)
> +======  ========================================
> +
> +The full register map, decoded from Windows USB captures and
> +cross-checked against hardware, lives in the driver's own development
> +repository (not shipped in-tree) - the constants and the comments
> +next to each vendor write in the source are the authoritative
> +in-tree reference.
> +
> +The one property that shapes the rest of the driver: **almost nothing
> +here is readable back**.  The 0x17 request returns the front-panel

   here can be read back**.

> +and preamp state, but the crosspoint matrix, the output masters, the
> +routing flags and the clock all have to be tracked host-side - the
> +device will accept a write blindly and never confirm what it actually
> +holds.  Two consequences follow directly from this:
-- 
~Randy