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