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_