usbdev - USB Device Driver API

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

  1. Support for multiple instances on a single board
  2. 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.

Data transmission is done by requesting the endpoint with a max packet size. Memory for this buffer is allocated from dedicated memory of the MCU USB peripheral or from a buffer allocated by the peripheral specific usbdev struct. Received data from the host ends up at this buffer automatically by the low level drivers. Signalling that the data at the specified address is ready to be reused is done with the usbdev_ep_ready function by supplying a size of 0 for the len argument.

For transmitting data back to the host, a similar approach is used. The data to be transmitted is written to the specified address and the usbdev_ep_ready function is called with the size of the data as len argument.

This approach of setting the address and only indicating new data available is done to allow the low level USB peripheral to use DMA to transfer the data from and to the MCU memory.

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.
 

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_EP_BUF_SPACE   1024
 Statically allocated buffer space for endpoints. More...
 
#define USBDEV_NUM_ENDPOINTS   8
 Number of USB IN and OUT endpoints allocated. More...
 

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. More...
 
typedef void(* usbdev_ep_event_cb_t) (usbdev_ep_t *ep, usbdev_event_t event)
 Event callback for signaling endpoint events to upper layers. More...
 
typedef struct usbdev_driver usbdev_driver_t
 usbdev driver functions More...
 

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, USBDEV_EVENT_TR_FAIL
}
 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. More...
 
usbdev_tusbdev_get_ctx (unsigned num)
 Retrieve usbdev context from the peripheral. More...
 
static void usbdev_init (usbdev_t *dev)
 Initialize the USB peripheral device. More...
 
static usbdev_ep_tusbdev_new_ep (usbdev_t *dev, usb_ep_type_t type, usb_ep_dir_t dir, size_t buf_len)
 Retrieve an USB endpoint of the specified type. More...
 
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. More...
 
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. More...
 
static void usbdev_esr (usbdev_t *dev)
 a driver's user-space event service handler More...
 
static void usbdev_ep_init (usbdev_ep_t *ep)
 Initialize the USB endpoint. More...
 
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. More...
 
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. More...
 
static void usbdev_ep_esr (usbdev_ep_t *ep)
 an endpoint's user-space event handler More...
 
static int usbdev_ep_ready (usbdev_ep_t *ep, size_t len)
 Signal data buffer ready for data transmission. More...
 

Macro Definition Documentation

◆ USBDEV_EP_BUF_SPACE

#define USBDEV_EP_BUF_SPACE   1024

Statically allocated buffer space for endpoints.

When the device doesn't have dedicated memory for endpoint buffers, a buffer of this size is allocated to contain the endpoint buffers. Only needs to be as big as the total buffer space required by all endpoints

Definition at line 103 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 113 of file usbdev.h.

Typedef Documentation

◆ 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]epusbdev endpoint context
[in]eventtype of the event

Definition at line 211 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]usbdevusbdev context
[in]eventtype of the event

Definition at line 203 of file usbdev.h.

Enumeration Type Documentation

◆ 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 occured.

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 occured 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

USBDEV_EVENT_TR_FAIL 

Transaction fail event.

An endpoint should emit this event after a nack reply to the host.

Definition at line 120 of file usbdev.h.

Function Documentation

◆ 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]epUSB endpoint descriptor to service

Definition at line 555 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]epUSB endpoint descriptor
[in]optoption type
[out]valuepointer to store the option's value in
[in]max_lenmaximum number of byte that fit into value
Returns
number of bytes written to value
< 0 on error

Definition at line 513 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]epUSB endpoint descriptor

Definition at line 490 of file usbdev.h.

◆ usbdev_ep_ready()

static int usbdev_ep_ready ( usbdev_ep_t ep,
size_t  len 
)
inlinestatic

Signal data buffer ready for data transmission.

See also
usbdev_driver_t::ready
Precondition
(ep != NULL)
(ep->dev != NULL)
Parameters
[in]epUSB endpoint descriptor
[in]lenlength of the data to be transmitted

Definition at line 573 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]epUSB endpoint descriptor
[in]optoption type
[in]valuepointer to the value
[in]value_lenthe length of value
Returns
number of bytes used from value
< 0 on error

Definition at line 537 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]devUSB device descriptor

Definition at line 474 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]devUSB device descriptor
[in]optoption type
[out]valuepointer to store the option's value in
[in]max_lenmaximal amount of byte that fit into value
Returns
number of bytes written to value
< 0 on error 0

Definition at line 436 of file usbdev.h.

◆ usbdev_get_ctx()

usbdev_t* usbdev_get_ctx ( unsigned  num)

Retrieve usbdev context from the peripheral.

Parameters
numusbdev 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
devusb device to initialize

Definition at line 393 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  buf_len 
)
inlinestatic

Retrieve an USB endpoint of the specified type.

See also
usbdev_driver_t::new_ep
Precondition
(dev != NULL)
Parameters
[in]devUSB device descriptor
[in]typeUSB endpoint type
[in]dirUSB endpoint direction
[in]buf_lenoptimal USB endpoint buffer size
Returns
ptr to the new USB endpoint descriptor
NULL on error

Definition at line 414 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]devUSB device descriptor
[in]optoption type
[in]valuevalue to set
[in]value_lenthe length of value
Returns
number of bytes used from value
< 0 on error

Definition at line 458 of file usbdev.h.