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	control.h
	USBUS control endpoint module.

file	usbus.h
	USBUS basic interface.

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_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. 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_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...

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. More...

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

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.

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

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 161 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 194 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 141 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 131 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 150 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_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 549 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 537 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

usbus	USBUS context
event	event to post

Definition at line 425 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 586 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 572 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 560 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_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

Detailed Description

Modules

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

USBUS thread flags

USBUS handler subscription flags

Typedef Documentation

◆ usbus_descr_gen_t

◆ usbus_interface_alt_t

Enumeration Type Documentation

◆ usbus_control_request_state_t

◆ usbus_descr_len_type_t

◆ usbus_event_transfer_t

◆ usbus_event_usb_t

◆ usbus_state_t

Function Documentation

◆ usbus_add_conf_descriptor()

◆ usbus_add_endpoint()

◆ usbus_add_interface()

◆ usbus_add_string_descriptor()

◆ usbus_create()

◆ usbus_disable_endpoint()

◆ usbus_enable_endpoint()

◆ usbus_event_post()

◆ usbus_handler_isset_flag()

◆ usbus_handler_remove_flag()

◆ usbus_handler_set_flag()

◆ usbus_init()

◆ usbus_interface_find_endpoint()

◆ usbus_register_event_handler()