USB Device Controller (UDC)
[USB Device Framework]

Collaboration diagram for USB Device Controller (UDC):

Data Structures

struct  udc
 A USB Device Controller. More...
struct  udc_fifo
 Internal state variables used by the FIFO accessors. More...

Typedefs

typedef int8_t usb_ep_id_t
 Endpoint identifier.

Enumerations

enum  udc_flag { UDC_IS_ENABLED, UDC_AUTOATTACH, UDC_HAS_POWER, UDC_IS_SUSPENDED }
 

Bit definitions for udc::flags.

More...

Functions

static status_t udc_lib_standard_request (struct udc *udc, struct usb_setup_req *req)
 Handle a standard USB SETUP request.
static struct at90usb_udc * at90usb_udc_of (struct udc *udc)
 Helper function get the AT90USB UDC instance from the UDC instance.
static struct at90usb_udc * at90usb_udc_task_of (struct workqueue_task *task)
 Helper function get the AT90USB UDC instance from the work queue task.
static struct at90usb_udc_ep * at90usb_ep_task_of (struct workqueue_task *task)
 Helper function get the AT90USB UDC endpoint instance from the work queue task.
static void at90usb_udc_req_done (struct udc *udc, struct usb_request *req, enum status_code status)
 Helper function to complete USB requests.
static void at90usb_udc_kill_last_in_bank (void)
 Kill last bank for an IN endpoint.
static void at90usb_udc_kill_first_out_bank (void)
 Kill first bank for an OUT endpoint.
static void at90usb_udc_kill_all_banks (struct udc *udc, usb_ep_id_t ep_id)
 Kill all banks for an endpoint.
static void at90usb_udc_submit_out_queue (struct workqueue_task *task)
 Submit queued buffers on a non-control OUT endpoint.
static void at90usb_udc_submit_in_queue (struct workqueue_task *task)
 Submit queued buffers on a non-control IN endpoint.
static status_t at90usb_udc_configure_ep (uint8_t id, unsigned int size, enum usb_ep_xfer_type type, bool is_in, uint8_t nr_banks)
static void at90usb_udc_ep_flush (struct at90usb_udc *udc90, struct at90usb_udc_ep *ep)
 Flush a non-control endpoint.
static struct at90usb_udc_ep * at90usb_ep_alloc (struct udc *udc, uint8_t addr, uint16_t max_packet_size)
 Allocate a non-control endpoint.
static usb_ep_id_t at90usb_ep_enable (struct at90usb_udc_ep *ep, uint8_t addr, uint16_t max_packet_size, enum usb_ep_xfer_type type, unsigned int nr_banks)
 Enable a non-control endpoint.
static void at90usb_ep0_tx_complete (struct udc *udc, struct at90usb_udc_ep *ep)
 Helper function to complete control endpoint USB requests.
static void at90usb_ep0_tx_flush (struct udc *udc, struct at90usb_udc_ep *ep)
 Flush a control endpoint.
static void at90usb_udc_ep0_worker (struct workqueue_task *task)
 The AT90USB UDC endpoint 0 work task handler.
static void at90usb_udc_device_worker (struct workqueue_task *task)
 The AT90USB device-mode device work task handler.
static void at90usb_udc_maybe_attach (struct at90usb_udc *udc90)
 Helper function to let the UDC maybe attach to the USB bus.
static void at90usb_udc_detach (struct at90usb_udc *udc90)
 Helper function to let the UDC detach from the USB bus.
void at90usb_udc_vbus_on (struct at90usb_udc *udc90)
 Signal that a high Vbus level has been detected.
void at90usb_udc_vbus_off (struct at90usb_udc *udc90)
 Signal that a low Vbus level has been detected.
struct at90usb_udc * at90usb_udc_init (void)
 Initialize the device part of the AT90USB controller.
void at90usb_udc_shutdown (struct at90usb_udc *udc90)
 Shut down the device part of the AT90USB controller.

UDC Library Interface

The following functions make up the interface between the UDC driver and the optional UDC library. The UDC library contains common helper functions for UDC drivers.



status_t udc_lib_process_setup_request (struct udc *udc, struct usb_setup_req *req)
 Handle a USB SETUP request.
status_t udc_enter_test_mode (struct udc *udc, unsigned int mode)
 Enter Test Mode.
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.

Control Transfer

The following functions are used to send and receive packets over the default control endpoint, ep0. Most functions are asynchronous and will call a callback function after the transfer is done. The only exception is udc_ep0_write_sync(), which will write the data to the FIFO immediately and busy-wait until it has been sent.



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.
status_t udc_ep0_write_sync (struct udc *udc, const void *data, size_t len)
 Transmit IN data on the default control endpoint synchronously.
void udc_ep0_send_status (struct udc *udc)
 Send a status IN packet on the default control endpoint.
void udc_ep0_expect_status (struct udc *udc)
 Signal that a status OUT packet is expected on the default control endpoint.

Data Transfer

The following functions are used to do non-control transfers, i.e. bulk, interrupt and isochronous transfers. Note that no synchronous functions are available -- the caller must always provide a callback if needed.



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.

Endpoint Management

