USB host controller driver API

The USB host controller (UHC) driver API implements the low level layer to interface with the host controller. All USB host controller drivers should implement the APIs described in include/zephyr/drivers/usb/uhc.h.

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_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 owner)

Allocate UHC transfer.

Allocate a new transfer from common transfer pool. Transfer has no buffers after allocation, these can be requested and assigned separately.

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
owner – [in] Transfer owner

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.

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

Allocate UHC transfer buffer.

Allocate a new buffer from common request buffer pool and assign it to the transfer.

Parameters:

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

Returns:

pointer to allocated request or NULL on error.

int 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

Returns:

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

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

struct k_fifo queue: FIFO requests to process

struct k_fifo done: FIFO to keep completed requests

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 claimed: Flag marks request buffer claimed by the controller

unsigned int queued: Flag marks request buffer is queued

unsigned int setup: Flag marks setup stage of transfer

void *owner: Transfer owner

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

uint32_t value: Event value

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

int status: Event status, 0 on success, other (transfer) values on error

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