[qemu] Earlgrey 1.0.0 `usb` implementation

[moidx]

Description

Proposed implementation

lowRISC proposes implementing the USB IP block using USB/IP.

USB/IP is a protocol designed to share USB devices across computers by encapsulating USB protocol messages into TCP/IP payloads and transmitting them over the network. In this architecture, a client that wishes to use a USB device connects to a server that exposes one or more USB devices. In our case, the client would be the workstation running QEMU and the server would be QEMU. A QEMU device would implement the server side of the USB/IP protocol and interact with the guest system to emulate the OT USB IP block.

• The OT QEMU USB device would need to translate the high-level USB transactions into the corresponding packets that the real OT USB would handle.
• The QEMU USB device would also emulate the corresponding IP block behaviours such as the FIFO usage, generating interrupt signals, and updating various other register values, all based on the high-level transactions being emulated.

[moidx]

CC @korran @a-will @amit-kumarh

[moidx]

Question from @luismarques: Can you confirm the integration requirement? Is it ok for the device to be exposed as a kernel module, or should it be emulated?

@cfrantz can you clarify which kernel module is needed to enable this, and confirm that this will enable the USB to show up in the host USB device hierarchy?

@luismarques will confirm the module name.

[pamaury]

Just to clarify the question: the QEMU driver will emulate the USB device but USB requires a host. So the question is: is it ok if the USB device is virtually "plugged" to the linux host through USB-IP? This requires a kernel module which I think is vhci_hcd (which depends on usbip_core) but I need to confirm that. The idea would be that the QEMU USB driver creates a USB/IP server and the kernel module vhci_hcd connects to it, which effectively attaches the OT USB device to the linux USB stack.

[amit-kumarh]

@pamaury Our existing simulation infrastructure uses a library called usbredir to interface with emulated USB devices, which broadly implements the same USB over network concept (and natively supports QEMU integration). So yes, virtually plugging in to the Linux host is fine, but if we're able to use usbredir library for the USB redirection that would be best for us.

cc @cfrantz

[pamaury]

@amit-kumarh I will look into it, it looks very similar.

[pamaury]

@amit-kumarh Could you clarify a few things? From the usbredir documentation, it seems that QEMU has code to create a virtual USB host controller inside the VM, and then one can attach (real or emulated) USB devices to it. Although the only tool provided by usbredir (as far as I can see) is to attach real USB device.

But in our case, we want the opposite? We want QEMU to emulate a USB device (not host) and plug that into a real USB host stack. So unless the host stack is itself in a QEMU VM (which create quite a burden for development), this library does not seem as useful compared to USB/IP? I am missing something?

[amit-kumarh]

@pamaury Gotcha - you are correct, usbredir natively only supports the QEMU guest being the USB host; that was an oversight from me mixing up host vs device vs guest. Final answer - yep, connecting to the Linux host with USB/IP will be work for us.

[pamaury]

I have looked into QEMU, USB/IP and I have a plan.

I have been playing with USB/IP outside of QEMU to get more familiar with the protocol. The protocol seems to work well for transfers but it definitely has some sharp edges/limitations

The main limitation is that the server (which provides a USB device, it's kind of backwards) receives requests to list devices, but has no out of band mechanism to report the (dis)appearance of devices. So if you want to know that a new device has appeared, you have to busy poll. On top of that, a client (which wants to use a device provided by the host), has to explicitely import ("attach") devices before using them (at least when using the official tooling) so if the device resets or disconnectes/reconnects, one has to redo the import step. This is not ideal for automation, but can be covered for by custom tooling (either by polling or extending the USB/IP protocol).

For the protocol itself, there are issues around non-transfers events: the protocol has no notion of resets. As far as I can see, if you reset a USB device using the vhci_vcd kernel driver, it does nothing. The only way you know that it was reset is because it will go through the "ask device descriptor" dance. Also there is no support for resume/suspend at all. All of those issues come from the fact that the vhci_hcd kernel drivers emulates a root hub to host "virtual" devices but it only implements the minimum of the minimum to support it [*]. Again this can be covered for by extending the protocol.

Another thing to keep in mind is that the way the protocol is design, the server in order to expose a device has to provide the full set of configuration descriptors. This means that the server has to implement a "mini-host" to at least query the descriptors out of the device, before even doing anything with USB/IP.

Finally, a last detail is that we obviously cannot manage VBUS in emulation the same way as it works in hardware.

There are some additional technical details which will need to be investigated (like SOF handling) but those are probably not critical and can be added later.

Therefore the plan of action I have is:

• create QEMU driver with a "management" interface of a chardev device
• implement minimal VBUS management over this chardev
• implement data transfers and a "minihost" to query the descriptors
• wire up USB/IP into this
• add additional reset/suspend/resume management over the chardev/as a USB/IP extension.

@amit-kumarh It would be useful to know of a precise usecase for this driver. In particuler, is the handling of resets/suspend/resume particularly important or is it mostly going to be standard control/bulk/interrupt transfers?

[*] As an experiment, I tried to emulate a virtual hub with USB/IP which implements suspend/reset/resume (since those are just bits in HUB registers). It kind of worked in the sense that the host can see my host but obviously it fails to enumerate anything below the hub because vhci_hcd explicitely tracks connected devices and assumes all devices are not hub, so it fails any transfer to a device that it doesn't know. Maybe this can be worked around, I still have to look into it.
For resume/suspend, we could create our own USB/IP requests, I think it would be acceptable since linux does not provide an official API for that anyway. But for resets that's really more problematic if you can't even assume that the official way to reset doesn't work.

[korran]

Doesn't the USB hub specification include control requests for reset/suspend/resume (See 11.24.2.13 Set Port Feature in the usb 2.0 spec)? Could you instantiate a virtual hub inside qemu and then let the kernel control that via USB/IP?

We can get by for awhile without suspend/resume, but it is important that the peripheral send the INTR_STATE.LINK_RESET interrupt to our firmware when the simulated connection is first made to the host, and a second time before SET_ADDRESS.

Also, USB reset has meaning the the rescue protocol implemented by the ROM_EXT; there's needs to be some mechanism for actuating this from a test-case.