USB Device Core Layer API. More...

Data Structures
struct	usb_ep_cfg_data
	USB Endpoint Configuration. More...

struct	usb_interface_cfg_data
	USB Interface Configuration. More...

struct	usb_cfg_data
	USB device configuration. More...

Macros
#define	USB_TRANS_READ BIT(0) /** Read transfer flag */

#define	USB_TRANS_WRITE BIT(1) /** Write transfer flag */

#define	USB_TRANS_NO_ZLP BIT(2) /** No zero-length packet flag */

#define	USB_DEVICE_BOS_DESC_DEFINE_CAP static __in_section(usb, bos_desc_area, 1) __aligned(1) __used
	Helper macro to place the BOS compatibility descriptor in the right memory section.

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.

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.

int	usb_deconfig (void)
	Deconfigure USB controller.

int	usb_enable (usb_dc_status_callback status_cb)
	Enable the USB subsystem and associated hardware.

int	usb_disable (void)
	Disable the USB device.

int	usb_write (uint8_t ep, const uint8_t data, uint32_t data_len, uint32_t bytes_ret)
	Write data to the specified endpoint.

int	usb_read (uint8_t ep, uint8_t data, uint32_t max_data_len, uint32_t ret_bytes)
	Read data from the specified endpoint.

int	usb_ep_set_stall (uint8_t ep)
	Set STALL condition on the specified endpoint.

int	usb_ep_clear_stall (uint8_t ep)
	Clears STALL condition on the specified endpoint.

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.

int	usb_ep_read_continue (uint8_t ep)
	Continue reading data from the endpoint.

void	usb_transfer_ep_callback (uint8_t ep, enum usb_dc_ep_cb_status_code)
	Transfer management 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.

int	usb_transfer_sync (uint8_t ep, uint8_t *data, size_t dlen, unsigned int flags)
	Start a transfer and block-wait for completion.

void	usb_cancel_transfer (uint8_t ep)
	Cancel any ongoing transfer on the specified endpoint.

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.

int	usb_wakeup_request (void)
	Start the USB remote wakeup procedure.

bool	usb_get_remote_wakeup_status (void)
	Get status of the USB remote wakeup feature.

void	usb_bos_register_cap (void *hdr)
	Register BOS capability descriptor.

Detailed Description

USB Device Core Layer API.

Macro Definition Documentation

◆ USB_DEVICE_BOS_DESC_DEFINE_CAP

#define USB_DEVICE_BOS_DESC_DEFINE_CAP static __in_section(usb, bos_desc_area, 1) __aligned(1) __used

#include <zephyr/usb/usb_device.h>

Helper macro to place the BOS compatibility descriptor in the right memory section.

◆ USB_TRANS_NO_ZLP

#define USB_TRANS_NO_ZLP BIT(2) /** No zero-length packet flag */

#include <zephyr/usb/usb_device.h>

◆ USB_TRANS_READ

#define USB_TRANS_READ BIT(0) /** Read transfer flag */

#include <zephyr/usb/usb_device.h>

◆ USB_TRANS_WRITE

#define USB_TRANS_WRITE BIT(1) /** Write transfer flag */

#include <zephyr/usb/usb_device.h>

Typedef Documentation

◆ usb_ep_callback

typedef void(* usb_ep_callback) (uint8_t ep, enum usb_dc_ep_cb_status_code cb_status)

#include <zephyr/usb/usb_device.h>

Callback function signature for the USB Endpoint status.

◆ usb_interface_config

typedef void(* usb_interface_config) (struct usb_desc_header *head, uint8_t bInterfaceNumber)

#include <zephyr/usb/usb_device.h>

Function for interface runtime configuration.

◆ usb_request_handler

typedef int(* usb_request_handler) (struct usb_setup_packet *setup, int32_t *transfer_len, uint8_t **payload_data)

#include <zephyr/usb/usb_device.h>

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.

◆ usb_transfer_callback

typedef void(* usb_transfer_callback) (uint8_t ep, int tsize, void *priv)

#include <zephyr/usb/usb_device.h>

Callback function signature for transfer completion.

Function Documentation

◆ usb_bos_register_cap()

void usb_bos_register_cap ( void * hdr )

#include <zephyr/usb/usb_device.h>

Register BOS capability descriptor.

This function should be used by the application to register BOS capability descriptors before the USB device stack is enabled.

Parameters

[in] hdr Pointer to BOS capability descriptor

◆ usb_cancel_transfer()

void usb_cancel_transfer ( uint8_t ep )

#include <zephyr/usb/usb_device.h>

Cancel any ongoing transfer on the specified endpoint.

Parameters

[in] ep Endpoint address corresponding to the one listed in the device configuration table

◆ usb_cancel_transfers()

void usb_cancel_transfers ( void )

#include <zephyr/usb/usb_device.h>

Cancel all ongoing transfers.

◆ usb_deconfig()

int usb_deconfig ( void )

#include <zephyr/usb/usb_device.h>

Deconfigure USB controller.

This function returns the USB device to it's initial state

Returns: 0 on success, negative errno code on fail

◆ usb_disable()

int usb_disable ( void )

#include <zephyr/usb/usb_device.h>

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

◆ usb_enable()

int usb_enable ( usb_dc_status_callback status_cb )

#include <zephyr/usb/usb_device.h>

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

[in] status_cb Callback registered by user to notify about USB device controller state.

Returns: 0 on success, negative errno code on fail.

◆ usb_ep_clear_stall()

int usb_ep_clear_stall ( uint8_t ep )

#include <zephyr/usb/usb_device.h>

Clears STALL condition on the specified endpoint.

This function is called by USB device class handler code to clear stall condition on endpoint.

Parameters

[in] ep Endpoint address corresponding to the one listed in the device configuration table

