partially document CDC & RNDIS

2 files changed, 144 insertions, 131 deletions

diff --git a/tinyusb/class/cdc.h b/tinyusb/class/cdc.h
index 7bbeb714f..945c0b818 100644
--- a/tinyusb/class/cdc.h
+++ b/tinyusb/class/cdc.h
@@ -36,16 +36,11 @@
 */

 /**************************************************************************/

 

-/** \file

- *  \brief CDC Class Driver

- *

- *  \note TBD

- */

-

 /** 

  *  \addtogroup ClassDriver Class Driver

  *  @{

- *  \defgroup ClassDriver_CDC Communication Device Class

+ *  \defgroup ClassDriver_CDC Communication Device Class (CDC)

+ *            Currently only Abstract Control Model subclass is supported

  *  @{

  */

 

diff --git a/tinyusb/class/cdc_host.h b/tinyusb/class/cdc_host.h
index b723d5fbe..786eeb205 100644
--- a/tinyusb/class/cdc_host.h
+++ b/tinyusb/class/cdc_host.h
@@ -1,124 +1,142 @@
-/**************************************************************************/
-/*!
-    @file     cdc_host.h
-    @author   hathach (tinyusb.org)
-
-    @section LICENSE
-
-    Software License Agreement (BSD License)
-
-    Copyright (c) 2013, hathach (tinyusb.org)
-    All rights reserved.
-
-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions are met:
-    1. Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
-    2. Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in the
-    documentation and/or other materials provided with the distribution.
-    3. Neither the name of the copyright holders nor the
-    names of its contributors may be used to endorse or promote products
-    derived from this software without specific prior written permission.
-
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY
-    EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY
-    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-    This file is part of the tinyusb stack.
-*/
-/**************************************************************************/
-
-/** \ingroup TBD
- *  \defgroup TBD
- *  \brief TBD
- *
- *  @{
- */
-
-#ifndef _TUSB_CDC_HOST_H_
-#define _TUSB_CDC_HOST_H_
-
-#include "common/common.h"
-#include "host/usbh.h"
-#include "cdc.h"
-
-#ifdef __cplusplus
- extern "C" {
-#endif
-
-typedef enum {
-  CDC_PIPE_ERROR = 0,
-  CDC_PIPE_NOTIFICATION,
-  CDC_PIPE_DATA_IN,
-  CDC_PIPE_DATA_OUT
-}cdc_pipeid_t;
-
-//--------------------------------------------------------------------+
-// APPLICATION PUBLIC API
-//--------------------------------------------------------------------+
-bool tusbh_cdc_serial_is_mounted(uint8_t dev_addr) ATTR_PURE ATTR_WARN_UNUSED_RESULT;
-
-tusb_error_t tusbh_cdc_send(uint8_t dev_addr, void const * p_data, uint32_t length, bool is_notify);
-tusb_error_t tusbh_cdc_receive(uint8_t dev_addr, void * p_buffer, uint32_t length, bool is_notify);
-
-//------------- CDC Application Callback -------------//
-void tusbh_cdc_mounted_cb(uint8_t dev_addr);
-void tusbh_cdc_unmounted_cb(uint8_t dev_addr);
-void tusbh_cdc_xfer_isr(uint8_t dev_addr, tusb_event_t event, cdc_pipeid_t pipe_id, uint32_t xferred_bytes);
-
-
-#if TUSB_CFG_HOST_CDC_RNDIS
-//--------------------------------------------------------------------+
-// RNDIS APPLICATION API
-//--------------------------------------------------------------------+
-bool tusbh_cdc_rndis_is_mounted(uint8_t dev_addr) ATTR_PURE ATTR_WARN_UNUSED_RESULT;
-tusb_error_t tusbh_cdc_rndis_get_mac_addr(uint8_t dev_addr, uint8_t mac_address[6]);
-
-//------------- RNDIS Application Callback (overshadow CDC callbacks) -------------//
-void tusbh_cdc_rndis_mounted_cb(uint8_t dev_addr);
-void tusbh_cdc_rndis_unmounted_cb(uint8_t dev_addr);
-void tusbh_cdc_rndis_xfer_isr(uint8_t dev_addr, tusb_event_t event, cdc_pipeid_t pipe_id, uint32_t xferred_bytes);
-
-
-
-#endif
-
-//--------------------------------------------------------------------+
-// USBH-CLASS API
-//--------------------------------------------------------------------+
-#ifdef _TINY_USB_SOURCE_FILE_
-
-typedef struct {
-  uint8_t interface_number;
-  uint8_t interface_protocol;
-  bool is_rndis;
-  cdc_acm_capability_t acm_capability;
-
-  pipe_handle_t pipe_notification, pipe_out, pipe_in;
-
-} cdch_data_t;
-
-extern cdch_data_t cdch_data[TUSB_CFG_HOST_DEVICE_MAX]; // TODO consider to move to cdch internal header file
-
-void         cdch_init(void);
-tusb_error_t cdch_open_subtask(uint8_t dev_addr, tusb_descriptor_interface_t const *p_interface_desc, uint16_t *p_length) ATTR_WARN_UNUSED_RESULT;
-void         cdch_isr(pipe_handle_t pipe_hdl, tusb_event_t event, uint32_t xferred_bytes);
-void         cdch_close(uint8_t dev_addr);
-
-#endif
-
-#ifdef __cplusplus
- }
-#endif
-
-#endif /* _TUSB_CDC_HOST_H_ */
-
-/** @} */
+/**************************************************************************/

