AVR4900 ASF - USB Device Stack
AVR4900 ASF - USB Device Stack
Features
USB 2.0 compliance - USB Chapter 9 certified - Control, Bulk, Isochronous and Interrupt transfer types - Low Speed (1.5Mbit/s), Full Speed (12Mbit/s), High Speed (480Mbit/s) data rates Small stack size frees space for main application Real time (OS compliance, no latency) Supports 8-bit and 32-bit AVR platforms USB DMA support increases speed performance Supports most USB classes and ready to use (HID, CDC, MSC, PHDC, AUDIO)
1 Introduction
This document introduces the USB device stack. This stack is included in the Atmel AVR Software Framework (ASF), and aims to provide the customer with the quickest and easiest way to build a USB application. A full description of this stack is available in this document. No specific knowledge is required to use it except basic USB knowledge.
Rev. 8360C-AVR-09/11
2 Abbreviations
ASF: AVR Software Framework CBW: Command Block Wrapper (from Mass Storage Class) CDC: Communication Device Class CSW: Command Status Wrapper (from Mass Storage Class) DP or D+ Data Plus differential line DM or DData Minus differential line FS: USB Full Speed HID: Human interface device HS: USB High Speed UDC: USB Device Controller UDD: USB Device Descriptor UDI: USB Device Interface USB: Universal Serial Bus MSC: Mass Storage Class PHDC: Peripheral Health Device Class sleepmgr : Sleep management service from ASF ZLP: Zero length packet
AVR4900
8360C-AVR-09/11
AVR4900
3 USB Device Application Notes
Several USB device examples are provided by Atmel. For each example, Atmel provides an Application Note. Figure 3-1. USB device application notes.
Basic USB knowledge is necessary to understand the USB Device Class application notes (Classes: HID, CDC, MSC, PHDC). To create a USB device with one of the ASF provided classes, refer directly to the related application note for this USB class. The New Class and Composite USB Device application notes are designed for advanced USB developers.
3
8360C-AVR-09/11
4 Organization
4.1 Overview
The USB Device stack is divided into three parts: USB Device Controller (UDC) provides USB Chapter 9 compliance USB Device Interface (UDI) provides USB Class compliance USB Device Driver (UDD) provides the USB interface for each AVR product Figure 4-1. USB device stack architecture.
UDD
These parameters give many values, and in average the USB Device stack does not exceed 10Kbytes of FLASH and 1Kbytes of RAM using compiler high optimization level.
AVR4900
8360C-AVR-09/11
AVR4900
4.3 USB Device stack files
The USB Device Stack files are available in Atmel AVR Studio 5. Atmel AVR Studio 5 allows creation of a New Example Project. Thus, in example list the USB Device examples beginning by USB Device (Select Technology USB to reduce example list). Note, the example with text (from ASF V1) does not corresponding at this USB Device Stack. 4.3.1 Common files for all AVR products Files Defines USB constant usb_protocol.h (from usb.org) usb_atmel.h (from Atmel) UDC files udc.c/h udc_desc.h udi.h udd.h Classes Protocols files usb_protocol_foo.h UDI files udi_foo.c/h udi_foo_desc.c udi_foo_conf.h 4.3.2 UDD files depending on selected AVR products avr32/drivers/usbb/usbb_device.c/h avr32/drivers/usbb/usbb_otg.h avr32/drivers/usbc/usbc_device.c/h avr32/drivers/usbc/usbc_otg.h Paths common/services/usb/
common/services/usb/udc/
common/services/usb/class/foo/ common/services/usb/class/foo/device/
4.3.3 Specific file for each application Application file usb_conf.h (This configuration file is mandatory)
5
8360C-AVR-09/11
Application
External API from UDC Described in this document External API from UDI Described in external UDI documents Internal API Described in this document for USB experts
UDC
UDI -
UDD
UDC
AVR4900
8360C-AVR-09/11
AVR4900
All UDC callbacks are optional and defined by user in usb_conf.h for each application. Table 5-2. External API from UDC Callback.
Define name UDC_VBUS_EVENT(bool b_present) UDC_SUSPEND_EVENT() UDC_RESUME_EVENT() UDC_SOF_EVENT() UDC_REMOTEWAKEUP_ENABLE() UDC_REMOTEWAKEUP_DISABLE() UDC_GET_EXTRA_STRING() UDC_SPECIFIC_REQUEST() Description To notify VBUS level change (only if USB hardware includes VBUS monitoring) Called when USB enters in suspend mode Called when USB wakes up Called for each received SOF each 1 ms Note: Available in High and Full speed mode Called when USB host requests to enable/disable remote-wakeup feature when the device supports it When a extra string descriptor must be supported (other than manufacturer, product and serial string) When a specific device setup request must be supported
UDC
UDI -
Linked at compilation
UDD
Note: Numbers are references for tables below.
The UDI API is linked with the UDC module via the UDC descriptor configuration file (see section 7.2)
7
8360C-AVR-09/11
uint16_t udd_get_frame_number() udd_send_wake_up() bool udd_ep_alloc( usb_ep_id_t ep, uint8_t bmAttributes, uint16_t wMaxPacketSize) udd_ep_free(usb_ep_id_t) bool udd_ep_clear_halt(usb_ep_id_t) bool udd_ep_set_halt(usb_ep_id_t) bool udd_ep_is_halted(usb_ep_id_t) bool udd_ep_wait_stall_clear( udd_ep_id_t endp, udd_callback_nohalt_t callback) bool udd_ep_run( usb_ep_id_t endp, bool b_shortpacket, uint8_t *buf, uint32_t u32_size_buf, udd_callback_trans_t callback) udd_ep_abort(usb_ep_id_t endp)
Application Application
UDC
Enables/disables endpoints
UDC Clears/sets/gets the endpoint state (halted or not) UDC/UDI Registers a callback to call when endpoint halt is removed
Starts/stops a data transfer in or out on an endpoint UDI Note: The control endpoint is not authorized here UDI
AVR4900
8360C-AVR-09/11
AVR4900
Table 5-7. UDD callback (5).
Declaration typedef void (*udd_callback_nohalt_t) (void); typedef void (*udd_callback_trans_t) (udd_ep_status_t status, iram_size_t nb_transfered) Description Called when the halt on endpoint is removed. This one is registered via udd_ep_wait_stall_clear(). Called when a transfer request is finished or cancelled. This one is registered via udcdrv_ep_run().
Table 5-8. UDD input for High Speed application only (4).
Declaration uint16_t udd_get_microframe_number() udd_test_mode_j() udd_test_mode_k() udd_test_mode_se0_nak() udd_test_mode_packet () Caller Application UDC UDC UDC UDC Features to test the USB HS device. These are requested to run a USB certification. Description Returns the current micro start of frame number
The global variable udd_g_ctrlreq is declared by UDD, and contains two parts:
- Values updated by UDD and used by UDC & UDIs (Table 5-9) - Values updated by UDC & UDIs and used by UDD (Table 5-10)
Outside the UDD, this variable is processed by udc_process_setup() for UDC and *setup() for UDI (see Figure 6-2).
9
8360C-AVR-09/11
6 Behavior
This section aims to answer advanced USB usage questions and introduce the USB device stack behavior. The stack implementation provides a UDC stack which is managed only by USB interruption. This solution guarantees lowest latency, does not require any wait loop, and guarantees OS compatibility. How long can the USB interrupt routine be blocked? The USB interrupt routine is enabled with low priority, and can be blocked by another interrupt routine with higher priority or a critical code section. Following the USB specification, the AVR USB hardware and software should not have any time limitation except the USB Set Address request (performed during USB enumeration phase to assign USB address). Table 6-1. Set Address timings.
USB host Specification USB org certification tools Windows XP Windows 7, Vista Mac Mini OSX 10.5.8 Ubuntu 8.04, Ubuntu 9, Open Suse 11.1 Fedora 9, Fedora 10 Note: Time maximum (1) 2ms 12ms 48ms 32ms 77ms 29ms 24ms
1. These timings can depend on USB host hardware, but gives a range. Also, this time includes the time for setup retry.
The USB host uses a timeout to reset a non-answering USB device (this time is not specified by the USB specification). Hereunder examples of operating systems timeouts: Table 6-2. OS timeout.
Timeout Control endpoint USB host Specification Windows XP Windows 7, Vista Mac Mini OSX 10.5.8 Ubuntu 8.04, Ubuntu 9, Open Suse 11.1 Fedora 9, Fedora 10 5.3s 5.3s 5.9s 5s 5s 5.3s 5.3s 5.6s 5s 5s Data phase ZLP phase CBW No timeout 19s 19s 11s 30s 30s 9.3s 160s/60s 31s 30s 60s 9.3s 160s/60s 22s 30s 30s Mass storage Data read CSW
10
AVR4900
8360C-AVR-09/11
AVR4900
The following figures describe the interaction between the different layers. Figure 6-1. USB device startup and stop.
App
udc_start()
UDC
udd_enable() udc_attach() udd_attach()
UDD
VBUS high Set D+/- pull-up Reset line Enable Ep control (0) Setup (Ep0) udc_stop() udd_disable() Remove D+/- pull-up
udc_start() udd_enable() VBUS high UDC_VBUS_EVENT(true) udc_attach() udd_attach() Set D+/- pull-up VBUS low UDC_VBUS_EVENT(false) udc_stop() udd_disable() udc_vbus(false) Remove D+/- pull-up udc_vbus(true)
11
8360C-AVR-09/11
UDI
Setup STALLED
UDC
UDD
Setup (Ep0)
Setup ACKED by UDC with data transfer Decode setup ACK it Prepare data transfer
Setup (Ep0) udc_process_setup() IN or OUT (Ep0) IN or OUT (Ep0) ZLP IN or OUT eof_request()
Setup ACKED by UDI with data transfer setup() Decode setup ACK it Prepare data transfer
Setup ACKED by UDC with data transfer split Decode setup ACK it Prepare data transfer
Setup (Ep0) udc_process_setup() IN or OUT (Ep0) req_over_under_run() Prepare new data transfer IN or OUT (Ep0) ZLP IN or OUT eof_request()
NOTE
The udd_g_ctrlreq variable is used to communicate between UDD and UDC/UDIs (see Table 5-9 and Table 5-10).
12
AVR4900
8360C-AVR-09/11
AVR4900
Figure 6-3. Typical enumeration.
UDI-2
SET_ADDRESS request
UDI-1
UDC
UDD
Setup (Ep0)
udc_process_setup() ZLP IN or OUT eof_request() udd_set_address() SET_CONFIGURATION request Setup (Ep0) udc_process_setup() udd_ep_alloc() enable() udd_ep_alloc() enable() ZLP IN or OUT
13
8360C-AVR-09/11
7 Configuration
The configuration is divided into two sections: Application and USB Descriptors. The applications configurations are defined in the conf_usb.h file. This file must be created for each application, and this action requires a basic USB knowledge. The conf_usb.h file must define the following configurations: o USB device configuration o USB interface configuration o USB driver configuration The USB Descriptors configuration is requested when the default configuration provided by Atmel is not used. This configuration information is available for advanced USB users.
14
AVR4900
8360C-AVR-09/11
AVR4900
7.1 USB configuration
7.1.1 USB device configuration The following configuration must be included in the conf_usb.h file of the application, which is the main USB device configuration. Table 7-1. USB Device Configuration.
Define name USB_DEVICE_VENDOR_ID USB_DEVICE_PRODUCT_ID USB_DEVICE_MAJOR_VERSION USB_DEVICE_MINOR_VERSION USB_DEVICE_MANUFACTURE_NAME (2) USB_DEVICE_PRODUCT_NAME USB_DEVICE_SERIAL_NAME
(2) (2) (2)
Description Vendor ID provided by USB org (ATMEL 0x03EB) Product ID (referenced in usb_atmel.h) Major version of the device Minor version of the device Static ASCII name for the manufacture Static ASCII name for the product Static ASCII name to enable and set a serial number Give a pointer on a dynamic ASCII name to enable and set a serial number. Require USB_DEVICE_GET_SERIAL_NAME_LENGTH and ignore USB_DEVICE_SERIAL_NAME. Give the length of dynamic ASCII name used to enable a serial number. Maximum device power (mA) USB attributes to add to enable feature: - USB_CONFIG_ATTR_SELF_POWERED - USB_CONFIG_ATTR_REMOTE_WAKEUP Note: If remote wake feature is enabled, then defines remotewakeup callbacks (see Table 5-2) Force the USB device to run in Low Speed Authorize the USB device to run in High Speed Define the maximum endpoint number used by the device (dont include control endpoint) ATMEL.
USB_DEVICE_GET_SERIAL_NAME_POINTER()
#define USB_DEVICE_MANUFACTURE_NAME
The Define can be omitted, thus the string is removed of USB enumeration. 2. Optional configuration. Comment the define statement to disable it (ex: // #define USB_DEVICE_X).
15
8360C-AVR-09/11
7.1.2 USB Interface configuration The UDI configurations are described in USB Device Class application notes. 7.1.3 USB Drivers configuration The following configuration must be included in the conf_usb.h file of the application. The AVR products provide specific hardware features which can be enabled here. Table 7-2. USB Device Driver Configuration.
Define name
UDD_NO_SLEEP_MGR UDD_ISOCHRONOUS_NB_BANK UDD_BULK_NB_BANK UDD_INTERRUPT_NB_BANK UDD_USB_INT_LEVEL
Values
Only defined 1, 2, 3 1, 2, 3 1, 2, 3 0 to 3
UDD All AVR32 - USBB AVR32 - USBB AVR32 - USBB AVR32 - USBB AVR32 - USBC
Description Remove the management of sleepmgr service Reduces or increases isochronous endpoint buffering. Default value: 2 Reduces or increases bulk endpoint buffering. Default value: 2 Reduces or increases interrupt endpoint buffering. Default value: 1 Sets the USB interrupt level on AVR32 core. Default value: 0 (recommended)
16
AVR4900
8360C-AVR-09/11
AVR4900
Figure 7-1. USB descriptors.
udc_iface_fcnt_t udc_config_t app_udc_config *usb_dev_desc_t *udc_config_speed_t udc_config_speed_t *usb_conf_desc_t **udc_iface_fcnt_t *enable() *disable() *setup() *getsetting()
Device Descriptor Device Configuration Descriptor Device Qualifier Descriptor udc_iface_fcnt_t udc_config_speed_t *usb_conf_desc_t **udc_iface_fcnt_t *enable() *disable() *setup() *getsetting()
Legend:
For more information, see Atmel application note, ASF - USB Device New Class.
17
8360C-AVR-09/11
8 Power consumption
The power modes available on AVR products can be supported by the USB hardware according to USB line state. The USB drivers use the sleepmgr service to manage all these power save modes. When a USB application is created, the sleepmgr service initialization sleepmgr_init() is required.
Table 8-1. Maximum sleep levels supported in USB suspend state on AT32UC3.
USB Power Mode Bus and self power Bus and self power Self power Self power Bus power Bus power Note: USB Speed Mode LS, FS HS LS, FS HS LS, FS HS USB Clock Startup >10ms >3ms <=10ms <=3ms <=10ms <=3ms Sleep mode authorized STANDBY STANDBY STOP STOP STATIC STATIC
Often an external oscillator is used to generate the USB clock. Thus, USB clock startup timing corresponding at oscillator startup timing.
The AT32UC3 family supports easily the power limit (2.5mA) in USB suspend mode. Thus, for any Bus power device application, it is require to: Remove USB_CONFIG_ATTR_SELF_POWERED bit in USB_DEVICE_ATTR define from conf_usb.h file. Use an external oscillator with a low startup time. This value is specified in the board header via BOARD_OSC0_STARTUP_US define. Take care at startup time possibility and see OSCCTRL0 register possibility in AT32UC3 datasheets. An external low drop regulator is required to generate the 3.3V AT32UC3 power supply. When selecting this regulator, be sure its quiescent current does not consume a too large proportion of the global 2.5mA suspend current.
18
AVR4900
8360C-AVR-09/11
AVR4900
8.2 ATxmega sleep modes
All ATxmega sleep modes are described in each ATxmega datasheet Power Manager. The Sleep modes supported by USB drivers are: - in USB IDLE state, the driver needs of the USB clock and authorizes up to IDLE mode. - in USB SUSPEND state, the driver does not need USB clock but requests a minimum timing for restarting clock. Thus, it is supported up to POWER DOWN or STANDBY mode.
Table 8-2. Maximum sleep levels supported in USB suspend state on ATxmega.
USB Power Mode Bus and self power Bus and self power Note: USB Speed Mode LS, FS LS, FS USB Clock Startup >10ms <=10ms Sleep mode authorized STANDBY POWER DOWN
Often the internal oscillator is used to generate the USB clock. Thus, USB clock startup timing is < 10ms.
The ATxmega family supports easily the power limit (2.5mA) in USB suspend mode. Thus, for any Bus power device application, it is require to: Remove USB_CONFIG_ATTR_SELF_POWERED bit in USB_DEVICE_ATTR define from conf_usb.h file. Use the internal oscillator to have a low startup time. An external low drop regulator is required to generate the 3.3V ATxmega power supply. When selecting this regulator, be sure its quiescent current does not consume a too large proportion of the global 2.5mA suspend current.
19
8360C-AVR-09/11
9 Changelog
9.1 8360C-08/12
1. 2. 3. Add new option to implement a dynamic serial number in Error! Reference source not found.. Add ATxmega product information. In features list, fix the High Speed 48Mbit/s by 480Mbit/s.
9.2 8360B-04/11
1. 2. Updated all section concerning Power consumption. Updated UDI and UDD APIs. See sof_notify() and udd_get_microframe_number() description.
9.3 8360A-12/10
Initial revision
20
AVR4900
8360C-AVR-09/11
AVR4900
10 Table of Contents
Features ............................................................................................... 1 1 Introduction ...................................................................................... 1 2 Abbreviations ................................................................................... 2 3 USB Device Application Notes ....................................................... 3 4 Organization ..................................................................................... 4
4.1 Overview.............................................................................................................. 4 4.2 Memory Footprint ................................................................................................ 4 4.3 USB Device stack files ........................................................................................ 5
4.3.1 Common files for all AVR products............................................................................ 5 4.3.2 UDD files depending on selected AVR products ....................................................... 5 4.3.3 Specific file for each application ................................................................................ 5
8 Power consumption....................................................................... 18
8.1 USBB and USBC sleep modes ......................................................................... 18 8.2 ATxmega sleep modes...................................................................................... 19
9 Changelog ...................................................................................... 20
9.1 8360C-08/12...................................................................................................... 20 9.2 8360B-04/11 ...................................................................................................... 20 9.3 8360A-12/10 ...................................................................................................... 20
10 Table of Contents......................................................................... 21
21
8360C-AVR-09/11
Atmel Corporation 2325 Orchard Parkway San Jose, CA 95131 USA Tel: (+1)(408) 441-0311 Fax: (+1)(408) 487-2600 www.atmel.com
Atmel Asia Limited Unit 01-5 & 16, 19F BEA Tower, Milennium City 5 418 Kwun Tong Road Kwun Tong, Kowloon HONG KONG Tel: (+852) 2245-6100 Fax: (+852) 2722-1369
Atmel Munich GmbH Business Campus Parkring 4 D-85748 Garching b. Munich GERMANY Tel: (+49) 89-31970-0 Fax: (+49) 89-3194621
Atmel Japan 9F, Tonetsu Shinkawa Bldg. 1-24-8 Shinkawa Chou-ku, Tokyo 104-0033 JAPAN Tel: (+81) 3523-3551 Fax: (+81) 3523-7581
2011 Atmel Corporation. All rights reserved. Atmel , Atmel logo and combinations thereof, AVR and others are registered trademarks of Atmel Corporation or its subsidiaries. Windows and others are registered trademarks of Microsoft Corporation in U.S. and or other countries. Other terms and product names may be trademarks of others.
Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.
8360C-AVR-09/11