The following functions allow drivers to create and destroy endpoints, as well as set, clear and query their "halted" and "wedged" states.

Wedging an endpoint is useful when encountering errors that need some sort of error recovery procedure to be performed by the host. A wedged endpoint behaves like one that is halted, except that the host is prevented from clearing the halted state through the standard ClearFeature(HALT) request. This behaviour is required by the USB Mass Storage Bulk-Only Transport specification.



status_t udc_ep_is_halted (struct udc *udc, usb_ep_id_t ep)
 Check if the endpoint ep is halted.
status_t udc_ep_set_halt (struct udc *udc, usb_ep_id_t ep)
 Set the halted state of the endpoint ep.
status_t udc_ep_clear_halt (struct udc *udc, usb_ep_id_t ep)
 Clear the halted state of the endpoint ep.
bool udc_ep_is_wedged (struct udc *udc, usb_ep_id_t ep)
 Check if a given endpoint is wedged.
void udc_ep_set_wedge (struct udc *udc, usb_ep_id_t ep)
 Set the wedged state of an endpoint.
void udc_ep_clear_wedge (struct udc *udc, usb_ep_id_t ep)
 Clear the wedged state of an endpoint.
void udc_ep_flush (struct udc *udc, usb_ep_id_t ep)
 Terminate all pending requests on an endpoint.
usb_ep_id_t udc_ep_create_bulk (struct udc *udc, uint8_t addr, uint16_t max_packet_size)
 Create a new Bulk endpoint.
usb_ep_id_t udc_ep_create_interrupt (struct udc *udc, uint8_t addr, uint16_t max_packet_size)
 Create a new Interrupt endpoint.
void udc_ep_destroy (struct udc *udc, usb_ep_id_t ep)
 Destroy a previously created endpoint.

Device State

The following functions are used to query and modify the state of the USB device as a whole.



void udc_attach (struct udc *udc)
 Attach udc to the bus when possible.
void udc_detach (struct udc *udc)
 Detach udc from the bus.
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)
 Figure out which usb_device_state the device is in.

Initialization



struct udc * udc_init (void)
 Initialize the USB Device Controller.

FIFO Access Helpers

The following functions may be used by the UDC driver to copy data into and out of a FIFO aperture. It is assumed that the FIFO aperture has a fixed size equal to the max packet size of the endpoint, and that the bytes within it must be accessed sequentially from offset 0 up to the number of bytes available, i.e. no random access is possible.



static void udc_fifo_init (struct udc_fifo *fifo, size_t aperture_size)
 Initialize the internal state of the FIFO.
static bool udc_fifo_zlp_is_pending (struct udc_fifo *fifo, struct usb_request *req)
 Return true if the UDC driver is to send a Zero-Length Packet once the controller is ready to send a new packet.
static void udc_fifo_zlp_clear_pending (struct udc_fifo *fifo, struct usb_request *req)
 Notify the FIFO accessors that a ZLP has been queued, so it is not pending anymore.
static int udc_fifo_write_data (void *dest, struct udc_fifo *fifo, struct slist *done_list, struct usb_request *req)
 Copy data from one or more buffers into the FIFO.
static unsigned int udc_fifo_read_data (const void *src, struct udc_fifo *fifo, unsigned int fifo_nbytes, struct slist *done_bufs, struct usb_request *req)
 Copy data from the FIFO into one or more buffers.

Detailed Description

The UDC driver provides a low-level abstraction of the device controller hardware. Most events originate from the hardware in the form of interrupts, which may cause the UDC driver to call into the UDC library or the device core. These may in turn call back into the driver in order to send an appropriate response to the host.

Typedef Documentation

typedef int8_t usb_ep_id_t

Endpoint identifier.

Used to identify endpoints on a USB device.

Definition at line 67 of file udc.h.

Enumeration Type Documentation

enum udc_flag

Bit definitions for udc::flags.

Enumerator:
UDC_IS_ENABLED 

Device Controller enabled.

UDC_AUTOATTACH 

Attach when possible.

UDC_HAS_POWER 

Vbus detected.

UDC_IS_SUSPENDED 

Bus is suspended.

Definition at line 72 of file udc.h.

Function Documentation

static void at90usb_ep0_tx_complete ( struct udc *  udc,
struct at90usb_udc_ep *  ep 
) [static]

Helper function to complete control endpoint USB requests.

For internal use only.

This helper function will set the USB request status flag and call the request done callback if needed for requests on the control endpoint.

Parameters:
udc The UDC instance.
ep The control endpoint instance.

Definition at line 1132 of file at90usb_udc.c.

References assert, AT90USB_EP_ACTIVE_XFER, at90usb_udc_req_done(), usb_request::buf_list, at90usb_udc_ep::buf_offset, at90usb_udc_ep::buf_queue, at90usb_udc_ep::bytes_written, usb_request::bytes_xfered, clear_bit, at90usb_udc_ep::flags, buffer::len, buffer::node, at90usb_udc_ep::req_queue, slist_give_back_head(), slist_init(), slist_is_empty(), slist_peek_head, and slist_pop_head_node().

Referenced by at90usb_ep0_tx_flush(), and at90usb_udc_ep0_worker().