+/*!

+    @file     cdc_host.h

+    @author   hathach (tinyusb.org)

+

+    @section LICENSE

+

+    Software License Agreement (BSD License)

+

+    Copyright (c) 2013, hathach (tinyusb.org)

+    All rights reserved.

+

+    Redistribution and use in source and binary forms, with or without

+    modification, are permitted provided that the following conditions are met:

+    1. Redistributions of source code must retain the above copyright

+    notice, this list of conditions and the following disclaimer.

+    2. Redistributions in binary form must reproduce the above copyright

+    notice, this list of conditions and the following disclaimer in the

+    documentation and/or other materials provided with the distribution.

+    3. Neither the name of the copyright holders nor the

+    names of its contributors may be used to endorse or promote products

+    derived from this software without specific prior written permission.

+

+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY

+    EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

+    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

+    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY

+    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES

+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;

+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

+    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

+

+    This file is part of the tinyusb stack.

+*/

+/**************************************************************************/

+

+/** \addtogroup ClassDriver_CDC Communication Device Class (CDC)

+ *  @{ */

+

+#ifndef _TUSB_CDC_HOST_H_

+#define _TUSB_CDC_HOST_H_

+

+#include "common/common.h"

+#include "host/usbh.h"

+#include "cdc.h"

+

+#ifdef __cplusplus

+ extern "C" {

+#endif

+

+typedef enum {

+  CDC_PIPE_ERROR = 0,

+  CDC_PIPE_NOTIFICATION,

+  CDC_PIPE_DATA_IN,

+  CDC_PIPE_DATA_OUT

+}cdc_pipeid_t;

+

+//--------------------------------------------------------------------+

+// APPLICATION PUBLIC API

+//--------------------------------------------------------------------+

+/** \defgroup CDC_ACM Abtract Control Model (ACM)

+ *  @{ */

+

+bool tusbh_cdc_serial_is_mounted(uint8_t dev_addr) ATTR_PURE ATTR_WARN_UNUSED_RESULT;

+tusb_error_t tusbh_cdc_send(uint8_t dev_addr, void const * p_data, uint32_t length, bool is_notify);

+tusb_error_t tusbh_cdc_receive(uint8_t dev_addr, void * p_buffer, uint32_t length, bool is_notify);

+

+//------------- CDC Application Callback -------------//

+/** \brief 			Callback function that will be invoked when a device with CDC Abstract Control Model interface is mounted

+ * \param[in]	  dev_addr Address of newly mounted device

+ * \note        This callback should be used by Application to set-up interface-related data

+ */

+void tusbh_cdc_mounted_cb(uint8_t dev_addr);

+

+/** \brief 			Callback function that will be invoked when a device with CDC Abstract Control Model interface is unmounted

+ * \param[in] 	dev_addr Address of newly unmounted device

+ * \note        This callback should be used by Application to tear-down interface-related data

+ */

+void tusbh_cdc_unmounted_cb(uint8_t dev_addr);

+

+void tusbh_cdc_xfer_isr(uint8_t dev_addr, tusb_event_t event, cdc_pipeid_t pipe_id, uint32_t xferred_bytes);

+

+/// @}

+

+//--------------------------------------------------------------------+

+// RNDIS APPLICATION API

+//--------------------------------------------------------------------+

+/** \defgroup CDC_RNDIS Remote Network Driver Interface Specification (RNDIS)

+ *  @{ */

+bool tusbh_cdc_rndis_is_mounted(uint8_t dev_addr) ATTR_PURE ATTR_WARN_UNUSED_RESULT;

+tusb_error_t tusbh_cdc_rndis_get_mac_addr(uint8_t dev_addr, uint8_t mac_address[6]);

+

+//------------- RNDIS Application Callback (overshadow CDC callbacks) -------------//

+/** \brief 			Callback function that will be invoked when a device with RNDIS interface is mounted

+ * \param[in]	  dev_addr Address of newly mounted device

+ * \note        This callback should be used by Application to set-up interface-related data

+ */

+void tusbh_cdc_rndis_mounted_cb(uint8_t dev_addr);

+

+/** \brief 			Callback function that will be invoked when a device with RNDIS interface is unmounted

+ * \param[in] 	dev_addr Address of newly unmounted device

+ * \note        This callback should be used by Application to tear-down interface-related data

+ */

+void tusbh_cdc_rndis_unmounted_cb(uint8_t dev_addr);

+

+void tusbh_cdc_rndis_xfer_isr(uint8_t dev_addr, tusb_event_t event, cdc_pipeid_t pipe_id, uint32_t xferred_bytes);

+

+/// @}

+

+//--------------------------------------------------------------------+

+// USBH-CLASS API

+//--------------------------------------------------------------------+

+#ifdef _TINY_USB_SOURCE_FILE_

+

+typedef struct {

+  uint8_t interface_number;

+  uint8_t interface_protocol;

+  bool is_rndis;

+  cdc_acm_capability_t acm_capability;

+

+  pipe_handle_t pipe_notification, pipe_out, pipe_in;

+

+} cdch_data_t;

+

+extern cdch_data_t cdch_data[TUSB_CFG_HOST_DEVICE_MAX]; // TODO consider to move to cdch internal header file

+

+void         cdch_init(void);

+tusb_error_t cdch_open_subtask(uint8_t dev_addr, tusb_descriptor_interface_t const *p_interface_desc, uint16_t *p_length) ATTR_WARN_UNUSED_RESULT;

+void         cdch_isr(pipe_handle_t pipe_hdl, tusb_event_t event, uint32_t xferred_bytes);

+void         cdch_close(uint8_t dev_addr);

+

+#endif

+

+#ifdef __cplusplus

+ }

+#endif

+

+#endif /* _TUSB_CDC_HOST_H_ */

+

+/** @} */