Rust Drives A Linux USB Device

USB is the “Universal Serial Bus,” which is a wonderfully optimistic name for something that can make a grown engineer
whisper, “Why is endpoint 0 laughing at me?” at 2:00 a.m. Now add Linux (powerful, opinionated) and
Rust (safe, strict, and somehow still fun), and you’ve got a surprisingly great combo for talking to
a USB devicewhether you’re controlling a custom gadget, polling a sensor, or reverse-engineering that one mystery
dongle you found in a desk drawer labeled “DO NOT PLUG IN.”

This guide covers how Rust can “drive” a USB device on Linux in practical terms: user-space communication using
libusb-style APIs (often the quickest path), when you actually need a kernel driver (and what that looks like),
and how to avoid the classic USB faceplants (permissions, driver binding, stalled pipes, timeouts, hotplug, and the
dreaded “works on my laptop” phenomenon).

Why Rust + USB on Linux is a power couple (and occasionally a soap opera)

USB is a protocol stack with layers: physical signaling, host controllers (xHCI these days), device descriptors,
configurations, interfaces, endpoints, and transfers (control/bulk/interrupt/isochronous). Linux handles a massive
portion of this for you through the kernel USB subsystem, while you choose how your software interacts with it.

Rust shines here because USB programming is full of “small sharp objects”: buffer ownership, lifetimes across async
callbacks, multithreaded hotplug, and parsing binary descriptor data without stepping on a rake. Rust’s type system,
lifetimes, and RAII patterns make it harder to accidentally read uninitialized data, use a freed buffer, or leak a
device handle while you’re juggling retries and timeouts. In other words: Rust doesn’t magically fix USB, but it does
keep your code from turning one weird packet into a memory-corruption haunted house.

Also, Rust tooling is excellent for iterating quicklyespecially in user space. You can prototype device behavior,
validate your understanding of endpoints, and only drop to kernel space when you’re absolutely sure you need to.
(Kernel drivers are like tattoos: meaningful, permanent, and you should really think about them first.)

First decision: user-space or kernel-space?

When people say “USB driver,” they might mean three different things. Here’s how to pick the right approach on Linux.

Option A: User-space “driver” with libusb (usually the fastest path)

If your device is vendor-specific (custom firmware, custom protocol) and you just need to send commands and read data,
user space is often ideal. With libusb-style access, your Rust program talks to the kernel’s USB stack
via device nodes like /dev/bus/usb/BBB/DDD. You don’t write a kernel module; you write a normal Rust app.

• Best for: prototyping, custom peripherals, tools, testers, reverse engineering, internal apps.
• Pros: fast iteration, safer debugging, no kernel crashes, deploy like any other binary.
• Cons: may be limited for ultra-low latency, special power management, or tight integration with the kernel.

Option B: Kernel driver (when you need tight timing or deep integration)

You write a kernel USB driver when you need the kernel to own the device: exposing a character device in /dev,
integrating with a kernel subsystem (e.g., input/HID, network, serial), handling power management aggressively, or
supporting multiple apps without coordination. In kernel space, Linux USB uses asynchronous request objects (URBs),
probe/disconnect callbacks, and endpoint pipes.

• Best for: production device support, mainline-quality integration, performance-critical streaming.
• Pros: kernel-managed lifecycle, better integration, potentially lower overhead.
• Cons: slower iteration, higher risk, must follow kernel rules, and debugging feels like spelunking.

Option C: Linux as a USB device (gadget mode)

Sometimes Linux isn’t the USB hostit’s the USB device. On boards with a USB Device Controller (UDC), Linux can present
itself as a serial gadget, mass storage, MIDI device, and more. You can configure composite devices via configfs and
sometimes implement parts of the behavior in user space (for example, via FunctionFS), where Rust can be a great fit.

This article focuses mainly on Linux-as-host driving a USB peripheral, but gadget mode is worth knowing if your “device”
is actually an embedded Linux board pretending to be a USB peripheral.

USB in 90 seconds: descriptors, endpoints, and the “why is it stalled?” moment

Every USB device describes itself using descriptors:
a device descriptor (vendor/product IDs), configuration descriptors, interfaces, and endpoints. Your code typically:

1. Find the device (by VID/PID or class).
2. Select a configuration (some devices have multiple).
3. Claim an interface (and sometimes select an alternate setting).
4. Use endpoints to transfer data (bulk for “lots,” interrupt for “small and timely,” iso for streaming).

A classic pitfall: you open the device and immediately try to write to endpoint 0x01 because it “looks right.”
Then the device stalls and you learn that endpoint directions matter (IN vs OUT), interfaces must be claimed, and the
device might require a control transfer handshake first. USB is polite like that: it doesn’t scream “wrong,” it just
silently hands you an error code and a life lesson.

Building a Rust user-space USB client with rusb

In Rust, the most common path is using a safe wrapper around libusb. Conceptually, you:
enumerate devices, open one, claim the correct interface, then perform transfers.

