New USB device controller (UDC) driver API . More...

Functions
static bool	udc_is_initialized (const struct device *dev)
	Checks whether the controller is initialized.

static bool	udc_is_enabled (const struct device *dev)
	Checks whether the controller is enabled.

static bool	udc_is_suspended (const struct device *dev)
	Checks whether the controller is suspended.

int	udc_init (const struct device dev, udc_event_cb_t event_cb, const void const event_ctx)
	Initialize USB device controller.

int	udc_enable (const struct device *dev)
	Enable USB device controller.

int	udc_disable (const struct device *dev)
	Disable USB device controller.

int	udc_shutdown (const struct device *dev)
	Poweroff USB device controller.

static struct udc_device_caps	udc_caps (const struct device *dev)
	Get USB device controller capabilities.

enum udc_bus_speed	udc_device_speed (const struct device *dev)
	Get actual USB device speed.

static int	udc_set_address (const struct device *dev, const uint8_t addr)
	Set USB device address.

static int	udc_test_mode (const struct device *dev, const uint8_t mode, const bool dryrun)
	Enable Test Mode.

static int	udc_host_wakeup (const struct device *dev)
	Initiate host wakeup procedure.

int	udc_ep_try_config (const struct device dev, const uint8_t ep, const uint8_t attributes, uint16_t const mps, const uint8_t interval)
	Try an endpoint configuration.

int	udc_ep_enable (const struct device *dev, const uint8_t ep, const uint8_t attributes, const uint16_t mps, const uint8_t interval)
	Configure and enable endpoint.

int	udc_ep_disable (const struct device *dev, const uint8_t ep)
	Disable endpoint.

int	udc_ep_set_halt (const struct device *dev, const uint8_t ep)
	Halt endpoint.

int	udc_ep_clear_halt (const struct device *dev, const uint8_t ep)
	Clear endpoint halt.

int	udc_ep_enqueue (const struct device dev, struct net_buf const buf)
	Queue USB device controller request.

int	udc_ep_dequeue (const struct device *dev, const uint8_t ep)
	Remove all USB device controller requests from endpoint queue.

struct net_buf *	udc_ep_buf_alloc (const struct device *dev, const uint8_t ep, const size_t size)
	Allocate UDC request buffer.

int	udc_ep_buf_free (const struct device dev, struct net_buf const buf)
	Free UDC request buffer.

static void	udc_ep_buf_set_zlp (struct net_buf *const buf)
	Set ZLP flag in requests metadata.

static struct udc_buf_info *	udc_get_buf_info (const struct net_buf *const buf)
	Get requests metadata.

static const void *	udc_get_event_ctx (const struct device *dev)
	Get pointer to higher layer context.

static uint16_t	udc_mps_ep_size (const struct udc_ep_config *const cfg)
	Get endpoint size from UDC endpoint configuration.

Detailed Description

New USB device controller (UDC) driver API .

Since: 3.3

Version: 0.1.0

Function Documentation

◆ udc_caps()

static struct udc_device_caps udc_caps ( const struct device * dev )

inlinestatic

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

Get USB device controller capabilities.

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

Parameters

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

Returns: USB device controller capabilities.

◆ udc_device_speed()

enum udc_bus_speed udc_device_speed ( const struct device * dev )

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

Get actual USB device speed.

The function should be called after the reset event to determine the actual bus speed.

Parameters

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

Returns: USB device controller capabilities.

◆ udc_disable()

int udc_disable ( const struct device * dev )

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

Disable USB device controller.

Disable enabled USB device controller. The driver should continue to detect power state changes.

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

◆ udc_enable()

int udc_enable ( const struct device * dev )

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

Enable USB device controller.

Enable powered USB device controller and allow host to recognize and enumerate the device.

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
-ETIMEDOUT	enable operation timed out

◆ udc_ep_buf_alloc()

struct net_buf * udc_ep_buf_alloc	(	const struct device *	dev,
		const uint8_t	ep,
		const size_t	size )

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

Allocate UDC request buffer.

Allocate a new buffer from common request buffer pool.

Parameters

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

Returns: pointer to allocated request or NULL on error.

◆ udc_ep_buf_free()

int udc_ep_buf_free	(	const struct device *	dev,
		struct net_buf *const	buf )

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

