dsg/usbip-rs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Rust usbip protocol library and tooling
163 commits 1 branch 0 tags 1.2 MiB
Find a file
Davíð Steinn Geirsson b73b4b31f4 fix: ISO alt setting and actual_length for isochronous transfers 
- Add set_alt_setting() to UsbInterfaceHandler trait so host passthrough
  handlers can update the physical USB interface's alternate setting via
  nusb::Interface::set_alt_setting() instead of raw control transfers.
  This allows nusb to find ISO endpoints after alt setting changes.
- Fix ISO OUT actual_length to equal the sum of per-packet actual_lengths
  instead of transfer_buffer_length. The kernel validates this invariant
  and disconnects the device on mismatch ("total length of iso packets
  not equal to actual length of buffer").

Enables successful USB Audio Class 2 isochronous playback through
host passthrough.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-22 12:45:55 +00:00
cli fix: correct OUT actual_length, BCD encoding, and silent transfer failures 2026-03-22 11:05:53 +00:00
docs/superpowers feat: add isochronous transfer support and fix host passthrough 2026-03-22 10:42:08 +00:00
lib fix: ISO alt setting and actual_length for isochronous transfers 2026-03-22 12:45:55 +00:00
.gitignore feat: add usbip-rs CLI tool with vsock transport 2026-03-22 10:41:42 +00:00
Cargo.lock feat: add isochronous transfer support and fix host passthrough 2026-03-22 10:42:08 +00:00
Cargo.toml feat: add usbip-rs CLI tool with vsock transport 2026-03-22 10:41:42 +00:00
flake.lock feat: add usbip-rs CLI tool with vsock transport 2026-03-22 10:41:42 +00:00
flake.nix feat: add isochronous transfer support and fix host passthrough 2026-03-22 10:42:08 +00:00
LICENSE Simplify documentation (fixes #59) 2025-12-25 20:58:48 +08:00
NOTES.md Add notes 2022-12-05 17:39:37 +08:00
README.md Update README.md 2026-03-22 11:33:07 +00:00

README.md

usbip-rs

A USB/IP tool and library for Linux. Share physical USB devices over vsock or TCP, or export simulated devices for testing.

Overview

usbip-rs provides:

  • CLI tool (usbip-rs) — pass through real USB devices from a host to a client over vsock or TCP, using Linux's vhci_hcd kernel module
  • Rust library (usbip-rs crate) — implement custom USB/IP device handlers, with built-in HID keyboard and CDC ACM serial examples

Supported transfer types: control, bulk and interrupt. Isochronous support is being worked on.

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 three top-level commands: client, host, and test_hid. Transport addresses use the format vsock:<port>, vsock:<cid>:<port>, tcp:<port>, or tcp:<host>:<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

Library examples

The lib/examples/ directory contains standalone USB/IP servers using the library directly:

  • hid_keyboard — simulated HID keyboard
  • cdc_acm_serial — simulated CDC ACM serial device
  • host — physical device passthrough (legacy, single-device)
cargo run -p usbip-rs --example hid_keyboard

These listen on the standard USB/IP port and work with the Linux usbip userspace tools:

usbip list -r <host-ip>
usbip attach -r <host-ip> -b <bus-id>

Project structure

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

License

MIT — see LICENSE.