Atmel Software Framework

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
USB Device Controller (UDC)

The UDC provides a high-level abstraction of the usb device.

You can use these functions to control the main device state (start/attach/wakeup).

USB Device Custom configuration

The following USB Device configuration must be included in the conf_usb.h file of the application.

USB_DEVICE_VENDOR_ID (Word)
Vendor ID provided by USB org (ATMEL 0x03EB).

USB_DEVICE_PRODUCT_ID (Word)
Product ID (Referenced in usb_atmel.h).

USB_DEVICE_MAJOR_VERSION (Byte)
Major version of the device

USB_DEVICE_MINOR_VERSION (Byte)
Minor version of the device

USB_DEVICE_MANUFACTURE_NAME (string)
ASCII name for the manufacture

USB_DEVICE_PRODUCT_NAME (string)
ASCII name for the product

USB_DEVICE_SERIAL_NAME (string)
ASCII name to enable and set a serial number

USB_DEVICE_POWER (Numeric)
(unit mA) Maximum device power

USB_DEVICE_ATTR (Byte)
USB attributes available:

USB_DEVICE_LOW_SPEED (Only defined)
Force the USB Device to run in low speed

USB_DEVICE_HS_SUPPORT (Only defined)
Authorize the USB Device to run in high speed

USB_DEVICE_MAX_EP (Byte)
Define the maximum endpoint number used by the USB Device.
This one is already defined in UDI default configuration. Ex:

Modules

 Implementation of UDC
 Internal implementation.
 
 USB Device Controller (UDC) - Prerequisites
 Common prerequisites for all USB devices.
 
 USB Device Controller (UDC) - Example code
 Common example code for all USB devices.
 
 USB Device Controller (UDC) - Workflow
 Common workflow for all USB devices.
 
 USB Device Descriptor
 

Data Structures

struct  udc_desc_t
 Structure for USB Device Configuration Descriptor. More...
 
struct  udc_string_desc_t
 USB device string descriptor Structure used to transfer ASCII strings to USB String descriptor structure. More...
 

Functions

static void udc_attach (void)
 Attach device to the bus when possible. More...
 
static void udc_detach (void)
 Detaches the device from the bus. More...
 
usb_iface_desc_t UDC_DESC_STORAGEudc_get_interface_desc (void)
 Returns a pointer on the current interface descriptor. More...
 
static bool udc_iface_disable (void)
 Disables an usb device interface (UDI) This routine call the UDI corresponding to interface number. More...
 
static bool udc_iface_enable (void)
 Enables an usb device interface (UDI) This routine calls the UDI corresponding to the interface and setting number. More...
 
static bool udc_include_vbus_monitoring (void)
 Authorizes the VBUS event. More...
 
bool udc_process_setup (void)
 Main routine to manage the USB SETUP request. More...
 
static void udc_remotewakeup (void)
 The USB driver sends a resume signal called "Upstream Resume" This is authorized only when the remote wakeup feature is enabled by host. More...
 
static bool udc_req_iface (void)
 Send the SETUP interface request to UDI. More...
 
static bool udc_req_std_dev_get_configuration (void)
 Standard device request to get configuration number. More...
 
static bool udc_req_std_dev_get_descriptor (void)
 Standard device request to get descriptors about USB device. More...
 
static bool udc_req_std_dev_get_status (void)
 Standard device request to get device status. More...
 
static bool udc_req_std_dev_get_str_desc (void)
 Standard device request to get device string descriptor. More...
 
static bool udc_req_std_dev_set_address (void)
 Standard device request to set device address. More...
 
static bool udc_req_std_dev_set_configuration (void)
 Standard device request to enable a configuration. More...
 
static bool udc_reqstd (void)
 Main routine to manage the standard USB SETUP request. More...
 
void udc_reset (void)
 Reset the current configuration of the USB device, This routines can be called by UDD when a RESET on the USB line occurs. More...
 
void udc_sof_notify (void)
 To signal that a SOF is occurred. More...
 
void udc_start (void)
 Start the USB Device stack. More...
 
void udc_stop (void)
 Stop the USB Device stack. More...
 
static void udc_valid_address (void)
 Change the address of device Callback called at the end of request set address. More...
 

Internal variables to manage the USB device

static le16_t udc_device_status
 Device status state (see enum usb_device_status in usb_protocol.h) More...
 
static uint8_t udc_num_configuration = 0
 Device Configuration number selected by the USB host. More...
 
UDC_DESC_STORAGE usb_dev_desc_t udc_device_desc
 Pointer on the selected speed device configuration. More...
 
UDC_DESC_STORAGE udc_desc_t udc_desc_fs
 USB Device Configuration Descriptor filled for full and high speed. More...
 

Internal structure to store the USB device main strings

static UDC_DESC_STORAGE struct
udc_string_desc_t 
udc_string_desc
 