Free UDC 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 UDC request buffer

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

◆ udc_ep_buf_set_zlp()

static void udc_ep_buf_set_zlp ( struct net_buf *const buf )

inlinestatic

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

Set ZLP flag in requests metadata.

The controller should send a ZLP at the end of the transfer.

Parameters

[in] buf Pointer to UDC request buffer

◆ udc_ep_clear_halt()

int udc_ep_clear_halt	(	const struct device *	dev,
		const uint8_t	ep )

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

Clear endpoint halt.

Valid for all endpoints.

Parameters

[in]	dev	Pointer to device struct of the driver instance
[in]	ep	Endpoint address

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

Return values

-ENODEV	endpoint configuration not found
-ENOTSUP	not supported (e.g. isochronous endpoint)
-EPERM	controller is not enabled

◆ udc_ep_dequeue()

int udc_ep_dequeue	(	const struct device *	dev,
		const uint8_t	ep )

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

Remove all USB device controller requests from endpoint queue.

UDC_EVT_EP_REQUEST event will be generated when the driver releases claimed buffer, no new requests will be claimed, all requests in the queue will passed as chained list of the event variable buf. The endpoint queue is empty after that.

Parameters

[in]	dev	Pointer to device struct of the driver instance
[in]	ep	Endpoint address

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

Return values

-ENODEV	endpoint configuration not found
-EACCES	endpoint is not disabled
-EPERM	controller is not initialized

◆ udc_ep_disable()

int udc_ep_disable	(	const struct device *	dev,
		const uint8_t	ep )

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

Disable endpoint.

Valid for all endpoints except control IN/OUT.

Parameters

[in]	dev	Pointer to device struct of the driver instance
[in]	ep	Endpoint address

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

Return values

-EINVAL	on wrong parameter (control IN/OUT endpoint)
-ENODEV	endpoint configuration not found
-EALREADY	endpoint is already disabled
-EPERM	controller is not initialized

◆ udc_ep_enable()

int udc_ep_enable	(	const struct device *	dev,
		const uint8_t	ep,
		const uint8_t	attributes,
		const uint16_t	mps,
		const uint8_t	interval )

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

Configure and enable endpoint.

Configure and make an endpoint ready for use. Valid for all endpoints except control IN/OUT.

Parameters

[in]	dev	Pointer to device struct of the driver instance
[in]	ep	Endpoint address (same as bEndpointAddress)
[in]	attributes	Endpoint attributes (same as bmAttributes)
[in]	mps	Maximum packet size (same as wMaxPacketSize)
[in]	interval	Polling interval (same as bInterval)

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

Return values

-EINVAL	on wrong parameter (control IN/OUT endpoint)
-EPERM	controller is not initialized
-ENODEV	endpoint configuration not found
-EALREADY	endpoint is already enabled

◆ udc_ep_enqueue()

int udc_ep_enqueue	(	const struct device *	dev,
		struct net_buf *const	buf )

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

Queue USB device controller request.

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

Parameters

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

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

Return values

-ENODEV	endpoint configuration not found
-EACCES	endpoint is not enabled (TBD)
-EBUSY	request can not be queued
-EPERM	controller is not initialized

◆ udc_ep_set_halt()

int udc_ep_set_halt	(	const struct device *	dev,
		const uint8_t	ep )

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

Halt endpoint.

Valid for all endpoints.

Parameters

[in]	dev	Pointer to device struct of the driver instance
[in]	ep	Endpoint address

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

Return values

-ENODEV	endpoint configuration not found
-ENOTSUP	not supported (e.g. isochronous endpoint)
-EPERM	controller is not enabled

◆ udc_ep_try_config()

int udc_ep_try_config	(	const struct device *	dev,
		const uint8_t	ep,
		const uint8_t	attributes,
		uint16_t *const	mps,
		const uint8_t	interval )

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

Try an endpoint configuration.

Try an endpoint configuration based on endpoint descriptor. This function may modify wMaxPacketSize descriptor fields of the endpoint. All properties of the descriptor, such as direction, and transfer type, should be set correctly. If wMaxPacketSize value is zero, it will be updated to maximum buffer size of the endpoint.

Parameters

