This is a generic low-level USB driver interface. More...

Detailed Description

This is a generic low-level USB driver interface.

About

usbdev specifies a common USB device API for low level USB interfaces. The interface is split in a definition for the USB interface hardware and for individual USB endpoints.

Design goals

Support for multiple instances on a single board
Interface optimized for MCU peripheral interfaces.

Details

The driver interface is split in two separate parts. One part is a global USB device interface, the other is an endpoint control API.

The usb device driver can manage parts of the USB interface itself such as the pull up resistor state or the USB speed.

The endpoint control API manages a single endpoint. This allows for a modular approach where multiple USB functions/interfaces can be multiplexed over a single USB interface. Each interface can be implemented as a separate module. The interface handler does not have to care about the usb device itself or it's endpoint number. It can simply request an available endpoint from the usb device with the usbdev_new_ep function.

Each interface handler can request multiple endpoints from the usbdev device. It must supply the expected maximum endpoint transfer size and other properties of the endpoint. A pointer to an usbdev endpoint is returned if an endpoint fitting the requirements is available.

Data transmission is done via the usbdev_ep_xmit function. A buffer and length must be supplied. Received data from the host ends up at this buffer automatically by the low level drivers after reception. For reception the maximum expected transfer length must be supplied, equal to the maximum endpoint transfer size. The data received can be less than this.

For transmitting data back to the host, a similar approach is used. The data to be transmitted is supplied as buffer and the usbdev_ep_xmit function is called with the buffer and the size of the data.

To ensure that the data buffers adhere to the restrictions of the low level USB peripheral memory interface, the specific usbdev_ep_buf_t data type must be used. It behaves as a regular uint8_t byte buffer, but is instantiated with the attributes to ensure that the low level DMA interface can use it.

A callback function is required for signalling events from the driver. The USBDEV_EVENT_ESR is special in that it indicates that the USB peripheral had an interrupt that needs to be serviced in a non-interrupt context. This requires the usbdev_esr function to be called. In the case that the event is signalled via the usbdev_t::epcb callback, the usbdev_ep_esr should be called to service the endpoint specific events from the peripheral.

Files
file	usbdev.h
	Definitions low-level USB driver interface.

file	usbdev_synopsys_dwc2.h
	Low level USB FS/HS driver definitions for MCUs with Synopsys DWC2 IP core.

Data Structures
struct	usbdev
	usbdev device descriptor More...

struct	usbdev_ep
	usbdev endpoint descriptor More...

struct	usbdev_driver
	usbdev driver functions More...

Macros
#define	USBDEV_CPU_DMA_REQUIREMENTS
	USBDEV endpoint buffer CPU-specific requirements.

#define	usbdev_ep_buf_t USBDEV_CPU_DMA_REQUIREMENTS uint8_t
	Instantiation type for usbdev endpoint buffers.

#define	USBDEV_CPU_SET_ADDR_AFTER_STATUS 1
	USBDEV specific requirement for setting the device address.

#define	USBDEV_NUM_ENDPOINTS 8
	Number of USB IN and OUT endpoints allocated.

Typedefs
typedef struct usbdev	usbdev_t
	usbdev_t forward declaration

typedef struct usbdev_ep	usbdev_ep_t
	usbdev_ep_t forward declaration

typedef void(*	usbdev_event_cb_t) (usbdev_t *usbdev, usbdev_event_t event)
	Event callback for signaling usbdev event to upper layers.

typedef void(*	usbdev_ep_event_cb_t) (usbdev_ep_t *ep, usbdev_event_t event)
	Event callback for signaling endpoint events to upper layers.

typedef struct usbdev_driver	usbdev_driver_t
	usbdev driver functions

Enumerations
enum	usbdev_event_t { USBDEV_EVENT_ESR = 1 , USBDEV_EVENT_HOST_CONNECT , USBDEV_EVENT_HOST_DISCONNECT , USBDEV_EVENT_RESET , USBDEV_EVENT_SOF , USBDEV_EVENT_SUSPEND , USBDEV_EVENT_RESUME , USBDEV_EVENT_TR_COMPLETE , USBDEV_EVENT_TR_STALL }
	List of event types that can be send from the device driver to the upper layer. More...

Functions
void	usbdev_init_lowlevel (void)
	Low level USB peripheral driver initialization.

usbdev_t *	usbdev_get_ctx (unsigned num)
	Retrieve usbdev context from the peripheral.

static void	usbdev_init (usbdev_t *dev)
	Initialize the USB peripheral device.

