begriffs open source - cmsis/blob - CMSIS/Documentation/Doxygen/Driver/src/Driver_USBD.c

   1 /**
   2 \defgroup   usbd_interface_gr USB Device Interface
   3 \ingroup    usb_interface_gr
   4 \brief      Driver API for USB Device Peripheral (%Driver_USBD.h)
   5 @{
   6 */
   7
   8 /**
   9 \struct     ARM_DRIVER_USBD
  10 \details
  11 The functions of the USB Device driver are accessed by function pointers. Refer to \ref DriverFunctions for
  12 overview information.
  13
  14 Each instance of an USBD provides such an access struct. The instance is indicated by
  15 a postfix in the symbol name of the access struct, for example:
  16  - \b Driver_USBD0 is the name of the access struct of the first instance (no. 0).
  17  - \b Driver_USBD1 is the name of the access struct of the second instance (no. 1).
  18
  19
  20 A configuration setting in the middleware allows connecting the middleware to a specific driver instance <b>Driver_USBD<i>n</i></b>.
  21 The default is \token{0}, which connects a middleware to the first instance of a driver.
  22
  23 \note    The struct must remain unchanged.
  24 *****************************************************************************************************************/
  25
  26 /**
  27 \struct     ARM_USBD_CAPABILITIES
  28 \details
  29 A USB Device driver can be implemented with different capabilities.
  30 The data fields of this structure encode the capabilities implemented by this driver.
  31
  32 <b>Returned by:</b>
  33   - \ref ARM_USBD_GetCapabilities
  34
  35 \note    The struct must remain unchanged.
  36 *****************************************************************************************************************/
  37
  38 /**
  39 \struct     ARM_USBD_STATE
  40 \details
  41 This structure stores information about the state of the USB Device. The data fields encode the established speed,
  42 whether the device is powered and active.
  43
  44 <b>Returned by:</b>
  45   - \ref ARM_USBD_DeviceGetState
  46 *****************************************************************************************************************/
  47
  48 /**
  49 \typedef    ARM_USBD_SignalDeviceEvent_t
  50 \details
  51 Provides the typedef for the callback function \ref ARM_USBD_SignalDeviceEvent.
  52
  53 <b>Parameter for:</b>
  54   - \ref ARM_USBD_Initialize
  55 *******************************************************************************************************************/
  56
  57 /**
  58 \typedef    ARM_USBD_SignalEndpointEvent_t
  59 \details
  60 Provides the typedef for the callback function \ref ARM_USBD_SignalEndpointEvent.
  61
  62 <b>Parameter for:</b>
  63   - \ref ARM_USBD_Initialize
  64 *******************************************************************************************************************/
  65
  66 /**
  67 \defgroup USBD_dev_events USBD Device Events
  68 \ingroup usbd_interface_gr
  69 \brief The USB Device driver generates Device call back events that are notified via the function \ref ARM_USBD_SignalDeviceEvent.
  70 \details
  71 This section provides the event values for the \ref ARM_USBD_SignalDeviceEvent callback function.
  72
  73 The following call back notification events are generated:
  74 @{
  75 \def  ARM_USBD_EVENT_VBUS_ON
  76 \def  ARM_USBD_EVENT_VBUS_OFF
  77 \def  ARM_USBD_EVENT_RESET
  78 \def  ARM_USBD_EVENT_HIGH_SPEED
  79 \def  ARM_USBD_EVENT_SUSPEND
  80 \def  ARM_USBD_EVENT_RESUME
  81 @}
  82 */
  83
  84 /**
  85 \defgroup USBD_ep_events USBD Endpoint Events
  86 \ingroup usbd_interface_gr
  87 \brief The USB Device driver generates Endpoint call back events that are notified via the function \ref ARM_USBD_SignalEndpointEvent.
  88 \details
  89 This section provides the event values for the \ref ARM_USBD_SignalEndpointEvent callback function.
  90
  91 The following call back notification events are generated:
  92 @{
  93 \def  ARM_USBD_EVENT_SETUP
  94 \def  ARM_USBD_EVENT_OUT
  95 \def  ARM_USBD_EVENT_IN
  96 @}
  97 */
  98
  99
 100 //
 101 // Functions
 102 //
 103
 104 ARM_DRIVER_VERSION ARM_USBD_GetVersion (void)  {
 105   return { 0, 0 };
 106 }
 107 /**
 108 \fn     ARM_DRIVER_VERSION ARM_USBD_GetVersion (void)
 109 \details
 110 The function \b ARM_USBD_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
 111  - API version is the version of the CMSIS-Driver specification used to implement this driver.
 112  - Driver version is source code version of the actual driver implementation.
 113
 114 Example:
 115 \code
 116 extern ARM_DRIVER_USBD Driver_USBD0;
 117 ARM_DRIVER_USBD *drv_info;
 118
 119 void setup_usbd (void)  {
 120   ARM_DRIVER_VERSION  version;
 121
 122   drv_info = &Driver_USBD0;
 123   version = drv_info->GetVersion ();
 124   if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
 125     // error handling
 126     return;
 127   }
 128 }
 129 \endcode
 130 *****************************************************************************************************************/
 131
 132 ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities (void)  {
 133   return { 0 };
 134 }
 135 /**
 136 \fn       ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities (void)
 137 \details
 138 The function \b ARM_USBD_GetCapabilities returns information about capabilities in this driver implementation.
 139 The data fields of the structure \ref ARM_USBD_CAPABILITIES encode various capabilities, for example
 140 if the hardware can create signal events using the \ref ARM_USBD_SignalDeviceEvent callback function.
 141
 142 Example:
 143 \code
 144 extern ARM_DRIVER_USBD Driver_USBD0;
 145 ARM_DRIVER_USBD *drv_info;
 146
 147 void read_capabilities (void)  {
 148   ARM_USBD_CAPABILITIES drv_capabilities;
 149
 150   drv_info = &Driver_USBD0;
 151   drv_capabilities = drv_info->GetCapabilities ();
 152   // interrogate capabilities
 153
 154 }
 155 \endcode
 156 *****************************************************************************************************************/
 157
 158 int32_t ARM_USBD_Initialize (ARM_USBD_SignalDeviceEvent_t   cb_device_event,
 159                              ARM_USBD_SignalEndpointEvent_t cb_endpoint_event)  {
 160   return ARM_DRIVER_OK;
 161 }
 162 /**
 163 \fn       int32_t ARM_USBD_Initialize (ARM_USBD_SignalDeviceEvent_t cb_device_event, ARM_USBD_SignalEndpointEvent_t cb_endpoint_event)
 164 \details
 165 The function \b ARM_USBD_Initialize initializes the USB Device interface.
 166 It is called when the middleware component starts operation.
 167
 168 The function performs the following operations:
 169   - Initializes the resources needed for the USBD interface.
 170   - Registers the \ref ARM_USBD_SignalDeviceEvent callback function.
 171   - Registers the \ref ARM_USBD_SignalEndpointEvent callback function.
 172
 173 The parameter \em cb_device_event is a pointer to the \ref ARM_USBD_SignalDeviceEvent callback function; use a NULL pointer
 174 when no device callback signals are required. \n
 175 The parameter \em cb_endpoint_event is a pointer to the \ref ARM_USBD_SignalEndpointEvent callback function.
 176
 177 \b Example:
 178  - see \ref usbd_interface_gr - Driver Functions
 179
 180 *****************************************************************************************************************/
 181
 182 int32_t ARM_USBD_Uninitialize (void)  {
 183   return ARM_DRIVER_OK;
 184 }
 185 /**
 186 \fn       int32_t ARM_USBD_Uninitialize (void)
 187 \details
 188 The function \b ARM_USBD_Uninitialize de-initializes the resources of USBD interface.
 189
 190 It is called when the middleware component stops operation and releases the software resources used by the interface.
 191 *****************************************************************************************************************/
 192
 193 int32_t ARM_USBD_PowerControl (ARM_POWER_STATE state)  {
 194   return ARM_DRIVER_OK;
 195 }
 196 /**
 197 \fn int32_t ARM_USBD_PowerControl (ARM_POWER_STATE state)
 198 \details
 199 The function \b ARM_USBD_PowerControl operates the power modes of the USB Device interface.
 200
 201 The parameter \em state sets the operation and can have the following values:
 202   - \ref ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA.
 203                           Can be called multiple times. If the peripheral is already in this mode the function performs
 204                                                   no operation and returns with \ref ARM_DRIVER_OK.
 205   - \ref ARM_POWER_LOW : may use power saving. Returns \ref ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
 206   - \ref ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
 207
 208 Refer to \ref CallSequence for more information.
 209 *****************************************************************************************************************/
 210
 211 int32_t ARM_USBD_DeviceConnect (void)  {
 212   return ARM_DRIVER_OK;
 213 }
 214 /**
 215 \fn int32_t ARM_USBD_DeviceConnect (void)
 216 \details
 217 The function \b ARM_USBD_DeviceConnect signals to the host that the device is connected.
 218 *****************************************************************************************************************/
 219
 220 int32_t ARM_USBD_DeviceDisconnect (void)  {
 221   return ARM_DRIVER_OK;
 222 }
 223 /**
 224 \fn int32_t ARM_USBD_DeviceDisconnect (void)
 225 \details
 226 The function \b ARM_USBD_DeviceDisconnect signals to the host that the device is disconnected.
 227 *****************************************************************************************************************/
 228
 229 ARM_USBD_STATE ARM_USBD_DeviceGetState (void)  {
 230   return ARM_DRIVER_OK;
 231 }
 232 /**
 233 \fn ARM_USBD_STATE ARM_USBD_DeviceGetState (void)
 234 \details
 235 Retrieves the current USB device state.
 236 *****************************************************************************************************************/
 237
 238 int32_t ARM_USBD_DeviceRemoteWakeup (void)  {
 239   return ARM_DRIVER_OK;
 240 }
 241 /**
 242 \fn int32_t ARM_USBD_DeviceRemoteWakeup (void)
 243 \details
 244 The function \b ARM_USBD_DeviceRemoteWakeup signals remote wakeup to the host.
 245 *****************************************************************************************************************/
 246
 247 int32_t ARM_USBD_DeviceSetAddress (uint8_t dev_addr)  {
 248   return ARM_DRIVER_OK;
 249 }
 250 /**
 251 \fn int32_t ARM_USBD_DeviceSetAddress (uint8_t dev_addr)
 252 \details
 253 Assigns an address to the device.
 254 \note This function is called after status stage of the Set Address request (after IN packet in status stage was sent with the old address).
 255
 256 *****************************************************************************************************************/
 257
 258 int32_t ARM_USBD_ReadSetupPacket (uint8_t *setup)  {
 259   return ARM_DRIVER_OK;
 260 }
 261 /**
 262 \fn int32_t ARM_USBD_ReadSetupPacket (uint8_t *setup)
 263 \details
 264 The function \b ARM_USBD_ReadSetupPacket reads the last SETUP packet (8 bytes) that was received over Control Endpoint (Endpoint 0)
 265 which is indicated by \ref ARM_USBD_EVENT_SETUP event.
 266
 267 <b>See also:</b>
 268  - \ref ARM_USBD_SignalEndpointEvent
 269 *****************************************************************************************************************/
 270
 271 int32_t ARM_USBD_EndpointConfigure (uint8_t  ep_addr,
 272                                     uint8_t  ep_type,
 273                                     uint16_t ep_max_packet_size)  {
 274   return ARM_DRIVER_OK;
 275 }
 276 /**
 277 \fn int32_t ARM_USBD_EndpointConfigure (uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size)
 278 \details
 279 The function \b ARM_USBD_EndpointConfigure configures an endpoint for transfers.
 280
 281
 282 *****************************************************************************************************************/
 283
 284 int32_t ARM_USBD_EndpointUnconfigure (uint8_t ep_addr)  {
 285   return ARM_DRIVER_OK;
 286 }
 287 /**
 288 \fn int32_t ARM_USBD_EndpointUnconfigure (uint8_t ep_addr)
 289 \details
 290 The function \b ARM_USBD_EndpointUnconfigure de-configures the specified endpoint.
 291
 292 The parameter \em ep_addr specifies the endpoint address.
 293 *****************************************************************************************************************/
 294
 295 int32_t ARM_USBD_EndpointStall (uint8_t ep_addr, bool stall)  {
 296   return ARM_DRIVER_OK;
 297 }
 298 /**
 299 \fn int32_t ARM_USBD_EndpointStall (uint8_t ep_addr, bool stall)
 300 \details
 301 The function \b ARM_USBD_EndpointStall sets or clears stall condition for the specified endpoint.
 302
 303 The parameter \em ep_addr specifies the endpoint address. \n
 304 The parameter \em stall is a boolean parameter.
 305 *****************************************************************************************************************/
 306
 307 int32_t ARM_USBD_EndpointTransfer (uint8_t ep_addr, uint8_t *data, uint32_t num)  {
 308   return ARM_DRIVER_OK;
 309 }
 310 /**
 311 \fn int32_t ARM_USBD_EndpointTransfer (uint8_t ep_addr, uint8_t *data, uint32_t num)
 312 \details
 313
 314 The function \b ARM_USBD_EndpointTransfer reads from or writes data to an USB Endpoint.
 315
 316 The parameter \em ep_addr specifies the endpoint address. \n
 317 The parameter \em data is a buffer for data to read or data to write. \n
 318 The parameter \em num is the number of bytes to transfer (must be multiple of endpoint maximum packet size for Read transfers).
 319
 320 The function is non-blocking and returns as soon as the driver starts the operation on the specified endpoint.
 321 During the operation it is not allowed to call this function again on the same endpoint.
 322 Also the data buffer must stay allocated and the contents of data must not be modified.
 323
 324 Direction in the endpoint address specifies the type of transfer:
 325 - Endpoint Read for OUT endpoint (direction = 0)
 326 - Endpoint Write for IN endpoint (direction = 1)
 327
 328 Endpoint Read is finished when the requested number of data bytes have been received or when a short packet or ZLP (Zero-Length Packet) has been received.
 329 Completion of operation is indicated by \ref ARM_USBD_EVENT_OUT event. Number of successfully received data bytes can be retrieved
 330 by calling \ref ARM_USBD_EndpointTransferGetResult.
 331
 332 Endpoint Write is finished when the requested number of data bytes have been sent.
 333 Completion of operation is indicated by \ref ARM_USBD_EVENT_IN event. Number of successfully sent data bytes can be retrieved
 334 by calling \ref ARM_USBD_EndpointTransferGetResult.
 335
 336 Transfer operation can be aborted by calling \ref ARM_USBD_EndpointTransferAbort.
 337 *****************************************************************************************************************/
 338
 339 uint32_t ARM_USBD_EndpointTransferGetResult (uint8_t ep_addr)  {
 340   return 0;
 341 }
 342 /**
 343 \fn uint32_t ARM_USBD_EndpointTransferGetResult (uint8_t ep_addr)
 344 \details
 345 The function \b ARM_USBD_EndpointTransferGetResult returns the number of successfully transferred data bytes started by \ref ARM_USBD_EndpointTransfer.
 346
 347 The parameter \em ep_addr specifies the endpoint address.
 348 *****************************************************************************************************************/
 349
 350 int32_t ARM_USBD_EndpointTransferAbort (uint8_t ep_addr)  {
 351   return ARM_DRIVER_OK;
 352 }
 353 /**
 354 \fn int32_t ARM_USBD_EndpointTransferAbort (uint8_t ep_addr)
 355 \details
 356 The function \b ARM_USBD_EndpointTransferAbort aborts the transfer to an endpoint started by \ref ARM_USBD_EndpointTransfer.
 357
 358 The parameter \em ep_addr specifies the endpoint address.
 359 *****************************************************************************************************************/
 360
 361 uint16_t ARM_USBD_GetFrameNumber (void)  {
 362   return 0;
 363 }
 364 /**
 365 \fn uint16_t ARM_USBD_GetFrameNumber (void)
 366 \details
 367 Retrieves the sequential 11-bit frame number of the last Start of Frame (SOF) packet.
 368 *****************************************************************************************************************/
 369
 370 void ARM_USBD_SignalDeviceEvent (uint32_t event)  {
 371   // function body
 372 }
 373 /**
 374 \fn void ARM_USBD_SignalDeviceEvent (uint32_t event)
 375 \details
 376 The function \b ARM_USBD_SignalDeviceEvent is a callback function registered by the function \ref ARM_USBD_Initialize.
 377
 378 The parameter \em event indicates one or more events that occurred during driver operation.
 379 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
 380
 381 Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the
 382 data fields of the structure \ref ARM_USBD_CAPABILITIES, which can be retrieved with the function \ref ARM_USBD_GetCapabilities.
 383
 384 The following events can be generated:
 385
 386 Event                           | Bit| Description                                        | supported when \ref ARM_USBD_CAPABILITIES
 387 :-------------------------------|---:|:---------------------------------------------------|----------------------------------------------
 388 \ref ARM_USBD_EVENT_VBUS_ON     | 0  | Occurs when valid VBUS voltage is detected.        | data field \em  event_vbus_on = \token{1}
 389 \ref ARM_USBD_EVENT_VBUS_OFF    | 1  | Occurs when VBUS voltage is turned off.            | data field \em  event_vbus_off = \token{1}
 390 \ref ARM_USBD_EVENT_RESET       | 2  | Occurs when USB Reset is detected.                 | <i>always supported</i>
 391 \ref ARM_USBD_EVENT_HIGH_SPEED  | 3  | Occurs when USB Device is switched to High-speed.  | <i>always supported</i>
 392 \ref ARM_USBD_EVENT_SUSPEND     | 4  | Occurs when USB Suspend is detected.               | <i>always supported</i>
 393 \ref ARM_USBD_EVENT_RESUME      | 5  | Occurs when USB Resume is detected.                | <i>always supported</i>
 394 *****************************************************************************************************************/
 395
 396 void ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, uint32_t ep_event)  {
 397   // function body
 398 }
 399 /**
 400 \fn void ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, uint32_t event)
 401 \details
 402 The function \b ARM_USBD_SignalEndpointEvent is a callback function registered by the function \ref ARM_USBD_Initialize.
 403
 404 The argument \a ep_addr specifies the endpoint. \n
 405 The parameter \em event indicates one or more events that occurred during driver operation.
 406 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
 407
 408 The following events can be generated:
 409
 410 Event                                    | Bit | Description
 411 :----------------------------------------|----:|:-----------
 412 \ref ARM_USBD_EVENT_SETUP                |  0  | Occurs when SETUP packet is received over Control Endpoint.
 413 \ref ARM_USBD_EVENT_OUT                  |  1  | Occurs when data is received over OUT Endpoint.
 414 \ref ARM_USBD_EVENT_IN                   |  2  | Occurs when data is sent over IN Endpoint.
 415 *****************************************************************************************************************/
 416
 417 /**
 418 @}
 419 */
 420 // End USBD Interface