static UDC_DESC_STORAGE
usb_str_lgid_desc_t 
udc_string_desc_languageid
 Language ID of USB device (US ID by default) More...
 
#define USB_DEVICE_MANUFACTURE_NAME_SIZE   0
 USB device manufacture name storage String is allocated only if USB_DEVICE_MANUFACTURE_NAME is declared by usb application configuration. More...
 
#define USB_DEVICE_PRODUCT_NAME_SIZE   0
 USB device product name storage String is allocated only if USB_DEVICE_PRODUCT_NAME is declared by usb application configuration. More...
 
#define USB_DEVICE_SERIAL_NAME_SIZE   0
 USB device serial number storage String is allocated only if USB_DEVICE_SERIAL_NAME is declared by usb application configuration. More...
 

#define USB_DEVICE_MANUFACTURE_NAME_SIZE   0

USB device manufacture name storage String is allocated only if USB_DEVICE_MANUFACTURE_NAME is declared by usb application configuration.

Referenced by udc_req_std_dev_get_str_desc().

#define USB_DEVICE_PRODUCT_NAME_SIZE   0

USB device product name storage String is allocated only if USB_DEVICE_PRODUCT_NAME is declared by usb application configuration.

Referenced by udc_req_std_dev_get_str_desc().

#define USB_DEVICE_SERIAL_NAME_SIZE   0

USB device serial number storage String is allocated only if USB_DEVICE_SERIAL_NAME is declared by usb application configuration.

Referenced by udc_req_std_dev_get_str_desc().

static void udc_attach ( void  )
inlinestatic

Attach device to the bus when possible.

Warning
If a VBus control is included in driver, then it will attach device when an acceptable Vbus level from the host is detected.

References udd_attach().

static void udc_detach ( void  )
inlinestatic

Detaches the device from the bus.

The driver must remove pull-up on USB line D- or D+.

References udd_detach().

usb_iface_desc_t UDC_DESC_STORAGE* udc_get_interface_desc ( void  )

Returns a pointer on the current interface descriptor.

Returns
pointer on the current interface descriptor.

References udc_ptr_iface.

Referenced by udi_hid_reqstdifaceget_descriptor(), and udi_vendor_enable().

static bool udc_iface_disable ( void  )
static

Disables an usb device interface (UDI) This routine call the UDI corresponding to interface number.

Parameters
iface_numInterface number to disable
Returns
1 if it is done or 0 if interface is not found

References udi_dfu_atmel_disable().

Referenced by udc_reset().

static bool udc_iface_enable ( void  )
static

Enables an usb device interface (UDI) This routine calls the UDI corresponding to the interface and setting number.

Parameters
iface_numInterface number to enable
setting_numSetting number to enable
Returns
1 if it is done or 0 if interface is not found

References udi_dfu_atmel_enable().

Referenced by udc_req_std_dev_set_configuration().

static bool udc_include_vbus_monitoring ( void  )
inlinestatic

Authorizes the VBUS event.

Returns
true, if the VBUS monitoring is possible.

VBus monitoring used cases

The VBus monitoring is used only for USB SELF Power application.

  • By default the USB device is automatically attached when Vbus is high or when USB is start for devices without internal Vbus monitoring. conf_usb.h file does not contains define USB_DEVICE_ATTACH_AUTO_DISABLE.
    //#define USB_DEVICE_ATTACH_AUTO_DISABLE
  • Add custom VBUS monitoring. conf_usb.h file contains define USB_DEVICE_ATTACH_AUTO_DISABLE:
    #define USB_DEVICE_ATTACH_AUTO_DISABLE
    User C file contains:
    // Authorize VBUS monitoring
    // Implement custom VBUS monitoring via GPIO or other
    }
    Event_VBUS_present() // VBUS interrupt or GPIO interrupt or other
    {
    // Attach USB Device
    }
  • Case of battery charging. conf_usb.h file contains define USB_DEVICE_ATTACH_AUTO_DISABLE:
    #define USB_DEVICE_ATTACH_AUTO_DISABLE
    User C file contains:
    Event VBUS present() // VBUS interrupt or GPIO interrupt or ..
    {
    // Authorize battery charging, but wait key press to start USB.
    }
    Event Key press()
    {
    // Stop batteries charging
    // Start USB
    }

References udd_include_vbus_monitoring().

Referenced by run_usb_cdc_test(), run_usb_keyboard_test(), run_usb_mouse_test(), and run_usb_msc_test().

bool udc_process_setup ( void  )

Main routine to manage the USB SETUP request.

Decodes and manages a 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.

The main standard requests defined by the USB 2.0 standard are handled internally. The interface requests are sent to UDI, and the specific request sent to a specific application callback.

Returns
true if the request is supported, else the request is stalled by UDD

