Drive USB devices - deliberately libusb-shaped. More...

Files
file	usbip-host.h
	Host API - write host drivers that drive USB devices over USB/IP.

Data Structures
struct	usbip_host_iso_packet_descriptor
	One isochronous packet's request/result (libusb-shaped). More...

struct	usbip_host_transfer
	An isochronous transfer (libusb-shaped; submitted synchronously). More...

Typedefs
typedef struct usbip_host_context	usbip_host_context
	Library session / device list owner.

typedef struct usbip_host_device	usbip_host_device
	An enumerated device, not yet opened.

typedef struct usbip_host_handle	usbip_host_handle
	An opened device, usable for I/O

Functions
int	usbip_host_init (usbip_host_context **ctx)
	Create a library context (the root object for enumeration and I/O).

void	usbip_host_exit (usbip_host_context *ctx)
	Destroy a context created by usbip_host_init() and free its resources.

int	usbip_host_set_transport (usbip_host_context ctx, usb_transport transport)
	Bind a USB/IP transport to the context - the only USB/IP-aware call.

long	usbip_host_get_device_list (usbip_host_context ctx, usbip_host_device **list)
	Enumerate the devices reachable on the context's transport.

void	usbip_host_free_device_list (usbip_host_device **list)
	Free a device list returned by usbip_host_get_device_list().

int	usbip_host_get_device_descriptor (usbip_host_device dev, usb_device_descriptor out)
	Copy an enumerated device's 18-byte device descriptor.

int	usbip_host_open (usbip_host_device dev, usbip_host_handle *handle)
	Open an enumerated device, yielding a handle for I/O.

usbip_host_handle *	usbip_host_open_vid_pid (usbip_host_context *ctx, uint16_t vid, uint16_t pid)
	Convenience: enumerate, match the first device by VID:PID, and open it.

void	usbip_host_close (usbip_host_handle *handle)
	Close a handle from usbip_host_open() / usbip_host_open_vid_pid().

int	usbip_host_set_configuration (usbip_host_handle *handle, int config)
	Select a configuration (standard SET_CONFIGURATION request).

int	usbip_host_claim_interface (usbip_host_handle *handle, int iface)
	Claim an interface.

int	usbip_host_release_interface (usbip_host_handle *handle, int iface)
	Release an interface claimed with usbip_host_claim_interface() (compatibility no-op).

int	usbip_host_set_interface_alt_setting (usbip_host_handle *handle, int iface, int alt)
	Select an interface's alternate setting (standard SET_INTERFACE request).

int	usbip_host_clear_halt (usbip_host_handle *handle, uint8_t endpoint)
	Clear a halted (STALLed) endpoint - `CLEAR_FEATURE(ENDPOINT_HALT)`.

int	usbip_host_control_transfer (usbip_host_handle handle, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, uint8_t data, uint16_t wLength, unsigned timeout_ms)
	Perform a synchronous control transfer on endpoint 0 (libusb-shaped).

int	usbip_host_bulk_transfer (usbip_host_handle handle, uint8_t endpoint, uint8_t data, int length, int *transferred, unsigned timeout_ms)
	Perform a synchronous bulk transfer (libusb-shaped).

int	usbip_host_interrupt_transfer (usbip_host_handle handle, uint8_t endpoint, uint8_t data, int length, int *transferred, unsigned timeout_ms)
	Perform a synchronous interrupt transfer (libusb-shaped).

usbip_host_transfer *	usbip_host_alloc_transfer (int num_iso_packets)
	Allocate an iso transfer with room for `num_iso_packets` packet descriptors.

void	usbip_host_free_transfer (usbip_host_transfer *transfer)
	Free a transfer from usbip_host_alloc_transfer().

void	usbip_host_fill_iso_transfer (usbip_host_transfer transfer, usbip_host_handle handle, uint8_t endpoint, uint8_t *buffer, int length, int num_iso_packets, unsigned timeout_ms)
	Populate an iso transfer's fields (libusb-shaped convenience setter).

void	usbip_host_set_iso_packet_lengths (usbip_host_transfer *transfer, unsigned length)
	Set every packet's requested length to `length` (the common equal-size case).

uint8_t *	usbip_host_get_iso_packet_buffer_simple (usbip_host_transfer *transfer, unsigned packet)
	Pointer to packet `packet's` data within the transfer buffer (assumes equal-size packets).

