begriffs open source - cmsis/blob - CMSIS/DoxyGen/Driver/src/Driver_USBH.c

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