include/usb/udc.h File Reference

USB Device Controller interface. More...

#include <bitops.h>
#include <usb/usb_protocol.h>
#include <app/config_usb.h>

Include dependency graph for udc.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct udc

Typedefs

typedef int usb_ep_id_t

Enumerations

enum usb_device_flag { USB_DEV_IS_ENABLED, USB_DEV_AUTOATTACH, USB_DEV_HAS_POWER, USB_DEV_IS_SUSPENDED }

Bit definitions for udc::flags. More...

Functions

static bool udc_is_high_speed (struct udc *udc)

Test whether the USB Device Controller is running at high speed.

static bool udc_is_full_speed (struct udc *udc)

Test whether the USB Device Controller is running at full speed.

static bool udc_is_low_speed (struct udc *udc)

Test whether the USB Device Controller is running at low speed.

static enum usb_device_state udc_state (struct udc *udc)

struct udc * udc_init (void)

Initialize the USB Device Controller.

void udc_attach (struct udc *udc)

Attach udc to the bus when possible.

void udc_detach (struct udc *udc)

Detach udc from the bus.

usb_ep_id_t udc_ep_create (struct udc *udc, const struct usb_endpoint_descriptor *desc, unsigned int nr_banks)

Create a new endpoint.

void udc_ep_destroy (struct udc *udc, usb_ep_id_t ep)

Destroy a previously created endpoint.

int udc_ep_clear_halt (struct udc *udc, usb_ep_id_t ep)

Clear the halted state of an endpoint.

int udc_ep_set_halt (struct udc *udc, usb_ep_id_t ep)

Set the halted state of an endpoint.

int udc_ep_is_halted (struct udc *udc, usb_ep_id_t ep)

Check if a given endpoint is halted.

void udc_ep_clear_wedge (struct udc *udc, usb_ep_id_t ep)

Clear the wedged state of an endpoint.

void udc_ep_set_wedge (struct udc *udc, usb_ep_id_t ep)

Set the wedged state of an endpoint.

bool udc_ep_is_wedged (struct udc *udc, usb_ep_id_t)

Check if a given endpoint is wedged.

void udc_ep0_submit_out_req (struct udc *udc, struct usb_request *req)

Submit an OUT request on the default control endpoint.

void udc_ep0_submit_in_req (struct udc *udc, struct usb_request *req)

Submit an IN request on the default control endpoint.

int udc_ep0_write_sync (struct udc *udc, const void *data, size_t len)

Transmit IN data on the default control data synchronously.

void udc_ep0_send_status (struct udc *udc)

Send a status packet on the default control endpoint.

void udc_ep0_expect_status (struct udc *udc)

Signal that a status packet is expected on the default control endpoint.

void udc_set_address (struct udc *udc, unsigned int addr)

Signal that the UDC is to change its USB address after the status IN phase is complete.

void udc_ep_submit_out_req (struct udc *udc, usb_ep_id_t ep, struct usb_request *req)

Submit an OUT request on a non-control endpoint.

void udc_ep_submit_in_req (struct udc *udc, usb_ep_id_t ep, struct usb_request *req)

Submit an IN request on a non-control endpoint.

void udc_ep_flush (struct udc *udc, usb_ep_id_t ep)

Terminate all pending requests on an endpoint.

int udc_lib_process_setup_request (struct udc *udc, struct usb_setup_req *req)

Handle a USB SETUP request.

Detailed Description

USB Device Controller interface.

This file contains functions and data structures common to all USB Device Controller implementations.

Compiler: IAR EWAVR32 and GNU GCC for AVR32
Supported devices: All AVR32 devices with a USBB module can be used.
AppNote:

Author:: Atmel Corporation: http://www.atmel.com
Support and FAQ: http://support.atmel.no/

Definition in file udc.h.

Typedef Documentation

typedef int usb_ep_id_t

Endpoint ID. Used to identify endpoints on a USB device.

Definition at line 51 of file udc.h.

Enumeration Type Documentation

enum usb_device_flag

Bit definitions for udc::flags.

Enumerator:

USB_DEV_IS_ENABLED	Device Controller enabled.
USB_DEV_AUTOATTACH	Attach when possible.
USB_DEV_HAS_POWER	Vbus detected.
USB_DEV_IS_SUSPENDED	Bus is suspended.

Definition at line 61 of file udc.h.

Function Documentation

void udc_attach ( struct udc * udc )

Attach udc to the bus when possible.

Call this function to signal that the application is ready for the UDC to attach to the bus. This will cause the UDC to attach whenever the following conditions are present:

The ID pin indicates Device operation. When the driver operates in device-only mode, this condition is assumed to always be true.
An acceptable Vbus level from the host is detected.

Definition at line 1757 of file usbb_udc.c.

References cpu_irq_restore(), cpu_irq_save(), udc::flags, set_bit(), test_bit(), and USB_DEV_AUTOATTACH.

Here is the call graph for this function:

void udc_detach ( struct udc * udc )

Detach udc from the bus.

Call this function to forcibly detach the UDC from the bus. The UDC will detach immediately and won't reattach until udc_attach() is called, subject to the conditions listed for that function.

Definition at line 1777 of file usbb_udc.c.

References clear_bit(), cpu_irq_restore(), cpu_irq_save(), udc::flags, test_bit(), and USB_DEV_AUTOATTACH.

Here is the call graph for this function:

void udc_ep0_expect_status ( struct udc * udc )

Signal that a status packet is expected on the default control endpoint.

This function marks the end of the data IN phase, and signals that a status OUT packet is expected.

Parameters:

udc

The USB Device Controller instance.

Precondition:: ep0 is ready to transmit data (no other buffers are queued.)

Postcondition:: ep0 has entered the status OUT phase.

Definition at line 282 of file usbb_udc.c.

References assert, EP0_STATE_STATUS_OUT, test_bit(), and USBB_EP_TXINI.

Referenced by usb_func_get_interface().

Here is the call graph for this function:

void udc_ep0_send_status ( struct udc * udc )

Send a status packet on the default control endpoint.

This function will send a zero-length status packet on ep0. It does not wait for completion, as a status packet marks the end of a control transaction so no further action by the function driver is necessary.

Parameters:

udc

The USB Device Controller instance.

Precondition:: ep0 is ready to transmit data (no other buffers are queued.)

Postcondition:: ep0 has entered the status IN phase.

Definition at line 253 of file usbb_udc.c.

References assert, dbg_printf, EP0_STATE_STATUS_IN, test_bit(), USBB_EP_RXOUTI, and USBB_EP_TXINI.

Here is the call graph for this function:

void udc_ep0_submit_in_req	(	struct udc *	udc,
		struct usb_request *	req
	)

Submit an IN request on the default control endpoint.

This function queues a USB request for transmitting IN data on the default control endpoint (ep0).

Parameters:

	udc	The USB Device Controller instance
	req	Request containing IN data for transmission.

Precondition:: No other requests are queued on ep0.

Postcondition:: ep0 has entered the data IN phase.

Definition at line 187 of file usbb_udc.c.

References assert, barrier, usb_request::buf_list, EP0_STATE_DATA_IN, usb_request::node, set_bit(), slist_borrow_to_tail(), slist_insert_tail(), slist_is_empty(), test_bit(), and USBB_EP_TXINI.

Referenced by usb_func_get_descriptor().

Here is the call graph for this function:

void udc_ep0_submit_out_req	(	struct udc *	udc,
		struct usb_request *	req
	)

Submit an OUT request on the default control endpoint.

This function queues a USB request for receiving OUT data on the default control endpoint (ep0).

Parameters:

	udc	The USB Device Controller instance
	req	Request to use for receiving the OUT data.

Precondition:: No other requests are queued on ep0.

Postcondition:: ep0 has entered the data OUT phase.

Definition at line 157 of file usbb_udc.c.

References assert, barrier, usb_request::buf_list, EP0_STATE_DATA_OUT, usb_request::node, set_bit(), slist_borrow_to_tail(), slist_insert_tail(), slist_is_empty(), test_bit(), and USBB_EP_RXOUTI.

Here is the call graph for this function:

int udc_ep0_write_sync	(	struct udc *	udc,
		const void *	data,
		size_t	len
	)

Transmit IN data on the default control data synchronously.

This function will submit IN data on the default control endpoint (ep0) and busy-wait until it has been sent.

Parameters:

	udc	The USB Device Controller instance.
	data	The data to be transmitted on ep0.
	len	The number of bytes to be transmitted.

Returns:: The number of bytes actually transmitted. This may be less than the requested number of bytes. When sending 8 bytes or less, it is safe to assume that everything will be sent.

Note:: This function should only be used for small quantities of data when it is impractical to submit a buffer asynchronously.

Precondition:: ep0 is ready to transmit data (no other buffers are queued.)

Postcondition:: ep0 is ready to transmit data.

Definition at line 225 of file usbb_udc.c.

References assert, barrier, memcpy(), min, test_bit(), and USBB_EP_TXINI.

Referenced by usb_func_get_interface().

Here is the call graph for this function:

int udc_ep_clear_halt	(	struct udc *	udc,
		usb_ep_id_t	ep
	)

Clear the halted state of an endpoint.

After this function is called, any transaction on ep will be handled normally, i.e. a STALL hanshake will not be sent, and the data toggle sequence will start at DATA0.

Parameters:

	udc	USB Device Controller instance.
	ep	The ID of the endpoint to be un-halted.

Return values:

	0	if the endpoint was successfully halted.
	-1	if the endpoint address is invalid.

Definition at line 744 of file usbb_udc.c.

References dbg_printf, test_bit(), USBB_UECON_RSTDT, and USBB_UECON_STALLRQ.

Here is the call graph for this function:

void udc_ep_clear_wedge	(	struct udc *	udc,
		usb_ep_id_t	ep
	)

Clear the wedged state of an endpoint.

After this function is called, the endpoint halt condition may be cleared by calling udc_ep_clear_halt(). In particular, the host is allowed to clear the halt condition using the ClearFeature(HALT) control request.

This function may be called even if the endpoint isn't wedged, but if it is wedged, it must be halted too.

Parameters:

	udc	USB Device Controller instance.
	ep	The ID of the endpoint to be un-wedged.

Precondition:: ep < CONFIG_USBB_NR_EP

Definition at line 838 of file usbb_udc.c.

References assert, clear_bit(), cpu_irq_restore(), cpu_irq_save(), dbg_printf, test_bit(), and udc_ep_is_halted().

Here is the call graph for this function:

usb_ep_id_t udc_ep_create	(	struct udc *	udc,
		const struct usb_endpoint_descriptor *	desc,
		unsigned int	nr_banks
	)

Create a new endpoint.

Create a new endpoint matching a given endpoint descriptor. The transfer type, endpoint address, and FIFO bank size parameters are taken from the descriptor.

Parameters:

	udc	USB Device Controller instance.
	desc	USB Endpoint Descriptor for the new endpoint.
	nr_banks	The number of FIFO banks to allocate.

Returns:: A cookie identifying the new endpoint, or a negative error code.

Definition at line 1009 of file usbb_udc.c.

References assert, usb_endpoint_descriptor::bEndpointAddress, usb_endpoint_descriptor::bmAttributes, cpu_irq_restore(), cpu_irq_save(), dbg_printf, set_bit(), slist_init(), STATUS_INVALID_PARAM, usbb_udc_configure_ep(), USBB_UDINT_EP, and usb_endpoint_descriptor::wMaxPacketSize.

Here is the call graph for this function:

void udc_ep_destroy	(	struct udc *	udc,
		usb_ep_id_t	ep_id
	)

Destroy a previously created endpoint.

This function will disable the specified endpoint, terminating all queued buffers.

Parameters:

	udc	USB Device Controller instance.
	ep_id	USB Endpoint ID previously returned by udc_ep_create().

