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_CONFIG_ATTR_SELF_POWERED
USB_CONFIG_ATTR_REMOTE_WAKEUP Note: if remote wake enabled then defines remotewakeup callbacks, see Table 5-2. External API from UDC - Callback

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:

When endpoint control 0x00, endpoint 0x01 and endpoint 0x82 is used then USB_DEVICE_MAX_EP=2
When only endpoint control 0x00 is used then USB_DEVICE_MAX_EP=0
When endpoint 0x01 and endpoint 0x81 is used then USB_DEVICE_MAX_EP=1
(configuration not possible on USBB interface)

Modules
	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

	Implementation of UDC
	Internal implementation.

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_STORAGE *	udc_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 FS. 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().

Referenced by main_vbus_action().

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().

Referenced by main_vbus_action().

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_num Interface 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_num	Interface number to enable
setting_num	Setting 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

if (!udc_include_vbus_monitoring()) {

// Implement custom VBUS monitoring via GPIO or other

}

Event_VBUS_present() // VBUS interrupt or GPIO interrupt or other

{

// Attach USB Device

udc_attach();

}
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

udc_attach();

}

References udd_include_vbus_monitoring().

Referenced by main(), 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

Referenced by udd_ctrl_setup_received().

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_descriptor ( void )

static

Standard device request to get descriptors about USB device.

Returns: true if success

References usb_dev_desc_t::bLength, le16_to_cpu, udd_ctrl_request_t::payload_size, udd_ctrl_request_t::req, udc_device_desc, udc_req_std_dev_get_str_desc(), udd_g_ctrlreq, udd_set_setup_payload(), USB_DT_CONFIGURATION, USB_DT_DEVICE, USB_DT_STRING, usb_setup_req_t::wLength, and usb_setup_req_t::wValue.

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_get_str_desc ( void )

static

Standard device request to get device string descriptor.

Returns: true if success

References usb_str_desc_t::bLength, cpu_to_le16, udc_string_desc_t::header, udd_ctrl_request_t::req, udc_string_desc_t::string, udc_string_desc, udc_string_desc_languageid, udd_g_ctrlreq, udd_set_setup_payload(), USB_DEVICE_MANUFACTURE_NAME_SIZE, USB_DEVICE_PRODUCT_NAME_SIZE, USB_DEVICE_SERIAL_NAME_SIZE, and usb_setup_req_t::wValue.

Referenced by udc_req_std_dev_get_descriptor().

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().

static bool udc_reqstd ( void )

static

Main routine to manage the standard USB SETUP request.

Returns: true if the request is supported

References usb_setup_req_t::bRequest, udd_ctrl_request_t::req, udc_req_std_dev_get_configuration(), udc_req_std_dev_get_descriptor(), udc_req_std_dev_get_status(), udc_req_std_dev_set_address(), udc_req_std_dev_set_configuration(), udd_g_ctrlreq, Udd_setup_is_in, Udd_setup_recipient, USB_REQ_GET_CONFIGURATION, USB_REQ_GET_DESCRIPTOR, USB_REQ_GET_STATUS, USB_REQ_RECIP_DEVICE, USB_REQ_SET_ADDRESS, and USB_REQ_SET_CONFIGURATION.

Referenced by udc_process_setup().

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.

Referenced by ISR(), udc_req_std_dev_set_configuration(), udc_req_std_dev_set_feature(), and udc_stop().

void udc_sof_notify ( void )

To signal that a SOF is occurred.

The UDC must send the signal to all UDIs enabled

Referenced by ISR().

void udc_start ( void )

Start the USB Device stack.

References udd_enable().

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

void udc_stop ( void )

Stop the USB Device stack.

References udd_disable().

Referenced by main_hid_set_feature(), 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().

UDC_DESC_STORAGE udc_desc_t udc_desc_fs

USB Device Configuration Descriptor filled for FS.

UDC_DESC_STORAGE usb_dev_desc_t udc_device_desc

Pointer on the selected speed device configuration.

Pointer on interface descriptor used by SETUP request.

Pointer on the selected speed device configuration.

USB Device Descriptor

Pointer on the selected speed device configuration.

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
}

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)}
}

Language ID of USB device (US ID by default)

Referenced by udc_req_std_dev_get_str_desc().

Microchip® Advanced Software Framework

USB Device Custom configuration

Modules

Data Structures

Functions

Internal variables to manage the USB device

Internal structure to store the USB device main strings

VBus monitoring used cases