document cdc

3 files changed, 68 insertions, 12 deletions

diff --git a/demos/host/src/tusb_config.h b/demos/host/src/tusb_config.h
index b83fa51f2..05c415b13 100644
--- a/demos/host/src/tusb_config.h
+++ b/demos/host/src/tusb_config.h
@@ -72,12 +72,12 @@
 #define TUSB_CFG_HOST_ENUM_BUFFER_SIZE 255

 

 //------------- CLASS -------------//

-#define TUSB_CFG_HOST_HUB           1

-#define TUSB_CFG_HOST_HID_KEYBOARD  1

+#define TUSB_CFG_HOST_HUB           0

+#define TUSB_CFG_HOST_HID_KEYBOARD  0

 #define TUSB_CFG_HOST_HID_MOUSE     0

 #define TUSB_CFG_HOST_HID_GENERIC   0

-#define TUSB_CFG_HOST_MSC           1

-#define TUSB_CFG_HOST_CDC           0

+#define TUSB_CFG_HOST_MSC           0

+#define TUSB_CFG_HOST_CDC           1

 #define TUSB_CFG_HOST_CDC_RNDIS     0

 

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

diff --git a/tinyusb/class/cdc_host.h b/tinyusb/class/cdc_host.h
index e73d96d60..9a32cc896 100644
--- a/tinyusb/class/cdc_host.h
+++ b/tinyusb/class/cdc_host.h
@@ -50,23 +50,65 @@
  extern "C" {

 #endif

 

+/// CDC Pipe ID, used to indicate which pipe the API is addressing to (Notification, Out, In)

 typedef enum {

-  CDC_PIPE_ERROR = 0,

-  CDC_PIPE_NOTIFICATION,

-  CDC_PIPE_DATA_IN,

-  CDC_PIPE_DATA_OUT

+  CDC_PIPE_ERROR = 0    , ///< Invalid Pipe ID

+  CDC_PIPE_NOTIFICATION , ///< Notificaiton pipe

+  CDC_PIPE_DATA_IN      , ///< Data in pipe

+  CDC_PIPE_DATA_OUT       ///< Data out pipe

 }cdc_pipeid_t;

 

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

 // APPLICATION PUBLIC API

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

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

- *  @{ */

+/** \addtogroup CDC_Serial Serial

+ *  @{

+ *  \defgroup   CDC_Serial_Host Host

+ *  @{

+ *  */

 

+/** \brief 			Check if device support CDC Serial interface or not

+ * \param[in]		dev_addr	device address

+ * \retval      true if device supports

+ * \retval      false if device does not support or is not mounted

+ */

 bool tusbh_cdc_serial_is_mounted(uint8_t dev_addr) ATTR_PURE ATTR_WARN_UNUSED_RESULT;

+

+/** \brief      Check if the interface is currently busy or not

+ * \param[in]   dev_addr device address

+ * \param[in]   pipeid value from \ref cdc_pipeid_t to indicate target pipe.

+ * \retval      true if the interface is busy, meaning the stack is still transferring/waiting data from/to device

+ * \retval      false if the interface is not busy, meaning the stack successfully transferred data from/to device

+ * \note        This function is used to check if previous transfer is complete (success or error), so that the next transfer

+ *              can be scheduled. User needs to make sure the corresponding interface is mounted

+ *              (by \ref tusbh_cdc_serial_is_mounted or \ref tusbh_cdc_rndis_is_mounted) before calling this function.

+ */

 bool tusbh_cdc_is_busy(uint8_t dev_addr, cdc_pipeid_t pipeid)  ATTR_PURE ATTR_WARN_UNUSED_RESULT;

 

+/** \brief 			Perform USB OUT transfer to device

+ * \param[in]		dev_addr	device address

+ * \param[in]	  p_data    Buffer containing data. Must be accessible by USB controller (see \ref TUSB_CFG_ATTR_USBRAM)

+ * \param[in]		length    Number of bytes to be transferred via USB bus

+ * \retval      TUSB_ERROR_NONE on success

+ * \retval      TUSB_ERROR_INTERFACE_IS_BUSY if the interface is already transferring data with device

+ * \retval      TUSB_ERROR_DEVICE_NOT_READY if device is not yet configured (by SET CONFIGURED request)

+ * \retval      TUSB_ERROR_INVALID_PARA if input parameters are not correct

+ * \note        This function is non-blocking and returns immediately. The result of USB transfer will be reported by the

+ *              interface's callback function. \a p_data must be declared with \ref TUSB_CFG_ATTR_USBRAM.

+ */

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

+

+/** \brief 			Perform USB IN transfer to get data from device

+ * \param[in]		dev_addr	device address

+ * \param[in]	  p_buffer  Buffer containing received data. Must be accessible by USB controller (see \ref TUSB_CFG_ATTR_USBRAM)

+ * \param[in]		length    Number of bytes to be transferred via USB bus

+ * \retval      TUSB_ERROR_NONE on success

+ * \retval      TUSB_ERROR_INTERFACE_IS_BUSY if the interface is already transferring data with device

+ * \retval      TUSB_ERROR_DEVICE_NOT_READY if device is not yet configured (by SET CONFIGURED request)

+ * \retval      TUSB_ERROR_INVALID_PARA if input parameters are not correct

+ * \note        This function is non-blocking and returns immediately. The result of USB transfer will be reported by the

+ *              interface's callback function. \a p_data must be declared with \ref TUSB_CFG_ATTR_USBRAM.

+ */

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

 

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

@@ -82,9 +124,21 @@ void tusbh_cdc_mounted_cb(uint8_t dev_addr);
  */

 void tusbh_cdc_unmounted_cb(uint8_t dev_addr);

 

+/** \brief      Callback function that is invoked when an transferring event occurred

+ * \param[in]		dev_addr	Address of device

+ * \param[in]   event an value from \ref tusb_event_t

+ * \param[in]   pipe_id value from \ref cdc_pipeid_t indicate the pipe

+ * \param[in]   xferred_bytes Number of bytes transferred via USB bus

+ * \note        event can be one of following

+ *              - TUSB_EVENT_XFER_COMPLETE : previously scheduled transfer completes successfully.

+ *              - TUSB_EVENT_XFER_ERROR   : previously scheduled transfer encountered a transaction error.

+ *              - TUSB_EVENT_XFER_STALLED : previously scheduled transfer is stalled by device.

+ * \note

+ */

 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

diff --git a/tinyusb/class/msc_host.h b/tinyusb/class/msc_host.h
index a2cba10f2..ddb8a7f54 100644
--- a/tinyusb/class/msc_host.h
+++ b/tinyusb/class/msc_host.h
@@ -67,8 +67,9 @@ bool          tusbh_msc_is_mounted(uint8_t dev_addr) ATTR_PURE ATTR_WARN_UNUSED_
  * \param[in]   dev_addr device address

  * \retval      true if the interface is busy meaning the stack is still transferring/waiting data from/to device

  * \retval      false if the interface is not busy meaning the stack successfully transferred data from/to device

- * \note        This function is primarily used for polling/waiting result after transferring API.

- *              Alternatively, asynchronous event API can be used

+ * \note        This function is used to check if previous transfer is complete (success or error), so that the next transfer

+ *              can be scheduled. User needs to make sure the corresponding interface is mounted (by \ref tusbh_msc_is_mounted)

+ *              before calling this function

  */

 bool          tusbh_msc_is_busy(uint8_t dev_addr) ATTR_PURE ATTR_WARN_UNUSED_RESULT;

 

@@ -174,6 +175,7 @@ void tusbh_msc_unmounted_cb(uint8_t dev_addr);
 /** \brief      Callback function that is invoked when an transferring event occurred

  * \param[in]		dev_addr	Address of device

  * \param[in]   event an value from \ref tusb_event_t

+ * \param[in]   xferred_bytes Number of bytes transferred via USB bus

  * \note        event can be one of following

  *              - TUSB_EVENT_XFER_COMPLETE : previously scheduled transfer completes successfully.

  *              - TUSB_EVENT_XFER_ERROR   : previously scheduled transfer encountered a transaction error.