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