Host driver

The host API is the other half of the library: instead of being a USB device, you drive one.

It is deliberately libusb-shaped - porting libusb code is essentially s/libusb_/usbip_host_/ - and it talks USB/IP itself, so it needs no kernel driver, no vhci and no root. It runs the same on Linux, Windows and macOS.

In USB/IP terms this side is the client (role table): something must already be serving before any of the calls below can succeed - a program on the device API, or a real usbipd exporting genuine hardware. Both are driven with identical code.

Link -lusbip-host (never both roles in one binary - see Getting Started).

This below example lists what a server exports, imports one device by vendor/product id, reads its descriptor over a control transfer, and round-trips a payload through its bulk endpoints. Run vendor_device first, then this against it.

 
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
 
#include "usbip-host.h"
 
#define VENDOR_ID   0x1209 /* what vendor_device serves */
#define PRODUCT_ID  0x0004
#define EP_BULK_OUT 0x01   /* host -> device */
#define EP_BULK_IN  0x81   /* device -> host */
 
int main(int argc, char **argv)
{
    const char *server = (argc > 1) ? argv[1] : NULL; /* NULL = local, 127.0.0.1 */
    int port = (argc > 2) ? atoi(argv[2]) : 3240;
 
    /* 1. a context. It starts on the local transport; name a server to go remote. */
    usbip_host_context *ctx;
    int rc = usbip_host_init(&ctx);
 
    if (rc != USB_SUCCESS)
    {
        fprintf(stderr, "usbip_host_init failed: %s\n", usb_strerror(rc));
        return 1;
    }
    if (server)
    {
        usb_transport *transport = usbip_transport(server, port);
 
        usbip_host_set_transport(ctx, transport);
    }
 
    /* 2. what does the server export? (the USB/IP device list) */
    usbip_host_device **list;
    long n_devices = usbip_host_get_device_list(ctx, &list);
 
    if (n_devices < 0)
    {
        fprintf(stderr, "device list failed: %s (is a device being served?)\n",
                usb_strerror((int)n_devices));
        usbip_host_exit(ctx);
        return 1;
    }
    printf("exported devices: %ld\n", n_devices);
 
    for (long i = 0; i < n_devices; i++)
    {
        usb_device_descriptor desc;
        usbip_host_get_device_descriptor(list[i], &desc);
        printf("  [%ld] %04x:%04x\n", i, desc.idVendor, desc.idProduct);
    }
    usbip_host_free_device_list(list);
 
    /* 3. import one of them by vendor/product id */
    usbip_host_handle *handle = usbip_host_open_vid_pid(ctx, VENDOR_ID, PRODUCT_ID);
 
    if (!handle)
    {
        fprintf(stderr, "open %04x:%04x failed (is vendor_device running?)\n",
                VENDOR_ID, PRODUCT_ID);
        usbip_host_exit(ctx);
        return 1;
    }
 
    /* 4. a control transfer: the standard GET_DESCRIPTOR(device) */
    usb_device_descriptor desc;
    int desc_bytes = usbip_host_control_transfer(handle, USB_REQ_DIR_IN, USB_REQ_GET_DESCRIPTOR,
                                                 0x0100, 0, (uint8_t *)&desc, sizeof(desc), 1000);
    printf("opened %04x:%04x (device descriptor: %d bytes, USB %x.%02x)\n",
           desc.idVendor, desc.idProduct, desc_bytes, USB_U16_MSB(desc.bcdUSB), USB_U16_LSB(desc.bcdUSB));
 
    usbip_host_set_configuration(handle, 1); /* required before endpoint I/O */
    usbip_host_claim_interface(handle, 0);
 
    /* 5. bulk I/O: send a payload, read the device's echo back */
    const char *message = "hello device";
    uint8_t echo[64];
    int n_sent = 0;
    int n_received = 0;
 
    rc = usbip_host_bulk_transfer(handle, EP_BULK_OUT, (uint8_t *)message,
                                  (int)strlen(message), &n_sent, 1000);
    if (rc == USB_SUCCESS)
        rc = usbip_host_bulk_transfer(handle, EP_BULK_IN, echo, sizeof(echo), &n_received, 1000);
 
    if (rc != USB_SUCCESS)
    {
        fprintf(stderr, "bulk transfer failed: %s\n", usb_strerror(rc));
        usbip_host_close(handle);
        usbip_host_exit(ctx);
        return 1;
    }
    printf("sent %d bytes, received %d back: \"%.*s\"\n", n_sent, n_received, n_received, echo);
 
    /* 6. done */
    usbip_host_release_interface(handle, 0);
    usbip_host_close(handle);
    usbip_host_exit(ctx);
 
    int matched = (n_received == n_sent) && memcmp(echo, message, (size_t)n_sent) == 0;
    const char *verdict = matched ? "OK: loopback round-trip matched\n" : "MISMATCH\n";
 
    printf("%s", verdict);
 
    return matched ? 0 : 1;
}