static void at90usb_ep0_tx_flush ( struct udc *  udc,
struct at90usb_udc_ep *  ep 
) [static]

Flush a control endpoint.

For internal use only.

Parameters:
udc The UDC instance.
ep The control endpoint instance.

Definition at line 1182 of file at90usb_udc.c.

References assert, at90usb_ep0_tx_complete(), AT90USB_EP_ACTIVE_XFER, at90usb_udc_req_done(), at90usb_udc_ep::buf_offset, at90usb_udc_ep::buf_queue, clear_bit, ERR_PROTOCOL, at90usb_udc_ep::flags, usb_request::node, at90usb_udc_ep::req_queue, slist_init(), slist_is_empty(), and slist_pop_head.

Referenced by at90usb_udc_device_worker(), and at90usb_udc_ep0_worker().

static struct at90usb_udc_ep* at90usb_ep_alloc ( struct udc *  udc,
uint8_t  addr,
uint16_t  max_packet_size 
) [static, read]

Allocate a non-control endpoint.

For internal use only.

Allocate and initialize the basics variables for a non-control endpoint instance. Also initialize the work queue handler.

Parameters:
udc The UDC instance.
addr Endpoint address.
max_packet_size Endpoint maximum packet size.
Returns:
Address of the allocated endpoint instance, NULL on error.

Definition at line 974 of file at90usb_udc.c.

References assert, AT90USB_EP_ALLOCATED, AT90USB_EP_IS_IN, at90usb_udc_of(), at90usb_udc_submit_in_queue(), at90usb_udc_submit_out_queue(), atomic_test_and_set_bit(), at90usb_udc::ep, at90usb_udc_ep::flags, at90usb_udc_ep::id, at90usb_udc_ep::maxpacket, at90usb_udc_ep::req_queue, set_bit, slist_init(), at90usb_udc_ep::task, test_bit, at90usb_udc_ep::udc90, at90usb_udc_ep::ueienx, USB_DIR_IN, USB_EP_ADDR_MASK, and workqueue_task_init().

static usb_ep_id_t at90usb_ep_enable ( struct at90usb_udc_ep *  ep,
uint8_t  addr,
uint16_t  max_packet_size,
enum usb_ep_xfer_type  type,
unsigned int  nr_banks 
) [static]

Enable a non-control endpoint.

For internal use only.

Configures and enables a non-control endpoint for transfers.

Parameters:
ep An AT90USB UDC endpoint instance.
addr Endpoint address.
max_packet_size Endpoint maximum packet size.
type Endpoint transfer type.
nr_banks Number of endpoint banks.
Returns:
An allocated endpoint instance, or NULL on error.

Definition at line 1023 of file at90usb_udc.c.

References AT90USB_EP_ENABLED, at90usb_udc_configure_ep(), barrier, at90usb_udc_ep::flags, set_bit, USB_DIR_IN, and USB_EP_ADDR_MASK.

static struct at90usb_udc_ep* at90usb_ep_task_of ( struct workqueue_task *  task  )  [static, read]

Helper function get the AT90USB UDC endpoint instance from the work queue task.

For internal use only.

Parameters:
task A work queue task.
Returns:
The AT90USB UDC endpoint instance.

Definition at line 158 of file at90usb_udc.c.

References container_of.

Referenced by at90usb_udc_ep0_worker(), at90usb_udc_submit_in_queue(), and at90usb_udc_submit_out_queue().

static status_t at90usb_udc_configure_ep ( uint8_t  id,
unsigned int  size,
enum usb_ep_xfer_type  type,
bool  is_in,
uint8_t  nr_banks 
) [static]

For internal use only.

Configure an endpoint at the hardware level.

Parameters:
id Endpoint number.
size Maximum packet size.
type Endpoint transfer type.
is_in true if the endpoint is an IN endpoint. Must be false for control endpoints.
nr_banks Number of FIFO banks (1 or 2).
Return values:
STATUS_OK The endpoint was configured successfully
ERR_INVALID_ARG The endpoint configuration is invalid

Todo:
Only endpoint 1 can be 256 bytes, max 64 for the rest.

Definition at line 821 of file at90usb_udc.c.

References assert, AT90USB_UECFG0X_EPTYPE, AT90USB_UECFG1X_ALLOC, AT90USB_UECFG1X_EPBK, AT90USB_UECFG1X_EPSIZE_128, AT90USB_UECFG1X_EPSIZE_16, AT90USB_UECFG1X_EPSIZE_256, AT90USB_UECFG1X_EPSIZE_32, AT90USB_UECFG1X_EPSIZE_64, AT90USB_UECFG1X_EPSIZE_8, AT90USB_UECONX_EPEN, AT90USB_UERST_EPRST, AT90USB_UESTA0X_CFGOK, cpu_irq_restore(), cpu_irq_save(), dbg_error, ERR_INVALID_ARG, and STATUS_OK.

Referenced by at90usb_ep_enable(), and at90usb_udc_device_worker().

static void at90usb_udc_detach ( struct at90usb_udc *  udc90  )  [static]

Helper function to let the UDC detach from the USB bus.

