MdeModulePkg/Bus/Pci/UhciPei/UhcPeim.h

   1 /** @file
   2 Private Header file for Usb Host Controller PEIM
   3
   4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _RECOVERY_UHC_H_
  11 #define _RECOVERY_UHC_H_
  12
  13 #include <PiPei.h>
  14
  15 #include <Ppi/UsbController.h>
  16 #include <Ppi/UsbHostController.h>
  17 #include <Ppi/IoMmu.h>
  18 #include <Ppi/EndOfPeiPhase.h>
  19
  20 #include <Library/DebugLib.h>
  21 #include <Library/PeimEntryPoint.h>
  22 #include <Library/PeiServicesLib.h>
  23 #include <Library/BaseMemoryLib.h>
  24 #include <Library/TimerLib.h>
  25 #include <Library/IoLib.h>
  26 #include <Library/PeiServicesLib.h>
  27
  28 #define USB_SLOW_SPEED_DEVICE  0x01
  29 #define USB_FULL_SPEED_DEVICE  0x02
  30
  31 //
  32 // One memory block uses 16 page
  33 //
  34 #define NORMAL_MEMORY_BLOCK_UNIT_IN_PAGES  16
  35
  36 #define USBCMD          0                         /* Command Register Offset 00-01h */
  37 #define USBCMD_RS       BIT0                      /* Run/Stop */
  38 #define USBCMD_HCRESET  BIT1                      /* Host reset */
  39 #define USBCMD_GRESET   BIT2                      /* Global reset */
  40 #define USBCMD_EGSM     BIT3                      /* Global Suspend Mode */
  41 #define USBCMD_FGR      BIT4                      /* Force Global Resume */
  42 #define USBCMD_SWDBG    BIT5                      /* SW Debug mode */
  43 #define USBCMD_CF       BIT6                      /* Config Flag (sw only) */
  44 #define USBCMD_MAXP     BIT7                      /* Max Packet (0 = 32, 1 = 64) */
  45
  46 /* Status register */
  47 #define USBSTS         2      /* Status Register Offset 02-03h */
  48 #define USBSTS_USBINT  BIT0   /* Interrupt due to IOC */
  49 #define USBSTS_ERROR   BIT1   /* Interrupt due to error */
  50 #define USBSTS_RD      BIT2   /* Resume Detect */
  51 #define USBSTS_HSE     BIT3   /* Host System Error - basically PCI problems */
  52 #define USBSTS_HCPE    BIT4   /* Host Controller Process Error - the scripts were buggy */
  53 #define USBSTS_HCH     BIT5   /* HC Halted */
  54
  55 /* Interrupt enable register */
  56 #define USBINTR          4      /* Interrupt Enable Register 04-05h */
  57 #define USBINTR_TIMEOUT  BIT0   /* Timeout/CRC error enable */
  58 #define USBINTR_RESUME   BIT1   /* Resume interrupt enable */
  59 #define USBINTR_IOC      BIT2   /* Interrupt On Complete enable */
  60 #define USBINTR_SP       BIT3   /* Short packet interrupt enable */
  61
  62 /* Frame Number Register Offset 06-08h */
  63 #define USBFRNUM  6
  64
  65 /* Frame List Base Address Register Offset 08-0Bh */
  66 #define USBFLBASEADD  8
  67
  68 /* Start of Frame Modify Register Offset 0Ch */
  69 #define USBSOF  0x0c
  70
  71 /* USB port status and control registers */
  72 #define USBPORTSC1  0x10                /*Port 1 offset 10-11h */
  73 #define USBPORTSC2  0x12                /*Port 2 offset 12-13h */
  74
  75 #define USBPORTSC_CCS   BIT0            /* Current Connect Status ("device present") */
  76 #define USBPORTSC_CSC   BIT1            /* Connect Status Change */
  77 #define USBPORTSC_PED   BIT2            /* Port Enable / Disable */
  78 #define USBPORTSC_PEDC  BIT3            /* Port Enable / Disable Change */
  79 #define USBPORTSC_LSL   BIT4            /* Line Status Low bit*/
  80 #define USBPORTSC_LSH   BIT5            /* Line Status High bit*/
  81 #define USBPORTSC_RD    BIT6            /* Resume Detect */
  82 #define USBPORTSC_LSDA  BIT8            /* Low Speed Device Attached */
  83 #define USBPORTSC_PR    BIT9            /* Port Reset */
  84 #define USBPORTSC_SUSP  BIT12           /* Suspend */
  85
  86 #define SETUP_PACKET_ID   0x2D
  87 #define INPUT_PACKET_ID   0x69
  88 #define OUTPUT_PACKET_ID  0xE1
  89 #define ERROR_PACKET_ID   0x55
  90
  91 #define STALL_1_MICRO_SECOND  1
  92 #define STALL_1_MILLI_SECOND  1000
  93
  94 #pragma pack(1)
  95
  96 typedef struct {
  97   UINT32    FrameListPtrTerminate : 1;
  98   UINT32    FrameListPtrQSelect   : 1;
  99   UINT32    FrameListRsvd         : 2;
 100   UINT32    FrameListPtr          : 28;
 101 } FRAMELIST_ENTRY;
 102
 103 typedef struct {
 104   UINT32    QHHorizontalTerminate : 1;
 105   UINT32    QHHorizontalQSelect   : 1;
 106   UINT32    QHHorizontalRsvd      : 2;
 107   UINT32    QHHorizontalPtr       : 28;
 108   UINT32    QHVerticalTerminate   : 1;
 109   UINT32    QHVerticalQSelect     : 1;
 110   UINT32    QHVerticalRsvd        : 2;
 111   UINT32    QHVerticalPtr         : 28;
 112 } QUEUE_HEAD;
 113
 114 typedef struct {
 115   QUEUE_HEAD    QueueHead;
 116   UINT32        Reserved1;
 117   UINT32        Reserved2;
 118   VOID          *PtrNext;
 119   VOID          *PtrDown;
 120   VOID          *Reserved3;
 121   UINT32        Reserved4;
 122 } QH_STRUCT;
 123
 124 typedef struct {
 125   UINT32    TDLinkPtrTerminate   : 1;
 126   UINT32    TDLinkPtrQSelect     : 1;
 127   UINT32    TDLinkPtrDepthSelect : 1;
 128   UINT32    TDLinkPtrRsvd        : 1;
 129   UINT32    TDLinkPtr            : 28;
 130   UINT32    TDStatusActualLength : 11;
 131   UINT32    TDStatusRsvd         : 5;
 132   UINT32    TDStatus             : 8;
 133   UINT32    TDStatusIOC          : 1;
 134   UINT32    TDStatusIOS          : 1;
 135   UINT32    TDStatusLS           : 1;
 136   UINT32    TDStatusErr          : 2;
 137   UINT32    TDStatusSPD          : 1;
 138   UINT32    TDStatusRsvd2        : 2;
 139   UINT32    TDTokenPID           : 8;
 140   UINT32    TDTokenDevAddr       : 7;
 141   UINT32    TDTokenEndPt         : 4;
 142   UINT32    TDTokenDataToggle    : 1;
 143   UINT32    TDTokenRsvd          : 1;
 144   UINT32    TDTokenMaxLen        : 11;
 145   UINT32    TDBufferPtr;
 146 } TD;
 147
 148 typedef struct {
 149   TD        TDData;
 150   UINT8     *PtrTDBuffer;
 151   VOID      *PtrNextTD;
 152   VOID      *PtrNextQH;
 153   UINT16    TDBufferLength;
 154   UINT16    Reserved;
 155 } TD_STRUCT;
 156
 157 #pragma pack()
 158
 159 typedef struct _MEMORY_MANAGE_HEADER MEMORY_MANAGE_HEADER;
 160
 161 struct _MEMORY_MANAGE_HEADER {
 162   UINT8                   *BitArrayPtr;
 163   UINTN                   BitArraySizeInBytes;
 164   UINT8                   *MemoryBlockPtr;
 165   UINTN                   MemoryBlockSizeInBytes;
 166   MEMORY_MANAGE_HEADER    *Next;
 167 };
 168
 169 #define USB_UHC_DEV_SIGNATURE  SIGNATURE_32 ('p', 'u', 'h', 'c')
 170 typedef struct {
 171   UINTN                          Signature;
 172   PEI_USB_HOST_CONTROLLER_PPI    UsbHostControllerPpi;
 173   EDKII_IOMMU_PPI                *IoMmu;
 174   EFI_PEI_PPI_DESCRIPTOR         PpiDescriptor;
 175   //
 176   // EndOfPei callback is used to stop the UHC DMA operation
 177   // after exit PEI phase.
 178   //
 179   EFI_PEI_NOTIFY_DESCRIPTOR      EndOfPeiNotifyList;
 180
 181   UINT32                         UsbHostControllerBaseAddress;
 182   FRAMELIST_ENTRY                *FrameListEntry;
 183   QH_STRUCT                      *ConfigQH;
 184   QH_STRUCT                      *BulkQH;
 185   //
 186   // Header1 used for QH,TD memory blocks management
 187   //
 188   MEMORY_MANAGE_HEADER           *Header1;
 189 } USB_UHC_DEV;
 190
 191 #define PEI_RECOVERY_USB_UHC_DEV_FROM_UHCI_THIS(a)    CR (a, USB_UHC_DEV, UsbHostControllerPpi, USB_UHC_DEV_SIGNATURE)
 192 #define PEI_RECOVERY_USB_UHC_DEV_FROM_THIS_NOTIFY(a)  CR (a, USB_UHC_DEV, EndOfPeiNotifyList, USB_UHC_DEV_SIGNATURE)
 193
 194 /**
 195   Submits control transfer to a target USB device.
 196
 197   @param  PeiServices            The pointer of EFI_PEI_SERVICES.
 198   @param  This                   The pointer of PEI_USB_HOST_CONTROLLER_PPI.
 199   @param  DeviceAddress          The target device address.
 200   @param  DeviceSpeed            Target device speed.
 201   @param  MaximumPacketLength    Maximum packet size the default control transfer
 202                                  endpoint is capable of sending or receiving.
 203   @param  Request                USB device request to send.
 204   @param  TransferDirection      Specifies the data direction for the data stage.
 205   @param  Data                   Data buffer to be transmitted or received from USB device.
 206   @param  DataLength             The size (in bytes) of the data buffer.
 207   @param  TimeOut                Indicates the maximum timeout, in millisecond.
 208   @param  TransferResult         Return the result of this control transfer.
 209
 210   @retval EFI_SUCCESS            Transfer was completed successfully.
 211   @retval EFI_OUT_OF_RESOURCES   The transfer failed due to lack of resources.
 212   @retval EFI_INVALID_PARAMETER  Some parameters are invalid.
 213   @retval EFI_TIMEOUT            Transfer failed due to timeout.
 214   @retval EFI_DEVICE_ERROR       Transfer failed due to host controller or device error.
 215
 216 **/
 217 EFI_STATUS
 218 EFIAPI
 219 UhcControlTransfer (
 220   IN EFI_PEI_SERVICES             **PeiServices,
 221   IN PEI_USB_HOST_CONTROLLER_PPI  *This,
 222   IN     UINT8                    DeviceAddress,
 223   IN     UINT8                    DeviceSpeed,
 224   IN     UINT8                    MaximumPacketLength,
 225   IN     EFI_USB_DEVICE_REQUEST   *Request,
 226   IN     EFI_USB_DATA_DIRECTION   TransferDirection,
 227   IN OUT VOID                     *Data OPTIONAL,
 228   IN OUT UINTN                    *DataLength OPTIONAL,
 229   IN     UINTN                    TimeOut,
 230   OUT    UINT32                   *TransferResult
 231   );
 232
 233 /**
 234   Submits bulk transfer to a bulk endpoint of a USB device.
 235
 236   @param  PeiServices           The pointer of EFI_PEI_SERVICES.
 237   @param  This                  The pointer of PEI_USB_HOST_CONTROLLER_PPI.
 238   @param  DeviceAddress         Target device address.
 239   @param  EndPointAddress       Endpoint number and its direction in bit 7.
 240   @param  MaximumPacketLength   Maximum packet size the endpoint is capable of
 241                                 sending or receiving.
 242   @param  Data                  Array of pointers to the buffers of data to transmit
 243                                 from or receive into.
 244   @param  DataLength            The lenght of the data buffer.
 245   @param  DataToggle            On input, the initial data toggle for the transfer;
 246                                 On output, it is updated to to next data toggle to use of
 247                                 the subsequent bulk transfer.
 248   @param  TimeOut               Indicates the maximum time, in millisecond, which the
 249                                 transfer is allowed to complete.
 250   @param  TransferResult        A pointer to the detailed result information of the
 251                                 bulk transfer.
 252
 253   @retval EFI_SUCCESS           The transfer was completed successfully.
 254   @retval EFI_OUT_OF_RESOURCES  The transfer failed due to lack of resource.
 255   @retval EFI_INVALID_PARAMETER Parameters are invalid.
 256   @retval EFI_TIMEOUT           The transfer failed due to timeout.
 257   @retval EFI_DEVICE_ERROR      The transfer failed due to host controller error.
 258
 259 **/
 260 EFI_STATUS
 261 EFIAPI
 262 UhcBulkTransfer (
 263   IN EFI_PEI_SERVICES             **PeiServices,
 264   IN PEI_USB_HOST_CONTROLLER_PPI  *This,
 265   IN  UINT8                       DeviceAddress,
 266   IN  UINT8                       EndPointAddress,
 267   IN  UINT8                       MaximumPacketLength,
 268   IN OUT VOID                     *Data,
 269   IN OUT UINTN                    *DataLength,
 270   IN OUT UINT8                    *DataToggle,
 271   IN  UINTN                       TimeOut,
 272   OUT UINT32                      *TransferResult
 273   );
 274
 275 /**
 276   Retrieves the number of root hub ports.
 277
 278   @param[in]  PeiServices   The pointer to the PEI Services Table.
 279   @param[in]  This          The pointer to this instance of the
 280                             PEI_USB_HOST_CONTROLLER_PPI.
 281   @param[out] PortNumber    The pointer to the number of the root hub ports.
 282
 283   @retval EFI_SUCCESS           The port number was retrieved successfully.
 284   @retval EFI_INVALID_PARAMETER PortNumber is NULL.
 285
 286 **/
 287 EFI_STATUS
 288 EFIAPI
 289 UhcGetRootHubPortNumber (
 290   IN EFI_PEI_SERVICES             **PeiServices,
 291   IN PEI_USB_HOST_CONTROLLER_PPI  *This,
 292   OUT UINT8                       *PortNumber
 293   );
 294
 295 /**
 296   Retrieves the current status of a USB root hub port.
 297
 298   @param  PeiServices            The pointer of EFI_PEI_SERVICES.
 299   @param  This                   The pointer of PEI_USB_HOST_CONTROLLER_PPI.
 300   @param  PortNumber             The root hub port to retrieve the state from.
 301   @param  PortStatus             Variable to receive the port state.
 302
 303   @retval EFI_SUCCESS            The status of the USB root hub port specified.
 304                                  by PortNumber was returned in PortStatus.
 305   @retval EFI_INVALID_PARAMETER  PortNumber is invalid.
 306
 307 **/
 308 EFI_STATUS
 309 EFIAPI
 310 UhcGetRootHubPortStatus (
 311   IN EFI_PEI_SERVICES             **PeiServices,
 312   IN PEI_USB_HOST_CONTROLLER_PPI  *This,
 313   IN  UINT8                       PortNumber,
 314   OUT EFI_USB_PORT_STATUS         *PortStatus
 315   );
 316
 317 /**
 318   Sets a feature for the specified root hub port.
 319
 320   @param  PeiServices           The pointer of EFI_PEI_SERVICES
 321   @param  This                  The pointer of PEI_USB_HOST_CONTROLLER_PPI
 322   @param  PortNumber            Root hub port to set.
 323   @param  PortFeature           Feature to set.
 324
 325   @retval EFI_SUCCESS            The feature specified by PortFeature was set.
 326   @retval EFI_INVALID_PARAMETER  PortNumber is invalid or PortFeature is invalid.
 327   @retval EFI_TIMEOUT            The time out occurred.
 328
 329 **/
 330 EFI_STATUS
 331 EFIAPI
 332 UhcSetRootHubPortFeature (
 333   IN EFI_PEI_SERVICES             **PeiServices,
 334   IN PEI_USB_HOST_CONTROLLER_PPI  *This,
 335   IN UINT8                        PortNumber,
 336   IN EFI_USB_PORT_FEATURE         PortFeature
 337   );
 338
 339 /**
 340   Clears a feature for the specified root hub port.
 341
 342   @param  PeiServices           The pointer of EFI_PEI_SERVICES.
 343   @param  This                  The pointer of PEI_USB_HOST_CONTROLLER_PPI.
 344   @param  PortNumber            Specifies the root hub port whose feature
 345                                 is requested to be cleared.
 346   @param  PortFeature           Indicates the feature selector associated with the
 347                                 feature clear request.
 348
 349   @retval EFI_SUCCESS            The feature specified by PortFeature was cleared
 350                                  for the USB root hub port specified by PortNumber.
 351   @retval EFI_INVALID_PARAMETER  PortNumber is invalid or PortFeature is invalid.
 352
 353 **/
 354 EFI_STATUS
 355 EFIAPI
 356 UhcClearRootHubPortFeature (
 357   IN EFI_PEI_SERVICES             **PeiServices,
 358   IN PEI_USB_HOST_CONTROLLER_PPI  *This,
 359   IN UINT8                        PortNumber,
 360   IN EFI_USB_PORT_FEATURE         PortFeature
 361   );
 362
 363 /**
 364   Initialize UHCI.
 365
 366   @param  UhcDev                 UHCI Device.
 367
 368   @retval EFI_SUCCESS            UHCI successfully initialized.
 369   @retval EFI_OUT_OF_RESOURCES   Resource can not be allocated.
 370
 371 **/
 372 EFI_STATUS
 373 InitializeUsbHC (
 374   IN USB_UHC_DEV  *UhcDev
 375   );
 376
 377 /**
 378   Create Frame List Structure.
 379
 380   @param  UhcDev                 UHCI device.
 381
 382   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.
 383   @retval EFI_SUCCESS            Success.
 384
 385 **/
 386 EFI_STATUS
 387 CreateFrameList (
 388   USB_UHC_DEV  *UhcDev
 389   );
 390
 391 /**
 392   Read a 16bit width data from Uhc HC IO space register.
 393
 394   @param  UhcDev  The UHCI device.
 395   @param  Port    The IO space address of the register.
 396
 397   @retval the register content read.
 398
 399 **/
 400 UINT16
 401 USBReadPortW (
 402   IN  USB_UHC_DEV  *UhcDev,
 403   IN  UINT32       Port
 404   );
 405
 406 /**
 407   Write a 16bit width data into Uhc HC IO space register.
 408
 409   @param  UhcDev  The UHCI device.
 410   @param  Port    The IO space address of the register.
 411   @param  Data    The data written into the register.
 412
 413 **/
 414 VOID
 415 USBWritePortW (
 416   IN  USB_UHC_DEV  *UhcDev,
 417   IN  UINT32       Port,
 418   IN  UINT16       Data
 419   );
 420
 421 /**
 422   Write a 32bit width data into Uhc HC IO space register.
 423
 424   @param  UhcDev  The UHCI device.
 425   @param  Port    The IO space address of the register.
 426   @param  Data    The data written into the register.
 427
 428 **/
 429 VOID
 430 USBWritePortDW (
 431   IN  USB_UHC_DEV  *UhcDev,
 432   IN  UINT32       Port,
 433   IN  UINT32       Data
 434   );
 435
 436 /**
 437   Clear the content of UHCI's Status Register.
 438
 439   @param  UhcDev       The UHCI device.
 440   @param  StatusAddr   The IO space address of the register.
 441
 442 **/
 443 VOID
 444 ClearStatusReg (
 445   IN  USB_UHC_DEV  *UhcDev,
 446   IN  UINT32       StatusAddr
 447   );
 448
 449 /**
 450   Check whether the host controller operates well.
 451
 452   @param  UhcDev        The UHCI device.
 453   @param  StatusRegAddr The io address of status register.
 454
 455   @retval TRUE          Host controller is working.
 456   @retval FALSE         Host controller is halted or system error.
 457
 458 **/
 459 BOOLEAN
 460 IsStatusOK (
 461   IN USB_UHC_DEV  *UhcDev,
 462   IN UINT32       StatusRegAddr
 463   );
 464
 465 /**
 466   Set Frame List Base Address.
 467
 468   @param  UhcDev           The UHCI device.
 469   @param  FrameListRegAddr The address of frame list register.
 470   @param  Addr             The address of frame list table.
 471
 472 **/
 473 VOID
 474 SetFrameListBaseAddress (
 475   IN USB_UHC_DEV  *UhcDev,
 476   IN UINT32       FrameListRegAddr,
 477   IN UINT32       Addr
 478   );
 479
 480 /**
 481   Create QH and initialize.
 482
 483   @param  UhcDev               The UHCI device.
 484   @param  PtrQH                Place to store QH_STRUCT pointer.
 485
 486   @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.
 487   @retval EFI_SUCCESS        Success.
 488
 489 **/
 490 EFI_STATUS
 491 CreateQH (
 492   IN  USB_UHC_DEV  *UhcDev,
 493   OUT QH_STRUCT    **PtrQH
 494   );
 495
 496 /**
 497   Set the horizontal link pointer in QH.
 498
 499   @param  PtrQH               Place to store QH_STRUCT pointer.
 500   @param  PtrNext             Place to the next QH_STRUCT.
 501
 502 **/
 503 VOID
 504 SetQHHorizontalLinkPtr (
 505   IN QH_STRUCT  *PtrQH,
 506   IN VOID       *PtrNext
 507   );
 508
 509 /**
 510   Set a QH or TD horizontally to be connected with a specific QH.
 511
 512   @param  PtrQH      Place to store QH_STRUCT pointer.
 513   @param  IsQH       Specify QH or TD is connected.
 514
 515 **/
 516 VOID
 517 SetQHHorizontalQHorTDSelect (
 518   IN QH_STRUCT  *PtrQH,
 519   IN BOOLEAN    IsQH
 520   );
 521
 522 /**
 523   Set the horizontal validor bit in QH.
 524
 525   @param  PtrQH      Place to store QH_STRUCT pointer.
 526   @param  IsValid    Specify the horizontal linker is valid or not.
 527
 528 **/
 529 VOID
 530 SetQHHorizontalValidorInvalid (
 531   IN QH_STRUCT  *PtrQH,
 532   IN BOOLEAN    IsValid
 533   );
 534
 535 /**
 536   Set the vertical link pointer in QH.
 537
 538   @param  PtrQH       Place to store QH_STRUCT pointer.
 539   @param  PtrNext     Place to the next QH_STRUCT.
 540
 541 **/
 542 VOID
 543 SetQHVerticalLinkPtr (
 544   IN QH_STRUCT  *PtrQH,
 545   IN VOID       *PtrNext
 546   );
 547
 548 /**
 549   Set a QH or TD vertically to be connected with a specific QH.
 550
 551   @param  PtrQH      Place to store QH_STRUCT pointer.
 552   @param  IsQH       Specify QH or TD is connected.
 553
 554 **/
 555 VOID
 556 SetQHVerticalQHorTDSelect (
 557   IN QH_STRUCT  *PtrQH,
 558   IN BOOLEAN    IsQH
 559   );
 560
 561 /**
 562   Set the vertical validor bit in QH.
 563
 564   @param  PtrQH      Place to store QH_STRUCT pointer.
 565   @param  IsValid    Specify the vertical linker is valid or not.
 566
 567 **/
 568 VOID
 569 SetQHVerticalValidorInvalid (
 570   IN QH_STRUCT  *PtrQH,
 571   IN BOOLEAN    IsValid
 572   );
 573
 574 /**
 575   Allocate TD or QH Struct.
 576
 577   @param  UhcDev                 The UHCI device.
 578   @param  Size                   The size of allocation.
 579   @param  PtrStruct              Place to store TD_STRUCT pointer.
 580
 581   @return EFI_SUCCESS            Allocate successfully.
 582   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resource.
 583
 584 **/
 585 EFI_STATUS
 586 AllocateTDorQHStruct (
 587   IN  USB_UHC_DEV  *UhcDev,
 588   IN  UINT32       Size,
 589   OUT VOID         **PtrStruct
 590   );
 591
 592 /**
 593   Create a TD Struct.
 594
 595   @param  UhcDev                 The UHCI device.
 596   @param  PtrTD                  Place to store TD_STRUCT pointer.
 597
 598   @return EFI_SUCCESS            Allocate successfully.
 599   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resource.
 600
 601 **/
 602 EFI_STATUS
 603 CreateTD (
 604   IN  USB_UHC_DEV  *UhcDev,
 605   OUT TD_STRUCT    **PtrTD
 606   );
 607
 608 /**
 609   Generate Setup Stage TD.
 610
 611   @param  UhcDev       The UHCI device.
 612   @param  DevAddr      Device address.
 613   @param  Endpoint     Endpoint number.
 614   @param  DeviceSpeed  Device Speed.
 615   @param  DevRequest   CPU memory address of request structure buffer to transfer.
 616   @param  RequestPhy   PCI memory address of request structure buffer to transfer.
 617   @param  RequestLen   Request length.
 618   @param  PtrTD        TD_STRUCT generated.
 619
 620   @return EFI_SUCCESS            Generate setup stage TD successfully.
 621   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resource.
 622
 623 **/
 624 EFI_STATUS
 625 GenSetupStageTD (
 626   IN  USB_UHC_DEV  *UhcDev,
 627   IN  UINT8        DevAddr,
 628   IN  UINT8        Endpoint,
 629   IN  UINT8        DeviceSpeed,
 630   IN  UINT8        *DevRequest,
 631   IN  UINT8        *RequestPhy,
 632   IN  UINT8        RequestLen,
 633   OUT TD_STRUCT    **PtrTD
 634   );
 635
 636 /**
 637   Generate Data Stage TD.
 638
 639   @param  UhcDev       The UHCI device.
 640   @param  DevAddr      Device address.
 641   @param  Endpoint     Endpoint number.
 642   @param  PtrData      CPU memory address of user data buffer to transfer.
 643   @param  DataPhy      PCI memory address of user data buffer to transfer.
 644   @param  Len          Data length.
 645   @param  PktID        PacketID.
 646   @param  Toggle       Data toggle value.
 647   @param  DeviceSpeed  Device Speed.
 648   @param  PtrTD        TD_STRUCT generated.
 649
 650   @return EFI_SUCCESS            Generate data stage TD successfully.
 651   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resource.
 652
 653 **/
 654 EFI_STATUS
 655 GenDataTD (
 656   IN  USB_UHC_DEV  *UhcDev,
 657   IN  UINT8        DevAddr,
 658   IN  UINT8        Endpoint,
 659   IN  UINT8        *PtrData,
 660   IN  UINT8        *DataPhy,
 661   IN  UINT8        Len,
 662   IN  UINT8        PktID,
 663   IN  UINT8        Toggle,
 664   IN  UINT8        DeviceSpeed,
 665   OUT TD_STRUCT    **PtrTD
 666   );
 667
 668 /**
 669   Generate Status Stage TD.
 670
 671   @param  UhcDev       The UHCI device.
 672   @param  DevAddr      Device address.
 673   @param  Endpoint     Endpoint number.
 674   @param  PktID        PacketID.
 675   @param  DeviceSpeed  Device Speed.
 676   @param  PtrTD        TD_STRUCT generated.
 677
 678   @return EFI_SUCCESS            Generate status stage TD successfully.
 679   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resource.
 680
 681 **/
 682 EFI_STATUS
 683 CreateStatusTD (
 684   IN  USB_UHC_DEV  *UhcDev,
 685   IN  UINT8        DevAddr,
 686   IN  UINT8        Endpoint,
 687   IN  UINT8        PktID,
 688   IN  UINT8        DeviceSpeed,
 689   OUT TD_STRUCT    **PtrTD
 690   );
 691
 692 /**
 693   Set the link pointer validor bit in TD.
 694
 695   @param  PtrTDStruct  Place to store TD_STRUCT pointer.
 696   @param  IsValid      Specify the linker pointer is valid or not.
 697
 698 **/
 699 VOID
 700 SetTDLinkPtrValidorInvalid (
 701   IN  TD_STRUCT  *PtrTDStruct,
 702   IN  BOOLEAN    IsValid
 703   );
 704
 705 /**
 706   Set the Link Pointer pointing to a QH or TD.
 707
 708   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 709   @param  IsQH          Specify QH or TD is connected.
 710
 711 **/
 712 VOID
 713 SetTDLinkPtrQHorTDSelect (
 714   IN  TD_STRUCT  *PtrTDStruct,
 715   IN  BOOLEAN    IsQH
 716   );
 717
 718 /**
 719   Set the traverse is depth-first or breadth-first.
 720
 721   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 722   @param  IsDepth       Specify the traverse is depth-first or breadth-first.
 723
 724 **/
 725 VOID
 726 SetTDLinkPtrDepthorBreadth (
 727   IN  TD_STRUCT  *PtrTDStruct,
 728   IN  BOOLEAN    IsDepth
 729   );
 730
 731 /**
 732   Set TD Link Pointer in TD.
 733
 734   @param  PtrTDStruct  Place to store TD_STRUCT pointer.
 735   @param  PtrNext      Place to the next TD_STRUCT.
 736
 737 **/
 738 VOID
 739 SetTDLinkPtr (
 740   IN  TD_STRUCT  *PtrTDStruct,
 741   IN  VOID       *PtrNext
 742   );
 743
 744 /**
 745   Get TD Link Pointer.
 746
 747   @param  PtrTDStruct     Place to store TD_STRUCT pointer.
 748
 749   @retval Get TD Link Pointer in TD.
 750
 751 **/
 752 VOID *
 753 GetTDLinkPtr (
 754   IN  TD_STRUCT  *PtrTDStruct
 755   );
 756
 757 /**
 758   Enable/Disable short packet detection mechanism.
 759
 760   @param  PtrTDStruct  Place to store TD_STRUCT pointer.
 761   @param  IsEnable     Enable or disable short packet detection mechanism.
 762
 763 **/
 764 VOID
 765 EnableorDisableTDShortPacket (
 766   IN  TD_STRUCT  *PtrTDStruct,
 767   IN  BOOLEAN    IsEnable
 768   );
 769
 770 /**
 771   Set the max error counter in TD.
 772
 773   @param  PtrTDStruct  Place to store TD_STRUCT pointer.
 774   @param  MaxErrors    The number of allowable error.
 775
 776 **/
 777 VOID
 778 SetTDControlErrorCounter (
 779   IN  TD_STRUCT  *PtrTDStruct,
 780   IN  UINT8      MaxErrors
 781   );
 782
 783 /**
 784   Set the TD is targeting a low-speed device or not.
 785
 786   @param  PtrTDStruct       Place to store TD_STRUCT pointer.
 787   @param  IsLowSpeedDevice  Whether The device is low-speed.
 788
 789 **/
 790 VOID
 791 SetTDLoworFullSpeedDevice (
 792   IN  TD_STRUCT  *PtrTDStruct,
 793   IN  BOOLEAN    IsLowSpeedDevice
 794   );
 795
 796 /**
 797   Set the TD is isochronous transfer type or not.
 798
 799   @param  PtrTDStruct       Place to store TD_STRUCT pointer.
 800   @param  IsIsochronous     Whether the transaction isochronous transfer type.
 801
 802 **/
 803 VOID
 804 SetTDControlIsochronousorNot (
 805   IN  TD_STRUCT  *PtrTDStruct,
 806   IN  BOOLEAN    IsIsochronous
 807   );
 808
 809 /**
 810   Set if UCHI should issue an interrupt on completion of the frame
 811   in which this TD is executed
 812
 813   @param  PtrTDStruct       Place to store TD_STRUCT pointer.
 814   @param  IsSet             Whether HC should issue an interrupt on completion.
 815
 816 **/
 817 VOID
 818 SetorClearTDControlIOC (
 819   IN  TD_STRUCT  *PtrTDStruct,
 820   IN  BOOLEAN    IsSet
 821   );
 822
 823 /**
 824   Set if the TD is active and can be executed.
 825
 826   @param  PtrTDStruct       Place to store TD_STRUCT pointer.
 827   @param  IsActive          Whether the TD is active and can be executed.
 828
 829 **/
 830 VOID
 831 SetTDStatusActiveorInactive (
 832   IN  TD_STRUCT  *PtrTDStruct,
 833   IN  BOOLEAN    IsActive
 834   );
 835
 836 /**
 837   Specifies the maximum number of data bytes allowed for the transfer.
 838
 839   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 840   @param  MaxLen        The maximum number of data bytes allowed.
 841
 842   @retval The allowed maximum number of data.
 843 **/
 844 UINT16
 845 SetTDTokenMaxLength (
 846   IN  TD_STRUCT  *PtrTDStruct,
 847   IN  UINT16     MaxLen
 848   );
 849
 850 /**
 851   Set the data toggle bit to DATA1.
 852
 853   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 854
 855 **/
 856 VOID
 857 SetTDTokenDataToggle1 (
 858   IN  TD_STRUCT  *PtrTDStruct
 859   );
 860
 861 /**
 862   Set the data toggle bit to DATA0.
 863
 864   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 865
 866 **/
 867 VOID
 868 SetTDTokenDataToggle0 (
 869   IN  TD_STRUCT  *PtrTDStruct
 870   );
 871
 872 /**
 873   Set EndPoint Number the TD is targeting at.
 874
 875   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 876   @param  EndPoint      The Endport number of the target.
 877
 878 **/
 879 VOID
 880 SetTDTokenEndPoint (
 881   IN  TD_STRUCT  *PtrTDStruct,
 882   IN  UINTN      EndPoint
 883   );
 884
 885 /**
 886   Set Device Address the TD is targeting at.
 887
 888   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 889   @param  DevAddr       The Device Address of the target.
 890
 891 **/
 892 VOID
 893 SetTDTokenDeviceAddress (
 894   IN  TD_STRUCT  *PtrTDStruct,
 895   IN  UINTN      DevAddr
 896   );
 897
 898 /**
 899   Set Packet Identification the TD is targeting at.
 900
 901   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 902   @param  PacketID      The Packet Identification of the target.
 903
 904 **/
 905 VOID
 906 SetTDTokenPacketID (
 907   IN  TD_STRUCT  *PtrTDStruct,
 908   IN  UINT8      PacketID
 909   );
 910
 911 /**
 912   Set the beginning address of the data buffer that will be used
 913   during the transaction.
 914
 915   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 916
 917 **/
 918 VOID
 919 SetTDDataBuffer (
 920   IN  TD_STRUCT  *PtrTDStruct
 921   );
 922
 923 /**
 924   Detect whether the TD is active.
 925
 926   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 927
 928   @retval The TD is active or not.
 929
 930 **/
 931 BOOLEAN
 932 IsTDStatusActive (
 933   IN  TD_STRUCT  *PtrTDStruct
 934   );
 935
 936 /**
 937   Detect whether the TD is stalled.
 938
 939   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 940
 941   @retval The TD is stalled or not.
 942
 943 **/
 944 BOOLEAN
 945 IsTDStatusStalled (
 946   IN  TD_STRUCT  *PtrTDStruct
 947   );
 948
 949 /**
 950   Detect whether Data Buffer Error is happened.
 951
 952   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 953
 954   @retval The Data Buffer Error is happened or not.
 955
 956 **/
 957 BOOLEAN
 958 IsTDStatusBufferError (
 959   IN  TD_STRUCT  *PtrTDStruct
 960   );
 961
 962 /**
 963   Detect whether Babble Error is happened.
 964
 965   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 966
 967   @retval The Babble Error is happened or not.
 968
 969 **/
 970 BOOLEAN
 971 IsTDStatusBabbleError (
 972   IN  TD_STRUCT  *PtrTDStruct
 973   );
 974
 975 /**
 976   Detect whether NAK is received.
 977
 978   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 979
 980   @retval The NAK is received or not.
 981
 982 **/
 983 BOOLEAN
 984 IsTDStatusNAKReceived (
 985   IN  TD_STRUCT  *PtrTDStruct
 986   );
 987
 988 /**
 989   Detect whether CRC/Time Out Error is encountered.
 990
 991   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
 992
 993   @retval The CRC/Time Out Error is encountered or not.
 994
 995 **/
 996 BOOLEAN
 997 IsTDStatusCRCTimeOutError (
 998   IN  TD_STRUCT  *PtrTDStruct
 999   );
