USB host controller (UHC) driver API

The USB host controller driver API is described in include/zephyr/drivers/usb/uhc.h and referred to as the UHC driver API.

UHC driver API is experimental and is subject to change without notice.

Driver API reference

group uhc_api

USB host controller (UHC) driver API.

Defines

UHC_STATUS_INITIALIZED: Controller is initialized by uhc_init()

UHC_STATUS_ENABLED: Controller is enabled and all API functions are available.

Typedefs

typedef int (*uhc_event_cb_t)(const struct device *dev, const struct uhc_event *const event)

Callback to submit UHC event to higher layer.

At the higher level, the event is to be inserted into a message queue.

Param dev:: [in] Pointer to device struct of the driver instance
Param event:: [in] Point to event structure
Return:: 0 on success, all other values should be treated as error.

Enums

enum uhc_control_stage

USB control transfer stage.

Values:

enumerator UHC_CONTROL_STAGE_SETUP = 0

enumerator UHC_CONTROL_STAGE_DATA

enumerator UHC_CONTROL_STAGE_STATUS

enum uhc_event_type

USB host controller event types.

Values:

enumerator UHC_EVT_DEV_CONNECTED_LS: Low speed device connected.

enumerator UHC_EVT_DEV_CONNECTED_FS: Full speed device connected.

enumerator UHC_EVT_DEV_CONNECTED_HS: High speed device connected.

enumerator UHC_EVT_DEV_REMOVED: Device (peripheral) removed.

enumerator UHC_EVT_RESETED: Bus reset operation finished.

enumerator UHC_EVT_SUSPENDED: Bus suspend operation finished.

enumerator UHC_EVT_RESUMED: Bus resume operation finished.

enumerator UHC_EVT_RWUP: Remote wakeup signal.

enumerator UHC_EVT_EP_REQUEST: Endpoint request result event.

enumerator UHC_EVT_ERROR: Non-correctable error event, requires attention from higher levels or application.

Functions

static inline bool uhc_is_initialized(const struct device *dev)

Checks whether the controller is initialized.

Parameters:

dev – [in] Pointer to device struct of the driver instance

Returns:

true if controller is initialized, false otherwise

static inline bool uhc_is_enabled(const struct device *dev)

Checks whether the controller is enabled.

Parameters:

dev – [in] Pointer to device struct of the driver instance

Returns:

true if controller is enabled, false otherwise

static inline int uhc_bus_reset(const struct device *dev)

Reset USB bus.

Perform USB bus reset, controller may emit UHC_EVT_RESETED at the end of reset signaling.

Parameters:

dev – [in] Pointer to device struct of the driver instance

Return values:

-EBUSY – if the controller is already performing a bus operation

Returns:

0 on success, all other values should be treated as error.

static inline int uhc_sof_enable(const struct device *dev)

Enable Start of Frame generator.

Enable SOF generator.

Parameters:

dev – [in] Pointer to device struct of the driver instance

Return values:

-EALREADY – if already enabled

Returns:

0 on success, all other values should be treated as error.

static inline int uhc_bus_suspend(const struct device *dev)

Suspend USB bus.

Disable SOF generator and emit UHC_EVT_SUSPENDED event when USB bus is suspended.

Parameters:

dev – [in] Pointer to device struct of the driver instance

Return values:

-EALREADY – if already suspended

Returns:

0 on success, all other values should be treated as error.

static inline int uhc_bus_resume(const struct device *dev)

Resume USB bus.

Signal resume for at least 20ms, emit UHC_EVT_RESUMED at the end of USB bus resume signaling. The SoF generator should subsequently start within 3ms.

Parameters:

dev – [in] Pointer to device struct of the driver instance

Return values:

-EBUSY – if the controller is already performing a bus operation

Returns:

0 on success, all other values should be treated as error.

struct uhc_transfer *uhc_xfer_alloc(const struct device *dev, const uint8_t addr, const uint8_t ep, const uint8_t attrib, const uint16_t mps, const uint16_t timeout, void *const udev, void *const cb)

Allocate UHC transfer.

Allocate a new transfer from common transfer pool. Transfer has no buffer after allocation, but can be allocated and added from different pools.

Parameters:

dev – [in] Pointer to device struct of the driver instance
addr – [in] Device (peripheral) address
ep – [in] Endpoint address
attrib – [in] Endpoint attributes
mps – [in] Maximum packet size of the endpoint
timeout – [in] Timeout in number of frames
udev – [in] Opaque pointer to USB device
cb – [in] Transfer completion callback

Returns:

pointer to allocated transfer or NULL on error.

struct uhc_transfer *uhc_xfer_alloc_with_buf(const struct device *dev, const uint8_t addr, const uint8_t ep, const uint8_t attrib, const uint16_t mps, const uint16_t timeout, void *const udev, void *const cb, size_t size)

Allocate UHC transfer with buffer.

Allocate a new transfer from common transfer pool with buffer.

Parameters:

dev – [in] Pointer to device struct of the driver instance
addr – [in] Device (peripheral) address
ep – [in] Endpoint address
attrib – [in] Endpoint attributes
mps – [in] Maximum packet size of the endpoint
timeout – [in] Timeout in number of frames
udev – [in] Opaque pointer to USB device
cb – [in] Transfer completion callback
size – [in] Size of the buffer

Returns:

pointer to allocated transfer or NULL on error.

int uhc_xfer_free(const struct device *dev, struct uhc_transfer *const xfer)

Free UHC transfer and any buffers.

Free any buffers and put the transfer back into the transfer pool.

Parameters:

dev – [in] Pointer to device struct of the driver instance
xfer – [in] Pointer to UHC transfer

Returns:

0 on success, all other values should be treated as error.

int uhc_xfer_buf_add(const struct device *dev, struct uhc_transfer *const xfer, struct net_buf *buf)

Add UHC transfer buffer.

Add a previously allocated buffer to the transfer.

Parameters:

dev – [in] Pointer to device struct of the driver instance
xfer – [in] Pointer to UHC transfer
buf – [in] Pointer to UHC request buffer

Returns:

pointer to allocated request or NULL on error.

struct net_buf *uhc_xfer_buf_alloc(const struct device *dev, const size_t size)

Allocate UHC transfer buffer.

Allocate a new buffer from common request buffer pool and assign it to the transfer if the xfer parameter is not NULL.

Parameters:

dev – [in] Pointer to device struct of the driver instance
size – [in] Size of the request buffer

Returns:

pointer to allocated request or NULL on error.

void uhc_xfer_buf_free(const struct device *dev, struct net_buf *const buf)

Free UHC request buffer.

Put the buffer back into the request buffer pool.

Parameters:

dev – [in] Pointer to device struct of the driver instance
buf – [in] Pointer to UHC request buffer

int uhc_ep_enqueue(const struct device *dev, struct uhc_transfer *const xfer)

Queue USB host controller transfer.

Add transfer to the queue. If the queue is empty, the transfer can be claimed by the controller immediately.

Parameters:

dev – [in] Pointer to device struct of the driver instance
xfer – [in] Pointer to UHC transfer

Return values:

-EPERM – controller is not initialized

Returns:

0 on success, all other values should be treated as error.

int uhc_ep_dequeue(const struct device *dev, struct uhc_transfer *const xfer)

Remove a USB host controller transfers from queue.

Not implemented yet.

Parameters:

dev – [in] Pointer to device struct of the driver instance
xfer – [in] Pointer to UHC transfer

Return values:

-EPERM – controller is not initialized

Returns:

0 on success, all other values should be treated as error.

int uhc_init(const struct device *dev, uhc_event_cb_t event_cb)

Initialize USB host controller.

Parameters:

dev – [in] Pointer to device struct of the driver instance
event_cb – [in] Event callback from the higher layer (USB host stack)

Return values:

-EINVAL – on parameter error (no callback is passed)
-EALREADY – already initialized

Returns:

0 on success, all other values should be treated as error.

int uhc_enable(const struct device *dev)

Enable USB host controller.

Enable powered USB host controller and allow host stack to recognize and enumerate devices.

Parameters:

dev – [in] Pointer to device struct of the driver instance

Return values:

-EPERM – controller is not initialized
-EALREADY – already enabled

Returns:

0 on success, all other values should be treated as error.

int uhc_disable(const struct device *dev)

Disable USB host controller.

Disable enabled USB host controller.

Parameters:

dev – [in] Pointer to device struct of the driver instance

Return values:

-EALREADY – already disabled

Returns:

0 on success, all other values should be treated as error.

int uhc_shutdown(const struct device *dev)

Poweroff USB host controller.

Shut down the controller completely to reduce energy consumption or to change the role of the controller.

Parameters:

dev – [in] Pointer to device struct of the driver instance

Return values:

-EALREADY – controller is already uninitialized

Returns:

0 on success, all other values should be treated as error.

static inline struct uhc_device_caps uhc_caps(const struct device *dev)

Get USB host controller capabilities.

Obtain the capabilities of the controller such as high speed (HS), and more.

Parameters:

dev – [in] Pointer to device struct of the driver instance

Returns:

USB host controller capabilities.

struct uhc_transfer

#include <uhc.h>

UHC endpoint buffer info.

This structure is mandatory for all UHC request. It contains the meta data about the request and FIFOs to store net_buf structures for each request.

The members of this structure should not be used directly by a higher layer (host stack).

Public Members

sys_dnode_t node: dlist node

uint8_t setup_pkt[8]: Control transfer setup packet.

struct net_buf *buf: Transfer data buffer.

uint8_t addr: Device (peripheral) address.

uint8_t ep: Endpoint to which request is associated.

uint8_t attrib: Endpoint attributes (TBD)

uint16_t mps: Maximum packet size.

uint16_t timeout: Timeout in number of frames.

unsigned int queued: Flag marks request buffer is queued.

unsigned int stage: Control stage status, up to the driver to use it or not.

void *udev: Pointer to USB device (opaque for the UHC)

void *cb: Pointer to transfer completion callback (opaque for the UHC)

int err: Transfer result, 0 on success, other values on error.

struct uhc_event

#include <uhc.h>

USB host controller event.

Common structure for all events that originate from the UHC driver and are passed to higher layer using message queue and a callback (uhc_event_cb_t) provided by higher layer during controller initialization (uhc_init).

Public Members

sys_snode_t node: slist node for the message queue

enum uhc_event_type type: Event type.

int status: Event status value, if any.

struct uhc_transfer *xfer: Pointer to request used only for UHC_EVT_EP_REQUEST.

const struct device *dev: Pointer to controller’s device struct.

struct uhc_device_caps

#include <uhc.h>

USB host controller capabilities.

This structure is mainly intended for the USB host stack.

Public Members

uint32_t hs: USB high speed capable controller.

struct uhc_data

#include <uhc.h>

Common UHC driver data structure.

Mandatory structure for each UHC controller driver. To be implemented as device’s private data (device->data).

Public Members

struct uhc_device_caps caps: Controller capabilities.

struct k_mutex mutex: Driver access mutex.

sys_dlist_t ctrl_xfers: dlist for control transfers

sys_dlist_t bulk_xfers: dlist for bulk transfers

uhc_event_cb_t event_cb: Callback to submit an UHC event to upper layer.

atomic_t status: USB host controller status.

void *priv: Driver private data.