8486
8486
8486
Features
USB 2.0 compliance - Chapter 9 - Control, Bulk, Isochronous and Interrupt transfer types - Low Speed (1.5Mbit/s), Full Speed (12Mbit/s), High Speed (480Mbit/s) data rates Low stack size Real time (OS compliance, no latency) Interrupt driven Speed performance using USB DMA Low power modes USB HUB Major USB classes and ready to use (HID, CDC, MSC, PHDC, AUDIO) Composite device 8-bit and 32-bit AVR platforms GCC and IAR compilers
1 Introduction
This document introduces the USB host 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 embedded host application. Also this USB host stack is oriented low footprint and low power. A full description of this stack is available in this document.
Rev. 8486A-AVR-02/12
2 Abbreviations
ASF: CBW: CDC: CSW: DM or D-: EHCI: FS: HID: HS: LS: MSC: OHCI: PHDC: PIPE: sleepmgr: UDC: UDD: UDI: UHC: UHD: UHI: USB: USBB: USBC: STALL: ZLP: AVR Software Framework Command Block Wrapper (from Mass Storage Class) Communication Device Class Command Status Wrapper (from Mass Storage Class) Data Minus differential line Enhanced Host Controller Interface USB Full Speed Human interface device USB High Speed USB Low Speed Mass Storage Class Open Host Controller Interface Peripheral Health Device Class Data buffer to manage an endpoint transfer in host mode Sleep management service from ASF USB Device Controller USB Device Descriptor USB Device Interface USB Host Controller USB Host Descriptor USB Host Interface Universal Serial Bus USB hardware interface version B for 32-bit Atmel core USB hardware interface version C for 32-bit Atmel core USB token used to stop a USB transaction Zero length packet
Atmel AVR4950
8486A-AVR-02/12
Atmel AVR4950
3 USB host application notes
Several USB host examples are provided by Atmel. For each example, Atmel provides several application notes. Figure 3-1. USB host application notes.
Basic USB knowledge is necessary to understand the USB host class application notes (Classes: HID, CDC, MSC, PHDC, AUDIO). To create a USB host with one of the ASF provided classes, refer directly to the related application note for this USB class. The USB host stack and USB host vendor class application notes are designed for advanced USB developers.
3
8486A-AVR-02/12
4 Organization
4.1 Overview
The USB host stack is divided into three parts: The USB Host Controller (UHC), providing USB Chapter 9 compliance The USB Host Interface (UHI), providing USB Class compliance The USB Host Driver (UHD), providing the USB interface for each Atmel product NOTE The USB host drivers are implemented in full interrupt mode, thus this UHD is a perfect base to create a USB driver for third partys USB stacks. This is applicable either for custom interface or for OHCI/EHCI interface. Figure 4-1. USB host stack architecture.
UHD
In case of dual (device/host) mode, the application note AVR4900: ASF USB Device stack is provided to describe the USB device stack.
Atmel AVR4950
8486A-AVR-02/12
Atmel AVR4950
NOTE The example names including From ASF V1 refer to former implementation of USB host stack from ASF v1.7 which is beyond the scope of this application note. 4.3.1 Common files for all products Files Paths Defines USB constants common/services/usb/ usb_protocol.h* (from usb.org) usb_atmel.h* (from Atmel) UHC files uhc.c/h uhi.h uhd.h Classes Protocols files usb_protocol_<class>.h* UHI files uhi_foo.c/h NOTE common/services/usb/uhc/
common/services/usb/class/<class>/ common/services/usb/class/foo/host/
4.3.2 UHD files depending on selected products NOTE avr32/drivers/usbb/usbb_host.c/h avr32/drivers/usbb/usbb_otg.h* avr32/drivers/usbc/usbc_host.c/h avr32/drivers/usbc/usbc_otg.h*
4.3.3 Specific file for each application Application file to configure USB host stack (see Chapter 7 Configuration, and Table 5-3) usb_conf_host.h
5
8486A-AVR-02/12
Application
External API from UHC Described in this document External API from UHI Described in external UHI documents Internal API Described in this document for USB experts
UHC
UHI -
UHC
Atmel AVR4950
8486A-AVR-02/12
Atmel AVR4950
Table 5-2. External API from UHC Input functions concerning connected devices.
Declaration uint8_t uhc_get_device_number() char* uhc_dev_get_str_manufacturer( uhc_device_t*dev) char* uhc_dev_get_str_product( uhc_device_t*dev) char* uhc_dev_get_str_serial( uhc_device_t*dev) char* uhc_dev_get_str( uhc_device_t*dev, uint8_t str_id) uint16_t uhc_dev_get_power( uhc_device_t*) uhd_speed_t uhc_dev_get_speed( uhc_device_t*) bool uhc_dev_is_high_speed_support( uhc_device_t*) Description Return the number of devices connected. Return the string ASCII manufacturer corresponding at USB device. Return the string ASCII product corresponding at USB device. Return the string ASCII serial corresponding at USB device. Return the USB string ASCII corresponding at the string ID. Get the maximum consumption of a device (mA). Return the current device speed. Return true if it is the device supports high speed.
All UHC callbacks are optional and defined by the user in conf_usb_host.h file for each application. Table 5-3. External API from UHC Callback functions.
Define name UHC_MODE_CHANGE( bool b_host_mode) Description To notify that the USB mode are switched automatically. This is possible only when ID pin is available. To notify that the VBUS level has changed (Available only in USB hardware with VBUS monitoring). To notify that a VBUS error has occurred (Available only in USB hardware with VBUS monitoring). To notify that a device has been connected or disconnected. Called when a USB device or the host have wake up the USB line. Called for each received SOF each 1ms. Note: Available in High and Full speed mode. Called when a USB device configuration must be chosen. Thus, the application can choose either a configuration number for this device or a configuration number 0 to reject it. If callback not defined the configuration 1 is chosen.
UHC_VBUS_CHANGE(bool b_present)
7
8486A-AVR-02/12
Define name
Description Called when a USB device enumeration is completed. The status can be: - UHC_ENUM_SUCCESS Device is bus enumerated with at least one supported interface. - UHC_ENUM_UNSUPPORTED All interfaces are not supported by UHIs. - UHC_ENUM_OVERCURRENT Device power can not be supported - UHC_ENUM_FAIL A problem has been occurred during USB enumeration. - UHC_ENUM_HARDWARE_LIMIT USB hardware can not support it. Not enough free pipes. - UHC_ENUM_SOFTWARE_LIMIT USB software can not support it. Implementaion limit. - UHC_ENUM_MEMORY_LIMIT USB software can not support it. Not enough memory.
UHC
UHI -
Linked at compilation
UHD
NOTE Numbers are references for tables below. Table 5-4. UHI input from UHC (1).
Declaration uhc_enum_status_t (*install)(uhc_device_t*) void (*uninstall)(uhc_device_t*) void (*enable)(uhc_device_t*) Description Install interface if supported by new device (allocation of endpoints). Uninstall the interface if installed for this device. Called to start the USB interface of the device.
Atmel AVR4950
8486A-AVR-02/12
Atmel AVR4950
Declaration void (*sof_notify)(bool b_micro) Note: Description Called by UHC to notify a SOF event on the enabled USB interface.
The UHI API are stored in USB_HOST_UHI array, see Table 7-1.
UHC/UHI
Add this setup request, in the control endpoint setup queue. (Request timeout is 5s)
UHC
UHC UHC
Enables endpoints (except control endpoint). Disables one endpoint or all endpoints of a device.
9
8486A-AVR-02/12
Declaration bool uhd_ep_run( usb_add_t add, usb_ep_t endp, bool b_shortpacket, uint8_t *buf, iram_size_t buf_size, uint16_t timeout, uhd_callback_trans_t callback) uhd_ep_abort( usb_add_t add, usb_ep_t endp)
Caller
Description
UHI
Starts/stops a data transfer in or out on an endpoint. The schedule of the transfer is managed by UHD. Note: The control endpoint is not authorized here.
UHI
Called when a transfer request is completed or cancelled. This request is registered via uhd_ep_run(). This structure is updated after every attempted transaction, whether successful or not. If the transaction is successful, then the status field is set to: - UHD_TRANS_NOERROR. Otherwise, it is set according to the following transmission error types: - UHD_TRANS_CRC, CRC error in data packet. - UHD_TRANS_DISCONNECT, device is disconnected. - UHD_TRANS_DT_MISMATCH, data toggle PID did not match the expected value. - UHD_TRANS_STALL, the endpoint returned a STALL PID. - UHD_TRANS_NOT_RESPONDING, Device did not respond to token (IN) or did not provide a handshake (OUT). - UHD_TRANS_PID_FAILURE, Check bits on PID from endpoint failed. - UHD_TRANS_TIMEOUT, Data transmission not completed before timeout. - UHD_TRANS_ABORTED, Data transmission has been aborted.
uhd_trans_status_t
10
Atmel AVR4950
8486A-AVR-02/12
Atmel AVR4950
Table 5-8. UHD input for High Speed application only (4).
Declaration uhd_test_mode_j() uhd_test_mode_k() uhd_test_mode_se0_nak() uhd_test_mode_packet() Caller UHC UHC UHC UHC Description Features to enable a specific signal on a USB HS port. These are requested to run a USB host HS certification.
Figure 5-3. uhc_device_t definition. uhc_device_t g_uhc_device_root usb_dev_desc_t dev_desc usb_conf_desc_t *conf_desc uint8_t address uhd_speed_t speed uhc_device_t *prev uhc_device_t *next uhc_device_t *hub uint8_t hub_port uint16_t power Device Configuration Descriptor Device Descriptor
Legend:
12
Atmel AVR4950
8486A-AVR-02/12
Atmel AVR4950
Figure 6-1. USB manual dual role.
App
Custom event
USB device mode running Custom event udc_stop() Switch from device to host mode
uhc_start()
App
uhc_start()
App can wait before start device mode USB device mode running
udc_start() The ID pin tides to ground. (OTG connector plugged) Stop device auto UHC_MODE_CHANGE(true)
App can wait before start host mode USB host mode running
uhc_start()
USB interrupts
13
8486A-AVR-02/12
App
uhc_start()
UHC_MODE_CHANGE(false)
Start device auto USB device mode running The ID pin tides to ground. (OTG connector plugged) Stop device auto Just to notify application but not mandatory UHC_MODE_CHANGE(true)
14
Atmel AVR4950
8486A-AVR-02/12
Atmel AVR4950
6.2 VBUS management
Figure 6-4. VBUS management.
App
UHC
VBUS always on
UHD
Start host mode USB host mode running Start host mode
uhc_start() uhd_enable()
uhc_stop() uhd_disable()
VBUS controlled by application Start host mode Turn on VBUS uhc_start() uhd_enable() USB host mode running uhc_stop() uhd_disable() Start host mode Turn off VBUS
VBUS controlled by USB Driver (VBOF) Start host mode uhc_start() uhd_enable() Turn on VBUS VBUS high VBUS error
UHC_VBUS_CHANGE(true) USB host mode running UHC_VBUS_ERROR() uhc_stop() Start host mode uhd_disable()
USB interrupts
15
8486A-AVR-02/12
UHC
UHD
Device plugged
UHC_CONNECTION_EVENT()
uhc_connection(true) uhd_send_reset() Reset callback SOF uhc_sof() uhd_send_reset() End of reset End of reset
USB RESET
USB RESET Reset callback uhc_sof() USB IDLE 100ms uhd_setup_request() Setup ACK Setup request Get device descriptor (Default control endpoint size = 64B, and fill uhc_device_t.dev_desc.bMaxPa cketSize0) Setup callback uhc_sof() USB IDLE 20ms uhd_send_reset() End of reset USB RESET Reset callback uhc_sof() USB IDLE 100ms uhd_setup_request() Setup request Set address USB IDLE 20ms Setup request Get device descriptor (Fill uhc_device_t.dev_desc) Setup callback SOF uhc_sof() uhd_setup_request() USB interrupts Setup SOF IN ACK SOF
NOTE NOTE
This sequence is the same for the device connected thru a USB HUB, but the connection and reset events are managed via USB HUB setup request. When the USB device enumeration fails four times, the USB line of the device is set in USB SUSPEND mode.
16
Atmel AVR4950
8486A-AVR-02/12
Atmel AVR4950
6.4 Device enumeration
Figure 6-6. USB device enumeration (single USB configuration).
UHI UHI
Send request Get configuration descriptor 1 Fill uhc_device_t.conf_desc
UHC
UHD
uhi_install() No supported Call the UHIs to install (allocate endpoints) the new supported USB interface. uhi_install() uhd_ep_alloc() Supported Send request Set configuration 1 UHC_ENUM_EVENT( UHC_ENUM_SUCCESS) Enable all UHI modules. The UHI module(s) can send a setup interface request.
Setup end The UHI module receives the result of the setup interface request and can continue the initialization of USB interface. Here, a transfer is start on an endpoint.
uhd_ep_run()
USB interrupts
NOTE
Here the callback UHC_DEVICE_CONF() is not defined, thus the device configuration 1 is chosen by default.
17
8486A-AVR-02/12
UHI
UHC_DEVICE_CONF () Which return the configuration number chosen (N) Send request Get configuration descriptor N Fill uhc_device_t.conf_desc
UHC
UHD
uhi_valid() Call the UHIs to find unless one supported USB interface and allocate endpoints of valid interface(s). uhi_alloc() uhd_ep_alloc() uhd_setup_request() Send request Set configuration N UHC_ENUM_EVENT() Setup end
USB interrupts
18
Atmel AVR4950
8486A-AVR-02/12
Atmel AVR4950
7 Configuration
The applications configurations are defined in the conf_usb_host.h file. This file must be created for each application, and this action requires a basic USB knowledge. The conf_usb_host.h file defines the following configurations: USB host configuration USB host interface configuration USB host driver configuration
USB_HOST_POWER_MAX USB_HOST_HUB_SUPPORT
(1)
1. Optional configuration. Comment the define statement to disable it (ex: // #define USB_HOST_X).
19
8486A-AVR-02/12
Description By default, when the ID pin is available (USB_ID defined), the host or device mode are stopped and started automatically when the ID pin changes. This automatically start can be disabled, but the automatically stop mode remains.
USB_ID
AVR32_USBC_USB_ or AVR32_USBC_USB_x
AVR32 - USBC
USB_VBOF
AVR32_USBB_USB_VBOF_x_x
AVR32 - USBB
USB_VBOF
AVR32_USBC_USB_VBOF or AVR32_USBC_USB_VBOF_x
AVR32 - USBC
USB_VBOF_ACTIVE_LEVEL
LOW or HIGH
20
Atmel AVR4950
8486A-AVR-02/12
Atmel AVR4950
8 USB HUB support
The USB host stack is able to support a USB tree through a USB HUB. However, the USB hardware interface provided on Atmel parts can limit the USB tree. Table 8-1. USB HUB hardware limitation.
USB hardware interface USBB Description Number of pipes limited to seven or eight, but control endpoint multiplexed in one pipe. Does not support multiple USB speeds in same time on a USB tree. Number of pipes limited to seven, but control endpoint multiplexed in one pipe. Supports pipe multiplexing (1). Does not support multiple USB speeds in same time on a USB tree. 1. To avoid the limitation due to pipes number a multiplexing of the pipes is possible. However, the transfer scheduling must be done by software (UHD driver) instead of by USB hardware.
USBC
Note:
21
8486A-AVR-02/12
9 Power consumption
The power modes available on Atmel products are supported by the USB hardware. All USB drivers implement the feature from sleepmgr service. Thus, the sleepmgr service initialization sleepmgr_init() must be called by the application prior any calls to the USB stack.
NOTE
The sleep modes listed here may not be reached if any other software module than the USB stack requires a less profound sleep mode.
22
Atmel AVR4950
8486A-AVR-02/12
Atmel AVR4950
10 Table of Contents
Atmel AVR4950: ASF - USB Host Stack ............................................ 1 Features ............................................................................................... 1 1 Introduction ...................................................................................... 1 2 Abbreviations ................................................................................... 2 3 USB host application notes ............................................................ 3 4 Organization ..................................................................................... 4
4.1 Overview.............................................................................................................. 4 4.2 Memory Footprint ................................................................................................ 4 4.3 USB host stack files ............................................................................................ 4
4.3.1 Common files for all products .................................................................................... 5 4.3.2 UHD files depending on selected products................................................................ 5 4.3.3 Specific file for each application ................................................................................ 5
7 Configuration ................................................................................. 19
7.1 USB host configuration...................................................................................... 19 7.2 USB host interface configuration....................................................................... 19 7.3 USB host drivers configuration.......................................................................... 19
10 Table of Contents......................................................................... 23
23
8486A-AVR-02/12
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 16F, Shin Osaki Kangyo Bldg. 1-6-4 Osaki Shinagawa-ku Tokyo 104-0032 JAPAN Tel: (+81) 3-6417-0300 Fax: (+81) 3-6417-0370
2012 Atmel Corporation. All rights reserved. Atmel , Atmel logo and combinations thereof, AVR , AVR Studio , megaAVR , and others are registered trademarks of Atmel Corporation or its subsidiaries. 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.
8486A-AVR-02/12