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.

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_descr_gen	usbus_descr_gen_t
	USBUS descriptor generator.
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.
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.
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.
uint16_t	usbus_add_interface (usbus_t *usbus, usbus_interface_t *iface)
	Add an interface to the USBUS thread context.
void	usbus_add_interface_alt (usbus_interface_t *iface, usbus_interface_alt_t *alt)
	Add alternate settings to a given interface.
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.
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.
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.
void	usbus_register_event_handler (usbus_t *usbus, usbus_handler_t *handler)
	Add an event handler to the USBUS context.
void	usbus_init (usbus_t *usbus, usbdev_t *usbdev)
	Initialize an USBUS context.
size_t	usbus_max_bulk_endpoint_size (usbus_t *usbus)
	Get the maximum supported bulk endpoint transfer size based on the enumeration speed.
size_t	usbus_max_interrupt_endpoint_size (usbus_t *usbus)
	Get the maximum supported interrupt endpoint transfer size based on the enumeration speed.
void	usbus_create (char *stack, int stacksize, char priority, const char *name, usbus_t *usbus)
	Create and start the USBUS thread.
static void	usbus_urb_init (usbus_urb_t *urb, uint8_t *buf, size_t len, uint32_t flags)
	Initialize a new URB.
void	usbus_urb_submit (usbus_t *usbus, usbus_endpoint_t *endpoint, usbus_urb_t *urb)
	Submit an URB to an endpoint.
int	usbus_urb_cancel (usbus_t *usbus, usbus_endpoint_t *endpoint, usbus_urb_t *urb)
	Cancel and already queued URB.
void	usbus_endpoint_halt (usbus_endpoint_t *ep)
	Set the halt condition on an endpoint.
void	usbus_endpoint_clear_halt (usbus_endpoint_t *ep)
	Clear the halt condition on an endpoint.
static void	usbus_enable_endpoint (usbus_endpoint_t *ep)
	Enable an endpoint.
static void	usbus_disable_endpoint (usbus_endpoint_t *ep)
	Disable an endpoint.
static void	usbus_handler_set_flag (usbus_handler_t *handler, uint32_t flag)
	enable a specific handler flag
static void	usbus_handler_remove_flag (usbus_handler_t *handler, uint32_t flag)
	disable a specific handler flag
static bool	usbus_handler_isset_flag (usbus_handler_t *handler, uint32_t flag)
	check if a specific handler flag is set
static void	usbus_urb_set_flag (usbus_urb_t *urb, uint32_t flag)
	enable an URB flag
static void	usbus_urb_remove_flag (usbus_urb_t *urb, uint32_t flag)
	disable an URB flag
static bool	usbus_urb_isset_flag (usbus_urb_t *urb, uint32_t flag)
	check if an URB flag is set

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_STALL   (0x0020)
	Report transfer stall complete.

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.
#define	USBUS_URB_FLAG_NEEDS_ZLP   (0x1000)
	URB needs a zero length packet and it is requested.
#define	USBUS_URB_FLAG_CANCELLED   (0x2000)
	URB must be cancelled after the next finished xmit.

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

typedef struct usbus_descr_gen 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

typedef struct usbus_handler usbus_handler_t

USBUS event handler forward declaration.

Definition at line 224 of file usbus.h.

usbus_interface_alt_t

typedef struct usbus_interface_alt 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

enum 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

enum 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

enum 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

enum 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

enum 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]	usbus	USBUS context
[in]	descr_gen	descriptor 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]	usbus	USBUS context
[in]	iface	USB interface to add the endpoint to
[in]	type	USB endpoint type
[in]	dir	USB endpoint direction
[in]	len	Buffer 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]	usbus	USBUS context
[in]	iface	USB 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]	iface	USB interface
[in]	alt	alternate 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]	usbus	USBUS context
[in]	desc	string descriptor context
[in]	str	C 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]	stack	The stack for the USBUS thread.
[in]	stacksize	Size of stack.
[in]	priority	Priority for the USBUS thread.
[in]	name	Name for the USBUS thread May be NULL.
[in]	usbus	context 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]

ep

endpoint 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]

ep

endpoint 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

usbus	USBUS context
event	event 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]	handler	handler to check for flag
[in]	flag	flag 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]	handler	handler to disable the flag for
[in]	flag	flag 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]	handler	handler to enable the flag for
[in]	flag	flag 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]	usbus	context to initialize
[in]	usbdev	usbdev 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]	interface	interface to look in
[in]	type	endpoint type to match
[in]	dir	endpoint 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]	usbus	USBUS context
[in]	handler	event 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]	usbus	USBUS context
[in]	endpoint	USBUS endpoint the URB is queued to
[in]	urb	URB 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]	urb	URB to submit
[in]	buf	Buffer to store or transmit the data from
[in]	len	Length of buf in bytes
[in]	flags	Flags 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]	urb	URB to check for flag
[in]	flag	flag 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]	urb	URB to disable the flag for
[in]	flag	flag 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]	urb	URB to enable the flag for
[in]	flag	flag 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]	usbus	USBUS context
[in]	endpoint	USBUS endpoint the URB is queued to
[in]	urb	URB to submit