USB Host Controller

USB host controller (UHC) driver API. More...

Data Structures
struct	usb_host_interface
struct	usb_host_ep
struct	usb_device
	Host representation of a USB device. More...
struct	uhc_transfer
	UHC endpoint buffer info. More...
struct	uhc_event
	USB host controller event. More...
struct	uhc_device_caps
	USB host controller capabilities. More...
struct	uhc_data
	Common UHC driver data structure. More...

Macros
#define	UHC_INTERFACES_MAX   32
#define	UHC_STATUS_INITIALIZED   0
	Controller is initialized by uhc_init()
#define	UHC_STATUS_ENABLED   1
	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.

Enumerations
enum	usb_device_state { USB_STATE_NOTCONNECTED , USB_STATE_DEFAULT , USB_STATE_ADDRESSED , USB_STATE_CONFIGURED }
	USB device state. More...
enum	usb_device_speed {   USB_SPEED_UNKNOWN , USB_SPEED_SPEED_LS , USB_SPEED_SPEED_FS , USB_SPEED_SPEED_HS ,   USB_SPEED_SPEED_SS }
	USB device operating speed. More...
enum	uhc_control_stage { UHC_CONTROL_STAGE_SETUP = 0 , UHC_CONTROL_STAGE_DATA , UHC_CONTROL_STAGE_STATUS }
	USB control transfer stage. More...
enum	uhc_event_type {   UHC_EVT_DEV_CONNECTED_LS , UHC_EVT_DEV_CONNECTED_FS , UHC_EVT_DEV_CONNECTED_HS , UHC_EVT_DEV_REMOVED ,   UHC_EVT_RESETED , UHC_EVT_SUSPENDED , UHC_EVT_RESUMED , UHC_EVT_RWUP ,   UHC_EVT_EP_REQUEST , UHC_EVT_ERROR }
	USB host controller event types. More...

Functions
static bool	uhc_is_initialized (const struct device *dev)
	Checks whether the controller is initialized.
static bool	uhc_is_enabled (const struct device *dev)
	Checks whether the controller is enabled.
static int	uhc_bus_reset (const struct device *dev)
	Reset USB bus.
static int	uhc_sof_enable (const struct device *dev)
	Enable Start of Frame generator.
static int	uhc_bus_suspend (const struct device *dev)
	Suspend USB bus.
static int	uhc_bus_resume (const struct device *dev)
	Resume USB bus.
struct uhc_transfer *	uhc_xfer_alloc (const struct device *dev, const uint8_t ep, struct usb_device *const udev, void *const cb, void *const cb_priv)
	Allocate UHC transfer.
struct uhc_transfer *	uhc_xfer_alloc_with_buf (const struct device *dev, const uint8_t ep, struct usb_device *const udev, void *const cb, void *const cb_priv, size_t size)
	Allocate UHC transfer with buffer.
int	uhc_xfer_free (const struct device *dev, struct uhc_transfer *const xfer)
	Free UHC transfer and any buffers.
int	uhc_xfer_buf_add (const struct device *dev, struct uhc_transfer *const xfer, struct net_buf *buf)
	Add UHC transfer buffer.
struct net_buf *	uhc_xfer_buf_alloc (const struct device *dev, const size_t size)
	Allocate UHC transfer buffer.
void	uhc_xfer_buf_free (const struct device *dev, struct net_buf *const buf)
	Free UHC request buffer.
int	uhc_ep_enqueue (const struct device *dev, struct uhc_transfer *const xfer)
	Queue USB host controller transfer.
int	uhc_ep_dequeue (const struct device *dev, struct uhc_transfer *const xfer)
	Remove a USB host controller transfers from queue.
int	uhc_init (const struct device *dev, uhc_event_cb_t event_cb, const void *const event_ctx)
	Initialize USB host controller.
int	uhc_enable (const struct device *dev)
	Enable USB host controller.
int	uhc_disable (const struct device *dev)
	Disable USB host controller.
int	uhc_shutdown (const struct device *dev)
	Poweroff USB host controller.
static struct uhc_device_caps	uhc_caps (const struct device *dev)
	Get USB host controller capabilities.
static const void *	uhc_get_event_ctx (const struct device *dev)
	Get pointer to higher layer context.

