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 descriptor formatter functions
 

Files

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

Data Structures

struct  usbus_string
 USBUS string type. More...
 
struct  usbus_hdr_gen_funcs_t
 USBUS header generator function pointers. More...
 
struct  usbus_hdr_gen
 USBUS header generator. More...
 
struct  usbus_endpoint
 USBUS endpoint context. 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_STACKSIZE   (THREAD_STACKSIZE_DEFAULT)
 USBUS thread stack size.
 
#define USBUS_PRIO   (THREAD_PRIORITY_MAIN - 6)
 USBUS thread priority.
 
#define USBUS_TNAME   "usbus"
 USBUS thread name.
 
#define USBUS_AUTO_ATTACH   (1)
 USBUS auto attach setting. More...
 
#define USBUS_EP0_SIZE   64
 USBUS endpoint 0 buffer size. More...
 

Typedefs

typedef struct usbus_string usbus_string_t
 USBUS string type.
 
typedef struct usbus usbus_t
 USBUS context forward declaration.
 
typedef struct usbus_handler usbus_handler_t
 USBUS event handler forward declaration.
 
typedef struct usbus_hdr_gen usbus_hdr_gen_t
 USBUS header generator. More...
 
typedef struct usbus_endpoint usbus_endpoint_t
 USBUS endpoint context.
 
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_setuprq_state_t {
  USBUS_SETUPRQ_READY, USBUS_SETUPRQ_INDATA, USBUS_SETUPRQ_OUTACK, USBUS_SETUPRQ_OUTDATA,
  USBUS_SETUPRQ_INACK
}
 USBUS setup request state machine. More...
 
enum  usbus_hdr_len_type_t { USBUS_HDR_LEN_FIXED, USBUS_HDR_LEN_FUNC }
 Header 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...
 
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_hdr_gen_t *hdr_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...
 
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_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...
 

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
 
#define USBUS_THREAD_FLAG_USBDEV_EP   (0x04)
 One or more endpoints requires servicing.
 

USBUS handler subscription flags

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

Macro Definition Documentation

◆ USBUS_AUTO_ATTACH

#define USBUS_AUTO_ATTACH   (1)

USBUS auto attach setting.

When set, the USBUS thread will automatically enable the USB pull-up resistor after initializing the thread. This will signal to the host that the USB peripheral is ready for use.

Definition at line 70 of file usbus.h.

◆ USBUS_EP0_SIZE

#define USBUS_EP0_SIZE   64

USBUS endpoint 0 buffer size.

This configures the buffer size of the control endpoint. Unless you transfer large amount of data often over the control endpoint, a minimal size should be sufficient

Definition at line 81 of file usbus.h.

Typedef Documentation

◆ usbus_hdr_gen_t

USBUS header generator.

The functions are called to allow custom modules to define their own headers 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 headers

◆ usbus_interface_alt_t

USBUS interface alternative setting.

Used for specifying alternative interfaces for an usbus_interface_t

Enumeration Type Documentation

◆ usbus_event_transfer_t

USB endpoint transfer status events.

Enumerator
USBUS_EVENT_TRANSFER_COMPLETE 

Transfer succesfully completed.

USBUS_EVENT_TRANSFER_FAIL 

Transfer nack replied by peripheral.

USBUS_EVENT_TRANSFER_STALL 

Transfer stall replied by peripheral.

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

◆ usbus_hdr_len_type_t

Header length types for USB descriptor generators.

Enumerator
USBUS_HDR_LEN_FIXED 

Header always generates a fixed length.

USBUS_HDR_LEN_FUNC 

Header length is calculated by a function.

Definition at line 175 of file usbus.h.

◆ usbus_setuprq_state_t

USBUS setup request state machine.

Enumerator
USBUS_SETUPRQ_READY 

Ready for new setup request.

USBUS_SETUPRQ_INDATA 

Request received with expected DATA IN stage.

USBUS_SETUPRQ_OUTACK 

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

USBUS_SETUPRQ_OUTDATA 

Data OUT expected.

USBUS_SETUPRQ_INACK 

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

Definition at line 143 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 132 of file usbus.h.

Function Documentation

◆ usbus_add_conf_descriptor()

void usbus_add_conf_descriptor ( usbus_t usbus,
usbus_hdr_gen_t hdr_gen 
)

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

Parameters
[in]usbusUSBUS context
[in]hdr_genHeader 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_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 486 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 474 of file usbus.h.

◆ 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 380 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 523 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 509 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 497 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_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