[in]	dev	Pointer to device struct of the driver instance
[in]	ep	Endpoint address (same as bEndpointAddress)
[in]	attributes	Endpoint attributes (same as bmAttributes)
[in]	mps	Maximum packet size (same as wMaxPacketSize)
[in]	interval	Polling interval (same as bInterval)

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

Return values

-EINVAL	on wrong parameter
-ENOTSUP	endpoint configuration not supported
-ENODEV	no endpoints available

◆ udc_get_buf_info()

static struct udc_buf_info * udc_get_buf_info ( const struct net_buf *const buf )

inlinestatic

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

Get requests metadata.

Parameters

[in] buf Pointer to UDC request buffer

Returns: pointer to metadata structure.

◆ udc_get_event_ctx()

static const void * udc_get_event_ctx ( const struct device * dev )

inlinestatic

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

Get pointer to higher layer context.

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

Parameters

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

Returns: Opaque pointer to higher layer context

◆ udc_host_wakeup()

static int udc_host_wakeup ( const struct device * dev )

inlinestatic

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

Initiate host wakeup procedure.

Initiate host wakeup. Only possible when the 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

-EPERM controller is not enabled (or not initialized)

◆ udc_init()

int udc_init	(	const struct device *	dev,
		udc_event_cb_t	event_cb,
		const void *const	event_ctx )

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

Initialize USB device controller.

Initialize USB device controller and control IN/OUT endpoint. After initialization controller driver should be able to detect power state of the bus and signal power state changes.

Parameters

[in]	dev	Pointer to device struct of the driver instance
[in]	event_cb	Event callback from the higher layer (USB device 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

◆ udc_is_enabled()

static bool udc_is_enabled ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/usb/udc.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

◆ udc_is_initialized()

static bool udc_is_initialized ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/usb/udc.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

◆ udc_is_suspended()

static bool udc_is_suspended ( const struct device * dev )

inlinestatic

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

Checks whether the controller is suspended.

Parameters

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

Returns: true if controller is suspended, false otherwise

◆ udc_mps_ep_size()

static uint16_t udc_mps_ep_size ( const struct udc_ep_config *const cfg )

inlinestatic

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

Get endpoint size from UDC endpoint configuration.

Parameters

[in] cfg Pointer to UDC endpoint configuration

Returns: Endpoint size

◆ udc_set_address()

static int udc_set_address	(	const struct device *	dev,
		const uint8_t	addr )

inlinestatic

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

Set USB device address.

Set address of enabled USB device.

Parameters

[in]	dev	Pointer to device struct of the driver instance
[in]	addr	USB device address

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

Return values

-EPERM controller is not enabled (or not initialized)

◆ udc_shutdown()

int udc_shutdown ( const struct device * dev )

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

Poweroff USB device 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 not initialized

◆ udc_test_mode()

static int udc_test_mode	(	const struct device *	dev,
		const uint8_t	mode,
		const bool	dryrun )

inlinestatic

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

Enable Test Mode.

For compliance testing, high-speed controllers must support test modes. A particular test is enabled by a SetFeature(TEST_MODE) request. To disable a test mode, device needs to be power cycled.

Parameters

[in]	dev	Pointer to device struct of the driver instance
[in]	mode	Test mode
[in]	dryrun	Verify that a particular mode can be enabled, but do not enable test mode

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

Return values

-ENOTSUP Test mode is not supported

Functions

Detailed Description

Function Documentation

◆ udc_caps()

◆ udc_device_speed()

◆ udc_disable()

◆ udc_enable()

◆ udc_ep_buf_alloc()

◆ udc_ep_buf_free()

◆ udc_ep_buf_set_zlp()

◆ udc_ep_clear_halt()

◆ udc_ep_dequeue()

◆ udc_ep_disable()

◆ udc_ep_enable()

◆ udc_ep_enqueue()

◆ udc_ep_set_halt()

◆ udc_ep_try_config()

◆ udc_get_buf_info()

◆ udc_get_event_ctx()

◆ udc_host_wakeup()

◆ udc_init()

◆ udc_is_enabled()

◆ udc_is_initialized()

◆ udc_is_suspended()

◆ udc_mps_ep_size()

◆ udc_set_address()

◆ udc_shutdown()

◆ udc_test_mode()