Detailed Description

USB host controller (UHC) driver API.

Since

3.3

Version

0.1.1

Macro Definition Documentation

UHC_INTERFACES_MAX

#define UHC_INTERFACES_MAX   32

#include <zephyr/drivers/usb/uhc.h>

UHC_STATUS_ENABLED

#define UHC_STATUS_ENABLED   1

#include <zephyr/drivers/usb/uhc.h>

Controller is enabled and all API functions are available.

UHC_STATUS_INITIALIZED

#define UHC_STATUS_INITIALIZED   0

#include <zephyr/drivers/usb/uhc.h>

Controller is initialized by uhc_init()

Typedef Documentation

uhc_event_cb_t

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

#include <zephyr/drivers/usb/uhc.h>

Callback to submit UHC event to higher layer.

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

Parameters

[in]	dev	Pointer to device struct of the driver instance
[in]	event	Point to event structure

Returns

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

Enumeration Type Documentation

uhc_control_stage

enum uhc_control_stage

#include <zephyr/drivers/usb/uhc.h>

USB control transfer stage.

Enumerator
UHC_CONTROL_STAGE_SETUP
UHC_CONTROL_STAGE_DATA
UHC_CONTROL_STAGE_STATUS

uhc_event_type

enum uhc_event_type

#include <zephyr/drivers/usb/uhc.h>

USB host controller event types.

Enumerator
UHC_EVT_DEV_CONNECTED_LS	Low speed device connected.
UHC_EVT_DEV_CONNECTED_FS	Full speed device connected.
UHC_EVT_DEV_CONNECTED_HS	High speed device connected.
UHC_EVT_DEV_REMOVED	Device (peripheral) removed.
UHC_EVT_RESETED	Bus reset operation finished.
UHC_EVT_SUSPENDED	Bus suspend operation finished.
UHC_EVT_RESUMED	Bus resume operation finished.
UHC_EVT_RWUP	Remote wakeup signal.
UHC_EVT_EP_REQUEST	Endpoint request result event.
UHC_EVT_ERROR	Non-correctable error event, requires attention from higher levels or application.

usb_device_speed

enum usb_device_speed

#include <zephyr/drivers/usb/uhc.h>

USB device operating speed.

Enumerator
USB_SPEED_UNKNOWN	Device is probably not connected.
USB_SPEED_SPEED_LS	Low speed.
USB_SPEED_SPEED_FS	Full speed.
USB_SPEED_SPEED_HS	High speed.
USB_SPEED_SPEED_SS	Super speed.

usb_device_state

enum usb_device_state

#include <zephyr/drivers/usb/uhc.h>

USB device state.

Enumerator
USB_STATE_NOTCONNECTED
USB_STATE_DEFAULT
USB_STATE_ADDRESSED
USB_STATE_CONFIGURED

Function Documentation

uhc_bus_reset()

int uhc_bus_reset ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/usb/uhc.h>

Reset USB bus.

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

Parameters

[in]

dev

Pointer to device struct of the driver instance

Returns

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

Return values

-EBUSY

if the controller is already performing a bus operation

uhc_bus_resume()

int uhc_bus_resume ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/usb/uhc.h>

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

[in]

dev

Pointer to device struct of the driver instance

Returns

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

Return values

-EBUSY

if the controller is already performing a bus operation

uhc_bus_suspend()

int uhc_bus_suspend ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/usb/uhc.h>

Suspend USB bus.

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

Parameters

[in]

dev

Pointer to device struct of the driver instance

Returns

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

Return values

-EALREADY

if already suspended

uhc_caps()

struct uhc_device_caps uhc_caps ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/usb/uhc.h>

Get USB host controller capabilities.

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

Parameters

[in]

dev

Pointer to device struct of the driver instance

Returns

USB host controller capabilities.

uhc_disable()

int uhc_disable

(

const struct device *

dev

)

#include <zephyr/drivers/usb/uhc.h>

Disable USB host controller.

Disable enabled USB host controller.

Parameters

[in]

dev

Pointer to device struct of the driver instance

Returns

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

Return values

-EALREADY

already disabled

uhc_enable()

int uhc_enable

(

const struct device *

dev

)

#include <zephyr/drivers/usb/uhc.h>

