usbip.h File Reference

Shared, role-neutral types and the transport seam. More...

#include <stdint.h>
#include <stddef.h>
#include <string.h>

Data Structures
struct	usb_setup
	The 8-byte SETUP packet that begins every control transfer (host byte order in the API). More...
struct	usb_device_descriptor
	Standard USB device descriptor (Sec.9.6.1). More...
struct	usb_config_descriptor
	Standard configuration descriptor (Sec.9.6.3). More...
struct	usb_interface_descriptor
	Standard interface descriptor (Sec.9.6.5). More...
struct	usb_endpoint_descriptor
	Standard endpoint descriptor (Sec.9.6.6). More...

Macros
#define	USBIP_VERSION
	USBIP release version, as a string literal.
#define	USBIP_VERSION_MAJOR
	Major part of USBIP_VERSION.
#define	USBIP_VERSION_MINOR
	Minor part of USBIP_VERSION.
#define	USBIP_VERSION_MICRO
	Micro (patch) part of USBIP_VERSION.
#define	USB_PACKED
	Give a descriptor struct the wire's layout: no padding, and little-endian storage.
#define	USB_U16LE(x)
	A 16-bit value as its two little-endian bytes, for descriptor initialisers.
#define	USB_U24LE(x)
	A 24-bit value as its three little-endian bytes (a UAC sample rate, say).
#define	USB_U32LE(x)
	A 32-bit value as its four little-endian bytes.
#define	USB_U16BE(x)
	A 16-bit value as its two big-endian bytes, for the class payloads that are big-endian on the wire (SCSI, CTAPHID, PTP status words).
#define	USB_U24BE(x)
	A 24-bit value as its three big-endian bytes.
#define	USB_U32BE(x)
	A 32-bit value as its four big-endian bytes.
#define	USB_U16_LSB(x)
	The least significant byte of a 16-bit value - the index half of a wValue, an interface number out of a wIndex.
#define	USB_U16_MSB(x)
	The most significant byte of a 16-bit value - the type half of a wValue, a control selector, a report type.
#define	USB_BCD_USB_2_0
	bcdUSB: USB 2.0
#define	USB_BCD_DEVICE_DEFAULT
	bcdDevice: device release 1.00, unless set
#define	USB_EP_ADDR_NUM_MASK
	bEndpointAddress is a 4-bit endpoint number plus a direction bit.
#define	USB_EP_ADDR_DIR_IN
	Direction bit set = IN (device to host)
#define	USB_EP_SYNC_NONE
	Isochronous synchronisation type - bits 3:2 of bmAttributes.
#define	USB_EP_SYNC_ASYNC
	Asynchronous - free-running source, the host adapts.
#define	USB_EP_SYNC_ADAPTIVE
	Adaptive - the endpoint follows the host's rate.
#define	USB_EP_SYNC_SYNC
	Synchronous - locked to the bus SOF clock.
#define	USB_EP_USAGE_DATA
	Isochronous usage type - bits 5:4 of bmAttributes.