Returns: 0 on success, negative errno code on fail

◆ usb_ep_read_continue()

int usb_ep_read_continue ( uint8_t ep )

#include <zephyr/usb/usb_device.h>

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

[in] ep Endpoint address corresponding to the one listed in the device configuration table

Returns: 0 on success, negative errno code on fail.

◆ usb_ep_read_wait()

int usb_ep_read_wait	(	uint8_t	ep,
		uint8_t *	data,
		uint32_t	max_data_len,
		uint32_t *	read_bytes
	)

#include <zephyr/usb/usb_device.h>

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

[in]	ep	Endpoint address corresponding to the one listed in the device configuration table
[in]	data	pointer to data buffer to write to
[in]	max_data_len	max length of data to read
[out]	read_bytes	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.

◆ usb_ep_set_stall()

int usb_ep_set_stall ( uint8_t ep )

#include <zephyr/usb/usb_device.h>

Set STALL condition on the specified endpoint.

This function is called by USB device class handler code to set stall condition on endpoint.

Parameters

[in] ep Endpoint address corresponding to the one listed in the device configuration table

Returns: 0 on success, negative errno code on fail

◆ usb_get_remote_wakeup_status()

bool usb_get_remote_wakeup_status ( void )

#include <zephyr/usb/usb_device.h>

Get status of the USB remote wakeup feature.

Returns: true if remote wakeup has been enabled by the host, false otherwise.

◆ usb_read()

int usb_read	(	uint8_t	ep,
		uint8_t *	data,
		uint32_t	max_data_len,
		uint32_t *	ret_bytes
	)

#include <zephyr/usb/usb_device.h>

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

[in]	ep	Endpoint address corresponding to the one listed in the device configuration table
[in]	data	Pointer to data buffer to write to
[in]	max_data_len	Max length of data to read
[out]	ret_bytes	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

◆ usb_set_config()

int usb_set_config ( const uint8_t * usb_descriptor )

#include <zephyr/usb/usb_device.h>

Configure USB controller.

Function to configure USB controller. Configuration parameters must be valid or an error is returned

Parameters

[in] usb_descriptor USB descriptor table

Returns: 0 on success, negative errno code on fail

◆ usb_transfer()

int usb_transfer	(	uint8_t	ep,
		uint8_t *	data,
		size_t	dlen,
		unsigned int	flags,
		usb_transfer_callback	cb,
		void *	priv
	)

#include <zephyr/usb/usb_device.h>

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

[in]	ep	Endpoint address corresponding to the one listed in the device configuration table
[in]	data	Pointer to data buffer to write-to/read-from
[in]	dlen	Size of data buffer
[in]	flags	Transfer flags (USB_TRANS_READ, USB_TRANS_WRITE...)
[in]	cb	Function called on transfer completion/failure
[in]	priv	Data passed back to the transfer completion callback

Returns: 0 on success, negative errno code on fail.

◆ usb_transfer_ep_callback()

void usb_transfer_ep_callback	(	uint8_t	ep,
		enum	usb_dc_ep_cb_status_code
	)

#include <zephyr/usb/usb_device.h>

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.

◆ usb_transfer_is_busy()

bool usb_transfer_is_busy ( uint8_t ep )

#include <zephyr/usb/usb_device.h>

Check that transfer is ongoing for the endpoint.

Parameters

[in] ep Endpoint address corresponding to the one listed in the device configuration table

Returns: true if transfer is ongoing, false otherwise.

◆ usb_transfer_sync()

int usb_transfer_sync	(	uint8_t	ep,
		uint8_t *	data,
		size_t	dlen,
		unsigned int	flags
	)

#include <zephyr/usb/usb_device.h>

Start a transfer and block-wait for completion.

Synchronous version of usb_transfer, wait for transfer completion before returning. A return value of zero can also mean that transfer was cancelled or that the endpoint is not ready. This is due to the design of transfers and usb_dc API.

Parameters

[in]	ep	Endpoint address corresponding to the one listed in the device configuration table
[in]	data	Pointer to data buffer to write-to/read-from
[in]	dlen	Size of data buffer
[in]	flags	Transfer flags

Returns: number of bytes transferred on success, negative errno code on fail.

◆ usb_wakeup_request()

int usb_wakeup_request ( void )

#include <zephyr/usb/usb_device.h>

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.

◆ usb_write()

int usb_write	(	uint8_t	ep,
		const uint8_t *	data,
		uint32_t	data_len,
		uint32_t *	bytes_ret
	)

#include <zephyr/usb/usb_device.h>

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

[in]	ep	Endpoint address corresponding to the one listed in the device configuration table
[in]	data	Pointer to data to write
[in]	data_len	Length of data requested to write. This may be zero for a zero length status packet.
[out]	bytes_ret	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

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ USB_DEVICE_BOS_DESC_DEFINE_CAP

◆ USB_TRANS_NO_ZLP

◆ USB_TRANS_READ

◆ USB_TRANS_WRITE

Typedef Documentation

◆ usb_ep_callback

◆ usb_interface_config

◆ usb_request_handler

◆ usb_transfer_callback

Function Documentation

◆ usb_bos_register_cap()

◆ usb_cancel_transfer()

◆ usb_cancel_transfers()

◆ usb_deconfig()

◆ usb_disable()

◆ usb_enable()

◆ usb_ep_clear_stall()

◆ usb_ep_read_continue()

◆ usb_ep_read_wait()

◆ usb_ep_set_stall()

◆ usb_get_remote_wakeup_status()

◆ usb_read()

◆ usb_set_config()

◆ usb_transfer()

◆ usb_transfer_ep_callback()

◆ usb_transfer_is_busy()

◆ usb_transfer_sync()

◆ usb_wakeup_request()

◆ usb_write()