int	usbip_host_submit_transfer (usbip_host_transfer *transfer)
	Submit - and, here, synchronously complete - an isochronous transfer.

Detailed Description

Drive USB devices - deliberately libusb-shaped.

Initialise a usbip_host_context, optionally bind a transport with usbip_host_set_transport(), enumerate, open a device and run control / bulk / interrupt / isochronous transfers - against a virtual device or a real usbipd. The program is the USB/IP client (roles); porting libusb code is essentially s/libusb_/usbip_host_/.

Typedef Documentation

◆ usbip_host_context

typedef struct usbip_host_context usbip_host_context

Library session / device list owner.

◆ usbip_host_device

typedef struct usbip_host_device usbip_host_device

An enumerated device, not yet opened.

◆ usbip_host_handle

typedef struct usbip_host_handle usbip_host_handle

An opened device, usable for I/O

Function Documentation

◆ usbip_host_init()

int usbip_host_init ( usbip_host_context ** ctx )

Create a library context (the root object for enumeration and I/O).

The context starts on the local transport; call usbip_host_set_transport() to point it at a remote USB/IP server. Pair every successful call with usbip_host_exit().

Parameters

[out] ctx receives the new context on success.

Return values

USB_SUCCESS	context created.
USB_ERROR_NO_MEM	allocation failed (`*ctx` is left `NULL`).

◆ usbip_host_exit()

void usbip_host_exit ( usbip_host_context * ctx )

Destroy a context created by usbip_host_init() and free its resources.

Parameters

ctx	the context (may be `NULL`).

◆ usbip_host_set_transport()

int usbip_host_set_transport	(	usbip_host_context *	ctx,
		usb_transport *	transport
	)

Bind a USB/IP transport to the context - the only USB/IP-aware call.

This side is the USB/IP client: the transport names the server to connect to, which must already be serving (a program on the device API, or a real usbipd). Note that the wrappers' USBIP_HOST / USBIP_PORT variables do not apply here - this call is how a program using the host API picks its server.

Skip it and everything stays local. Set the transport before enumerating or opening devices; the context does not take ownership (free it yourself with usbip_transport_free() after usbip_host_exit()).

Parameters

ctx	the context.
transport	transport from usbip_transport(); `NULL` restores the local default.

Return values

USB_SUCCESS always.

◆ usbip_host_get_device_list()

long usbip_host_get_device_list	(	usbip_host_context *	ctx,
		usbip_host_device ***	list
	)

Enumerate the devices reachable on the context's transport.

On success list points to a freshly allocated, NULL-terminated array of usbip_host_device pointers; release it with usbip_host_free_device_list().

Parameters

	ctx	the context.
[out]	list	receives the device-list array.

Returns: the number of devices (>= 0), or a negative USB_ERROR code (e.g. USB_ERROR_IO if the transport is unreachable, USB_ERROR_NO_MEM).

◆ usbip_host_free_device_list()

void usbip_host_free_device_list ( usbip_host_device ** list )

Free a device list returned by usbip_host_get_device_list().

Parameters

list	the array to free (may be `NULL`). Handles opened from it stay valid.

◆ usbip_host_get_device_descriptor()

int usbip_host_get_device_descriptor	(	usbip_host_device *	dev,
		usb_device_descriptor *	out
	)

Copy an enumerated device's 18-byte device descriptor.

Parameters

	dev	a device from usbip_host_get_device_list().
[out]	out	receives the descriptor.

Return values

USB_SUCCESS on success.

Returns: a negative USB_ERROR code otherwise.

◆ usbip_host_open()

int usbip_host_open	(	usbip_host_device *	dev,
		usbip_host_handle **	handle
	)

Open an enumerated device, yielding a handle for I/O.

Parameters

	dev	the device to open.
[out]	handle	receives the open handle on success.

Return values

USB_SUCCESS	opened.
USB_ERROR_NO_DEVICE	the device is gone.
USB_ERROR_IO	the transport failed.

◆ usbip_host_open_vid_pid()

usbip_host_handle * usbip_host_open_vid_pid	(	usbip_host_context *	ctx,
		uint16_t	vid,
		uint16_t	pid
	)

Convenience: enumerate, match the first device by VID:PID, and open it.

Parameters

ctx	the context.
vid	vendor ID to match.
pid	product ID to match.

Returns: an open handle, or NULL if no match was found or opening failed.

◆ usbip_host_close()

