USB device stack¶
USB Vendor and Product identifiers¶
The USB Vendor ID for the Zephyr project is 0x2FE3. The default USB Product ID for the Zephyr project is 0x100. The USB bcdDevice Device Release Number represents the Zephyr kernel major and minor versions as a binary coded decimal value. When a vendor integrates the Zephyr USB subsystem into a product, the vendor must use the USB Vendor and Product ID assigned to them. A vendor integrating the Zephyr USB subsystem in a product must not use the Vendor ID of the Zephyr project.
The USB maintainer, if one is assigned, or otherwise the Zephyr Technical Steering Committee, may allocate other USB Product IDs based on well-motivated and documented requests.
Each USB sample has its own unique Product ID.
When adding a new sample, add a new entry in samples/subsys/usb/usb_pid.Kconfig
and a Kconfig file inside your sample subdirectory.
The following Product IDs are currently used:
USB device controller drivers¶
The Device Controller Driver Layer implements the low level control routines to deal directly with the hardware. All device controller drivers should implement the APIs described in file usb_dc.h. This allows the integration of new USB device controllers to be done without changing the upper layers.
USB Device Controller API¶
-
group
_usb_device_controller_api
USB Device Controller API.
Typedefs
-
typedef void (*
usb_dc_ep_callback
)(uint8_t ep, enum usb_dc_ep_cb_status_code cb_status)¶ Callback function signature for the USB Endpoint status
-
typedef void (*
usb_dc_status_callback
)(enum usb_dc_status_code cb_status, const uint8_t *param)¶ Callback function signature for the device
Enums
-
enum
usb_dc_status_code
¶ USB Driver Status Codes.
Status codes reported by the registered device status callback.
Values:
-
enumerator
USB_DC_ERROR
¶ USB error reported by the controller
-
enumerator
USB_DC_RESET
¶ USB reset
-
enumerator
USB_DC_CONNECTED
¶ USB connection established, hardware enumeration is completed
-
enumerator
USB_DC_CONFIGURED
¶ USB configuration done
-
enumerator
USB_DC_DISCONNECTED
¶ USB connection lost
-
enumerator
USB_DC_SUSPEND
¶ USB connection suspended by the HOST
-
enumerator
USB_DC_RESUME
¶ USB connection resumed by the HOST
-
enumerator
USB_DC_INTERFACE
¶ USB interface selected
-
enumerator
USB_DC_SET_HALT
¶ Set Feature ENDPOINT_HALT received
-
enumerator
USB_DC_CLEAR_HALT
¶ Clear Feature ENDPOINT_HALT received
-
enumerator
USB_DC_SOF
¶ Start of Frame received
-
enumerator
USB_DC_UNKNOWN
¶ Initial USB connection status
-
enumerator
-
enum
usb_dc_ep_cb_status_code
¶ USB Endpoint Callback Status Codes.
Status Codes reported by the registered endpoint callback.
Values:
-
enumerator
USB_DC_EP_SETUP
¶ SETUP received
-
enumerator
USB_DC_EP_DATA_OUT
¶ Out transaction on this EP, data is available for read
-
enumerator
USB_DC_EP_DATA_IN
¶ In transaction done on this EP
-
enumerator
-
enum
usb_dc_ep_transfer_type
¶ USB Endpoint Transfer Type.
Values:
-
enumerator
USB_DC_EP_CONTROL
= 0¶ Control type endpoint
-
enumerator
USB_DC_EP_ISOCHRONOUS
¶ Isochronous type endpoint
-
enumerator
USB_DC_EP_BULK
¶ Bulk type endpoint
-
enumerator
USB_DC_EP_INTERRUPT
¶ Interrupt type endpoint
-
enumerator
-
enum
usb_dc_ep_synchronozation_type
¶ USB Endpoint Synchronization Type.
Note
Valid only for Isochronous Endpoints
Values:
-
enumerator
USB_DC_EP_NO_SYNCHRONIZATION
= (0U << 2U)¶ No Synchronization
-
enumerator
USB_DC_EP_ASYNCHRONOUS
= (1U << 2U)¶ Asynchronous
-
enumerator
USB_DC_EP_ADAPTIVE
= (2U << 2U)¶ Adaptive
-
enumerator
USB_DC_EP_SYNCHRONOUS
= (3U << 2U)¶ Synchronous
-
enumerator
Functions
-
int
usb_dc_attach
(void)¶ Attach USB for device connection.
Function to attach USB for device connection. Upon success, the USB PLL is enabled, and the USB device is now capable of transmitting and receiving on the USB bus and of generating interrupts.
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_detach
(void)¶ Detach the USB device.
Function to detach the USB device. Upon success, the USB hardware PLL is powered down and USB communication is disabled.
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_reset
(void)¶ Reset the USB device.
This function returns the USB device and firmware back to it’s initial state. N.B. the USB PLL is handled by the usb_detach function
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_set_address
(const uint8_t addr)¶ Set USB device address.
- Parameters
addr – [in] Device address
- Returns
0 on success, negative errno code on fail.
-
void
usb_dc_set_status_callback
(const usb_dc_status_callback cb)¶ Set USB device controller status callback.
Function to set USB device controller status callback. The registered callback is used to report changes in the status of the device controller. The status code are described by the usb_dc_status_code enumeration.
- Parameters
cb – [in] Callback function
-
int
usb_dc_ep_check_cap
(const struct usb_dc_ep_cfg_data *const cfg)¶ check endpoint capabilities
Function to check capabilities of an endpoint. usb_dc_ep_cfg_data structure provides the endpoint configuration parameters: endpoint address, endpoint maximum packet size and endpoint type. The driver should check endpoint capabilities and return 0 if the endpoint configuration is possible.
- Parameters
cfg – [in] Endpoint config
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_configure
(const struct usb_dc_ep_cfg_data *const cfg)¶ Configure endpoint.
Function to configure an endpoint. usb_dc_ep_cfg_data structure provides the endpoint configuration parameters: endpoint address, endpoint maximum packet size and endpoint type.
- Parameters
cfg – [in] Endpoint config
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_set_stall
(const uint8_t ep)¶ Set stall condition for the selected endpoint.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_clear_stall
(const uint8_t ep)¶ Clear stall condition for the selected endpoint.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_is_stalled
(const uint8_t ep, uint8_t *const stalled)¶ Check if the selected endpoint is stalled.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
stalled – [out] Endpoint stall status
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_halt
(const uint8_t ep)¶ Halt the selected endpoint.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_enable
(const uint8_t ep)¶ Enable the selected endpoint.
Function to enable the selected endpoint. Upon success interrupts are enabled for the corresponding endpoint and the endpoint is ready for transmitting/receiving data.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_disable
(const uint8_t ep)¶ Disable the selected endpoint.
Function to disable the selected endpoint. Upon success interrupts are disabled for the corresponding endpoint and the endpoint is no longer able for transmitting/receiving data.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_flush
(const uint8_t ep)¶ Flush the selected endpoint.
This function flushes the FIFOs for the selected endpoint.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_write
(const uint8_t ep, const uint8_t *const data, const uint32_t data_len, uint32_t *const ret_bytes)¶ Write data to the specified endpoint.
This function is called to write data to the specified endpoint. The supplied usb_ep_callback function will be called when data is transmitted out.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
data – [in] Pointer to data to write
data_len – [in] Length of the data requested to write. This may be zero for a zero length status packet.
ret_bytes – [out] Bytes scheduled for transmission. This value may be NULL if the application expects all bytes to be written
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_read
(const uint8_t ep, uint8_t *const data, const uint32_t max_data_len, uint32_t *const read_bytes)¶ Read data from the specified endpoint.
This function is called by the endpoint handler function, after an OUT interrupt has been received for that EP. The application must only call this function through the supplied usb_ep_callback function. This function clears the ENDPOINT NAK, if all data in the endpoint FIFO has been read, so as to accept more data from host.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
data – [in] Pointer to data buffer to write to
max_data_len – [in] Max length of data to read
read_bytes – [out] Number of bytes read. If data is NULL and max_data_len is 0 the number of bytes available for read should be returned.
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_set_callback
(const uint8_t ep, const usb_dc_ep_callback cb)¶ Set callback function for the specified endpoint.
Function to set callback function for notification of data received and available to application or transmit done on the selected endpoint, NULL if callback not required by application code. The callback status code is described by usb_dc_ep_cb_status_code.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
cb – [in] Callback function
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_read_wait
(uint8_t ep, uint8_t *data, uint32_t max_data_len, uint32_t *read_bytes)¶ Read data from the specified endpoint.
This is similar to usb_dc_ep_read, the difference being that, it doesn’t clear the endpoint NAKs so that the consumer is not bogged down by further upcalls till he is done with the processing of the data. The caller should reactivate ep by invoking usb_dc_ep_read_continue() do so.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
data – [in] Pointer to data buffer to write to
max_data_len – [in] Max length of data to read
read_bytes – [out] Number of bytes read. If data is NULL and max_data_len is 0 the number of bytes available for read should be returned.
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_read_continue
(uint8_t ep)¶ Continue reading data from the endpoint.
Clear the endpoint NAK and enable the endpoint to accept more data from the host. Usually called after usb_dc_ep_read_wait() when the consumer is fine to accept more data. Thus these calls together act as a flow control mechanism.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
0 on success, negative errno code on fail.
-
int
usb_dc_ep_mps
(uint8_t ep)¶ Get endpoint max packet size.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
Enpoint max packet size (mps)
-
int
usb_dc_wakeup_request
(void)¶ Start the host wake up procedure.
Function to wake up the host if it’s currently in sleep mode.
- Returns
0 on success, negative errno code on fail.
-
struct
usb_dc_ep_cfg_data
¶ - #include <usb_dc.h>
USB Endpoint Configuration.
Structure containing the USB endpoint configuration.
Public Members
-
uint8_t
ep_addr
¶ The number associated with the EP in the device configuration structure IN EP = 0x80 | <endpoint number> OUT EP = 0x00 | <endpoint number>
-
uint16_t
ep_mps
¶ Endpoint max packet size
-
enum usb_dc_ep_transfer_type
ep_type
¶ Endpoint Transfer Type. May be Bulk, Interrupt, Control or Isochronous
-
uint8_t
-
typedef void (*
USB device core layer¶
The USB Device core layer is a hardware independent interface between USB device controller driver and USB device class drivers or customer applications. It’s a port of the LPCUSB device stack. It provides the following functionalities:
Responds to standard device requests and returns standard descriptors, essentially handling ‘Chapter 9’ processing, specifically the standard device requests in table 9-3 from the universal serial bus specification revision 2.0.
Provides a programming interface to be used by USB device classes or customer applications. The APIs are described in the usb_device.h file.
Uses the APIs provided by the device controller drivers to interact with the USB device controller.
USB Device Core Layer API¶
There are two ways to transmit data, using the ‘low’ level read/write API or the ‘high’ level transfer API.
- Low level API
To transmit data to the host, the class driver should call usb_write(). Upon completion the registered endpoint callback will be called. Before sending another packet the class driver should wait for the completion of the previous write. When data is received, the registered endpoint callback is called. usb_read() should be used for retrieving the received data. For CDC ACM sample driver this happens via the OUT bulk endpoint handler (cdc_acm_bulk_out) mentioned in the endpoint array (cdc_acm_ep_data).
- High level API
The usb_transfer method can be used to transfer data to/from the host. The transfer API will automatically split the data transmission into one or more USB transaction(s), depending endpoint max packet size. The class driver does not have to implement endpoint callback and should set this callback to the generic usb_transfer_ep_callback.
-
group
_usb_device_core_api
USB Device Core Layer API.
Typedefs
-
typedef void (*
usb_ep_callback
)(uint8_t ep, enum usb_dc_ep_cb_status_code cb_status)¶ Callback function signature for the USB Endpoint status.
-
typedef int (*
usb_request_handler
)(struct usb_setup_packet *setup, int32_t *transfer_len, uint8_t **payload_data)¶ Callback function signature for class specific requests.
Function which handles Class specific requests corresponding to an interface number specified in the device descriptor table. For host to device direction the ‘len’ and ‘payload_data’ contain the length of the received data and the pointer to the received data respectively. For device to host class requests, ‘len’ and ‘payload_data’ should be set by the callback function with the length and the address of the data to be transmitted buffer respectively.
-
typedef void (*
usb_interface_config
)(struct usb_desc_header *head, uint8_t bInterfaceNumber)¶ Function for interface runtime configuration.
-
typedef void (*
usb_transfer_callback
)(uint8_t ep, int tsize, void *priv)¶ Callback function signature for transfer completion.
Functions
-
int
usb_set_config
(const uint8_t *usb_descriptor)¶ Configure USB controller.
Function to configure USB controller. Configuration parameters must be valid or an error is returned
- Parameters
usb_descriptor – [in] USB descriptor table
- Returns
0 on success, negative errno code on fail
-
int
usb_deconfig
(void)¶ Deconfigure USB controller.
This function returns the USB device to it’s initial state
- Returns
0 on success, negative errno code on fail
-
int
usb_enable
(usb_dc_status_callback status_cb)¶ Enable the USB subsystem and associated hardware.
This function initializes the USB core subsystem and enables the corresponding hardware so that it can begin transmitting and receiving on the USB bus, as well as generating interrupts.
Class-specific initialization and registration must be performed by the user before invoking this, so that any data or events on the bus are processed correctly by the associated class handling code.
- Parameters
status_cb – [in] Callback registered by user to notify about USB device controller state.
- Returns
0 on success, negative errno code on fail.
-
int
usb_disable
(void)¶ Disable the USB device.
Function to disable the USB device. Upon success, the specified USB interface is clock gated in hardware, it is no longer capable of generating interrupts.
- Returns
0 on success, negative errno code on fail
-
int
usb_write
(uint8_t ep, const uint8_t *data, uint32_t data_len, uint32_t *bytes_ret)¶ Write data to the specified endpoint.
Function to write data to the specified endpoint. The supplied usb_ep_callback will be called when transmission is done.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
data – [in] Pointer to data to write
data_len – [in] Length of data requested to write. This may be zero for a zero length status packet.
bytes_ret – [out] Bytes written to the EP FIFO. This value may be NULL if the application expects all bytes to be written
- Returns
0 on success, negative errno code on fail
-
int
usb_read
(uint8_t ep, uint8_t *data, uint32_t max_data_len, uint32_t *ret_bytes)¶ Read data from the specified endpoint.
This function is called by the Endpoint handler function, after an OUT interrupt has been received for that EP. The application must only call this function through the supplied usb_ep_callback function.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
data – [in] Pointer to data buffer to write to
max_data_len – [in] Max length of data to read
ret_bytes – [out] Number of bytes read. If data is NULL and max_data_len is 0 the number of bytes available for read is returned.
- Returns
0 on success, negative errno code on fail
-
int
usb_ep_set_stall
(uint8_t ep)¶ Set STALL condition on the specified endpoint.
This function is called by USB device class handler code to set stall condition on endpoint.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
0 on success, negative errno code on fail
-
int
usb_ep_clear_stall
(uint8_t ep)¶ Clears STALL condition on the specified endpoint.
This function is called by USB device class handler code to clear stall condition on endpoint.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
0 on success, negative errno code on fail
-
int
usb_ep_read_wait
(uint8_t ep, uint8_t *data, uint32_t max_data_len, uint32_t *read_bytes)¶ Read data from the specified endpoint.
This is similar to usb_ep_read, the difference being that, it doesn’t clear the endpoint NAKs so that the consumer is not bogged down by further upcalls till he is done with the processing of the data. The caller should reactivate ep by invoking usb_ep_read_continue() do so.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
data – [in] pointer to data buffer to write to
max_data_len – [in] max length of data to read
read_bytes – [out] Number of bytes read. If data is NULL and max_data_len is 0 the number of bytes available for read should be returned.
- Returns
0 on success, negative errno code on fail.
-
int
usb_ep_read_continue
(uint8_t ep)¶ Continue reading data from the endpoint.
Clear the endpoint NAK and enable the endpoint to accept more data from the host. Usually called after usb_ep_read_wait() when the consumer is fine to accept more data. Thus these calls together acts as flow control mechanism.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
0 on success, negative errno code on fail.
-
void
usb_transfer_ep_callback
(uint8_t ep, enum usb_dc_ep_cb_status_code)¶ Transfer management endpoint callback.
If a USB class driver wants to use high-level transfer functions, driver needs to register this callback as usb endpoint callback.
-
int
usb_transfer
(uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags, usb_transfer_callback cb, void *priv)¶ Start a transfer.
Start a usb transfer to/from the data buffer. This function is asynchronous and can be executed in IRQ context. The provided callback will be called on transfer completion (or error) in thread context.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
data – [in] Pointer to data buffer to write-to/read-from
dlen – [in] Size of data buffer
flags – [in] Transfer flags (USB_TRANS_READ, USB_TRANS_WRITE…)
cb – [in] Function called on transfer completion/failure
priv – [in] Data passed back to the transfer completion callback
- Returns
0 on success, negative errno code on fail.
-
int
usb_transfer_sync
(uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags)¶ Start a transfer and block-wait for completion.
Synchronous version of usb_transfer, wait for transfer completion before returning.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
data – [in] Pointer to data buffer to write-to/read-from
dlen – [in] Size of data buffer
flags – [in] Transfer flags
- Returns
number of bytes transferred on success, negative errno code on fail.
-
void
usb_cancel_transfer
(uint8_t ep)¶ Cancel any ongoing transfer on the specified endpoint.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
0 on success, negative errno code on fail.
-
void
usb_cancel_transfers
(void)¶ Cancel all ongoing transfers.
-
bool
usb_transfer_is_busy
(uint8_t ep)¶ Check that transfer is ongoing for the endpoint.
- Parameters
ep – [in] Endpoint address corresponding to the one listed in the device configuration table
- Returns
true if transfer is ongoing, false otherwise.
-
int
usb_wakeup_request
(void)¶ Start the USB remote wakeup procedure.
Function to request a remote wakeup. This feature must be enabled in configuration, otherwise it will always return -ENOTSUP error.
- Returns
0 on success, negative errno code on fail, i.e. when the bus is already active.
-
struct
usb_ep_cfg_data
¶ - #include <usb_device.h>
USB Endpoint Configuration.
This structure contains configuration for the endpoint.
Public Members
-
usb_ep_callback
ep_cb
¶ Callback function for notification of data received and available to application or transmit done, NULL if callback not required by application code
-
uint8_t
ep_addr
¶ The number associated with the EP in the device configuration structure IN EP = 0x80 | <endpoint number> OUT EP = 0x00 | <endpoint number>
-
usb_ep_callback
-
struct
usb_interface_cfg_data
¶ - #include <usb_device.h>
USB Interface Configuration.
This structure contains USB interface configuration.
Public Members
-
usb_request_handler
class_handler
¶ Handler for USB Class specific Control (EP 0) communications
-
usb_request_handler
vendor_handler
¶ Handler for USB Vendor specific commands
-
usb_request_handler
custom_handler
¶ The custom request handler gets a first chance at handling the request before it is handed over to the ‘chapter 9’ request handler. return 0 on success, -EINVAL if the request has not been handled by the custom handler and instead needs to be handled by the core USB stack. Any other error code to denote failure within the custom handler.
-
usb_request_handler
-
struct
usb_cfg_data
¶ - #include <usb_device.h>
USB device configuration.
The Application instantiates this with given parameters added using the “usb_set_config” function. Once this function is called changes to this structure will result in undefined behavior. This structure may only be updated after calls to usb_deconfig
Public Members
-
const uint8_t *
usb_device_description
¶ USB device description, see http://www.beyondlogic.org/usbnutshell/usb5.shtml#DeviceDescriptors
-
void *
interface_descriptor
¶ Pointer to interface descriptor
-
usb_interface_config
interface_config
¶ Function for interface runtime configuration
-
void (*
cb_usb_status
)(struct usb_cfg_data *cfg, enum usb_dc_status_code cb_status, const uint8_t *param)¶ Callback to be notified on USB connection status change
-
struct usb_interface_cfg_data
interface
¶ USB interface (Class) handler and storage space
-
uint8_t
num_endpoints
¶ Number of individual endpoints in the device configuration
-
struct usb_ep_cfg_data *
endpoint
¶ Pointer to an array of endpoint structs of length equal to the number of EP associated with the device description, not including control endpoints
-
const uint8_t *
-
typedef void (*
USB device class drivers¶
Zephyr USB Device Stack supports many standard classes, such as HID, MSC Ethernet over USB, DFU, Bluetooth.
Implementing non standard USB class¶
Configuration of USB Device is done in the stack layer.
The following structures and callbacks need to be defined:
Part of USB Descriptor table
USB Endpoint configuration table
USB Device configuration structure
Endpoint callbacks
Optionally class, vendor and custom handlers
For example, for USB loopback application:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | struct usb_loopback_config {
struct usb_if_descriptor if0;
struct usb_ep_descriptor if0_out_ep;
struct usb_ep_descriptor if0_in_ep;
} __packed;
USBD_CLASS_DESCR_DEFINE(primary, 0) struct usb_loopback_config loopback_cfg = {
/* Interface descriptor 0 */
.if0 = {
.bLength = sizeof(struct usb_if_descriptor),
.bDescriptorType = USB_INTERFACE_DESC,
.bInterfaceNumber = 0,
.bAlternateSetting = 0,
.bNumEndpoints = 2,
.bInterfaceClass = CUSTOM_CLASS,
.bInterfaceSubClass = 0,
.bInterfaceProtocol = 0,
.iInterface = 0,
},
/* Data Endpoint OUT */
.if0_out_ep = {
.bLength = sizeof(struct usb_ep_descriptor),
.bDescriptorType = USB_ENDPOINT_DESC,
.bEndpointAddress = LOOPBACK_OUT_EP_ADDR,
.bmAttributes = USB_DC_EP_BULK,
.wMaxPacketSize = sys_cpu_to_le16(CONFIG_LOOPBACK_BULK_EP_MPS),
.bInterval = 0x00,
},
/* Data Endpoint IN */
.if0_in_ep = {
.bLength = sizeof(struct usb_ep_descriptor),
.bDescriptorType = USB_ENDPOINT_DESC,
.bEndpointAddress = LOOPBACK_IN_EP_ADDR,
.bmAttributes = USB_DC_EP_BULK,
.wMaxPacketSize = sys_cpu_to_le16(CONFIG_LOOPBACK_BULK_EP_MPS),
.bInterval = 0x00,
},
};
|
Endpoint configuration:
1 2 3 4 5 6 7 8 9 10 | static struct usb_ep_cfg_data ep_cfg[] = {
{
.ep_cb = loopback_out_cb,
.ep_addr = LOOPBACK_OUT_EP_ADDR,
},
{
.ep_cb = loopback_in_cb,
.ep_addr = LOOPBACK_IN_EP_ADDR,
},
};
|
USB Device configuration structure:
1 2 3 4 5 6 7 8 9 10 11 12 13 | USBD_CFG_DATA_DEFINE(primary, loopback) struct usb_cfg_data loopback_config = {
.usb_device_description = NULL,
.interface_config = loopback_interface_config,
.interface_descriptor = &loopback_cfg.if0,
.cb_usb_status = loopback_status_cb,
.interface = {
.class_handler = NULL,
.custom_handler = NULL,
.vendor_handler = loopback_vendor_handler,
},
.num_endpoints = ARRAY_SIZE(ep_cfg),
.endpoint = ep_cfg,
};
|
The vendor device requests are forwarded by the USB stack core driver to the class driver through the registered vendor handler.
For the loopback class driver, loopback_vendor_handler()
processes
the vendor requests:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | static int loopback_vendor_handler(struct usb_setup_packet *setup,
int32_t *len, uint8_t **data)
{
LOG_DBG("Class request: bRequest 0x%x bmRequestType 0x%x len %d",
setup->bRequest, setup->bmRequestType, *len);
if (REQTYPE_GET_RECIP(setup->bmRequestType) != REQTYPE_RECIP_DEVICE) {
return -ENOTSUP;
}
if (REQTYPE_GET_DIR(setup->bmRequestType) == REQTYPE_DIR_TO_DEVICE &&
setup->bRequest == 0x5b) {
LOG_DBG("Host-to-Device, data %p", *data);
return 0;
}
if ((REQTYPE_GET_DIR(setup->bmRequestType) == REQTYPE_DIR_TO_HOST) &&
(setup->bRequest == 0x5c)) {
LOG_DBG("Device-to-Host, wLength %d, data %p",
setup->wLength, *data);
return 0;
}
return -ENOTSUP;
}
|
The class driver waits for the USB_DC_CONFIGURED device status code before transmitting any data.
Testing USB over USP/IP in native_posix¶
Virtual USB controller implemented through USB/IP might be used to test USB Device stack. Follow general build procedure to build USB sample for the native_posix configuration.
Run built sample with:
west build -t run
In a terminal window, run the following command to list USB devices:
$ usbip list -r localhost
Exportable USB devices
======================
- 127.0.0.1
1-1: unknown vendor : unknown product (2fe3:0100)
: /sys/devices/pci0000:00/0000:00:01.2/usb1/1-1
: (Defined at Interface level) (00/00/00)
: 0 - Vendor Specific Class / unknown subclass / unknown protocol (ff/00/00)
In a terminal window, run the following command to attach USB device:
$ sudo usbip attach -r localhost -b 1-1
The USB device should be connected to your Linux host, and verified with the following commands:
$ sudo usbip port
Imported USB devices
====================
Port 00: <Port in Use> at Full Speed(12Mbps)
unknown vendor : unknown product (2fe3:0100)
7-1 -> usbip://localhost:3240/1-1
-> remote bus/dev 001/002
$ lsusb -d 2fe3:0100
Bus 007 Device 004: ID 2fe3:0100
USB Human Interface Devices (HID) support¶
HID Item helpers¶
HID item helper macros can be used to compose a HID Report Descriptor. The names correspond to those used in the USB HID Specification.
Example of a HID Report Descriptor:
static const uint8_t hid_report_desc[] = {
HID_USAGE_PAGE(HID_USAGE_GEN_DESKTOP),
HID_USAGE(HID_USAGE_GEN_DESKTOP_UNDEFINED),
HID_COLLECTION(HID_COLLECTION_APPLICATION),
HID_LOGICAL_MIN8(0),
/* logical maximum 255 */
HID_LOGICAL_MAX16(0xFF, 0x00),
HID_REPORT_ID(1),
HID_REPORT_SIZE(8),
HID_REPORT_COUNT(1),
HID_USAGE(HID_USAGE_GEN_DESKTOP_UNDEFINED),
/* HID_INPUT (Data, Variable, Absolute) */
HID_INPUT(0x02),
HID_END_COLLECTION,
};
-
group
usb_hid_items
Defines
-
HID_ITEM
(bTag, bType, bSize)¶ Define HID short item.
- Parameters
bTag – Item tag
bType – Item type
bSize – Item data size
- Returns
HID Input item
-
HID_INPUT
(a)¶ Define HID Input item with the data length of one byte.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Parameters
a – Input item data
- Returns
HID Input item
-
HID_OUTPUT
(a)¶ Define HID Output item with the data length of one byte.
For usage examples, see HID_KEYBOARD_REPORT_DESC()
- Parameters
a – Output item data
- Returns
HID Output item
-
HID_FEATURE
(a)¶ Define HID Feature item with the data length of one byte.
- Parameters
a – Feature item data
- Returns
HID Feature item
-
HID_COLLECTION
(a)¶ Define HID Collection item with the data length of one byte.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Parameters
a – Collection item data
- Returns
HID Collection item
-
HID_END_COLLECTION
¶ Define HID End Collection (non-data) item.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Returns
HID End Collection item
-
HID_USAGE_PAGE
(page)¶ Define HID Usage Page item.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Parameters
page – Usage Page
- Returns
HID Usage Page item
-
HID_LOGICAL_MIN8
(a)¶ Define HID Logical Minimum item with the data length of one byte.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Parameters
a – Minimum value in logical units
- Returns
HID Logical Minimum item
-
HID_LOGICAL_MAX8
(a)¶ Define HID Logical Maximum item with the data length of one byte.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Parameters
a – Maximum value in logical units
- Returns
HID Logical Maximum item
-
HID_LOGICAL_MIN16
(a, b)¶ Define HID Logical Minimum item with the data length of two bytes.
- Parameters
a – Minimum value lower byte
b – Minimum value higher byte
- Returns
HID Logical Minimum item
-
HID_LOGICAL_MAX16
(a, b)¶ Define HID Logical Maximum item with the data length of two bytes.
- Parameters
a – Minimum value lower byte
b – Minimum value higher byte
- Returns
HID Logical Maximum item
-
HID_LOGICAL_MIN32
(a, b, c, d)¶ Define HID Logical Minimum item with the data length of four bytes.
- Parameters
a – Minimum value lower byte
b – Minimum value low middle byte
c – Minimum value high middle byte
d – Minimum value higher byte
- Returns
HID Logical Minimum item
-
HID_LOGICAL_MAX32
(a, b, c, d)¶ Define HID Logical Maximum item with the data length of four bytes.
- Parameters
a – Minimum value lower byte
b – Minimum value low middle byte
c – Minimum value high middle byte
d – Minimum value higher byte
- Returns
HID Logical Maximum item
-
HID_REPORT_SIZE
(size)¶ Define HID Report Size item with the data length of one byte.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Parameters
size – Report field size in bits
- Returns
HID Report Size item
-
HID_REPORT_ID
(id)¶ Define HID Report ID item with the data length of one byte.
- Parameters
id – Report ID
- Returns
HID Report ID item
-
HID_REPORT_COUNT
(count)¶ Define HID Report Count item with the data length of one byte.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Parameters
count – Number of data fields included in the report
- Returns
HID Report Count item
-
HID_USAGE
(idx)¶ Define HID Usage Index item with the data length of one byte.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Parameters
idx – Number of data fields included in the report
- Returns
HID Usage Index item
-
HID_USAGE_MIN8
(a)¶ Define HID Usage Minimum item with the data length of one byte.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Parameters
a – Starting Usage
- Returns
HID Usage Minimum item
-
HID_USAGE_MAX8
(a)¶ Define HID Usage Maximum item with the data length of one byte.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Parameters
a – Ending Usage
- Returns
HID Usage Maximum item
-
HID_USAGE_MIN16
(a, b)¶ Define HID Usage Minimum item with the data length of two bytes.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Parameters
a – Starting Usage lower byte
b – Starting Usage higher byte
- Returns
HID Usage Minimum item
-
HID_USAGE_MAX16
(a, b)¶ Define HID Usage Maximum item with the data length of two bytes.
For usage examples, see HID_MOUSE_REPORT_DESC(), HID_KEYBOARD_REPORT_DESC()
- Parameters
a – Ending Usage lower byte
b – Ending Usage higher byte
- Returns
HID Usage Maximum item
-
-
group
usb_hid_types
Defines
-
USB_DESC_HID
¶ USB HID Class HID descriptor type
-
USB_DESC_HID_REPORT
¶ USB HID Class Report descriptor type
-
USB_DESC_HID_PHYSICAL
¶ USB HID Class physical descriptor type
-
USB_HID_GET_REPORT
¶ USB HID Class GetReport bRequest value
-
USB_HID_GET_IDLE
¶ USB HID Class GetIdle bRequest value
-
USB_HID_GET_PROTOCOL
¶ USB HID Class GetProtocol bRequest value
-
USB_HID_SET_REPORT
¶ USB HID Class SetReport bRequest value
-
USB_HID_SET_IDLE
¶ USB HID Class SetIdle bRequest value
-
USB_HID_SET_PROTOCOL
¶ USB HID Class SetProtocol bRequest value
-
HID_BOOT_IFACE_CODE_NONE
¶ USB HID Boot Interface Protocol (bInterfaceProtocol) Code None
-
HID_BOOT_IFACE_CODE_KEYBOARD
¶ USB HID Boot Interface Protocol (bInterfaceProtocol) Code Keyboard
-
HID_BOOT_IFACE_CODE_MOUSE
¶ USB HID Boot Interface Protocol (bInterfaceProtocol) Code Mouse
-
HID_PROTOCOL_BOOT
¶ USB HID Class Boot protocol code
-
HID_PROTOCOL_REPORT
¶ USB HID Class Report protocol code
-
HID_ITEM_TYPE_MAIN
¶ HID Main item type
-
HID_ITEM_TYPE_GLOBAL
¶ HID Global item type
-
HID_ITEM_TYPE_LOCAL
¶ HID Local item type
-
HID_ITEM_TAG_INPUT
¶ HID Input item tag
-
HID_ITEM_TAG_OUTPUT
¶ HID Output item tag
-
HID_ITEM_TAG_COLLECTION
¶ HID Collection item tag
-
HID_ITEM_TAG_FEATURE
¶ HID Feature item tag
-
HID_ITEM_TAG_COLLECTION_END
¶ HID End Collection item tag
-
HID_ITEM_TAG_USAGE_PAGE
¶ HID Usage Page item tag
-
HID_ITEM_TAG_LOGICAL_MIN
¶ HID Logical Minimum item tag
-
HID_ITEM_TAG_LOGICAL_MAX
¶ HID Logical Maximum item tag
-
HID_ITEM_TAG_PHYSICAL_MIN
¶ HID Physical Minimum item tag
-
HID_ITEM_TAG_PHYSICAL_MAX
¶ HID Physical Maximum item tag
-
HID_ITEM_TAG_UNIT_EXPONENT
¶ HID Unit Exponent item tag
-
HID_ITEM_TAG_UNIT
¶ HID Unit item tag
-
HID_ITEM_TAG_REPORT_SIZE
¶ HID Report Size item tag
-
HID_ITEM_TAG_REPORT_ID
¶ HID Report ID item tag
-
HID_ITEM_TAG_REPORT_COUNT
¶ HID Report count item tag
-
HID_ITEM_TAG_USAGE
¶ HID Usage item tag
-
HID_ITEM_TAG_USAGE_MIN
¶ HID Usage Minimum item tag
-
HID_ITEM_TAG_USAGE_MAX
¶ HID Usage Maximum item tag
-
HID_COLLECTION_PHYSICAL
¶ Physical collection type
-
HID_COLLECTION_APPLICATION
¶ Application collection type
-
HID_USAGE_GEN_DESKTOP
¶ HID Generic Desktop Controls Usage page
-
HID_USAGE_GEN_KEYBOARD
¶ HID Keyboard Usage page
-
HID_USAGE_GEN_LEDS
¶ HID LEDs Usage page
-
HID_USAGE_GEN_BUTTON
¶ HID Button Usage page
-
HID_USAGE_GEN_DESKTOP_UNDEFINED
¶ HID Generic Desktop Undefined Usage ID
-
HID_USAGE_GEN_DESKTOP_POINTER
¶ HID Generic Desktop Pointer Usage ID
-
HID_USAGE_GEN_DESKTOP_MOUSE
¶ HID Generic Desktop Mouse Usage ID
-
HID_USAGE_GEN_DESKTOP_JOYSTICK
¶ HID Generic Desktop Joystick Usage ID
-
HID_USAGE_GEN_DESKTOP_GAMEPAD
¶ HID Generic Desktop Gamepad Usage ID
-
HID_USAGE_GEN_DESKTOP_KEYBOARD
¶ HID Generic Desktop Keyboard Usage ID
-
HID_USAGE_GEN_DESKTOP_KEYPAD
¶ HID Generic Desktop Keypad Usage ID
-
HID_USAGE_GEN_DESKTOP_X
¶ HID Generic Desktop X Usage ID
-
HID_USAGE_GEN_DESKTOP_Y
¶ HID Generic Desktop Y Usage ID
-
HID_USAGE_GEN_DESKTOP_WHEEL
¶ HID Generic Desktop Wheel Usage ID
-
HID Mouse and Keyboard report descriptors¶
The pre-defined Mouse and Keyboard report descriptors can be used by a HID device implementation or simply as examples.
-
group
usb_hid_mk_report_desc
Defines
-
HID_MOUSE_REPORT_DESC
(bcnt)¶ Simple HID mouse report descriptor for n button mouse.
- Parameters
bcnt – Button count. Allowed values from 1 to 8.
-
HID_KEYBOARD_REPORT_DESC
()¶ Simple HID keyboard report descriptor.
Enums
-
enum
hid_kbd_code
¶ HID keyboard button codes.
Values:
-
enumerator
HID_KEY_A
= 4¶
-
enumerator
HID_KEY_B
= 5¶
-
enumerator
HID_KEY_C
= 6¶
-
enumerator
HID_KEY_D
= 7¶
-
enumerator
HID_KEY_E
= 8¶
-
enumerator
HID_KEY_F
= 9¶
-
enumerator
HID_KEY_G
= 10¶
-
enumerator
HID_KEY_H
= 11¶
-
enumerator
HID_KEY_I
= 12¶
-
enumerator
HID_KEY_J
= 13¶
-
enumerator
HID_KEY_K
= 14¶
-
enumerator
HID_KEY_L
= 15¶
-
enumerator
HID_KEY_M
= 16¶
-
enumerator
HID_KEY_N
= 17¶
-
enumerator
HID_KEY_O
= 18¶
-
enumerator
HID_KEY_P
= 19¶
-
enumerator
HID_KEY_Q
= 20¶
-
enumerator
HID_KEY_R
= 21¶
-
enumerator
HID_KEY_S
= 22¶
-
enumerator
HID_KEY_T
= 23¶
-
enumerator
HID_KEY_U
= 24¶
-
enumerator
HID_KEY_V
= 25¶
-
enumerator
HID_KEY_W
= 26¶
-
enumerator
HID_KEY_X
= 27¶
-
enumerator
HID_KEY_Y
= 28¶
-
enumerator
HID_KEY_Z
= 29¶
-
enumerator
HID_KEY_1
= 30¶
-
enumerator
HID_KEY_2
= 31¶
-
enumerator
HID_KEY_3
= 32¶
-
enumerator
HID_KEY_4
= 33¶
-
enumerator
HID_KEY_5
= 34¶
-
enumerator
HID_KEY_6
= 35¶
-
enumerator
HID_KEY_7
= 36¶
-
enumerator
HID_KEY_8
= 37¶
-
enumerator
HID_KEY_9
= 38¶
-
enumerator
HID_KEY_0
= 39¶
-
enumerator
HID_KEY_ENTER
= 40¶
-
enumerator
HID_KEY_ESC
= 41¶
-
enumerator
HID_KEY_BACKSPACE
= 42¶
-
enumerator
HID_KEY_TAB
= 43¶
-
enumerator
HID_KEY_SPACE
= 44¶
-
enumerator
HID_KEY_MINUS
= 45¶
-
enumerator
HID_KEY_EQUAL
= 46¶
-
enumerator
HID_KEY_LEFTBRACE
= 47¶
-
enumerator
HID_KEY_RIGHTBRACE
= 48¶
-
enumerator
HID_KEY_BACKSLASH
= 49¶
-
enumerator
HID_KEY_HASH
= 50¶
-
enumerator
HID_KEY_SEMICOLON
= 51¶
-
enumerator
HID_KEY_APOSTROPHE
= 52¶
-
enumerator
HID_KEY_GRAVE
= 53¶
-
enumerator
HID_KEY_COMMA
= 54¶
-
enumerator
HID_KEY_DOT
= 55¶
-
enumerator
HID_KEY_SLASH
= 56¶
-
enumerator
HID_KEY_CAPSLOCK
= 57¶
-
enumerator
HID_KEY_F1
= 58¶
-
enumerator
HID_KEY_F2
= 59¶
-
enumerator
HID_KEY_F3
= 60¶
-
enumerator
HID_KEY_F4
= 61¶
-
enumerator
HID_KEY_F5
= 62¶
-
enumerator
HID_KEY_F6
= 63¶
-
enumerator
HID_KEY_F7
= 64¶
-
enumerator
HID_KEY_F8
= 65¶
-
enumerator
HID_KEY_F9
= 66¶
-
enumerator
HID_KEY_F10
= 67¶
-
enumerator
HID_KEY_F11
= 68¶
-
enumerator
HID_KEY_F12
= 69¶
-
enumerator
HID_KEY_SYSRQ
= 70¶
-
enumerator
HID_KEY_SCROLLLOCK
= 71¶
-
enumerator
HID_KEY_PAUSE
= 72¶
-
enumerator
HID_KEY_INSERT
= 73¶
-
enumerator
HID_KEY_HOME
= 74¶
-
enumerator
HID_KEY_PAGEUP
= 75¶
-
enumerator
HID_KEY_DELETE
= 76¶
-
enumerator
HID_KEY_END
= 77¶
-
enumerator
HID_KEY_PAGEDOWN
= 78¶
-
enumerator
HID_KEY_RIGHT
= 79¶
-
enumerator
HID_KEY_LEFT
= 80¶
-
enumerator
HID_KEY_DOWN
= 81¶
-
enumerator
HID_KEY_UP
= 82¶
-
enumerator
HID_KEY_NUMLOCK
= 83¶
-
enumerator
HID_KEY_KPSLASH
= 84¶
-
enumerator
HID_KEY_KPASTERISK
= 85¶
-
enumerator
HID_KEY_KPMINUS
= 86¶
-
enumerator
HID_KEY_KPPLUS
= 87¶
-
enumerator
HID_KEY_KPENTER
= 88¶
-
enumerator
HID_KEY_KP_1
= 89¶
-
enumerator
HID_KEY_KP_2
= 90¶
-
enumerator
HID_KEY_KP_3
= 91¶
-
enumerator
HID_KEY_KP_4
= 92¶
-
enumerator
HID_KEY_KP_5
= 93¶
-
enumerator
HID_KEY_KP_6
= 94¶
-
enumerator
HID_KEY_KP_7
= 95¶
-
enumerator
HID_KEY_KP_8
= 96¶
-
enumerator
HID_KEY_KP_9
= 97¶
-
enumerator
HID_KEY_KP_0
= 98¶
-
enumerator
-
enum
hid_kbd_modifier
¶ HID keyboard modifiers.
Values:
-
enumerator
HID_KBD_MODIFIER_NONE
= 0x00¶
-
enumerator
HID_KBD_MODIFIER_LEFT_CTRL
= 0x01¶
-
enumerator
HID_KBD_MODIFIER_LEFT_SHIFT
= 0x02¶
-
enumerator
HID_KBD_MODIFIER_LEFT_ALT
= 0x04¶
-
enumerator
HID_KBD_MODIFIER_LEFT_UI
= 0x08¶
-
enumerator
HID_KBD_MODIFIER_RIGHT_CTRL
= 0x10¶
-
enumerator
HID_KBD_MODIFIER_RIGHT_SHIFT
= 0x20¶
-
enumerator
HID_KBD_MODIFIER_RIGHT_ALT
= 0x40¶
-
enumerator
HID_KBD_MODIFIER_RIGHT_UI
= 0x80¶
-
enumerator
-
HID Class Device API¶
USB HID devices like mouse, keyboard, or any other specific device use this API.
-
group
usb_hid_device_api
Typedefs
Functions
-
void
usb_hid_register_device
(const struct device *dev, const uint8_t *desc, size_t size, const struct hid_ops *op)¶ Register HID device.
- Parameters
dev – [in] Pointer to USB HID device
desc – [in] Pointer to HID report descriptor
size – [in] Size of HID report descriptor
op – [in] Pointer to USB HID device interrupt struct
-
int
hid_int_ep_write
(const struct device *dev, const uint8_t *data, uint32_t data_len, uint32_t *bytes_ret)¶ Write to USB HID interrupt endpoint buffer.
- Parameters
dev – [in] Pointer to USB HID device
data – [in] Pointer to data buffer
data_len – [in] Length of data to copy
bytes_ret – [out] Bytes written to the EP buffer.
- Returns
0 on success, negative errno code on fail.
-
int
hid_int_ep_read
(const struct device *dev, uint8_t *data, uint32_t max_data_len, uint32_t *ret_bytes)¶ Read from USB HID interrupt endpoint buffer.
- Parameters
dev – [in] Pointer to USB HID device
data – [in] Pointer to data buffer
max_data_len – [in] Max length of data to copy
ret_bytes – [out] Number of bytes to copy. If data is NULL and ret_bytes is 0 the number of bytes available in the buffer will be returned.
- Returns
0 on success, negative errno code on fail.
-
int
usb_hid_set_proto_code
(const struct device *dev, uint8_t proto_code)¶ Set USB HID class Protocol Code.
Should be called before usb_hid_init().
- Parameters
dev – [in] Pointer to USB HID device
proto_code – [in] Protocol Code to be used for bInterfaceProtocol
- Returns
0 on success, negative errno code on fail.
-
struct
hid_ops
¶ - #include <usb_hid.h>
USB HID device interface.
-
void