SAMV71 Xplained Ultra Software Package 1.3

uhi_cdc.h

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