USB/IP support¶

Renode provides a built-in USB/IP server and allows you to export virtual USB devices to the external world.

Exported devices can be attached to the host machine and from that moment the interaction with them is the same as with real hardware.

This allows for a hybrid setup where part of the system (i.e., virtual USB device and its environment) is simulated in Renode and the rest comes from the real world.

USB/IP protocol¶

The USB/IP protocol allows to share USB devices between a server (exporting party) and a client (importing party) over the IP network.

The protocol is well supported in Linux, and there exists a corresponding project for Windows as well, the latter however has not been tested.

Renode currently works as a server only - it is able to support exporting devices only, but is not able to connect physical USB devices to the emulation.

Creating a USB/IP server¶

In order to create a USB/IP server instance in Renode, type the following in the Monitor:

(monitor) emulation CreateUSBIPServer

As a result a host.usb device is created in the emulation and the server is started.

Now you can connect to it from your host machine. First, you need to import the vhci_hcd kernel module:

$ sudo modprobe vhci_hcd

Now, you can list exported devices:

$ sudo usbip list -r 127.0.0.1
usbip: info: no exportable devices found on 127.0.0.1

The output above informs that Renode is not exporting any devices at the moment.

Exporting devices¶

Let’s export a simple USB device - e.g. a mouse:

(monitor) host.usb AttachUSBMouse

Note

Note that there are some helper methods allowing to easily attach simple USB devices like mouse, keyboard or pendrive directly from host.usb. For more advanced scenario see Real life scenario: Foboot.

List exported devices again:

$ sudo usbip list -r 127.0.0.1
Exportable USB devices
======================
- 127.0.0.1
        1-0: unknown vendor : unknown product (0000:0000)
        : /renode/virtual/1-0
        : (Defined at Interface level) (00/00/00)
        :  0 - Human Interface Device / Boot Interface Subclass / Mouse (03/01/02)

Attaching exported device to host¶

The next step is to attach the exported virtual USB device to the host machine:

$ sudo usbip attach -r 127.0.0.1 -b 1-0

Note that the -b argument must match the device id returned by the usb list command.

A new USB mouse should be now visible in the host. Confirm it by reading the system logs:

$ sudo dmesg
...
[1310770.549767] usb 7-1: New USB device found, idVendor=0000, idProduct=0000, bcdDevice= 0.00
[1310770.549771] usb 7-1: New USB device strings: Mfr=0, Product=0, SerialNumber=0
[1310770.560676] input: HID 0000:0000 as /devices/platform/vhci_hcd.0/usb7/7-1/7-1:1.0/0003:0000:0000.002D/input/input66
[1310770.560888] hid-generic 0003:0000:0000.002D: input,hidraw4: USB HID v0.00 Mouse [HID 0000:0000] on usb-vhci_hcd.0-1/input0

Or with lsusb:

$ lsusb -v -d 0000:0000

Bus 007 Device 091: ID 0000:0000
Device Descriptor:
bLength                18
bDescriptorType         1
bcdUSB               2.00
bDeviceClass            0
bDeviceSubClass         0
bDeviceProtocol         0
bMaxPacketSize0        64
idVendor           0x0000
idProduct          0x0000
bcdDevice            0.00
iManufacturer           0
iProduct                0
iSerial                 0
bNumConfigurations      1
Configuration Descriptor:
    bLength                 9
    bDescriptorType         2
    wTotalLength       0x0022
    bNumInterfaces          1
    bConfigurationValue     1
    iConfiguration          0
    bmAttributes         0x00
    (Missing must-be-set bit!)
    (Bus Powered)
    MaxPower                0mA
    Interface Descriptor:
    bLength                 9
    bDescriptorType         4
    bInterfaceNumber        0
    bAlternateSetting       0
    bNumEndpoints           1
    bInterfaceClass         3 Human Interface Device
    bInterfaceSubClass      1 Boot Interface Subclass
    bInterfaceProtocol      2 Mouse
    iInterface              0
        HID Device Descriptor:
        bLength                 9
        bDescriptorType        33
        bcdHID               0.00
        bCountryCode            0 Not supported
        bNumDescriptors         1
        bDescriptorType        34 Report
        wDescriptorLength      46
        Report Descriptors:
        ** UNAVAILABLE **
    Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x81  EP 1 IN
        bmAttributes            3
        Transfer Type            Interrupt
        Synch Type               None
        Usage Type               Data
        wMaxPacketSize     0x0004  1x 4 bytes
        bInterval              10

Now you can control your mouse from Renode. Type:

(monitor) host.usb MoveMouse 100 100

and observe the cursor moving on the screen.

Real life scenario: Foboot¶

In this section we will show how to run a simulation of Foboot: The Bootloader for Fomu.

Foboot runs on the Fomu platform that uses the ValentyUSB core to implement a software-driven USB device where the whole logic (including generating USB descriptors) is executed by the CPU.

Create a Fomu platform¶

Renode comes with a definition of the Fomu platform. To create a new virtual Fomu instance, type in the Monitor:

(monitor) mach create
(machine-0) machine LoadPlatformDescription @platforms/cpus/fomu.repl

Load the Foboot software:

(machine-0) sysbus LoadELF @https://antmicro.com/projects/renode/fomu--foboot.elf-s_112080-70b1181d470646a31ebef7300fc8e6dc5447e282

Create a USB/IP server and export Fomu:

(machine-0) emulation CreateUSBIPServer
(machine-0) host.usb Register sysbus.valenty

Start the emulation:

(machine-0) start

Use it on your host machine¶

Import Fomu on the host:

$ sudo usbip attach -r 127.0.0.1 -b 1-0

Upload software using dfu-util:

$ wget https://antmicro.com/projects/renode/fomu--test_binary_flash.bin-s_1016-4a3c37baf69aeb401f834521b0ac4bc6d157ecdf -O fomu--test_binary_flash.bin
$ sudo dfu-util -D fomu--test_binary_flash.bin
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 1209:5bf0
Run-time device DFU version 0101
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0101
Device returned transfer size 1024
Copying data from PC to DFU device
Download    [=========================] 100%         1016 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(8) = dfuMANIFEST-WAIT-RESET, status(0) = No error condition is present
Done!

Disconnect dfu-util to reboot into the uploaded software:

$ sudo dfu-util -e

As Fomu does not have many interfaces we can observe, the uploaded binary is quite trivial. Looking through the log you will see repeated writes of consecutive values to 0x40000000.

To analyze the loaded binary in more detail you can use Renode’s GDB debugging capabilities or extensive logging support.

Last update: 2024-04-19