USB descriptors & types

Shared, role-neutral USB types used by both host and device. More...

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	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_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:

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...

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.

Detailed Description

Shared, role-neutral USB types used by both host and device.

Standard descriptor structs (device / configuration / interface / endpoint), the 8-byte SETUP packet, and the direction / transfer-type / speed enums.

Macro Definition Documentation

USB_BCD_USB_2_0

#define USB_BCD_USB_2_0

bcdUSB: USB 2.0

USB_BCD_DEVICE_DEFAULT

#define USB_BCD_DEVICE_DEFAULT

bcdDevice: device release 1.00, unless set

USB_EP_ADDR_NUM_MASK

#define USB_EP_ADDR_NUM_MASK

bEndpointAddress is a 4-bit endpoint number plus a direction bit.

Endpoint number within bEndpointAddress

USB_EP_ADDR_DIR_IN

#define USB_EP_ADDR_DIR_IN

Direction bit set = IN (device to host)

USB_EP_SYNC_NONE

#define USB_EP_SYNC_NONE

Isochronous synchronisation type - bits 3:2 of bmAttributes.

No synchronisation

USB_EP_SYNC_ASYNC

#define USB_EP_SYNC_ASYNC

Asynchronous - free-running source, the host adapts.

USB_EP_SYNC_ADAPTIVE

#define USB_EP_SYNC_ADAPTIVE

Adaptive - the endpoint follows the host's rate.

USB_EP_SYNC_SYNC

#define USB_EP_SYNC_SYNC

Synchronous - locked to the bus SOF clock.

USB_EP_USAGE_DATA

#define USB_EP_USAGE_DATA

Isochronous usage type - bits 5:4 of bmAttributes.

Data endpoint

USB_EP_USAGE_FEEDBACK

#define USB_EP_USAGE_FEEDBACK

