MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridgeIo.c

   1 /** @file
   2
   3   PCI Root Bridge Io Protocol code.
   4
   5 Copyright (c) 1999 - 2016, Intel Corporation. All rights reserved.<BR>
   6 This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #include "PciHostBridge.h"
  17 #include "PciRootBridge.h"
  18 #include "PciHostResource.h"
  19
  20 #define NO_MAPPING  (VOID *) (UINTN) -1
  21
  22 //
  23 // Lookup table for increment values based on transfer widths
  24 //
  25 UINT8 mInStride[] = {
  26   1, // EfiPciWidthUint8
  27   2, // EfiPciWidthUint16
  28   4, // EfiPciWidthUint32
  29   8, // EfiPciWidthUint64
  30   0, // EfiPciWidthFifoUint8
  31   0, // EfiPciWidthFifoUint16
  32   0, // EfiPciWidthFifoUint32
  33   0, // EfiPciWidthFifoUint64
  34   1, // EfiPciWidthFillUint8
  35   2, // EfiPciWidthFillUint16
  36   4, // EfiPciWidthFillUint32
  37   8  // EfiPciWidthFillUint64
  38 };
  39
  40 //
  41 // Lookup table for increment values based on transfer widths
  42 //
  43 UINT8 mOutStride[] = {
  44   1, // EfiPciWidthUint8
  45   2, // EfiPciWidthUint16
  46   4, // EfiPciWidthUint32
  47   8, // EfiPciWidthUint64
  48   1, // EfiPciWidthFifoUint8
  49   2, // EfiPciWidthFifoUint16
  50   4, // EfiPciWidthFifoUint32
  51   8, // EfiPciWidthFifoUint64
  52   0, // EfiPciWidthFillUint8
  53   0, // EfiPciWidthFillUint16
  54   0, // EfiPciWidthFillUint32
  55   0  // EfiPciWidthFillUint64
  56 };
  57
  58 /**
  59   Construct the Pci Root Bridge instance.
  60
  61   @param Bridge            The root bridge instance.
  62   @param HostBridgeHandle  Handle to the HostBridge.
  63
  64   @return The pointer to PCI_ROOT_BRIDGE_INSTANCE just created
  65           or NULL if creation fails.
  66 **/
  67 PCI_ROOT_BRIDGE_INSTANCE *
  68 CreateRootBridge (
  69   IN PCI_ROOT_BRIDGE       *Bridge,
  70   IN EFI_HANDLE            HostBridgeHandle
  71   )
  72 {
  73   PCI_ROOT_BRIDGE_INSTANCE *RootBridge;
  74   PCI_RESOURCE_TYPE        Index;
  75   CHAR16                   *DevicePathStr;
  76
  77   DevicePathStr = NULL;
  78
  79   DEBUG ((EFI_D_INFO, "RootBridge: "));
  80   DEBUG ((EFI_D_INFO, "%s\n", DevicePathStr = ConvertDevicePathToText (Bridge->DevicePath, FALSE, FALSE)));
  81   DEBUG ((EFI_D_INFO, "  Support/Attr: %lx / %lx\n", Bridge->Supports, Bridge->Attributes));
  82   DEBUG ((EFI_D_INFO, "    DmaAbove4G: %s\n", Bridge->DmaAbove4G ? L"Yes" : L"No"));
  83   DEBUG ((EFI_D_INFO, "NoExtConfSpace: %s\n", Bridge->NoExtendedConfigSpace ? L"Yes" : L"No"));
  84   DEBUG ((EFI_D_INFO, "     AllocAttr: %lx (%s%s)\n", Bridge->AllocationAttributes,
  85           (Bridge->AllocationAttributes & EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM) != 0 ? L"CombineMemPMem " : L"",
  86           (Bridge->AllocationAttributes & EFI_PCI_HOST_BRIDGE_MEM64_DECODE) != 0 ? L"Mem64Decode" : L""
  87           ));
  88   DEBUG ((EFI_D_INFO, "           Bus: %lx - %lx\n", Bridge->Bus.Base, Bridge->Bus.Limit));
  89   DEBUG ((EFI_D_INFO, "            Io: %lx - %lx\n", Bridge->Io.Base, Bridge->Io.Limit));
  90   DEBUG ((EFI_D_INFO, "           Mem: %lx - %lx\n", Bridge->Mem.Base, Bridge->Mem.Limit));
  91   DEBUG ((EFI_D_INFO, "    MemAbove4G: %lx - %lx\n", Bridge->MemAbove4G.Base, Bridge->MemAbove4G.Limit));
  92   DEBUG ((EFI_D_INFO, "          PMem: %lx - %lx\n", Bridge->PMem.Base, Bridge->PMem.Limit));
  93   DEBUG ((EFI_D_INFO, "   PMemAbove4G: %lx - %lx\n", Bridge->PMemAbove4G.Base, Bridge->PMemAbove4G.Limit));
  94
  95   //
  96   // Make sure Mem and MemAbove4G apertures are valid
  97   //
  98   if (Bridge->Mem.Base < Bridge->Mem.Limit) {
  99     ASSERT (Bridge->Mem.Limit < SIZE_4GB);
 100     if (Bridge->Mem.Limit >= SIZE_4GB) {
 101       return NULL;
 102     }
 103   }
 104   if (Bridge->MemAbove4G.Base < Bridge->MemAbove4G.Limit) {
 105     ASSERT (Bridge->MemAbove4G.Base >= SIZE_4GB);
 106     if (Bridge->MemAbove4G.Base < SIZE_4GB) {
 107       return NULL;
 108     }
 109   }
 110   if (Bridge->PMem.Base < Bridge->PMem.Limit) {
 111     ASSERT (Bridge->PMem.Limit < SIZE_4GB);
 112     if (Bridge->PMem.Limit >= SIZE_4GB) {
 113       return NULL;
 114     }
 115   }
 116   if (Bridge->PMemAbove4G.Base < Bridge->PMemAbove4G.Limit) {
 117     ASSERT (Bridge->PMemAbove4G.Base >= SIZE_4GB);
 118     if (Bridge->PMemAbove4G.Base < SIZE_4GB) {
 119       return NULL;
 120     }
 121   }
 122
 123   if ((Bridge->AllocationAttributes & EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM) != 0) {
 124     //
 125     // If this bit is set, then the PCI Root Bridge does not
 126     // support separate windows for Non-prefetchable and Prefetchable
 127     // memory.
 128     //
 129     ASSERT (Bridge->PMem.Base >= Bridge->PMem.Limit);
 130     ASSERT (Bridge->PMemAbove4G.Base >= Bridge->PMemAbove4G.Limit);
 131     if ((Bridge->PMem.Base < Bridge->PMem.Limit) ||
 132         (Bridge->PMemAbove4G.Base < Bridge->PMemAbove4G.Limit)
 133         ) {
 134       return NULL;
 135     }
 136   }
 137
 138   if ((Bridge->AllocationAttributes & EFI_PCI_HOST_BRIDGE_MEM64_DECODE) == 0) {
 139     //
 140     // If this bit is not set, then the PCI Root Bridge does not support
 141     // 64 bit memory windows.
 142     //
 143     ASSERT (Bridge->MemAbove4G.Base >= Bridge->MemAbove4G.Limit);
 144     ASSERT (Bridge->PMemAbove4G.Base >= Bridge->PMemAbove4G.Limit);
 145     if ((Bridge->MemAbove4G.Base < Bridge->MemAbove4G.Limit) ||
 146         (Bridge->PMemAbove4G.Base < Bridge->PMemAbove4G.Limit)
 147         ) {
 148       return NULL;
 149     }
 150   }
 151
 152   RootBridge = AllocateZeroPool (sizeof (PCI_ROOT_BRIDGE_INSTANCE));
 153   ASSERT (RootBridge != NULL);
 154
 155   RootBridge->Signature = PCI_ROOT_BRIDGE_SIGNATURE;
 156   RootBridge->Supports = Bridge->Supports;
 157   RootBridge->Attributes = Bridge->Attributes;
 158   RootBridge->DmaAbove4G = Bridge->DmaAbove4G;
 159   RootBridge->NoExtendedConfigSpace = Bridge->NoExtendedConfigSpace;
 160   RootBridge->AllocationAttributes = Bridge->AllocationAttributes;
 161   RootBridge->DevicePath = DuplicateDevicePath (Bridge->DevicePath);
 162   RootBridge->DevicePathStr = DevicePathStr;
 163   RootBridge->ConfigBuffer = AllocatePool (
 164     TypeMax * sizeof (EFI_ACPI_ADDRESS_SPACE_DESCRIPTOR) + sizeof (EFI_ACPI_END_TAG_DESCRIPTOR)
 165     );
 166   ASSERT (RootBridge->ConfigBuffer != NULL);
 167   InitializeListHead (&RootBridge->Maps);
 168
 169   CopyMem (&RootBridge->Bus, &Bridge->Bus, sizeof (PCI_ROOT_BRIDGE_APERTURE));
 170   CopyMem (&RootBridge->Io, &Bridge->Io, sizeof (PCI_ROOT_BRIDGE_APERTURE));
 171   CopyMem (&RootBridge->Mem, &Bridge->Mem, sizeof (PCI_ROOT_BRIDGE_APERTURE));
 172   CopyMem (&RootBridge->MemAbove4G, &Bridge->MemAbove4G, sizeof (PCI_ROOT_BRIDGE_APERTURE));
 173
 174
 175   for (Index = TypeIo; Index < TypeMax; Index++) {
 176     RootBridge->ResAllocNode[Index].Type   = Index;
 177     RootBridge->ResAllocNode[Index].Base   = 0;
 178     RootBridge->ResAllocNode[Index].Length = 0;
 179     RootBridge->ResAllocNode[Index].Status = ResNone;
 180   }
 181
 182   RootBridge->RootBridgeIo.SegmentNumber  = Bridge->Segment;
 183   RootBridge->RootBridgeIo.ParentHandle   = HostBridgeHandle;
 184   RootBridge->RootBridgeIo.PollMem        = RootBridgeIoPollMem;
 185   RootBridge->RootBridgeIo.PollIo         = RootBridgeIoPollIo;
 186   RootBridge->RootBridgeIo.Mem.Read       = RootBridgeIoMemRead;
 187   RootBridge->RootBridgeIo.Mem.Write      = RootBridgeIoMemWrite;
 188   RootBridge->RootBridgeIo.Io.Read        = RootBridgeIoIoRead;
 189   RootBridge->RootBridgeIo.Io.Write       = RootBridgeIoIoWrite;
 190   RootBridge->RootBridgeIo.CopyMem        = RootBridgeIoCopyMem;
 191   RootBridge->RootBridgeIo.Pci.Read       = RootBridgeIoPciRead;
 192   RootBridge->RootBridgeIo.Pci.Write      = RootBridgeIoPciWrite;
 193   RootBridge->RootBridgeIo.Map            = RootBridgeIoMap;
 194   RootBridge->RootBridgeIo.Unmap          = RootBridgeIoUnmap;
 195   RootBridge->RootBridgeIo.AllocateBuffer = RootBridgeIoAllocateBuffer;
 196   RootBridge->RootBridgeIo.FreeBuffer     = RootBridgeIoFreeBuffer;
 197   RootBridge->RootBridgeIo.Flush          = RootBridgeIoFlush;
 198   RootBridge->RootBridgeIo.GetAttributes  = RootBridgeIoGetAttributes;
 199   RootBridge->RootBridgeIo.SetAttributes  = RootBridgeIoSetAttributes;
 200   RootBridge->RootBridgeIo.Configuration  = RootBridgeIoConfiguration;
 201
 202   return RootBridge;
 203 }
 204
 205 /**
 206   Check parameters for IO,MMIO,PCI read/write services of PCI Root Bridge IO.
 207
 208   The I/O operations are carried out exactly as requested. The caller is
 209   responsible for satisfying any alignment and I/O width restrictions that a PI
 210   System on a platform might require. For example on some platforms, width
 211   requests of EfiCpuIoWidthUint64 do not work. Misaligned buffers, on the other
 212   hand, will be handled by the driver.
 213
 214   @param[in] This           A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 215
 216   @param[in] OperationType  I/O operation type: IO/MMIO/PCI.
 217
 218   @param[in] Width          Signifies the width of the I/O or Memory operation.
 219
 220   @param[in] Address        The base address of the I/O operation.
 221
 222   @param[in] Count          The number of I/O operations to perform. The number
 223                             of bytes moved is Width size * Count, starting at
 224                             Address.
 225
 226   @param[in] Buffer         For read operations, the destination buffer to
 227                             store the results. For write operations, the source
 228                             buffer from which to write data.
 229
 230   @retval EFI_SUCCESS            The parameters for this request pass the
 231                                  checks.
 232
 233   @retval EFI_INVALID_PARAMETER  Width is invalid for this PI system.
 234
 235   @retval EFI_INVALID_PARAMETER  Buffer is NULL.
 236
 237   @retval EFI_UNSUPPORTED        The Buffer is not aligned for the given Width.
 238
 239   @retval EFI_UNSUPPORTED        The address range specified by Address, Width,
 240                                  and Count is not valid for this PI system.
 241 **/
 242 EFI_STATUS
 243 RootBridgeIoCheckParameter (
 244   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL        *This,
 245   IN OPERATION_TYPE                         OperationType,
 246   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH  Width,
 247   IN UINT64                                 Address,
 248   IN UINTN                                  Count,
 249   IN VOID                                   *Buffer
 250   )
 251 {
 252   PCI_ROOT_BRIDGE_INSTANCE                     *RootBridge;
 253   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS  *PciRbAddr;
 254   UINT64                                       Base;
 255   UINT64                                       Limit;
 256   UINT32                                       Size;
 257
 258   //
 259   // Check to see if Buffer is NULL
 260   //
 261   if (Buffer == NULL) {
 262     return EFI_INVALID_PARAMETER;
 263   }
 264
 265   //
 266   // Check to see if Width is in the valid range
 267   //
 268   if ((UINT32) Width >= EfiPciWidthMaximum) {
 269     return EFI_INVALID_PARAMETER;
 270   }
 271
 272   //
 273   // For FIFO type, the target address won't increase during the access,
 274   // so treat Count as 1
 275   //
 276   if (Width >= EfiPciWidthFifoUint8 && Width <= EfiPciWidthFifoUint64) {
 277     Count = 1;
 278   }
 279
 280   Width = (EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH) (Width & 0x03);
 281   Size  = 1 << Width;
 282
 283   //
 284   // Check to see if Address is aligned
 285   //
 286   if ((Address & (Size - 1)) != 0) {
 287     return EFI_UNSUPPORTED;
 288   }
 289
 290   RootBridge = ROOT_BRIDGE_FROM_THIS (This);
 291
 292   //
 293   // Check to see if any address associated with this transfer exceeds the
 294   // maximum allowed address.  The maximum address implied by the parameters
 295   // passed in is Address + Size * Count.  If the following condition is met,
 296   // then the transfer is not supported.
 297   //
 298   //    Address + Size * Count > Limit + 1
 299   //
 300   // Since Limit can be the maximum integer value supported by the CPU and
 301   // Count can also be the maximum integer value supported by the CPU, this
 302   // range check must be adjusted to avoid all oveflow conditions.
 303   //
 304   if (OperationType == IoOperation) {
 305     //
 306     // Allow Legacy IO access
 307     //
 308     if (Address + MultU64x32 (Count, Size) <= 0x1000) {
 309       if ((RootBridge->Attributes & (
 310            EFI_PCI_ATTRIBUTE_ISA_IO | EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO | EFI_PCI_ATTRIBUTE_VGA_IO |
 311            EFI_PCI_ATTRIBUTE_IDE_PRIMARY_IO | EFI_PCI_ATTRIBUTE_IDE_SECONDARY_IO |
 312            EFI_PCI_ATTRIBUTE_ISA_IO_16 | EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO_16 | EFI_PCI_ATTRIBUTE_VGA_IO_16)) != 0) {
 313         return EFI_SUCCESS;
 314       }
 315     }
 316     Base = RootBridge->Io.Base;
 317     Limit = RootBridge->Io.Limit;
 318   } else if (OperationType == MemOperation) {
 319     //
 320     // Allow Legacy MMIO access
 321     //
 322     if ((Address >= 0xA0000) && (Address + MultU64x32 (Count, Size)) <= 0xC0000) {
 323       if ((RootBridge->Attributes & EFI_PCI_ATTRIBUTE_VGA_MEMORY) != 0) {
 324         return EFI_SUCCESS;
 325       }
 326     }
 327     //
 328     // By comparing the Address against Limit we know which range to be used
 329     // for checking
 330     //
 331     if (Address + MultU64x32 (Count, Size) <= RootBridge->Mem.Limit + 1) {
 332       Base = RootBridge->Mem.Base;
 333       Limit = RootBridge->Mem.Limit;
 334     } else {
 335       Base = RootBridge->MemAbove4G.Base;
 336       Limit = RootBridge->MemAbove4G.Limit;
 337     }
 338   } else {
 339     PciRbAddr = (EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS*) &Address;
 340     if (PciRbAddr->Bus < RootBridge->Bus.Base ||
 341         PciRbAddr->Bus > RootBridge->Bus.Limit) {
 342       return EFI_INVALID_PARAMETER;
 343     }
 344
 345     if (PciRbAddr->Device > PCI_MAX_DEVICE ||
 346         PciRbAddr->Function > PCI_MAX_FUNC) {
 347       return EFI_INVALID_PARAMETER;
 348     }
 349
 350     if (PciRbAddr->ExtendedRegister != 0) {
 351       Address = PciRbAddr->ExtendedRegister;
 352     } else {
 353       Address = PciRbAddr->Register;
 354     }
 355     Base = 0;
 356     Limit = RootBridge->NoExtendedConfigSpace ? 0xFF : 0xFFF;
 357   }
 358
 359   if (Address < Base) {
 360       return EFI_INVALID_PARAMETER;
 361   }
 362
 363   if (Address + MultU64x32 (Count, Size) > Limit + 1) {
 364     return EFI_INVALID_PARAMETER;
 365   }
 366
 367   return EFI_SUCCESS;
 368 }
 369
 370 /**
 371   Polls an address in memory mapped I/O space until an exit condition is met,
 372   or a timeout occurs.
 373
 374   This function provides a standard way to poll a PCI memory location. A PCI
 375   memory read operation is performed at the PCI memory address specified by
 376   Address for the width specified by Width. The result of this PCI memory read
 377   operation is stored in Result. This PCI memory read operation is repeated
 378   until either a timeout of Delay 100 ns units has expired, or (Result & Mask)
 379   is equal to Value.
 380
 381   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 382   @param[in]   Width     Signifies the width of the memory operations.
 383   @param[in]   Address   The base address of the memory operations. The caller
 384                          is responsible for aligning Address if required.
 385   @param[in]   Mask      Mask used for the polling criteria. Bytes above Width
 386                          in Mask are ignored. The bits in the bytes below Width
 387                          which are zero in Mask are ignored when polling the
 388                          memory address.
 389   @param[in]   Value     The comparison value used for the polling exit
 390                          criteria.
 391   @param[in]   Delay     The number of 100 ns units to poll. Note that timer
 392                          available may be of poorer granularity.
 393   @param[out]  Result    Pointer to the last value read from the memory
 394                          location.
 395
 396   @retval EFI_SUCCESS            The last data returned from the access matched
 397                                  the poll exit criteria.
 398   @retval EFI_INVALID_PARAMETER  Width is invalid.
 399   @retval EFI_INVALID_PARAMETER  Result is NULL.
 400   @retval EFI_TIMEOUT            Delay expired before a match occurred.
 401   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a
 402                                  lack of resources.
 403 **/
 404 EFI_STATUS
 405 EFIAPI
 406 RootBridgeIoPollMem (
 407   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL        *This,
 408   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH  Width,
 409   IN  UINT64                                 Address,
 410   IN  UINT64                                 Mask,
 411   IN  UINT64                                 Value,
 412   IN  UINT64                                 Delay,
 413   OUT UINT64                                 *Result
 414   )
 415 {
 416   EFI_STATUS  Status;
 417   UINT64      NumberOfTicks;
 418   UINT32      Remainder;
 419
 420   if (Result == NULL) {
 421     return EFI_INVALID_PARAMETER;
 422   }
 423
 424   if ((UINT32)Width > EfiPciWidthUint64) {
 425     return EFI_INVALID_PARAMETER;
 426   }
 427
 428   //
 429   // No matter what, always do a single poll.
 430   //
 431   Status = This->Mem.Read (This, Width, Address, 1, Result);
 432   if (EFI_ERROR (Status)) {
 433     return Status;
 434   }
 435
 436   if ((*Result & Mask) == Value) {
 437     return EFI_SUCCESS;
 438   }
 439
 440   if (Delay == 0) {
 441     return EFI_SUCCESS;
 442
 443   } else {
 444
 445     //
 446     // Determine the proper # of metronome ticks to wait for polling the
 447     // location.  The nuber of ticks is Roundup (Delay /
 448     // mMetronome->TickPeriod)+1
 449     // The "+1" to account for the possibility of the first tick being short
 450     // because we started in the middle of a tick.
 451     //
 452     // BugBug: overriding mMetronome->TickPeriod with UINT32 until Metronome
 453     // protocol definition is updated.
 454     //
 455     NumberOfTicks = DivU64x32Remainder (Delay, (UINT32) mMetronome->TickPeriod,
 456                       &Remainder);
 457     if (Remainder != 0) {
 458       NumberOfTicks += 1;
 459     }
 460     NumberOfTicks += 1;
 461
 462     while (NumberOfTicks != 0) {
 463
 464       mMetronome->WaitForTick (mMetronome, 1);
 465
 466       Status = This->Mem.Read (This, Width, Address, 1, Result);
 467       if (EFI_ERROR (Status)) {
 468         return Status;
 469       }
 470
 471       if ((*Result & Mask) == Value) {
 472         return EFI_SUCCESS;
 473       }
 474
 475       NumberOfTicks -= 1;
 476     }
 477   }
 478   return EFI_TIMEOUT;
 479 }
 480
 481 /**
 482   Reads from the I/O space of a PCI Root Bridge. Returns when either the
 483   polling exit criteria is satisfied or after a defined duration.
 484
 485   This function provides a standard way to poll a PCI I/O location. A PCI I/O
 486   read operation is performed at the PCI I/O address specified by Address for
 487   the width specified by Width.
 488   The result of this PCI I/O read operation is stored in Result. This PCI I/O
 489   read operation is repeated until either a timeout of Delay 100 ns units has
 490   expired, or (Result & Mask) is equal to Value.
 491
 492   @param[in] This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 493   @param[in] Width     Signifies the width of the I/O operations.
 494   @param[in] Address   The base address of the I/O operations. The caller is
 495                        responsible for aligning Address if required.
 496   @param[in] Mask      Mask used for the polling criteria. Bytes above Width in
 497                        Mask are ignored. The bits in the bytes below Width
 498                        which are zero in Mask are ignored when polling the I/O
 499                        address.
 500   @param[in] Value     The comparison value used for the polling exit criteria.
 501   @param[in] Delay     The number of 100 ns units to poll. Note that timer
 502                        available may be of poorer granularity.
 503   @param[out] Result   Pointer to the last value read from the memory location.
 504
 505   @retval EFI_SUCCESS            The last data returned from the access matched
 506                                  the poll exit criteria.
 507   @retval EFI_INVALID_PARAMETER  Width is invalid.
 508   @retval EFI_INVALID_PARAMETER  Result is NULL.
 509   @retval EFI_TIMEOUT            Delay expired before a match occurred.
 510   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a
 511                                  lack of resources.
 512 **/
 513 EFI_STATUS
 514 EFIAPI
 515 RootBridgeIoPollIo (
 516   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL        *This,
 517   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH  Width,
 518   IN  UINT64                                 Address,
 519   IN  UINT64                                 Mask,
 520   IN  UINT64                                 Value,
 521   IN  UINT64                                 Delay,
 522   OUT UINT64                                 *Result
 523   )
 524 {
 525   EFI_STATUS  Status;
 526   UINT64      NumberOfTicks;
 527   UINT32      Remainder;
 528
 529   //
 530   // No matter what, always do a single poll.
 531   //
 532
 533   if (Result == NULL) {
 534     return EFI_INVALID_PARAMETER;
 535   }
 536
 537   if ((UINT32)Width > EfiPciWidthUint64) {
 538     return EFI_INVALID_PARAMETER;
 539   }
 540
 541   Status = This->Io.Read (This, Width, Address, 1, Result);
 542   if (EFI_ERROR (Status)) {
 543     return Status;
 544   }
 545   if ((*Result & Mask) == Value) {
 546     return EFI_SUCCESS;
 547   }
 548
 549   if (Delay == 0) {
 550     return EFI_SUCCESS;
 551
 552   } else {
 553
 554     //
 555     // Determine the proper # of metronome ticks to wait for polling the
 556     // location.  The number of ticks is Roundup (Delay /
 557     // mMetronome->TickPeriod)+1
 558     // The "+1" to account for the possibility of the first tick being short
 559     // because we started in the middle of a tick.
 560     //
 561     NumberOfTicks = DivU64x32Remainder (Delay, (UINT32)mMetronome->TickPeriod,
 562                       &Remainder);
 563     if (Remainder != 0) {
 564       NumberOfTicks += 1;
 565     }
 566     NumberOfTicks += 1;
 567
 568     while (NumberOfTicks != 0) {
 569
 570       mMetronome->WaitForTick (mMetronome, 1);
 571
 572       Status = This->Io.Read (This, Width, Address, 1, Result);
 573       if (EFI_ERROR (Status)) {
 574         return Status;
 575       }
 576
 577       if ((*Result & Mask) == Value) {
 578         return EFI_SUCCESS;
 579       }
 580
 581       NumberOfTicks -= 1;
 582     }
 583   }
 584   return EFI_TIMEOUT;
 585 }
 586
 587 /**
 588   Enables a PCI driver to access PCI controller registers in the PCI root
 589   bridge memory space.
 590
 591   The Mem.Read(), and Mem.Write() functions enable a driver to access PCI
 592   controller registers in the PCI root bridge memory space.
 593   The memory operations are carried out exactly as requested. The caller is
 594   responsible for satisfying any alignment and memory width restrictions that a
 595   PCI Root Bridge on a platform might require.
 596
 597   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 598   @param[in]   Width     Signifies the width of the memory operation.
 599   @param[in]   Address   The base address of the memory operation. The caller
 600                          is responsible for aligning the Address if required.
 601   @param[in]   Count     The number of memory operations to perform. Bytes
 602                          moved is Width size * Count, starting at Address.
 603   @param[out]  Buffer    For read operations, the destination buffer to store
 604                          the results. For write operations, the source buffer
 605                          to write data from.
 606
 607   @retval EFI_SUCCESS            The data was read from or written to the PCI
 608                                  root bridge.
 609   @retval EFI_INVALID_PARAMETER  Width is invalid for this PCI root bridge.
 610   @retval EFI_INVALID_PARAMETER  Buffer is NULL.
 611   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a
 612                                  lack of resources.
 613 **/
 614 EFI_STATUS
 615 EFIAPI
 616 RootBridgeIoMemRead (
 617   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL        *This,
 618   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH  Width,
 619   IN     UINT64                                 Address,
 620   IN     UINTN                                  Count,
 621   OUT    VOID                                   *Buffer
 622   )
 623 {
 624   EFI_STATUS                             Status;
 625
 626   Status = RootBridgeIoCheckParameter (This, MemOperation, Width, Address,
 627                                        Count, Buffer);
 628   if (EFI_ERROR (Status)) {
 629     return Status;
 630   }
 631   return mCpuIo->Mem.Read (mCpuIo, (EFI_CPU_IO_PROTOCOL_WIDTH) Width, Address, Count, Buffer);
 632 }
 633
 634 /**
 635   Enables a PCI driver to access PCI controller registers in the PCI root
 636   bridge memory space.
 637
 638   The Mem.Read(), and Mem.Write() functions enable a driver to access PCI
 639   controller registers in the PCI root bridge memory space.
 640   The memory operations are carried out exactly as requested. The caller is
 641   responsible for satisfying any alignment and memory width restrictions that a
 642   PCI Root Bridge on a platform might require.
 643
 644   @param[in]   This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 645   @param[in]   Width     Signifies the width of the memory operation.
 646   @param[in]   Address   The base address of the memory operation. The caller
 647                          is responsible for aligning the Address if required.
 648   @param[in]   Count     The number of memory operations to perform. Bytes
 649                          moved is Width size * Count, starting at Address.
 650   @param[in]   Buffer    For read operations, the destination buffer to store
 651                          the results. For write operations, the source buffer
 652                          to write data from.
 653
 654   @retval EFI_SUCCESS            The data was read from or written to the PCI
 655                                  root bridge.
 656   @retval EFI_INVALID_PARAMETER  Width is invalid for this PCI root bridge.
 657   @retval EFI_INVALID_PARAMETER  Buffer is NULL.
 658   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a
 659                                  lack of resources.
 660 **/
 661 EFI_STATUS
 662 EFIAPI
 663 RootBridgeIoMemWrite (
 664   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL        *This,
 665   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH  Width,
 666   IN     UINT64                                 Address,
 667   IN     UINTN                                  Count,
 668   IN     VOID                                   *Buffer
 669   )
 670 {
 671   EFI_STATUS                             Status;
 672
 673   Status = RootBridgeIoCheckParameter (This, MemOperation, Width, Address,
 674                                        Count, Buffer);
 675   if (EFI_ERROR (Status)) {
 676     return Status;
 677   }
 678   return mCpuIo->Mem.Write (mCpuIo, (EFI_CPU_IO_PROTOCOL_WIDTH) Width, Address, Count, Buffer);
 679 }
 680
 681 /**
 682   Enables a PCI driver to access PCI controller registers in the PCI root
 683   bridge I/O space.
 684
 685   @param[in]   This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 686   @param[in]   Width       Signifies the width of the memory operations.
 687   @param[in]   Address     The base address of the I/O operation. The caller is
 688                            responsible for aligning the Address if required.
 689   @param[in]   Count       The number of I/O operations to perform. Bytes moved
 690                            is Width size * Count, starting at Address.
 691   @param[out]  Buffer      For read operations, the destination buffer to store
 692                            the results. For write operations, the source buffer
 693                            to write data from.
 694
 695   @retval EFI_SUCCESS              The data was read from or written to the PCI
 696                                    root bridge.
 697   @retval EFI_INVALID_PARAMETER    Width is invalid for this PCI root bridge.
 698   @retval EFI_INVALID_PARAMETER    Buffer is NULL.
 699   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a
 700                                    lack of resources.
 701 **/
 702 EFI_STATUS
 703 EFIAPI
 704 RootBridgeIoIoRead (
 705   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL        *This,
 706   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH  Width,
 707   IN     UINT64                                 Address,
 708   IN     UINTN                                  Count,
 709   OUT    VOID                                   *Buffer
 710   )
 711 {
 712   EFI_STATUS                                    Status;
 713   Status = RootBridgeIoCheckParameter (
 714              This, IoOperation, Width,
 715              Address, Count, Buffer
 716              );
 717   if (EFI_ERROR (Status)) {
 718     return Status;
 719   }
 720   return mCpuIo->Io.Read (mCpuIo, (EFI_CPU_IO_PROTOCOL_WIDTH) Width, Address, Count, Buffer);
 721 }
 722
 723 /**
 724   Enables a PCI driver to access PCI controller registers in the PCI root
 725   bridge I/O space.
 726
 727   @param[in]   This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 728   @param[in]   Width       Signifies the width of the memory operations.
 729   @param[in]   Address     The base address of the I/O operation. The caller is
 730                            responsible for aligning the Address if required.
 731   @param[in]   Count       The number of I/O operations to perform. Bytes moved
 732                            is Width size * Count, starting at Address.
 733   @param[in]   Buffer      For read operations, the destination buffer to store
 734                            the results. For write operations, the source buffer
 735                            to write data from.
 736
 737   @retval EFI_SUCCESS              The data was read from or written to the PCI
 738                                    root bridge.
 739   @retval EFI_INVALID_PARAMETER    Width is invalid for this PCI root bridge.
 740   @retval EFI_INVALID_PARAMETER    Buffer is NULL.
 741   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a
 742                                    lack of resources.
 743 **/
 744 EFI_STATUS
 745 EFIAPI
 746 RootBridgeIoIoWrite (
 747   IN       EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL         *This,
 748   IN       EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH   Width,
 749   IN       UINT64                                  Address,
 750   IN       UINTN                                   Count,
 751   IN       VOID                                    *Buffer
 752   )
 753 {
 754   EFI_STATUS                                    Status;
 755   Status = RootBridgeIoCheckParameter (
 756              This, IoOperation, Width,
 757              Address, Count, Buffer
 758              );
 759   if (EFI_ERROR (Status)) {
 760     return Status;
 761   }
 762   return mCpuIo->Io.Write (mCpuIo, (EFI_CPU_IO_PROTOCOL_WIDTH) Width, Address, Count, Buffer);
 763 }
 764
 765 /**
 766   Enables a PCI driver to copy one region of PCI root bridge memory space to
 767   another region of PCI root bridge memory space.
 768
 769   The CopyMem() function enables a PCI driver to copy one region of PCI root
 770   bridge memory space to another region of PCI root bridge memory space. This
 771   is especially useful for video scroll operation on a memory mapped video
 772   buffer.
 773   The memory operations are carried out exactly as requested. The caller is
 774   responsible for satisfying any alignment and memory width restrictions that a
 775   PCI root bridge on a platform might require.
 776
 777   @param[in] This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
 778                          instance.
 779   @param[in] Width       Signifies the width of the memory operations.
 780   @param[in] DestAddress The destination address of the memory operation. The
 781                          caller is responsible for aligning the DestAddress if
 782                          required.
 783   @param[in] SrcAddress  The source address of the memory operation. The caller
 784                          is responsible for aligning the SrcAddress if
 785                          required.
 786   @param[in] Count       The number of memory operations to perform. Bytes
 787                          moved is Width size * Count, starting at DestAddress
 788                          and SrcAddress.
 789
 790   @retval  EFI_SUCCESS             The data was copied from one memory region
 791                                    to another memory region.
 792   @retval  EFI_INVALID_PARAMETER   Width is invalid for this PCI root bridge.
 793   @retval  EFI_OUT_OF_RESOURCES    The request could not be completed due to a
 794                                    lack of resources.
 795 **/
 796 EFI_STATUS
 797 EFIAPI
 798 RootBridgeIoCopyMem (
 799   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL              *This,
 800   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH        Width,
 801   IN UINT64                                       DestAddress,
 802   IN UINT64                                       SrcAddress,
 803   IN UINTN                                        Count
 804   )
 805 {
 806   EFI_STATUS  Status;
 807   BOOLEAN     Forward;
 808   UINTN       Stride;
 809   UINTN       Index;
 810   UINT64      Result;
 811
 812   if ((UINT32) Width > EfiPciWidthUint64) {
 813     return EFI_INVALID_PARAMETER;
 814   }
 815
 816   if (DestAddress == SrcAddress) {
 817     return EFI_SUCCESS;
 818   }
 819
 820   Stride = (UINTN) (1 << Width);
 821
 822   Forward = TRUE;
 823   if ((DestAddress > SrcAddress) &&
 824       (DestAddress < (SrcAddress + Count * Stride))) {
 825     Forward = FALSE;
 826     SrcAddress = SrcAddress + (Count - 1) * Stride;
 827     DestAddress = DestAddress + (Count - 1) * Stride;
 828   }
 829
 830   for (Index = 0; Index < Count; Index++) {
 831     Status = RootBridgeIoMemRead (
 832                This,
 833                Width,
 834                SrcAddress,
 835                1,
 836                &Result
 837                );
 838     if (EFI_ERROR (Status)) {
 839       return Status;
 840     }
 841     Status = RootBridgeIoMemWrite (
 842                This,
 843                Width,
 844                DestAddress,
 845                1,
 846                &Result
 847                );
 848     if (EFI_ERROR (Status)) {
 849       return Status;
 850     }
 851     if (Forward) {
 852       SrcAddress += Stride;
 853       DestAddress += Stride;
 854     } else {
 855       SrcAddress -= Stride;
 856       DestAddress -= Stride;
 857     }
 858   }
 859   return EFI_SUCCESS;
 860 }
 861
 862
 863 /**
 864   PCI configuration space access.
 865
 866   @param This     A pointer to EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
 867   @param Read     TRUE indicating it's a read operation.
 868   @param Width    Signifies the width of the memory operation.
 869   @param Address  The address within the PCI configuration space
 870                   for the PCI controller.
 871   @param Count    The number of PCI configuration operations
 872                   to perform.
 873   @param Buffer   The destination buffer to store the results.
 874
 875   @retval EFI_SUCCESS            The data was read/written from/to the PCI root bridge.
 876   @retval EFI_INVALID_PARAMETER  Invalid parameters found.
 877 **/
 878 EFI_STATUS
 879 EFIAPI
 880 RootBridgeIoPciAccess (
 881   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL       *This,
 882   IN     BOOLEAN                               Read,
 883   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH Width,
 884   IN     UINT64                                Address,
 885   IN     UINTN                                 Count,
 886   IN OUT VOID                                  *Buffer
 887   )
 888 {
 889   EFI_STATUS                                   Status;
 890   PCI_ROOT_BRIDGE_INSTANCE                     *RootBridge;
 891   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS  PciAddress;
 892   UINT8                                        *Uint8Buffer;
 893   UINT8                                        InStride;
 894   UINT8                                        OutStride;
 895   UINTN                                        Size;
 896
 897   Status = RootBridgeIoCheckParameter (This, PciOperation, Width, Address, Count, Buffer);
 898   if (EFI_ERROR (Status)) {
 899     return Status;
 900   }
 901
 902   //
 903   // Read Pci configuration space
 904   //
 905   RootBridge = ROOT_BRIDGE_FROM_THIS (This);
 906   CopyMem (&PciAddress, &Address, sizeof (PciAddress));
 907
 908   if (PciAddress.ExtendedRegister == 0) {
 909     PciAddress.ExtendedRegister = PciAddress.Register;
 910   }
 911
 912   Address = PCI_SEGMENT_LIB_ADDRESS (
 913               RootBridge->RootBridgeIo.SegmentNumber,
 914               PciAddress.Bus,
 915               PciAddress.Device,
 916               PciAddress.Function,
 917               PciAddress.ExtendedRegister
 918               );
 919
 920   //
 921   // Select loop based on the width of the transfer
 922   //
 923   InStride  = mInStride[Width];
 924   OutStride = mOutStride[Width];
 925   Size      = (UINTN) (1 << (Width & 0x03));
 926   for (Uint8Buffer = Buffer; Count > 0; Address += InStride, Uint8Buffer += OutStride, Count--) {
 927     if (Read) {
 928       PciSegmentReadBuffer (Address, Size, Uint8Buffer);
 929     } else {
 930       PciSegmentWriteBuffer (Address, Size, Uint8Buffer);
 931     }
 932   }
 933   return EFI_SUCCESS;
 934 }
 935
 936 /**
 937   Allows read from PCI configuration space.
 938
 939   @param This     A pointer to EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
 940   @param Width    Signifies the width of the memory operation.
 941   @param Address  The address within the PCI configuration space
 942                   for the PCI controller.
 943   @param Count    The number of PCI configuration operations
 944                   to perform.
 945   @param Buffer   The destination buffer to store the results.
 946
 947   @retval EFI_SUCCESS           The data was read from the PCI root bridge.
 948   @retval EFI_INVALID_PARAMETER Invalid parameters found.
 949 **/
 950 EFI_STATUS
 951 EFIAPI
 952 RootBridgeIoPciRead (
 953   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL       *This,
 954   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH Width,
 955   IN     UINT64                                Address,
 956   IN     UINTN                                 Count,
 957   IN OUT VOID                                  *Buffer
 958   )
 959 {
 960   return RootBridgeIoPciAccess (This, TRUE, Width, Address, Count, Buffer);
 961 }
 962
 963 /**
 964   Allows write to PCI configuration space.
 965
 966   @param This     A pointer to EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
 967   @param Width    Signifies the width of the memory operation.
 968   @param Address  The address within the PCI configuration space
 969                   for the PCI controller.
 970   @param Count    The number of PCI configuration operations
 971                   to perform.
 972   @param Buffer   The source buffer to get the results.
 973
 974   @retval EFI_SUCCESS            The data was written to the PCI root bridge.
 975   @retval EFI_INVALID_PARAMETER  Invalid parameters found.
 976 **/
 977 EFI_STATUS
 978 EFIAPI
 979 RootBridgeIoPciWrite (
 980   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL       *This,
 981   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH Width,
 982   IN     UINT64                                Address,
 983   IN     UINTN                                 Count,
 984   IN OUT VOID                                  *Buffer
 985   )
 986 {
 987   return RootBridgeIoPciAccess (This, FALSE, Width, Address, Count, Buffer);
 988 }
 989
 990 /**
 991   Provides the PCI controller-specific address needed to access
 992   system memory for DMA.
 993
 994   @param This           A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 995   @param Operation      Indicate if the bus master is going to read or write
 996                         to system memory.
 997   @param HostAddress    The system memory address to map on the PCI controller.
 998   @param NumberOfBytes  On input the number of bytes to map.
 999                         On output the number of bytes that were mapped.
1000   @param DeviceAddress  The resulting map address for the bus master PCI
1001                         controller to use to access the system memory's HostAddress.
1002   @param Mapping        The value to pass to Unmap() when the bus master DMA
1003                         operation is complete.
1004
1005   @retval EFI_SUCCESS            Success.
1006   @retval EFI_INVALID_PARAMETER  Invalid parameters found.
1007   @retval EFI_UNSUPPORTED        The HostAddress cannot be mapped as a common buffer.
1008   @retval EFI_DEVICE_ERROR       The System hardware could not map the requested address.
1009   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to lack of resources.
1010 **/
1011 EFI_STATUS
1012 EFIAPI
1013 RootBridgeIoMap (
1014   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL            *This,
1015   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_OPERATION  Operation,
1016   IN     VOID                                       *HostAddress,
1017   IN OUT UINTN                                      *NumberOfBytes,
1018   OUT    EFI_PHYSICAL_ADDRESS                       *DeviceAddress,
1019   OUT    VOID                                       **Mapping
1020   )
1021 {
1022   EFI_STATUS                                        Status;
1023   PCI_ROOT_BRIDGE_INSTANCE                          *RootBridge;
1024   EFI_PHYSICAL_ADDRESS                              PhysicalAddress;
1025   MAP_INFO                                          *MapInfo;
1026
1027   if (HostAddress == NULL || NumberOfBytes == NULL || DeviceAddress == NULL ||
1028       Mapping == NULL) {
1029     return EFI_INVALID_PARAMETER;
1030   }
1031
1032   //
1033   // Make sure that Operation is valid
1034   //
1035   if ((UINT32) Operation >= EfiPciOperationMaximum) {
1036     return EFI_INVALID_PARAMETER;
1037   }
1038
1039   RootBridge = ROOT_BRIDGE_FROM_THIS (This);
1040
1041   PhysicalAddress = (EFI_PHYSICAL_ADDRESS) (UINTN) HostAddress;
1042   if (!RootBridge->DmaAbove4G && ((PhysicalAddress + *NumberOfBytes) > SIZE_4GB)) {
1043     //
1044     // If the root bridge can not handle performing DMA above 4GB but
1045     // any part of the DMA transfer being mapped is above 4GB, then
1046     // map the DMA transfer to a buffer below 4GB.
1047     //
1048
1049     if (Operation == EfiPciOperationBusMasterCommonBuffer ||
1050         Operation == EfiPciOperationBusMasterCommonBuffer64) {
1051       //
1052       // Common Buffer operations can not be remapped.  If the common buffer
1053       // if above 4GB, then it is not possible to generate a mapping, so return
1054       // an error.
1055       //
1056       return EFI_UNSUPPORTED;
1057     }
1058
1059     //
1060     // Allocate a MAP_INFO structure to remember the mapping when Unmap() is
1061     // called later.
1062     //
1063     MapInfo = AllocatePool (sizeof (MAP_INFO));
1064     if (MapInfo == NULL) {
1065       *NumberOfBytes = 0;
1066       return EFI_OUT_OF_RESOURCES;
1067     }
1068
1069     //
1070     // Initialize the MAP_INFO structure
1071     //
1072     MapInfo->Signature         = MAP_INFO_SIGNATURE;
1073     MapInfo->Operation         = Operation;
1074     MapInfo->NumberOfBytes     = *NumberOfBytes;
1075     MapInfo->NumberOfPages     = EFI_SIZE_TO_PAGES (MapInfo->NumberOfBytes);
1076     MapInfo->HostAddress       = PhysicalAddress;
1077     MapInfo->MappedHostAddress = SIZE_4GB - 1;
1078
1079     //
1080     // Allocate a buffer below 4GB to map the transfer to.
1081     //
1082     Status = gBS->AllocatePages (
1083                     AllocateMaxAddress,
1084                     EfiBootServicesData,
1085                     MapInfo->NumberOfPages,
1086                     &MapInfo->MappedHostAddress
1087                     );
1088     if (EFI_ERROR (Status)) {
1089       FreePool (MapInfo);
1090       *NumberOfBytes = 0;
1091       return Status;
1092     }
1093
1094     //
1095     // If this is a read operation from the Bus Master's point of view,
1096     // then copy the contents of the real buffer into the mapped buffer
1097     // so the Bus Master can read the contents of the real buffer.
1098     //
1099     if (Operation == EfiPciOperationBusMasterRead ||
1100         Operation == EfiPciOperationBusMasterRead64) {
1101       CopyMem (
1102         (VOID *) (UINTN) MapInfo->MappedHostAddress,
1103         (VOID *) (UINTN) MapInfo->HostAddress,
1104         MapInfo->NumberOfBytes
1105         );
1106     }
1107
1108     InsertTailList (&RootBridge->Maps, &MapInfo->Link);
1109
1110     //
1111     // The DeviceAddress is the address of the maped buffer below 4GB
1112     //
1113     *DeviceAddress = MapInfo->MappedHostAddress;
1114     //
1115     // Return a pointer to the MAP_INFO structure in Mapping
1116     //
1117     *Mapping       = MapInfo;
1118   } else {
1119     //
1120     // If the root bridge CAN handle performing DMA above 4GB or
1121     // the transfer is below 4GB, so the DeviceAddress is simply the
1122     // HostAddress
1123     //
1124     *DeviceAddress = PhysicalAddress;
1125     *Mapping       = NO_MAPPING;
1126   }
1127
1128   return EFI_SUCCESS;
1129 }
1130
1131 /**
1132   Completes the Map() operation and releases any corresponding resources.
1133
1134   The Unmap() function completes the Map() operation and releases any
1135   corresponding resources.
1136   If the operation was an EfiPciOperationBusMasterWrite or
1137   EfiPciOperationBusMasterWrite64, the data is committed to the target system
1138   memory.
1139   Any resources used for the mapping are freed.
1140
1141   @param[in] This      A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
1142   @param[in] Mapping   The mapping value returned from Map().
1143
1144   @retval EFI_SUCCESS            The range was unmapped.
1145   @retval EFI_INVALID_PARAMETER  Mapping is not a value that was returned by Map().
1146   @retval EFI_DEVICE_ERROR       The data was not committed to the target system memory.
1147 **/
1148 EFI_STATUS
1149 EFIAPI
1150 RootBridgeIoUnmap (
1151   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL  *This,
1152   IN VOID                             *Mapping
1153   )
1154 {
1155   MAP_INFO                 *MapInfo;
1156   LIST_ENTRY               *Link;
1157   PCI_ROOT_BRIDGE_INSTANCE *RootBridge;
1158
1159   RootBridge = ROOT_BRIDGE_FROM_THIS (This);
1160   //
1161   // See if the Map() operation associated with this Unmap() required a mapping
1162   // buffer. If a mapping buffer was not required, then this function simply
1163   // returns EFI_SUCCESS.
1164   //
1165   if (Mapping == NO_MAPPING) {
1166     return EFI_SUCCESS;
1167   }
1168
1169   MapInfo = NO_MAPPING;
1170   for (Link = GetFirstNode (&RootBridge->Maps)
1171        ; !IsNull (&RootBridge->Maps, Link)
1172        ; Link = GetNextNode (&RootBridge->Maps, Link)
1173        ) {
1174     MapInfo = MAP_INFO_FROM_LINK (Link);
1175     if (MapInfo == Mapping) {
1176       break;
1177     }
1178   }
1179   //
1180   // Mapping is not a valid value returned by Map()
1181   //
1182   if (MapInfo != Mapping) {
1183     return EFI_INVALID_PARAMETER;
1184   }
1185   RemoveEntryList (&MapInfo->Link);
1186
1187   //
1188   // If this is a write operation from the Bus Master's point of view,
1189   // then copy the contents of the mapped buffer into the real buffer
1190   // so the processor can read the contents of the real buffer.
1191   //
1192   if (MapInfo->Operation == EfiPciOperationBusMasterWrite ||
1193       MapInfo->Operation == EfiPciOperationBusMasterWrite64) {
1194     CopyMem (
1195       (VOID *) (UINTN) MapInfo->HostAddress,
1196       (VOID *) (UINTN) MapInfo->MappedHostAddress,
1197       MapInfo->NumberOfBytes
1198       );
1199   }
1200
1201   //
1202   // Free the mapped buffer and the MAP_INFO structure.
1203   //
1204   gBS->FreePages (MapInfo->MappedHostAddress, MapInfo->NumberOfPages);
1205   FreePool (Mapping);
1206   return EFI_SUCCESS;
1207 }
1208
1209 /**
1210   Allocates pages that are suitable for an EfiPciOperationBusMasterCommonBuffer
1211   or EfiPciOperationBusMasterCommonBuffer64 mapping.
1212
1213   @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
1214   @param Type        This parameter is not used and must be ignored.
1215   @param MemoryType  The type of memory to allocate, EfiBootServicesData or
1216                      EfiRuntimeServicesData.
1217   @param Pages       The number of pages to allocate.
1218   @param HostAddress A pointer to store the base system memory address of the
1219                      allocated range.
1220   @param Attributes  The requested bit mask of attributes for the allocated
1221                      range. Only the attributes
1222                      EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE,
1223                      EFI_PCI_ATTRIBUTE_MEMORY_CACHED, and
1224                      EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE may be used with this
1225                      function.
1226
1227   @retval EFI_SUCCESS            The requested memory pages were allocated.
1228   @retval EFI_INVALID_PARAMETER  MemoryType is invalid.
1229   @retval EFI_INVALID_PARAMETER  HostAddress is NULL.
1230   @retval EFI_UNSUPPORTED        Attributes is unsupported. The only legal
1231                                  attribute bits are MEMORY_WRITE_COMBINE,
1232                                  MEMORY_CACHED, and DUAL_ADDRESS_CYCLE.
1233   @retval EFI_OUT_OF_RESOURCES   The memory pages could not be allocated.
1234 **/
1235 EFI_STATUS
1236 EFIAPI
1237 RootBridgeIoAllocateBuffer (
1238   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL  *This,
1239   IN  EFI_ALLOCATE_TYPE                Type,
1240   IN  EFI_MEMORY_TYPE                  MemoryType,
1241   IN  UINTN                            Pages,
1242   OUT VOID                             **HostAddress,
1243   IN  UINT64                           Attributes
1244   )
1245 {
1246   EFI_STATUS                Status;
1247   EFI_PHYSICAL_ADDRESS      PhysicalAddress;
1248   PCI_ROOT_BRIDGE_INSTANCE  *RootBridge;
1249   EFI_ALLOCATE_TYPE         AllocateType;
1250
1251   //
1252   // Validate Attributes
1253   //
1254   if ((Attributes & EFI_PCI_ATTRIBUTE_INVALID_FOR_ALLOCATE_BUFFER) != 0) {
1255     return EFI_UNSUPPORTED;
1256   }
1257
1258   //
1259   // Check for invalid inputs
1260   //
1261   if (HostAddress == NULL) {
1262     return EFI_INVALID_PARAMETER;
1263   }
1264
1265   //
1266   // The only valid memory types are EfiBootServicesData and
1267   // EfiRuntimeServicesData
1268   //
1269   if (MemoryType != EfiBootServicesData &&
1270       MemoryType != EfiRuntimeServicesData) {
1271     return EFI_INVALID_PARAMETER;
1272   }
1273
1274   RootBridge = ROOT_BRIDGE_FROM_THIS (This);
1275
1276   AllocateType = AllocateAnyPages;
1277   if (!RootBridge->DmaAbove4G) {
1278     //
1279     // Limit allocations to memory below 4GB
1280     //
1281     AllocateType    = AllocateMaxAddress;
1282     PhysicalAddress = (EFI_PHYSICAL_ADDRESS) (SIZE_4GB - 1);
1283   }
1284   Status = gBS->AllocatePages (
1285                   AllocateType,
1286                   MemoryType,
1287                   Pages,
1288                   &PhysicalAddress
1289                   );
1290   if (!EFI_ERROR (Status)) {
1291     *HostAddress = (VOID *) (UINTN) PhysicalAddress;
1292   }
1293
1294   return Status;
1295 }
1296
1297 /**
1298   Frees memory that was allocated with AllocateBuffer().
1299
1300   The FreeBuffer() function frees memory that was allocated with
1301   AllocateBuffer().
1302
1303   @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
1304   @param Pages       The number of pages to free.
1305   @param HostAddress The base system memory address of the allocated range.
1306
1307   @retval EFI_SUCCESS            The requested memory pages were freed.
1308   @retval EFI_INVALID_PARAMETER  The memory range specified by HostAddress and
1309                                  Pages was not allocated with AllocateBuffer().
1310 **/
1311 EFI_STATUS
1312 EFIAPI
1313 RootBridgeIoFreeBuffer (
1314   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL  *This,
1315   IN  UINTN                            Pages,
1316   OUT VOID                             *HostAddress
1317   )
1318 {
1319   return gBS->FreePages ((EFI_PHYSICAL_ADDRESS) (UINTN) HostAddress, Pages);
1320 }
1321
1322 /**
1323   Flushes all PCI posted write transactions from a PCI host bridge to system
1324   memory.
1325
1326   The Flush() function flushes any PCI posted write transactions from a PCI
1327   host bridge to system memory. Posted write transactions are generated by PCI
1328   bus masters when they perform write transactions to target addresses in
1329   system memory.
1330   This function does not flush posted write transactions from any PCI bridges.
1331   A PCI controller specific action must be taken to guarantee that the posted
1332   write transactions have been flushed from the PCI controller and from all the
1333   PCI bridges into the PCI host bridge. This is typically done with a PCI read
1334   transaction from the PCI controller prior to calling Flush().
1335
1336   @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
1337
1338   @retval EFI_SUCCESS        The PCI posted write transactions were flushed
1339                              from the PCI host bridge to system memory.
1340   @retval EFI_DEVICE_ERROR   The PCI posted write transactions were not flushed
1341                              from the PCI host bridge due to a hardware error.
1342 **/
1343 EFI_STATUS
1344 EFIAPI
1345 RootBridgeIoFlush (
1346   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL           *This
1347   )
1348 {
1349   return EFI_SUCCESS;
1350 }
1351
1352 /**
1353   Gets the attributes that a PCI root bridge supports setting with
1354   SetAttributes(), and the attributes that a PCI root bridge is currently
1355   using.
1356
1357   The GetAttributes() function returns the mask of attributes that this PCI
1358   root bridge supports and the mask of attributes that the PCI root bridge is
1359   currently using.
1360
1361   @param This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
1362   @param Supported   A pointer to the mask of attributes that this PCI root
1363                      bridge supports setting with SetAttributes().
1364   @param Attributes  A pointer to the mask of attributes that this PCI root
1365                      bridge is currently using.
1366
1367   @retval  EFI_SUCCESS           If Supports is not NULL, then the attributes
1368                                  that the PCI root bridge supports is returned
1369                                  in Supports. If Attributes is not NULL, then
1370                                  the attributes that the PCI root bridge is
1371                                  currently using is returned in Attributes.
1372   @retval  EFI_INVALID_PARAMETER Both Supports and Attributes are NULL.
1373 **/
1374 EFI_STATUS
1375 EFIAPI
1376 RootBridgeIoGetAttributes (
1377   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL  *This,
1378   OUT UINT64                           *Supported,
1379   OUT UINT64                           *Attributes
1380   )
1381 {
1382   PCI_ROOT_BRIDGE_INSTANCE *RootBridge;
1383
1384   if (Attributes == NULL && Supported == NULL) {
1385     return EFI_INVALID_PARAMETER;
1386   }
1387
1388   RootBridge = ROOT_BRIDGE_FROM_THIS (This);
1389   //
1390   // Set the return value for Supported and Attributes
1391   //
1392   if (Supported != NULL) {
1393     *Supported  = RootBridge->Supports;
1394   }
1395
1396   if (Attributes != NULL) {
1397     *Attributes = RootBridge->Attributes;
1398   }
1399
1400   return EFI_SUCCESS;
1401 }
1402
1403 /**
1404   Sets attributes for a resource range on a PCI root bridge.
1405
1406   The SetAttributes() function sets the attributes specified in Attributes for
1407   the PCI root bridge on the resource range specified by ResourceBase and
1408   ResourceLength. Since the granularity of setting these attributes may vary
1409   from resource type to resource type, and from platform to platform, the
1410   actual resource range and the one passed in by the caller may differ. As a
1411   result, this function may set the attributes specified by Attributes on a
1412   larger resource range than the caller requested. The actual range is returned
1413   in ResourceBase and ResourceLength. The caller is responsible for verifying
1414   that the actual range for which the attributes were set is acceptable.
1415
1416   @param This            A pointer to the
1417                          EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
1418   @param Attributes      The mask of attributes to set. If the
1419                          attribute bit MEMORY_WRITE_COMBINE,
1420                          MEMORY_CACHED, or MEMORY_DISABLE is set,
1421                          then the resource range is specified by
1422                          ResourceBase and ResourceLength. If
1423                          MEMORY_WRITE_COMBINE, MEMORY_CACHED, and
1424                          MEMORY_DISABLE are not set, then
1425                          ResourceBase and ResourceLength are ignored,
1426                          and may be NULL.
1427   @param ResourceBase    A pointer to the base address of the
1428                          resource range to be modified by the
1429                          attributes specified by Attributes.
1430   @param ResourceLength  A pointer to the length of the resource
1431                                    range to be modified by the attributes
1432                                    specified by Attributes.
1433
1434   @retval  EFI_SUCCESS           The current configuration of this PCI root bridge
1435                                  was returned in Resources.
1436   @retval  EFI_UNSUPPORTED       The current configuration of this PCI root bridge
1437                                  could not be retrieved.
1438 **/
1439 EFI_STATUS
1440 EFIAPI
1441 RootBridgeIoSetAttributes (
1442   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL  *This,
1443   IN     UINT64                           Attributes,
1444   IN OUT UINT64                           *ResourceBase,
1445   IN OUT UINT64                           *ResourceLength
1446   )
1447 {
1448   PCI_ROOT_BRIDGE_INSTANCE            *RootBridge;
1449
1450   RootBridge = ROOT_BRIDGE_FROM_THIS (This);
1451
1452   if ((Attributes & (~RootBridge->Supports)) != 0) {
1453     return EFI_UNSUPPORTED;
1454   }
1455
1456   RootBridge->Attributes = Attributes;
1457   return EFI_SUCCESS;
1458 }
1459
1460 /**
1461   Retrieves the current resource settings of this PCI root bridge in the form
1462   of a set of ACPI 2.0 resource descriptors.
1463
1464   There are only two resource descriptor types from the ACPI Specification that
1465   may be used to describe the current resources allocated to a PCI root bridge.
1466   These are the QWORD Address Space Descriptor (ACPI 2.0 Section 6.4.3.5.1),
1467   and the End Tag (ACPI 2.0 Section 6.4.2.8). The QWORD Address Space
1468   Descriptor can describe memory, I/O, and bus number ranges for dynamic or
1469   fixed resources. The configuration of a PCI root bridge is described with one
1470   or more QWORD Address Space Descriptors followed by an End Tag.
1471
1472   @param[in]   This        A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
1473   @param[out]  Resources   A pointer to the ACPI 2.0 resource descriptors that
1474                            describe the current configuration of this PCI root
1475                            bridge. The storage for the ACPI 2.0 resource
1476                            descriptors is allocated by this function. The
1477                            caller must treat the return buffer as read-only
1478                            data, and the buffer must not be freed by the
1479                            caller.
1480
1481   @retval  EFI_SUCCESS     The current configuration of this PCI root bridge
1482                            was returned in Resources.
1483   @retval  EFI_UNSUPPORTED The current configuration of this PCI root bridge
1484                            could not be retrieved.
1485 **/
1486 EFI_STATUS
1487 EFIAPI
1488 RootBridgeIoConfiguration (
1489   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL     *This,
1490   OUT VOID                                **Resources
1491   )
1492 {
1493   PCI_RESOURCE_TYPE                 Index;
1494   PCI_ROOT_BRIDGE_INSTANCE          *RootBridge;
1495   PCI_RES_NODE                      *ResAllocNode;
1496   EFI_ACPI_ADDRESS_SPACE_DESCRIPTOR *Descriptor;
1497   EFI_ACPI_END_TAG_DESCRIPTOR       *End;
1498
1499   //
1500   // Get this instance of the Root Bridge.
1501   //
1502   RootBridge = ROOT_BRIDGE_FROM_THIS (This);
1503   ZeroMem (
1504     RootBridge->ConfigBuffer,
1505     TypeMax * sizeof (EFI_ACPI_ADDRESS_SPACE_DESCRIPTOR) + sizeof (EFI_ACPI_END_TAG_DESCRIPTOR)
1506     );
1507   Descriptor = RootBridge->ConfigBuffer;
1508   for (Index = TypeIo; Index < TypeMax; Index++) {
1509
1510     ResAllocNode = &RootBridge->ResAllocNode[Index];
1511
1512     if (ResAllocNode->Status != ResAllocated) {
1513       continue;
1514     }
1515
1516     Descriptor->Desc = ACPI_ADDRESS_SPACE_DESCRIPTOR;
1517     Descriptor->Len  = sizeof (EFI_ACPI_ADDRESS_SPACE_DESCRIPTOR) - 3;
1518     Descriptor->AddrRangeMin  = ResAllocNode->Base;
1519     Descriptor->AddrRangeMax  = ResAllocNode->Base + ResAllocNode->Length - 1;
1520     Descriptor->AddrLen       = ResAllocNode->Length;
1521     switch (ResAllocNode->Type) {
1522
1523     case TypeIo:
1524       Descriptor->ResType       = ACPI_ADDRESS_SPACE_TYPE_IO;
1525       break;
1526
1527     case TypePMem32:
1528       Descriptor->SpecificFlag = EFI_ACPI_MEMORY_RESOURCE_SPECIFIC_FLAG_CACHEABLE_PREFETCHABLE;
1529     case TypeMem32:
1530       Descriptor->ResType               = ACPI_ADDRESS_SPACE_TYPE_MEM;
1531       Descriptor->AddrSpaceGranularity  = 32;
1532       break;
1533
1534     case TypePMem64:
1535       Descriptor->SpecificFlag = EFI_ACPI_MEMORY_RESOURCE_SPECIFIC_FLAG_CACHEABLE_PREFETCHABLE;
1536     case TypeMem64:
1537       Descriptor->ResType               = ACPI_ADDRESS_SPACE_TYPE_MEM;
1538       Descriptor->AddrSpaceGranularity  = 64;
1539       break;
1540
1541     case TypeBus:
1542       Descriptor->ResType       = ACPI_ADDRESS_SPACE_TYPE_BUS;
1543       break;
1544
1545     default:
1546       break;
1547     }
1548
1549     Descriptor++;
1550   }
1551   //
1552   // Terminate the entries.
1553   //
1554   End = (EFI_ACPI_END_TAG_DESCRIPTOR *) Descriptor;
1555   End->Desc     = ACPI_END_TAG_DESCRIPTOR;
1556   End->Checksum = 0x0;
1557
1558   *Resources = RootBridge->ConfigBuffer;
1559   return EFI_SUCCESS;
1560 }