void usbip_host_close ( usbip_host_handle * handle )

Close a handle from usbip_host_open() / usbip_host_open_vid_pid().

Parameters

handle the handle (may be NULL).

◆ usbip_host_set_configuration()

int usbip_host_set_configuration	(	usbip_host_handle *	handle,
		int	config
	)

Select a configuration (standard SET_CONFIGURATION request).

Parameters

handle	an open handle.
config	the bConfigurationValue to activate.

Return values

USB_SUCCESS on success; a negative USB_ERROR code otherwise.

◆ usbip_host_claim_interface()

int usbip_host_claim_interface	(	usbip_host_handle *	handle,
		int	iface
	)

Claim an interface.

USB/IP has no kernel driver to detach and no exclusive-ownership concept, so this is a compatibility no-op kept for libusb source parity.

Parameters

handle	an open handle.
iface	the interface number.

Return values

USB_SUCCESS always.

◆ usbip_host_release_interface()

int usbip_host_release_interface	(	usbip_host_handle *	handle,
		int	iface
	)

Release an interface claimed with usbip_host_claim_interface() (compatibility no-op).

Parameters

handle	an open handle.
iface	the interface number.

Return values

USB_SUCCESS always.

◆ usbip_host_set_interface_alt_setting()

int usbip_host_set_interface_alt_setting	(	usbip_host_handle *	handle,
		int	iface,
		int	alt
	)

Select an interface's alternate setting (standard SET_INTERFACE request).

Parameters

handle	an open handle.
iface	the interface number.
alt	the alternate setting to activate.

Return values

USB_SUCCESS on success; a negative USB_ERROR code otherwise.

◆ usbip_host_clear_halt()

int usbip_host_clear_halt	(	usbip_host_handle *	handle,
		uint8_t	endpoint
	)

Clear a halted (STALLed) endpoint - CLEAR_FEATURE(ENDPOINT_HALT).

The standard recovery after a transfer returns USB_ERROR_PIPE: a device halts a pipe to abandon a transfer it cannot complete, and the pipe stays halted until this clears it. Mass storage relies on it - a failed data phase halts the bulk pipe, and the status wrapper can only be read once cleared.

Parameters

handle	an open handle.
endpoint	the endpoint address, direction bit included.

Return values

USB_SUCCESS on success; a negative USB_ERROR code otherwise.

◆ usbip_host_control_transfer()

int usbip_host_control_transfer	(	usbip_host_handle *	handle,
		uint8_t	bmRequestType,
		uint8_t	bRequest,
		uint16_t	wValue,
		uint16_t	wIndex,
		uint8_t *	data,
		uint16_t	wLength,
		unsigned	timeout_ms
	)

Perform a synchronous control transfer on endpoint 0 (libusb-shaped).

Parameters

handle	an open handle.
bmRequestType	request type bitmask (direction in bit 7 - see usb_setup).
bRequest	request code.
wValue	request-specific value.
wIndex	request-specific index.
data	IN: buffer that receives up to `wLength` bytes; OUT: the `wLength` bytes to send (may be `NULL` when `wLength` is 0).
wLength	size of the data stage in bytes.
timeout_ms	timeout in milliseconds (0 = wait indefinitely).

Returns: the number of bytes transferred (>= 0), or a negative USB_ERROR code - notably USB_ERROR_PIPE if the device STALLed the request, or USB_ERROR_TIMEOUT.

◆ usbip_host_bulk_transfer()

int usbip_host_bulk_transfer	(	usbip_host_handle *	handle,
		uint8_t	endpoint,
		uint8_t *	data,
		int	length,
		int *	transferred,
		unsigned	timeout_ms
	)

Perform a synchronous bulk transfer (libusb-shaped).

Parameters

	handle	an open handle.
	endpoint	endpoint address; bit 7 sets direction (0x81 = IN, 0x01 = OUT).
	data	IN: receive buffer; OUT: data to send.
	length	buffer size / bytes to send.
[out]	transferred	receives the number of bytes actually transferred (may be `NULL`).
	timeout_ms	timeout in milliseconds (0 = wait indefinitely).

Return values

USB_SUCCESS on success (count returned via transferred).

Returns: a negative USB_ERROR code otherwise (e.g. USB_ERROR_PIPE, USB_ERROR_TIMEOUT).

◆ usbip_host_interrupt_transfer()

