SAMV71 Xplained Ultra Software Package 1.5

USBH.h

Go to the documentation of this file.
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_
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines