tmk_core/protocol/arm_atsam/usb/udc.h

   1 /**
   2  * \file
   3  *
   4  * \brief Interface of the USB Device Controller (UDC)
   5  *
   6  * Copyright (c) 2009-2015 Atmel Corporation. All rights reserved.
   7  *
   8  * \asf_license_start
   9  *
  10  * \page License
  11  *
  12  * Redistribution and use in source and binary forms, with or without
  13  * modification, are permitted provided that the following conditions are met:
  14  *
  15  * 1. Redistributions of source code must retain the above copyright notice,
  16  *    this list of conditions and the following disclaimer.
  17  *
  18  * 2. Redistributions in binary form must reproduce the above copyright notice,
  19  *    this list of conditions and the following disclaimer in the documentation
  20  *    and/or other materials provided with the distribution.
  21  *
  22  * 3. The name of Atmel may not be used to endorse or promote products derived
  23  *    from this software without specific prior written permission.
  24  *
  25  * 4. This software may only be redistributed and used in connection with an
  26  *    Atmel microcontroller product.
  27  *
  28  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
  29  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  30  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
  31  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
  32  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  33  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  34  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  36  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  37  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  38  * POSSIBILITY OF SUCH DAMAGE.
  39  *
  40  * \asf_license_stop
  41  *
  42  */
  43 /*
  44  * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
  45  */
  46
  47 #ifndef _UDC_H_
  48 #define _UDC_H_
  49
  50 #include "conf_usb.h"
  51 #include "usb_protocol.h"
  52 #include "udc_desc.h"
  53 #include "udd.h"
  54
  55 #if USB_DEVICE_VENDOR_ID == 0
  56 #   error USB_DEVICE_VENDOR_ID cannot be equal to 0
  57 #endif
  58
  59 #if USB_DEVICE_PRODUCT_ID == 0
  60 #   error USB_DEVICE_PRODUCT_ID cannot be equal to 0
  61 #endif
  62
  63 #ifdef __cplusplus
  64 extern "C" {
  65 #endif
  66
  67 /**
  68  * \ingroup usb_device_group
  69  * \defgroup udc_group USB Device Controller (UDC)
  70  *
  71  * The UDC provides a high-level abstraction of the usb device.
  72  * You can use these functions to control the main device state
  73  * (start/attach/wakeup).
  74  *
  75  * \section USB_DEVICE_CONF USB Device Custom configuration
  76  * The following USB Device configuration must be included in the conf_usb.h
  77  * file of the application.
  78  *
  79  * USB_DEVICE_VENDOR_ID (Word)<br>
  80  * Vendor ID provided by USB org (ATMEL 0x03EB).
  81  *
  82  * USB_DEVICE_PRODUCT_ID (Word)<br>
  83  * Product ID (Referenced in usb_atmel.h).
  84  *
  85  * USB_DEVICE_MAJOR_VERSION (Byte)<br>
  86  * Major version of the device
  87  *
  88  * USB_DEVICE_MINOR_VERSION (Byte)<br>
  89  * Minor version of the device
  90  *
  91  * USB_DEVICE_MANUFACTURE_NAME (string)<br>
  92  * ASCII name for the manufacture
  93  *
  94  * USB_DEVICE_PRODUCT_NAME (string)<br>
  95  * ASCII name for the product
  96  *
  97  * USB_DEVICE_SERIAL_NAME (string)<br>
  98  * ASCII name to enable and set a serial number
  99  *
 100  * USB_DEVICE_POWER (Numeric)<br>
 101  * (unit mA) Maximum device power
 102  *
 103  * USB_DEVICE_ATTR (Byte)<br>
 104  * USB attributes available:
 105  *  - USB_CONFIG_ATTR_SELF_POWERED
 106  *  - USB_CONFIG_ATTR_REMOTE_WAKEUP
 107  *  Note: if remote wake enabled then defines remotewakeup callbacks,
 108  * see Table 5-2. External API from UDC - Callback
 109  *
 110  * USB_DEVICE_LOW_SPEED (Only defined)<br>
 111  * Force the USB Device to run in low speed
 112  *
 113  * USB_DEVICE_HS_SUPPORT (Only defined)<br>
 114  * Authorize the USB Device to run in high speed
 115  *
 116  * USB_DEVICE_MAX_EP (Byte)<br>
 117  * Define the maximum endpoint number used by the USB Device.<br>
 118  * This one is already defined in UDI default configuration.
 119  * Ex:
 120  * - When endpoint control 0x00, endpoint 0x01 and
 121  *   endpoint 0x82 is used then USB_DEVICE_MAX_EP=2
 122  * - When only endpoint control 0x00 is used then USB_DEVICE_MAX_EP=0
 123  * - When endpoint 0x01 and endpoint 0x81 is used then USB_DEVICE_MAX_EP=1<br>
 124  *   (configuration not possible on USBB interface)
 125  * @{
 126  */
 127
 128 /**
 129  * \brief Authorizes the VBUS event
 130  *
 131  * \return true, if the VBUS monitoring is possible.
 132  *
 133  * \section udc_vbus_monitoring VBus monitoring used cases
 134  *
 135  * The VBus monitoring is used only for USB SELF Power application.
 136  *
 137  * - By default the USB device is automatically attached when Vbus is high
 138  * or when USB is start for devices without internal Vbus monitoring.
 139  * conf_usb.h file does not contains define USB_DEVICE_ATTACH_AUTO_DISABLE.
 140  * \code //#define USB_DEVICE_ATTACH_AUTO_DISABLE \endcode
 141  *
 142  * - Add custom VBUS monitoring. conf_usb.h file contains define
 143  * USB_DEVICE_ATTACH_AUTO_DISABLE:
 144  * \code #define USB_DEVICE_ATTACH_AUTO_DISABLE \endcode
 145  * User C file contains:
 146  * \code
 147     // Authorize VBUS monitoring
 148     if (!udc_include_vbus_monitoring()) {
 149       // Implement custom VBUS monitoring via GPIO or other
 150     }
 151     Event_VBUS_present() // VBUS interrupt or GPIO interrupt or other
 152     {
 153       // Attach USB Device
 154       udc_attach();
 155     }
 156 \endcode
 157  *
 158  * - Case of battery charging. conf_usb.h file contains define
 159  * USB_DEVICE_ATTACH_AUTO_DISABLE:
 160  * \code #define USB_DEVICE_ATTACH_AUTO_DISABLE \endcode
 161  * User C file contains:
 162  * \code
 163     Event VBUS present() // VBUS interrupt or GPIO interrupt or ..
 164     {
 165       // Authorize battery charging, but wait key press to start USB.
 166     }
 167     Event Key press()
 168     {
 169       // Stop batteries charging
 170       // Start USB
 171       udc_attach();
 172     }
 173 \endcode
 174  */
 175 static inline bool udc_include_vbus_monitoring(void)
 176 {
 177     return udd_include_vbus_monitoring();
 178 }
 179
 180 /*! \brief Start the USB Device stack
 181  */
 182 void udc_start(void);
 183
 184 /*! \brief Stop the USB Device stack
 185  */
 186 void udc_stop(void);
 187
 188 /**
 189  * \brief Attach device to the bus when possible
 190  *
 191  * \warning If a VBus control is included in driver,
 192  * then it will attach device when an acceptable Vbus
 193  * level from the host is detected.
 194  */
 195 static inline void udc_attach(void)
 196 {
 197     udd_attach();
 198 }
 199
 200 /**
 201  * \brief Detaches the device from the bus
 202  *
 203  * The driver must remove pull-up on USB line D- or D+.
 204  */
 205 static inline void udc_detach(void)
 206 {
 207     udd_detach();
 208 }
 209
 210 /*! \brief The USB driver sends a resume signal called \e "Upstream Resume"
 211  * This is authorized only when the remote wakeup feature is enabled by host.
 212  */
 213 static inline void udc_remotewakeup(void)
 214 {
 215     udd_send_remotewakeup();
 216 }
 217
 218 /**
 219  * \brief Returns a pointer on the current interface descriptor
 220  *
 221  * \return pointer on the current interface descriptor.
 222  */
 223 usb_iface_desc_t UDC_DESC_STORAGE *udc_get_interface_desc(void);
 224
 225 //@}
 226
 227 /**
 228  * \ingroup usb_group
 229  * \defgroup usb_device_group USB Stack Device
 230  *
 231  * This module includes USB Stack Device implementation.
 232  * The stack is divided in three parts:
 233  * - USB Device Controller (UDC) provides USB chapter 9 compliance
 234  * - USB Device Interface (UDI) provides USB Class compliance
 235  * - USB Device Driver (UDD) provides USB Driver for each Atmel MCU
 236
 237  * Many USB Device applications can be implemented on Atmel MCU.
 238  * Atmel provides many application notes for different applications:
 239  * - AVR4900, provides general information about Device Stack
 240  * - AVR4901, explains how to create a new class
 241  * - AVR4902, explains how to create a composite device
 242  * - AVR49xx, all device classes provided in ASF have an application note
 243  *
 244  * A basic USB knowledge is required to understand the USB Device
 245  * Class application notes (HID,MS,CDC,PHDC,...).
 246  * Then, to create an USB device with
 247  * only one class provided by ASF, refer directly to the application note
 248  * corresponding to this USB class. The USB Device application note for
 249  * New Class and Composite is dedicated to advanced USB users.
 250  *
 251  * @{
 252  */
 253
 254 //! @}
 255
 256 #ifdef __cplusplus
 257 }
 258 #endif
 259
 260 #endif // _UDC_H_