dsg/usbip-rs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Rust usbip protocol library and tooling
169 commits 1 branch 0 tags 1.2 MiB
Find a file
Davíð Steinn Geirsson 804a4910a0 fix: USB spec conformance and reliability improvements 
Spec conformance:
- Add missing standard control requests for simulated devices:
  GetConfiguration, GetStatus (device/interface/endpoint),
  ClearFeature, SetFeature, SetAddress
- Replace debug_assert with truncate for path/bus_id wire format
  to prevent protocol desync in release builds

Reliability:
- server() now returns Result instead of panicking on bind failure

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 00:12:36 +00:00
cli feat: add fc-vsock transport for Firecracker/Cloud-Hypervisor VMs 2026-03-22 15:44:15 +00:00
docs/superpowers feat: add isochronous transfer support and fix host passthrough 2026-03-22 10:42:08 +00:00
lib fix: USB spec conformance and reliability improvements 2026-03-25 00:12:36 +00:00
.gitignore feat: add usbip-rs CLI tool with vsock transport 2026-03-22 10:41:42 +00:00
Cargo.lock feat: concurrent ISO pipelining via nusb update and &self handlers 2026-03-22 15:10:28 +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 Update flake.nix to allow nix flake check torun tests 2026-03-25 00:07:13 +00:00
improvements.md fix: USB spec conformance and reliability improvements 2026-03-25 00:12:36 +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.