For internal use only.

Parameters:
udc90 The AT90USB UDC instance.

Definition at line 1536 of file at90usb_udc.c.

References udc::address, AT90USB_UDCON_DETACH, dbg_verbose, udc::flags, udc::speed, at90usb_udc::udc, UDC_AUTOATTACH, UDC_HAS_POWER, UDC_IS_ENABLED, usb_dev_reset(), and USB_SPEED_UNKNOWN.

Referenced by at90usb_udc_vbus_off().

static void at90usb_udc_device_worker ( struct workqueue_task *  task  )  [static]

The AT90USB device-mode device work task handler.

For internal use only.

Precondition:
Called from workqueue, interrupts enabled.

Definition at line 1457 of file at90usb_udc.c.

References udc::address, at90usb_ep0_tx_flush(), at90usb_udc_configure_ep(), at90usb_udc_task_of(), AT90USB_UDIEN_EORSTE, AT90USB_UDINT_EORSTI, AT90USB_UEIENX_RXSTPE, clear_bit, cpu_irq_restore(), cpu_irq_save(), at90usb_udc::ctrl_state, dbg_verbose, at90usb_udc::ep, EP0_STATE_SETUP, udc::flags, udc::speed, at90usb_udc::udc, UDC_IS_SUSPENDED, at90usb_udc_ep::ueienx, usb_dev_reset(), USB_SPEED_FULL, USB_SPEED_LOW, and USB_SPEED_UNKNOWN.

Referenced by at90usb_udc_init().

static void at90usb_udc_ep0_worker ( struct workqueue_task *  task  )  [static]

The AT90USB UDC endpoint 0 work task handler.

For internal use only.

Note:
This function will disable and enable interrupts while processing the queue, but will return with interrupt flag as when called.
Parameters:
task Work queue task.
Precondition:
Called from workqueue, interrupts enabled.

Definition at line 1211 of file at90usb_udc.c.

References buffer::addr, udc::address, assert, at90usb_ep0_tx_complete(), at90usb_ep0_tx_flush(), AT90USB_EP_ACTIVE_XFER, at90usb_ep_task_of(), AT90USB_UDADDR_ADDEN, AT90USB_UDADDR_UADD_MASK, at90usb_udc_req_done(), AT90USB_UEIENX_RXOUTE, AT90USB_UEIENX_TXINE, AT90USB_UEINTX_RXOUTI, AT90USB_UEINTX_RXSTPI, AT90USB_UEINTX_TXINI, usb_request::buf_list, at90usb_udc_ep::buf_offset, at90usb_udc_ep::buf_queue, at90usb_udc_ep::bytes_written, usb_request::bytes_xfered, clear_bit, copy_from_fifo(), copy_to_fifo(), cpu_irq_disable, cpu_irq_enable, at90usb_udc::ctrl_state, dbg_verbose, EP0_STATE_DATA_IN, EP0_STATE_DATA_ZLP, EP0_STATE_SETUP, EP0_STATE_STATUS_IN, usb_request::flags, at90usb_udc_ep::flags, slist::last, le16_to_cpu(), buffer::len, min_u, buffer::node, dma_addr_t::phys, dma_addr_t::ptr, at90usb_udc_ep::req_queue, at90usb_udc::setup_req, slist_init(), slist_is_empty(), slist_node_is_last(), slist_peek_head, slist_peek_next, slist_pop_head_node(), test_bit, at90usb_udc::udc, at90usb_udc_ep::udc90, udc_ep_set_halt(), udc_lib_process_setup_request(), at90usb_udc_ep::ueienx, and USB_REQ_SHORT_PKT.

Referenced by at90usb_udc_init().

static void at90usb_udc_ep_flush ( struct at90usb_udc *  udc90,
struct at90usb_udc_ep *  ep 
) [static]

Flush a non-control endpoint.

For internal use only.

Parameters:
udc90 The AT90USB UDC instance.
ep An UDC endpoint instance.

Definition at line 889 of file at90usb_udc.c.

References assert, AT90USB_EP_ACTIVE_XFER, AT90USB_EP_ENABLED, at90usb_udc_kill_all_banks(), at90usb_udc_req_done(), usb_request::buf_list, clear_bit, cpu_irq_restore(), cpu_irq_save(), dbg_verbose, ERR_FLUSHED, slist::first, at90usb_udc_ep::flags, at90usb_udc_ep::id, slist::last, slist_node::next, buffer::node, usb_request::node, at90usb_udc_ep::req_queue, slist_is_empty(), slist_node_is_valid(), slist_peek_head, slist_peek_next, slist_pop_head, test_bit, at90usb_udc::udc, and at90usb_udc_ep::ueienx.

struct at90usb_udc* at90usb_udc_init ( void   )  [read]

Initialize the device part of the AT90USB controller.

For internal use only.

This function does any device-side initialization necessary when the AT90USB controller as a whole is being initialized. It does not enable any device-side functionality.

Returns:
The AT90USB device controller (UDC) instance.

Definition at line 1634 of file at90usb_udc.c.

References at90usb_udc_device_worker(), at90usb_udc_ep0_worker(), AT90USB_UDCON_LSM, at90usb_udc_ep::buf_queue, at90usb_udc::ep, udc::flags, at90usb_udc_ep::id, at90usb_udc_ep::req_queue, slist_init(), at90usb_udc_ep::task, at90usb_udc::task, at90usb_udc::udc, at90usb_udc_ep::udc90, and workqueue_task_init().

Referenced by at90usb_init().

static void at90usb_udc_kill_all_banks ( struct udc *  udc,
usb_ep_id_t  ep_id 
) [static]

Kill all banks for an endpoint.

For internal use only.

Precondition:
In interrupt handler and/or interrupts disabled and with the appropriate endpoint selected through the AVR_REG_UENUM UENUM register.
Parameters:
udc The UDC instance.
ep_id Endpoint number.

Definition at line 223 of file at90usb_udc.c.

References at90usb_udc_kill_first_out_bank(), at90usb_udc_kill_last_in_bank(), AT90USB_UECFG0X_EPDIR_IN, and AT90USB_UESTA0X_GET_NBUSYBK.

Referenced by at90usb_udc_ep_flush().

static void at90usb_udc_kill_first_out_bank ( void   )  [static]

Kill first bank for an OUT endpoint.

For internal use only.

Precondition:
In interrupt handler and/or interrupts disabled and with the appropriate endpoint selected through the AVR_REG_UENUM UENUM register.

Definition at line 206 of file at90usb_udc.c.

References AT90USB_UEINTX_FIFOCON, and AT90USB_UEINTX_RXOUTI.

Referenced by at90usb_udc_kill_all_banks().

static void at90usb_udc_kill_last_in_bank ( void   )  [static]

Kill last bank for an IN endpoint.

For internal use only.

Precondition:
In interrupt handler and/or interrupts disabled and with the appropriate endpoint selected through the AVR_REG_UENUM UENUM register.

Definition at line 191 of file at90usb_udc.c.

References AT90USB_UEINTX_KILLBK, and barrier.

Referenced by at90usb_udc_kill_all_banks().

static void at90usb_udc_maybe_attach ( struct at90usb_udc *  udc90  )  [static]

Helper function to let the UDC maybe attach to the USB bus.

For internal use only.

Parameters:
udc90 The AT90USB UDC instance.

Definition at line 1511 of file at90usb_udc.c.

References at90usb_udc_is_enabled(), AT90USB_UDCON_DETACH, AT90USB_UDIEN_EORSTE, AT90USB_UHWCON_UVREGE, dbg_verbose, udc::flags, test_bit, at90usb_udc::udc, UDC_AUTOATTACH, and UDC_HAS_POWER.

Referenced by at90usb_udc_vbus_on().

static struct at90usb_udc* at90usb_udc_of ( struct udc *  udc  )  [static, read]

Helper function get the AT90USB UDC instance from the UDC instance.

For internal use only.

Parameters:
udc An UDC instance.
Returns:
The AT90USB UDC instance.

Definition at line 128 of file at90usb_udc.c.

References container_of.

Referenced by at90usb_ep_alloc().

static void at90usb_udc_req_done ( struct udc *  udc,
struct usb_request *  req,
enum status_code  status 
) [static]

Helper function to complete USB requests.

For internal use only.

This helper function will set the USB request status flag and call the request done callback if needed.

Parameters:
udc The UDC instance.
req A completed USB request.
status Status code for the completed USB request.

Definition at line 174 of file at90usb_udc.c.

References usb_request::req_done, and usb_request::status.

Referenced by at90usb_ep0_tx_complete(), at90usb_ep0_tx_flush(), at90usb_udc_ep0_worker(), at90usb_udc_ep_flush(), at90usb_udc_submit_in_queue(), and at90usb_udc_submit_out_queue().

void at90usb_udc_shutdown ( struct at90usb_udc *  udc90  ) 

Shut down the device part of the AT90USB controller.

For internal use only.

This function does any device-side cleanups necessary when the AT90USB controller as a whole is being shut down.

Parameters:
udc90 The AT90USB UDC instance.

Definition at line 1668 of file at90usb_udc.c.

References udc::flags, and at90usb_udc::udc.

Referenced by at90usb_init().

static void at90usb_udc_submit_in_queue ( struct workqueue_task *  task  )  [static]

Submit queued buffers on a non-control IN endpoint.

For internal use only.

Note:
This function will disable and enable interrupts while processing the queue, but will return with interrupt flag as when called. It will process an entire USB request before calling the callback (if any) and exit, potentially doing a reentry shortly after to process any additional USB requests.
Parameters:
task Work queue task.
Precondition:
ep->active == NULL
Called from workqueue, interrupts enabled.

Definition at line 496 of file at90usb_udc.c.