gcc host_drive.c -I. libusbip-host.a -pthread -o host_drive
./vendor_device        # the device being driven
./host_drive           # in a second terminal

On Windows the link line adds -lws2_32 -static and the programs end in .exe.

A Linux box exports real USB hardware with the kernel's own usbipd. Exporting is the one step that is Linux-only - usbipd / usbip bind have no equivalent elsewhere - while your driver still runs on any OS. Bind the device to the USB/IP host driver on the machine holding it:

sudo modprobe usbip-host
sudo usbipd -D                       # the USB/IP server daemon
usbip list -l                        # find the bus id, e.g. 3-2
sudo usbip bind -b 3-2               # export it

Then point a host context at that machine and use it exactly as above - the API does not know or care that the device is physical:

usb_transport *transport = usbip_transport("10.0.0.5", 3240);
usbip_host_set_transport(ctx, transport);

examples/host/host_probe.c is the tool for this: it enumerates a server, opens the first device, walks the configuration descriptor and issues a class request. It is how the library is tested against real kernel gadgets.

Everything hangs off a usbip_host_context: usbip_host_init() creates it, usbip_host_exit() destroys it. The context starts on the local transport; usbip_host_set_transport() points it at a remote server (the context does not take ownership - free the transport yourself with usbip_transport_free() after exit).

Enumeration is libusb's model: usbip_host_get_device_list() returns a NULL-terminated array of usbip_host_device (and the count), each of which answers usbip_host_get_device_descriptor() and opens with usbip_host_open(); release the array with usbip_host_free_device_list() (open handles stay valid). usbip_host_open_vid_pid() collapses all of that into one call when a VID:PID match is enough.

Configuration is the standard requests under libusb names: usbip_host_set_configuration() (SET_CONFIGURATION) and usbip_host_set_interface_alt_setting() (SET_INTERFACE). usbip_host_claim_interface() / usbip_host_release_interface() are compatibility no-ops - USB/IP has no kernel driver to detach and no exclusive-ownership concept - kept so ported libusb code compiles and runs unchanged.

Function	Transfer
usbip_host_control_transfer()	control (endpoint 0)
usbip_host_bulk_transfer()	bulk
usbip_host_interrupt_transfer()	interrupt
usbip_host_alloc_transfer() + usbip_host_fill_iso_transfer() + usbip_host_submit_transfer()	isochronous

The isochronous path mirrors libusb's asynchronous API - usbip_host_alloc_transfer(), usbip_host_fill_iso_transfer(), usbip_host_set_iso_packet_lengths(), usbip_host_get_iso_packet_buffer_simple(), usbip_host_free_transfer() - except that submission is synchronous: the USBIP host is blocking by design. examples/host/uvc_host.c pulls webcam frames this way.

A STALLed transfer returns USB_ERROR_PIPE; recover the pipe with usbip_host_clear_halt() (USB concepts explains STALL and halt). Every code renders through usb_strerror().

If the program that should drive the device already exists - dfu-util, lsusb, a pyusb script, a libusbK or WinUSB application - it needs no porting and none of the API above: Wrappers lets a stock binary drive a virtual device unmodified, and pyusb covers pyusb specifically.

• Host API - the full host API reference
• Wrappers - run an existing libusb / libusbK program instead
• USB/IP clients - importing into an OS instead of driving from code
• examples/host/ - the runnable programs: cdc_host, uvc_host, host_probe