From 064d0cf5a93499e7c15c805e83910bd654b30961 Mon Sep 17 00:00:00 2001 From: hathach Date: Sun, 27 Oct 2013 19:59:06 +0700 Subject: [PATCH] document cdc --- demos/host/src/tusb_config.h | 8 ++--- tinyusb/class/cdc_host.h | 66 ++++++++++++++++++++++++++++++++---- tinyusb/class/msc_host.h | 6 ++-- 3 files changed, 68 insertions(+), 12 deletions(-) diff --git a/demos/host/src/tusb_config.h b/demos/host/src/tusb_config.h index b83fa51f..05c415b1 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 e73d96d6..9a32cc89 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,8 +124,20 @@ 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); +/// @} /// @} //--------------------------------------------------------------------+ diff --git a/tinyusb/class/msc_host.h b/tinyusb/class/msc_host.h index a2cba10f..ddb8a7f5 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.