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 */ 154
