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