USBUS device and endpoint manager

USBUS (Universal Serial Bus Unified Stack), USB device management interface. More...

Detailed Description

USBUS (Universal Serial Bus Unified Stack), USB device management interface.

Modules

 USBUS compile time configurations
 
 USBUS descriptor formatter functions
 

Files

file  usbus.h
 USBUS basic interface.
 
file  control.h
 USBUS control endpoint module.
 

Data Structures

struct  usbus_string
 USBUS string type. More...
 
struct  usbus_descr_gen_funcs_t
 USBUS descriptor generator function pointers. More...
 
struct  usbus_descr_gen
 USBUS descriptor generator. More...
 
struct  usbus_endpoint
 USBUS endpoint context. More...
 
struct  usbus_urb
 USBUS USB request/response block. More...
 
struct  usbus_interface_alt
 USBUS interface alternative setting. More...
 
struct  usbus_interface
 USBUS interface. More...
 
struct  usbus_handler_driver
 USBUS event handler function pointers. More...
 
struct  usbus_handler
 USBUS handler struct. More...
 
struct  usbus
 USBUS context struct. More...
 

Macros

#define USBUS_TNAME   "usbus"
 USBUS thread name. More...
 

Typedefs

typedef struct usbus_string usbus_string_t
 USBUS string type.
 
typedef struct usbus usbus_t
 USBUS context forward declaration. More...
 
typedef struct usbus_handler usbus_handler_t
 USBUS event handler forward declaration. More...
 
typedef struct usbus_descr_gen usbus_descr_gen_t
 USBUS descriptor generator. More...
 
typedef struct usbus_endpoint usbus_endpoint_t
 USBUS endpoint context.
 
typedef struct usbus_urb usbus_urb_t
 USBUS USB request/response block.
 
typedef struct usbus_interface_alt usbus_interface_alt_t
 USBUS interface alternative setting. More...
 
typedef struct usbus_interface usbus_interface_t
 USBUS interface.
 
typedef struct usbus_handler_driver usbus_handler_driver_t
 USBUS event handler function pointers.
 

Enumerations

enum  usbus_event_usb_t { USBUS_EVENT_USB_RESET , USBUS_EVENT_USB_SOF , USBUS_EVENT_USB_SUSPEND , USBUS_EVENT_USB_RESUME }
 USB handler events. More...
 
enum  usbus_event_transfer_t { USBUS_EVENT_TRANSFER_COMPLETE , USBUS_EVENT_TRANSFER_FAIL , USBUS_EVENT_TRANSFER_STALL }
 USB endpoint transfer status events. More...
 
enum  usbus_state_t {
  USBUS_STATE_DISCONNECT , USBUS_STATE_RESET , USBUS_STATE_ADDR , USBUS_STATE_CONFIGURED ,
  USBUS_STATE_SUSPEND
}
 state machine states for the global USBUS thread More...
 
enum  usbus_control_request_state_t {
  USBUS_CONTROL_REQUEST_STATE_READY , USBUS_CONTROL_REQUEST_STATE_INDATA , USBUS_CONTROL_REQUEST_STATE_OUTACK , USBUS_CONTROL_REQUEST_STATE_OUTDATA ,
  USBUS_CONTROL_REQUEST_STATE_INACK
}
 USBUS control request state machine. More...
 
enum  usbus_descr_len_type_t { USBUS_DESCR_LEN_FIXED , USBUS_DESCR_LEN_FUNC }
 descriptor length types for USB descriptor generators More...
 

Functions

static void usbus_event_post (usbus_t *usbus, event_t *event)
 Submit an event to the usbus thread. More...
 
uint16_t usbus_add_string_descriptor (usbus_t *usbus, usbus_string_t *desc, const char *str)
 Add a string descriptor to the USBUS thread context. More...
 
uint16_t usbus_add_interface (usbus_t *usbus, usbus_interface_t *iface)
 Add an interface to the USBUS thread context. More...
 
void usbus_add_interface_alt (usbus_interface_t *iface, usbus_interface_alt_t *alt)
 Add alternate settings to a given interface. More...
 
usbus_endpoint_tusbus_interface_find_endpoint (usbus_interface_t *interface, usb_ep_type_t type, usb_ep_dir_t dir)
 Find an endpoint from an interface based on the endpoint properties. More...
 
usbus_endpoint_tusbus_add_endpoint (usbus_t *usbus, usbus_interface_t *iface, usb_ep_type_t type, usb_ep_dir_t dir, size_t len)
 Add an endpoint to the specified interface. More...
 