Definition at line 1072 of file usbb_udc.c.

References assert, cpu_irq_restore(), cpu_irq_save(), dbg_printf, and USBB_UERST_EPEN.

Here is the call graph for this function:

void udc_ep_flush	(	struct udc *	udc,
		usb_ep_id_t	ep_id
	)

Terminate all pending requests on an endpoint.

This function will flush an endpoint, terminating all queued requests with an error status. After this function returns, the endpoint request queue will be empty.

Parameters:

	udc	USB Device Controller instance.
	ep_id	USB Endpoint ID previously returned by udc_ep_create().

Definition at line 978 of file usbb_udc.c.

References cpu_irq_restore(), cpu_irq_save(), dbg_printf, and set_bit().

Here is the call graph for this function:

int udc_ep_is_halted	(	struct udc *	udc,
		usb_ep_id_t	ep
	)

Check if a given endpoint is halted.

Parameters:

	udc	USB Device Controller instance.
	ep	The ID of the endpoint to check.

Return values:

	1	if ep is halted, i.e. the controller will respond with a STALL handshake to any transaction other than SETUP.
	0	if ep is not halted.
	-1	if the endpoint address is invalid.

Definition at line 652 of file usbb_udc.c.

References USBB_UECON_STALLRQ.

Referenced by udc_ep_clear_wedge().

bool udc_ep_is_wedged	(	struct udc *	udc,
		usb_ep_id_t	ep
	)

Check if a given endpoint is wedged.

A wedged endpoint is a halted endpoint where udc_ep_clear_halt() requests are ignored. To un-halt an wedged endpoint, first call udc_ep_clear_wedge(), then call udc_ep_clear_halt().

Parameters:

	udc	USB Device Controller instance.
	ep	The ID of the endpoint to check.

Return values:

	true	if ep is wedged
	false	if ep is not wedged.

Precondition:: ep < CONFIG_USBB_NR_EP

Definition at line 781 of file usbb_udc.c.

References assert, and test_bit().

Here is the call graph for this function:

int udc_ep_set_halt	(	struct udc *	udc,
		usb_ep_id_t	ep
	)

Set the halted state of an endpoint.

After this function is called, any transaction on ep will result in a STALL hanshake being sent. Any pending transactions will be performed first, however.

Parameters:

	udc	USB Device Controller instance.
	ep	The ID of the endpoint to be halted.

Return values:

	0	if the endpoint was successfully halted.
	-1	if the endpoint address is invalid.

Definition at line 673 of file usbb_udc.c.

References dbg_printf, USBB_UECFG_EPDIR_IN, USBB_UECON_STALLRQ, and USBB_UESTA_GET_NBUSYBK.

Referenced by udc_ep_set_wedge().

void udc_ep_set_wedge	(	struct udc *	udc,
		usb_ep_id_t	ep
	)

Set the wedged state of an endpoint.

After this function is called, any transaction on ep will result in a STALL hanshake being sent, and all requests to clear the halt condition will be ignored. Any pending transactions will be performed first, however.

Parameters:

	udc	USB Device Controller instance.
	ep	The ID of the endpoint to be wedged.

Precondition:: ep < CONFIG_USBB_NR_EP

Definition at line 802 of file usbb_udc.c.

References assert, cpu_irq_restore(), cpu_irq_save(), dbg_printf, set_bit(), and udc_ep_set_halt().

Here is the call graph for this function:

void udc_ep_submit_in_req	(	struct udc *	udc,
		usb_ep_id_t	ep_id,
		struct usb_request *	req
	)

Submit an IN request on a non-control endpoint.

This function queues a USB request for transmitting IN data on a non-control endpoint.

Parameters:

	udc	The USB Device Controller instance
	ep_id	The endpoint ID on which to queue the buffer.
	req	Request containing IN data for transmission.

Precondition:: Interrupts not masked
ep > 0 && ep < CONFIG_USBB_NR_EP

Definition at line 615 of file usbb_udc.c.

References assert, usb_request::buf_list, cpu_irq_disable, cpu_irq_enable, cpu_irq_is_enabled, usb_request::node, slist_borrow_to_tail(), slist_insert_tail(), STATUS_IO_ERROR, test_bit(), and usbb_udc_submit_in_queue().

Here is the call graph for this function:

void udc_ep_submit_out_req	(	struct udc *	udc,
		usb_ep_id_t	ep_id,
		struct usb_request *	req
	)

Submit an OUT request on a non-control endpoint.

This function queues a USB request for receiving OUT data on a non-control endpoint.

Parameters:

	udc	The USB Device Controller instance
	ep_id	The endpoint ID on which to queue the buffer.
	req	Request containing OUT data for reception.

Precondition:: Interrupts not masked
ep > 0 && ep < CONFIG_USBB_NR_EP

Definition at line 576 of file usbb_udc.c.

References assert, usb_request::buf_list, cpu_irq_disable, cpu_irq_enable, cpu_irq_is_enabled, usb_request::node, slist_borrow_to_tail(), slist_insert_tail(), STATUS_IO_ERROR, test_bit(), and usbb_udc_submit_out_queue().

Referenced by msc_submit_write_data_req().

Here is the call graph for this function:

struct udc* udc_init ( void ) [read]

Initialize the USB Device Controller.

This will initialize the USB Device Controller, making it ready to attach to the bus. The controller won't attach automatically until udc_attach() has been called as well.

If the UDC is part of a dual-role (OTG) controller, and dual-role configuration is enabled, this function will initialize the whole controller if it hasn't been initialized before.

Returns:: The USB Device Controller object

Definition at line 342 of file usbb_core.c.

References usbb_init().

Here is the call graph for this function:

static bool udc_is_full_speed ( struct udc * udc ) [inline, static]

Test whether the USB Device Controller is running at full speed.

If the UDC doesn't support full-speed operation, this function will always return false. This may be used by the compiler to eliminate full-speed only code when the UDC doesn't support it, e.g. when it is configured to run in low-speed mode only.

Return values:

	true	The UDC is running at full speed
	false	The UDC is not running at full speed

Definition at line 121 of file udc.h.

References udc::speed.

static bool udc_is_high_speed ( struct udc * udc ) [inline, static]

Test whether the USB Device Controller is running at high speed.

If the UDC doesn't support high-speed operation, this function will always return false. This may be used by the compiler to eliminate high-speed only code when the UDC doesn't support it.

Return values:

	true	The UDC is running at high speed
	false	The UDC is not running at high speed

Definition at line 100 of file udc.h.

References udc::speed.

static bool udc_is_low_speed ( struct udc * udc ) [inline, static]

Test whether the USB Device Controller is running at low speed.

If the UDC doesn't support low-speed operation, this function will always return false. This may be used by the compiler to eliminate low-speed only code when the UDC doesn't support it. Note that low-speed mode is incompatible with all other modes, so this function will always return false for full- and/or high-speed capable devices.

Return values:

	true	The UDC is running at low speed
	false	The UDC is not running at low speed

Definition at line 143 of file udc.h.

References udc::speed.

int udc_lib_process_setup_request	(	struct udc *	udc,
		struct usb_setup_req *	req
	)

Handle a USB SETUP request.

This function parses a USB SETUP request and submits an appropriate response back to the host or, in the case of SETUP OUT requests with data, sets up a buffer for receiving the data payload.

Standard requests defined by the USB 2.0 standard are handled internaly, while class- and vendor-specific requests are passed on to the function driver.

Parameters:

	udc	USB Device Controller instance.
	req	The raw USB SETUP request.

Returns:: 0 if successful or a negative value if a STALL handshake should be sent as the response.

Definition at line 224 of file udc_lib.c.

References usb_setup_req::bmRequestType, usb_setup_req::bRequest, dbg_printf, usb_func_process_setup_request(), usb_setup_req::wIndex, usb_setup_req::wLength, and usb_setup_req::wValue.

Here is the call graph for this function:

void udc_set_address	(	struct udc *	udc,
		unsigned int	addr
	)