References buffer::addr, assert, AT90USB_EP_ACTIVE_XFER, AT90USB_EP_ENABLED, at90usb_ep_task_of(), at90usb_udc_req_done(), AT90USB_UEINTX_FIFOCON, AT90USB_UEINTX_TXINI, barrier, usb_request::buf_list, usb_request::bytes_xfered, clear_bit, copy_to_fifo(), cpu_irq_disable, cpu_irq_enable, dbg_verbose, at90usb_udc_ep::flags, at90usb_udc_ep::id, slist::last, buffer::len, main_workqueue, at90usb_udc_ep::maxpacket, min_u, buffer::node, usb_request::node, dma_addr_t::phys, at90usb_udc_ep::req_queue, set_bit, slist_is_empty(), slist_node_is_valid(), slist_peek_head, slist_peek_head_node(), slist_peek_next, slist_pop_head, at90usb_udc_ep::task, test_bit, at90usb_udc::udc, at90usb_udc_ep::udc90, and workqueue_add_task().

Referenced by at90usb_ep_alloc().

static void at90usb_udc_submit_out_queue ( struct workqueue_task *  task  )  [static]

Submit queued buffers on a non-control OUT endpoint.

For internal use only.

Note:
This function will disable and enable interrupts while processing the queue, but will return with interrupt flag as when called. It will process an entire USB request before calling the callback (if any) and exit, potentially doing a reentry shortly after to process any additional USB requests.
Parameters:
task Work queue task.
Precondition:
ep->active == NULL
Called from workqueue, interrupts enabled.

Definition at line 366 of file at90usb_udc.c.

References buffer::addr, assert, AT90USB_EP_ACTIVE_XFER, AT90USB_EP_ENABLED, at90usb_ep_task_of(), at90usb_udc_req_done(), AT90USB_UEIENX_RXOUTE, AT90USB_UEINTX_FIFOCON, AT90USB_UEINTX_RXOUTI, barrier, usb_request::buf_list, usb_request::bytes_xfered, clear_bit, copy_from_fifo(), cpu_irq_disable, cpu_irq_enable, dbg_verbose, at90usb_udc_ep::flags, at90usb_udc_ep::id, slist::last, buffer::len, min_u, buffer::node, usb_request::node, dma_addr_t::phys, at90usb_udc_ep::req_queue, set_bit, slist_is_empty(), slist_node_is_valid(), slist_peek_head, slist_peek_head_node(), slist_peek_next, slist_pop_head, test_bit, at90usb_udc::udc, at90usb_udc_ep::udc90, and at90usb_udc_ep::ueienx.

Referenced by at90usb_ep_alloc().

static struct at90usb_udc* at90usb_udc_task_of ( struct workqueue_task *  task  )  [static, read]

Helper function get the AT90USB UDC instance from the work queue task.

For internal use only.

Parameters:
task A work queue task.
Returns:
The AT90USB UDC instance.

Definition at line 143 of file at90usb_udc.c.

References container_of.

Referenced by at90usb_udc_device_worker().

void at90usb_udc_vbus_off ( struct at90usb_udc *  udc90  ) 

Signal that a low Vbus level has been detected.

For internal use only.

This function is called by the AT90USB bus interface driver when Vbus power is no longer provided by the host.

Parameters:
udc90 The AT90USB UDC instance.

Definition at line 1587 of file at90usb_udc.c.

References at90usb_udc_detach(), clear_bit, dbg_verbose, udc::flags, test_bit, at90usb_udc::udc, and UDC_HAS_POWER.

Referenced by at90usb_check_vbus().

void at90usb_udc_vbus_on ( struct at90usb_udc *  udc90  ) 

Signal that a high Vbus level has been detected.

For internal use only.

This function is called by the AT90USB bus interface driver when Vbus power is provided by the host.

Parameters:
udc90 The AT90USB UDC instance.

Definition at line 1567 of file at90usb_udc.c.

References at90usb_udc_maybe_attach(), dbg_verbose, udc::flags, set_bit, test_bit, at90usb_udc::udc, and UDC_HAS_POWER.

Referenced by at90usb_check_vbus().

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.

Referenced by app_usb_mode_worker().

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.

Referenced by app_usb_mode_worker().

status_t udc_enter_test_mode ( struct udc *  udc,
unsigned int  mode 
)

Enter Test Mode.

This function is implemented by the UDC driver and called by the UDC library to request the device to enter test mode after the status IN stage is complete.

Parameters:
udc The USB Device Controller instance
mode The index of the test mode to be entered
Return values:
STATUS_OK The specified test mode will be entered
negative The device does not support the specified test mode

Referenced by udc_lib_standard_request().

void udc_ep0_expect_status ( struct udc *  udc  ) 

Signal that a status OUT 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

Referenced by udc_lib_standard_request().

void udc_ep0_send_status ( struct udc *  udc  ) 

Send a status IN packet on the default control endpoint.

This function will send a zero-length status IN 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 higher layers 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

Referenced by udc_lib_standard_request().

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
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
status_t udc_ep0_write_sync ( struct udc *  udc,
const void *  data,
size_t  len 
)

Transmit IN data on the default control endpoint synchronously.

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

Note:
This function must only be used for small quantities of data when it is impractical to submit a buffer asynchronously.
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.
Precondition:
ep0 is ready to transmit data (no other buffers are queued)
Postcondition:
ep0 is ready to transmit data

Referenced by udc_lib_standard_request().

status_t udc_ep_clear_halt ( struct udc *  udc,
usb_ep_id_t  ep 
)

Clear the halted state of the endpoint ep.

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:
STATUS_OK The endpoint was successfully halted
negative The endpoint could not be halted

Referenced by udc_lib_standard_request().

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 < APP_UDC_NR_ENDPOINTS
usb_ep_id_t udc_ep_create_bulk ( struct udc *  udc,
uint8_t  addr,
uint16_t  max_packet_size 
)

Create a new Bulk endpoint.

Create a new endpoint with bulk transfer type. If bit 7 of addr is set, the endpoint is configured as a bulk-IN endpoint; otherwise, it's configured as a bulk-OUT endpoint.

Parameters:
udc USB Device Controller instance
addr USB endpoint address, including direction. Bits 6..4 are reserved and must be set to 0. Same as the bEndpointAddress field of the endpoint descriptor.
max_packet_size The maximum packet size to allow on this endpoint. Same as the wMaxPacket field in the endpoint descriptor converted to native endian.
Returns:
A cookie identifying the new endpoint, or a negative error code
usb_ep_id_t udc_ep_create_interrupt ( struct udc *  udc,
uint8_t  addr,
uint16_t  max_packet_size 
)

Create a new Interrupt endpoint.

Create a new endpoint with interrupt transfer type. If bit 7 of addr is set, the endpoint is configured as an interrupt-IN endpoint; otherwise, it's configured as an interrupt-OUT endpoint.

Parameters:
udc USB Device Controller instance
addr USB endpoint address, including direction. Bits 6..4 are reserved and must be set to 0. Same as the bEndpointAddress field of the endpoint descriptor.
max_packet_size The maximum packet size to allow on this endpoint. Same as the wMaxPacket field in the endpoint descriptor converted to native endian.
Returns:
A cookie identifying the new endpoint, or a negative error code
void udc_ep_destroy ( struct udc *  udc,
usb_ep_id_t  ep 
)

Destroy a previously created endpoint.

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

Parameters:
udc USB Device Controller instance
ep USB Endpoint ID previously returned by udc_ep_create()
void udc_ep_flush ( struct udc *  udc,
usb_ep_id_t  ep 
)

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. The data toggle sequence and the halted and wedged states of the endpoints will not be affected.

Parameters:
udc USB Device Controller instance.
ep USB Endpoint ID previously returned by udc_ep_create().
status_t udc_ep_is_halted ( struct udc *  udc,
usb_ep_id_t  ep 
)

Check if the endpoint ep is halted.

Parameters:
udc USB Device Controller instance.
ep The ID of the endpoint to check.
Return values:
1 ep is halted, i.e. the controller will respond with a STALL handshake to any transaction other than SETUP.
0 ep is not halted.
negative The halted state could not be determined (i.e. ep does not identify a valid endpoint.)

Referenced by udc_lib_standard_request().

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 ep is wedged
false ep is not wedged.
Precondition:
ep < APP_UDC_NR_ENDPOINTS
status_t udc_ep_set_halt ( struct udc *  udc,
usb_ep_id_t  ep 
)

Set the halted state of the endpoint ep.

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:
STATUS_OK The endpoint was successfully halted
negative The endpoint could not be halted

Referenced by at90usb_udc_ep0_worker(), and udc_lib_standard_request().

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

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

Parameters:
udc The USB Device Controller instance
ep The endpoint ID on which to queue the buffer
req Request containing IN data for transmission
Precondition:
Interrupts not masked
ep > 0 && ep < APP_UDC_NR_ENDPOINTS
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.

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

Parameters:
udc The USB Device Controller instance
ep The endpoint ID on which to queue the buffer
req Request containing OUT data for reception
Precondition:
Interrupts not masked
ep > 0 && ep < APP_UDC_NR_ENDPOINTS

Referenced by msc_submit_write_data_req().

static void udc_fifo_init ( struct udc_fifo *  fifo,
size_t  aperture_size 
) [inline, static]

Initialize the internal state of the FIFO.

Parameters:
fifo The FIFO to be initialized
aperture_size The size of the FIFO aperture in bytes

Definition at line 125 of file udc_lib.h.

References udc_fifo::buf_offset, udc_fifo::send_zlp, and udc_fifo::size.

static unsigned int udc_fifo_read_data ( const void *  src,
struct udc_fifo *  fifo,
unsigned int  fifo_nbytes,
struct slist *  done_bufs,
struct usb_request *  req 
) [inline, static]

Copy data from the FIFO into one or more buffers.

This function will consume one or more buffers from req and copy data from the FIFO into the memory areas they represent. If the buffer has room for more data than the FIFO can provide, the current offset will be recorded and the next call to this function will resume where it left off.

It is the caller's responsibility to ensure that the FIFO bank at src contains valid data.

Parameters:
src The virtual address of the FIFO aperture
fifo Internal state for use by the FIFO accessors
fifo_nbytes The number of valid bytes in the FIFO, as reported by the UDC hardware
done_bufs Buffers which have been fully consumed are placed on this list
req The USB request from which to consume buffers
Returns:
The number of bytes read from the FIFO, or a negative error code on failure.

Definition at line 257 of file udc_lib.h.

References buffer::addr, assert, usb_request::buf_list, buf_list_pop_head, udc_fifo::buf_offset, dbg_verbose, buffer::len, memcpy(), min_u, buffer::node, dma_addr_t::ptr, slist_insert_head(), slist_insert_tail(), and slist_is_empty().

static int udc_fifo_write_data ( void *  dest,
struct udc_fifo *  fifo,
struct slist *  done_list,
struct usb_request *  req 
) [inline, static]

Copy data from one or more buffers into the FIFO.

This function will consume one or more buffers from req and copy the data contained within them into the FIFO aperture at dest. If the buffer contains more data than can fit into the FIFO, the current offset will be recorded and the next call to this function will resume where it left off.

It is the caller's responsibility to ensure that the FIFO bank at dest is available and has room for a whole USB packet.

Parameters:
dest The virtual address of the FIFO aperture
fifo Internal state for use by the FIFO accessors
done_list Buffers which have been fully consumed are placed on this list
req The USB request from which to consume buffers
Returns:
The number of bytes written to the FIFO, or a negative error code on failure.

Definition at line 183 of file udc_lib.h.

References buffer::addr, usb_request::buf_list, buf_list_pop_head, udc_fifo::buf_offset, dbg_verbose, usb_request::flags, buffer::len, memcpy(), min_u, buffer::node, dma_addr_t::ptr, udc_fifo::send_zlp, udc_fifo::size, slist_insert_head(), slist_insert_tail(), slist_is_empty(), test_bit, and USB_REQ_SHORT_PKT.

static void udc_fifo_zlp_clear_pending ( struct udc_fifo *  fifo,
struct usb_request *  req 
) [inline, static]

Notify the FIFO accessors that a ZLP has been queued, so it is not pending anymore.

Parameters:
fifo Internal state for use by the FIFO accessors
req The USB request currently at the head of the queue

Definition at line 156 of file udc_lib.h.

References udc_fifo::send_zlp.

static bool udc_fifo_zlp_is_pending ( struct udc_fifo *  fifo,
struct usb_request *  req 
) [inline, static]

Return true if the UDC driver is to send a Zero-Length Packet once the controller is ready to send a new packet.

Parameters:
fifo Internal state for use by the FIFO accessors
req The USB request currently at the head of the queue
Return values:
true The UDC driver must send a ZLP after the currently pending packets have been sent.
false The UDC driver must not send a ZLP at this point.

Definition at line 143 of file udc_lib.h.

References udc_fifo::send_zlp.

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:
A USB Device Controller object

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 426 of file at90usb_core.c.

References at90usb_get_udc(), at90usb_init(), and at90usb_udc::udc.

Referenced by main().

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 176 of file udc.h.

References udc::speed, and USB_SPEED_FULL.

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 155 of file udc.h.

References udc::speed, and USB_SPEED_HIGH.

Referenced by udc_lib_standard_request().

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 198 of file udc.h.

References udc::speed, and USB_SPEED_LOW.

status_t 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 internally, while class- and vendor-specific requests are passed on to a higher-level driver.

Parameters:
udc USB Device Controller instance.
req The raw USB SETUP request.
Return values:
STATUS_OK The request was handled successfully
negative The request failed, so ep0 should be STALLed.

Referenced by at90usb_udc_ep0_worker().

static status_t udc_lib_standard_request ( struct udc *  udc,
struct usb_setup_req *  req 
) [static]

Handle a standard USB SETUP request.

For internal use only.

Todo:
Need a way for the application and/or drivers to switch between self-powered and bus-powered mode.
Todo:
Implement remote wakeup support

Definition at line 62 of file udc_lib.c.

References udc::address, build_assert, udc::config, cpu_to_le16(), LE16, le16_to_cpu(), usb_request::status, udc_enter_test_mode(), udc_ep0_expect_status(), udc_ep0_send_status(), udc_ep0_write_sync(), udc_ep_clear_halt(), udc_ep_is_halted(), udc_ep_set_halt(), udc_is_high_speed(), udc_set_address(), USB_DEV_FEATURE_REMOTE_WAKEUP, USB_DEV_FEATURE_TEST_MODE, usb_dev_get_descriptor(), usb_dev_get_interface(), usb_dev_set_configuration(), usb_dev_set_interface(), USB_DEV_STATUS_SELF_POWERED, USB_EP_ADDR_MASK, usb_setup_is_in, usb_setup_is_out, and usb_setup_recipient.

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.

This function is implemented by the UDC driver and called by the UDC library when a Set Address request is received from the host.

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

Referenced by udc_lib_standard_request().

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

Figure out which usb_device_state the device is 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 214 of file udc.h.

References udc::address, udc::config, udc::flags, udc::speed, test_bit, UDC_HAS_POWER, UDC_IS_SUSPENDED, USB_SPEED_UNKNOWN, USB_STATE_ADDRESS, USB_STATE_ATTACHED, USB_STATE_CONFIGURED, USB_STATE_DEFAULT, USB_STATE_POWERED, and USB_STATE_SUSPENDED.

Generated on Thu Apr 29 14:10:35 2010 for xplain-bc by  doxygen 1.6.3