begriffs open source - cmsis/blob - CMSIS/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 *****************************************************************************************************************/
 255
 256 int32_t ARM_USBD_ReadSetupPacket (uint8_t *setup)  {
 257   return ARM_DRIVER_OK;
 258 }
 259 /**
 260 \fn int32_t ARM_USBD_ReadSetupPacket (uint8_t *setup)
 261 \details
 262 The function \b ARM_USBD_ReadSetupPacket reads the last SETUP packet (8 bytes) that was received over Control Endpoint (Endpoint 0)
 263 which is indicated by \ref ARM_USBD_EVENT_SETUP event.
 264
 265 <b>See also:</b>
 266  - \ref ARM_USBD_SignalEndpointEvent
 267 *****************************************************************************************************************/
 268
 269 int32_t ARM_USBD_EndpointConfigure (uint8_t  ep_addr,
 270                                     uint8_t  ep_type,
 271                                     uint16_t ep_max_packet_size)  {
 272   return ARM_DRIVER_OK;
 273 }
 274 /**
 275 \fn int32_t ARM_USBD_EndpointConfigure (uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size)
 276 \details
 277 The function \b ARM_USBD_EndpointConfigure configures an endpoint for transfers.
 278
 279
 280 *****************************************************************************************************************/
 281
 282 int32_t ARM_USBD_EndpointUnconfigure (uint8_t ep_addr)  {
 283   return ARM_DRIVER_OK;
 284 }
 285 /**
 286 \fn int32_t ARM_USBD_EndpointUnconfigure (uint8_t ep_addr)
 287 \details
 288 The function \b ARM_USBD_EndpointUnconfigure de-configures the specified endpoint.
 289
 290 The parameter \em ep_addr specifies the endpoint address.
 291 *****************************************************************************************************************/
 292
 293 int32_t ARM_USBD_EndpointStall (uint8_t ep_addr, bool stall)  {
 294   return ARM_DRIVER_OK;
 295 }
 296 /**
 297 \fn int32_t ARM_USBD_EndpointStall (uint8_t ep_addr, bool stall)
 298 \details
 299 The function \b ARM_USBD_EndpointStall sets or clears stall condition for the specified endpoint.
 300
 301 The parameter \em ep_addr specifies the endpoint address. \n
 302 The parameter \em stall is a boolean parameter.
 303 *****************************************************************************************************************/
 304
 305 int32_t ARM_USBD_EndpointTransfer (uint8_t ep_addr, uint8_t *data, uint32_t num)  {
 306   return ARM_DRIVER_OK;
 307 }
 308 /**
 309 \fn int32_t ARM_USBD_EndpointTransfer (uint8_t ep_addr, uint8_t *data, uint32_t num)
 310 \details
 311
 312 The function \b ARM_USBD_EndpointTransfer reads from or writes data to an USB Endpoint.
 313
 314 The parameter \em ep_addr specifies the endpoint address. \n
 315 The parameter \em data is a buffer for data to read or data to write. \n
 316 The parameter \em num is the number of bytes to transfer (must be multiple of endpoint maximum packet size for Read transfers).
 317
 318 The function is non-blocking and returns as soon as the driver starts the operation on the specified endpoint.
 319 During the operation it is not allowed to call this function again on the same endpoint.
 320 Also the data buffer must stay allocated and the contents of data must not be modified.
 321
 322 Direction in the endpoint address specifies the type of transfer:
 323 - Endpoint Read for OUT endpoint (direction = 0)
 324 - Endpoint Write for IN endpoint (direction = 1)
 325
 326 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.
 327 Completion of operation is indicated by \ref ARM_USBD_EVENT_OUT event. Number of successfully received data bytes can be retrieved
 328 by calling \ref ARM_USBD_EndpointTransferGetResult.
 329
 330 Endpoint Write is finished when the requested number of data bytes have been sent.
 331 Completion of operation is indicated by \ref ARM_USBD_EVENT_IN event. Number of successfully sent data bytes can be retrieved
 332 by calling \ref ARM_USBD_EndpointTransferGetResult.
 333
 334 Transfer operation can be aborted by calling \ref ARM_USBD_EndpointTransferAbort.
 335 *****************************************************************************************************************/
 336
 337 uint32_t ARM_USBD_EndpointTransferGetResult (uint8_t ep_addr)  {
 338   return 0;
 339 }
 340 /**
 341 \fn uint32_t ARM_USBD_EndpointTransferGetResult (uint8_t ep_addr)
 342 \details
 343 The function \b ARM_USBD_EndpointTransferGetResult returns the number of successfully transferred data bytes started by \ref ARM_USBD_EndpointTransfer.
 344
 345 The parameter \em ep_addr specifies the endpoint address.
 346 *****************************************************************************************************************/
 347
 348 int32_t ARM_USBD_EndpointTransferAbort (uint8_t ep_addr)  {
 349   return ARM_DRIVER_OK;
 350 }
 351 /**
 352 \fn int32_t ARM_USBD_EndpointTransferAbort (uint8_t ep_addr)
 353 \details
 354 The function \b ARM_USBD_EndpointTransferAbort aborts the transfer to an endpoint started by \ref ARM_USBD_EndpointTransfer.
 355
 356 The parameter \em ep_addr specifies the endpoint address.
 357 *****************************************************************************************************************/
 358
 359 uint16_t ARM_USBD_GetFrameNumber (void)  {
 360   return 0;
 361 }
 362 /**
 363 \fn uint16_t ARM_USBD_GetFrameNumber (void)
 364 \details
 365 Retrieves the sequential 11-bit frame number of the last Start of Frame (SOF) packet.
 366 *****************************************************************************************************************/
 367
 368 void ARM_USBD_SignalDeviceEvent (uint32_t event)  {
 369   // function body
 370 }
 371 /**
 372 \fn void ARM_USBD_SignalDeviceEvent (uint32_t event)
 373 \details
 374 The function \b ARM_USBD_SignalDeviceEvent is a callback function registered by the function \ref ARM_USBD_Initialize.
 375
 376 The parameter \em event indicates one or more events that occurred during driver operation.
 377 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
 378
 379 Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the
 380 data fields of the structure \ref ARM_USBD_CAPABILITIES, which can be retrieved with the function \ref ARM_USBD_GetCapabilities.
 381
 382 The following events can be generated:
 383
 384 Event                           | Bit| Description                                        | supported when \ref ARM_USBD_CAPABILITIES
 385 :-------------------------------|---:|:---------------------------------------------------|----------------------------------------------
 386 \ref ARM_USBD_EVENT_VBUS_ON     | 0  | Occurs when valid VBUS voltage is detected.        | data field \em  event_vbus_on = \token{1}
 387 \ref ARM_USBD_EVENT_VBUS_OFF    | 1  | Occurs when VBUS voltage is turned off.            | data field \em  event_vbus_off = \token{1}
 388 \ref ARM_USBD_EVENT_RESET       | 2  | Occurs when USB Reset is detected.                 | <i>always supported</i>
 389 \ref ARM_USBD_EVENT_HIGH_SPEED  | 3  | Occurs when USB Device is switched to High-speed.  | <i>always supported</i>
 390 \ref ARM_USBD_EVENT_SUSPEND     | 4  | Occurs when USB Suspend is detected.               | <i>always supported</i>
 391 \ref ARM_USBD_EVENT_RESUME      | 5  | Occurs when USB Resume is detected.                | <i>always supported</i>
 392 *****************************************************************************************************************/
 393
 394 void ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, uint32_t ep_event)  {
 395   // function body
 396 }
 397 /**
 398 \fn void ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, uint32_t event)
 399 \details
 400 The function \b ARM_USBD_SignalEndpointEvent is a callback function registered by the function \ref ARM_USBD_Initialize.
 401
 402 The argument \a ep_addr specifies the endpoint. \n
 403 The parameter \em event indicates one or more events that occurred during driver operation.
 404 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
 405
 406 The following events can be generated:
 407
 408 Event                                    | Bit | Description
 409 :----------------------------------------|----:|:-----------
 410 \ref ARM_USBD_EVENT_SETUP                |  0  | Occurs when SETUP packet is received over Control Endpoint.
 411 \ref ARM_USBD_EVENT_OUT                  |  1  | Occurs when data is received over OUT Endpoint.
 412 \ref ARM_USBD_EVENT_IN                   |  2  | Occurs when data is sent over IN Endpoint.
 413 *****************************************************************************************************************/
 414
 415 /**
 416 @}
 417 */
 418 // End USBD Interface