BasePciCapLib.c

Go to the documentation of this file.

 
#include <IndustryStandard/PciExpress21.h>
 
#include <Library/BaseMemoryLib.h>
#include <Library/DebugLib.h>
#include <Library/MemoryAllocationLib.h>
 
#include "BasePciCapLib.h"
 
STATIC
INTN
EFIAPI
ComparePciCapKey (
  IN CONST VOID  *PciCapKey,
  IN CONST VOID  *PciCap
  )
{
  CONST PCI_CAP_KEY  *Key1;
  CONST PCI_CAP_KEY  *Key2;
 
  Key1 = PciCapKey;
  Key2 = &((CONST PCI_CAP *)PciCap)->Key;
 
  if (Key1->Domain < Key2->Domain) {
    return -1;
  }
 
  if (Key1->Domain > Key2->Domain) {
    return 1;
  }
 
  if (Key1->CapId < Key2->CapId) {
    return -1;
  }
 
  if (Key1->CapId > Key2->CapId) {
    return 1;
  }
 
  if (Key1->Instance < Key2->Instance) {
    return -1;
  }
 
  if (Key1->Instance > Key2->Instance) {
    return 1;
  }
 
  return 0;
}
 
STATIC
INTN
EFIAPI
ComparePciCap (
  IN CONST VOID  *PciCap1,
  IN CONST VOID  *PciCap2
  )
{
  CONST PCI_CAP_KEY  *PciCap1Key;
 
  PciCap1Key = &((CONST PCI_CAP *)PciCap1)->Key;
  return ComparePciCapKey (PciCap1Key, PciCap2);
}
 
STATIC
INTN
EFIAPI
ComparePciCapOffsetKey (
  IN CONST VOID  *CapHdrOffset,
  IN CONST VOID  *PciCap
  )
{
  UINT16  Offset1;
  UINT16  Offset2;
 
  Offset1 = *(CONST UINT16 *)CapHdrOffset;
  Offset2 = ((CONST PCI_CAP *)PciCap)->Offset;
  //
  // Note: both Offset1 and Offset2 are promoted to INT32 below, and the
  // subtraction takes place between INT32 values.
  //
  return Offset1 - Offset2;
}
 
STATIC
INTN
EFIAPI
ComparePciCapOffset (
  IN CONST VOID  *PciCap1,
  IN CONST VOID  *PciCap2
  )
{
  UINT16  Offset1;
  UINT16  Offset2;
 
  Offset1 = ((CONST PCI_CAP *)PciCap1)->Offset;
  Offset2 = ((CONST PCI_CAP *)PciCap2)->Offset;
  //
  // Note: both Offset1 and Offset2 are promoted to INT32 below, and the
  // subtraction takes place between INT32 values.
  //
  return Offset1 - Offset2;
}
 
STATIC
RETURN_STATUS
InsertPciCap (
  IN OUT PCI_CAP_LIST        *CapList,
  IN OUT ORDERED_COLLECTION  *CapHdrOffsets,
  IN     PCI_CAP_DOMAIN      Domain,
  IN     UINT16              CapId,
  IN     UINT16              Offset,
  IN     UINT8               Version
  )
{
  PCI_CAP                   *PciCap;
  RETURN_STATUS             Status;
  ORDERED_COLLECTION_ENTRY  *PciCapEntry;
  PCI_CAP                   *InstanceZero;
 
  ASSERT ((Offset & 0x3) == 0);
  ASSERT (
    Offset < (Domain == PciCapNormal ?
              PCI_MAX_CONFIG_OFFSET : PCI_EXP_MAX_CONFIG_OFFSET)
    );
  ASSERT (Domain == PciCapExtended || Version == 0);
 
  //
  // Set InstanceZero to suppress incorrect compiler/analyzer warnings.
  //
  InstanceZero = NULL;
 
  //
  // Allocate PciCap, and populate it assuming it is the first occurrence of
  // (Domain, CapId). Note that PciCap->MaxSizeHint is not assigned the final
  // value just yet.
  //
  PciCap = AllocatePool (sizeof *PciCap);
  if (PciCap == NULL) {
    return RETURN_OUT_OF_RESOURCES;
  }
 
  PciCap->Key.Domain                     = Domain;
  PciCap->Key.CapId                      = CapId;
  PciCap->Key.Instance                   = 0;
  PciCap->NumInstancesUnion.NumInstances = 1;
  PciCap->Offset                         = Offset;
  PciCap->MaxSizeHint                    = 0;
  PciCap->Version                        = Version;
 
  //
  // Add PciCap to CapList.
  //
  Status = OrderedCollectionInsert (
             CapList->Capabilities,
             &PciCapEntry,
             PciCap
             );
  if (RETURN_ERROR (Status)) {
    if (Status == RETURN_OUT_OF_RESOURCES) {
      goto FreePciCap;
    }
 
    ASSERT (Status == RETURN_ALREADY_STARTED);
    //
    // PciCap is not the first instance of (Domain, CapId). Add it as a new
    // instance, taking the current instance count from Instance#0. Note that
    // we don't bump the instance count maintained in Instance#0 just yet, to
    // keep rollback on errors simple.
    //
    InstanceZero                           = OrderedCollectionUserStruct (PciCapEntry);
    PciCap->Key.Instance                   = InstanceZero->NumInstancesUnion.NumInstances;
    PciCap->NumInstancesUnion.InstanceZero = InstanceZero;
 
    ASSERT (PciCap->Key.Instance > 0);
    Status = OrderedCollectionInsert (
               CapList->Capabilities,
               &PciCapEntry,
               PciCap
               );
    if (Status == RETURN_OUT_OF_RESOURCES) {
      goto FreePciCap;
    }
  }
 
  //
  // At this point, PciCap has been inserted in CapList->Capabilities, either
  // with Instance==0 or with Instance>0. PciCapEntry is the iterator that
  // links PciCap.
  //
  ASSERT_RETURN_ERROR (Status);
 
  //
  // Link PciCap into CapHdrOffsets too, to order it globally based on config
  // space offset. Note that partial overlaps between capability headers is not
  // possible: Offset is DWORD aligned, normal capability headers are 16-bit
  // wide, and extended capability headers are 32-bit wide. Therefore any two
  // capability headers either are distinct or start at the same offset
  // (implying a loop in the respective capabilities list).
  //
  Status = OrderedCollectionInsert (CapHdrOffsets, NULL, PciCap);
  if (RETURN_ERROR (Status)) {
    if (Status == RETURN_ALREADY_STARTED) {
      //
      // Loop found; map return status accordingly.
      //
      Status = RETURN_DEVICE_ERROR;
    }
 
    goto DeletePciCapFromCapList;
  }
 
  //
  // Now we can bump the instance count maintained in Instance#0, if PciCap is
  // not the first instance of (Domain, CapId).
  //
  if (PciCap->Key.Instance > 0) {
    //
    // Suppress invalid "nullptr dereference" compiler/analyzer warnings: the
    // only way for "PciCap->Key.Instance" to be positive here is for it to
    // have been assigned *from* dereferencing "InstanceZero" above.
    //
    ASSERT (InstanceZero != NULL);
 
    InstanceZero->NumInstancesUnion.NumInstances++;
  }
 
  return RETURN_SUCCESS;
 
DeletePciCapFromCapList:
  OrderedCollectionDelete (CapList->Capabilities, PciCapEntry, NULL);
 
FreePciCap:
  FreePool (PciCap);
 
  return Status;
}
 
STATIC
VOID
CalculatePciCapMaxSizeHint (
  IN OUT PCI_CAP  *PciCap,
  IN     PCI_CAP  *NextPciCap OPTIONAL
  )
{
  UINT16  ConfigSpaceSize;
 
  ConfigSpaceSize = (PciCap->Key.Domain == PciCapNormal ?
                     PCI_MAX_CONFIG_OFFSET : PCI_EXP_MAX_CONFIG_OFFSET);
  //
  // The following is guaranteed by the interface contract on
  // CalculatePciCapMaxSizeHint().
  //
  ASSERT (NextPciCap == NULL || PciCap->Offset < NextPciCap->Offset);
  //
  // The following is guaranteed by the interface contract on InsertPciCap().
  //
  ASSERT (PciCap->Offset < ConfigSpaceSize);
  //
  // Thus we can safely subtract PciCap->Offset from either of
  // - ConfigSpaceSize
  // - and NextPciCap->Offset (if NextPciCap is not NULL).
  //
  // PciCap extends from PciCap->Offset to NextPciCap->Offset (if any), except
  // it cannot cross config space boundary.
  //
  if ((NextPciCap == NULL) || (NextPciCap->Offset >= ConfigSpaceSize)) {
    PciCap->MaxSizeHint = ConfigSpaceSize - PciCap->Offset;
    return;
  }
 
  PciCap->MaxSizeHint = NextPciCap->Offset - PciCap->Offset;
}
 
STATIC
VOID
EFIAPI
DebugDumpPciCapList (
  IN PCI_CAP_LIST  *CapList
  )
{
  DEBUG_CODE_BEGIN ();
  ORDERED_COLLECTION_ENTRY  *PciCapEntry;
 
  for (PciCapEntry = OrderedCollectionMin (CapList->Capabilities);
       PciCapEntry != NULL;
       PciCapEntry = OrderedCollectionNext (PciCapEntry))
  {
    PCI_CAP        *PciCap;
    RETURN_STATUS  Status;
    PCI_CAP_INFO   Info;
 
    PciCap = OrderedCollectionUserStruct (PciCapEntry);
    Status = PciCapGetInfo (PciCap, &Info);
    //
    // PciCapGetInfo() cannot fail in this library instance.
    //
    ASSERT_RETURN_ERROR (Status);
 
    DEBUG ((
      DEBUG_VERBOSE,
      "%a:%a: %a 0x%04x %03u/%03u v0x%x @0x%03x+0x%03x\n",
      gEfiCallerBaseName,
      __func__,
      (Info.Domain == PciCapNormal ? "Norm" : "Extd"),
      Info.CapId,
      Info.Instance,
      Info.NumInstances,
      Info.Version,
      Info.Offset,
      Info.MaxSizeHint
      ));
  }
 
  DEBUG_CODE_END ();
}
 
STATIC
VOID
EmptyAndUninitPciCapCollection (
  IN OUT ORDERED_COLLECTION  *PciCapCollection,
  IN     BOOLEAN             FreePciCap
  )
{
  ORDERED_COLLECTION_ENTRY  *PciCapEntry;
  ORDERED_COLLECTION_ENTRY  *NextEntry;
 
  for (PciCapEntry = OrderedCollectionMin (PciCapCollection);
       PciCapEntry != NULL;
       PciCapEntry = NextEntry)
  {
    PCI_CAP  *PciCap;
 
    NextEntry = OrderedCollectionNext (PciCapEntry);
    OrderedCollectionDelete (PciCapCollection, PciCapEntry, (VOID **)&PciCap);
    if (FreePciCap) {
      FreePool (PciCap);
    }
  }
 
  OrderedCollectionUninit (PciCapCollection);
}
 
