OvmfPkg/Library/BasePciCapLib/BasePciCapLib.c

   1 /** @file
   2   Work with PCI capabilities in PCI config space.
   3
   4   Provides functions to parse capabilities lists, and to locate, describe, read
   5   and write capabilities. PCI config space access is abstracted away.
   6
   7   Copyright (C) 2018, Red Hat, Inc.
   8
   9   This program and the accompanying materials are licensed and made available
  10   under the terms and conditions of the BSD License which accompanies this
  11   distribution.  The full text of the license may be found at
  12   http://opensource.org/licenses/bsd-license.php
  13
  14   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
  15   WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  16 **/
  17
  18 #include <IndustryStandard/PciExpress21.h>
  19
  20 #include <Library/BaseMemoryLib.h>
  21 #include <Library/DebugLib.h>
  22 #include <Library/MemoryAllocationLib.h>
  23
  24 #include "BasePciCapLib.h"
  25
  26
  27 /**
  28   Compare a standalone PCI_CAP_KEY against a PCI_CAP containing an embedded
  29   PCI_CAP_KEY.
  30
  31   @param[in] PciCapKey  Pointer to the bare PCI_CAP_KEY.
  32
  33   @param[in] PciCap     Pointer to the PCI_CAP with the embedded PCI_CAP_KEY.
  34
  35   @retval <0  If PciCapKey compares less than PciCap->Key.
  36
  37   @retval  0  If PciCapKey compares equal to PciCap->Key.
  38
  39   @retval >0  If PciCapKey compares greater than PciCap->Key.
  40 **/
  41 STATIC
  42 INTN
  43 EFIAPI
  44 ComparePciCapKey (
  45   IN CONST VOID *PciCapKey,
  46   IN CONST VOID *PciCap
  47   )
  48 {
  49   CONST PCI_CAP_KEY *Key1;
  50   CONST PCI_CAP_KEY *Key2;
  51
  52   Key1 = PciCapKey;
  53   Key2 = &((CONST PCI_CAP *)PciCap)->Key;
  54
  55   if (Key1->Domain < Key2->Domain) {
  56     return -1;
  57   }
  58   if (Key1->Domain > Key2->Domain) {
  59     return 1;
  60   }
  61   if (Key1->CapId < Key2->CapId) {
  62     return -1;
  63   }
  64   if (Key1->CapId > Key2->CapId) {
  65     return 1;
  66   }
  67   if (Key1->Instance < Key2->Instance) {
  68     return -1;
  69   }
  70   if (Key1->Instance > Key2->Instance) {
  71     return 1;
  72   }
  73   return 0;
  74 }
  75
  76
  77 /**
  78   Compare two PCI_CAP objects based on PCI_CAP.Key.
  79
  80   @param[in] PciCap1  Pointer to the first PCI_CAP.
  81
  82   @param[in] PciCap2  Pointer to the second PCI_CAP.
  83
  84   @retval <0  If PciCap1 compares less than PciCap2.
  85
  86   @retval  0  If PciCap1 compares equal to PciCap2.
  87
  88   @retval >0  If PciCap1 compares greater than PciCap2.
  89 **/
  90 STATIC
  91 INTN
  92 EFIAPI
  93 ComparePciCap (
  94   IN CONST VOID *PciCap1,
  95   IN CONST VOID *PciCap2
  96   )
  97 {
  98   CONST PCI_CAP_KEY *PciCap1Key;
  99
 100   PciCap1Key = &((CONST PCI_CAP *)PciCap1)->Key;
 101   return ComparePciCapKey (PciCap1Key, PciCap2);
 102 }
 103
 104
 105 /**
 106   Compare the standalone UINT16 config space offset of a capability header
 107   against a PCI_CAP containing an embedded Offset.
 108
 109   @param[in] CapHdrOffset  Pointer to the bare UINT16 config space offset.
 110
 111   @param[in] PciCap        Pointer to the PCI_CAP with the embedded Offset.
 112
 113   @retval <0  If CapHdrOffset compares less than PciCap->Offset.
 114
 115   @retval  0  If CapHdrOffset compares equal to PciCap->Offset.
 116
 117   @retval >0  If CapHdrOffset compares greater than PciCap->Offset.
 118 **/
 119 STATIC
 120 INTN
 121 EFIAPI
 122 ComparePciCapOffsetKey (
 123   IN CONST VOID *CapHdrOffset,
 124   IN CONST VOID *PciCap
 125   )
 126 {
 127   UINT16 Offset1;
 128   UINT16 Offset2;
 129
 130   Offset1 = *(CONST UINT16 *)CapHdrOffset;
 131   Offset2 = ((CONST PCI_CAP *)PciCap)->Offset;
 132   //
 133   // Note: both Offset1 and Offset2 are promoted to INT32 below, and the
 134   // subtraction takes place between INT32 values.
 135   //
 136   return Offset1 - Offset2;
 137 }
 138
 139
 140 /**
 141   Compare two PCI_CAP objects based on PCI_CAP.Offset.
 142
 143   @param[in] PciCap1  Pointer to the first PCI_CAP.
 144
 145   @param[in] PciCap2  Pointer to the second PCI_CAP.
 146
 147   @retval <0  If PciCap1 compares less than PciCap2.
 148
 149   @retval  0  If PciCap1 compares equal to PciCap2.
 150
 151   @retval >0  If PciCap1 compares greater than PciCap2.
 152 **/
 153 STATIC
 154 INTN
 155 EFIAPI
 156 ComparePciCapOffset (
 157   IN CONST VOID *PciCap1,
 158   IN CONST VOID *PciCap2
 159   )
 160 {
 161   UINT16 Offset1;
 162   UINT16 Offset2;
 163
 164   Offset1 = ((CONST PCI_CAP *)PciCap1)->Offset;
 165   Offset2 = ((CONST PCI_CAP *)PciCap2)->Offset;
 166   //
 167   // Note: both Offset1 and Offset2 are promoted to INT32 below, and the
 168   // subtraction takes place between INT32 values.
 169   //
 170   return Offset1 - Offset2;
 171 }
 172
 173
 174 /**
 175   Insert a new instance of the PCI capability given by (Domain, CapId) in
 176   CapList.
 177
 178   @param[in,out] CapList        The PCI_CAP_LIST into which the new PCI_CAP
 179                                 should be inserted. CapList will own the new
 180                                 PCI_CAP structure.
 181
 182   @param[in,out] CapHdrOffsets  Link the new PCI_CAP structure into the
 183                                 (non-owning) CapHdrOffsets collection as well.
 184                                 CapHdrOffsets orders the PCI_CAP structures
 185                                 based on the PCI_CAP.Offset member, and enables
 186                                 the calculation of PCI_CAP.MaxSizeHint.
 187
 188   @param[in] Domain             Whether the capability is normal or extended.
 189
 190   @param[in] CapId              Capability ID (specific to Domain).
 191
 192   @param[in] Offset             Config space offset at which the standard
 193                                 header of the capability starts. The caller is
 194                                 responsible for ensuring that Offset be DWORD
 195                                 aligned. The caller is also responsible for
 196                                 ensuring that Offset be within the config space
 197                                 identified by Domain.
 198
 199   @param[in] Version            The version number of the capability. The
 200                                 caller is responsible for passing 0 as Version
 201                                 if Domain is PciCapNormal.
 202
 203   @retval RETURN_SUCCESS           Insertion successful.
 204
 205   @retval RETURN_OUT_OF_RESOURCES  Memory allocation failed.
 206
 207   @retval RETURN_DEVICE_ERROR      A PCI_CAP with Offset is already linked by
 208                                    CapHdrOffsets. This indicates a loop in the
 209                                    capabilities list being parsed.
 210 **/
 211 STATIC
 212 RETURN_STATUS
 213 InsertPciCap (
 214   IN OUT PCI_CAP_LIST       *CapList,
 215   IN OUT ORDERED_COLLECTION *CapHdrOffsets,
 216   IN     PCI_CAP_DOMAIN     Domain,
 217   IN     UINT16             CapId,
 218   IN     UINT16             Offset,
 219   IN     UINT8              Version
 220   )
 221 {
 222   PCI_CAP                  *PciCap;
 223   RETURN_STATUS            Status;
 224   ORDERED_COLLECTION_ENTRY *PciCapEntry;
 225   PCI_CAP                  *InstanceZero;
 226
 227   ASSERT ((Offset & 0x3) == 0);
 228   ASSERT (Offset < (Domain == PciCapNormal ?
 229                     PCI_MAX_CONFIG_OFFSET : PCI_EXP_MAX_CONFIG_OFFSET));
 230   ASSERT (Domain == PciCapExtended || Version == 0);
 231
 232   //
 233   // Set InstanceZero to suppress incorrect compiler/analyzer warnings.
 234   //
 235   InstanceZero = NULL;
 236
 237   //
 238   // Allocate PciCap, and populate it assuming it is the first occurrence of
 239   // (Domain, CapId). Note that PciCap->MaxSizeHint is not assigned the final
 240   // value just yet.
 241   //
 242   PciCap = AllocatePool (sizeof *PciCap);
 243   if (PciCap == NULL) {
 244     return RETURN_OUT_OF_RESOURCES;
 245   }
 246   PciCap->Key.Domain                     = Domain;
 247   PciCap->Key.CapId                      = CapId;
 248   PciCap->Key.Instance                   = 0;
 249   PciCap->NumInstancesUnion.NumInstances = 1;
 250   PciCap->Offset                         = Offset;
 251   PciCap->MaxSizeHint                    = 0;
 252   PciCap->Version                        = Version;
 253
 254   //
 255   // Add PciCap to CapList.
 256   //
 257   Status = OrderedCollectionInsert (CapList->Capabilities, &PciCapEntry,
 258              PciCap);
 259   if (RETURN_ERROR (Status)) {
 260     if (Status == RETURN_OUT_OF_RESOURCES) {
 261       goto FreePciCap;
 262     }
 263     ASSERT (Status == RETURN_ALREADY_STARTED);
 264     //
 265     // PciCap is not the first instance of (Domain, CapId). Add it as a new
 266     // instance, taking the current instance count from Instance#0. Note that
 267     // we don't bump the instance count maintained in Instance#0 just yet, to
 268     // keep rollback on errors simple.
 269     //
 270     InstanceZero = OrderedCollectionUserStruct (PciCapEntry);
 271     PciCap->Key.Instance = InstanceZero->NumInstancesUnion.NumInstances;
 272     PciCap->NumInstancesUnion.InstanceZero = InstanceZero;
 273
 274     ASSERT (PciCap->Key.Instance > 0);
 275     Status = OrderedCollectionInsert (CapList->Capabilities, &PciCapEntry,
 276                PciCap);
 277     if (Status == RETURN_OUT_OF_RESOURCES) {
 278       goto FreePciCap;
 279     }
 280   }
 281   //
 282   // At this point, PciCap has been inserted in CapList->Capabilities, either
 283   // with Instance==0 or with Instance>0. PciCapEntry is the iterator that
 284   // links PciCap.
 285   //
 286   ASSERT_RETURN_ERROR (Status);
 287
 288   //
 289   // Link PciCap into CapHdrOffsets too, to order it globally based on config
 290   // space offset. Note that partial overlaps between capability headers is not
 291   // possible: Offset is DWORD aligned, normal capability headers are 16-bit
 292   // wide, and extended capability headers are 32-bit wide. Therefore any two
 293   // capability headers either are distinct or start at the same offset
 294   // (implying a loop in the respective capabilities list).
 295   //
 296   Status = OrderedCollectionInsert (CapHdrOffsets, NULL, PciCap);
 297   if (RETURN_ERROR (Status)) {
 298     if (Status == RETURN_ALREADY_STARTED) {
 299       //
 300       // Loop found; map return status accordingly.
 301       //
 302       Status = RETURN_DEVICE_ERROR;
 303     }
 304     goto DeletePciCapFromCapList;
 305   }
 306
 307   //
 308   // Now we can bump the instance count maintained in Instance#0, if PciCap is
 309   // not the first instance of (Domain, CapId).
 310   //
 311   if (PciCap->Key.Instance > 0) {
 312     InstanceZero->NumInstancesUnion.NumInstances++;
 313   }
 314   return RETURN_SUCCESS;
 315
 316 DeletePciCapFromCapList:
 317   OrderedCollectionDelete (CapList->Capabilities, PciCapEntry, NULL);
 318
 319 FreePciCap:
 320   FreePool (PciCap);
 321
 322   return Status;
 323 }
 324
 325
 326 /**
 327   Calculate the MaxSizeHint member for a PCI_CAP object.
 328
 329   CalculatePciCapMaxSizeHint() may only be called once all capability instances
 330   have been successfully processed by InsertPciCap().
 331
 332   @param[in,out] PciCap  The PCI_CAP object for which to calculate the
 333                          MaxSizeHint member. The caller is responsible for
 334                          passing a PCI_CAP object that has been created by a
 335                          successful invocation of InsertPciCap().
 336
 337   @param[in] NextPciCap  If NextPciCap is NULL, then the caller is responsible
 338                          for PciCap to represent the capability instance with
 339                          the highest header offset in all config space. If
 340                          NextPciCap is not NULL, then the caller is responsible
 341                          for (a) having created NextPciCap with a successful
 342                          invocation of InsertPciCap(), and (b) NextPciCap being
 343                          the direct successor of PciCap in config space offset
 344                          order, as ordered by ComparePciCapOffset().
 345 **/
 346 STATIC
 347 VOID
 348 CalculatePciCapMaxSizeHint (
 349   IN OUT PCI_CAP *PciCap,
 350   IN     PCI_CAP *NextPciCap OPTIONAL
 351   )
 352 {
 353   UINT16 ConfigSpaceSize;
 354
 355   ConfigSpaceSize = (PciCap->Key.Domain == PciCapNormal ?
 356                      PCI_MAX_CONFIG_OFFSET : PCI_EXP_MAX_CONFIG_OFFSET);
 357   //
 358   // The following is guaranteed by the interface contract on
 359   // CalculatePciCapMaxSizeHint().
 360   //
 361   ASSERT (NextPciCap == NULL || PciCap->Offset < NextPciCap->Offset);
 362   //
 363   // The following is guaranteed by the interface contract on InsertPciCap().
 364   //
 365   ASSERT (PciCap->Offset < ConfigSpaceSize);
 366   //
 367   // Thus we can safely subtract PciCap->Offset from either of
 368   // - ConfigSpaceSize
 369   // - and NextPciCap->Offset (if NextPciCap is not NULL).
 370   //
 371   // PciCap extends from PciCap->Offset to NextPciCap->Offset (if any), except
 372   // it cannot cross config space boundary.
 373   //
 374   if (NextPciCap == NULL || NextPciCap->Offset >= ConfigSpaceSize) {
 375     PciCap->MaxSizeHint = ConfigSpaceSize - PciCap->Offset;
 376     return;
 377   }
 378   PciCap->MaxSizeHint = NextPciCap->Offset - PciCap->Offset;
 379 }
 380
 381
 382 /**
 383   Debug dump a PCI_CAP_LIST object at the DEBUG_VERBOSE level.
 384
 385   @param[in] CapList  The PCI_CAP_LIST object to dump.
 386 **/
 387 STATIC
 388 VOID
 389 EFIAPI
 390 DebugDumpPciCapList (
 391   IN PCI_CAP_LIST *CapList
 392   )
 393 {
 394   DEBUG_CODE_BEGIN ();
 395   ORDERED_COLLECTION_ENTRY *PciCapEntry;
 396
 397   for (PciCapEntry = OrderedCollectionMin (CapList->Capabilities);
 398        PciCapEntry != NULL;
 399        PciCapEntry = OrderedCollectionNext (PciCapEntry)) {
 400     PCI_CAP       *PciCap;
 401     RETURN_STATUS Status;
 402     PCI_CAP_INFO  Info;
 403
 404     PciCap = OrderedCollectionUserStruct (PciCapEntry);
 405     Status = PciCapGetInfo (PciCap, &Info);
 406     //
 407     // PciCapGetInfo() cannot fail in this library instance.
 408     //
 409     ASSERT_RETURN_ERROR (Status);
 410
 411     DEBUG ((DEBUG_VERBOSE,
 412       "%a:%a: %a 0x%04x %03u/%03u v0x%x @0x%03x+0x%03x\n", gEfiCallerBaseName,
 413       __FUNCTION__, (Info.Domain == PciCapNormal ? "Norm" : "Extd"),
 414       Info.CapId, Info.Instance, Info.NumInstances, Info.Version, Info.Offset,
 415       Info.MaxSizeHint));
 416   }
 417   DEBUG_CODE_END ();
 418 }
 419
 420
 421 /**
 422   Empty a collection of PCI_CAP structures, optionally releasing the referenced
 423   PCI_CAP structures themselves. Release the collection at last.
 424
 425   @param[in,out] PciCapCollection  The collection to empty and release.
 426
 427   @param[in] FreePciCap            TRUE if the PCI_CAP structures linked by
 428                                    PciCapCollection should be released. When
 429                                    FALSE, the caller is responsible for
 430                                    retaining at least one reference to each
 431                                    PCI_CAP structure originally linked by
 432                                    PciCapCollection.
 433 **/
 434 STATIC
 435 VOID
 436 EmptyAndUninitPciCapCollection (
 437   IN OUT ORDERED_COLLECTION *PciCapCollection,
 438   IN     BOOLEAN            FreePciCap
 439   )
 440 {
 441   ORDERED_COLLECTION_ENTRY *PciCapEntry;
 442   ORDERED_COLLECTION_ENTRY *NextEntry;
 443
 444   for (PciCapEntry = OrderedCollectionMin (PciCapCollection);
 445        PciCapEntry != NULL;
 446        PciCapEntry = NextEntry) {
 447     PCI_CAP *PciCap;
 448
 449     NextEntry = OrderedCollectionNext (PciCapEntry);
 450     OrderedCollectionDelete (PciCapCollection, PciCapEntry, (VOID **)&PciCap);
 451     if (FreePciCap) {
 452       FreePool (PciCap);
 453     }
 454   }
 455   OrderedCollectionUninit (PciCapCollection);
 456 }
 457
 458
 459 /**
 460   Parse the capabilities lists (both normal and extended, as applicable) of a
 461   PCI device.
 462
 463   If the PCI device has no capabilities, that per se will not fail
 464   PciCapListInit(); an empty capabilities list will be represented.
 465
 466   If the PCI device is found to be PCI Express, then an attempt will be made to
 467   parse the extended capabilities list as well. If the first extended config
 468   space access -- via PciDevice->ReadConfig() with SourceOffset=0x100 and
 469   Size=4 -- fails, that per se will not fail PciCapListInit(); the device will
 470   be assumed to have no extended capabilities.
 471
 472   @param[in] PciDevice  Implementation-specific unique representation of the
 473                         PCI device in the PCI hierarchy.
 474
 475   @param[out] CapList   Opaque data structure that holds an in-memory
 476                         representation of the parsed capabilities lists of
 477                         PciDevice.
 478
 479   @retval RETURN_SUCCESS           The capabilities lists have been parsed from
 480                                    config space.
 481
 482   @retval RETURN_OUT_OF_RESOURCES  Memory allocation failed.
 483
 484   @retval RETURN_DEVICE_ERROR      A loop or some other kind of invalid pointer
 485                                    was detected in the capabilities lists of
 486                                    PciDevice.
 487
 488   @return                          Error codes propagated from
 489                                    PciDevice->ReadConfig().
 490 **/
 491 RETURN_STATUS
 492 EFIAPI
 493 PciCapListInit (
 494   IN  PCI_CAP_DEV  *PciDevice,
 495   OUT PCI_CAP_LIST **CapList
 496   )
 497 {
 498   PCI_CAP_LIST             *OutCapList;
 499   RETURN_STATUS            Status;
 500   ORDERED_COLLECTION       *CapHdrOffsets;
 501   UINT16                   PciStatusReg;
 502   BOOLEAN                  DeviceIsExpress;
 503   ORDERED_COLLECTION_ENTRY *OffsetEntry;
 504
 505   //
 506   // Allocate the output structure.
 507   //
 508   OutCapList = AllocatePool (sizeof *OutCapList);
 509   if (OutCapList == NULL) {
 510     return RETURN_OUT_OF_RESOURCES;
 511   }
 512   //
 513   // The OutCapList->Capabilities collection owns the PCI_CAP structures and
 514   // orders them based on PCI_CAP.Key.
 515   //
 516   OutCapList->Capabilities = OrderedCollectionInit (ComparePciCap,
 517                                ComparePciCapKey);
 518   if (OutCapList->Capabilities == NULL) {
 519     Status = RETURN_OUT_OF_RESOURCES;
 520     goto FreeOutCapList;
 521   }
 522
 523   //
 524   // The (temporary) CapHdrOffsets collection only references PCI_CAP
 525   // structures, and orders them based on PCI_CAP.Offset.
 526   //
 527   CapHdrOffsets = OrderedCollectionInit (ComparePciCapOffset,
 528                     ComparePciCapOffsetKey);
 529   if (CapHdrOffsets == NULL) {
 530     Status = RETURN_OUT_OF_RESOURCES;
 531     goto FreeCapabilities;
 532   }
 533
 534   //
 535   // Whether the device is PCI Express depends on the normal capability with
 536   // identifier EFI_PCI_CAPABILITY_ID_PCIEXP.
 537   //
 538   DeviceIsExpress = FALSE;
 539
 540   //
 541   // Check whether a normal capabilities list is present. If there's none,
 542   // that's not an error; we'll just return OutCapList->Capabilities empty.
 543   //
 544   Status = PciDevice->ReadConfig (PciDevice, PCI_PRIMARY_STATUS_OFFSET,
 545                         &PciStatusReg, sizeof PciStatusReg);
 546   if (RETURN_ERROR (Status)) {
 547     goto FreeCapHdrOffsets;
 548   }
 549   if ((PciStatusReg & EFI_PCI_STATUS_CAPABILITY) != 0) {
 550     UINT8 NormalCapHdrOffset;
 551
 552     //
 553     // Fetch the start offset of the normal capabilities list.
 554     //
 555     Status = PciDevice->ReadConfig (PciDevice, PCI_CAPBILITY_POINTER_OFFSET,
 556                           &NormalCapHdrOffset, sizeof NormalCapHdrOffset);
 557     if (RETURN_ERROR (Status)) {
 558       goto FreeCapHdrOffsets;
 559     }
 560
 561     //
 562     // Traverse the normal capabilities list.
 563     //
 564     NormalCapHdrOffset &= 0xFC;
 565     while (NormalCapHdrOffset > 0) {
 566       EFI_PCI_CAPABILITY_HDR NormalCapHdr;
 567
 568       Status = PciDevice->ReadConfig (PciDevice, NormalCapHdrOffset,
 569                             &NormalCapHdr, sizeof NormalCapHdr);
 570       if (RETURN_ERROR (Status)) {
 571         goto FreeCapHdrOffsets;
 572       }
 573
 574       Status = InsertPciCap (OutCapList, CapHdrOffsets, PciCapNormal,
 575                  NormalCapHdr.CapabilityID, NormalCapHdrOffset, 0);
 576       if (RETURN_ERROR (Status)) {
 577         goto FreeCapHdrOffsets;
 578       }
 579
 580       if (NormalCapHdr.CapabilityID == EFI_PCI_CAPABILITY_ID_PCIEXP) {
 581         DeviceIsExpress = TRUE;
 582       }
 583       NormalCapHdrOffset = NormalCapHdr.NextItemPtr & 0xFC;
 584     }
 585   }
 586
 587   //
 588   // If the device has been found PCI Express, attempt to traverse the extended
 589   // capabilities list. It starts right after the normal config space.
 590   //
 591   if (DeviceIsExpress) {
 592     UINT16 ExtendedCapHdrOffset;
 593
 594     ExtendedCapHdrOffset = PCI_MAX_CONFIG_OFFSET;
 595     while (ExtendedCapHdrOffset > 0) {
 596       PCI_EXPRESS_EXTENDED_CAPABILITIES_HEADER ExtendedCapHdr;
 597
 598       Status = PciDevice->ReadConfig (PciDevice, ExtendedCapHdrOffset,
 599                             &ExtendedCapHdr, sizeof ExtendedCapHdr);
 600       //
 601       // If the first extended config space access fails, assume the device has
 602       // no extended capabilities. If the first extended config space access
 603       // succeeds but we read an "all bits zero" extended capability header,
 604       // that means (by spec) the device has no extended capabilities.
 605       //
 606       if (ExtendedCapHdrOffset == PCI_MAX_CONFIG_OFFSET &&
 607           (RETURN_ERROR (Status) ||
 608            IsZeroBuffer (&ExtendedCapHdr, sizeof ExtendedCapHdr))) {
 609         break;
 610       }
 611       if (RETURN_ERROR (Status)) {
 612         goto FreeCapHdrOffsets;
 613       }
 614
 615       Status = InsertPciCap (OutCapList, CapHdrOffsets, PciCapExtended,
 616                  (UINT16)ExtendedCapHdr.CapabilityId, ExtendedCapHdrOffset,
 617                  (UINT8)ExtendedCapHdr.CapabilityVersion);
 618       if (RETURN_ERROR (Status)) {
 619         goto FreeCapHdrOffsets;
 620       }
 621
 622       ExtendedCapHdrOffset = ExtendedCapHdr.NextCapabilityOffset & 0xFFC;
 623       if (ExtendedCapHdrOffset > 0 &&
 624           ExtendedCapHdrOffset < PCI_MAX_CONFIG_OFFSET) {
 625         //
 626         // Invalid capability pointer.
 627         //
 628         Status = RETURN_DEVICE_ERROR;
 629         goto FreeCapHdrOffsets;
 630       }
 631     }
 632   }
 633
 634   //
 635   // Both capabilities lists have been parsed; compute the PCI_CAP.MaxSizeHint
 636   // members if at least one capability has been found. In parallel, evacuate
 637   // the CapHdrOffsets collection.
 638   //
 639   // At first, set OffsetEntry to the iterator of the PCI_CAP object with the
 640   // lowest Offset (if such exists).
 641   //
 642   OffsetEntry = OrderedCollectionMin (CapHdrOffsets);
 643   if (OffsetEntry != NULL) {
 644     ORDERED_COLLECTION_ENTRY *NextOffsetEntry;
 645     PCI_CAP                  *PciCap;
 646
 647     //
 648     // Initialize NextOffsetEntry to the iterator of the PCI_CAP object with
 649     // the second lowest Offset (if such exists).
 650     //
 651     NextOffsetEntry = OrderedCollectionNext (OffsetEntry);
 652     //
 653     // Calculate MaxSizeHint for all PCI_CAP objects except the one with the
 654     // highest Offset.
 655     //
 656     while (NextOffsetEntry != NULL) {
 657       PCI_CAP *NextPciCap;
 658
 659       OrderedCollectionDelete (CapHdrOffsets, OffsetEntry, (VOID **)&PciCap);
 660       NextPciCap = OrderedCollectionUserStruct (NextOffsetEntry);
 661       CalculatePciCapMaxSizeHint (PciCap, NextPciCap);
 662
 663       OffsetEntry = NextOffsetEntry;
 664       NextOffsetEntry = OrderedCollectionNext (OffsetEntry);
 665     }
 666     //
 667     // Calculate MaxSizeHint for the PCI_CAP object with the highest Offset.
 668     //
 669     OrderedCollectionDelete (CapHdrOffsets, OffsetEntry, (VOID **)&PciCap);
 670     CalculatePciCapMaxSizeHint (PciCap, NULL);
 671   }
 672   ASSERT (OrderedCollectionIsEmpty (CapHdrOffsets));
 673   OrderedCollectionUninit (CapHdrOffsets);
 674
 675   DebugDumpPciCapList (OutCapList);
 676   *CapList = OutCapList;
 677   return RETURN_SUCCESS;
 678
 679 FreeCapHdrOffsets:
 680   EmptyAndUninitPciCapCollection (CapHdrOffsets, FALSE);
 681
 682 FreeCapabilities:
 683   EmptyAndUninitPciCapCollection (OutCapList->Capabilities, TRUE);
 684
 685 FreeOutCapList:
 686   FreePool (OutCapList);
 687
 688   ASSERT (RETURN_ERROR (Status));
 689   DEBUG ((DEBUG_ERROR, "%a:%a: %r\n", gEfiCallerBaseName, __FUNCTION__,
 690     Status));
 691   return Status;
 692 }
 693
 694
 695 /**
 696   Free the resources used by CapList.
 697
 698   @param[in] CapList  The PCI_CAP_LIST object to free, originally produced by
 699                       PciCapListInit().
 700 **/
 701 VOID
 702 EFIAPI
 703 PciCapListUninit (
 704   IN PCI_CAP_LIST *CapList
 705   )
 706 {
 707   EmptyAndUninitPciCapCollection (CapList->Capabilities, TRUE);
 708   FreePool (CapList);
 709 }
 710
 711
 712 /**
 713   Locate a capability instance in the parsed capabilities lists.
 714
 715   @param[in] CapList   The PCI_CAP_LIST object produced by PciCapListInit().
 716
 717   @param[in] Domain    Distinguishes whether CapId is 8-bit wide and
 718                        interpreted in normal config space, or 16-bit wide and
 719                        interpreted in extended config space. Capability ID
 720                        definitions are relative to domain.
 721
 722   @param[in] CapId     Capability identifier to look up.
 723
 724   @param[in] Instance  Domain and CapId may identify a multi-instance
 725                        capability. When Instance is zero, the first instance of
 726                        the capability is located (in list traversal order --
 727                        which may not mean increasing config space offset
 728                        order). Higher Instance values locate subsequent
 729                        instances of the same capability (in list traversal
 730                        order).
 731
 732   @param[out] Cap      The capability instance that matches the search
 733                        criteria. Cap is owned by CapList and becomes invalid
 734                        when CapList is freed with PciCapListUninit().
 735                        PciCapListFindCap() may be called with Cap set to NULL,
 736                        in order to test the existence of a specific capability
 737                        instance.
 738
 739   @retval RETURN_SUCCESS    The capability instance identified by (Domain,
 740                             CapId, Instance) has been found.
 741
 742   @retval RETURN_NOT_FOUND  The requested (Domain, CapId, Instance) capability
 743                             instance does not exist.
 744 **/
 745 RETURN_STATUS
 746 EFIAPI
 747 PciCapListFindCap (
 748   IN  PCI_CAP_LIST   *CapList,
 749   IN  PCI_CAP_DOMAIN Domain,
 750   IN  UINT16         CapId,
 751   IN  UINT16         Instance,
 752   OUT PCI_CAP        **Cap    OPTIONAL
 753   )
 754 {
 755   PCI_CAP_KEY              Key;
 756   ORDERED_COLLECTION_ENTRY *PciCapEntry;
 757
 758   Key.Domain   = Domain;
 759   Key.CapId    = CapId;
 760   Key.Instance = Instance;
 761
 762   PciCapEntry = OrderedCollectionFind (CapList->Capabilities, &Key);
 763   if (PciCapEntry == NULL) {
 764     return RETURN_NOT_FOUND;
 765   }
 766   if (Cap != NULL) {
 767     *Cap = OrderedCollectionUserStruct (PciCapEntry);
 768   }
 769   return RETURN_SUCCESS;
 770 }
 771
 772
 773 /**
 774   Locate the first instance of the capability given by (Domain, CapId) such
 775   that the instance's Version is greater than or equal to MinVersion.
 776
 777   This is a convenience function that may save client code calls to
 778   PciCapListFindCap() and PciCapGetInfo().
 779
 780   @param[in] CapList     The PCI_CAP_LIST object produced by PciCapListInit().
 781
 782   @param[in] Domain      Distinguishes whether CapId is 8-bit wide and
 783                          interpreted in normal config space, or 16-bit wide and
 784                          interpreted in extended config space. Capability ID
 785                          definitions are relative to domain.
 786
 787   @param[in] CapId       Capability identifier to look up.
 788
 789   @param[in] MinVersion  The minimum version that the capability instance is
 790                          required to have. Note that all capability instances
 791                          in Domain=PciCapNormal have Version=0.
 792
 793   @param[out] Cap        The first capability instance that matches the search
 794                          criteria. Cap is owned by CapList and becomes invalid
 795                          when CapList is freed with PciCapListUninit().
 796                          PciCapListFindCapVersion() may be called with Cap set
 797                          to NULL, in order just to test whether the search
 798                          criteria are satisfiable.
 799
 800   @retval RETURN_SUCCESS    The first capability instance matching (Domain,
 801                             CapId, MinVersion) has been located.
 802
 803   @retval RETURN_NOT_FOUND  No capability instance matches (Domain, CapId,
 804                             MinVersion).
 805 **/
 806 RETURN_STATUS
 807 EFIAPI
 808 PciCapListFindCapVersion (
 809   IN  PCI_CAP_LIST   *CapList,
 810   IN  PCI_CAP_DOMAIN Domain,
 811   IN  UINT16         CapId,
 812   IN  UINT8          MinVersion,
 813   OUT PCI_CAP        **Cap      OPTIONAL
 814   )
 815 {
 816   PCI_CAP_KEY              Key;
 817   ORDERED_COLLECTION_ENTRY *PciCapEntry;
 818
 819   //
 820   // Start the version checks at Instance#0 of (Domain, CapId).
 821   //
 822   Key.Domain   = Domain;
 823   Key.CapId    = CapId;
 824   Key.Instance = 0;
 825
 826   for (PciCapEntry = OrderedCollectionFind (CapList->Capabilities, &Key);
 827        PciCapEntry != NULL;
 828        PciCapEntry = OrderedCollectionNext (PciCapEntry)) {
 829     PCI_CAP *PciCap;
 830
 831     PciCap = OrderedCollectionUserStruct (PciCapEntry);
 832     //
 833     // PCI_CAP.Key ordering keeps instances of the same (Domain, CapId)
 834     // adjacent to each other, so stop searching if either Domain or CapId
 835     // changes.
 836     //
 837     if (PciCap->Key.Domain != Domain || PciCap->Key.CapId != CapId) {
 838       break;
 839     }
 840     if (PciCap->Version >= MinVersion) {
 841       //
 842       // Match found.
 843       //
 844       if (Cap != NULL) {
 845         *Cap = PciCap;
 846       }
 847       return RETURN_SUCCESS;
 848     }
 849   }
 850   return RETURN_NOT_FOUND;
 851 }
 852
 853
 854 /**
 855   Get information about a PCI Capability instance.
 856
 857   @param[in] Cap    The capability instance to get info about, located with
 858                     PciCapListFindCap*().
 859
 860   @param[out] Info  A PCI_CAP_INFO structure that describes the properties of
 861                     Cap.
 862
 863   @retval RETURN_SUCCESS  Fields of Info have been set.
 864
 865   @return                 Unspecified error codes, if filling in Info failed
 866                           for some reason.
 867 **/
 868 RETURN_STATUS
 869 EFIAPI
 870 PciCapGetInfo (
 871   IN  PCI_CAP      *Cap,
 872   OUT PCI_CAP_INFO *Info
 873   )
 874 {
 875   PCI_CAP *InstanceZero;
 876
 877   ASSERT (Info != NULL);
 878
 879   InstanceZero = (Cap->Key.Instance == 0 ? Cap :
 880                   Cap->NumInstancesUnion.InstanceZero);
 881
 882   Info->Domain       = Cap->Key.Domain;
 883   Info->CapId        = Cap->Key.CapId;
 884   Info->NumInstances = InstanceZero->NumInstancesUnion.NumInstances;
 885   Info->Instance     = Cap->Key.Instance;
 886   Info->Offset       = Cap->Offset;
 887   Info->MaxSizeHint  = Cap->MaxSizeHint;
 888   Info->Version      = Cap->Version;
 889
 890   return RETURN_SUCCESS;
 891 }
 892
 893
 894 /**
 895   Read a slice of a capability instance.
 896
 897   The function performs as few config space accesses as possible (without
 898   attempting 64-bit wide accesses). PciCapRead() performs bounds checking on
 899   SourceOffsetInCap and Size, and only invokes PciDevice->ReadConfig() if the
 900   requested transfer falls within Cap.
 901
 902   @param[in] PciDevice           Implementation-specific unique representation
 903                                  of the PCI device in the PCI hierarchy.
 904
 905   @param[in] Cap                 The capability instance to read, located with
 906                                  PciCapListFindCap*().
 907
 908   @param[in] SourceOffsetInCap   Source offset relative to the capability
 909                                  header to start reading from. A zero value
 910                                  refers to the first byte of the capability
 911                                  header.
 912
 913   @param[out] DestinationBuffer  Buffer to store the read data to.
 914
 915   @param[in] Size                The number of bytes to transfer.
 916
 917   @retval RETURN_SUCCESS          Size bytes have been transferred from Cap to
 918                                   DestinationBuffer.
 919
 920   @retval RETURN_BAD_BUFFER_SIZE  Reading Size bytes starting from
 921                                   SourceOffsetInCap would not (entirely) be
 922                                   contained within Cap, as suggested by
 923                                   PCI_CAP_INFO.MaxSizeHint. No bytes have been
 924                                   read.
 925
 926   @return                         Error codes propagated from
 927                                   PciDevice->ReadConfig(). Fewer than Size
 928                                   bytes may have been read.
 929 **/
 930 RETURN_STATUS
 931 EFIAPI
 932 PciCapRead (
 933   IN  PCI_CAP_DEV *PciDevice,
 934   IN  PCI_CAP     *Cap,
 935   IN  UINT16      SourceOffsetInCap,
 936   OUT VOID        *DestinationBuffer,
 937   IN  UINT16      Size
 938   )
 939 {
 940   //
 941   // Note: all UINT16 values are promoted to INT32 below, and addition and
 942   // comparison take place between INT32 values.
 943   //
 944   if (SourceOffsetInCap + Size > Cap->MaxSizeHint) {
 945     return RETURN_BAD_BUFFER_SIZE;
 946   }
 947   return PciDevice->ReadConfig (PciDevice, Cap->Offset + SourceOffsetInCap,
 948                       DestinationBuffer, Size);
 949 }
 950
 951
 952 /**
 953   Write a slice of a capability instance.
 954
 955   The function performs as few config space accesses as possible (without
 956   attempting 64-bit wide accesses). PciCapWrite() performs bounds checking on
 957   DestinationOffsetInCap and Size, and only invokes PciDevice->WriteConfig() if
 958   the requested transfer falls within Cap.
 959
 960   @param[in] PciDevice               Implementation-specific unique
 961                                      representation of the PCI device in the
 962                                      PCI hierarchy.
 963
 964   @param[in] Cap                     The capability instance to write, located
 965                                      with PciCapListFindCap*().
 966
 967   @param[in] DestinationOffsetInCap  Destination offset relative to the
 968                                      capability header to start writing at. A
 969                                      zero value refers to the first byte of the
 970                                      capability header.
 971
 972   @param[in] SourceBuffer            Buffer to read the data to be stored from.
 973
 974   @param[in] Size                    The number of bytes to transfer.
 975
 976   @retval RETURN_SUCCESS          Size bytes have been transferred from
 977                                   SourceBuffer to Cap.
 978
 979   @retval RETURN_BAD_BUFFER_SIZE  Writing Size bytes starting at
 980                                   DestinationOffsetInCap would not (entirely)
 981                                   be contained within Cap, as suggested by
 982                                   PCI_CAP_INFO.MaxSizeHint. No bytes have been
 983                                   written.
 984
 985   @return                         Error codes propagated from
 986                                   PciDevice->WriteConfig(). Fewer than Size
 987                                   bytes may have been written.
 988 **/
 989 RETURN_STATUS
 990 EFIAPI
 991 PciCapWrite (
 992   IN PCI_CAP_DEV *PciDevice,
 993   IN PCI_CAP     *Cap,
 994   IN UINT16      DestinationOffsetInCap,
 995   IN VOID        *SourceBuffer,
 996   IN UINT16      Size
 997   )
 998 {
 999   //
1000   // Note: all UINT16 values are promoted to INT32 below, and addition and
1001   // comparison take place between INT32 values.
1002   //
1003   if (DestinationOffsetInCap + Size > Cap->MaxSizeHint) {
1004     return RETURN_BAD_BUFFER_SIZE;
1005   }
1006   return PciDevice->WriteConfig (PciDevice,
1007                       Cap->Offset + DestinationOffsetInCap, SourceBuffer,
1008                       Size);
1009 }