Feedback endpoint (reports the sink's rate)

USB_REQ_GET_STATUS

#define USB_REQ_GET_STATUS

Read the recipient's 2-byte status word (see USB_STATUS_ENDPOINT_HALT)

USB_REQ_CLEAR_FEATURE

#define USB_REQ_CLEAR_FEATURE

Clear a feature on the recipient (see USB_FEATURE_ENDPOINT_HALT)

USB_REQ_SET_FEATURE

#define USB_REQ_SET_FEATURE

Set a feature on the recipient.

USB_REQ_SET_ADDRESS

#define USB_REQ_SET_ADDRESS

Assign the device its bus address (handled by the host stack)

USB_REQ_GET_DESCRIPTOR

#define USB_REQ_GET_DESCRIPTOR

Fetch a descriptor; wValue is type:index (see the USB_DT_* codes)

USB_REQ_SET_DESCRIPTOR

#define USB_REQ_SET_DESCRIPTOR

Write a descriptor - optional, this library does not implement it.

USB_REQ_GET_CONFIGURATION

#define USB_REQ_GET_CONFIGURATION

Read the active bConfigurationValue.

USB_REQ_SET_CONFIGURATION

#define USB_REQ_SET_CONFIGURATION

Select a configuration; only USB_CONFIG_VALUE exists here.

USB_REQ_GET_INTERFACE

#define USB_REQ_GET_INTERFACE

Read an interface's current alternate setting.

USB_REQ_SET_INTERFACE

#define USB_REQ_SET_INTERFACE

Select an interface's alternate setting (how streaming classes start/stop)

USB_REQ_SYNCH_FRAME

#define USB_REQ_SYNCH_FRAME

Report an isochronous endpoint's synchronization frame.

USB_REQ_DIR_IN

#define USB_REQ_DIR_IN

bmRequestType bit 7: device-to-host

USB_REQ_TYPE

#define USB_REQ_TYPE

(

bmRequestType

)

Extract the usb_req_type from a bmRequestType (bits 6:5).

USB_RECIP_DEVICE

#define USB_RECIP_DEVICE

The device as a whole.

USB_RECIP_INTERFACE

#define USB_RECIP_INTERFACE

One interface, named by the low byte of wIndex.

USB_RECIP_ENDPOINT

#define USB_RECIP_ENDPOINT

One endpoint, named by the low byte of wIndex.

USB_REQ_RECIP

#define USB_REQ_RECIP

(

bmRequestType

)

Extract the recipient from a bmRequestType (bits 4:0).

USB_FEATURE_ENDPOINT_HALT

#define USB_FEATURE_ENDPOINT_HALT

wValue for CLEAR_FEATURE / SET_FEATURE on an endpoint recipient (USB 2.0 Table 9-6).

USB_STATUS_ENDPOINT_HALT

#define USB_STATUS_ENDPOINT_HALT

GET_STATUS on an endpoint recipient returns this bit set while the endpoint is halted.

USB_DT_CLASS_SPECIFIC_BASE

#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.

USB_EP0_MAX_PACKET

#define USB_EP0_MAX_PACKET

Fixed fields of the device and configuration descriptors this library emits.

bMaxPacketSize0 for a full/high-speed device

USB_NUM_CONFIGURATIONS

#define USB_NUM_CONFIGURATIONS

Exactly one configuration is exposed.

USB_CONFIG_VALUE

#define USB_CONFIG_VALUE

Its bConfigurationValue.

USB_CONFIG_ATTR_BUS_POWERED

#define USB_CONFIG_ATTR_BUS_POWERED

bmAttributes bit 7: reserved, always set

USB_CONFIG_MAX_POWER_100MA

#define USB_CONFIG_MAX_POWER_100MA

bMaxPower, counted in 2 mA units

USB_DT_DEVICE

#define USB_DT_DEVICE

Standard descriptor type codes (the bDescriptorType field, Sec.9.6).

Device descriptor

USB_DT_CONFIG

#define USB_DT_CONFIG

Configuration descriptor.

USB_DT_STRING

#define USB_DT_STRING

String descriptor.

USB_DT_INTERFACE

#define USB_DT_INTERFACE

Interface descriptor.

USB_DT_ENDPOINT

#define USB_DT_ENDPOINT

Endpoint descriptor.

USB_DT_INTERFACE_ASSOCIATION

#define USB_DT_INTERFACE_ASSOCIATION

IAD - groups interfaces into one function.

USB_CLASS_PER_INTERFACE

#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).

Subclass and protocol codes are specific to each class specification and live with that class's code. bDeviceClass 0: class defined per interface

USB_CLASS_AUDIO

#define USB_CLASS_AUDIO

Audio (UAC)

USB_CLASS_CDC

#define USB_CLASS_CDC

Communications and CDC Control.

USB_CLASS_HID

#define USB_CLASS_HID

Human Interface Device.

USB_CLASS_IMAGE

#define USB_CLASS_IMAGE

Still Imaging (PTP; MTP rides on it)

USB_CLASS_MSC

#define USB_CLASS_MSC

Mass Storage.

USB_CLASS_CDC_DATA

#define USB_CLASS_CDC_DATA

CDC Data.

USB_CLASS_VIDEO

#define USB_CLASS_VIDEO

Video (UVC)

USB_CLASS_WIRELESS

#define USB_CLASS_WIRELESS

Wireless Controller (Bluetooth radio)

USB_CLASS_MISC

#define USB_CLASS_MISC

Miscellaneous (see the IAD triple below)

USB_CLASS_APP_SPEC

#define USB_CLASS_APP_SPEC

Application Specific (DFU)

USB_CLASS_VENDOR_SPEC

#define USB_CLASS_VENDOR_SPEC

Vendor Specific.

USB_SUBCLASS_COMMON

#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).

Set by usbip_device_set_composite(); a class that is itself multi-interface (e.g. UVC) declares it too. bDeviceSubClass: Common Class (with USB_CLASS_MISC)

USB_PROTOCOL_IAD

#define USB_PROTOCOL_IAD

bDeviceProtocol: Interface Association Descriptor

USB_SETUP_BYTES

#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:

uint8_t setup[8] = { USB_SETUP_BYTES(0x80, USB_REQ_GET_DESCRIPTOR, 0x0100, 0, 18) };

Parameters

type	bmRequestType.
request	bRequest.
value	wValue, in host order.
index	wIndex, in host order.
length	wLength, in host order.

Enumeration Type Documentation

usb_dir

enum usb_dir

Transfer direction (matches bit 7 of an endpoint address / bmRequestType).

Enumerator
USB_OUT	Host → device.
USB_IN	Device → host.

usb_xfer_type

enum usb_xfer_type

Endpoint transfer type (the transfer-type field of bmAttributes).

Enumerator
USB_CONTROL	Control - setup/config/commands (endpoint 0)
USB_ISO	Isochronous - streaming media, timed, may drop data.
USB_BULK	Bulk - large data, reliable, no timing guarantee.
USB_INTR	Interrupt - small periodic data, bounded latency.

usb_req_type

enum usb_req_type

Control-request type - bits 6:5 of the SETUP packet's bmRequestType.

Enumerator
USB_STANDARD	A standard request defined by the USB spec.
USB_CLASS	A class-specific request (handled by a device class)
USB_VENDOR	A vendor-specific request.

usb_speed

enum usb_speed

Reported link speed (select with usbip_device_set_speed()).

Enumerator
USB_SPEED_LOW	Low speed, 1.5 Mbit/s.
USB_SPEED_FULL	Full speed, 12 Mbit/s (the default)
USB_SPEED_HIGH	High speed, 480 Mbit/s (512-byte bulk endpoints)
USB_SPEED_SUPER	Super speed, 5 Gbit/s.