void usbus_add_conf_descriptor (usbus_t *usbus, usbus_descr_gen_t *descr_gen)
 Add a generator for generating additional top level USB descriptor content. More...
 
void usbus_register_event_handler (usbus_t *usbus, usbus_handler_t *handler)
 Add an event handler to the USBUS context. More...
 
void usbus_init (usbus_t *usbus, usbdev_t *usbdev)
 Initialize an USBUS context. More...
 
size_t usbus_max_bulk_endpoint_size (usbus_t *usbus)
 Get the maximum supported bulk endpoint transfer size based on the enumeration speed. More...
 
size_t usbus_max_interrupt_endpoint_size (usbus_t *usbus)
 Get the maximum supported interrupt endpoint transfer size based on the enumeration speed. More...
 
void usbus_create (char *stack, int stacksize, char priority, const char *name, usbus_t *usbus)
 Create and start the USBUS thread. More...
 
static void usbus_urb_init (usbus_urb_t *urb, uint8_t *buf, size_t len, uint32_t flags)
 Initialize a new URB. More...
 
void usbus_urb_submit (usbus_t *usbus, usbus_endpoint_t *endpoint, usbus_urb_t *urb)
 Submit an URB to an endpoint. More...
 
int usbus_urb_cancel (usbus_t *usbus, usbus_endpoint_t *endpoint, usbus_urb_t *urb)
 Cancel and already queued URB. More...
 
void usbus_endpoint_halt (usbus_endpoint_t *ep)
 Set the halt condition on an endpoint. More...
 
void usbus_endpoint_clear_halt (usbus_endpoint_t *ep)
 Clear the halt condition on an endpoint. More...
 
static void usbus_enable_endpoint (usbus_endpoint_t *ep)
 Enable an endpoint. More...
 
static void usbus_disable_endpoint (usbus_endpoint_t *ep)
 Disable an endpoint. More...
 
static void usbus_handler_set_flag (usbus_handler_t *handler, uint32_t flag)
 enable a specific handler flag More...
 
static void usbus_handler_remove_flag (usbus_handler_t *handler, uint32_t flag)
 disable a specific handler flag More...
 
static bool usbus_handler_isset_flag (usbus_handler_t *handler, uint32_t flag)
 check if a specific handler flag is set More...
 
static void usbus_urb_set_flag (usbus_urb_t *urb, uint32_t flag)
 enable an URB flag More...
 
static void usbus_urb_remove_flag (usbus_urb_t *urb, uint32_t flag)
 disable an URB flag More...
 
static bool usbus_urb_isset_flag (usbus_urb_t *urb, uint32_t flag)
 check if an URB flag is set More...
 

USBUS thread flags

Thread flags used by the USBUS thread.

THREAD_FLAG_EVENT is also used, but defined elsewhere

#define USBUS_THREAD_FLAG_USBDEV   (0x02)
 usbdev esr needs handling More...
 
#define USBUS_THREAD_FLAG_USBDEV_EP   (0x04)
 One or more endpoints requires servicing. More...
 

USBUS handler subscription flags

#define USBUS_HANDLER_FLAG_RESET   (0x0001)
 Report reset event. More...
 
#define USBUS_HANDLER_FLAG_SOF   (0x0002)
 Report SOF events. More...
 
#define USBUS_HANDLER_FLAG_SUSPEND   (0x0004)
 Report suspend events. More...
 
#define USBUS_HANDLER_FLAG_RESUME   (0x0008)
 Report resume from suspend. More...
 
#define USBUS_HANDLER_FLAG_TR_STALL   (0x0020)
 Report transfer stall complete. More...
 

USBUS URB flags

#define USBUS_URB_FLAG_AUTO_ZLP   (0x0001)
 End the URB with a zero length packet if the URB is a full number of USB transfers in length. More...
 
#define USBUS_URB_FLAG_NEEDS_ZLP   (0x1000)
 URB needs a zero length packet and it is requested. More...
 
#define USBUS_URB_FLAG_CANCELLED   (0x2000)
 URB must be cancelled after the next finished xmit. More...
 

Macro Definition Documentation

◆ USBUS_HANDLER_FLAG_RESET

#define USBUS_HANDLER_FLAG_RESET   (0x0001)

Report reset event.

Definition at line 131 of file usbus.h.

◆ USBUS_HANDLER_FLAG_RESUME

#define USBUS_HANDLER_FLAG_RESUME   (0x0008)

Report resume from suspend.

Definition at line 134 of file usbus.h.

◆ USBUS_HANDLER_FLAG_SOF

#define USBUS_HANDLER_FLAG_SOF   (0x0002)

Report SOF events.

Definition at line 132 of file usbus.h.

