SAMV71 Xplained Ultra Software Package 1.5

USBHDriver.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  * \file
00031  *
00032  * \brief Common API for USB Host Drivers (UHD)
00033  */
00034 /*
00035  * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
00036  */
00037 
00038 #ifndef _UHD_H_
00039 #define _UHD_H_
00040 
00041 #include "USBDescriptors.h"
00042 #include "USBRequests.h"
00043 #include "board.h"
00044 
00045 
00046 #ifdef __cplusplus
00047 extern "C" {
00048 #endif
00049 
00050 /**
00051  * \ingroup usb_host_group
00052  * \defgroup uhd_group USB Host Driver (UHD)
00053  *
00054  * The UHD driver provides a low-level abstraction of the host
00055  * controller hardware. Most events coming from the hardware such as
00056  * interrupts may cause the UHD performing function call in UHC and UHI.
00057  *
00058  * @{
00059  */
00060 
00061 //! \brief Device speed
00062 typedef enum {
00063     UHD_SPEED_LOW  = 0,
00064     UHD_SPEED_FULL = 1,
00065     UHD_SPEED_HIGH = 2,
00066 } USBH_Speed_t;
00067 
00068 /**
00069  * \brief Endpoint transfer status
00070  * The status field is updated after each transaction attempt,
00071  * whether successful or not.
00072  */
00073 typedef enum {
00074     //! Transaction is successful
00075     UHD_TRANS_NOERROR = 0,
00076 
00077     //! Device is disconnected
00078     UHD_TRANS_DISCONNECT,
00079 
00080     //! CRC error in data packet
00081     UHD_TRANS_CRC,
00082 
00083     //! Data toggle PID did not match the expected value
00084     UHD_TRANS_DT_MISMATCH,
00085 
00086     //! The endpoint returned a STALL PID
00087     UHD_TRANS_STALL,
00088 
00089     //! Device did not respond to token (IN)
00090     //! or did not provide a handshake (OUT)
00091     UHD_TRANS_NOTRESPONDING,
00092 
00093     //! Check bits on PID from endpoint failed
00094     UHD_TRANS_PIDFAILURE,
00095 
00096     //! Data transmission not completed before timeout
00097     UHD_TRANS_TIMEOUT,
00098 
00099     //! Data transmission has been aborted
00100     UHD_TRANS_ABORTED,
00101 } USBH_XfrStatus_t;
00102 
00103 /**
00104  * \brief End of reset callback function type.
00105  * Registered by uhd_send_reset()
00106  * Callback called when reset event is completed.
00107  */
00108 typedef void (*uhd_callback_reset_t)(void);
00109 
00110 /**
00111  * \brief Data setup transfer callback function type.
00112  * Registered by USBH_HAL_SetupReq()
00113  * Called during DATA phase when the (payload) buffer is full or empty.
00114  * Then the setup request is halted.
00115  * A new buffer can be provided to continue the DATA phase or
00116  * abort DATA phase.
00117  *
00118  * \param add           USB address of the setup request
00119  * \param payload       To return the next buffer address
00120  * \param payload_size  To return the size of next buffer
00121  *
00122  * \return \c true, if a new buffer is available, otherwise stop the request.
00123  */
00124 typedef bool (*uhd_callback_setup_run_t)(
00125     uint8_t add,
00126     uint8_t **payload,
00127     uint16_t *payload_size );
00128 
00129 /**
00130  * \brief End of setup callback function type.
00131  * Registered by USBH_HAL_SetupReq()
00132  * Called when the setup request is completed.
00133  *
00134  * \param add           USB address of the setup request
00135  * \param status        Transfer status
00136  * \param payload_trans Number of data transfered during DATA phase
00137  */
00138 typedef void (*uhd_callback_setup_end_t)(
00139     uint8_t add,
00140     USBH_XfrStatus_t status,
00141     uint16_t payload_trans);
00142 
00143 /**
00144  * \brief End of transfer callback function type.
00145  * Registered by USBH_HAL_RunEndpoint()
00146  * Callback called by USB interrupt after data transfer or abort (reset,...).
00147  *
00148  * \param add           USB address used by the transfer
00149  * \param status        Transfer status
00150  * \param nb_transfered Number of data transfered
00151  */
00152 typedef void (*uhd_callback_trans_t) (
00153     uint8_t add,
00154     uint8_t ep,
00155     USBH_XfrStatus_t status,
00156     uint32_t nb_transfered);
00157 
00158 /*
00159  * SCB_CleanDCache_by_Addr
00160  * Make the address to be aligned to 32-byte boundary
00161  */
00162 void USBHS_SCB_CleanDCache_by_Addr(uint32_t *addr, int32_t dsize);
00163 /*
00164  * SCB_InvalidateDCache_by_Addr
00165  * Make the address to be aligned to 32-byte boundary
00166  */
00167 void USBHS_SCB_InvalidateDCache_by_Addr(uint32_t *addr, int32_t dsize);
00168 
00169 /**
00170  * \brief Enables the USB host mode
00171  * Start the ID pin management if the ID pin is available.
00172  */
00173 void USBH_HAL_EnableUsbHost(void);
00174 
00175 /**
00176  * \brief Disables the USB host mode
00177  *
00178  * \param b_id_stop  Stop ID pin management, if true.
00179  */
00180 void USBH_HAL_DisableUsb(bool b_id_stop);
00181 
00182 /**
00183  * \brief Returns the speed of connected device
00184  *
00185  * \return Device speed
00186  */
00187 USBH_Speed_t USBH_HAL_GetSpeed(void);
00188 
00189 /**
00190  * \brief Returns the current Start Of Frame (SOF) number
00191  *
00192  * \return current start of frame number.
00193  */
00194 uint16_t USBH_HAL_GetFrameNum(void);
00195 
00196 /**
00197  * \brief Returns the current micro start of frame number
00198  *
00199  * \return current micro start of frame number required in high speed mode.
00200  */
00201 uint16_t USBH_HAL_GetMicroFrameNum(void);
00202 
00203 /**
00204  * \brief Enables the Reset state on the USB line.
00205  *
00206  * \param callback  Callback when reset sequence is finished
00207  */
00208 void USBH_HAL_Reset(uhd_callback_reset_t callback );
00209 
00210 /**
00211  * \brief Enables the suspend state on the USB line.
00212  * The SUSPEND state is enable when SOF are disabled on USB line.
00213  */
00214 void USBH_HAL_Suspend(void);
00215 
00216 /**
00217  * \brief Test if the suspend state is enabled on the USB line.
00218  * \return USB line in SUSPEND state, if true
00219  */
00220 bool USBH_HAL_IsSuspended(void);
00221 
00222 /**
00223  * \brief Enables the IDLE state on the USB line.
00224  * The IDLE state is enable when SOF are present on USB line.
00225  * A Downstream Resume signal can be sent.
00226  */
00227 void USBH_HAL_Resume(void);
00228 
00229 #ifdef USB_HOST_LPM_SUPPORT
00230 /**
00231  * \brief Enables the suspend L1 state on the USB line.
00232  * The SUSPEND LPM state is enable when a LPM transaction is done.
00233  *
00234  * \param b_remotewakeup Authorize the remote wakeup features, if true
00235  * \param besl Best effort service latency value
00236  *
00237  * \return USB line in SUSPEND state, if true
00238  */
00239 bool uhd_suspend_lpm(bool b_remotewakeup, uint8_t besl);
00240 #endif // USB_HOST_LPM_SUPPORT
00241 
00242 /**
00243  * \brief Add a setup request in the control endpoint setup queue.
00244  * Note: Request timeout is 5s.
00245  *
00246  * \param add           USB address of control endpoint
00247  * \param req           Setup request definition
00248  * \param payload       Buffer to use in setup DATA phase
00249  * \param payload_size  Size of buffer used in DATA phase
00250  * \param callback_run  Callback to call if buffer is empty or full
00251  * \param callback_end  Callback to call when request is finish
00252  *
00253  * \return \c true if the request has been accepted, otherwise \c false.
00254  * Note: The swap of "req.wValues" from uin16_t to le16_t is done by UHD.
00255  */
00256 bool USBH_HAL_SetupReq(
00257     uint8_t add,
00258     USBGenericRequest *req,
00259     uint8_t *payload,
00260     uint16_t payload_size,
00261     uhd_callback_setup_run_t callback_run,
00262     uhd_callback_setup_end_t callback_end);
00263 
00264 
00265 
00266 /**
00267  * \name Endpoint Management
00268  *
00269  * The following functions allow drivers to create and remove
00270  * endpoints, as well as set, clear and query their "halted" and
00271  * "wedged" states.
00272  */
00273 //@{
00274 
00275 /**
00276  * \brief Configures and enables a control endpoint 0
00277  *
00278  * \param add              USB address of endpoint
00279  * \param ep_size          Endpoint control maximum size
00280  *
00281  * \return \c 1 if the endpoint is enabled, otherwise \c 0.
00282  */
00283 bool USBH_HAL_ConfigureControlPipe(uint8_t add, uint16_t ep_size);
00284 
00285 /**
00286  * \brief Configures and enables an endpoint
00287  *
00288  * \param add              USB address of endpoint
00289  * \param ep_desc          Endpoint descriptor
00290  *
00291  * \return \c 1 if the endpoint is enabled, otherwise \c 0.
00292  */
00293 bool USBH_HAL_ConfigurePipe(uint8_t add, USBEndpointDescriptor *ep_desc);
00294 
00295 /**
00296  * \brief Disables an endpoint or all endpoint of a device
00297  *
00298  * \param add              USB address of endpoint
00299  * \param endp             Endpoint number and direction (USB_EP_DIR_IN/OUT).
00300  *                         Remove all endpoints of USB address, if 0xFF.
00301  */
00302 void USBH_HAL_FreePipe(uint8_t add, uint8_t endp);
00303 
00304 /**
00305  * \brief Allows to receive or send data on an endpoint
00306  *
00307  * If a USB DMA is available, the driver uses it to transfer endpoint data
00308  * from or to internal RAM.
00309  * When the transfer is finished or aborted (stall, reset, ...),
00310  * the \a callback is called. This callback returns the transfer status
00311  * and eventually the number of byte transfered.
00312  * Note: The control endpoint is not authorized.
00313  *
00314  * \param add           USB address of endpoint
00315  * \param endp          Endpoint number
00316  * \param b_shortpacket Enabled automatic short packet
00317  * \param buf           Buffer on Internal RAM to send or fill.
00318  *                      It must be align, then use COMPILER_WORD_ALIGNED.
00319  * \param buf_size      Buffer size to send or fill
00320  * \param timeout       Transfer timeout (ms)
00321  * \param callback      NULL or function to call at the end of transfer
00322  *
00323  * \warning About \a b_shortpacket, for OUT endpoint it means that
00324  * a short packet or a Zero Length Packet must be sent to the USB line
00325  * to properly close the USB transfer at the end of the data transfer.
00326  * For Bulk and Interrupt IN endpoint, it will automatically stop the transfer
00327  * at the end of the data transfer (received short packet).
00328  *
00329  * \warning About \a timeout, for BULK endpoint with \a timeout set to zero,
00330  * it means that the transfer will never be stopped before transfer done. Since
00331  * most of USB embedded peripherals do not manage the transfer bandwidth by
00332  * peripheral hardware, such a BULK transfer will occupy all USB non-periodic
00333  * transfer bandwidth. In this case, other BULK transfers started later will be
00334  * pending until this transfer is done and bandwidth released. So it is better
00335  * to use BULK transfers with none zero \a timeout.
00336  *
00337  * \return \c 1 if function was successfully done, otherwise \c 0.
00338  */
00339 bool USBH_HAL_RunEndpoint(
00340     uint8_t add,
00341     uint8_t endp,
00342     bool b_shortpacket,
00343     uint8_t *buf,
00344     uint32_t buf_size,
00345     uint16_t timeout,
00346     uhd_callback_trans_t callback);
00347 
00348 /**
00349  * \brief Aborts an on-going transfer on an endpoint
00350  *
00351  * If a transfer is on going, then it is stopped and
00352  * the callback registered is called to signal the end of transfer.
00353  * Note: The control endpoint is not authorized.
00354  *
00355  * \param add           USB address of endpoint
00356  * \param endp          Endpoint to abort
00357  *
00358  */
00359 void USBH_HAL_AbortEndPoint(uint8_t add, uint8_t endp);
00360 
00361 //@}
00362 
00363 
00364 
00365 /**
00366  * \name UHC callbacks to provide for UHD
00367  *
00368  * The following callbacks are used by UHD.
00369  */
00370 //@{
00371 
00372 #ifndef _UHC_H_ /* uhc.h is not included before */
00373 /**
00374  * \brief Starts the host mode
00375  */
00376 extern void USBH_start(void);
00377 
00378 /**
00379  * \brief Stops the host mode
00380  */
00381 extern void USBH_stop(bool b_id_stop);
00382 #endif
00383 
00384 /**
00385  * \brief Notify device connection or disconnection
00386  *
00387  * \param b_plug  Device connection, if true
00388  */
00389 extern void USBH_notify_connection(bool b_plug);
00390 
00391 /**
00392  * \brief Notify each start of frame sent by driver
00393  *
00394  * \param b_micro  It is a micro start of frame, if true
00395  */
00396 extern void USBH_notify_sof(bool b_micro);
00397 
00398 /**
00399  * \brief Notify that a resume bus occurs
00400  * A resume can occur after a downstream or an upstream resume.
00401  */
00402 extern void USBH_notify_resume(void);
00403 
00404 #ifdef USB_HOST_LPM_SUPPORT
00405 /**
00406  * \brief Notify that a resume bus occurs after a L1 state
00407  * A resume can occur after a downstream or an upstream resume.
00408  */
00409 extern void USBH_notify_resume_lpm(void);
00410 #endif
00411 
00412 //uint32_t* Memory_Align(uint32_t* StartAddr, uint32_t align_num);
00413 
00414 //@}
00415 
00416 //@}
00417 
00418 #ifdef __cplusplus
00419 }
00420 #endif
00421 #endif // _UHD_H_
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines