From 6c629a18fcd59876a6772e50b2f3cf8fadabf573 Mon Sep 17 00:00:00 2001 From: hathach Date: Thu, 24 Oct 2013 17:26:06 +0700 Subject: [PATCH] partially document CDC & RNDIS --- tinyusb/class/cdc.h | 9 +- tinyusb/class/cdc_host.h | 266 +++++++++++++++++++++------------------ 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_ */ + +/** @} */