#define	USB_EP_USAGE_FEEDBACK
	Feedback endpoint (reports the sink's rate)
#define	USB_REQ_DIR_IN
	bmRequestType bit 7: device-to-host
#define	USB_REQ_TYPE(bmRequestType)
	Extract the usb_req_type from a bmRequestType (bits 6:5).
#define	USB_REQ_RECIP(bmRequestType)
	Extract the recipient from a bmRequestType (bits 4:0).
#define	USB_FEATURE_ENDPOINT_HALT
	wValue for CLEAR_FEATURE / SET_FEATURE on an endpoint recipient (USB 2.0 Table 9-6).
#define	USB_STATUS_ENDPOINT_HALT
	GET_STATUS on an endpoint recipient returns this bit set while the endpoint is halted.
#define	USB_DT_CLASS_SPECIFIC_BASE
	Descriptor types below this are standard; from here up they are class-specific (0x21 HID, 0x24 CS_INTERFACE, ...) and belong to a class, not the core.
#define	USB_EP0_MAX_PACKET
	Fixed fields of the device and configuration descriptors this library emits.
#define	USB_NUM_CONFIGURATIONS
	Exactly one configuration is exposed.
#define	USB_CONFIG_VALUE
	Its bConfigurationValue.
#define	USB_CONFIG_ATTR_BUS_POWERED
	bmAttributes bit 7: reserved, always set
#define	USB_CONFIG_MAX_POWER_100MA
	bMaxPower, counted in 2 mA units
#define	USB_DT_DEVICE
	Standard descriptor type codes (the bDescriptorType field, Sec.9.6).
#define	USB_DT_CONFIG
	Configuration descriptor.
#define	USB_DT_STRING
	String descriptor.
#define	USB_DT_INTERFACE
	Interface descriptor.
#define	USB_DT_ENDPOINT
	Endpoint descriptor.
#define	USB_DT_INTERFACE_ASSOCIATION
	IAD - groups interfaces into one function.
#define	USB_CLASS_PER_INTERFACE
	USB-IF base class codes, as they appear in bInterfaceClass (and in bDeviceClass for the few that are device-defining).
#define	USB_CLASS_AUDIO
	Audio (UAC)
#define	USB_CLASS_CDC
	Communications and CDC Control.
#define	USB_CLASS_HID
	Human Interface Device.
#define	USB_CLASS_IMAGE
	Still Imaging (PTP; MTP rides on it)
#define	USB_CLASS_MSC
	Mass Storage.
#define	USB_CLASS_CDC_DATA
	CDC Data.
#define	USB_CLASS_VIDEO
	Video (UVC)
#define	USB_CLASS_WIRELESS
	Wireless Controller (Bluetooth radio)
#define	USB_CLASS_MISC
	Miscellaneous (see the IAD triple below)
#define	USB_CLASS_APP_SPEC
	Application Specific (DFU)
#define	USB_CLASS_VENDOR_SPEC
	Vendor Specific.
#define	USB_SUBCLASS_COMMON
	The device-descriptor class triple that declares a device composite: its functions are described by Interface Association Descriptors rather than by a single device-wide class (USB-IF IAD ECN).
#define	USB_PROTOCOL_IAD
	bDeviceProtocol: Interface Association Descriptor
#define	USB_SUCCESS
	Error/status codes - same values as libusb, so ported constants keep working.
#define	USB_ERROR_IO
	Input/output error on the transport.
#define	USB_ERROR_INVALID_PARAM
	An argument was invalid.
#define	USB_ERROR_ACCESS
	Insufficient permissions.
#define	USB_ERROR_NO_DEVICE
	The device has been disconnected.
#define	USB_ERROR_NOT_FOUND
	Entity not found (no matching device/endpoint)
#define	USB_ERROR_BUSY
	Resource busy.
#define	USB_ERROR_TIMEOUT
	The operation timed out.
#define	USB_ERROR_PIPE
	Endpoint STALLed / pipe error.
#define	USB_ERROR_NO_MEM
	Out of memory.
#define	USB_ERROR_OTHER
	Other / unspecified error.
#define	USB_SETUP_BYTES(type, request, value, index, length)
	The same SETUP packet as the eight bytes that go on the wire, for the client side, which submits it as a byte array rather than a struct:
Standard request codes
bRequest values for USB_STANDARD requests (USB 2.0 Table 9-4). The core answers these itself; a class only ever sees USB_CLASS / USB_VENDOR ones, plus GET_DESCRIPTOR for its own class-specific descriptor types.
#define	USB_REQ_GET_STATUS
	Read the recipient's 2-byte status word (see USB_STATUS_ENDPOINT_HALT)
#define	USB_REQ_CLEAR_FEATURE
	Clear a feature on the recipient (see USB_FEATURE_ENDPOINT_HALT)
#define	USB_REQ_SET_FEATURE
	Set a feature on the recipient.
#define	USB_REQ_SET_ADDRESS
	Assign the device its bus address (handled by the host stack)
#define	USB_REQ_GET_DESCRIPTOR
	Fetch a descriptor; wValue is type:index (see the USB_DT_* codes)
#define	USB_REQ_SET_DESCRIPTOR
	Write a descriptor - optional, this library does not implement it.
#define	USB_REQ_GET_CONFIGURATION
	Read the active bConfigurationValue.
#define	USB_REQ_SET_CONFIGURATION
	Select a configuration; only USB_CONFIG_VALUE exists here.
#define	USB_REQ_GET_INTERFACE
	Read an interface's current alternate setting.
#define	USB_REQ_SET_INTERFACE
	Select an interface's alternate setting (how streaming classes start/stop)
#define	USB_REQ_SYNCH_FRAME
	Report an isochronous endpoint's synchronization frame.
Request recipients
Bits 4:0 of bmRequestType (USB 2.0 Table 9-2).
#define	USB_RECIP_DEVICE
	The device as a whole.
#define	USB_RECIP_INTERFACE
	One interface, named by the low byte of wIndex.
#define	USB_RECIP_ENDPOINT
	One endpoint, named by the low byte of wIndex.

Typedefs
typedef struct usb_transport	usb_transport
	Opaque handle to a USB/IP transport (the wire under host/device calls).

Enumerations
enum	usb_dir { USB_OUT , USB_IN }
	Transfer direction (matches bit 7 of an endpoint address / bmRequestType). More...
enum	usb_xfer_type { USB_CONTROL , USB_ISO , USB_BULK , USB_INTR }
	Endpoint transfer type (the transfer-type field of bmAttributes). More...
enum	usb_req_type { USB_STANDARD , USB_CLASS , USB_VENDOR }
	Control-request type - bits 6:5 of the SETUP packet's bmRequestType. More...
enum	usb_speed { USB_SPEED_LOW , USB_SPEED_FULL , USB_SPEED_HIGH , USB_SPEED_SUPER }
	Reported link speed (select with usbip_device_set_speed()). More...

Functions
const char *	usb_strerror (int code)
	Map a USB_* status/error code to a human-readable string.
usb_transport *	usbip_transport (const char *host, int port)
	Create a real USB/IP transport over TCP.
usb_transport *	usbip_loopback (void)
	Create an in-process transport for tests - no sockets, no kernel, no root.
void	usbip_transport_free (usb_transport *transport)
	Release a transport created by usbip_transport() / usbip_loopback().

Detailed Description

Shared, role-neutral types and the transport seam.

Everything both roles need in one header: the USB constants and packed descriptor structs, the unaligned little/big-endian accessors, the USB_* error codes, and the usb_transport handle under every host/device call. Include it through usbip-device.h or usbip-host.h.

Prefixes: usb_* (shared types) · usbip_host_* (host side) · usbip_* (wire / transport). On the device side the prefix names the receiver of the first parameter - usbip_device_*, usbip_function_*, usbip_interface_*, usbip_endpoint_* - with usbip_device_* also covering the data path (usbip_device_read()/usbip_device_write()), mirroring usbip_host_*.

Macro Definition Documentation

USBIP_VERSION

#define USBIP_VERSION

USBIP release version, as a string literal.

Keep in sync with python usbip.__version__.

USBIP_VERSION_MAJOR

#define USBIP_VERSION_MAJOR

Major part of USBIP_VERSION.

USBIP_VERSION_MINOR

#define USBIP_VERSION_MINOR

Minor part of USBIP_VERSION.

USBIP_VERSION_MICRO

#define USBIP_VERSION_MICRO

Micro (patch) part of USBIP_VERSION.

USB_PACKED

#define USB_PACKED

Give a descriptor struct the wire's layout: no padding, and little-endian storage.

Apply it to every struct whose bytes go out on the bus.

USB descriptors are little-endian by definition, so that is a property of the type rather than something each emitter has to remember. Fields are still read and written in host order - .wMaxPacketSize = 512, s->wValue - and the compiler swaps on access, so a descriptor can be serialized (and a SETUP packet parsed) with a plain memcpy on any host. On a little-endian build nothing is emitted at all; the attribute costs nothing there.

The one restriction, and it is a useful one: you cannot take the address of a multi-byte field (&desc->wLength). GCC rejects it outright on a big-endian build rather than handing out a pointer to bytes in the wrong order.

USB_U16LE

#define USB_U16LE

(

x

)

A 16-bit value as its two little-endian bytes, for descriptor initialisers.

The expansion is a comma-separated byte pair rather than a single value, so a whole descriptor can be written as one array in wire order:

uint8_t d[] = { 18, USB_DT_DEVICE, USB_U16LE(bcdUSB), ... };

Endian-safe by construction - the shifts do not depend on host byte order. The argument is expanded once per byte, so it must not have side effects.

Parameters

x	the value to emit.

USB_U24LE

#define USB_U24LE

(

x

)

A 24-bit value as its three little-endian bytes (a UAC sample rate, say).

See USB_U16LE.

Parameters

x	the value to emit.

USB_U32LE

#define USB_U32LE

(

x

)

A 32-bit value as its four little-endian bytes.

See USB_U16LE.

Parameters

x	the value to emit.

USB_U16BE

#define USB_U16BE

(

x

)

A 16-bit value as its two big-endian bytes, for the class payloads that are big-endian on the wire (SCSI, CTAPHID, PTP status words).

See USB_U16LE.

Parameters

x	the value to emit.

USB_U24BE

#define USB_U24BE

(

x

)

A 24-bit value as its three big-endian bytes.

See USB_U16BE.

Parameters

x	the value to emit.

USB_U32BE

#define USB_U32BE

(

x

)

A 32-bit value as its four big-endian bytes.

See USB_U16BE.

Parameters

x	the value to emit.

USB_U16_LSB

#define USB_U16_LSB

(

x

)

The least significant byte of a 16-bit value - the index half of a wValue, an interface number out of a wIndex.

Parameters

x	the 16-bit value to take the byte from.

USB_U16_MSB

#define USB_U16_MSB

(

x

)

The most significant byte of a 16-bit value - the type half of a wValue, a control selector, a report type.

Parameters

x	the 16-bit value to take the byte from.