Inside snd-fireface-ucx
A walk through the whole project: how the RME Fireface UCX talks over USB, how the kernel module turns that into an ALSA sound card with 244 controls, and how libucx, ucxcfg and ucxtui drive it from user space. Each chapter shows the real code, and the panels let you work the protocol by hand.
0x3f990812 · the dump request
one DSP command word, bulk OUT 0x0cWrite register 0x3f99 = 0x0812 and the unit answers on 0x8d with all 1636 of its registers. The driver sends this word at probe, and every register table and ALSA control value starts from that answer.
Contents
The map: who talks to whom
The project has three layers. At the bottom is the unit, which exposes six USB interfaces. In the middle is the kernel module, which claims four of them and publishes an ALSA card with a PCM device, a control device, a hwdep device and two MIDI ports. On top are the user-space tools. None of them speaks USB except ucxctl, the test bench. The others go through ALSA.
Click a box for what it does and where its code lives. Pick a path to trace one flow of data from end to end.
System map
click a box · or trace a pathUSB in ten minutes, as this device uses it
A USB device has one configuration made of interfaces. Each interface has one or more alternate settings, and each alt setting lists endpoints. An endpoint is a one-way pipe with an address: bit 7 set means IN (device to host), so 0x82 is IN endpoint 2 and 0x01 is OUT endpoint 1. Endpoint 0 is the control pipe every device has.
Each endpoint has one of four transfer types, and the type decides what the host controller guarantees:
Control (EP 0)
Setup packet plus optional data. Used for vendor requests: bmRequestType 0x40/0xc0, a request number, wValue, wIndex. The UCX's clock and hardware settings (REG1), stream start and status reads go here. In the kernel: usb_control_msg().
Bulk
Gets whatever bandwidth is left, with no timing promise, but delivery is guaranteed and retried. The DSP command words (0x0c), their replies (0x8d), the meters (0x85) and MIDI use bulk. In the kernel: usb_bulk_msg() or a bulk URB.
Interrupt
Bandwidth is reserved and the host polls every bInterval. The UCX streams audio this way. The device NAKs until it has data or room, so the device's clock paces the stream. In the kernel: usb_fill_int_urb().
The fourth type, isochronous, has reserved bandwidth and no retries. Class-compliant USB audio uses it, and so does snd-usb-audio. The UCX's interface 0 has isochronous endpoints, but RME's Windows driver never uses them. In RME mode the audio goes over interrupt endpoints. This is the main reason snd-usb-audio can't drive this mode and the project needs its own driver.
| Interface | Endpoints | Type | Used for | Driver |
|---|---|---|---|---|
| 0 | 0x0e / 0x8f | isoc | unknown; Windows ignores it | unused |
| 1 | 0x0c → / 0x8d ← | bulk | DSP command words and the unit's register reports | claimed: ucx_mixer.c |
| 1 | 0x85 ← | bulk | level meters, 5 banks of 20 channels | claimed: ucx_mixer.c |
| 2 | 0x07 → / 0x86 ← | bulk | standard USB-MIDI class, 2 ports | claimed: snd-usbmidi-lib |
| 3 | 0x09 → / 0x88 ← | bulk | flash programming, 256-byte blocks | never touched |
| 4 | 0x8b ← | interrupt | 4-byte device events (stream start bursts, errors) | claimed: ucx_mixer.c |
| 5 | 0x01 → / 0x82 ← (+ 0x03 / 0x84 at quad) | interrupt | audio; alt setting 1/2/3 = speed class | bound: probe, ucx_pcm.c |
URBs: the unit of asynchronous USB I/O
A URB (USB Request Block) is a request you hand to the USB core: endpoint, buffer, length, and a completion callback. usb_submit_urb() returns at once. The host controller does the transfer, and later your callback runs in atomic context (interrupt or softirq). That means no sleeping, no mutexes and only GFP_ATOMIC allocations. Streaming drivers keep several URBs in flight and resubmit each one from its own completion, so the endpoint never runs dry.
The blocking helpers usb_control_msg() and usb_bulk_msg() build a URB, submit it and wait. They can only be called where sleeping is allowed (process context). That one rule shapes most of the driver: anything that has to talk to the unit from a completion handler is deferred to a workqueue.
Every protocol fact in this repo names the address in RME's Windows driver (fireface_usb_amd.sys 1.2.77) where it was found, so you can check it again later. Facts not yet confirmed on a unit are marked UNVERIFIED in ucx_proto.h. It's a good habit for any reverse-engineered driver.
Probe, disconnect and the card's lifetime
The USB core matches a device against each driver's id_table and calls probe once per interface. The UCX has six interfaces, but the driver wants exactly one sound card. So probe ignores every interface except 5 (audio). From there it claims interfaces 1, 2 and 4 itself with usb_driver_claim_interface(), so no other driver can bind them. Step through the sequence:
Disconnect runs up to four times
Because the driver claimed four interfaces, the USB core calls disconnect once for each. The first call tears everything down and clears the intfdata pointers. The later calls find NULL and return. snd_card_free_when_closed() keeps the memory until the last open file handle (PipeWire, alsamixer) is closed.
Teardown order matters
snd_card_disconnect() first, so new opens fail and running streams are stopped. Then MIDI, the mixer (kill reply and event URBs, cancel works) and the PCM (kill stream URBs, free them). Each cancel_work_sync() comes after the URB kills, so a late completion can't schedule the work again.
Struct layout: one allocation for the whole card
snd_card_new(..., sizeof(*ucx), &card) allocates struct ucx as the card's private_data, so the driver state lives and dies with the card. kmod/ucx.h is worth reading in full. Every field has a comment saying which lock guards it and which context touches it.
Stream layout: blocks, speed classes and latency
The UCX streams in blocks. A block is one interrupt packet, and its size is the endpoint's wMaxPacketSize in the chosen alt setting. A block always holds 8, 16 or 32 frames, so at 48 kHz, 96 kHz or 192 kHz it is the same 1/6000 s slice of time. More frames per block leaves room for fewer channels: 18 at single speed, 14 at double, and 12 at quad, where they are split over two endpoint pairs.
There is no packet header. Samples are interleaved little-endian 32-bit words with 24 valid bits at the top. ALSA calls that S32_LE with msbits = 24. The driver copies bytes and never converts a sample.
Stream calculator
the math in ucx_proto.h, liveucx_proto.h is plain C made of static inline functions. It compiles in the kernel (via ccflags-y := -I$(src)/../include in kmod/Kbuild) and in user space. The tools and the driver therefore agree on every encoding, and tests/proto.c checks the integer dB math against libm without a unit attached.
The PCM engine
ALSA's PCM layer owns a ring buffer (runtime->dma_area). The application writes into it, through mmap or write(), ahead of an application pointer. The driver consumes from it at the hardware pointer, which it reports through the .pointer callback. The buffer is split into periods. Each time the hardware pointer crosses a period boundary, the driver calls snd_pcm_period_elapsed(), which wakes the application to refill.
Most PCI drivers point the sound chip's DMA straight at that ring. A USB driver can't, so it copies between the ring and URB buffers in every completion. This driver allocates the ring with SNDRV_DMA_TYPE_VMALLOC and sets SNDRV_PCM_INFO_BATCH to tell ALSA that the pointer moves in chunks.
| Callback | Context | What this driver does |
|---|---|---|
open | process | Sets runtime->hw and adds hw rules: channels follow the rate (18/14/12), the rate follows the channels, and the period is a whole number of URBs. If the engine already runs, the rate is pinned to it, since both directions share the device clock. |
hw_params | process | Not set. The managed buffer (snd_pcm_set_managed_buffer_all) allocates the ring for it. |
prepare | process, sleeps | Starts the engine if it isn't running (ucx_engine_start: alt setting, REG1, START_AT, submit URBs, CHANNELS). Resets this direction's positions. |
trigger | atomic | Never touches USB. START only arms the stream (sets s->substream, armed); STOP detaches it. URBs keep flowing either way. |
pointer | atomic | Returns s->hwptr under stream_lock. |
hw_free | process | Clears this direction's prepared bit and stops the engine once neither direction is prepared. |
The engine is always duplex. Once either direction is prepared, playback and capture URBs both run, and the unpopulated direction plays silence or drops data. The unit clocks both endpoints together, so starting them separately would leave the playback-to-capture offset (the round trip) different from one start to the next.
Engine, slowed down
48 kHz · one block = 8 framesCompletion handlers: the hot path
Each completed URB is one fixed slice of the unit's time. The playback handler fills the URB from the ring and resubmits it at once. The capture handler first runs ucx_tick() (on the first pair only), pulls the S/PDIF channel status out of the samples' low byte, copies into the ring and resubmits.
ucx_copy() does the ring arithmetic. With one endpoint pair, a URB is a contiguous chunk that may wrap once at the end of the ring, hence first and rest. At quad speed each pair carries six channels, which are one slice of every interleaved frame, so it copies frame by frame. Each pair keeps its own position, and the position reported to ALSA belongs to the pair that is behind.
Why a period must be whole URBs
ucx_copy() moves a whole URB at a time and handles at most one wrap. ucx_rule_period() rounds the allowed period sizes to multiples of urb_blocks × frames_per_block, so period interrupts arrive on time and the copy never straddles two wraps. prepare checks it again, because urb_blocks is a writable module parameter.
Signed-difference sequence compares
(int)(seq - s->start_seq) >= 0 is the kernel's wrap-safe way to compare counters (the same idea as time_after()). The counters are unsigned int and overflow after a few days of streaming. A plain >= would break when they do.
Starting at the same instant: ucx_tick()
trigger runs in atomic context, at any moment between two completions. If it attached the stream right away, playback might start one URB earlier or later than capture, and the measured round trip would vary by 16 frames from run to run. Instead trigger only sets armed. The next completion of capture endpoint 0x82, the device's clock, picks one URB sequence number that every endpoint still has ahead of it. All completions of one host controller run in order in one context, so this is the one place where both directions' counters have a fixed relation.
The start sequence
ucx_engine_start() is the order RME's driver uses, checked from user space with ucxctl before it went into the kernel:
usb_set_interface(udev, 5, speed_class). The alt setting sizes the endpoints for one block. The driver checkswMaxPacketSizeequalsucx_bytes_per_block(rate).- REG1 rate bits (
0x10, mask0x0030), only if the rate changed. Any write, even of the same value, makes the unit reload its stored mixer a few seconds later. After a load the driver first reads STATUS (0x11) to learn the current rate. - REG1 large-buffer bit (
0x8000), then START_AT (0x1d, value 0 = now). - Fill and submit the URBs in the Windows order
0x03, 0x84, 0x01, 0x82: 2 playback URBs per OUT endpoint (that queue is the output latency) and 8 capture URBs per IN endpoint (waiting IN URBs add no latency). - CHANNELS (
0x14) with the channel mask. Without it the unit accepts OUT packets and the DSP never sees them.
When a URB fails
A failed stream URB loses its slice of time, and the endpoints no longer count the same URBs. So the driver doesn't resubmit it. ucx_stream_error() sets a flag (once) and schedules stream_err_work. In process context, that work stops the engine, restarts it at the same rate (at most 5 restarts per 10 s), and calls snd_pcm_stop_xrun() on running substreams so the client prepares again from a known position. The read-only controls Stream Restarts and Stream Errors count these. They match the two numbers in RME's Windows Settings dialog.
DSP command words
All of the mixer, every EQ and compressor, reverb and echo, and most settings live in DSP registers. Writing one means sending a 32-bit little-endian word on bulk endpoint 0x0c. The format is the same one RME's FireWire "latter" models use, which is why snd-firewire-ctl-services and oscmix helped so much.
- bit 31: odd parity. The whole word must have an odd number of 1 bits.
- bits 30:16: register. Per-channel registers are
channel << 8 | parameter: inputs are channels 0–17 and outputs 18–35. Bit 30 set (register ≥0x4000) is a mixer gain:0x4000 + 64·output + source, where source is an input 0–17 or0x20+ a playback channel. - bits 15:0: the value, signed where that makes sense.
Word workbench
encode · decode · nothing is sentMixer gains are linear: 32768 is 0 dB and 65536 is +6 dB. That doesn't fit in 15 bits, so bit 15 works as an exponent flag. Small gains are stored as they are (15-bit two's complement), and gains with magnitude ≥ 0x4000 are stored divided by 8. Decoding (ucx_mix_signed()) sign-extends from bit 14 and multiplies by 8 when bit 15 is set. A negative gain inverts the phase: −0 dB is 0xf000.
The 128-word buffer that can wedge
The unit buffers 128 words and applies about 12 per millisecond. If a host overflows that buffer, every later transfer on 0x0c times out for 20 s to over 2 minutes. The driver therefore holds every sender to 2 words per millisecond (a usleep_range of 0.5 ms per word after each transfer) and caps one transfer at 63 words, like TotalMix. Try it in the model below:
Command buffer model
fill = sent − 12 words/ms draineddsp_buf is kmalloc'ed once and reused, not a stack array. USB transfer buffers must be DMA-able, and kernel stacks (vmalloc'ed with CONFIG_VMAP_STACK) are not. The same reason explains the kmalloc in ucx_vendor_read32() for a single 4-byte read.
Reading the unit back: the register table
The unit can't answer a "read register X" request. Instead it reports register changes as words in the same format on bulk IN 0x8d, as long as the host keeps polling with 0x3f00000N (N cycling 0–15, as TotalMix does). That includes changes made on the front panel. The 0x3f99 = 0x0812 request makes it report everything at once.
The driver keeps one bulk URB on 0x8d at all times, and stores every report in u16 regs[0x8000] plus a reg_seen bitmap. That table is the single source of truth for every control's get.
The mixer is never reported
The dump has no mixer gains. A mix control therefore reads -1 ("unknown") for every gain the driver hasn't written since load. A client that reads a control and writes it back gets -1 again, which leaves the unit alone. This is why ucxcfg apply --push exists, and why the systemd unit runs it at every plug-in.
…except a side record of the input half
The unit stores a "stand-alone input mix" record, which TotalMix writes next to every input fader, and returns it in the dump. The driver does the same (ucx_sa_follow()) and fills unknown input gains from it (ucx_sa_reply()). The record has 0.1 dB steps and no phase, so it never overrides a gain the driver wrote itself.
snd_ctl_notify() is safe from atomic context. It queues an event on the control device, and every client that has subscribed (alsamixer, PipeWire, amixer events) sees the value change. Front-panel changes therefore show up in other programs within one poll period, about 50 ms.
If the reply or event URB stops with an error, it is not resubmitted from the completion handler, which could spin on a stalled endpoint. ucx_recover_work retries later with a delay that starts at 100 ms and doubles up to 6.4 s, clears a halt on -EPIPE, and asks for a new dump, because replies may have been lost. After a cold plug the unit sometimes ignores the first dump request, so the poll work asks again every 40 polls until a dump-only register (0x12a0) has arrived.
ALSA controls: 244 of them, mostly from one table
An ALSA control (a snd_kcontrol) has three callbacks. info gives the type, count and range, get fills in current values, and put takes new ones and returns 1 if something changed (the core then notifies other clients). A TLV (type-length-value) block attaches a dB scale, so alsamixer can show "−12.0 dB" instead of a raw integer.
Instead of 118 hand-written controls, ucx_reg_ctls[] describes each one as register = value × mult + bias, with an optional per-channel count (18 values for 18 channels, register + (i << 8)) or shared (one value written to several registers). One set of info/get/put functions serves them all, and kctl->private_value holds the table index.
Control browser
| Control name (as amixer sees it) | Values | Register / request | Backed by |
|---|
ALSA control names follow conventions ("… Playback Volume", "… Capture Switch", SNDRV_CTL_NAME_IEC958(...)). alsamixer and PipeWire's ACP use the suffixes to decide what a control is. A volume paired with a same-named Switch is drawn as one fader with a mute button. That is why the output mutes are called "Line 1 Playback Switch".
REG1, STATUS and the other vendor requests
Clock and hardware settings are bits of a write-only register, REG1, written with vendor request 0x10 as a masked write: wValue carries the new bits and wIndex the mask of bits to change. REG1 can't be read back, but the unit mirrors most of its bits into DSP registers (0x3d20, 0x3d40–0x3d42…), which it reports on 0x8d. The controls write REG1 and read the mirror. Two settings, EQ+D record and Loopback, have no mirror. For those the driver keeps its own record in reserved table slots 0x7f10 and 0x7f20+.
Setup packet builder
what usb_control_msg() puts on the wireSTATUS decoder
vendor request 0x11, IN, 4 bytes| Request | Name | What the driver does with it |
|---|---|---|
| 0x10 | REG1 | rate bits at stream start, MIDI on at probe, the six hardware controls |
| 0x11 | STATUS | read before the first start (current rate), in debugfs/hwdep for tools |
| 0x14 | CHANNELS | after the URBs run; required for playback to reach the DSP |
| 0x15 | LOOPBACK | one per output: output signal replaces the matching input in the recording |
| 0x1d | START_AT | value 0 = start now |
| 0x1c, 0x1e, 0x1f | version, serial | read-only, for UCX_HWDEP_STATUS |
| 0x1b | CLOCK | never sent detunes the sample clock until a power cycle (measured) |
| 0x18, 0x19 | FLASH_WRITE / STATUS | never sent flash programming |
Meters, the hwdep device, MIDI and debugfs
Meters: five bulk reads
One bulk read on 0x85 returns one bank of 20 channels: u64 rms[20] at 0x00, u32 peak[20] at 0xa0 (227 = full scale, low 4 bits are flags), and a tag at 0xf0. Five reads in a row give inputs pre/post DSP, playback, and outputs pre/post volume. Each bank holds the peak since its previous read, so if two programs read meters they split the peaks between them.
hwdep: a raw door with a lock on it
/dev/snd/hwC<n>D0 belongs to the audio group, so no root is needed. write() sends DSP words (parity added), read() returns the register table, and two _IOR ioctls read meters and status. Words for 0x3e05/0x3e06 (flash store) and the driver's own slots ≥ 0x7f00 are refused with EPERM. Writes are recorded in the table, so the controls stay correct.
MIDI: reuse, don't rewrite
Interface 2 is a standard USB-MIDI class interface. snd-usb-audio doesn't bind this device, so the driver claims the interface, sets REG1 bit 0x0800 (MIDI on) and hands it to __snd_usbmidi_create() from snd-usbmidi-lib. That header is private to the kernel tree, so ucx.h declares the four exported functions by hand. MIDI is optional: if setup fails, the card still works.
debugfs: for root, while developing
Under /sys/kernel/debug/usb/<intf>/: regs (the table), meters (peaks in dBFS), status, dsp (write hex words) and pm (run the driver's half of suspend/resume on a live system, so a hang stays in one process instead of freezing the machine).
hw->ops.ioctl_compat = ucx_hwdep_ioctl lets 32-bit programs on a 64-bit kernel use the same ioctls. That is safe only because the structs hold no pointers and no longs, so their layout is the same on both ABIs. The UAPI header uses __u32/__u8 for that reason.
Locks, execution contexts and power management
Kernel code runs in different contexts, and the context decides what you may do. Process context (syscalls, workqueues) may sleep and take mutexes. Atomic context (URB completions, PCM trigger/pointer, anything under a spinlock) must not. The driver uses each kind of lock for the context that needs it:
| Lock | Kind | Guards | Taken in |
|---|---|---|---|
ucx->lock | mutex | engine state: running, rate, prepared, hw_rate | open, prepare, hw_free, stream_err_work, suspend, disconnect |
stream_lock | spinlock (irqsave) | substream pointers, positions, seq numbers, stream_err | URB completions, trigger, pointer, prepare |
dsp_lock | mutex | dsp_buf, gone/suspended/wedged flags; serialises all DSP sends and meter reads | control put, poll_work, recover_work, hwdep, debugfs |
regs_lock | spinlock (irqsave) | regs[], reg_seen | reply completion, every control get |
cs_lock | spinlock (irqsave) | S/PDIF channel status block | capture completion, IEC958 control get |
| USB device lock | core's | PM callbacks | held by the PM core; debugfs pm uses usb_trylock_device() |
Defer to a workqueue
A completion that needs to sleep (restart the engine, clear a halt) only sets a flag and calls schedule_work() or schedule_delayed_work(). stream_err_work, recover_work and poll_work all follow this pattern.
Kill, then cancel
usb_kill_urb() waits for a running completion. Only after that is cancel_work_sync() safe, because nothing can schedule the work again. The order appears in suspend and in disconnect.
Signal outside the lock
snd_pcm_period_elapsed() takes the PCM stream lock and may call back into pointer, which takes stream_lock. So ucx_copy() returns the substream and the caller signals after unlocking.
Suspend and resume across four interfaces
Without suspend/resume callbacks, the USB core would unbind the driver at every system sleep and probe it again on wake, and the card would disappear. With four claimed interfaces the core calls each callback four times, so the driver counts them (pm_count, as snd-usb-audio does). It does the work at the first suspend and the last resume, and remembers whether any of them was a reset_resume.
At suspend the PCM side kills the URBs but does not call usb_set_interface(…, 0), unlike a normal stop. That is a control transfer that re-registers endpoints while the PM core is suspending devices. Two suspends hung the machine with it in place (the comment notes the cause isn't proven). The PCM has no SNDRV_PCM_INFO_RESUME, so clients prepare again after wake, and that restarts the engine at the right alt setting. After a reset, REG1 is back at defaults, so resume turns MIDI on again. The register table is kept, and a fresh dump corrects anything that changed meanwhile.
User space: a declarative config and a safe apply
libucx (lib/) has two halves. config.c is struct ucx_config, the whole desired state of the unit, with its JSON format. It needs no device and is fuzzed with libFuzzer. device.c reads what the driver knows, computes the writes that take the unit to the config, and sends them through ALSA controls. It doesn't write raw words: using the controls means the driver skips unchanged values, keeps its table right and notifies other clients.
The file describes the whole unit. A key that is missing means "default" (routes off, volumes at −65 dB), not "leave it alone". So apply is a diff between two complete states:
The plan: seven phases so nothing ever gets louder
ucx_plan_make() sorts every difference into phases, so that at no point during the apply is an output louder than it was before or will be after. Walk through an example plan:
Unknown is a first-class value
UCX_UNKNOWN (INT_MIN) marks a value the driver hasn't seen. Reading uses the hwdep table's "seen" set to tell "minimum" apart from "unknown". The plan treats an unknown volume as "could be anything", so it closes the output first and opens it last. dump lists unknowns under an "unknown" key, which makes the file invalid as input until you decide.
Batched, paced writes
The 18 values of one mix control go in one snd_ctl_elem_write(). Ops in the plan are grouped by control, and -1 fills the slots this pass doesn't touch. After each write the library sleeps 0.5 ms per word, the same pace the driver keeps, so even a 720-gain --push can't wedge the unit.
ucxtui
The TUI is an editor for the same struct ucx_config, split into three files. term.c is a small terminal layer (raw mode, a cell buffer sent as a diff, 24-bit color, mouse) with no curses. doc.c holds the document and its edits, with undo history, and keeps linked pairs within what the file format can say (tests/doc.c checks that). ucxtui.c draws the screens. Every second it runs device_sync() (read state, diff against the document). Every 60 ms it reads meters through the hwdep ioctl and lets them fall at 40 dB/s. In live mode every edit becomes a plan and an apply. A confirmation step stops phantom power and clock-source changes from going out by a slip of the finger.
| Tool | Talks to | Role |
|---|---|---|
ucxcfg | libucx → ALSA | check, dump, apply [-n] [--push]; exit codes for scripts (3 = no device, 5 = dry run found changes) |
ucxtui | libucx → ALSA | mixer in the terminal; saves to ~/.config/ucx/config.json |
ucxctl | libusb, driver unloaded | the test bench: info, vendor requests, stream in/out, mixer probes. A crash costs a process, not the machine |
ucxdsp.py | hwdep | raw words, register table, meters, stand-alone record, status. No root needed |
looptest | ALSA PCM | clicks + sine through a cable: round-trip frames, glitches (x[n] = c·x[n−1] − x[n−2]), xruns |
routes.py, inprobe.sh, tone.py, midi_*.py | ALSA / hwdep | the measurement helpers used to verify the register map |
Hot plug, PipeWire and packaging
When the unit is plugged in, the kernel loads the module by its USB alias (MODULE_DEVICE_TABLE). The module registers the card, and ALSA creates the control device last. A udev rule matches that control device and asks the logged-in user's systemd to start ucxcfg-apply.service. The service waits 2 s for the dump to arrive, then runs ucxcfg apply --push. The --push is needed because after a fresh load the driver can't know the playback gains.
Reporting latency to PipeWire
The driver sets runtime->delay (playback queue = 2 URBs), but PipeWire only reports its own buffering for an ALSA node. The unit adds more: its converters and FIFOs. A WirePlumber rule adds the measured remainder, so a DAW that compensates for reported latency lines a recording up with what it played:
Building out of tree
kmod/Kbuild lists the three objects and adds ../include to the include path. kmod/Makefile calls the kernel's build system with make -C /lib/modules/$(uname -r)/build M=$(PWD). Install goes to updates/ and runs depmod. The module has to be rebuilt for every kernel.
NixOS
nix/kmod.nix builds against config.boot.kernelPackages, so the module follows kernel upgrades. nix/module.nix adds it to boot.extraModulePackages, installs the tools, udev rule and WirePlumber config, and defines the same user service as the .in file.
How the protocol was recovered, and the rules that kept the unit alive
- Read the Windows driver and TotalMix (Ghidra/rizin through REA) to find the interfaces, the vendor requests, the stream start, and how TotalMix's
CCardIOUCXclass encodes DSP words. Note the address of every fact. - Cross-check against open sources for sibling hardware: RME's FireWire "latter" protocol (snd-firewire-ctl-services), oscmix (UCX II, 802), and the kernel's Babyface Pro quirks, which use the same request numbers.
- Try it from user space first with
ucxctlover libusb, driver unloaded. Only proven steps go into the kernel. - Measure on hardware: cables looped from outputs to inputs, quiet test tones, the unit's own meters (five banks show where a signal is inside the DSP), one register at a time. Write the date into the comment.
- Finish every finding in four places:
PROTOCOL.md,ucx_proto.h, a driver control, and the tools (config key plus TUI label). Registers whose effect isn't known are documented but get no control.
Vendor requests 0x18/0x19 (flash write/status) and DSP words for 0x3e05/0x3e06 (store setup to flash). The driver, the hwdep device, debugfs and ucxctl all refuse them, and libucx's raw path only lets per-channel registers through. Also off-limits: request 0x1b, which detunes the clock until a power cycle, and bursts that overflow the 128-word buffer.
Ideas worth taking to your next driver
One shared protocol header
Encodings live once, as inline functions both kernel and user space compile. Test them in user space.
A table as the truth
Controls read a cache that the device fills. Writes skip unchanged values. "Unknown" is a real state, never a guess.
Rate-limit the hardware
If the device can be overwhelmed, pace in the one function every writer goes through, and detect and recover from the failure mode.
Keep the engine running
Run duplex from one clock and attach streams at a deterministic point. Stable latency is worth the silent URBs.
Fail into a restart
Don't patch over a lost URB. Restart the whole engine, report an xrun, count it, and cap the retries.
Debug hooks for the scary paths
A debugfs pm file runs the suspend logic on a live system, so a bug hangs one process instead of the laptop.
Kernel API cheat sheet and glossary
| API | Subsystem | Used for | Where |
|---|
Read next
- Writing an ALSA Driver: PCM ops, hw constraints, controls, TLV.
- USB Request Block (URB) and Writing USB Device Drivers.
sound/usb/in the kernel tree: snd-usb-audio, its MIDI library, andmixer_quirks.c(the Babyface Pro uses the same request numbers).- snd-firewire-ctl-services (
protocols/fireface/src/latter.rs) and oscmix: the same DSP words on related hardware. - In this repo:
kmod/ucx.h(the state and its locks),docs/PROTOCOL.md,include/ucx_proto.h.