Proposal: a protocol-independent ironrdp-usb crate

[uchouT (uchouT)]

Context

I am currently working on integrating RDPEUSB support into ironrdp-server, with the goal of using it from qemu-rdp's usbredir bridge.

ironrdp-server does not currently integrate ironrdp-rdpeusb, so this work is still at the architecture and early implementation stage.

While working on this integration, I found that a significant part of the required model is not specific to RDPEUSB. It consists of USB-standard concepts such as:

• device, configuration, interface, and endpoint descriptors;
• descriptor parsing, validation, and traversal;
• typed configuration, interface, and endpoint identifiers;
• standard control requests;
• transfer direction, transfer type, status, and related request/result data.

These concepts are needed both by the RDPEUSB implementation and by consumers that speak another USB transport protocol, such as qemu-rdp's usbredir bridge.

Before developing this further, I would like feedback on whether these concepts should live in a standalone ironrdp-usb crate.

Proposed responsibility split

ironrdp-usb

A protocol-independent, no_std, sans-I/O crate containing USB-standard data structures and semantics.

Possible responsibilities include:

• USB descriptor data structures;
• parsing and validation of USB descriptors;
• querying configuration/interface/endpoint relationships;
• protocol-independent control and transfer request/result types;
• strongly typed USB values and identifiers.

It would not contain:

• RDPEUSB PDUs or TS_URB structures;
• usbredir packet definitions;
• device I/O;
• asynchronous runtime integration;
• request routing or pending-request management;
• server-specific state.

The intent is for this crate to describe USB operations and data, but not execute them.

ironrdp-rdpeusb

ironrdp-rdpeusb would remain responsible for the RDP protocol layer:

• RDPEUSB capability negotiation and channel state;
• RDPEUSB PDU encoding and decoding;
• TS_URB structures and RDPEUSB-specific behavior;
• translation between protocol-independent USB operations and TS_URB, where applicable.

The dependency direction would be:

ironrdp-rdpeusb  ──depends on──>  ironrdp-usb

ironrdp-usb would not depend on ironrdp-rdpeusb.

ironrdp-server

ironrdp-server would integrate the RDPEUSB processor and expose a higher-level device facade expressed using ironrdp-usb types.

Conceptually, this could look like a UsbDeviceHandle exposing operations such as:

get_descriptor(...)
select_configuration(...)
select_interface(...)
control_transfer(...)
bulk_or_interrupt_transfer(...)

These names and signatures are only illustrative.

The server layer would own protocol execution concerns such as:

• request identifiers;
• pending request and completion lifecycle;
• cancellation and device closure;
• routing requests to the RDPEUSB processor;
• correlating RDPEUSB completions with callers.

This would prevent users of ironrdp-server from having to interact directly with TS_URB, RDPEUSB processors, or internal ServerEvent wiring.

Intended use from qemu-rdp

The expected data flow would be:

usbredir packet
      |
      | qemu-rdp translates transport-specific data
      v
ironrdp-usb request/result types
      |
      | ironrdp-server UsbDeviceHandle facade
      v
ironrdp-rdpeusb
      |
      | USB operation <-> RDPEUSB TS_URB
      v
redirected USB device

qemu-rdp would depend directly on:

• ironrdp-server, for the device facade and request lifecycle;
• ironrdp-usb, for the types used by the facade and for translating usbredir packets.

Ideally, qemu-rdp would not depend directly on ironrdp-rdpeusb and would not need to know about TS_URB.

usbredir-specific behavior, such as its ordering and synchronous/asynchronous packet rules, would remain in qemu-rdp rather than becoming part of the generic USB or RDPEUSB layers.

The same server facade could potentially be reused by other server applications or bridges, such as macrdp, without exposing RDPEUSB protocol details to them.

Why not ironrdp-rdpeusb::usb?

Keeping these types under ironrdp-rdpeusb would be simpler initially, but it would make protocol-independent USB concepts appear to belong to RDPEUSB.

It would also require consumers such as qemu-rdp to depend on ironrdp-rdpeusb only to access generic USB descriptor and transfer types.

A standalone crate would make the intended layering explicit:

USB semantics
      ↑
RDPEUSB adapter
      ↑
server facade
      ↑
application-specific bridge

However, keeping the implementation as an ironrdp-rdpeusb::usb module initially is still a possible alternative if a standalone crate is considered premature.

I have created an initial crate skeleton, but I would like to agree on the ownership and dependency boundaries before expanding the implementation.

[Marc-André Lureau (elmarco)]

As long as rdpeusb remains protocol-specific, I guess it'd be welcome to offer a common helper crate to expose higher level USB type & behaviour. In the meantime, you can iterate on this crate inside qemu-rdp anyway and see if it remains truly generic and generally useful?

[Benoît Cortier (CBenoit)]

Hi! Thank you for the write-up. I’m generally in favor of the split. The suggested architecture matches IronRDP’s philosophy: clear ownership, reusable semantics, smaller dependency surfaces, and more parallel compilation.

I only have two cautions:

• Treat generic request/result types cautiously as RDPEUSB and usbredir may model operations differently. We should promote abstractions only after both adapters demonstrate a truely lossless common model.
• Ideally, make server integrations feature-gated so consumers do not pay for it unnecessarily, and same for client integrations.

The approach I would recommend: extract standard USB definitions first, implement the RDPEUSB and usbredir translations, then generalize shared operation types based on observed overlap.