mirror of https://github.com/jiegec/usbip.git synced 2026-09-30 09:57:06 -04:00

Files

Jiajie Chen 411e63f8e8 Add QEMU end-to-end test verifying simulated USB devices

Boot a real Linux inside QEMU and confirm that simulated USB/IP devices
work against a real kernel (vhci-hcd + cdc_acm):

- Add examples/demo.rs: a single server exporting a HID keyboard and a
  CDC ACM serial device on port 3240.
- Add scripts/qemu/: build a minimal initramfs (host kernel + busybox +
  usbip tool + demo server), boot it in QEMU, attach the simulated devices
  over 127.0.0.1, and verify:
    * the serial port emits 'a' (0x61)  -> SERIAL_TEST
    * the keyboard generates a KEY_1 input event -> KEYBOARD_TEST
- Add .github/workflows/qemu.yml to run this in CI (KVM when available,
  TCG fallback otherwise), uploading the serial console log as an artefact.

2026-09-04 00:16:40 +08:00

2.5 KiB

Raw Blame History

usbip

A Rust library to run a USB/IP server to simulate USB devices and share real USB devices over a network.

What is USB/IP?

USB/IP is a network protocol that allows USB devices to be shared between computers over a network. It enables:

Device simulation: Create virtual USB devices that can be accessed remotely
Device sharing: Share physical USB devices from one machine to another
Cross-platform: Works across different operating systems (Linux, etc.)

Installation

Prerequisites

Install Rust from the official documentation.

Building from source

git clone https://github.com/jiegec/usbip.git
cd usbip
cargo build --release

How to use

Examples

The examples/ directory contains four example programs:

hid_keyboard: Simulate a HID keyboard that types something every second
cdc_acm_serial: Simulate a CDC ACM serial device that receives a character every second
host: Act as a USB/IP server, sharing physical devices from the host machine to remote clients
demo: Simulate a HID keyboard and a CDC ACM serial device together (used by the QEMU test)

Running an example

cargo run --example hid_keyboard

Connecting from a USB/IP client

On the client machine (e.g. Linux with USB/IP support):

# List available devices
usbip list -r $remote_ip

# Attach to a device
usbip attach -r $remote_ip -b $bus_id

QEMU end-to-end test

The simulated devices can be verified against a real Linux kernel booted under QEMU. The test assembles a minimal initramfs from the running kernel, its USB/IP and cdc_acm modules, a static busybox and the usbip userspace client, then boots it and uses vhci-hcd to attach the simulated keyboard and serial device. Inside the guest it confirms the serial port emits 'a' and that the keyboard generates a KEY_1 input event.

Run it locally (requires qemu-system-x86, a static busybox, cpio, and the usbip tool):

./scripts/qemu/run-qemu-test.sh --build --dump-log

It runs under KVM when available and falls back to QEMU TCG otherwise. It is also wired into CI via .github/workflows/qemu.yml.

License

MIT License - see LICENSE file for details.

2.5 KiB Raw Blame History