Davíð Steinn Geirsson 18a413870a feat: add UAC1 loopback test device and fix endpoint attribute dispatch

Add a simulated USB Audio Class 1 loopback device for testing
isochronous transfers. Audio sent to the playback OUT endpoint
(48kHz/16-bit/stereo) is looped back to the capture IN endpoint.

- Add UsbEndpoint::transfer_type() masking bmAttributes to bits 0-1,
  fixing dispatch for isochronous endpoints with sync-type sub-bits
- Update all endpoint attribute dispatch sites across the library
- Add UacLoopbackBuffer, UacControlHandler, UacStreamOutHandler,
  UacStreamInHandler in lib/src/uac.rs
- Add build_uac_loopback_device() builder function
- Add `test_uac connect` CLI subcommand
- Add 10 unit tests covering buffer, descriptors, and handler behavior
- Add design spec and implementation plan docs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-25 01:43:31 +00:00

3.5 KiB

Raw Blame History

usbip-rs

Implements a userspace server-side server for the usbip protocol, and a tool for the client-side to set up the socket and hand it off to the kernel. In usbip terminology, the "server"/"host" is the side that has the physical device being shared, and the "client" is the side the device is being shared to.

This project is based on https://github.com/jiegec/usbip, with significant changes and additions.

Why?

Implementing the server side in userspace instead of the kernel's usbip_host driver reduces the attack surface considerably. The kernel is not exposed directly to potentially untrusted network input. The userspace server talks to the USB device via /dev/bus/usb/..., and can validate the client's traffic before passing it on to the real USB device. It also makes it possible to implement strong sandboxing via seccomp and namespaces for the server side. The client side is of course still all in the kernel, since making the USB devices visible to the client kernel's drivers is the whole point. But for my use case, the server side is trusted and client side is untrusted, so securing the host side is critical.

There are a few other userspace usbip server implementations around, but as far as I could tell, none of them support isochronous mode. Isochronous is needed for e.g. USB audio devices and webcams. This project does, though my testing so far is limited to USB audio devices which work well.

This implementation also allows for reversing the connection flow. In standard usbip, the server side listens for connections, and the client side connects to it to access the device. usbip-rs supports having the client listen and the server initiating the connection, which maps much better to my needs.

usbip-rs also supports using vsock instead of TCP as the transport, making the "ip" in "usbip" not really true. This is useful when sharing a device to a virtual machine on the same hardware.

Building

With Nix

nix build

With Cargo

Requires libusb and libudev (Linux) system dependencies.

cargo build --release

The CLI binary is at target/release/usbip-rs.

Usage

The CLI has four top-level commands: client, host, test_hid, and test_uac. Transport addresses use the format vsock:<port>, vsock:<cid>:<port>, tcp:<port>, tcp:<host>:<port>, or fc-vsock:<path>:<port>.

Pass through a real USB device

On the client machine (needs vhci_hcd kernel module):

usbip-rs client listen tcp:3240

On the host machine (where the USB device is plugged in):

usbip-rs host connect tcp:<client-ip>:3240 1-2

The device argument is a bus ID (e.g. 1-2) or device path (e.g. /dev/bus/usb/001/002).

Test with a simulated HID keyboard

# Client side
usbip-rs client listen vsock:5000

# Host side (simulated keyboard, no real device needed)
usbip-rs test_hid connect vsock:5000

Test with a simulated UAC1 loopback audio device

# Client side
usbip-rs client listen tcp:3240

# Host side (simulated USB audio device, no real device needed)
usbip-rs test_uac connect tcp:3240

The UAC1 loopback device advertises 48kHz 16-bit stereo playback and capture. Audio sent to the playback endpoint is looped back to the capture endpoint.

Project structure

├── cli/          CLI binary (usbip-rs)
├── lib/          Library crate (usbip-rs)
│   ├── src/
│   └── examples/
└── flake.nix     Nix build

License

MIT — see LICENSE.

3.5 KiB Raw Blame History