References udd_ctrl_request_t::callback, NULL, udd_ctrl_request_t::over_under_run, udd_ctrl_request_t::payload_size, udd_ctrl_request_t::req, udc_req_ep(), udc_req_iface(), udc_reqstd(), udd_g_ctrlreq, Udd_setup_is_in, Udd_setup_recipient, Udd_setup_type, USB_REQ_RECIP_ENDPOINT, USB_REQ_RECIP_INTERFACE, USB_REQ_TYPE_STANDARD, and usb_setup_req_t::wLength.

static void udc_remotewakeup ( void  )
inlinestatic

The USB driver sends a resume signal called "Upstream Resume" This is authorized only when the remote wakeup feature is enabled by host.

References udd_send_remotewakeup().

static bool udc_req_iface ( void  )
static

Send the SETUP interface request to UDI.

Returns
true if the request is supported

References udi_dfu_atmel_setup().

Referenced by udc_process_setup().

static bool udc_req_std_dev_get_configuration ( void  )
static

Standard device request to get configuration number.

Returns
true if success

References udc_num_configuration, and udd_set_setup_payload().

Referenced by udc_reqstd().

static bool udc_req_std_dev_get_status ( void  )
static

Standard device request to get device status.

Returns
true if success

References udc_device_status, and udd_set_setup_payload().

Referenced by udc_reqstd().

static bool udc_req_std_dev_set_address ( void  )
static

Standard device request to set device address.

Returns
true if success

References udd_ctrl_request_t::callback, udc_valid_address(), and udd_g_ctrlreq.

Referenced by udc_reqstd().

static bool udc_req_std_dev_set_configuration ( void  )
static

Standard device request to enable a configuration.

Returns
true if success

References udd_ctrl_request_t::req, udc_iface_enable(), udc_num_configuration, udc_reset(), udd_g_ctrlreq, and usb_setup_req_t::wValue.

Referenced by udc_reqstd().

void udc_reset ( void  )

Reset the current configuration of the USB device, This routines can be called by UDD when a RESET on the USB line occurs.

Reset the UDC.

References usb_conf_desc_t::bNumInterfaces, CPU_TO_LE16, udc_config_speed_t::desc, udc_device_status, udc_iface_disable(), udc_num_configuration, udc_ptr_conf, UDC_REMOTEWAKEUP_DISABLE, USB_DEV_STATUS_BUS_POWERED, USB_DEV_STATUS_REMOTEWAKEUP, and USB_DEV_STATUS_SELF_POWERED.

void udc_sof_notify ( void  )

To signal that a SOF is occurred.

The UDC must send the signal to all UDIs enabled

References usb_conf_desc_t::bNumInterfaces, udc_config_speed_t::desc, NULL, udi_api_t::sof_notify, udc_num_configuration, udc_ptr_conf, and udc_config_speed_t::udi_apis.

void udc_start ( void  )
void udc_stop ( void  )

Stop the USB Device stack.

References udd_disable().

Referenced by ISR(), run_usb_cdc_test(), run_usb_keyboard_test(), run_usb_mouse_test(), and run_usb_msc_test().

static void udc_valid_address ( void  )
static

Change the address of device Callback called at the end of request set address.

References udd_ctrl_request_t::req, udd_g_ctrlreq, udd_set_address(), and usb_setup_req_t::wValue.

Referenced by udc_req_std_dev_set_address().

USB Device Configuration Descriptor filled for full and high speed.

USB Device Configuration Descriptor filled for full and high speed.

Referenced by udc_req_std_dev_get_descriptor().

Pointer on the selected speed device configuration.

Pointer on interface descriptor used by SETUP request.

Pointer on the selected speed device configuration.

Pointer on the selected speed device configuration.

USB Device Descriptor

Referenced by udc_req_std_dev_get_descriptor().

le16_t udc_device_status
static

Device status state (see enum usb_device_status in usb_protocol.h)

Referenced by udc_req_std_dev_get_status(), and udc_reset().

uint8_t udc_num_configuration = 0
static

Device Configuration number selected by the USB host.

Referenced by udc_req_std_dev_get_configuration(), udc_req_std_dev_set_configuration(), and udc_reset().

UDC_DESC_STORAGE struct udc_string_desc_t udc_string_desc
static
Initial value:
= {
.header.bDescriptorType = USB_DT_STRING
}
Definition: usb_protocol.h:199

Referenced by udc_req_std_dev_get_str_desc().

UDC_DESC_STORAGE usb_str_lgid_desc_t udc_string_desc_languageid
static
Initial value:
= {
.desc.bLength = sizeof(usb_str_lgid_desc_t),
.desc.bDescriptorType = USB_DT_STRING,
.string = {LE16(USB_LANGID_EN_US)}
}
English (United States)
Definition: usb_protocol.h:274
#define LE16(x)
Definition: compiler.h:1112
Definition: usb_protocol.h:199
Definition: usb_protocol.h:493

Language ID of USB device (US ID by default)

Referenced by udc_req_std_dev_get_str_desc().