00001 /** 00002 * \file 00003 * 00004 * \brief Interface of the USB Host Controller (UHC) 00005 * 00006 * Copyright (C) 2011-2015 Atmel Corporation. All rights reserved. 00007 * 00008 * \asf_license_start 00009 * 00010 * \page License 00011 * 00012 * Redistribution and use in source and binary forms, with or without 00013 * modification, are permitted provided that the following conditions are met: 00014 * 00015 * 1. Redistributions of source code must retain the above copyright notice, 00016 * this list of conditions and the following disclaimer. 00017 * 00018 * 2. Redistributions in binary form must reproduce the above copyright notice, 00019 * this list of conditions and the following disclaimer in the documentation 00020 * and/or other materials provided with the distribution. 00021 * 00022 * 3. The name of Atmel may not be used to endorse or promote products derived 00023 * from this software without specific prior written permission. 00024 * 00025 * 4. This software may only be redistributed and used in connection with an 00026 * Atmel microcontroller product. 00027 * 00028 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED 00029 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 00030 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 00031 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR 00032 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 00033 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 00034 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 00035 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 00036 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 00037 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 00038 * POSSIBILITY OF SUCH DAMAGE. 00039 * 00040 * \asf_license_stop 00041 * 00042 */ 00043 /* 00044 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a> 00045 */ 00046 00047 //#include "conf_usb_host.h" 00048 00049 #ifndef _UHC_H_ 00050 #define _UHC_H_ 00051 00052 #include "USBHDriver.h" 00053 00054 #ifdef __cplusplus 00055 extern "C" { 00056 #endif 00057 00058 /** 00059 * \ingroup usb_host_group 00060 * \defgroup USBH_group USB host Controller (UHC) 00061 * 00062 * The UHC provides a high-level abstraction of the usb host. 00063 * You can use these functions to control the main host state 00064 * (start/suspend/resume/...). 00065 * 00066 * \section USB_HOST_CONF USB host user configuration 00067 * The following USB host configuration must be included in the conf_usb_host.h 00068 * file of the application. 00069 * 00070 * USB_HOST_UHI (List of UHI APIs)<br> 00071 * Define the list of UHI supported by USB host. (Ex.: UHI_MSC,UHI_HID_MOUSE). 00072 * 00073 * USB_HOST_POWER_MAX (mA)<br> 00074 * Maximum current allowed on Vbus. 00075 * 00076 * USB_HOST_HS_SUPPORT (Only defined)<br> 00077 * Authorize the USB host to run in High Speed. 00078 * 00079 * USB_HOST_HUB_SUPPORT (Only defined)<br> 00080 * Authorize the USB HUB support. 00081 * 00082 * \section USB_HOST_CALLBACK USB host user callback 00083 * The following optional USB host callback can be defined in the conf_usb_host.h 00084 * file of the application. 00085 * 00086 * void UHC_MODE_CHANGE(bool b_host_mode)<br> 00087 * To notify that the USB mode are switched automatically. 00088 * This is possible only when ID pin is available. 00089 * 00090 * void UHC_VBUS_CHANGE(bool b_present)<br> 00091 * To notify that the Vbus level has changed 00092 * (Available only in USB hardware with Vbus monitoring). 00093 * 00094 * void UHC_VBUS_ERROR(void)<br> 00095 * To notify that a Vbus error has occurred 00096 * (Available only in USB hardware with Vbus monitoring). 00097 * 00098 * void UHC_CONNECTION_EVENT(USBH_device_t* dev,bool b_present)<br> 00099 * To notify that a device has been connected or disconnected. 00100 * 00101 * void UHC_WAKEUP_EVENT(void)<br> 00102 * Called when a USB device or the host have wake up the USB line. 00103 * 00104 * void UHC_SOF_EVENT(void)<br> 00105 * Called for each received SOF each 1 ms. 00106 * Available in High and Full speed mode. 00107 * 00108 * uint8_t UHC_DEVICE_CONF(USBH_device_t* dev)<br> 00109 * Called when a USB device configuration must be chosen. 00110 * Thus, the application can choose either a configuration number 00111 * for this device or a configuration number 0 to reject it. 00112 * If callback not defined the configuration 1 is chosen. 00113 * 00114 * void UHC_ENUM_EVENT(USBH_device_t* dev, uint8_t b_status)<br> 00115 * Called when a USB device enumeration is completed or fail. 00116 * 00117 * @{ 00118 */ 00119 00120 // Descriptor storage in internal RAM 00121 #if (defined UHC_DATA_USE_HRAM_SUPPORT) 00122 # if defined(__GNUC__) 00123 # define UHC_DATA(x) COMPILER_WORD_ALIGNED __attribute__((__section__(".data_hram0"))) 00124 # define UHC_BSS(x) COMPILER_ALIGNED(x) __attribute__((__section__(".bss_hram0"))) 00125 # elif defined(__ICCAVR32__) 00126 # define UHC_DATA(x) COMPILER_ALIGNED(x) __data32 00127 # define UHC_BSS(x) COMPILER_ALIGNED(x) __data32 00128 # endif 00129 #else 00130 # define UHC_DATA(x) COMPILER_ALIGNED(x) 00131 # define UHC_BSS(x) COMPILER_ALIGNED(x) 00132 #endif 00133 00134 /** 00135 * \brief Structure to store device information 00136 */ 00137 typedef struct{ 00138 //! USB device descriptor 00139 USBDeviceDescriptor dev_desc; 00140 00141 // USB address 00142 uint8_t address; 00143 00144 // USB speed 00145 USBH_Speed_t speed; 00146 00147 //! USB current configuration descriptor 00148 USBConfigurationDescriptor *conf_desc; 00149 00150 #ifdef USB_HOST_LPM_SUPPORT 00151 USB_DeviceLPMDescriptor *lpm_desc; 00152 #endif 00153 00154 #ifdef USB_HOST_HUB_SUPPORT 00155 USBH_device_t *prev; 00156 USBH_device_t *next; 00157 USBH_device_t *hub; 00158 // Power consumption if device or devices connected to a HUB downstream port are NUB powered 00159 uint16_t power; 00160 uint8_t hub_port; 00161 #endif 00162 } USBH_device_t; 00163 00164 /** 00165 * \brief Enumeration status 00166 * Used in UHC_ENUM_EVENT() callback 00167 * when a USB device enumeration is completed. 00168 */ 00169 typedef enum { 00170 //! Device is enumerated. 00171 //! The supported USB device interfaces has been enabled. 00172 UHC_ENUM_SUCCESS = 0, 00173 00174 //! None of the interfaces are supported by the UHIs. 00175 UHC_ENUM_UNSUPPORTED, 00176 00177 //! Device power is not supported. 00178 UHC_ENUM_OVERCURRENT, 00179 00180 //! A problem occurred during USB enumeration. 00181 UHC_ENUM_FAIL, 00182 00183 //! USB hardware can not support it. Not enough free pipes. 00184 UHC_ENUM_HARDWARE_LIMIT, 00185 00186 //! USB software can not support it. Implementation limit. 00187 UHC_ENUM_SOFTWARE_LIMIT, 00188 00189 //! USB software can not support it. Not enough memory. 00190 UHC_ENUM_MEMORY_LIMIT, 00191 00192 //! The device has been disconnected during USB enumeration. 00193 UHC_ENUM_DISCONNECT, 00194 } USBH_enum_status_t; 00195 00196 /** 00197 * \name Functions to control the USB host stack 00198 * 00199 * @{ 00200 */ 00201 00202 /*! \brief Starts the host mode 00203 */ 00204 void USBH_start(void); 00205 00206 /*! \brief Stops the host mode 00207 * 00208 * \param b_id_stop Stop USB ID pin management, if true. 00209 */ 00210 void USBH_stop(bool b_id_stop); 00211 00212 /** 00213 * \brief Suspends a USB line 00214 * 00215 * \param b_remotewakeup Authorize the remote wakeup features, if true 00216 */ 00217 void USBH_suspend(bool b_remotewakeup); 00218 00219 /** 00220 * \brief Test if the suspend state is enabled on the USB line. 00221 * \return USB line in SUSPEND state or device not connected, if true 00222 */ 00223 bool USBH_is_suspend(void); 00224 00225 /** 00226 * \brief Resumes the USB line 00227 */ 00228 void USBH_resume(void); 00229 00230 #ifdef USB_HOST_LPM_SUPPORT 00231 /** 00232 * \brief Suspends a USB line through LPM feature 00233 * 00234 * \param b_remotewakeup Authorize the remote wakeup features, if true 00235 * \param besl Best effort service latency value 00236 * 00237 * \return flase if the LPM is not supported by USB Device 00238 */ 00239 bool USBH_suspend_lpm(bool b_remotewakeup, uint8_t besl); 00240 #endif // USB_HOST_LPM_SUPPORT 00241 00242 //@} 00243 00244 00245 /** 00246 * \name User functions to manage a device 00247 * 00248 * @{ 00249 */ 00250 00251 /** 00252 * \brief Returns the number of connected devices 00253 * 00254 * \return Number of device connected on USB tree 00255 */ 00256 uint8_t USBH_get_device_number(void); 00257 00258 /** 00259 * \brief Gets the USB string manufacturer from a USB device 00260 * 00261 * This function waits the end of setup requests 00262 * and the timing can be long (3ms to 15s). 00263 * Thus, do not call it in an interrupt routine. 00264 * This function allocates a buffer which must be free by user application. 00265 * 00266 * \param dev Device to request 00267 * 00268 * \return Pointer on unicode string, or NULL if function fails. 00269 */ 00270 char* USBH_dev_get_string_manufacturer(USBH_device_t* dev); 00271 00272 00273 /** 00274 * \brief Gets the USB string product from a USB device 00275 * 00276 * This function waits the end of setup requests 00277 * and the timing can be long (3ms to 15s). 00278 * Thus, do not call it in an interrupt routine. 00279 * This function allocates a buffer which must be free by user application. 00280 * 00281 * \param dev Device to request 00282 * 00283 * \return Pointer on unicode string, or NULL if function fails. 00284 */ 00285 char* USBH_dev_get_string_product(USBH_device_t* dev); 00286 00287 00288 /** 00289 * \brief Gets the USB string serial from a USB device 00290 * 00291 * This function waits the end of setup requests 00292 * and the timing can be long (3ms to 15s). 00293 * Thus, do not call it in an interrupt routine. 00294 * This function allocates a buffer which must be free by user application. 00295 * 00296 * \param dev Device to request 00297 * 00298 * \return Pointer on unicode string, or NULL if function fails. 00299 */ 00300 char* USBH_dev_get_string_serial(USBH_device_t* dev); 00301 00302 /** 00303 * \brief Gets a USB string from a USB device 00304 * 00305 * This function waits the end of setup requests 00306 * and the timing can be long (3ms to 15s). 00307 * Thus, do not call it in an interrupt routine. 00308 * This function allocates a buffer which must be free by user application. 00309 * 00310 * \param dev Device to request 00311 * \param str_id String ID requested 00312 * 00313 * \return Pointer on unicode string, or NULL if function fails. 00314 */ 00315 char* USBH_dev_get_string(USBH_device_t* dev, uint8_t str_id); 00316 00317 /** 00318 * \brief Gets the maximum consumption of a device (mA) 00319 * 00320 * \param dev Device to request 00321 * 00322 * \return Maximum consumption of the device (mA) 00323 */ 00324 uint16_t USBH_dev_get_power(USBH_device_t* dev); 00325 00326 /** 00327 * \brief Returns the current device speed 00328 * 00329 * \param dev Device to request 00330 * 00331 * \return Device speed 00332 */ 00333 USBH_Speed_t USBH_dev_get_speed(USBH_device_t* dev); 00334 00335 /** 00336 * \brief Tests if the device supports the USB high speed 00337 * This function can wait the end of a setup request 00338 * and the timing can be long (1ms to 5s). 00339 * Thus, do not call it in an interrupt routine. 00340 * 00341 * \param dev Device to request 00342 * 00343 * \return True, if high speed is supported 00344 */ 00345 bool USBH_dev_is_high_speed_support(USBH_device_t* dev); 00346 00347 //@} 00348 00349 //@} 00350 00351 /** 00352 * \ingroup usb_group 00353 * \defgroup usb_host_group USB Stack Host 00354 * 00355 * This module includes USB Stack Host implementation. 00356 * The stack is divided in three parts: 00357 * - USB Host Controller (UHC) provides USB chapter 9 compliance 00358 * - USB Host Interface (UHI) provides USB Class compliance 00359 * - USB Host Driver (UHD) provides USB Driver for each Atmel MCU 00360 00361 * Many USB Host applications can be implemented on Atmel MCU. 00362 * Atmel provides the application note AVR4950 about USB Host Stack general 00363 * information. 00364 * 00365 * @{ 00366 */ 00367 00368 //! @} 00369 00370 #ifdef __cplusplus 00371 } 00372 #endif 00373 00374 /** 00375 * \ingroup USBH_group 00376 * \defgroup USBH_basic_use_case_setup_prereq USB Host Controller (UHC) - Prerequisites 00377 * Common prerequisites for all USB hosts. 00378 * 00379 * This module is based on USB host stack full interrupt driven and supporting 00380 * \ref sleepmgr_group sleepmgr. For AVR and SAM3/4 devices the 00381 * \ref clk_group clock services is supported. For SAMD21 devices the 00382 * \ref asfdoc_sam0_system_clock_group clock driver is supported. 00383 * 00384 * The following procedure must be executed to setup the project correctly: 00385 * - Specify the clock configuration: 00386 * - UC3 and SAM3/4 devices without USB high speed support need 48MHz clock input.\n 00387 * You must use a PLL and an external OSC. 00388 * - UC3 and SAM3/4 devices with USB high speed support need 12MHz clock input.\n 00389 * You must use an external OSC. 00390 * - UC3 devices with USBC hardware need CPU frequency higher than 25MHz. 00391 * - SAMD21 devices without USB high speed support need 48MHz clock input.\n 00392 * You must use a DFLL and an external OSC. 00393 * - In conf_board.h, the define CONF_BOARD_USB_PORT must be added to enable USB lines. 00394 * (Not mandatory for all boards) 00395 * - Enable interrupts 00396 * - Initialize the clock service 00397 * 00398 * The usage of \ref sleepmgr_group sleepmgr service is optional, but recommended to reduce power 00399 * consumption: 00400 * - Initialize the sleep manager service 00401 * - Activate sleep mode when the application is in IDLE state 00402 */ 00403 00404 /** 00405 * \ingroup USBH_group 00406 * \defgroup USBH_basic_use_case_setup_code USB Host Controller (UHC) - Example code 00407 * Common example code for all USB hosts. 00408 * 00409 * Content of conf_usb_host.h: 00410 * \code 00411 #define USB_HOST_POWER_MAX 500 00412 \endcode 00413 * 00414 * Add to application C-file: 00415 * \code 00416 void usb_init(void) 00417 { 00418 USBH_start(); 00419 } 00420 \endcode 00421 */ 00422 00423 /** 00424 * \ingroup USBH_group 00425 * \defgroup USBH_basic_use_case_setup_flow USB Device Controller (UHC) - Workflow 00426 * Common workflow for all USB devices. 00427 * 00428 * -# Ensure that conf_usb_host.h is available and contains the following configuration 00429 * which is the main USB device configuration: 00430 * - \code // Maximum current allowed on Vbus (mA) which depends of 5V generator 00431 #define USB_HOST_POWER_MAX 500 // (500mA) \endcode 00432 * -# Call the USB host stack start function to enable USB Host stack: 00433 * - \code USBH_start(); \endcode 00434 */ 00435 00436 /** 00437 * \page USBH_use_case_1 Enable USB high speed support 00438 * 00439 * In this use case, the USB host is used to support USB high speed. 00440 * 00441 * \section USBH_use_case_1_setup Setup steps 00442 * 00443 * Prior to implement this use case, be sure to have already 00444 * apply the UDI module "basic use case". 00445 * 00446 * \section USBH_use_case_1_usage Usage steps 00447 * 00448 * \subsection USBH_use_case_1_usage_code Example code 00449 * Content of conf_usb_host.h: 00450 * \code 00451 #define USB_HOST_HS_SUPPORT 00452 \endcode 00453 * 00454 * \subsection USBH_use_case_1_usage_flow Workflow 00455 * -# Ensure that conf_usb_host.h is available and contains the following parameters 00456 * required for a USB device high speed (480Mbit/s): 00457 * - \code #define USB_HOST_HS_SUPPORT \endcode 00458 */ 00459 00460 /** 00461 * \page USBH_use_case_2 Multiple classes support 00462 * 00463 * In this use case, the USB host is used to support several USB classes. 00464 * 00465 * \section USBH_use_case_2_setup Setup steps 00466 * 00467 * Prior to implement this use case, be sure to have already 00468 * apply the UDI module "basic use case". 00469 * 00470 * \section USBH_use_case_2_usage Usage steps 00471 * 00472 * \subsection USBH_use_case_2_usage_code Example code 00473 * Content of conf_usb_host.h: 00474 * \code 00475 #define USB_HOST_UHI UHI_HID_MOUSE, UHI_MSC, UHI_CDC 00476 \endcode 00477 * 00478 * \subsection USBH_use_case_2_usage_flow Workflow 00479 * -# Ensure that conf_usb_host.h is available and contains the following parameters: 00480 * - \code #define USB_HOST_UHI UHI_HID_MOUSE, UHI_MSC, UHI_CDC \endcode 00481 * \note USB_HOST_UHI defines the list of UHI supported by USB host. 00482 * Here, you must add all classes that you want to support. 00483 */ 00484 00485 /** 00486 * \page USBH_use_case_3 Dual roles support 00487 * 00488 * In this use case, the USB host and USB device are enabled, it is the dual role. 00489 * 00490 * Note: On the Atmel boards, the switch of USB role is managed automatically by the 00491 * USB stack thank to a USB OTG connector and its USB ID pin. 00492 * For a dual role management without OTG connector, please refer to 00493 * "AVR4950 section 6.1 Dual roles". 00494 * 00495 * \section USBH_use_case_3_setup Setup steps 00496 * 00497 * Prior to implement this use case, be sure to have already 00498 * apply the UDI module "basic use case". 00499 * 00500 * \section USBH_use_case_3_usage Usage steps 00501 * 00502 * \subsection USBH_use_case_3_usage_code Example code 00503 * Content of conf_usb_host.h: 00504 * \code 00505 #define UHC_MODE_CHANGE(b_host_mode) my_callback_mode_change(b_host_mode) 00506 extern void my_callback_mode_change(bool b_host_mode); 00507 \endcode 00508 * 00509 * Add to application C-file: 00510 * \code 00511 void usb_init(void) 00512 { 00513 //udc_start(); 00514 USBH_start(); 00515 } 00516 00517 bool my_host_mode; 00518 void my_callback_mode_change(bool b_host_mode) 00519 { 00520 my_host_mode = b_host_mode; 00521 } 00522 00523 void my_usb_task(void) 00524 { 00525 if (my_host_mode) { 00526 // CALL USB Host task 00527 } else { 00528 // CALL USB Device task 00529 } 00530 } 00531 \endcode 00532 * 00533 * \subsection USBH_use_case_3_usage_flow Workflow 00534 * -# In case of USB dual roles (Device and Host), the USB stack must be enabled 00535 * by USBH_start() and the udc_start() must not be called. 00536 * - \code //udc_start(); 00537 USBH_start(); \endcode 00538 * -# In dual role, to known the current USB mode, the callback to notify the 00539 * mode changes can be used. 00540 * - Ensure that conf_usb_host.h contains the following parameters. 00541 * \code 00542 #define UHC_MODE_CHANGE(b_host_mode) my_callback_mode_change(b_host_mode) 00543 extern void my_callback_mode_change(bool b_host_mode); 00544 \endcode 00545 * - Ensure that application contains the following code: 00546 * \code 00547 bool my_host_mode; 00548 void my_callback_mode_change(bool b_host_mode) 00549 { 00550 my_host_mode = b_host_mode; 00551 } 00552 00553 void my_usb_task(void) 00554 { 00555 if (my_host_mode) { 00556 // CALL USB Host task 00557 } else { 00558 // CALL USB Device task 00559 } 00560 } 00561 \endcode 00562 */ 00563 00564 #endif // _UHC_H_