begriffs open source - cmsis/blob - CMSIS/DoxyGen/Driver/src/Driver_USBH.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 Host Driver API
   8  * -------------------------------------------------------------------------- */
   9
  10
  11 /**
  12 \defgroup usbh_interface_gr USB Host Interface
  13 \ingroup usb_interface_gr
  14 \brief  Driver API for USB Host Peripheral (%Driver_USBH.h)
  15 */
  16
  17 /**
  18 \defgroup usbh_host_gr USB Host
  19 \ingroup usbh_interface_gr
  20 \brief  Driver API for USB Host
  21
  22 @{
  23 */
  24
  25 /**
  26 \struct ARM_DRIVER_USBH
  27 \details
  28 The functions of the USB Host driver are accessed by function pointers. Refer to \ref DriverFunctions for
  29 overview information.
  30
  31 Each instance of an USBH provides such an access struct. The instance is indicated by
  32 a postfix in the symbol name of the access struct, for example:
  33  - \b Driver_USBH0 is the name of the access struct of the first instance (no. 0).
  34  - \b Driver_USBH1 is the name of the access struct of the second instance (no. 1).
  35
  36
  37 A configuration setting in the middleware allows connecting the middleware to a specific driver instance <b>Driver_USBH<i>n</i></b>.
  38 The default is \token{0}, which connects a middleware to the first instance of a driver.
  39
  40 \note    The struct must remain unchanged.
  41 *****************************************************************************************************************/
  42
  43 /**
  44 \struct ARM_USBH_CAPABILITIES
  45 \details
  46 A USB Host driver can be implemented with different capabilities.
  47 The data fields of this structure encode the capabilities implemented by this driver.
  48
  49 <b>Returned by:</b>
  50   - \ref ARM_USBH_GetCapabilities
  51
  52 \note    The struct must remain unchanged.
  53 *****************************************************************************************************************/
  54
  55 /**
  56 \struct     ARM_USBH_PORT_STATE
  57 \details
  58 This structure stores information about the state of the USB Host Port. The data fields encode whether a device
  59 is connected to the port, if port overcurrent is detected, and the port speed.
  60
  61 <b>Returned by:</b>
  62   - \ref ARM_USBH_PortGetState
  63 *****************************************************************************************************************/
  64
  65 /**
  66 \typedef    uint32_t ARM_USBH_PIPE_HANDLE
  67 \details
  68 Each pipe is identified through a unique number, which is created by the function \ref ARM_USBH_PipeCreate.
  69
  70 <b>Parameter for:</b>
  71  - \ref ARM_USBH_PipeModify,
  72    \ref ARM_USBH_PipeDelete,
  73    \ref ARM_USBH_PipeReset,
  74    \ref ARM_USBH_PipeTransfer,
  75    \ref ARM_USBH_PipeTransferGetResult,
  76    \ref ARM_USBH_PipeTransferAbort,
  77    \ref ARM_USBH_SignalPipeEvent
  78
  79 <b>Retruned by:</b>
  80  - \ref ARM_USBH_PipeCreate
  81 *****************************************************************************************************************/
  82
  83 /**
  84 \typedef    ARM_USBH_SignalPortEvent_t
  85 \details
  86 Provides the typedef for the callback function \ref ARM_USBH_SignalPortEvent.
  87
  88 <b>Parameter for:</b>
  89   - \ref ARM_USBH_Initialize
  90 *******************************************************************************************************************/
  91
  92 /**
  93 \typedef    ARM_USBH_SignalPipeEvent_t
  94 \details
  95 Provides the typedef for the callback function \ref ARM_USBH_SignalPipeEvent.
  96
  97 <b>Parameter for:</b>
  98   - \ref ARM_USBH_Initialize
  99 *******************************************************************************************************************/
 100
 101 /**
 102 \defgroup USBH_port_events USBH Port Events
 103 \ingroup usbh_host_gr
 104 \brief The USB Host driver generates Port call back events that are notified via the function \ref ARM_USBH_SignalPortEvent.
 105 \details
 106 This section provides the event values for the \ref ARM_USBH_SignalPortEvent callback function.
 107
 108 The following call back notification events are generated:
 109 @{
 110 \def  ARM_USBH_EVENT_CONNECT
 111 \def  ARM_USBH_EVENT_DISCONNECT
 112 \def  ARM_USBH_EVENT_OVERCURRENT
 113 \def  ARM_USBH_EVENT_RESET
 114 \def  ARM_USBH_EVENT_SUSPEND
 115 \def  ARM_USBH_EVENT_RESUME
 116 \def  ARM_USBH_EVENT_REMOTE_WAKEUP
 117 @}
 118 */
 119
 120 /**
 121 \defgroup USBH_pipe_events USBH Pipe Events
 122 \ingroup usbh_host_gr
 123 \brief The USB Host driver generates Pipe call back events that are notified via the function \ref ARM_USBH_SignalPipeEvent.
 124 \details
 125 This section provides the event values for the \ref ARM_USBH_SignalPipeEvent callback function.
 126
 127 The following call back notification events are generated:
 128 @{
 129 \def  ARM_USBH_EVENT_TRANSFER_COMPLETE
 130 \def  ARM_USBH_EVENT_HANDSHAKE_NAK
 131 \def  ARM_USBH_EVENT_HANDSHAKE_NYET
 132 \def  ARM_USBH_EVENT_HANDSHAKE_MDATA
 133 \def  ARM_USBH_EVENT_HANDSHAKE_STALL
 134 \def  ARM_USBH_EVENT_HANDSHAKE_ERR
 135 \def  ARM_USBH_EVENT_BUS_ERROR
 136 @}
 137 */
 138
 139 /**
 140 \defgroup USBH_packets USBH Packet Information
 141 \ingroup usbh_host_gr
 142 \brief Specify USB packet information used by the function \ref ARM_USBH_PipeTransfer
 143 \details
 144 This section provides the packet information values (parameter \em packet) for the \ref ARM_USBH_PipeTransfer function.
 145
 146 The following values are defined:
 147 @{
 148 \def  ARM_USBH_PACKET_SETUP
 149 Generate SETUP transaction.
 150 \def  ARM_USBH_PACKET_OUT
 151 Generate OUT transaction.
 152 \def  ARM_USBH_PACKET_IN
 153 Generate IN transaction.
 154 \def  ARM_USBH_PACKET_PING
 155 Generate PING transaction (no data packet).
 156 \def  ARM_USBH_PACKET_DATA0
 157 Force DATA0 PID (Packet Identifier) for the initial data packet. When not specified than the driver provides the initial value according to the current state.
 158 \def  ARM_USBH_PACKET_DATA1
 159 Force DATA1 PID (Packet Identifier) for the initial data packet. When not specified than the driver provides the initial value according to the current state.
 160 \def  ARM_USBH_PACKET_SSPLIT
 161 Used when driver does not support automatic handling of SPLIT packets and indicates Start-Split packet.
 162 For isochronous OUT it indicates that the High-speed data is in the middle of the Full-speed data payload.
 163 \def  ARM_USBH_PACKET_SSPLIT_S
 164 Used when driver does not support automatic handling of SPLIT packets and indicates Start-Split packet.
 165 Valid only for isochronous OUT and indicates that the High-speed data is the start of the Full-speed data payload.
 166 \def  ARM_USBH_PACKET_SSPLIT_E
 167 Used when driver does not support automatic handling of SPLIT packets and indicates Start-Split packet.
 168 Valid only for isochronous OUT and indicates that the High-speed data is the end of the Full-speed data payload.
 169 \def  ARM_USBH_PACKET_SSPLIT_S_E
 170 Used when driver does not support automatic handling of SPLIT packets and indicates Start-Split packet.
 171 Valid only for isochronous OUT and indicates that the High-speed data is all of the Full-speed data payload.
 172 \def  ARM_USBH_PACKET_CSPLIT
 173 Used when driver does not support automatic handling of SPLIT packets and indicates Complete-Split packet.
 174 \def  ARM_USBH_PACKET_PRE
 175 Generate PRE (Preamble) for low-speed devices within a full/low-speed signaling environment.
 176 @}
 177 */
 178
 179
 180 //
 181 // Functions
 182 //
 183
 184 ARM_DRIVER_VERSION ARM_USBH_GetVersion (void)  {
 185   return { 0, 0 };
 186 }
 187 /**
 188 \fn       ARM_DRIVER_VERSION ARM_USBH_GetVersion (void)
 189 \details
 190 The function \b ARM_USBH_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
 191  - API version is the version of the CMSIS-Driver specification used to implement this driver.
 192  - Driver version is source code version of the actual driver implementation.
 193
 194 Example:
 195 \code
 196 extern ARM_DRIVER_USBH Driver_USBH0;
 197 ARM_DRIVER_USBH *drv_info;
 198
 199 void setup_usbh (void)  {
 200   ARM_DRIVER_VERSION  version;
 201
 202   drv_info = &Driver_USBH0;
 203   version = drv_info->GetVersion ();
 204   if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
 205     // error handling
 206     return;
 207   }
 208 }
 209 \endcode
 210 *****************************************************************************************************************/
 211
 212 ARM_USBH_CAPABILITIES ARM_USBH_GetCapabilities (void)  {
 213   return { 0 };
 214 }
 215 /**
 216 \fn       ARM_USBH_CAPABILITIES ARM_USBH_GetCapabilities (void)
 217 \details
 218 The function \b ARM_USBH_GetCapabilities returns information about capabilities in this driver implementation.
 219 The data fields of the structure \ref ARM_USBH_CAPABILITIES encode various capabilities, for example
 220 available HUB ports or if the hardware can generate signal events using the \ref ARM_USBH_SignalPortEvent
 221 callback function.
 222
 223 Example:
 224 \code
 225 extern ARM_DRIVER_USBH Driver_USBH0;
 226 ARM_DRIVER_USBH *drv_info;
 227
 228 void read_capabilities (void)  {
 229   ARM_USBH_CAPABILITIES drv_capabilities;
 230
 231   drv_info = &Driver_USBH0;
 232   drv_capabilities = drv_info->GetCapabilities ();
 233   // interrogate capabilities
 234
 235 }
 236 \endcode
 237 *****************************************************************************************************************/
 238
 239 int32_t ARM_USBH_Initialize (ARM_USBH_SignalPortEvent_t cb_port_event,
 240                              ARM_USBH_SignalPipeEvent_t cb_pipe_event)  {
 241   return ARM_DRIVER_OK;
 242 }
 243 /**
 244 \fn       int32_t ARM_USBH_Initialize (ARM_USBH_SignalPortEvent_t cb_port_event, ARM_USBH_SignalPipeEvent_t cb_pipe_event)
 245 \details
 246 The function \b ARM_USBH_Initialize initializes the USB Host interface.
 247 It is called when the middleware component starts operation.
 248
 249 The function performs the following operations:
 250   - Initializes the resources needed for the USBH interface.
 251   - Registers the \ref ARM_USBH_SignalPortEvent callback function.
 252   - Registers the \ref ARM_USBH_SignalPipeEvent callback function.
 253
 254 The parameter \em cb_port_event is a pointer to the \ref ARM_USBH_SignalPortEvent callback function; use a NULL pointer
 255 when no port callback signals are required.
 256
 257 The parameter \em cb_pipe_event is a pointer to the \ref ARM_USBH_SignalPipeEvent callback function.
 258
 259 \b Example:
 260  - see \ref usbh_interface_gr - Driver Functions
 261
 262 *****************************************************************************************************************/
 263
 264 int32_t ARM_USBH_Uninitialize (void) {
 265   return ARM_DRIVER_OK;
 266 }
 267 /**
 268 \fn       int32_t ARM_USBH_Uninitialize (void)
 269 \details
 270 The function \b ARM_USBH_Uninitialize de-initializes the resources of USB Host interface.
 271
 272 It is called when the middleware component stops operation and releases the software resources used by the interface.
 273 *****************************************************************************************************************/
 274
 275 int32_t ARM_USBH_PowerControl (ARM_POWER_STATE state)  {
 276   return ARM_DRIVER_OK;
 277 }
 278 /**
 279 \fn int32_t ARM_USBH_PowerControl (ARM_POWER_STATE state)
 280 \details
 281 The function \b ARM_USBH_PowerControl operates the power modes of the USB Host interface.
 282
 283 The parameter \em state sets the operation and can have the following values:
 284   - \ref ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA.
 285                           Can be called multiple times. If the peripheral is already in this mode the function performs
 286                                                   no operation and returns with \ref ARM_DRIVER_OK.
 287   - \ref ARM_POWER_LOW : may use power saving. Returns \ref ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
 288   - \ref ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
 289
 290 Refer to \ref CallSequence for more information.
 291 *****************************************************************************************************************/
 292
 293 int32_t ARM_USBH_PortVbusOnOff (uint8_t port, bool vbus)  {
 294   return ARM_DRIVER_OK;
 295 }
 296 /**
 297 \fn int32_t ARM_USBH_PortVbusOnOff (uint8_t port, bool vbus)
 298 \details
 299 The function \b ARM_USBH_PortVbusOnOff controls the VBUS signal of the specified port.
 300 *****************************************************************************************************************/
 301
 302 int32_t ARM_USBH_PortReset (uint8_t port)  {
 303   return ARM_DRIVER_OK;
 304 }
 305 /**
 306 \fn int32_t ARM_USBH_PortReset (uint8_t port)
 307 \details
 308 Executes reset signalling on the specified port.
 309 *****************************************************************************************************************/
 310
 311 int32_t ARM_USBH_PortSuspend (uint8_t port)  {
 312   return ARM_DRIVER_OK;
 313 }
 314 /**
 315 \fn int32_t ARM_USBH_PortSuspend (uint8_t port)
 316 \details
 317 The function \b ARM_USBH_PortSuspend auspends USB signaling on the specified port.
 318 *****************************************************************************************************************/
 319
 320 int32_t ARM_USBH_PortResume (uint8_t port)  {
 321   return ARM_DRIVER_OK;
 322 }
 323 /**
 324 \fn int32_t ARM_USBH_PortResume (uint8_t port)
 325 \details
 326 The function \b ARM_USBH_PortResume resumes USB signaling on the specified port.
 327 *****************************************************************************************************************/
 328
 329 ARM_USBH_PORT_STATE ARM_USBH_PortGetState (uint8_t port)  {
 330   return 0;
 331 }
 332 /**
 333 \fn ARM_USBH_PORT_STATE ARM_USBH_PortGetState (uint8_t port)
 334 \details
 335 The function \b ARM_USBH_PortGetState returns the current state of the specified port.
 336 *****************************************************************************************************************/
 337
 338 ARM_USBH_PIPE_HANDLE ARM_USBH_PipeCreate (uint8_t  dev_addr,
 339                                           uint8_t  dev_speed,
 340                                           uint8_t  hub_addr,
 341                                           uint8_t  hub_port,
 342                                           uint8_t  ep_addr,
 343                                           uint8_t  ep_type,
 344                                           uint16_t ep_max_packet_size,
 345                                           uint8_t  ep_interval)  {
 346   return 0;
 347 }
 348 /**
 349 \fn ARM_USBH_PIPE_HANDLE ARM_USBH_PipeCreate (uint8_t dev_addr, uint8_t dev_speed, uint8_t hub_addr, uint8_t hub_port, uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval)
 350 \details
 351 The function \b ARM_USBH_PipeCreate creates a pipe for transfers (allocates required resources and configures the pipe).
 352
 353 The parameters specify pipe information (connection between host and device endpoint):
 354  - device: address and speed
 355  - hub (optional): hub address and number of the hub port to which the device is connected
 356  - endpoint: address, type, maximum packet size and polling interval
 357
 358 The function returns an pipe handle that is used for all subsequent operations on that pipe.
 359 In case of errors an invalid handle (\em NULL) is returned.
 360 *****************************************************************************************************************/
 361
 362 int32_t ARM_USBH_PipeModify (ARM_USBH_PIPE_HANDLE pipe_hndl,
 363                              uint8_t              dev_addr,
 364                              uint8_t              dev_speed,
 365                              uint8_t              hub_addr,
 366                              uint8_t              hub_port,
 367                              uint16_t             ep_max_packet_size)  {
 368   return ARM_DRIVER_OK;
 369 }
 370 /**
 371 \fn int32_t ARM_USBH_PipeModify (ARM_USBH_PIPE_HANDLE pipe_hndl, uint8_t dev_addr, uint8_t dev_speed, uint8_t hub_addr, uint8_t hub_port, uint16_t ep_max_packet_size)
 372 \details
 373 The function \b ARM_USBH_PipeModify modifies a pipe configuration that was created with \ref ARM_USBH_PipeCreate.
 374 *****************************************************************************************************************/
 375
 376 int32_t ARM_USBH_PipeDelete (ARM_USBH_PIPE_HANDLE pipe_hndl)  {
 377   return ARM_DRIVER_OK;
 378 }
 379 /**
 380 \fn int32_t ARM_USBH_PipeDelete (ARM_USBH_PIPE_HANDLE pipe_hndl)
 381 \details
 382 The function \b ARM_USBH_PipeDelete deletes a pipe that was created with \ref ARM_USBH_PipeCreate (deactivates the pipe and releases used resources).
 383 *****************************************************************************************************************/
 384
 385 int32_t ARM_USBH_PipeReset (ARM_USBH_PIPE_HANDLE pipe_hndl)  {
 386   return ARM_DRIVER_OK;
 387 }
 388 /**
 389 \fn int32_t ARM_USBH_PipeReset (ARM_USBH_PIPE_HANDLE pipe_hndl)
 390 \details
 391 The function \b ARM_USBH_PipeReset clears Halt condition and resets data toggle on the specified pipe.
 392 *****************************************************************************************************************/
 393
 394 int32_t ARM_USBH_PipeTransfer (ARM_USBH_PIPE_HANDLE pipe_hndl,
 395                                uint32_t packet,
 396                                uint8_t *data,
 397                                uint32_t num)  {
 398   return ARM_DRIVER_OK;
 399 }
 400 /**
 401 \fn int32_t ARM_USBH_PipeTransfer (ARM_USBH_PIPE_HANDLE pipe_hndl, uint32_t packet, uint8_t *data, uint32_t num)
 402 \details
 403 The function \b ARM_USBH_PipeTransfer generates packets for sending or receiving data from an USB Endpoint.
 404
 405 The function specifies the buffer with data to send or for data to receive and the number of bytes to transfer (must be multiple of device endpoint maximum packet size for receive).
 406 It also specifies \ref USBH_packets with parameter \em packet.
 407
 408 The function is non-blocking and returns as soon as the driver starts the operation on the specified pipe. During the operation it is not allowed to call this function again on the same pipe. Also the data buffer must stay allocated and the contents of data must not be modified.
 409
 410 Operation is completed when the the requested number of data bytes have been transferred and is indicated with \ref ARM_USBH_EVENT_TRANSFER_COMPLETE event.
 411 It can also finish earlier on reception of different handshake tokens which are also indicated through \ref USBH_pipe_events.
 412
 413 Transfer operation can be aborted by calling \ref ARM_USBH_PipeTransferAbort.
 414 *****************************************************************************************************************/
 415
 416 uint32_t ARM_USBH_PipeTransferGetResult (ARM_USBH_PIPE_HANDLE pipe_hndl)  {
 417   return 0;
 418 }
 419 /**
 420 \fn uint32_t ARM_USBH_PipeTransferGetResult (ARM_USBH_PIPE_HANDLE pipe_hndl)
 421 \details
 422 The function \b ARM_USBH_PipeTransferGetResult returns the number of successfully transferred data bytes started by \ref ARM_USBH_PipeTransfer operation.
 423 *****************************************************************************************************************/
 424
 425 int32_t ARM_USBH_PipeTransferAbort (ARM_USBH_PIPE_HANDLE pipe_hndl)  {
 426   return ARM_DRIVER_OK;
 427 }
 428 /**
 429 \fn int32_t ARM_USBH_PipeTransferAbort (ARM_USBH_PIPE_HANDLE pipe_hndl)
 430 \details
 431
 432 The function \b ARM_USBH_PipeTransferAbort aborts an active pipe transfer started by \ref ARM_USBH_PipeTransfer.
 433 *****************************************************************************************************************/
 434
 435 uint16_t ARM_USBH_GetFrameNumber (void)  {
 436   return 0;
 437 }
 438 /**
 439 \fn uint16_t ARM_USBH_GetFrameNumber (void)
 440 \details
 441 The function \b ARM_USBH_GetFrameNumber returns the sequential 11-bit frame number of the last Start of Frame (SOF) packet.
 442 *****************************************************************************************************************/
 443
 444 void ARM_USBH_SignalPortEvent (uint8_t port, uint32_t event)  {
 445   // function body
 446 }
 447 /**
 448 \fn void ARM_USBH_SignalPortEvent (uint8_t port, uint32_t event)
 449 \details
 450 The function \b ARM_USBH_SignalPortEvent is a callback function registered by the function \ref ARM_USBH_Initialize.
 451
 452 The parameter \em port specifies the root hub port number. \n
 453 The parameter \em event indicates one or more events that occurred during driver operation.
 454 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
 455
 456 Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the
 457 data fields of the structure \ref ARM_USBH_CAPABILITIES, which can be retrieved with the function \ref ARM_USBH_GetCapabilities.
 458
 459 The following events can be generated:
 460
 461 Parameter \em event               | Bit | Description                                                                | supported when ARM_USBH_CAPABILITIES
 462 :---------------------------------|:---:|:---------------------------------------------------------------------------|---------------------------------------
 463 \ref ARM_USBH_EVENT_CONNECT       |  0  | Occurs when USB Device connects to the Host.                               | data field \em event_connect=\token{1}
 464 \ref ARM_USBH_EVENT_DISCONNECT    |  1  | Occurs when USB Device disconnects from the Host.                          | data field \em event_disconnect=\token{1}
 465 \ref ARM_USBH_EVENT_OVERCURRENT   |  2  | Occurs when USB Overcurrent it detected.                                   | data field \em event_overcurrent=\token{1}
 466 \ref ARM_USBH_EVENT_RESET         |  3  | Occurs when USB Reset is completed after calling \ref ARM_USBH_PortReset.  | <i>always supported</i>
 467 \ref ARM_USBH_EVENT_SUSPEND       |  4  | Occurs when USB Suspend is detected.                                       | <i>always supported</i>
 468 \ref ARM_USBH_EVENT_RESUME        |  5  | Occurs when USB Resume is detected.                                        | <i>always supported</i>
 469 \ref ARM_USBH_EVENT_REMOTE_WAKEUP |  6  | Occurs when USB Remote wakeup is detected.                                 | <i>always supported</i>
 470 *****************************************************************************************************************/
 471
 472 void ARM_USBH_SignalPipeEvent (ARM_USBH_PIPE_HANDLE pipe_hndl, uint32_t event)  {
 473   // function body
 474 }
 475 /**
 476 \fn void ARM_USBH_SignalPipeEvent (ARM_USBH_PIPE_HANDLE pipe_hndl, uint32_t event)
 477 \details
 478 The function \b ARM_USBH_SignalPipeEvent is a callback function registered by the function \ref ARM_USBH_Initialize.
 479
 480 The parameter \em pipe_hndl specifies the pipe handle. \n
 481 The parameter \em event indicates one or more events that occurred during driver operation.
 482 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
 483
 484 The following events can be generated:
 485
 486 Parameter \em event                       | Bit| Description
 487 :-----------------------------------------|---:|:-----------
 488 \ref ARM_USBH_EVENT_TRANSFER_COMPLETE     | 0  | Occurs after all the data has been transferred without errors.
 489 \ref ARM_USBH_EVENT_HANDSHAKE_NAK         | 1  | Occurs when NAK Handshake is received before all the data is transferred.
 490 \ref ARM_USBH_EVENT_HANDSHAKE_NYET        | 2  | Occurs when NYET Handshake is received before all the data is transferred.
 491 \ref ARM_USBH_EVENT_HANDSHAKE_MDATA       | 3  | Occurs when MDATA Handshake is received before all the data is transferred.
 492 \ref ARM_USBH_EVENT_HANDSHAKE_STALL       | 4  | Occurs when STALL Handshake is received before all the data is transferred.
 493 \ref ARM_USBH_EVENT_HANDSHAKE_ERR         | 5  | Occurs when ERR Handshake is received before all the data is transferred.
 494 \ref ARM_USBH_EVENT_BUS_ERROR             | 6  | Occurs when bus error is detected before all the data is transferred.
 495
 496 <b>See also:</b>
 497  - ARM_USBH_PipeCreate
 498 *****************************************************************************************************************/
 499
 500 /**
 501 @}
 502 */
 503
 504
 505
 506 /**
 507 \defgroup usbh_hci_gr USB OHCI/EHCI
 508 \ingroup usbh_interface_gr
 509 \brief  Driver API for USB OHCI/EHCI
 510 \details
 511 OHCI and EHCI compliant interfaces have memory mapped registers that are used to control the USB host.
 512
 513 Only certain functionalities (interrupts, VBUS control, power control) require device specific interface which is provided through functions
 514 of the struct \ref ARM_DRIVER_USBH_HCI (functionality accessed with the struct \ref ARM_DRIVER_USBH is not needed).
 515 @{
 516 */
 517
 518 /**
 519 \struct ARM_DRIVER_USBH_HCI
 520 \details
 521 The functions of the USB Host HCI (OHCI/EHCI) driver are accessed by function pointers. Refer to \ref DriverFunctions for
 522 overview information.
 523
 524 Each instance of an USBH provides such an access struct. The instance is indicated by
 525 a postfix in the symbol name of the access struct, for example:
 526  - \b Driver_USBH0_HCI is the name of the access struct of the first instance (no. 0).
 527  - \b Driver_USBH1_HCI is the name of the access struct of the second instance (no. 1).
 528
 529
 530 A configuration setting in the middleware allows connecting the middleware to a specific driver instance <b>Driver_USBH<i>n</i>_HCI</b>.
 531 The default is \token{0}, which connects a middleware to the first instance of a driver.
 532
 533 \note    The struct must remain unchanged.
 534 */
 535
 536
 537 /**
 538 \struct ARM_USBH_HCI_CAPABILITIES
 539 \details
 540 A USB Host HCI (OHCI/EHCI) driver can be implemented with different capabilities.
 541 The data fields of this structure encode the capabilities implemented by this driver.
 542
 543 <b>Returned by:</b>
 544   - \ref ARM_USBH_HCI_GetCapabilities
 545
 546 \note    The struct must remain unchanged.
 547 *****************************************************************************************************************/
 548
 549 /**
 550 \typedef    ARM_USBH_HCI_Interrupt_t
 551 \details
 552 Provides the typedef for the interrupt handler \ref ARM_USBH_HCI_Interrupt.
 553
 554 <b>Parameter for:</b>
 555   - \ref ARM_USBH_HCI_Initialize
 556 *******************************************************************************************************************/
 557
 558
 559 //
 560 // Functions
 561 //
 562
 563 ARM_DRIVER_VERSION ARM_USBH_HCI_GetVersion (void)  {
 564   return { 0, 0 };
 565 }
 566 /**
 567 \fn       ARM_DRIVER_VERSION ARM_USBH_HCI_GetVersion (void)
 568 \details
 569 The function \b ARM_USBH_HCI_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
 570  - API version is the version of the CMSIS-Driver specification used to implement this driver.
 571  - Driver version is source code version of the actual driver implementation.
 572
 573 Example:
 574 \code
 575 extern ARM_DRIVER_USBH Driver_USBH0_HCI;
 576 ARM_DRIVER_USBH *drv_info;
 577
 578 void setup_usbh (void)  {
 579   ARM_DRIVER_VERSION  version;
 580
 581   drv_info = &Driver_USBH0_HCI;
 582   version = drv_info->GetVersion ();
 583   if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
 584     // error handling
 585     return;
 586   }
 587 }
 588 \endcode
 589 *****************************************************************************************************************/
 590
 591 ARM_USBH_HCI_CAPABILITIES ARM_USBH_HCI_GetCapabilities (void)  {
 592   return { 0 };
 593 }
 594 /**
 595 \fn       ARM_USBH_HCI_CAPABILITIES ARM_USBH_HCI_GetCapabilities (void)
 596 \details
 597 The function \b ARM_USBH_HCI_GetCapabilities returns information about capabilities in this driver implementation.
 598 The data fields of the structure \ref ARM_USBH_HCI_CAPABILITIES encode various capabilities, for example
 599 available HUB ports.
 600
 601 Example:
 602 \code
 603 extern ARM_DRIVER_USBH_HCI Driver_USBH0_HCI;
 604 ARM_DRIVER_USBH_HCI *drv_info;
 605
 606 void read_capabilities (void)  {
 607   ARM_USBH_HCI_CAPABILITIES drv_capabilities;
 608
 609   drv_info = &Driver_USBH0_HCI;
 610   drv_capabilities = drv_info->GetCapabilities ();
 611   // interrogate capabilities
 612
 613 }
 614 \endcode
 615 *****************************************************************************************************************/
 616
 617 int32_t ARM_USBH_HCI_Initialize (ARM_USBH_HCI_Interrupt_t *cb_interrupt)  {
 618   return ARM_DRIVER_OK;
 619 }
 620 /**
 621 \fn       int32_t ARM_USBH_HCI_Initialize (ARM_USBH_HCI_Interrupt_t *cb_interrupt)
 622 \details
 623 The function \b ARM_USBH_HCI_Initialize initializes the USB Host HCI (OHCI/EHCI) interface.
 624 It is called when the middleware component starts operation.
 625
 626 The function performs the following operations:
 627   - Initializes the resources needed for the USBH interface.
 628   - Registers the \ref ARM_USBH_HCI_Interrupt interrupt handler.
 629
 630 The parameter \em cb_interrupt is a pointer to the interrupt routine of the OHCI/EHCI peripheral
 631 that needs to be registered. This function is called as ECHI Interrupt Service Handler.
 632
 633 \b Example:
 634  - see \ref usbh_interface_gr - Driver Functions
 635
 636 *****************************************************************************************************************/
 637
 638 int32_t ARM_USBH_HCI_Uninitialize (void) {
 639   return ARM_DRIVER_OK;
 640 }
 641 /**
 642 \fn       int32_t ARM_USBH_HCI_Uninitialize (void)
 643 \details
 644 The function \ref ARM_USBH_HCI_Uninitialize de-initializes the resources of USB Host HCI (OHCI/EHCI) interface.
 645
 646 It is called when the middleware component stops operation and releases the software resources used by the interface.
 647 *****************************************************************************************************************/
 648
 649 int32_t ARM_USBH_HCI_PowerControl (ARM_POWER_STATE state)  {
 650   return ARM_DRIVER_OK;
 651 }
 652 /**
 653 \fn int32_t ARM_USBH_HCI_PowerControl (ARM_POWER_STATE state)
 654 \details
 655 The function \b ARM_USBH_HCI_PowerControl operates the power modes of the USB Host HCI (OHCI/EHCI) interface.
 656
 657 The parameter \em state sets the operation and can have the following values:
 658   - \ref ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA.
 659                           Can be called multiple times. If the peripheral is already in this mode the function performs
 660                                                   no operation and returns with \ref ARM_DRIVER_OK.
 661   - \ref ARM_POWER_LOW : may use power saving. Returns \ref ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
 662   - \ref ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
 663
 664 Refer to \ref CallSequence for more information.
 665 *****************************************************************************************************************/
 666
 667 int32_t ARM_USBH_HCI_PortVbusOnOff (uint8_t port, bool vbus)  {
 668   return ARM_DRIVER_OK;
 669 }
 670 /**
 671 \fn int32_t ARM_USBH_HCI_PortVbusOnOff (uint8_t port, bool vbus)
 672 \details
 673 The function \b  ARM_USBH_HCI_PortVbusOnOff controls the VBUS signal of the specified port.
 674 Most HCI complained USB Host controllers do not require this optional function.
 675 It is only required when a external VBUS interface (for example via I/O pin) is required.
 676
 677 *****************************************************************************************************************/
 678
 679 void ARM_USBH_HCI_Interrupt (void)  {
 680   // function body
 681 }
 682 /**
 683 \fn void ARM_USBH_HCI_Interrupt (void)
 684 \details
 685 The function \b ARM_USBH_HCI_Interrupt is called from the USBH HCI Interrupt Handler.
 686 *****************************************************************************************************************/
 687
 688 /**
 689 @}
 690 */
 691 // End USBH Interface