SAMV71 Xplained Ultra Software Package 1.5

uhi_cdc.h

Go to the documentation of this file.
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_
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines