EdkModulePkg/Bus/Usb/UsbBus/Dxe/usbbus.h

   1 /*++
   2 Copyright (c) 2006, Intel Corporation
   3 All rights reserved. This program and the accompanying materials
   4 are licensed and made available under the terms and conditions of the BSD License
   5 which accompanies this distribution.  The full text of the license may be found at
   6 http://opensource.org/licenses/bsd-license.php
   7
   8 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
   9 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  10
  11   Module Name:
  12
  13     usbbus.h
  14
  15   Abstract:
  16
  17     Header file for USB bus driver Interface
  18
  19   Revision History
  20
  21
  22
  23 --*/
  24
  25 #ifndef _EFI_USB_BUS_H
  26 #define _EFI_USB_BUS_H
  27
  28
  29 #include <IndustryStandard/Usb.h>
  30 #include "hub.h"
  31 #include "usbutil.h"
  32
  33 extern UINTN  gUSBDebugLevel;
  34 extern UINTN  gUSBErrorLevel;
  35
  36 #define MICROSECOND       10000
  37 #define ONESECOND         (1000 * MICROSECOND)
  38 #define BUSPOLLING_PERIOD ONESECOND
  39 //
  40 // We define some maximun value here
  41 //
  42 #define USB_MAXCONFIG               8
  43 #define USB_MAXALTSETTING           4
  44 #define USB_MAXINTERFACES           32
  45 #define USB_MAXENDPOINTS            16
  46 #define USB_MAXSTRINGS              16
  47 #define USB_MAXLANID                16
  48 #define USB_MAXCHILDREN             8
  49 #define USB_MAXCONTROLLERS          4
  50
  51 #define USB_IO_CONTROLLER_SIGNATURE EFI_SIGNATURE_32 ('u', 's', 'b', 'd')
  52
  53 typedef struct {
  54   LIST_ENTRY      Link;
  55   UINT16          StringIndex;
  56   CHAR16          *String;
  57 } STR_LIST_ENTRY;
  58
  59 typedef struct {
  60   LIST_ENTRY                  Link;
  61   UINT16                      Toggle;
  62   EFI_USB_ENDPOINT_DESCRIPTOR EndpointDescriptor;
  63 } ENDPOINT_DESC_LIST_ENTRY;
  64
  65 typedef struct {
  66   LIST_ENTRY                    Link;
  67   EFI_USB_INTERFACE_DESCRIPTOR  InterfaceDescriptor;
  68   LIST_ENTRY                    EndpointDescListHead;
  69 } INTERFACE_DESC_LIST_ENTRY;
  70
  71 typedef struct {
  72   LIST_ENTRY                Link;
  73   EFI_USB_CONFIG_DESCRIPTOR CongfigDescriptor;
  74   LIST_ENTRY                InterfaceDescListHead;
  75   UINTN                     ActiveInterface;
  76 } CONFIG_DESC_LIST_ENTRY;
  77
  78 //
  79 // Forward declaring
  80 //
  81 struct usb_io_device;
  82
  83 //
  84 // This is used to form the USB Controller Handle
  85 //
  86 typedef struct usb_io_controller_device {
  87   UINTN                           Signature;
  88   EFI_HANDLE                      Handle;
  89   EFI_USB_IO_PROTOCOL             UsbIo;
  90   EFI_DEVICE_PATH_PROTOCOL        *DevicePath;
  91   EFI_HANDLE                      HostController;
  92   UINT8                           CurrentConfigValue;
  93   UINT8                           InterfaceNumber;
  94   struct usb_io_device            *UsbDevice;
  95
  96   BOOLEAN                         IsUsbHub;
  97   BOOLEAN                         IsManagedByDriver;
  98
  99   //
 100   // Fields specified for USB Hub
 101   //
 102   EFI_EVENT                       HubNotify;
 103   UINT8                           HubEndpointAddress;
 104   UINT8                           StatusChangePort;
 105   UINT8                           DownstreamPorts;
 106
 107   UINT8                           ParentPort;
 108   struct usb_io_controller_device *Parent;
 109   struct usb_io_device            *Children[USB_MAXCHILDREN];
 110 } USB_IO_CONTROLLER_DEVICE;
 111
 112 #define USB_IO_CONTROLLER_DEVICE_FROM_USB_IO_THIS(a) \
 113     CR(a, USB_IO_CONTROLLER_DEVICE, UsbIo, USB_IO_CONTROLLER_SIGNATURE)
 114
 115 //
 116 // This is used to keep the topology of USB bus
 117 //
 118 struct _usb_bus_controller_device;
 119
 120 typedef struct usb_io_device {
 121   UINT8                               DeviceAddress;
 122   BOOLEAN                             IsConfigured;
 123   BOOLEAN                             IsSlowDevice;
 124   UINT8                               DeviceSpeed;
 125   EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator;
 126   EFI_USB_DEVICE_DESCRIPTOR           DeviceDescriptor;
 127   LIST_ENTRY                          ConfigDescListHead;
 128   CONFIG_DESC_LIST_ENTRY              *ActiveConfig;
 129   UINT16                              LangID[USB_MAXLANID];
 130
 131   struct _usb_bus_controller_device   *BusController;
 132
 133   //
 134   // Track the controller handle
 135   //
 136   UINT8                               NumOfControllers;
 137   USB_IO_CONTROLLER_DEVICE            *UsbController[USB_MAXCONTROLLERS];
 138
 139 } USB_IO_DEVICE;
 140
 141 //
 142 // Usb Bus Controller device strcuture
 143 //
 144 #define EFI_USB_BUS_PROTOCOL_GUID \
 145  { 0x2B2F68CC, 0x0CD2, 0x44cf, { 0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75  } }
 146
 147 typedef struct _EFI_USB_BUS_PROTOCOL {
 148   UINT64  Reserved;
 149 } EFI_USB_BUS_PROTOCOL;
 150
 151 #define USB_BUS_DEVICE_SIGNATURE  EFI_SIGNATURE_32 ('u', 'b', 'u', 's')
 152
 153 typedef struct _usb_bus_controller_device {
 154   UINTN                     Signature;
 155
 156   EFI_USB_BUS_PROTOCOL      BusIdentify;
 157   EFI_USB2_HC_PROTOCOL      *Usb2HCInterface;
 158   EFI_USB_HC_PROTOCOL       *UsbHCInterface;
 159   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
 160   UINT8                     AddressPool[16];
 161   USB_IO_DEVICE             *Root;
 162   BOOLEAN                   Hc2ProtocolSupported;
 163 } USB_BUS_CONTROLLER_DEVICE;
 164
 165 #define USB_BUS_CONTROLLER_DEVICE_FROM_THIS(a) \
 166     CR(a, USB_BUS_CONTROLLER_DEVICE, BusIdentify, USB_BUS_DEVICE_SIGNATURE)
 167
 168
 169 //
 170 // Global Variables
 171 //
 172 extern EFI_DRIVER_BINDING_PROTOCOL  gUsbBusDriverBinding;
 173 extern EFI_COMPONENT_NAME_PROTOCOL  gUsbBusComponentName;
 174 extern EFI_GUID                     gUSBBusDriverGuid;
 175
 176 //
 177 // Usb Device Configuration functions
 178 //
 179 BOOLEAN
 180 IsHub (
 181   IN USB_IO_CONTROLLER_DEVICE     *Dev
 182   )
 183 /*++
 184
 185   Routine Description:
 186     Tell if a usb controller is a hub controller.
 187
 188   Arguments:
 189     Dev - UsbIoController device structure.
 190
 191   Returns:
 192     TRUE/FALSE
 193 --*/
 194 ;
 195
 196 EFI_STATUS
 197 UsbGetStringtable (
 198   IN  USB_IO_DEVICE     *UsbIoDevice
 199   )
 200 /*++
 201
 202   Routine Description:
 203     Get the string table stored in a usb device.
 204
 205   Arguments:
 206     Dev     -     UsbIoController device structure.
 207
 208   Returns:
 209     EFI_SUCCESS
 210     EFI_UNSUPPORTED
 211     EFI_OUT_OF_RESOURCES
 212
 213 --*/
 214 ;
 215
 216 EFI_STATUS
 217 UsbGetAllConfigurations (
 218   IN  USB_IO_DEVICE     *UsbIoDevice
 219   )
 220 /*++
 221
 222   Routine Description:
 223     This function is to parse all the configuration descriptor.
 224
 225   Arguments:
 226     UsbIoDevice  -  USB_IO_DEVICE device structure.
 227
 228   Returns:
 229     EFI_SUCCESS
 230     EFI_DEVICE_ERROR
 231     EFI_OUT_OF_RESOURCES
 232
 233 --*/
 234 ;
 235
 236 EFI_STATUS
 237 UsbSetConfiguration (
 238   IN  USB_IO_DEVICE     *Dev,
 239   IN  UINTN             ConfigurationValue
 240   )
 241 /*++
 242
 243   Routine Description:
 244     Set the device to a configuration value.
 245
 246   Arguments:
 247     UsbIoDev            -   USB_IO_DEVICE to be set configuration
 248     ConfigrationValue   -   The configuration value to be set to that device
 249
 250   Returns:
 251     EFI_SUCCESS
 252     EFI_DEVICE_ERROR
 253
 254 --*/
 255 ;
 256
 257 EFI_STATUS
 258 UsbSetDefaultConfiguration (
 259   IN  USB_IO_DEVICE     *Dev
 260   )
 261 /*++
 262
 263   Routine Description:
 264     Set the device to a default configuration value.
 265
 266   Arguments:
 267     UsbIoDev       -    USB_IO_DEVICE to be set configuration
 268
 269   Returns
 270     EFI_SUCCESS
 271     EFI_DEVICE_ERROR
 272
 273 --*/
 274 ;
 275
 276 //
 277 // Device Deconfiguration functions
 278 //
 279 VOID
 280 UsbDestroyAllConfiguration (
 281   IN USB_IO_DEVICE     *UsbIoDevice
 282   )
 283 /*++
 284
 285   Routine Description:
 286     Delete all configuration data when device is not used.
 287
 288   Arguments:
 289     UsbIoDevice  - USB_IO_DEVICE to be set configuration
 290
 291   Returns:
 292     VOID
 293
 294 --*/
 295 ;
 296
 297 EFI_STATUS
 298 DoHubConfig (
 299   IN USB_IO_CONTROLLER_DEVICE     *HubIoDevice
 300   )
 301 /*++
 302
 303   Routine Description:
 304     Configure the hub
 305
 306   Arguments:
 307     HubController         -   Indicating the hub controller device that
 308                               will be configured
 309
 310   Returns:
 311     EFI_SUCCESS
 312     EFI_DEVICE_ERROR
 313
 314 --*/
 315
 316 ;
 317
 318 VOID
 319 GetDeviceEndPointMaxPacketLength (
 320   IN EFI_USB_IO_PROTOCOL    *UsbIo,
 321   IN  UINT8                 EndpointAddr,
 322   OUT UINTN                 *MaxPacketLength
 323   )
 324 /*++
 325
 326   Routine Description:
 327     Get the Max Packet Length of the speified Endpoint.
 328
 329   Arguments:
 330     UsbIo           -     Given Usb Controller device.
 331     EndpointAddr    -     Given Endpoint address.
 332     MaxPacketLength -     The max packet length of that endpoint
 333
 334   Returns:
 335     N/A
 336
 337 --*/
 338 ;
 339
 340 VOID
 341 GetDataToggleBit (
 342   IN EFI_USB_IO_PROTOCOL    *UsbIo,
 343   IN  UINT8                 EndpointAddr,
 344   OUT UINT8                 *DataToggle
 345   )
 346 /*++
 347
 348   Routine Description:
 349     Get the datatoggle of a specified endpoint.
 350
 351   Arguments:
 352     UsbIo         -     Given Usb Controller device.
 353     EndpointAddr  -     Given Endpoint address.
 354     DataToggle    -     The current data toggle of that endpoint
 355
 356   Returns:
 357     VOID
 358
 359 --*/
 360 ;
 361
 362 VOID
 363 SetDataToggleBit (
 364   IN EFI_USB_IO_PROTOCOL    *UsbIo,
 365   IN UINT8                  EndpointAddr,
 366   IN UINT8                  DataToggle
 367   )
 368 /*++
 369
 370   Routine Description:
 371     Set the datatoggle of a specified endpoint
 372
 373   Arguments:
 374     UsbIo         -     Given Usb Controller device.
 375     EndpointAddr  -     Given Endpoint address.
 376     DataToggle    -     The current data toggle of that endpoint to be set
 377
 378   Returns:
 379     VOID
 380
 381 --*/
 382 ;
 383
 384 INTERFACE_DESC_LIST_ENTRY           *
 385 FindInterfaceListEntry (
 386   IN EFI_USB_IO_PROTOCOL    *This
 387   )
 388 /*++
 389
 390   Routine Description:
 391     Find Interface ListEntry.
 392
 393   Arguments:
 394     This         -  EFI_USB_IO_PROTOCOL
 395
 396   Returns:
 397     INTERFACE_DESC_LIST_ENTRY pointer
 398
 399 --*/
 400 ;
 401
 402 ENDPOINT_DESC_LIST_ENTRY            *
 403 FindEndPointListEntry (
 404   IN EFI_USB_IO_PROTOCOL    *This,
 405   IN UINT8                  EndPointAddress
 406   )
 407 /*++
 408
 409   Routine Description:
 410     Find EndPoint ListEntry.
 411
 412   Arguments:
 413     This         -  EFI_USB_IO_PROTOCOL
 414     EndpointAddr -  Endpoint address.
 415
 416   Returns:
 417     ENDPOINT_DESC_LIST_ENTRY pointer
 418
 419 --*/
 420 ;
 421
 422 EFI_STATUS
 423 IsDeviceDisconnected (
 424   IN USB_IO_CONTROLLER_DEVICE    *UsbIoController,
 425   IN OUT BOOLEAN                 *Disconnected
 426   )
 427 /*++
 428
 429   Routine Description:
 430     Reset if the device is disconencted or not
 431
 432   Arguments:
 433     UsbIoController   -   Indicating the Usb Controller Device.
 434     Disconnected      -   Indicate whether the device is disconencted or not
 435
 436   Returns:
 437     EFI_SUCCESS
 438     EFI_DEVICE_ERROR
 439
 440 --*/
 441 ;
 442
 443 EFI_STATUS
 444 UsbDeviceDeConfiguration (
 445   IN USB_IO_DEVICE     *UsbIoDevice
 446   )
 447 /*++
 448
 449   Routine Description:
 450     Remove Device, Device Handles, Uninstall Protocols.
 451
 452   Arguments:
 453     UsbIoDevice     -   The device to be deconfigured.
 454
 455   Returns:
 456     EFI_SUCCESS
 457     EFI_DEVICE_ERROR
 458
 459 --*/
 460 ;
 461
 462 EFI_STATUS
 463 EFIAPI
 464 UsbVirtualHcGetCapability (
 465   IN  USB_BUS_CONTROLLER_DEVICE *UsbBusDev,
 466   OUT UINT8                     *MaxSpeed,
 467   OUT UINT8                     *PortNumber,
 468   OUT UINT8                     *Is64BitCapable
 469   )
 470 /*++
 471
 472   Routine Description:
 473
 474     Virtual interface to Retrieves the capablility of root hub ports
 475     for both Hc2 and Hc protocol.
 476
 477   Arguments:
 478
 479     UsbBusDev       - A pointer to bus controller of the device.
 480     MaxSpeed        - A pointer to the number of the host controller.
 481     PortNumber      - A pointer to the number of the root hub ports.
 482     Is64BitCapable  - A pointer to the flag for whether controller supports
 483                       64-bit memory addressing.
 484
 485   Returns:
 486
 487     EFI_SUCCESS
 488           The host controller capability were retrieved successfully.
 489     EFI_INVALID_PARAMETER
 490           MaxSpeed or PortNumber or Is64BitCapable is NULL.
 491     EFI_DEVICE_ERROR
 492           An error was encountered while attempting to retrieve the capabilities.
 493
 494 --*/
 495 ;
 496
 497 EFI_STATUS
 498 EFIAPI
 499 UsbVirtualHcReset (
 500   IN  USB_BUS_CONTROLLER_DEVICE *UsbBusDev,
 501   IN UINT16                     Attributes
 502   )
 503 /*++
 504
 505   Routine Description:
 506
 507     Virtual interface to provides software reset for the USB host controller
 508     for both Hc2 and Hc protocol.
 509
 510   Arguments:
 511
 512     UsbBusDev   - A pointer to bus controller of the device.
 513     Attributes  - A bit mask of the reset operation to perform.
 514                 See below for a list of the supported bit mask values.
 515
 516   #define EFI_USB_HC_RESET_GLOBAL  0x0001               // Hc2 and Hc
 517   #define EFI_USB_HC_RESET_HOST_CONTROLLER  0x0002      // Hc2 and Hc
 518   #define EFI_USB_HC_RESET_GLOBAL_WITH_DEBUG  0x0004    // Hc2
 519   #define EFI_USB_HC_RESET_HOST_WITH_DEBUG  0x0008      // Hc2
 520
 521   EFI_USB_HC_RESET_GLOBAL
 522         If this bit is set, a global reset signal will be sent to the USB bus.
 523         This resets all of the USB bus logic, including the USB host
 524         controller hardware and all the devices attached on the USB bus.
 525   EFI_USB_HC_RESET_HOST_CONTROLLER
 526         If this bit is set, the USB host controller hardware will be reset.
 527         No reset signal will be sent to the USB bus.
 528   EFI_USB_HC_RESET_GLOBAL_WITH_DEBUG
 529         If this bit is set, a global reset signal will be sent to the USB bus.
 530         This resets all of the USB bus logic, including the USB host
 531         controller hardware and all the devices attached on the USB bus.
 532         If this is an EHCI controller and the debug port has configured, then
 533         this is will still reset the host controller.
 534   EFI_USB_HC_RESET_HOST_WITH_DEBUG
 535         If this bit is set, the USB host controller hardware will be reset.
 536         If this is an EHCI controller and the debug port has been configured,
 537         then this will still reset the host controller.
 538
 539   Returns:
 540
 541     EFI_SUCCESS
 542         The reset operation succeeded.
 543     EFI_INVALID_PARAMETER
 544         Attributes is not valid.
 545     EFI_UNSUPPOURTED
 546         The type of reset specified by Attributes is not currently supported by
 547         the host controller hardware.
 548     EFI_ACCESS_DENIED
 549         Reset operation is rejected due to the debug port being configured and
 550         active; only EFI_USB_HC_RESET_GLOBAL_WITH_DEBUG or
 551         EFI_USB_HC_RESET_HOST_WITH_DEBUG reset Atrributes can be used to
 552         perform reset operation for this host controller.
 553     EFI_DEVICE_ERROR
 554         An error was encountered while attempting to perform
 555         the reset operation.
 556
 557 --*/
 558 ;
 559
 560 EFI_STATUS
 561 EFIAPI
 562 UsbVirtualHcGetState (
 563   IN  USB_BUS_CONTROLLER_DEVICE *UsbBusDev,
 564   OUT EFI_USB_HC_STATE          *State
 565   )
 566 /*++
 567
 568   Routine Description:
 569
 570     Virtual interface to retrieves current state of the USB host controller
 571     for both Hc2 and Hc protocol.
 572
 573   Arguments:
 574
 575     UsbBusDev - A pointer to bus controller of the device.
 576     State     - A pointer to the EFI_USB_HC_STATE data structure that
 577               indicates current state of the USB host controller.
 578               Type EFI_USB_HC_STATE is defined below.
 579
 580     typedef enum {
 581       EfiUsbHcStateHalt,
 582       EfiUsbHcStateOperational,
 583       EfiUsbHcStateSuspend,
 584       EfiUsbHcStateMaximum
 585     } EFI_USB_HC_STATE;
 586
 587   Returns:
 588
 589     EFI_SUCCESS
 590             The state information of the host controller was returned in State.
 591     EFI_INVALID_PARAMETER
 592             State is NULL.
 593     EFI_DEVICE_ERROR
 594             An error was encountered while attempting to retrieve the
 595             host controller's current state.
 596
 597 --*/
 598 ;
 599
 600 EFI_STATUS
 601 EFIAPI
 602 UsbVirtualHcSetState (
 603   IN  USB_BUS_CONTROLLER_DEVICE *UsbBusDev,
 604   IN EFI_USB_HC_STATE           State
 605   )
 606 /*++
 607
 608   Routine Description:
 609
 610     Virtual interface to sets the USB host controller to a specific state
 611     for both Hc2 and Hc protocol.
 612
 613   Arguments:
 614
 615     UsbBusDev   - A pointer to bus controller of the device.
 616     State       - Indicates the state of the host controller that will be set.
 617
 618   Returns:
 619
 620     EFI_SUCCESS
 621           The USB host controller was successfully placed in the state
 622           specified by State.
 623     EFI_INVALID_PARAMETER
 624           State is invalid.
 625     EFI_DEVICE_ERROR
 626           Failed to set the state specified by State due to device error.
 627
 628 --*/
 629 ;
 630
 631 EFI_STATUS
 632 EFIAPI
 633 UsbVirtualHcGetRootHubPortStatus (
 634   IN  USB_BUS_CONTROLLER_DEVICE *UsbBusDev,
 635   IN  UINT8                     PortNumber,
 636   OUT EFI_USB_PORT_STATUS       *PortStatus
 637   )
 638 /*++
 639
 640   Routine Description:
 641
 642     Virtual interface to retrieves the current status of a USB root hub port
 643     both for Hc2 and Hc protocol.
 644
 645   Arguments:
 646
 647     UsbBusDev   - A pointer to bus controller of the device.
 648     PortNumber  - Specifies the root hub port from which the status
 649                 is to be retrieved.  This value is zero-based. For example,
 650                 if a root hub has two ports, then the first port is numbered 0,
 651                 and the second port is numbered 1.
 652     PortStatus  - A pointer to the current port status bits and
 653                 port status change bits.
 654
 655   Returns:
 656
 657     EFI_SUCCESS  The status of the USB root hub port specified by PortNumber
 658                  was returned in PortStatus.
 659     EFI_INVALID_PARAMETER PortNumber is invalid.
 660     EFI_DEVICE_ERROR      Can't read register
 661
 662 --*/
 663 ;
 664
 665 EFI_STATUS
 666 EFIAPI
 667 UsbVirtualHcSetRootHubPortFeature (
 668   IN  USB_BUS_CONTROLLER_DEVICE *UsbBusDev,
 669   IN  UINT8                     PortNumber,
 670   IN  EFI_USB_PORT_FEATURE      PortFeature
 671   )
 672 /*++
 673
 674   Routine Description:
 675     Virual interface to sets a feature for the specified root hub port
 676     for both Hc2 and Hc protocol.
 677
 678   Arguments:
 679
 680     UsbBusDev   - A pointer to bus controller of the device.
 681     PortNumber  - Specifies the root hub port whose feature
 682                 is requested to be set.
 683     PortFeature - Indicates the feature selector associated
 684                 with the feature set request.
 685
 686   Returns:
 687
 688     EFI_SUCCESS
 689         The feature specified by PortFeature was set for the
 690         USB root hub port specified by PortNumber.
 691     EFI_INVALID_PARAMETER
 692         PortNumber is invalid or PortFeature is invalid.
 693     EFI_DEVICE_ERROR
 694         Can't read register
 695
 696 --*/
 697 ;
 698
 699 EFI_STATUS
 700 EFIAPI
 701 UsbVirtualHcClearRootHubPortFeature (
 702   IN  USB_BUS_CONTROLLER_DEVICE *UsbBusDev,
 703   IN  UINT8                     PortNumber,
 704   IN  EFI_USB_PORT_FEATURE      PortFeature
 705   )
 706 /*++
 707
 708   Routine Description:
 709
 710     Virtual interface to clears a feature for the specified root hub port
 711     for both Hc2 and Hc protocol.
 712
 713   Arguments:
 714
 715     UsbBusDev   - A pointer to bus controller of the device.
 716     PortNumber  - Specifies the root hub port whose feature
 717                 is requested to be cleared.
 718     PortFeature - Indicates the feature selector associated with the
 719                 feature clear request.
 720
 721   Returns:
 722
 723     EFI_SUCCESS
 724         The feature specified by PortFeature was cleared for the
 725         USB root hub port specified by PortNumber.
 726     EFI_INVALID_PARAMETER
 727         PortNumber is invalid or PortFeature is invalid.
 728     EFI_DEVICE_ERROR
 729         Can't read register
 730
 731 --*/
 732 ;
 733
 734 EFI_STATUS
 735 EFIAPI
 736 UsbVirtualHcControlTransfer (
 737   IN  USB_BUS_CONTROLLER_DEVICE            *UsbBusDev,
 738   IN  UINT8                                DeviceAddress,
 739   IN  UINT8                                DeviceSpeed,
 740   IN  UINTN                                MaximumPacketLength,
 741   IN  EFI_USB_DEVICE_REQUEST               *Request,
 742   IN  EFI_USB_DATA_DIRECTION               TransferDirection,
 743   IN  OUT VOID                             *Data,
 744   IN  OUT UINTN                            *DataLength,
 745   IN  UINTN                                TimeOut,
 746   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR   *Translator,
 747   OUT UINT32                               *TransferResult
 748   )
 749 /*++
 750
 751   Routine Description:
 752
 753     Virtual interface to submits control transfer to a target USB device
 754     for both Hc2 and Hc protocol.
 755
 756   Arguments:
 757
 758     UsbBusDev     - A pointer to bus controller of the device.
 759     DeviceAddress - Represents the address of the target device on the USB,
 760                   which is assigned during USB enumeration.
 761     DeviceSpeed   - Indicates target device speed.
 762     MaximumPacketLength - Indicates the maximum packet size that the
 763                         default control transfer endpoint is capable of
 764                         sending or receiving.
 765     Request       - A pointer to the USB device request that will be sent
 766                   to the USB device.
 767     TransferDirection - Specifies the data direction for the transfer.
 768                       There are three values available, DataIn, DataOut
 769                       and NoData.
 770     Data          - A pointer to the buffer of data that will be transmitted
 771                   to USB device or received from USB device.
 772     DataLength    - Indicates the size, in bytes, of the data buffer
 773                   specified by Data.
 774     TimeOut       - Indicates the maximum time, in microseconds,
 775                   which the transfer is allowed to complete.
 776     Translator      - A pointr to the transaction translator data.
 777     TransferResult  - A pointer to the detailed result information generated
 778                     by this control transfer.
 779
 780   Returns:
 781
 782     EFI_SUCCESS
 783         The control transfer was completed successfully.
 784     EFI_OUT_OF_RESOURCES
 785         The control transfer could not be completed due to a lack of resources.
 786     EFI_INVALID_PARAMETER
 787         Some parameters are invalid.
 788     EFI_TIMEOUT
 789         The control transfer failed due to timeout.
 790     EFI_DEVICE_ERROR
 791         The control transfer failed due to host controller or device error.
 792         Caller should check TranferResult for detailed error information.
 793
 794 --*/
 795 ;
 796
 797 EFI_STATUS
 798 EFIAPI
 799 UsbVirtualHcBulkTransfer (
 800   IN  USB_BUS_CONTROLLER_DEVICE           *UsbBusDev,
 801   IN  UINT8                               DeviceAddress,
 802   IN  UINT8                               EndPointAddress,
 803   IN  UINT8                               DeviceSpeed,
 804   IN  UINTN                               MaximumPacketLength,
 805   IN  UINT8                               DataBuffersNumber,
 806   IN  OUT VOID                            *Data[EFI_USB_MAX_BULK_BUFFER_NUM],
 807   IN  OUT UINTN                           *DataLength,
 808   IN  OUT UINT8                           *DataToggle,
 809   IN  UINTN                               TimeOut,
 810   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
 811   OUT UINT32                              *TransferResult
 812   )
 813 /*++
 814
 815   Routine Description:
 816
 817     Virtual interface to submits bulk transfer to a bulk endpoint of a USB device
 818     both for Hc2 and Hc protocol.
 819
 820   Arguments:
 821
 822     UsbBusDev         - A pointer to bus controller of the device.
 823     DeviceAddress     - Represents the address of the target device on the USB,
 824                       which is assigned during USB enumeration.
 825     EndPointAddress   - The combination of an endpoint number and an
 826                       endpoint direction of the target USB device.
 827                       Each endpoint address supports data transfer in
 828                       one direction except the control endpoint
 829                       (whose default endpoint address is 0).
 830                       It is the caller's responsibility to make sure that
 831                       the EndPointAddress represents a bulk endpoint.
 832     DeviceSpeed       - Indicates device speed. The supported values are EFI_USB_SPEED_FULL
 833                       and EFI_USB_SPEED_HIGH.
 834     MaximumPacketLength - Indicates the maximum packet size the target endpoint
 835                         is capable of sending or receiving.
 836     DataBuffersNumber - Number of data buffers prepared for the transfer.
 837     Data              - Array of pointers to the buffers of data that will be transmitted
 838                       to USB device or received from USB device.
 839     DataLength        - When input, indicates the size, in bytes, of the data buffer
 840                       specified by Data. When output, indicates the actually
 841                       transferred data size.
 842     DataToggle        - A pointer to the data toggle value. On input, it indicates
 843                       the initial data toggle value the bulk transfer should adopt;
 844                       on output, it is updated to indicate the data toggle value
 845                       of the subsequent bulk transfer.
 846     Translator        - A pointr to the transaction translator data.
 847     TimeOut           - Indicates the maximum time, in microseconds, which the
 848                       transfer is allowed to complete.
 849     TransferResult    - A pointer to the detailed result information of the
 850                       bulk transfer.
 851
 852   Returns:
 853
 854     EFI_SUCCESS
 855         The bulk transfer was completed successfully.
 856     EFI_OUT_OF_RESOURCES
 857         The bulk transfer could not be submitted due to lack of resource.
 858     EFI_INVALID_PARAMETER
 859         Some parameters are invalid.
 860     EFI_TIMEOUT
 861         The bulk transfer failed due to timeout.
 862     EFI_DEVICE_ERROR
 863         The bulk transfer failed due to host controller or device error.
 864         Caller should check TranferResult for detailed error information.
 865
 866 --*/
 867 ;
 868
 869 EFI_STATUS
 870 EFIAPI
 871 UsbVirtualHcAsyncInterruptTransfer (
 872   IN  USB_BUS_CONTROLLER_DEVICE             * UsbBusDev,
 873   IN  UINT8                                 DeviceAddress,
 874   IN  UINT8                                 EndPointAddress,
 875   IN  UINT8                                 DeviceSpeed,
 876   IN  UINTN                                 MaximumPacketLength,
 877   IN  BOOLEAN                               IsNewTransfer,
 878   IN OUT UINT8                              *DataToggle,
 879   IN  UINTN                                 PollingInterval,
 880   IN  UINTN                                 DataLength,
 881   IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR * Translator,
 882   IN  EFI_ASYNC_USB_TRANSFER_CALLBACK       CallBackFunction,
 883   IN  VOID                                  *Context OPTIONAL
 884   )
 885 /*++
 886
 887   Routine Description:
 888
 889     Virtual interface to submits an asynchronous interrupt transfer to an
 890     interrupt endpoint of a USB device for both Hc2 and Hc protocol.
 891
 892   Arguments:
 893
 894     UsbBusDev       - A pointer to bus controller of the device.
 895     DeviceAddress   - Represents the address of the target device on the USB,
 896                     which is assigned during USB enumeration.
 897     EndPointAddress - The combination of an endpoint number and an endpoint
 898                     direction of the target USB device. Each endpoint address
 899                     supports data transfer in one direction except the
 900                     control endpoint (whose default endpoint address is 0).
 901                     It is the caller's responsibility to make sure that
 902                     the EndPointAddress represents an interrupt endpoint.
 903     DeviceSpeed     - Indicates device speed.
 904     MaximumPacketLength  - Indicates the maximum packet size the target endpoint
 905                          is capable of sending or receiving.
 906     IsNewTransfer   - If TRUE, an asynchronous interrupt pipe is built between
 907                     the host and the target interrupt endpoint.
 908                     If FALSE, the specified asynchronous interrupt pipe
 909                     is canceled.
 910     DataToggle      - A pointer to the data toggle value.  On input, it is valid
 911                     when IsNewTransfer is TRUE, and it indicates the initial
 912                     data toggle value the asynchronous interrupt transfer
 913                     should adopt.
 914                     On output, it is valid when IsNewTransfer is FALSE,
 915                     and it is updated to indicate the data toggle value of
 916                     the subsequent asynchronous interrupt transfer.
 917     PollingInterval - Indicates the interval, in milliseconds, that the
 918                     asynchronous interrupt transfer is polled.
 919                     This parameter is required when IsNewTransfer is TRUE.
 920     DataLength      - Indicates the length of data to be received at the
 921                     rate specified by PollingInterval from the target
 922                     asynchronous interrupt endpoint.  This parameter
 923                     is only required when IsNewTransfer is TRUE.
 924     Translator      - A pointr to the transaction translator data.
 925     CallBackFunction  - The Callback function.This function is called at the
 926                       rate specified by PollingInterval.This parameter is
 927                       only required when IsNewTransfer is TRUE.
 928     Context         - The context that is passed to the CallBackFunction.
 929                     - This is an optional parameter and may be NULL.
 930
 931   Returns:
 932
 933     EFI_SUCCESS
 934         The asynchronous interrupt transfer request has been successfully
 935         submitted or canceled.
 936     EFI_INVALID_PARAMETER
 937         Some parameters are invalid.
 938     EFI_OUT_OF_RESOURCES
 939         The request could not be completed due to a lack of resources.
 940     EFI_DEVICE_ERROR
 941         Can't read register
 942
 943 --*/
 944 ;
 945
 946 EFI_STATUS
 947 EFIAPI
 948 UsbVirtualHcSyncInterruptTransfer (
 949   IN  USB_BUS_CONTROLLER_DEVICE             *UsbBusDev,
 950   IN  UINT8                                 DeviceAddress,
 951   IN  UINT8                                 EndPointAddress,
 952   IN  UINT8                                 DeviceSpeed,
 953   IN  UINTN                                 MaximumPacketLength,
 954   IN OUT VOID                               *Data,
 955   IN OUT UINTN                              *DataLength,
 956   IN OUT UINT8                              *DataToggle,
 957   IN  UINTN                                 TimeOut,
 958   IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,
 959   OUT UINT32                                *TransferResult
 960   )
 961 /*++
 962
 963   Routine Description:
 964
 965     Vitual interface to submits synchronous interrupt transfer to an interrupt endpoint
 966     of a USB device for both Hc2 and Hc protocol.
 967
 968   Arguments:
 969
 970     UsbBusDev       - A pointer to bus controller of the device.
 971     DeviceAddress   - Represents the address of the target device on the USB,
 972                     which is assigned during USB enumeration.
 973     EndPointAddress   - The combination of an endpoint number and an endpoint
 974                       direction of the target USB device. Each endpoint
 975                       address supports data transfer in one direction
 976                       except the control endpoint (whose default
 977                       endpoint address is 0). It is the caller's responsibility
 978                       to make sure that the EndPointAddress represents
 979                       an interrupt endpoint.
 980     DeviceSpeed     - Indicates device speed.
 981     MaximumPacketLength - Indicates the maximum packet size the target endpoint
 982                         is capable of sending or receiving.
 983     Data            - A pointer to the buffer of data that will be transmitted
 984                     to USB device or received from USB device.
 985     DataLength      - On input, the size, in bytes, of the data buffer specified
 986                     by Data. On output, the number of bytes transferred.
 987     DataToggle      - A pointer to the data toggle value. On input, it indicates
 988                     the initial data toggle value the synchronous interrupt
 989                     transfer should adopt;
 990                     on output, it is updated to indicate the data toggle value
 991                     of the subsequent synchronous interrupt transfer.
 992     TimeOut         - Indicates the maximum time, in microseconds, which the
 993                     transfer is allowed to complete.
 994     Translator      - A pointr to the transaction translator data.
 995     TransferResult  - A pointer to the detailed result information from
 996                     the synchronous interrupt transfer.
 997
 998   Returns:
 999
1000     EFI_SUCCESS
1001         The synchronous interrupt transfer was completed successfully.
1002     EFI_OUT_OF_RESOURCES
1003         The synchronous interrupt transfer could not be submitted due
1004         to lack of resource.
1005     EFI_INVALID_PARAMETER
1006         Some parameters are invalid.
1007     EFI_TIMEOUT
1008         The synchronous interrupt transfer failed due to timeout.
1009     EFI_DEVICE_ERROR
1010         The synchronous interrupt transfer failed due to host controller
1011         or device error. Caller should check TranferResult for detailed
1012         error information.
1013
1014 --*/
1015 ;
1016
1017 EFI_STATUS
1018 EFIAPI
1019 UsbVirtualHcIsochronousTransfer (
1020   IN  USB_BUS_CONTROLLER_DEVICE             *UsbBusDev,
1021   IN  UINT8                                 DeviceAddress,
1022   IN  UINT8                                 EndPointAddress,
1023   IN  UINT8                                 DeviceSpeed,
1024   IN  UINTN                                 MaximumPacketLength,
1025   IN  UINT8                                 DataBuffersNumber,
1026   IN  OUT VOID                              *Data[EFI_USB_MAX_ISO_BUFFER_NUM],
1027   IN  UINTN                                 DataLength,
1028   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR    *Translator,
1029   OUT UINT32                                *TransferResult
1030   )
1031 /*++
1032
1033   Routine Description:
1034
1035     Virtual interface to submits isochronous transfer to a target USB device
1036     for both Hc2 and Hc protocol.
1037
1038   Arguments:
1039
1040     UsbBusDev        - A pointer to bus controller of the device.
1041     DeviceAddress    - Represents the address of the target device on the USB,
1042                      which is assigned during USB enumeration.
1043     EndPointAddress  - End point address
1044     DeviceSpeed      - Indicates device speed.
1045     MaximumPacketLength    - Indicates the maximum packet size that the
1046                            default control transfer endpoint is capable of
1047                            sending or receiving.
1048     DataBuffersNumber - Number of data buffers prepared for the transfer.
1049     Data              - Array of pointers to the buffers of data that will be
1050                       transmitted to USB device or received from USB device.
1051     DataLength        - Indicates the size, in bytes, of the data buffer
1052                       specified by Data.
1053     Translator        - A pointr to the transaction translator data.
1054     TransferResult    - A pointer to the detailed result information generated
1055                       by this control transfer.
1056
1057   Returns:
1058
1059     EFI_UNSUPPORTED
1060
1061 --*/
1062 ;
1063
1064 EFI_STATUS
1065 EFIAPI
1066 UsbVirtualHcAsyncIsochronousTransfer (
1067   IN  USB_BUS_CONTROLLER_DEVICE           *UsbBusDev,
1068   IN  UINT8                               DeviceAddress,
1069   IN  UINT8                               EndPointAddress,
1070   IN  UINT8                               DeviceSpeed,
1071   IN  UINTN                               MaximumPacketLength,
1072   IN  UINT8                               DataBuffersNumber,
1073   IN OUT VOID                             *Data[EFI_USB_MAX_ISO_BUFFER_NUM],
1074   IN  UINTN                               DataLength,
1075   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
1076   IN  EFI_ASYNC_USB_TRANSFER_CALLBACK     IsochronousCallBack,
1077   IN  VOID                                *Context
1078   )
1079 /*++
1080
1081   Routine Description:
1082
1083     Vitual interface to submits Async isochronous transfer to a target USB device
1084     for both Hc2 and Hc protocol.
1085
1086   Arguments:
1087
1088     UsbBusDev           - A pointer to bus controller of the device.
1089     DeviceAddress       - Represents the address of the target device on the USB,
1090                         which is assigned during USB enumeration.
1091     EndPointAddress     - End point address
1092     DeviceSpeed         - Indicates device speed.
1093     MaximumPacketLength - Indicates the maximum packet size that the
1094                         default control transfer endpoint is capable of
1095                         sending or receiving.
1096     DataBuffersNumber   - Number of data buffers prepared for the transfer.
1097     Data                - Array of pointers to the buffers of data that will be transmitted
1098                         to USB device or received from USB device.
1099     DataLength          - Indicates the size, in bytes, of the data buffer
1100                         specified by Data.
1101     Translator          - A pointr to the transaction translator data.
1102     IsochronousCallBack - When the transfer complete, the call back function will be called
1103     Context             - Pass to the call back function as parameter
1104
1105   Returns:
1106
1107     EFI_UNSUPPORTED
1108
1109 --*/
1110 ;
1111
1112 #endif