Enable USB host controller.

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

Parameters

[in]

dev

Pointer to device struct of the driver instance

Returns

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

Return values

-EPERM	controller is not initialized
-EALREADY	already enabled

uhc_ep_dequeue()

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

#include <zephyr/drivers/usb/uhc.h>

Remove a USB host controller transfers from queue.

Not implemented yet.

Parameters

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

Returns

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

Return values

-EPERM

controller is not initialized

uhc_ep_enqueue()

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

#include <zephyr/drivers/usb/uhc.h>

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

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

Returns

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

Return values

-EPERM

controller is not initialized

uhc_get_event_ctx()

const void * uhc_get_event_ctx ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/usb/uhc.h>

Get pointer to higher layer context.

The address of the context is passed as an argument to the uhc_init() function and is stored in the uhc data.

Parameters

[in]

dev

Pointer to device struct of the driver instance

Returns

Opaque pointer to higher layer context

uhc_init()

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

#include <zephyr/drivers/usb/uhc.h>

Initialize USB host controller.

Initialize USB host controller.

Parameters

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

Returns

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

Return values

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

uhc_is_enabled()

bool uhc_is_enabled ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/usb/uhc.h>

Checks whether the controller is enabled.

Parameters

[in]

dev

Pointer to device struct of the driver instance

Returns

true if controller is enabled, false otherwise

uhc_is_initialized()

bool uhc_is_initialized ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/usb/uhc.h>

Checks whether the controller is initialized.

Parameters

[in]

dev

Pointer to device struct of the driver instance

Returns

true if controller is initialized, false otherwise

uhc_shutdown()

int uhc_shutdown

(

const struct device *

dev

)

#include <zephyr/drivers/usb/uhc.h>

Poweroff USB host controller.

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

Parameters

[in]

dev

Pointer to device struct of the driver instance

Returns

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

Return values

-EALREADY

controller is already uninitialized

uhc_sof_enable()

int uhc_sof_enable ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/usb/uhc.h>

Enable Start of Frame generator.

Enable SOF generator.

Parameters

[in]

dev

Pointer to device struct of the driver instance

Returns

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

Return values

-EALREADY

if already enabled

uhc_xfer_alloc()

struct uhc_transfer * uhc_xfer_alloc	(	const struct device *	dev,
		const uint8_t	ep,
		struct usb_device *const	udev,
		void *const	cb,
		void *const	cb_priv )

#include <zephyr/drivers/usb/uhc.h>

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

[in]	dev	Pointer to device struct of the driver instance
[in]	ep	Endpoint address
[in]	udev	Pointer to USB device
[in]	cb	Transfer completion callback
[in]	cb_priv	Completion callback callback private data

Returns

pointer to allocated transfer or NULL on error.

uhc_xfer_alloc_with_buf()

struct uhc_transfer * uhc_xfer_alloc_with_buf	(	const struct device *	dev,
		const uint8_t	ep,
		struct usb_device *const	udev,
		void *const	cb,
		void *const	cb_priv,
		size_t	size )

#include <zephyr/drivers/usb/uhc.h>

Allocate UHC transfer with buffer.

Allocate a new transfer from common transfer pool with buffer.

Parameters

[in]	dev	Pointer to device struct of the driver instance
[in]	ep	Endpoint address
[in]	udev	Pointer to USB device
[in]	cb	Transfer completion callback
[in]	cb_priv	Completion callback callback private data
[in]	size	Size of the buffer

Returns

pointer to allocated transfer or NULL on error.

uhc_xfer_buf_add()

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

#include <zephyr/drivers/usb/uhc.h>

Add UHC transfer buffer.

Add a previously allocated buffer to the transfer.

Parameters

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

Returns

pointer to allocated request or NULL on error.

uhc_xfer_buf_alloc()

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

#include <zephyr/drivers/usb/uhc.h>

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

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

Returns

pointer to allocated request or NULL on error.

uhc_xfer_buf_free()

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

#include <zephyr/drivers/usb/uhc.h>

Free UHC request buffer.

Put the buffer back into the request buffer pool.

Parameters

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

uhc_xfer_free()

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

#include <zephyr/drivers/usb/uhc.h>

Free UHC transfer and any buffers.

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

Parameters

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

Returns

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