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

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