SAMV71 Xplained Ultra Software Package 1.4

USBH.h

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