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