◆ USBUS_HANDLER_FLAG_SUSPEND

#define USBUS_HANDLER_FLAG_SUSPEND   (0x0004)

Report suspend events.

Definition at line 133 of file usbus.h.

◆ USBUS_HANDLER_FLAG_TR_STALL

#define USBUS_HANDLER_FLAG_TR_STALL   (0x0020)

Report transfer stall complete.

Definition at line 135 of file usbus.h.

◆ USBUS_THREAD_FLAG_USBDEV

#define USBUS_THREAD_FLAG_USBDEV   (0x02)

usbdev esr needs handling

Definition at line 121 of file usbus.h.

◆ USBUS_THREAD_FLAG_USBDEV_EP

#define USBUS_THREAD_FLAG_USBDEV_EP   (0x04)

One or more endpoints requires servicing.

Definition at line 123 of file usbus.h.

◆ USBUS_TNAME

#define USBUS_TNAME   "usbus"

USBUS thread name.

Definition at line 112 of file usbus.h.

◆ USBUS_URB_FLAG_AUTO_ZLP

#define USBUS_URB_FLAG_AUTO_ZLP   (0x0001)

End the URB with a zero length packet if the URB is a full number of USB transfers in length.

Definition at line 148 of file usbus.h.

◆ USBUS_URB_FLAG_CANCELLED

#define USBUS_URB_FLAG_CANCELLED   (0x2000)

URB must be cancelled after the next finished xmit.

Definition at line 160 of file usbus.h.

◆ USBUS_URB_FLAG_NEEDS_ZLP

#define USBUS_URB_FLAG_NEEDS_ZLP   (0x1000)

URB needs a zero length packet and it is requested.

Definition at line 154 of file usbus.h.

Typedef Documentation

◆ usbus_descr_gen_t

USBUS descriptor generator.

The functions are called to allow custom modules to define their own descriptors in addition to the USB descriptor. The top level (usbus_t), the interface (usbus_interface_t), interface alternative settings (usbus_interface_alt_t) and endpoints (usbus_endpoint_t) allow for generating additional descriptors

◆ usbus_handler_t

USBUS event handler forward declaration.

Definition at line 224 of file usbus.h.

◆ usbus_interface_alt_t

USBUS interface alternative setting.

Used for specifying alternative interfaces for an usbus_interface_t

◆ usbus_t

typedef struct usbus usbus_t

USBUS context forward declaration.

Definition at line 219 of file usbus.h.

Enumeration Type Documentation

◆ usbus_control_request_state_t

USBUS control request state machine.

Enumerator
USBUS_CONTROL_REQUEST_STATE_READY 

Ready for new control request.

USBUS_CONTROL_REQUEST_STATE_INDATA 

Request received with expected DATA IN stage.

USBUS_CONTROL_REQUEST_STATE_OUTACK 

Expecting a zero-length ack OUT request from the host.

USBUS_CONTROL_REQUEST_STATE_OUTDATA 

Data OUT expected.

USBUS_CONTROL_REQUEST_STATE_INACK 

Expecting a zero-length ack IN request from the host.

Definition at line 196 of file usbus.h.

◆ usbus_descr_len_type_t

descriptor length types for USB descriptor generators

Enumerator
USBUS_DESCR_LEN_FIXED 

Descriptor always generates a fixed length.

USBUS_DESCR_LEN_FUNC 

Descriptor length is calculated by a function.

Definition at line 229 of file usbus.h.

◆ usbus_event_transfer_t

USB endpoint transfer status events.

Enumerator
USBUS_EVENT_TRANSFER_COMPLETE 

Transfer successfully completed.

USBUS_EVENT_TRANSFER_FAIL 

Transfer nack replied by peripheral.

USBUS_EVENT_TRANSFER_STALL 

Transfer stall replied by peripheral.

Definition at line 176 of file usbus.h.

◆ usbus_event_usb_t

USB handler events.

Enumerator
USBUS_EVENT_USB_RESET 

USB reset event

USBUS_EVENT_USB_SOF 

USB start of frame received

USBUS_EVENT_USB_SUSPEND 

USB suspend condition detected.

USBUS_EVENT_USB_RESUME 

USB resume condition detected

Definition at line 166 of file usbus.h.

◆ usbus_state_t

state machine states for the global USBUS thread

Enumerator
USBUS_STATE_DISCONNECT 

Device is disconnected from the host.

USBUS_STATE_RESET 

Reset condition received.

USBUS_STATE_ADDR 

Address configured.

USBUS_STATE_CONFIGURED 

Peripheral is configured.

USBUS_STATE_SUSPEND 

Peripheral is suspended by the host.