Step 1: Permissions (because root shouldn’t be your USB development environment)

On many Linux distros, raw USB device nodes are owned by root by default, and user-space access requires udev rules.
The usual approach is to create a rule matching your device’s vendor/product ID and granting access to a group (or setting
mode). Keep it targetedbroad rules are how you accidentally give your entire system permission to talk to every USB device
like it’s an open mic night.

Practical workflow:
use lsusb to get VID/PID, then create a udev rule that matches those attributes and sets permissions for a
developer group. Reload udev rules and replug the device.

Step 2: Enumerate, open, and claim the interface

A “drive a USB device” Rust program typically does three things early:
(1) find the matching VID/PID,
(2) open a handle,
(3) claim the interface that owns the endpoints you need.
If the kernel already bound a driver (HID, CDC-ACM, mass storage), you may need to detach it or choose a device interface
meant for vendor access.

If you hit “device busy,” it often means the kernel driver has claimed the interface. For many devices, that’s correct
behavior (keyboards should keep working). For custom devices, you may ship firmware that uses a vendor-specific interface
so your user-space app can claim it without fighting standard kernel drivers.

Step 3: Transfers (control, bulk, interrupt) without losing your sanity

USB transfers are how you actually “drive” the device:
control transfers are usually for setup/commands,
bulk for larger data,
interrupt for small periodic data,
and isochronous for time-sensitive streaming.
In user space, you typically start with control + bulk and only reach for iso when you’re doing audio/video or high-rate sensors.

A common pattern for custom devices:
send a small command via a control transfer or a bulk OUT endpoint,
then read a response from a bulk IN endpoint.

The “real work” is your device protocol: framing, checksums, sequencing, retries, and keeping your program resilient
when the user unplugs the cable mid-transfer. Rust helps by making you handle errors explicitly, encouraging timeouts,
and keeping the rest of your system stable even when the device behaves like a toddler on a sugar rush.

Step 4: Hotplug and resilience

Hotplug is where USB gets spicy: devices appear, disappear, re-enumerate, and sometimes come back with a different
device node after a reset. A robust Rust client typically:

• uses a retry loop that re-enumerates devices if a transfer fails with “no device,”
• keeps state machines explicit (Connected → Initialized → Streaming),
• separates transport errors (USB) from protocol errors (your framing/checksum),
• logs enough context to debug without needing psychic powers.

What kernel USB drivers actually do (and what changes in Rust)

In kernel space, a USB driver registers with the Linux USB subsystem, declares which VID/PID (or classes) it supports,
and implements callbacksmost notably probe() and disconnect()that run when the device is
plugged in or removed. Data movement often uses URBs (USB Request Blocks), which are queued
asynchronously; completion handlers run later when the transfer finishes.

The async nature matters: your driver submits an URB and gets control back immediately. Completion happens later in a
callback, so you must manage lifetimes carefully, avoid blocking in the wrong context, and handle cancellation during
disconnect. Error codes like -ENODEV (device removed) and -EBUSY (already active) are part of
normal life, not personal insults.

Where does Rust fit? The Linux kernel has been incrementally adding support for Rust as a second language. Kernel Rust
is not the same as “normal Rust”: no standard library, strict rules about allocation and concurrency, and
a careful set of kernel-provided abstractions. The goal is to make certain classes of bugs harderespecially memory safety
issueswithout rewriting everything at once.

Practically, today’s “Rust in the kernel” experience often looks like:
Rust code calling into existing C APIs (through kernel-provided bindings),
using Rust wrappers where available,
and following the same driver model (probe/disconnect, power management, endpoints).
USB driver support in Rust is evolving; even when the USB core is C, Rust can help keep your driver logic safer where
Rust abstractions exist.

If you’re deciding between kernel Rust vs user-space Rust, be honest about your goals:
if you need rapid iteration, user-space Rust with libusb is your friend.
If you need kernel integration, evaluate whether Rust support for the interfaces you need is mature enough in your target
kernel version, and be ready for some “glue” with existing C APIs.

Debugging toolbox: how to stop guessing and start knowing

USB debugging is mostly about visibility. Helpful tools and habits include:

• Descriptor inspection: use lsusb -v to confirm interfaces/endpoints and directions.
• Kernel logs: check dmesg for enumeration errors, resets, and driver binding messages.
• Traffic capture: use Linux USB monitoring (usbmon) and inspect captures in tools like Wireshark.
• Stall/retry logic: treat stalls as signal: often you skipped a required setup step or claimed the wrong interface.
• Time bounds: always set timeouts and log elapsed time; “it hung” is not a diagnosis.

If you’re reverse engineering a device, a reliable approach is to capture known-good traffic from vendor software (where legal)
and replicate the sequence in your Rust client: initial control transfers, configuration selection, then the steady-state
bulk/interrupt pattern. Most devices aren’t mysterious; they’re just undocumented.

