SAMV71 Xplained Ultra Software Package 1.4

USBHDriver.h

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