RETURN_STATUS
EFIAPI
PciCapListInit (
  IN  PCI_CAP_DEV   *PciDevice,
  OUT PCI_CAP_LIST  **CapList
  )
{
  PCI_CAP_LIST              *OutCapList;
  RETURN_STATUS             Status;
  ORDERED_COLLECTION        *CapHdrOffsets;
  UINT16                    PciStatusReg;
  BOOLEAN                   DeviceIsExpress;
  ORDERED_COLLECTION_ENTRY  *OffsetEntry;
 
  //
  // Allocate the output structure.
  //
  OutCapList = AllocatePool (sizeof *OutCapList);
  if (OutCapList == NULL) {
    return RETURN_OUT_OF_RESOURCES;
  }
 
  //
  // The OutCapList->Capabilities collection owns the PCI_CAP structures and
  // orders them based on PCI_CAP.Key.
  //
  OutCapList->Capabilities = OrderedCollectionInit (
                               ComparePciCap,
                               ComparePciCapKey
                               );
  if (OutCapList->Capabilities == NULL) {
    Status = RETURN_OUT_OF_RESOURCES;
    goto FreeOutCapList;
  }
 
  //
  // The (temporary) CapHdrOffsets collection only references PCI_CAP
  // structures, and orders them based on PCI_CAP.Offset.
  //
  CapHdrOffsets = OrderedCollectionInit (
                    ComparePciCapOffset,
                    ComparePciCapOffsetKey
                    );
  if (CapHdrOffsets == NULL) {
    Status = RETURN_OUT_OF_RESOURCES;
    goto FreeCapabilities;
  }
 
  //
  // Whether the device is PCI Express depends on the normal capability with
  // identifier EFI_PCI_CAPABILITY_ID_PCIEXP.
  //
  DeviceIsExpress = FALSE;
 
  //
  // Check whether a normal capabilities list is present. If there's none,
  // that's not an error; we'll just return OutCapList->Capabilities empty.
  //
  Status = PciDevice->ReadConfig (
                        PciDevice,
                        PCI_PRIMARY_STATUS_OFFSET,
                        &PciStatusReg,
                        sizeof PciStatusReg
                        );
  if (RETURN_ERROR (Status)) {
    goto FreeCapHdrOffsets;
  }
 
  if ((PciStatusReg & EFI_PCI_STATUS_CAPABILITY) != 0) {
    UINT8  NormalCapHdrOffset;
 
    //
    // Fetch the start offset of the normal capabilities list.
    //
    Status = PciDevice->ReadConfig (
                          PciDevice,
                          PCI_CAPBILITY_POINTER_OFFSET,
                          &NormalCapHdrOffset,
                          sizeof NormalCapHdrOffset
                          );
    if (RETURN_ERROR (Status)) {
      goto FreeCapHdrOffsets;
    }
 
    //
    // Traverse the normal capabilities list.
    //
    NormalCapHdrOffset &= 0xFC;
    while (NormalCapHdrOffset > 0) {
      EFI_PCI_CAPABILITY_HDR  NormalCapHdr;
 
      Status = PciDevice->ReadConfig (
                            PciDevice,
                            NormalCapHdrOffset,
                            &NormalCapHdr,
                            sizeof NormalCapHdr
                            );
      if (RETURN_ERROR (Status)) {
        goto FreeCapHdrOffsets;
      }
 
      Status = InsertPciCap (
                 OutCapList,
                 CapHdrOffsets,
                 PciCapNormal,
                 NormalCapHdr.CapabilityID,
                 NormalCapHdrOffset,
                 0
                 );
      if (RETURN_ERROR (Status)) {
        goto FreeCapHdrOffsets;
      }
 
      if (NormalCapHdr.CapabilityID == EFI_PCI_CAPABILITY_ID_PCIEXP) {
        DeviceIsExpress = TRUE;
      }
 
      NormalCapHdrOffset = NormalCapHdr.NextItemPtr & 0xFC;
    }
  }
 
  //
  // If the device has been found PCI Express, attempt to traverse the extended
  // capabilities list. It starts right after the normal config space.
  //
  if (DeviceIsExpress) {
    UINT16  ExtendedCapHdrOffset;
 
    ExtendedCapHdrOffset = PCI_MAX_CONFIG_OFFSET;
    while (ExtendedCapHdrOffset > 0) {
      PCI_EXPRESS_EXTENDED_CAPABILITIES_HEADER  ExtendedCapHdr;
 
      Status = PciDevice->ReadConfig (
                            PciDevice,
                            ExtendedCapHdrOffset,
                            &ExtendedCapHdr,
                            sizeof ExtendedCapHdr
                            );
      //
      // If the first extended config space access fails, assume the device has
      // no extended capabilities. If the first extended config space access
      // succeeds but we read an "all bits zero" extended capability header,
      // that means (by spec) the device has no extended capabilities.
      //
      if ((ExtendedCapHdrOffset == PCI_MAX_CONFIG_OFFSET) &&
          (RETURN_ERROR (Status) ||
           IsZeroBuffer (&ExtendedCapHdr, sizeof ExtendedCapHdr)))
      {
        break;
      }
 
      if (RETURN_ERROR (Status)) {
        goto FreeCapHdrOffsets;
      }
 
      Status = InsertPciCap (
                 OutCapList,
                 CapHdrOffsets,
                 PciCapExtended,
                 (UINT16)ExtendedCapHdr.CapabilityId,
                 ExtendedCapHdrOffset,
                 (UINT8)ExtendedCapHdr.CapabilityVersion
                 );
      if (RETURN_ERROR (Status)) {
        goto FreeCapHdrOffsets;
      }
 
      ExtendedCapHdrOffset = ExtendedCapHdr.NextCapabilityOffset & 0xFFC;
      if ((ExtendedCapHdrOffset > 0) &&
          (ExtendedCapHdrOffset < PCI_MAX_CONFIG_OFFSET))
      {
        //
        // Invalid capability pointer.
        //
        Status = RETURN_DEVICE_ERROR;
        goto FreeCapHdrOffsets;
      }
    }
  }
 
  //
  // Both capabilities lists have been parsed; compute the PCI_CAP.MaxSizeHint
  // members if at least one capability has been found. In parallel, evacuate
  // the CapHdrOffsets collection.
  //
  // At first, set OffsetEntry to the iterator of the PCI_CAP object with the
  // lowest Offset (if such exists).
  //
  OffsetEntry = OrderedCollectionMin (CapHdrOffsets);
  if (OffsetEntry != NULL) {
    ORDERED_COLLECTION_ENTRY  *NextOffsetEntry;
    PCI_CAP                   *PciCap;
 
    //
    // Initialize NextOffsetEntry to the iterator of the PCI_CAP object with
    // the second lowest Offset (if such exists).
    //
    NextOffsetEntry = OrderedCollectionNext (OffsetEntry);
    //
    // Calculate MaxSizeHint for all PCI_CAP objects except the one with the
    // highest Offset.
    //
    while (NextOffsetEntry != NULL) {
      PCI_CAP  *NextPciCap;
 
      OrderedCollectionDelete (CapHdrOffsets, OffsetEntry, (VOID **)&PciCap);
      NextPciCap = OrderedCollectionUserStruct (NextOffsetEntry);
      CalculatePciCapMaxSizeHint (PciCap, NextPciCap);
 
      OffsetEntry     = NextOffsetEntry;
      NextOffsetEntry = OrderedCollectionNext (OffsetEntry);
    }
 
    //
    // Calculate MaxSizeHint for the PCI_CAP object with the highest Offset.
    //
    OrderedCollectionDelete (CapHdrOffsets, OffsetEntry, (VOID **)&PciCap);
    CalculatePciCapMaxSizeHint (PciCap, NULL);
  }
 
  ASSERT (OrderedCollectionIsEmpty (CapHdrOffsets));
  OrderedCollectionUninit (CapHdrOffsets);
 
  DebugDumpPciCapList (OutCapList);
  *CapList = OutCapList;
  return RETURN_SUCCESS;
 
FreeCapHdrOffsets:
  EmptyAndUninitPciCapCollection (CapHdrOffsets, FALSE);
 
FreeCapabilities:
  EmptyAndUninitPciCapCollection (OutCapList->Capabilities, TRUE);
 
FreeOutCapList:
  FreePool (OutCapList);
 
  ASSERT (RETURN_ERROR (Status));
  DEBUG ((
    DEBUG_ERROR,
    "%a:%a: %r\n",
    gEfiCallerBaseName,
    __func__,
    Status
    ));
  return Status;
}
 
VOID
EFIAPI
PciCapListUninit (
  IN PCI_CAP_LIST  *CapList
  )
{
  EmptyAndUninitPciCapCollection (CapList->Capabilities, TRUE);
  FreePool (CapList);
}
 
RETURN_STATUS
EFIAPI
PciCapListFindCap (
  IN  PCI_CAP_LIST    *CapList,
  IN  PCI_CAP_DOMAIN  Domain,
  IN  UINT16          CapId,
  IN  UINT16          Instance,
  OUT PCI_CAP         **Cap    OPTIONAL
  )
{
  PCI_CAP_KEY               Key;
  ORDERED_COLLECTION_ENTRY  *PciCapEntry;
 
  Key.Domain   = Domain;
  Key.CapId    = CapId;
  Key.Instance = Instance;
 
  PciCapEntry = OrderedCollectionFind (CapList->Capabilities, &Key);
  if (PciCapEntry == NULL) {
    return RETURN_NOT_FOUND;
  }
 
  if (Cap != NULL) {
    *Cap = OrderedCollectionUserStruct (PciCapEntry);
  }
 
  return RETURN_SUCCESS;
}
 
RETURN_STATUS
EFIAPI
PciCapListFindCapVersion (
  IN  PCI_CAP_LIST    *CapList,
  IN  PCI_CAP_DOMAIN  Domain,
  IN  UINT16          CapId,
  IN  UINT8           MinVersion,
  OUT PCI_CAP         **Cap      OPTIONAL
  )
{
  PCI_CAP_KEY               Key;
  ORDERED_COLLECTION_ENTRY  *PciCapEntry;
 
  //
  // Start the version checks at Instance#0 of (Domain, CapId).
  //
  Key.Domain   = Domain;
  Key.CapId    = CapId;
  Key.Instance = 0;
 
  for (PciCapEntry = OrderedCollectionFind (CapList->Capabilities, &Key);
       PciCapEntry != NULL;
       PciCapEntry = OrderedCollectionNext (PciCapEntry))
  {
    PCI_CAP  *PciCap;
 
    PciCap = OrderedCollectionUserStruct (PciCapEntry);
    //
    // PCI_CAP.Key ordering keeps instances of the same (Domain, CapId)
    // adjacent to each other, so stop searching if either Domain or CapId
    // changes.
    //
    if ((PciCap->Key.Domain != Domain) || (PciCap->Key.CapId != CapId)) {
      break;
    }
 
    if (PciCap->Version >= MinVersion) {
      //
      // Match found.
      //
      if (Cap != NULL) {
        *Cap = PciCap;
      }
 
      return RETURN_SUCCESS;
    }
  }
 
  return RETURN_NOT_FOUND;
}
 
RETURN_STATUS
EFIAPI
PciCapGetInfo (
  IN  PCI_CAP       *Cap,
  OUT PCI_CAP_INFO  *Info
  )
{
  PCI_CAP  *InstanceZero;
 
  ASSERT (Info != NULL);
 
  InstanceZero = (Cap->Key.Instance == 0 ? Cap :
                  Cap->NumInstancesUnion.InstanceZero);
 
  Info->Domain       = Cap->Key.Domain;
  Info->CapId        = Cap->Key.CapId;
  Info->NumInstances = InstanceZero->NumInstancesUnion.NumInstances;
  Info->Instance     = Cap->Key.Instance;
  Info->Offset       = Cap->Offset;
  Info->MaxSizeHint  = Cap->MaxSizeHint;
  Info->Version      = Cap->Version;
 
  return RETURN_SUCCESS;
}
 
RETURN_STATUS
EFIAPI
PciCapRead (
  IN  PCI_CAP_DEV  *PciDevice,
  IN  PCI_CAP      *Cap,
  IN  UINT16       SourceOffsetInCap,
  OUT VOID         *DestinationBuffer,
  IN  UINT16       Size
  )
{
  //
  // Note: all UINT16 values are promoted to INT32 below, and addition and
  // comparison take place between INT32 values.
  //
  if (SourceOffsetInCap + Size > Cap->MaxSizeHint) {
    return RETURN_BAD_BUFFER_SIZE;
  }
 
  return PciDevice->ReadConfig (
                      PciDevice,
                      Cap->Offset + SourceOffsetInCap,
                      DestinationBuffer,
                      Size
                      );
}
 
RETURN_STATUS
EFIAPI
PciCapWrite (
  IN PCI_CAP_DEV  *PciDevice,
  IN PCI_CAP      *Cap,
  IN UINT16       DestinationOffsetInCap,
  IN VOID         *SourceBuffer,
  IN UINT16       Size
  )
{
  //
  // Note: all UINT16 values are promoted to INT32 below, and addition and
  // comparison take place between INT32 values.
  //
  if (DestinationOffsetInCap + Size > Cap->MaxSizeHint) {
    return RETURN_BAD_BUFFER_SIZE;
  }
 
  return PciDevice->WriteConfig (
                      PciDevice,
                      Cap->Offset + DestinationOffsetInCap,
                      SourceBuffer,
                      Size
                      );
}