# 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: