begriffs open source - cmsis/blob - CMSIS/DoxyGen/Driver/src/Driver_USB.c

   1 /* -----------------------------------------------------------------------------\r
   2  * Copyright (c) 2013-2014 ARM Limited. All rights reserved.\r
   3  *  \r
   4  * $Date:        2. January 2014\r
   5  * $Revision:    V2.00\r
   6  *  \r
   7  * Project:      USB Driver API\r
   8  * -------------------------------------------------------------------------- */\r
   9 \r
  10 \r
  11 /**\r
  12 \defgroup usb_interface_gr USB Interface\r
  13 \brief   USB common definitions (%Driver_USB.h)\r
  14 \details\r
  15 The <b>Universal Serial Bus</b> (USB) implements a serial bus for data exchange. It is a host controlled, plug-and-play interface\r
  16 between a USB host and USB devices using a tiered star topology. \r
  17 In microcontroller (MCU) applications, the interface is often used to connect a device to a host for data exchange or control purposes.\r
  18 \r
  19  - Wikipedia offers more information about the <a href="http://en.wikipedia.org/wiki/Universal_Serial_Bus" target="_blank"><b>Universal Serial Bus</b></a>.\r
  20  - The USB Implementers Forum provides detailed documentation under <a href="http://www.usb.org"><b>www.usb.org</b></a>.\r
  21 \r
  22 \r
  23 **Block Diagram**\r
  24 \r
  25 Typically only one USB Device is connected to a USB Host. If several USB devices must be connected to the same USB host, then\r
  26 the connection must be done via a USB hub.\r
  27 \r
  28 <p>\r
  29 \image html USB_Schematics.png "Simplified USB Schema"\r
  30 </p>\r
  31 \r
  32 \r
  33 **USB API**\r
  34 \r
  35 The following header files define the Application Programming Interface (API) for the USB interface:\r
  36   - \b %Driver_USB.h :  Common definitions of the USBD and USBH interface\r
  37   - \b %Driver_USBD.h : Driver API for USB Device Peripheral\r
  38   - \b %Driver_USBH.h : Driver API for USB Host Peripheral\r
  39 \r
  40 The driver implementation is a typical part of the Device Family Pack (DFP) that supports the \r
  41 peripherals of the microcontroller family.\r
  42 \r
  43 \r
  44 **Driver Functions**\r
  45 \r
  46 The driver functions are published in the access struct as explained in \ref DriverFunctions\r
  47   - \ref ARM_DRIVER_USBD : access struct for USBD driver functions\r
  48   - \ref ARM_DRIVER_USBH : access struct for USBH driver functions\r
  49 */\r
  50 /*\r
  51 A typical setup sequence for the driver is shown below:\r
  52 \r
  53 <b>Example Code:</b>\r
  54 \r
  55 \todo example\r
  56 */\r
  57 /**\r
  58 <hr>\r
  59 \r
  60 */\r
  61 \r
  62 \r
  63 /**\r
  64 \addtogroup usbd_interface_gr \r
  65 \ingroup usb_interface_gr\r
  66 \details\r
  67 \r
  68 **USB Device API**\r
  69 \r
  70 The header file \b Driver_USBD.h defines the API for the <b>USB Device Driver</b> interface used by middleware components.\r
  71 The driver implementation itself is a typical part of the Device Family Pack, which provides entry points to the interface \r
  72 as function pointers in the struct \ref ARM_DRIVER_USBD. This structure can be available several times in each interface to control multiple USBD interfaces.\r
  73 \r
  74 Header file \b Driver_USBD.h also defines callback routines that can be categorized as \r
  75 <b>device event callbacks</b> and <b>endpoint event callbacks</b>.\r
  76 Callbacks are called by the driver, in interrupt context when an appropriate event occurs, to signal device related events (\ref USBD_dev_events)\r
  77 and endpoint related events (\ref USBD_ep_events).\r
  78 \r
  79 \r
  80 **USB Device Function Call Sequence**\r
  81 \r
  82 To use the USBD driver invoke the API functions in the following order:\r
  83 \r
  84 \msc\r
  85  a [label="", textcolor="indigo", linecolor="indigo", arclinecolor="red"],\r
  86  b [label="", textcolor="blue", linecolor="blue", arclinecolor="blue"];\r
  87 \r
  88  a rbox a [label="Middleware", linecolor="indigo"],\r
  89  b rbox b [label="USBD Driver", linecolor="blue"];\r
  90  a=>b [label="ARM_USBD_Initialize", URL="\ref ARM_USBD_Initialize"];\r
  91  a=>b [label="ARM_USBD_PowerControl (ARM_POWER_FULL)", URL="\ref ARM_USBD_Initialize"];\r
  92  a=>b [label="ARM_USBD_DeviceConnect", URL="\ref ARM_USBD_DeviceConnect"];\r
  93  a<=b [label="ARM_USBD_SignalDeviceEvent (ARM_USBD_EVENT_RESET)", URL="\ref ARM_USBD_SignalDeviceEvent", linecolor="orange"];\r
  94  a=>b [label="ARM_USBD_DeviceGetState", URL="\ref ARM_USBD_DeviceGetState"];\r
  95  a=>b [label="ARM_USBD_EndpointConfigure", URL="\ref ARM_USBD_EndpointConfigure", linecolor="green"];\r
  96  --- [label="Repeat and use as needed"];\r
  97  a=>b [label="ARM_USBD_EndpointTransfer", URL="\ref ARM_USBD_EndpointTransfer", linecolor="green"];\r
  98  a<=b [label="ARM_USBD_SignalEndpointEvent", URL="\ref ARM_USBD_SignalEndpointEvent", linecolor="orange"];\r
  99  a=>b [label="ARM_USBD_EndpointTransferGetResult", URL="\ref ARM_USBD_EndpointTransferGetResult", linecolor="green"];\r
 100  --- [label="Repeat End"];\r
 101  a=>b [label="ARM_USBD_DeviceDisconnect", URL="\ref ARM_USBD_DeviceDisconnect"];\r
 102  a=>b [label="ARM_USBD_PowerControl (ARM_POWER_OFF)", URL="\ref ARM_USBD_Initialize"];\r
 103  a=>b [label="ARM_USBD_Uninitialize", URL="\ref ARM_USBD_Uninitialize"];\r
 104 \endmsc\r
 105 \r
 106 */\r
 107 \r
 108 /**\r
 109 \addtogroup usbh_interface_gr\r
 110 \ingroup usb_interface_gr\r
 111 \details\r
 112 **USB Host API**\r
 113 \r
 114 The header file \b Driver_USBH.h defines the API for the <b>USB Host Driver</b> interface used by middleware components.\r
 115 The driver implementation itself is a typical part of the Device Family Pack, which provides entry points to the interface \r
 116 as function pointers in the struct \ref ARM_DRIVER_USBH. This structure can be available several times in each interface to control multiple USBH interfaces.\r
 117 \r
 118 \b Driver_USBH.h also defines callback routines, which are categorized in \r
 119 <b>port event callbacks</b> and <b>pipe event callbacks</b>.\r
 120 Callbacks are called by the driver, in interrupt context when an appropriate event occurs, to signal port related events (\ref ARM_USBH_SignalPortEvent)\r
 121 and pipe related events (\ref ARM_USBH_SignalPipeEvent). \r
 122 \r
 123 \cond\r
 124 \r
 125 **USB Host Function Call Sequence**\r
 126 \r
 127 To use the USBH driver invoke the API functions in the following order:\r
 128 \r
 129 \msc\r
 130  a [label="", textcolor="indigo", linecolor="indigo", arclinecolor="red"],\r
 131  b [label="", textcolor="blue", linecolor="blue", arclinecolor="blue"];\r
 132 \r
 133  a rbox a [label="Middleware", linecolor="indigo"],\r
 134  b rbox b [label="USBH Driver", linecolor="blue"];\r
 135  a=>b [label="ARM_USBH_Initialize", URL="\ref ARM_USBD_Initialize"];\r
 136  --- [label="Repeat and use as needed"];\r
 137  --- [label="Repeat End"];\r
 138  a=>b [label="ARM_USBH_Uninitialize", URL="\ref ARM_USBH_Uninitialize"];\r
 139 \endmsc\r
 140 \r
 141  <hr>\r
 142 \r
 143 \endcond\r
 144 */\r
 145 \r
 146 \r
 147 /**\r
 148 \defgroup USB_speed USB Speed\r
 149 \ingroup usb_interface_gr\r
 150 \brief USB Speed definitions\r
 151 \details\r
 152 The following USB speed values are defined:\r
 153 @{\r
 154 \def  ARM_USB_SPEED_LOW\r
 155 \def  ARM_USB_SPEED_FULL\r
 156 \def  ARM_USB_SPEED_HIGH\r
 157 @}\r
 158 */\r
 159 \r
 160 /**\r
 161 \defgroup USB_endpoint_type USB Endpoint Type\r
 162 \ingroup usb_interface_gr\r
 163 \brief USB Endpoint Type definitions\r
 164 \details\r
 165 The following USB Endpoint Type values are defined:\r
 166 @{\r
 167 \def  ARM_USB_ENDPOINT_CONTROL\r
 168 \def  ARM_USB_ENDPOINT_ISOCHRONOUS\r
 169 \def  ARM_USB_ENDPOINT_BULK\r
 170 \def  ARM_USB_ENDPOINT_INTERRUPT\r
 171 @}\r
 172 */\r