00001 /** 00002 * \file 00003 * 00004 * \brief USB host driver for Communication Device Class interface. 00005 * 00006 * Copyright (C) 2012-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 _UHI_CDC_H_ 00048 #define _UHI_CDC_H_ 00049 00050 #include "conf_usb_host.h" 00051 #include "CDCRequests.h" 00052 00053 #include "USBRequests.h" 00054 00055 #include "USBH.h" 00056 #include "uhi.h" 00057 00058 #ifdef __cplusplus 00059 extern "C" { 00060 #endif 00061 00062 /** 00063 * \ingroup uhi_cdc_group 00064 * \defgroup uhi_cdc_group_uhc Interface with USB Host Core (UHC) 00065 * 00066 * Define and functions required by UHC. 00067 * 00068 * @{ 00069 */ 00070 00071 //! Global define which contains standard UHI API for UHC 00072 //! It must be added in USB_HOST_UHI define from conf_usb_host.h file. 00073 #define UHI_CDC { \ 00074 .install = uhi_cdc_install, \ 00075 .enable = uhi_cdc_enable, \ 00076 .uninstall = uhi_cdc_uninstall, \ 00077 .sof_notify = uhi_cdc_sof, \ 00078 } 00079 00080 /** 00081 * \name Functions required by UHC 00082 * See \ref uhi_api_t for the function descriptions 00083 * @{ 00084 */ 00085 USBH_enum_status_t uhi_cdc_install(USBH_device_t* dev); 00086 void uhi_cdc_enable(USBH_device_t* dev); 00087 void uhi_cdc_uninstall(USBH_device_t* dev); 00088 void uhi_cdc_sof(bool b_micro); 00089 //@} 00090 00091 //@} 00092 00093 /** 00094 * \ingroup uhi_group 00095 * \defgroup uhi_cdc_group UHI for Communication Device Class 00096 * 00097 * Common APIs used by high level application to use this USB host class. 00098 * These routines are used by memory to transfer its data 00099 * to/from USB CDC endpoint. 00100 * 00101 * See \ref uhi_cdc_quickstart. 00102 * @{ 00103 */ 00104 00105 /** 00106 * \brief Open a port of UHI CDC interface 00107 * 00108 * \param port Communication port number 00109 * \param configuration Pointer on port configuration 00110 * 00111 * \return \c true if the port is available 00112 */ 00113 bool uhi_cdc_open(uint8_t port, CDCLineCoding *configuration); 00114 00115 /** 00116 * \brief Close a port 00117 * 00118 * \param port Communication port number 00119 */ 00120 void uhi_cdc_close(uint8_t port); 00121 00122 /** 00123 * \brief This function checks if a character has been received on the CDC line 00124 * 00125 * \param port Communication port number 00126 * 00127 * \return \c true if a byte is ready to be read. 00128 */ 00129 bool uhi_cdc_is_rx_ready(uint8_t port); 00130 00131 /** 00132 * \brief This function returns the number of character available on the CDC line 00133 * 00134 * \param port Communication port number 00135 * 00136 * \return the number of data received 00137 */ 00138 uint32_t uhi_cdc_get_nb_received(uint8_t port); 00139 00140 /** 00141 * \brief Waits and gets a value on CDC line 00142 * 00143 * \param port Communication port number 00144 * 00145 * \return value read on CDC line 00146 */ 00147 int uhi_cdc_getc(uint8_t port); 00148 00149 /** 00150 * \brief Reads a RAM buffer on CDC line 00151 * 00152 * \param port Communication port number 00153 * \param buf Values read 00154 * \param size Number of value read 00155 * 00156 * \return the number of data remaining 00157 */ 00158 uint32_t uhi_cdc_read_buf(uint8_t port, void* buf, uint32_t size); 00159 00160 /** 00161 * \brief This function checks if a new character sent is possible 00162 * The type int is used to support scanf redirection from compiler LIB. 00163 * 00164 * \param port Communication port number 00165 * 00166 * \return \c true if a new character can be sent 00167 */ 00168 bool uhi_cdc_is_tx_ready(uint8_t port); 00169 00170 /** 00171 * \brief Puts a byte on CDC line 00172 * The type int is used to support printf redirection from compiler LIB. 00173 * 00174 * \param port Communication port number 00175 * \param value Value to put 00176 * 00177 * \return \c true if function was successfully done, otherwise \c false. 00178 */ 00179 int uhi_cdc_putc(uint8_t port, int value); 00180 00181 /** 00182 * \brief Writes a RAM buffer on CDC line 00183 * 00184 * \param port Communication port number 00185 * \param buf Values to write 00186 * \param size Number of value to write 00187 * 00188 * \return the number of data remaining 00189 */ 00190 uint32_t uhi_cdc_write_buf(uint8_t port, const void* buf, uint32_t size); 00191 //@} 00192 00193 /** 00194 * \page uhi_cdc_quickstart Quick start guide for USB host Communication Device Class module (UHI CDC) 00195 * 00196 * This is the quick start guide for the \ref uhi_cdc_group 00197 * "USB host Communication Device Class module (UHI CDC)" with step-by-step instructions on 00198 * how to configure and use the modules in a selection of use cases. 00199 * 00200 * The use cases contain several code fragments. The code fragments in the 00201 * steps for setup can be copied into a custom initialization function, while 00202 * the steps for usage can be copied into, e.g., the main application function. 00203 * 00204 * \section uhi_cdc_basic_use_case Basic use case 00205 * In this basic use case, the "USB Host CDC (Single Class support)" module is used. 00206 * 00207 * The "USB Host CDC (Multiple Classes support)" module usage is described 00208 * in \ref uhi_cdc_use_cases "Advanced use cases". 00209 * 00210 * \section uhi_cdc_basic_use_case_setup Setup steps 00211 * \subsection uhi_cdc_basic_use_case_setup_prereq Prerequisites 00212 * \copydetails uhc_basic_use_case_setup_prereq 00213 * \subsection uhi_cdc_basic_use_case_setup_code Example code 00214 * \copydetails uhc_basic_use_case_setup_code 00215 * \subsection uhi_cdc_basic_use_case_setup_flow Workflow 00216 * \copydetails uhc_basic_use_case_setup_flow 00217 * 00218 * \section uhi_cdc_basic_use_case_usage Usage steps 00219 * 00220 * \subsection uhi_cdc_basic_use_case_usage_code Example code 00221 * Content of conf_usb_host.h: 00222 * \code 00223 #define USB_HOST_UHI UHI_CDC 00224 #define UHI_CDC_CHANGE(dev, b_plug) my_callback_cdc_change(dev, b_plug) 00225 extern bool my_callback_cdc_change(USBH_device_t* dev, bool b_plug); 00226 #define UHI_CDC_RX_NOTIFY() my_callback_cdc_rx_notify() 00227 extern void my_callback_cdc_rx_notify(void); 00228 #include "uhi_cdc.h" // At the end of conf_usb_host.h file 00229 \endcode 00230 * 00231 * Add to application C-file: 00232 * \code 00233 static bool my_flag_cdc_available = false; 00234 bool my_callback_cdc_change(USBH_device_t* dev, bool b_plug) 00235 { 00236 if (b_plug) { 00237 00238 // USB Device CDC connected 00239 my_flag_cdc_available = true; 00240 // Open and configure USB CDC ports 00241 CDCLineCoding cfg = { 00242 .dwDTERate = CPU_TO_LE32(115200), 00243 .bCharFormat = CDC_STOP_BITS_1, 00244 .bParityType = CDC_PAR_NONE, 00245 .bDataBits = 8, 00246 }; 00247 uhi_cdc_open(0, &cfg); 00248 00249 } else { 00250 00251 my_flag_cdc_available = false; 00252 00253 } 00254 } 00255 00256 void my_callback_cdc_rx_notify(void) 00257 { 00258 // Wakeup my_task_rx() task 00259 } 00260 00261 #define MESSAGE "Hello" 00262 void my_task(void) 00263 { 00264 static bool startup = true; 00265 00266 if (!my_flag_cdc_available) { 00267 startup = true; 00268 return; 00269 } 00270 00271 if (startup) { 00272 startup = false; 00273 // Send data on CDC communication port 00274 uhi_cdc_write_buf(0, MESSAGE, sizeof(MESSAGE)-1); 00275 uhi_cdc_putc(0,'\n'); 00276 return; 00277 } 00278 } 00279 00280 void my_task_rx(void) 00281 { 00282 while (uhi_cdc_is_rx_ready(0)) { 00283 int value = uhi_cdc_getc(0); 00284 } 00285 } 00286 \endcode 00287 * 00288 * \subsection uhi_cdc_basic_use_case_setup_flow Workflow 00289 * -# Ensure that conf_usb_host.h is available and contains the following configuration 00290 * which is the USB host CDC configuration: 00291 * - \code #define USB_HOST_UHI UHI_CDC \endcode 00292 * \note It defines the list of UHI supported by USB host. 00293 * - \code #define UHI_CDC_CHANGE(dev, b_plug) my_callback_cdc_change(dev, b_plug) 00294 extern bool my_callback_cdc_change(USBH_device_t* dev, bool b_plug); \endcode 00295 * \note This callback is called when a USB device CDC is plugged or unplugged. 00296 * The communication port can be opened and configured here. 00297 * - \code #define UHI_CDC_RX_NOTIFY() my_callback_cdc_rx_notify() 00298 extern void my_callback_cdc_rx_notify(void); \endcode 00299 * \note This callback is called when a new data are received. 00300 * This can be used to manage data reception through interrupt and avoid pooling. 00301 * -# The CDC data access functions are described in \ref uhi_cdc_group. 00302 * 00303 * \section uhi_cdc_use_cases Advanced use cases 00304 * For more advanced use of the UHI CDC module, see the following use cases: 00305 * - \subpage uhc_use_case_1 00306 * - \subpage uhc_use_case_2 00307 * - \subpage uhc_use_case_3 00308 */ 00309 00310 00311 #ifdef __cplusplus 00312 } 00313 #endif 00314 #endif // _UHI_CDC_H_