1000
1001 /**
1002   Detect whether Bitstuff Error is received.
1003
1004   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
1005
1006   @retval The Bitstuff Error is received or not.
1007
1008 **/
1009 BOOLEAN
1010 IsTDStatusBitStuffError (
1011   IN  TD_STRUCT  *PtrTDStruct
1012   );
1013
1014 /**
1015   Retrieve the actual number of bytes that were tansferred.
1016
1017   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
1018
1019   @retval The actual number of bytes that were tansferred.
1020
1021 **/
1022 UINT16
1023 GetTDStatusActualLength (
1024   IN  TD_STRUCT  *PtrTDStruct
1025   );
1026
1027 /**
1028   Retrieve the information of whether the Link Pointer field is valid or not.
1029
1030   @param  PtrTDStruct   Place to store TD_STRUCT pointer.
1031
1032   @retval The linker pointer field is valid or not.
1033
1034 **/
1035 BOOLEAN
1036 GetTDLinkPtrValidorInvalid (
1037   IN  TD_STRUCT  *PtrTDStruct
1038   );
1039
1040 /**
1041   Count TD Number from PtrFirstTD.
1042
1043   @param  PtrFirstTD   Place to store TD_STRUCT pointer.
1044
1045   @retval The queued TDs number.
1046
1047 **/
1048 UINTN
1049 CountTDsNumber (
1050   IN  TD_STRUCT  *PtrFirstTD
1051   );
1052
1053 /**
1054   Link TD To QH.
1055
1056   @param  PtrQH   Place to store QH_STRUCT pointer.
1057   @param  PtrTD   Place to store TD_STRUCT pointer.
1058
1059 **/
1060 VOID
1061 LinkTDToQH (
1062   IN  QH_STRUCT  *PtrQH,
1063   IN  TD_STRUCT  *PtrTD
1064   );
1065
1066 /**
1067   Link TD To TD.
1068
1069   @param  PtrPreTD  Place to store TD_STRUCT pointer.
1070   @param  PtrTD     Place to store TD_STRUCT pointer.
1071
1072 **/
1073 VOID
1074 LinkTDToTD (
1075   IN  TD_STRUCT  *PtrPreTD,
1076   IN  TD_STRUCT  *PtrTD
1077   );
1078
1079 /**
1080   Execute Control Transfer.
1081
1082   @param  UhcDev            The UCHI device.
1083   @param  PtrTD             A pointer to TD_STRUCT data.
1084   @param  ActualLen         Actual transfer Length.
1085   @param  TimeOut           TimeOut value.
1086   @param  TransferResult    Transfer Result.
1087
1088   @return EFI_DEVICE_ERROR  The transfer failed due to transfer error.
1089   @return EFI_TIMEOUT       The transfer failed due to time out.
1090   @return EFI_SUCCESS       The transfer finished OK.
1091
1092 **/
1093 EFI_STATUS
1094 ExecuteControlTransfer (
1095   IN  USB_UHC_DEV  *UhcDev,
1096   IN  TD_STRUCT    *PtrTD,
1097   OUT UINTN        *ActualLen,
1098   IN  UINTN        TimeOut,
1099   OUT UINT32       *TransferResult
1100   );
1101
1102 /**
1103   Execute Bulk Transfer.
1104
1105   @param  UhcDev            The UCHI device.
1106   @param  PtrTD             A pointer to TD_STRUCT data.
1107   @param  ActualLen         Actual transfer Length.
1108   @param  DataToggle        DataToggle value.
1109   @param  TimeOut           TimeOut value.
1110   @param  TransferResult    Transfer Result.
1111
1112   @return EFI_DEVICE_ERROR  The transfer failed due to transfer error.
1113   @return EFI_TIMEOUT       The transfer failed due to time out.
1114   @return EFI_SUCCESS       The transfer finished OK.
1115
1116 **/
1117 EFI_STATUS
1118 ExecBulkTransfer (
1119   IN     USB_UHC_DEV  *UhcDev,
1120   IN     TD_STRUCT    *PtrTD,
1121   IN OUT UINTN        *ActualLen,
1122   IN     UINT8        *DataToggle,
1123   IN     UINTN        TimeOut,
1124   OUT    UINT32       *TransferResult
1125   );
1126
1127 /**
1128   Delete Queued TDs.
1129
1130   @param  UhcDev       The UCHI device.
1131   @param  PtrFirstTD   Place to store TD_STRUCT pointer.
1132
1133 **/
1134 VOID
1135 DeleteQueuedTDs (
1136   IN USB_UHC_DEV  *UhcDev,
1137   IN TD_STRUCT    *PtrFirstTD
1138   );
1139
1140 /**
1141   Check TDs Results.
1142
1143   @param  PtrTD               A pointer to TD_STRUCT data.
1144   @param  Result              The result to return.
1145   @param  ErrTDPos            The Error TD position.
1146   @param  ActualTransferSize  Actual transfer size.
1147
1148   @retval The TD is executed successfully or not.
1149
1150 **/
1151 BOOLEAN
1152 CheckTDsResults (
1153   IN  TD_STRUCT  *PtrTD,
1154   OUT UINT32     *Result,
1155   OUT UINTN      *ErrTDPos,
1156   OUT UINTN      *ActualTransferSize
1157   );
1158
1159 /**
1160   Create Memory Block.
1161
1162   @param  UhcDev                   The UCHI device.
1163   @param  MemoryHeader             The Pointer to allocated memory block.
1164   @param  MemoryBlockSizeInPages   The page size of memory block to be allocated.
1165
1166   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.
1167   @retval EFI_SUCCESS            Success.
1168
1169 **/
1170 EFI_STATUS
1171 CreateMemoryBlock (
1172   IN  USB_UHC_DEV           *UhcDev,
1173   OUT MEMORY_MANAGE_HEADER  **MemoryHeader,
1174   IN  UINTN                 MemoryBlockSizeInPages
1175   );
1176
1177 /**
1178   Initialize UHCI memory management.
1179
1180   @param  UhcDev                 The UCHI device.
1181
1182   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.
1183   @retval EFI_SUCCESS            Success.
1184
1185 **/
1186 EFI_STATUS
1187 InitializeMemoryManagement (
1188   IN USB_UHC_DEV  *UhcDev
1189   );
1190
1191 /**
1192   Initialize UHCI memory management.
1193
1194   @param  UhcDev           The UCHI device.
1195   @param  Pool             Buffer pointer to store the buffer pointer.
1196   @param  AllocSize        The size of the pool to be allocated.
1197
1198   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.
1199   @retval EFI_SUCCESS            Success.
1200
1201 **/
1202 EFI_STATUS
1203 UhcAllocatePool (
1204   IN  USB_UHC_DEV  *UhcDev,
1205   OUT UINT8        **Pool,
1206   IN  UINTN        AllocSize
1207   );
1208
1209 /**
1210   Alloc Memory In MemoryBlock.
1211
1212   @param  MemoryHeader           The pointer to memory manage header.
1213   @param  Pool                   Buffer pointer to store the buffer pointer.
1214   @param  NumberOfMemoryUnit     The size of the pool to be allocated.
1215
1216   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.
1217   @retval EFI_SUCCESS            Success.
1218
1219 **/
1220 EFI_STATUS
1221 AllocMemInMemoryBlock (
1222   IN  MEMORY_MANAGE_HEADER  *MemoryHeader,
1223   OUT VOID                  **Pool,
1224   IN  UINTN                 NumberOfMemoryUnit
1225   );
1226
1227 /**
1228   Uhci Free Pool.
1229
1230   @param  UhcDev                 The UHCI device.
1231   @param  Pool                   A pointer to store the buffer address.
1232   @param  AllocSize              The size of the pool to be freed.
1233
1234 **/
1235 VOID
1236 UhcFreePool (
1237   IN USB_UHC_DEV  *UhcDev,
1238   IN UINT8        *Pool,
1239   IN UINTN        AllocSize
1240   );
1241
1242 /**
1243   Insert a new memory header into list.
1244
1245   @param  MemoryHeader         A pointer to the memory header list.
1246   @param  NewMemoryHeader      A new memory header to be inserted into the list.
1247
1248 **/
1249 VOID
1250 InsertMemoryHeaderToList (
1251   IN MEMORY_MANAGE_HEADER  *MemoryHeader,
1252   IN MEMORY_MANAGE_HEADER  *NewMemoryHeader
1253   );
1254
1255 /**
1256   Map address of request structure buffer.
1257
1258   @param  Uhc                The UHCI device.
1259   @param  Request            The user request buffer.
1260   @param  MappedAddr         Mapped address of request.
1261   @param  Map                Identificaion of this mapping to return.
1262
1263   @return EFI_SUCCESS        Success.
1264   @return EFI_DEVICE_ERROR   Fail to map the user request.
1265
1266 **/
1267 EFI_STATUS
1268 UhciMapUserRequest (
1269   IN  USB_UHC_DEV  *Uhc,
1270   IN  OUT VOID     *Request,
1271   OUT UINT8        **MappedAddr,
1272   OUT VOID         **Map
1273   );
1274
1275 /**
1276   Map address of user data buffer.
1277
1278   @param  Uhc                The UHCI device.
1279   @param  Direction          Direction of the data transfer.
1280   @param  Data               The user data buffer.
1281   @param  Len                Length of the user data.
1282   @param  PktId              Packet identificaion.
1283   @param  MappedAddr         Mapped address to return.
1284   @param  Map                Identificaion of this mapping to return.
1285
1286   @return EFI_SUCCESS        Success.
1287   @return EFI_DEVICE_ERROR   Fail to map the user data.
1288
1289 **/
1290 EFI_STATUS
1291 UhciMapUserData (
1292   IN  USB_UHC_DEV             *Uhc,
1293   IN  EFI_USB_DATA_DIRECTION  Direction,
1294   IN  VOID                    *Data,
1295   IN  OUT UINTN               *Len,
1296   OUT UINT8                   *PktId,
1297   OUT UINT8                   **MappedAddr,
1298   OUT VOID                    **Map
1299   );
1300
1301 /**
1302   Provides the controller-specific addresses required to access system memory from a
1303   DMA bus master.
1304
1305   @param IoMmu                  Pointer to IOMMU PPI.
1306   @param Operation              Indicates if the bus master is going to read or write to system memory.
1307   @param HostAddress            The system memory address to map to the PCI controller.
1308   @param NumberOfBytes          On input the number of bytes to map. On output the number of bytes
1309                                 that were mapped.
1310   @param DeviceAddress          The resulting map address for the bus master PCI controller to use to
1311                                 access the hosts HostAddress.
1312   @param Mapping                A resulting value to pass to Unmap().
1313
1314   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
1315   @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.
1316   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
1317   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
1318   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
1319
1320 **/
1321 EFI_STATUS
1322 IoMmuMap (
1323   IN EDKII_IOMMU_PPI        *IoMmu,
1324   IN EDKII_IOMMU_OPERATION  Operation,
1325   IN VOID                   *HostAddress,
1326   IN OUT UINTN              *NumberOfBytes,
1327   OUT EFI_PHYSICAL_ADDRESS  *DeviceAddress,
1328   OUT VOID                  **Mapping
1329   );
1330
1331 /**
1332   Completes the Map() operation and releases any corresponding resources.
1333
1334   @param IoMmu              Pointer to IOMMU PPI.
1335   @param Mapping            The mapping value returned from Map().
1336
1337 **/
1338 VOID
1339 IoMmuUnmap (
1340   IN EDKII_IOMMU_PPI  *IoMmu,
1341   IN VOID             *Mapping
1342   );
1343
1344 /**
1345   Allocates pages that are suitable for an OperationBusMasterCommonBuffer or
1346   OperationBusMasterCommonBuffer64 mapping.
1347
1348   @param IoMmu                  Pointer to IOMMU PPI.
1349   @param Pages                  The number of pages to allocate.
1350   @param HostAddress            A pointer to store the base system memory address of the
1351                                 allocated range.
1352   @param DeviceAddress          The resulting map address for the bus master PCI controller to use to
1353                                 access the hosts HostAddress.
1354   @param Mapping                A resulting value to pass to Unmap().
1355
1356   @retval EFI_SUCCESS           The requested memory pages were allocated.
1357   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
1358                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
1359   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
1360   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
1361
1362 **/
1363 EFI_STATUS
1364 IoMmuAllocateBuffer (
1365   IN EDKII_IOMMU_PPI        *IoMmu,
1366   IN UINTN                  Pages,
1367   OUT VOID                  **HostAddress,
1368   OUT EFI_PHYSICAL_ADDRESS  *DeviceAddress,
1369   OUT VOID                  **Mapping
1370   );
1371
1372 /**
1373   Initialize IOMMU.
1374
1375   @param IoMmu              Pointer to pointer to IOMMU PPI.
1376
1377 **/
1378 VOID
1379 IoMmuInit (
1380   OUT EDKII_IOMMU_PPI  **IoMmu
1381   );
1382
1383 #endif