Performance and safety checklist

Before you commit to architecture, sanity-check these points:

• Do you need kernel integration? If you just need data, user space is usually enough.
• Is the device already handled by a standard class driver? If yes, consider using the standard interface (e.g., HID/serial) instead of raw USB.
• Will multiple apps need access? Kernel driver (or a single daemon that multiplexes) may be cleaner.
• Is timing truly critical? Many “latency” issues are actually protocol design issues (batch commands, reduce round trips, use streaming endpoints).
• Are you handling disconnects? Plan for surprise unplugging like it’s a feature (because it is).

Conclusion

“Rust drives a Linux USB device” isn’t one thingit’s a spectrum of options. For most projects, a Rust user-space client
using libusb-style access is the sweet spot: fast development, strong safety guarantees, and enough performance for a
huge range of devices. Kernel drivers are the heavyweight option when you need deep integration, tight lifecycle control,
or subsystem supportand Rust in the kernel is an exciting path, but one that still depends on the maturity of Rust
abstractions for the specific APIs you need.

Start in user space, learn your device’s descriptors and endpoints, design a clear protocol, and build robust hotplug-aware
code. If you eventually need kernel space, you’ll arrive with evidence, not vibesand USB loves evidence.

Experiences: 10 Rust-on-USB lessons I learned the hard way (so you don’t have to)

1) Endpoint numbers are not opinions. I once spent an entire afternoon sending data to what I believed
was a bulk OUT endpoint. The device replied with… silence. Turned out I had grabbed the endpoint address from the wrong
interface. USB descriptors are a family tree, not a menu. In Rust, I now parse descriptors into a typed “device map”
up front and log it on startup so I can’t accidentally pretend I’m talking to interface 1 while claiming interface 0.

2) “It works once” is a bug report, not a victory lap. My first version worked until the second command,
then everything stalled. The culprit was a missing read that left the device’s response queue full. USB is still a
conversation; if you talk over the other side, it may stop replying. I now treat every command as a transaction with
explicit states: sent → awaiting reply → completed, and I never issue the next command until the previous one is resolved
(or timed out and reset).

3) Timeouts are love. Early on, I used generous (read: infinite) waits, because “the device should respond.”
Then I met reality: hotplug, flaky hubs, power saving, and that one cable that’s technically a cable but emotionally a noodle.
In Rust, every transfer gets a timeout, and I include the timeout value in logs. If something times out, I don’t just retry;
I record how far the protocol got so I can reproduce the failure.

4) Permissions will humble you. The most sophisticated USB code in the world does nothing if your process
can’t open the device node. The first time I “fixed” it by running as root, I immediately learned the second lesson:
running as root makes mistakes louder. These days I add a udev rule for my VID/PID (or a dev group), validate access on
startup, and print a friendly error that points to the permissions layerbecause future me deserves kindness.

5) Kernel drivers are jealous. I plugged in a device that looked vendor-specific… but it exposed a HID interface,
so the kernel bound a HID driver immediately. My Rust app couldn’t claim the interface and returned “busy.” That’s not a failure;
that’s Linux protecting the system. If you want user-space control, design your firmware with a vendor-specific interface
meant for your app, or separate “standard” and “vendor” interfaces cleanly.

6) Stalls usually mean “you skipped a step.” A stalled endpoint isn’t the device being mean; it’s the device
saying, “I can’t do that right now.” Common causes: wrong interface, wrong alternate setting, missing initialization command,
or invalid request length. I now treat stalls as a sign to review setup sequence and descriptor alignmentnot just to spam retries.

7) Hotplug isn’t optional. Someone will unplug the device during a transfer. Someone will close the laptop lid.
Someone will connect through a hub that deserves a documentary. Rust makes recovery code easier to structure: I wrap the device
handle in a state machine and rebuild the connection cleanly on “device removed” errors, instead of trying to duct-tape a broken
handle back together.

8) Log the protocol, not just the error. “Error: EPIPE” is not actionable without context. I log every command
with a sequence number, expected response type, and byte counts. When something fails, I can tell whether the device never
responded, responded with the wrong frame, or responded late. The difference matters.

9) When in doubt, reduce round trips. Many performance issues come from chatty protocols. If you send five small
commands and wait five times, you’ve built a latency machine. Batching commands, streaming data over bulk IN, and designing a
clear framing protocol often yields bigger wins than jumping to kernel space.

10) Start in user space unless you can prove you shouldn’t. I’ve watched teams rush into kernel modules
because “drivers belong in the kernel,” then spend weeks on build friction and debugging complexityonly to realize their needs
were perfectly served by a Rust daemon using libusb. Kernel drivers are powerful, but they’re also expensive. Prove the need,
then pay the cost.

If you take nothing else away: learn the descriptors, respect interface ownership, treat timeouts and disconnects as normal,
and let Rust’s safety model keep your debugging focused on the USB problemnot a side quest involving memory corruption.