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

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