static usbdev_ep_t *	usbdev_new_ep (usbdev_t *dev, usb_ep_type_t type, usb_ep_dir_t dir, size_t size)
	Retrieve an USB endpoint of the specified type.

static int	usbdev_get (usbdev_t dev, usbopt_t opt, void value, size_t max_len)
	Get an option value from a given usb device.

static int	usbdev_set (usbdev_t dev, usbopt_t opt, const void value, size_t value_len)
	Set an option value for a given usb device.

static void	usbdev_esr (usbdev_t *dev)
	a driver's user-space event service handler

static void	usbdev_ep0_stall (usbdev_t *dev)
	Stall both OUT and IN packets on endpoint 0 until a setup packet is received.

static void	usbdev_ep_init (usbdev_ep_t *ep)
	Initialize the USB endpoint.

static void	usbdev_ep_stall (usbdev_ep_t *ep, bool enable)
	Enable or disable the stall condition on the USB endpoint.

static int	usbdev_ep_get (usbdev_ep_t ep, usbopt_ep_t opt, void value, size_t max_len)
	Get an option value from a given usb device endpoint.

static int	usbdev_ep_set (usbdev_ep_t ep, usbopt_ep_t opt, const void value, size_t value_len)
	Set an option value for a given usb device endpoint.

static void	usbdev_ep_esr (usbdev_ep_t *ep)
	an endpoint's user-space event handler

static int	usbdev_ep_xmit (usbdev_ep_t ep, uint8_t buf, size_t len)
	Submit a buffer for a USB endpoint transmission.

Macro Definition Documentation

◆ USBDEV_CPU_DMA_REQUIREMENTS

#define USBDEV_CPU_DMA_REQUIREMENTS

USBDEV endpoint buffer CPU-specific requirements.

Can be overridden by periph_cpu if needed by the USB peripheral DMA.

Definition at line 107 of file usbdev.h.

◆ USBDEV_CPU_SET_ADDR_AFTER_STATUS

#define USBDEV_CPU_SET_ADDR_AFTER_STATUS 1

USBDEV specific requirement for setting the device address.

The address in the USB device can be set either directly after the SETUP stage on receipt of the SET ADDRESS Request or after the associated status stage. When the USB device address has to be set depends on the hardware. If USBDEV_CPU_SET_ADDR_AFTER_STATUS has the value 1 (default), the address is only set in the USB device after the status stage. Overwrite it with 0 in periph_cpu.h to set the address already directly after the SETUP stage.

Definition at line 139 of file usbdev.h.

◆ usbdev_ep_buf_t

#define usbdev_ep_buf_t USBDEV_CPU_DMA_REQUIREMENTS uint8_t

Instantiation type for usbdev endpoint buffers.

Functions passing around pointers to these buffers can still use uint8_t for the argument type.

Example usage:

usbdev_ep_buf_t buffer[64];

usbdev_ep_buf_t

#define usbdev_ep_buf_t

Instantiation type for usbdev endpoint buffers.

Definition usbdev.h:126

Note: This is a define and not a typedef so that the above works. With a typedef it would instantiate an array of aligned uint8_t and not an aligned array of uint8_t (assuming the requirement is alignment).

Definition at line 126 of file usbdev.h.

◆ USBDEV_NUM_ENDPOINTS

#define USBDEV_NUM_ENDPOINTS 8

Number of USB IN and OUT endpoints allocated.

Configures the number of endpoints allocated. An equal number of IN and OUT endpoints are allocated

Definition at line 149 of file usbdev.h.

Typedef Documentation

◆ usbdev_driver_t

typedef struct usbdev_driver usbdev_driver_t

usbdev driver functions

Helpers (such as usbdev_init) are provided and should be used instead. Directly calling these functions is not recommended.

◆ usbdev_ep_event_cb_t

typedef void(* usbdev_ep_event_cb_t) (usbdev_ep_t *ep, usbdev_event_t event)

Event callback for signaling endpoint events to upper layers.

Parameters

[in]	ep	usbdev endpoint context
[in]	event	type of the event

Definition at line 241 of file usbdev.h.

◆ usbdev_ep_t

typedef struct usbdev_ep usbdev_ep_t

usbdev_ep_t forward declaration

Definition at line 99 of file usbdev.h.

◆ usbdev_event_cb_t

typedef void(* usbdev_event_cb_t) (usbdev_t *usbdev, usbdev_event_t event)

Event callback for signaling usbdev event to upper layers.

Parameters

[in]	usbdev	usbdev context
[in]	event	type of the event

Definition at line 233 of file usbdev.h.

◆ usbdev_t

typedef struct usbdev usbdev_t

usbdev_t forward declaration

Definition at line 94 of file usbdev.h.

Enumeration Type Documentation

◆ usbdev_event_t

enum usbdev_event_t

List of event types that can be send from the device driver to the upper layer.

Enumerator
USBDEV_EVENT_ESR	Driver needs it's ESR (event service routine) handled.
USBDEV_EVENT_HOST_CONNECT	Host connection detected. A host has connected to the device. Detection should happen by detecting the USB power, but other detection mechanisms might be used.
USBDEV_EVENT_HOST_DISCONNECT	Host disconnected from the device. Similar to USBDEV_EVENT_HOST_CONNECT, except that the host disconnected instead.
USBDEV_EVENT_RESET	Line reset occurred. A line reset is a host initiated USB reset to the peripheral The peripheral driver must clears the following settings before emitting this event: Device address Endpoint configuration, including stall settings
USBDEV_EVENT_SOF	Start of Frame received. A Start of Frame (SoF) packet is received from the host.
USBDEV_EVENT_SUSPEND	USB suspend condition active.
USBDEV_EVENT_RESUME	USB suspend condition no longer active.
USBDEV_EVENT_TR_COMPLETE	Transaction completed event. An endpoint must emit this event after a transaction with the host occurred to indicate that the data in the buffer is used or new depending on the endpoint direction
USBDEV_EVENT_TR_STALL	Transaction stall event. An endpoint should emit this event after a stall reply has been transmitted to the host

Definition at line 156 of file usbdev.h.

Function Documentation

◆ usbdev_ep0_stall()

static void usbdev_ep0_stall ( usbdev_t * dev )

inlinestatic

Stall both OUT and IN packets on endpoint 0 until a setup packet is received.

See also: usbdev_driver_t::ep0_stall

Note: The stall condition is automatically cleared after receiving a setup packet.

Precondition: (dev != NULL)

Parameters

[in] dev USB device descriptor

Definition at line 555 of file usbdev.h.

◆ usbdev_ep_esr()

static void usbdev_ep_esr ( usbdev_ep_t * ep )

inlinestatic

an endpoint's user-space event handler

See also: usbdev_driver_t::ep_esr

Precondition: (ep != NULL); (ep->dev != NULL)

Parameters

[in] ep USB endpoint descriptor to service

Definition at line 656 of file usbdev.h.

◆ usbdev_ep_get()

static int usbdev_ep_get	(	usbdev_ep_t *	ep,
		usbopt_ep_t	opt,
		void *	value,
		size_t	max_len
	)

inlinestatic

Get an option value from a given usb device endpoint.

See also: usbdev_driver_t::ep_get

Precondition: (ep != NULL); (ep->dev != NULL)

Parameters

[in]	ep	USB endpoint descriptor
[in]	opt	option type
[out]	value	pointer to store the option's value in
[in]	max_len	maximum number of byte that fit into `value`

Returns: number of bytes written to value; < 0 on error

Definition at line 614 of file usbdev.h.

◆ usbdev_ep_init()

static void usbdev_ep_init ( usbdev_ep_t * ep )

inlinestatic

Initialize the USB endpoint.

See also: usbdev_driver_t::ep_init

Precondition: (ep != NULL); (ep->dev != NULL)

Parameters

[in] ep USB endpoint descriptor

Definition at line 571 of file usbdev.h.

◆ usbdev_ep_set()

static int usbdev_ep_set	(	usbdev_ep_t *	ep,
		usbopt_ep_t	opt,
		const void *	value,
		size_t	value_len
	)

inlinestatic

Set an option value for a given usb device endpoint.

See also: usbdev_driver_t::ep_set

Precondition: (ep != NULL); (ep->dev != NULL)

Parameters

[in]	ep	USB endpoint descriptor
[in]	opt	option type
[in]	value	pointer to the value
[in]	value_len	the length of `value`

Returns: number of bytes used from value; < 0 on error

Definition at line 638 of file usbdev.h.

◆ usbdev_ep_stall()

static void usbdev_ep_stall	(	usbdev_ep_t *	ep,
		bool	enable
	)

inlinestatic

Enable or disable the stall condition on the USB endpoint.

Note: For enabling stall on endpoint 0 usbdev_driver_t::ep0_stall must be used.

See also: usbdev_driver_t::ep_stall

Precondition: (ep->num != 0)

Parameters

[in]	ep	USB endpoint descriptor
[in]	enable	True to set stall, false to disable stall

Definition at line 591 of file usbdev.h.