int usbip_host_interrupt_transfer	(	usbip_host_handle *	handle,
		uint8_t	endpoint,
		uint8_t *	data,
		int	length,
		int *	transferred,
		unsigned	timeout_ms
	)

Perform a synchronous interrupt transfer (libusb-shaped).

Same contract as usbip_host_bulk_transfer().

Parameters

	handle	an open handle.
	endpoint	endpoint address (bit 7 = direction).
	data	IN: receive buffer; OUT: data to send.
	length	buffer size / bytes to send.
[out]	transferred	receives the byte count actually transferred (may be `NULL`).
	timeout_ms	timeout in milliseconds (0 = wait indefinitely).

Return values

USB_SUCCESS on success; a negative USB_ERROR code otherwise.

◆ usbip_host_alloc_transfer()

usbip_host_transfer * usbip_host_alloc_transfer ( int num_iso_packets )

Allocate an iso transfer with room for num_iso_packets packet descriptors.

Parameters

num_iso_packets number of isochronous packets (>= 1).

Returns: a zeroed usbip_host_transfer, or NULL on allocation failure. Free it with usbip_host_free_transfer().

◆ usbip_host_free_transfer()

void usbip_host_free_transfer ( usbip_host_transfer * transfer )

Free a transfer from usbip_host_alloc_transfer().

Parameters

transfer the transfer (may be NULL). The data buffer is the caller's and is not freed here.

◆ usbip_host_fill_iso_transfer()

void usbip_host_fill_iso_transfer	(	usbip_host_transfer *	transfer,
		usbip_host_handle *	handle,
		uint8_t	endpoint,
		uint8_t *	buffer,
		int	length,
		int	num_iso_packets,
		unsigned	timeout_ms
	)

Populate an iso transfer's fields (libusb-shaped convenience setter).

Parameters

transfer	the transfer.
handle	target handle.
endpoint	endpoint address (bit 7 = direction).
buffer	packet data buffer (caller-owned).
length	total `buffer` length.
num_iso_packets	packet count (must match usbip_host_alloc_transfer()).
timeout_ms	timeout in milliseconds (0 = indefinite).

◆ usbip_host_set_iso_packet_lengths()

void usbip_host_set_iso_packet_lengths	(	usbip_host_transfer *	transfer,
		unsigned	length
	)

Set every packet's requested length to length (the common equal-size case).

Parameters

transfer	the transfer.
length	per-packet requested length in bytes.

◆ usbip_host_get_iso_packet_buffer_simple()

uint8_t * usbip_host_get_iso_packet_buffer_simple	(	usbip_host_transfer *	transfer,
		unsigned	packet
	)

Pointer to packet packet's data within the transfer buffer (assumes equal-size packets).

Parameters

transfer	the transfer.
packet	zero-based packet index.

Returns: a pointer into t->buffer, or NULL if packet is out of range.

◆ usbip_host_submit_transfer()

int usbip_host_submit_transfer ( usbip_host_transfer * transfer )

Submit - and, here, synchronously complete - an isochronous transfer.

On return, t->actual_length and each iso_packet_desc[i].actual_length / .status are filled in.

Parameters

transfer a transfer prepared with usbip_host_fill_iso_transfer().

Return values

USB_SUCCESS the transfer completed (check per-packet status for partials).

Returns: a negative USB_ERROR code if it could not be submitted.

Files

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ usbip_host_context

◆ usbip_host_device

◆ usbip_host_handle

Function Documentation

◆ usbip_host_init()

◆ usbip_host_exit()

◆ usbip_host_set_transport()

◆ usbip_host_get_device_list()

◆ usbip_host_free_device_list()

◆ usbip_host_get_device_descriptor()

◆ usbip_host_open()

◆ usbip_host_open_vid_pid()

◆ usbip_host_close()

◆ usbip_host_set_configuration()

◆ usbip_host_claim_interface()

◆ usbip_host_release_interface()

◆ usbip_host_set_interface_alt_setting()

◆ usbip_host_clear_halt()

◆ usbip_host_control_transfer()

◆ usbip_host_bulk_transfer()

◆ usbip_host_interrupt_transfer()

◆ usbip_host_alloc_transfer()

◆ usbip_host_free_transfer()

◆ usbip_host_fill_iso_transfer()

◆ usbip_host_set_iso_packet_lengths()

◆ usbip_host_get_iso_packet_buffer_simple()

◆ usbip_host_submit_transfer()