Signal that the UDC is to change its USB address after the status IN phase is complete.

Parameters:

	udc	The USB Device Controller instance.
	addr	The new USB address to be used starting from the next control transaction.

Definition at line 304 of file usbb_udc.c.

static enum usb_device_state udc_state ( struct udc * udc ) [inline, static]

Figure out which usb_device_state we're in. This function is probably overly expensive for most purposes, but might useful for debugging. It's also useful for documentation purposes.

Definition at line 157 of file udc.h.

References udc::address, udc::config, udc::flags, udc::speed, test_bit(), USB_DEV_HAS_POWER, and USB_DEV_IS_SUSPENDED.

Here is the call graph for this function:


Data Structures
struct	udc
Typedefs
typedef int	usb_ep_id_t
Enumerations
enum	usb_device_flag { USB_DEV_IS_ENABLED, USB_DEV_AUTOATTACH, USB_DEV_HAS_POWER, USB_DEV_IS_SUSPENDED }
	Bit definitions for udc::flags. More...
Functions
static bool	udc_is_high_speed (struct udc *udc)
	Test whether the USB Device Controller is running at high speed.
static bool	udc_is_full_speed (struct udc *udc)
	Test whether the USB Device Controller is running at full speed.
static bool	udc_is_low_speed (struct udc *udc)
	Test whether the USB Device Controller is running at low speed.
static enum usb_device_state	udc_state (struct udc *udc)
struct udc *	udc_init (void)
	Initialize the USB Device Controller.
void	udc_attach (struct udc *udc)
	Attach udc to the bus when possible.
void	udc_detach (struct udc *udc)
	Detach udc from the bus.
usb_ep_id_t	udc_ep_create (struct udc udc, const struct usb_endpoint_descriptor desc, unsigned int nr_banks)
	Create a new endpoint.
void	udc_ep_destroy (struct udc *udc, usb_ep_id_t ep)
	Destroy a previously created endpoint.
int	udc_ep_clear_halt (struct udc *udc, usb_ep_id_t ep)
	Clear the halted state of an endpoint.
int	udc_ep_set_halt (struct udc *udc, usb_ep_id_t ep)
	Set the halted state of an endpoint.
int	udc_ep_is_halted (struct udc *udc, usb_ep_id_t ep)
	Check if a given endpoint is halted.
void	udc_ep_clear_wedge (struct udc *udc, usb_ep_id_t ep)
	Clear the wedged state of an endpoint.
void	udc_ep_set_wedge (struct udc *udc, usb_ep_id_t ep)
	Set the wedged state of an endpoint.
bool	udc_ep_is_wedged (struct udc *udc, usb_ep_id_t)
	Check if a given endpoint is wedged.
void	udc_ep0_submit_out_req (struct udc udc, struct usb_request req)
	Submit an OUT request on the default control endpoint.
void	udc_ep0_submit_in_req (struct udc udc, struct usb_request req)
	Submit an IN request on the default control endpoint.
int	udc_ep0_write_sync (struct udc udc, const void data, size_t len)
	Transmit IN data on the default control data synchronously.
void	udc_ep0_send_status (struct udc *udc)
	Send a status packet on the default control endpoint.
void	udc_ep0_expect_status (struct udc *udc)
	Signal that a status packet is expected on the default control endpoint.
void	udc_set_address (struct udc *udc, unsigned int addr)
	Signal that the UDC is to change its USB address after the status IN phase is complete.
void	udc_ep_submit_out_req (struct udc udc, usb_ep_id_t ep, struct usb_request req)
	Submit an OUT request on a non-control endpoint.
void	udc_ep_submit_in_req (struct udc udc, usb_ep_id_t ep, struct usb_request req)
	Submit an IN request on a non-control endpoint.
void	udc_ep_flush (struct udc *udc, usb_ep_id_t ep)
	Terminate all pending requests on an endpoint.
int	udc_lib_process_setup_request (struct udc udc, struct usb_setup_req req)
	Handle a USB SETUP request.