◆ usbdev_ep_xmit()

static int usbdev_ep_xmit	(	usbdev_ep_t *	ep,
		uint8_t *	buf,
		size_t	len
	)

inlinestatic

Submit a buffer for a USB endpoint transmission.

When dealing with an OUT type endpoint, len must be the maximum allowed transfer size for the endpoint. The host is allowed to transfer fewer bytes than len.

See also: usbdev_driver_t::xmit

Precondition: (ep != NULL); (ep->dev != NULL)

Parameters

[in]	ep	USB endpoint descriptor
[in,out]	buf	Buffer to submit for transmission
[in]	len	length of the buffer in bytes to be transmitted or received

Definition at line 679 of file usbdev.h.

◆ usbdev_esr()

static void usbdev_esr ( usbdev_t * dev )

inlinestatic

a driver's user-space event service handler

See also: usbdev_driver_t::esr

Precondition: (dev != NULL)

Parameters

[in] dev USB device descriptor

Definition at line 536 of file usbdev.h.

◆ usbdev_get()

static int usbdev_get	(	usbdev_t *	dev,
		usbopt_t	opt,
		void *	value,
		size_t	max_len
	)

inlinestatic

Get an option value from a given usb device.

See also: usbdev_driver_t::get

Precondition: (dev != NULL)

Parameters

[in]	dev	USB device descriptor
[in]	opt	option type
[out]	value	pointer to store the option's value in
[in]	max_len	maximal amount of byte that fit into `value`

Returns: number of bytes written to value; < 0 on error 0

Definition at line 498 of file usbdev.h.

◆ usbdev_get_ctx()

usbdev_t * usbdev_get_ctx ( unsigned num )

Retrieve usbdev context from the peripheral.

Parameters

num	usbdev peripheral number to retrieve

Returns: the usbdev context at index num

◆ usbdev_init()

static void usbdev_init ( usbdev_t * dev )

inlinestatic

Initialize the USB peripheral device.

See also: usbdev_driver_t::init

Precondition: (dev != NULL)

Parameters

dev	usb device to initialize

Definition at line 455 of file usbdev.h.

◆ usbdev_init_lowlevel()

void usbdev_init_lowlevel ( void )

Low level USB peripheral driver initialization.

This function prepares all usbdev peripherals available for initialization

◆ usbdev_new_ep()

static usbdev_ep_t * usbdev_new_ep	(	usbdev_t *	dev,
		usb_ep_type_t	type,
		usb_ep_dir_t	dir,
		size_t	size
	)

inlinestatic

Retrieve an USB endpoint of the specified type.

See also: usbdev_driver_t::new_ep

Precondition: (dev != NULL)

Parameters

[in]	dev	USB device descriptor
[in]	type	USB endpoint type
[in]	dir	USB endpoint direction
[in]	size	Maximum USB endpoint buffer size used

Returns: ptr to the new USB endpoint descriptor; NULL on error

Definition at line 476 of file usbdev.h.

◆ usbdev_set()

static int usbdev_set	(	usbdev_t *	dev,
		usbopt_t	opt,
		const void *	value,
		size_t	value_len
	)

inlinestatic

Set an option value for a given usb device.

See also: usbdev_driver_t::set

Precondition: (dev != NULL)

Parameters

[in]	dev	USB device descriptor
[in]	opt	option type
[in]	value	value to set
[in]	value_len	the length of `value`

Returns: number of bytes used from value; < 0 on error

Definition at line 520 of file usbdev.h.

Detailed Description

About

Design goals

Details

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ USBDEV_CPU_DMA_REQUIREMENTS

◆ USBDEV_CPU_SET_ADDR_AFTER_STATUS

◆ usbdev_ep_buf_t

◆ USBDEV_NUM_ENDPOINTS

Typedef Documentation

◆ usbdev_driver_t

◆ usbdev_ep_event_cb_t

◆ usbdev_ep_t

◆ usbdev_event_cb_t

◆ usbdev_t

Enumeration Type Documentation

◆ usbdev_event_t

Function Documentation

◆ usbdev_ep0_stall()

◆ usbdev_ep_esr()

◆ usbdev_ep_get()

◆ usbdev_ep_init()

◆ usbdev_ep_set()

◆ usbdev_ep_stall()

◆ usbdev_ep_xmit()

◆ usbdev_esr()

◆ usbdev_get()

◆ usbdev_get_ctx()

◆ usbdev_init()

◆ usbdev_init_lowlevel()

◆ usbdev_new_ep()

◆ usbdev_set()