Definition at line 185 of file usbus.h.

Function Documentation

◆ usbus_add_conf_descriptor()

void usbus_add_conf_descriptor ( usbus_t usbus,
usbus_descr_gen_t descr_gen 
)

Add a generator for generating additional top level USB descriptor content.

Parameters
[in]usbusUSBUS context
[in]descr_gendescriptor generator to add

◆ usbus_add_endpoint()

usbus_endpoint_t * usbus_add_endpoint ( usbus_t usbus,
usbus_interface_t iface,
usb_ep_type_t  type,
usb_ep_dir_t  dir,
size_t  len 
)

Add an endpoint to the specified interface.

An usbdev_ep_t is requested from the low level peripheral matching the type, direction and buffer length.

Parameters
[in]usbusUSBUS context
[in]ifaceUSB interface to add the endpoint to
[in]typeUSB endpoint type
[in]dirUSB endpoint direction
[in]lenBuffer space for the endpoint to allocate
Returns
Pointer to the endpoint struct
NULL when no endpoint available

◆ usbus_add_interface()

uint16_t usbus_add_interface ( usbus_t usbus,
usbus_interface_t iface 
)

Add an interface to the USBUS thread context.

Parameters
[in]usbusUSBUS context
[in]ifaceUSB interface to add
Returns
interface index

◆ usbus_add_interface_alt()

void usbus_add_interface_alt ( usbus_interface_t iface,
usbus_interface_alt_t alt 
)

Add alternate settings to a given interface.

Parameters
[in]ifaceUSB interface
[in]altalternate settings interface to add

◆ usbus_add_string_descriptor()

uint16_t usbus_add_string_descriptor ( usbus_t usbus,
usbus_string_t desc,
const char *  str 
)

Add a string descriptor to the USBUS thread context.

Parameters
[in]usbusUSBUS context
[in]descstring descriptor context
[in]strC string to use
Returns
Index of the string descriptor

◆ usbus_create()

void usbus_create ( char *  stack,
int  stacksize,
char  priority,
const char *  name,
usbus_t usbus 
)

Create and start the USBUS thread.

Parameters
[in]stackThe stack for the USBUS thread.
[in]stacksizeSize of stack.
[in]priorityPriority for the USBUS thread.
[in]nameName for the USBUS thread May be NULL.
[in]usbuscontext to start the thread for

◆ usbus_disable_endpoint()

static void usbus_disable_endpoint ( usbus_endpoint_t ep)
inlinestatic

Disable an endpoint.

Note
must only be used before the usb peripheral is attached to the host
Parameters
[in]ependpoint to disable

Definition at line 708 of file usbus.h.

◆ usbus_enable_endpoint()

static void usbus_enable_endpoint ( usbus_endpoint_t ep)
inlinestatic

Enable an endpoint.

Note
must only be used before the usb peripheral is attached to the host
Parameters
[in]ependpoint to enable

Definition at line 696 of file usbus.h.

◆ usbus_endpoint_clear_halt()

void usbus_endpoint_clear_halt ( usbus_endpoint_t ep)

Clear the halt condition on an endpoint.

Note
Must only be used when the endpoint is halted and when the host issues a SetInterface request on the interface containing the endpoint

◆ usbus_endpoint_halt()

void usbus_endpoint_halt ( usbus_endpoint_t ep)

Set the halt condition on an endpoint.

The endpoint will respond with stall to all packets and must explicitly be cleared by the host by clearing the halt condition or switching interfaces

◆ usbus_event_post()

static void usbus_event_post ( usbus_t usbus,
event_t event 
)
inlinestatic

Submit an event to the usbus thread.

Parameters
usbusUSBUS context
eventevent to post

Definition at line 484 of file usbus.h.

◆ usbus_handler_isset_flag()

static bool usbus_handler_isset_flag ( usbus_handler_t handler,
uint32_t  flag 
)
inlinestatic

check if a specific handler flag is set

Parameters
[in]handlerhandler to check for flag
[in]flagflag to check
Returns
true if the flag is set for this handler

Definition at line 745 of file usbus.h.

◆ usbus_handler_remove_flag()

static void usbus_handler_remove_flag ( usbus_handler_t handler,
uint32_t  flag 
)
inlinestatic

disable a specific handler flag

Parameters
[in]handlerhandler to disable the flag for
[in]flagflag to disable

Definition at line 731 of file usbus.h.

◆ usbus_handler_set_flag()

static void usbus_handler_set_flag ( usbus_handler_t handler,
uint32_t  flag 
)
inlinestatic

enable a specific handler flag

Parameters
[in]handlerhandler to enable the flag for
[in]flagflag to enable

Definition at line 719 of file usbus.h.

◆ usbus_init()

void usbus_init ( usbus_t usbus,
usbdev_t usbdev 
)

Initialize an USBUS context.

Parameters
[in]usbuscontext to initialize
[in]usbdevusbdev peripheral to use by USBUS

◆ usbus_interface_find_endpoint()

usbus_endpoint_t * usbus_interface_find_endpoint ( usbus_interface_t interface,
usb_ep_type_t  type,
usb_ep_dir_t  dir 
)

Find an endpoint from an interface based on the endpoint properties.

This iterates over the endpoints in an interface and will return the first endpoint from the interface matching the type and dir. It will return NULL when no matching endpoint is found.

Parameters
[in]interfaceinterface to look in
[in]typeendpoint type to match
[in]direndpoint direction to match
Returns
ptr to the first matching endpoint
NULL when no endpoint is found

◆ usbus_max_bulk_endpoint_size()

size_t usbus_max_bulk_endpoint_size ( usbus_t usbus)

Get the maximum supported bulk endpoint transfer size based on the enumeration speed.

Should only be called after enumeration has finished by the peripheral. Calling this in response to the USBUS_EVENT_USB_RESET is valid

◆ usbus_max_interrupt_endpoint_size()

size_t usbus_max_interrupt_endpoint_size ( usbus_t usbus)

Get the maximum supported interrupt endpoint transfer size based on the enumeration speed.

Should only be called after enumeration has finished by the peripheral. Calling this in response to the USBUS_EVENT_USB_RESET is valid

◆ usbus_register_event_handler()

void usbus_register_event_handler ( usbus_t usbus,
usbus_handler_t handler 
)

Add an event handler to the USBUS context.

The handler must also belong to an interface (usbus_interface_t::handler must point to handler) for transfer event callbacks to work.

Parameters
[in]usbusUSBUS context
[in]handlerevent handler to register

◆ usbus_urb_cancel()

int usbus_urb_cancel ( usbus_t usbus,
usbus_endpoint_t endpoint,
usbus_urb_t urb 
)

Cancel and already queued URB.

The URB will be cancelled after the next transmission if the URB is already partially completed. It is up to the handler code to gracefully handle the partially aborted transfer on the endpoint pipe.

The callback will be called if the URB was already started and cancelled while (partially) transferred

Note
Requires the usbus_urb module.
Parameters
[in]usbusUSBUS context
[in]endpointUSBUS endpoint the URB is queued to
[in]urbURB to cancel
Returns
0 if the URB is partially completed 1 if the URB was not yet started -1 if the URB was not found in the endpoint queue

◆ usbus_urb_init()

static void usbus_urb_init ( usbus_urb_t urb,
uint8_t *  buf,
size_t  len,
uint32_t  flags 
)
inlinestatic

Initialize a new URB.

Must be called before submitting an URB to an endpoint.

Note
When using this for OUT endpoints, the buffer size and the len argument must allow for a whole number of max length transfers.
Requires the usbus_urb module.
Parameters
[in]urbURB to submit
[in]bufBuffer to store or transmit the data from
[in]lenLength of buf in bytes
[in]flagsFlags to set for the URB such as USBUS_URB_FLAG_AUTO_ZLP

Definition at line 629 of file usbus.h.

◆ usbus_urb_isset_flag()

static bool usbus_urb_isset_flag ( usbus_urb_t urb,
uint32_t  flag 
)
inlinestatic

check if an URB flag is set

Parameters
[in]urbURB to check for flag
[in]flagflag to check
Returns
true if the flag is set for this URB

Definition at line 783 of file usbus.h.

◆ usbus_urb_remove_flag()

static void usbus_urb_remove_flag ( usbus_urb_t urb,
uint32_t  flag 
)
inlinestatic

disable an URB flag

Parameters
[in]urbURB to disable the flag for
[in]flagflag to disable

Definition at line 769 of file usbus.h.

◆ usbus_urb_set_flag()

static void usbus_urb_set_flag ( usbus_urb_t urb,
uint32_t  flag 
)
inlinestatic

enable an URB flag

Parameters
[in]urbURB to enable the flag for
[in]flagflag to enable

Definition at line 757 of file usbus.h.

◆ usbus_urb_submit()

void usbus_urb_submit ( usbus_t usbus,
usbus_endpoint_t endpoint,
usbus_urb_t urb 
)

Submit an URB to an endpoint.

Note
Requires the usbus_urb module.
Parameters
[in]usbusUSBUS context
[in]endpointUSBUS endpoint the URB is queued to
[in]urbURB to submit