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