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_