# drivers/usb/function/usb_function_core.c File Reference

USB function driver core. More...

`#include <assert.h>`
`#include <byteorder.h>`
`#include <debug.h>`
`#include <dmapool.h>`
`#include <malloc.h>`
`#include <string.h>`
`#include <util.h>`
`#include <usb/function.h>`
`#include <usb/function_core.h>`
`#include <usb/request.h>`
`#include <usb/udc.h>`
`#include <app/config_usb.h>`
`#include <app/usb_strings.h>`

Include dependency graph for usb_function_core.c:

Go to the source code of this file.

## Functions
void | usb_func_add_interface (struct usb_func_config *config, struct usb_func_iface *iface)
| Add an interface to a configuration.
struct usb_func_config * | usb_func_add_config (struct usb_configuration_descriptor *desc)
| Add a device configuration.
int | usb_func_get_descriptor (struct udc *udc, uint16_t value, uint16_t index, uint16_t len)
| Handle a standard GET_DESCRIPTOR request.
int | usb_func_set_configuration (struct udc *udc, uint16_t config_id)
| Set the active configuration.
int | usb_func_get_interface (struct udc *udc, uint16_t index)
| Get the currently active alternate setting of an interface.
int | usb_func_set_interface (struct udc *udc, uint16_t index, uint16_t altsetting)
| Select an alternate setting for an interface.
void | usb_func_reset (struct udc *udc)
| Reset the USB function driver.
int | usb_func_process_setup_request (struct udc *udc, struct usb_setup_req *req)
| Handle a class- or vendor-defined setup request.

## Detailed Description

USB function driver core.

This file implements a glue layer for easier function driver implementation, and for supporting multiple configurations and/or interfaces provided by separate function drivers.

- Compiler: IAR EWAVR32 and GNU GCC for AVR32
- Supported devices: All devices with a USB Device Controller
- AppNote:

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

Definition in file usb_function_core.c.

## Function Documentation

struct usb_func_config* usb_func_add_config | ( | struct usb_configuration_descriptor * | desc | ) | `[read]`

Add a device configuration.

This function will add a new configuration of the device.

Note:
  The contents of desc will be altered during normal operation.

Parameters:

  | desc | The configuration descriptor of the new configuration.

Returns:
  An object representing the new configuration.

Precondition:
  - desc must have a bConfigurationValue less than or equal to CONFIG_USB_FUNC_NR_CONFIGURATIONS.
  - Two configurations can not have the same bConfigurationValue.

Definition at line 185 of file usb_function_core.c.

References assert, usb_configuration_descriptor::bConfigurationValue, usb_configuration_descriptor::bNumInterfaces, dbg_printf, usb_func_config::desc, usb_func_config::interface, and memset().

Here is the call graph for this function:

void usb_func_add_interface | ( | struct usb_func_config * | config,
|  | struct usb_func_iface * | iface |
| ) |  |  |

Add an interface to a configuration.

This function will associate an interface with an existing configuration so that it will be automatically enabled when the configuration is selected, and the interface descriptor(s) will be included in the configuration descriptor for this configuration.

If no high-speed descriptors are provided, they will be assumed to be the same as the full-speed descriptors.

Parameters:

  | config | The USB function configuration.
  | iface | The interface to be added to config.

Precondition:
  - iface must have at least one alternate setting.
  - iface must have a bInterfaceNumber less than bNumInterfaces of config.
  - An interface with the same bInterfaceNumber must not have been registered before to the same configuration.
  - All settings must have the same bInterfaceNumber.
  - Each setting's high-speed descriptor, if present, must have the same bInterfaceNumber as the full-speed descriptor.

Definition at line 137 of file usb_function_core.c.

References assert, usb_interface_descriptor::bInterfaceNumber, dbg_printf, usb_func_iface_setting::fs_desc, usb_func_iface_setting::fs_desc_size, usb_func_iface_setting::hs_desc, usb_func_iface_setting::hs_desc_size, usb_func_config::interface, usb_func_iface::nr_settings, usb_func_iface_setting::ops, and usb_func_iface::setting.

int usb_func_get_descriptor | ( | struct udc * | udc,
|  | uint16_t | value,
|  | uint16_t | index,
|  | uint16_t | len |
| ) |  |  |

Handle a standard GET_DESCRIPTOR request.

This is called when the host sends a GET_DESCRIPTOR request. The function driver will queue one or more IN buffers with the requested descriptor data if available.

After the descriptor data has been successfully sent, which may happen after this function returns, udc_ep0_expect_status() will be called.

Parameters:

  | udc | USB Device Controller instance
  | value | The wValue of the request in native byte order
  | index | The wIndex of the request in native byte order
  | len | The wLength of the request in native byte order. The function driver will never queue more than this number of bytes even if the requested descriptor is larger.

Return values:

  | 0 | The request was handled successfully.
  | -1 | The request failed, so ep0 should be stalled.

Definition at line 339 of file usb_function_core.c.

References usb_configuration_descriptor::bDescriptorType, buffer_init_tx(), dbg_printf, usb_func_config::desc, usb_request::flags, min, usb_request::req_done, set_bit(), udc::speed, udc_ep0_submit_in_req(), usb_req_add_buffer(), usb_req_init(), and USB_REQ_SHORT_PKT.

Here is the call graph for this function:

int usb_func_get_interface | ( | struct udc * | udc,
|  | uint16_t | iface_id |
| ) |  |  |

Get the currently active alternate setting of an interface.

Queue a IN packet with a single byte indicating the currently selected alternate setting of the specified interface.

Parameters:

  | udc | USB Device Controller instance
  | iface_id | The bInterfaceNumber of the interface to query

Return values:

  | 0 | The request was handled successfully, and the IN packet was queued.
  | -1 | The request failed, so ep0 should be stalled.

Definition at line 519 of file usb_function_core.c.

References usb_interface_descriptor::bAlternateSetting, usb_func_iface::cur_setting, dbg_printf, usb_func_iface_setting::fs_desc, usb_func_config::interface, udc_ep0_expect_status(), and udc_ep0_write_sync().

Here is the call graph for this function:

int usb_func_process_setup_request | ( | struct udc * | udc,
|  | struct usb_setup_req * | req |
| ) |  |  |

Handle a class- or vendor-defined setup request.

This function is called when a SETUP request whose Type field in bmRequestType does not indicate a standard request. It is completely up to the function driver to decide which requests to support.

This function may queue one or more data or status packets asynchronously, and call udc_ep0_expect_status() when any queued IN data has been sent.

Note that the fields in req are in USB (little-endian) byte order.

Parameters:

  | udc | USB Device Controller instance
  | req | USB SETUP request

Return values:

  | 0 | The request was handled successfully.
  | -1 | The request failed, so ep0 should be stalled.

Definition at line 586 of file usb_function_core.c.

References usb_setup_req::bmRequestType, usb_func_iface::cur_setting, dbg_printf, usb_func_config::interface, usb_func_iface_setting::ops, usb_func_iface_ops::setup, and usb_setup_req::wIndex.

Referenced by udc_lib_process_setup_request().

void usb_func_reset | ( | struct udc * | udc | ) |

Reset the USB function driver.

This is called when a USB bus reset is detected, and when the device is disconnected from the host.

Parameters:

  | udc | USB Device Controller instance

Definition at line 578 of file usb_function_core.c.

References udc::config, dbg_printf, udc::speed, and usb_func_set_configuration().

Referenced by usbb_udc_softirq().

Here is the call graph for this function:

int usb_func_set_configuration | ( | struct udc * | udc,
|  | uint16_t | config_id |
| ) |  |  |

Set the active configuration.

This function will deselect the currently active configuration, and optionally select a new one. If config_id is zero, no new configuration will be selected, but the function will still report success. If config_id is higher than the number of supported configurations, the function will report failure.

Parameters:

  | udc | USB Device Controller instance
  | config_id | The bConfigurationValue of the new configuration, or zero if the device is to change to the Address state.

Return values:

  | 0 | The request was handled successfully.
  | -1 | The request failed, so ep0 should be stalled.

Definition at line 482 of file usb_function_core.c.

References udc::config, dbg_printf, and usb_func_config::desc.

Referenced by usb_func_reset().

int usb_func_set_interface | ( | struct udc * | udc,
|  | uint16_t | iface_id,
|  | uint16_t | alt_setting |
| ) |  |  |

Select an alternate setting for an interface.

Select alternate setting alt_setting for interface iface_id.

Parameters:

  | udc | USB Device Controller instance
  | iface_id | The bInterfaceNumber of the interface
  | alt_setting | The bAlternateSetting to be selected

Return values:

  | 0 | The request was handled successfully.
  | -1 | The request failed, so ep0 should be stalled.

Definition at line 540 of file usb_function_core.c.

References usb_func_iface::cur_setting, dbg_printf, usb_func_iface_ops::disable, usb_func_iface_ops::enable, usb_func_config::interface, usb_func_iface::nr_settings, usb_func_iface_setting::ops, and usb_func_iface::setting.