#include <IndustryStandard/PciExpress21.h>
#include <Library/BaseMemoryLib.h>
#include <Library/DebugLib.h>
#include <Library/MemoryAllocationLib.h>
#include "BasePciCapLib.h"

Functions
STATIC INTN EFIAPI	ComparePciCapKey (IN CONST VOID PciCapKey, IN CONST VOID PciCap)

STATIC INTN EFIAPI	ComparePciCap (IN CONST VOID PciCap1, IN CONST VOID PciCap2)

STATIC INTN EFIAPI	ComparePciCapOffsetKey (IN CONST VOID CapHdrOffset, IN CONST VOID PciCap)

STATIC INTN EFIAPI	ComparePciCapOffset (IN CONST VOID PciCap1, IN CONST VOID PciCap2)

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)

STATIC VOID	CalculatePciCapMaxSizeHint (IN OUT PCI_CAP PciCap, IN PCI_CAP NextPciCap OPTIONAL)

STATIC VOID EFIAPI	DebugDumpPciCapList (IN PCI_CAP_LIST *CapList)

STATIC VOID	EmptyAndUninitPciCapCollection (IN OUT ORDERED_COLLECTION *PciCapCollection, IN BOOLEAN FreePciCap)

RETURN_STATUS EFIAPI	PciCapListInit (IN PCI_CAP_DEV PciDevice, OUT PCI_CAP_LIST *CapList)

VOID EFIAPI	PciCapListUninit (IN PCI_CAP_LIST *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)

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)

RETURN_STATUS EFIAPI	PciCapGetInfo (IN PCI_CAP Cap, OUT PCI_CAP_INFO Info)

RETURN_STATUS EFIAPI	PciCapRead (IN PCI_CAP_DEV PciDevice, IN PCI_CAP Cap, IN UINT16 SourceOffsetInCap, OUT VOID *DestinationBuffer, IN UINT16 Size)

RETURN_STATUS EFIAPI	PciCapWrite (IN PCI_CAP_DEV PciDevice, IN PCI_CAP Cap, IN UINT16 DestinationOffsetInCap, IN VOID *SourceBuffer, IN UINT16 Size)

Detailed Description

Work with PCI capabilities in PCI config space.

Provides functions to parse capabilities lists, and to locate, describe, read and write capabilities. PCI config space access is abstracted away.

SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file BasePciCapLib.c.

Function Documentation

◆ CalculatePciCapMaxSizeHint()

STATIC VOID CalculatePciCapMaxSizeHint	(	IN OUT PCI_CAP *	PciCap,
		IN PCI_CAP *NextPciCap	OPTIONAL
	)

Calculate the MaxSizeHint member for a PCI_CAP object.

CalculatePciCapMaxSizeHint() may only be called once all capability instances have been successfully processed by InsertPciCap().

Parameters

[in,out]	PciCap	The PCI_CAP object for which to calculate the MaxSizeHint member. The caller is responsible for passing a PCI_CAP object that has been created by a successful invocation of InsertPciCap().
[in]	NextPciCap	If NextPciCap is NULL, then the caller is responsible for PciCap to represent the capability instance with the highest header offset in all config space. If NextPciCap is not NULL, then the caller is responsible for (a) having created NextPciCap with a successful invocation of InsertPciCap(), and (b) NextPciCap being the direct successor of PciCap in config space offset order, as ordered by ComparePciCapOffset().

Definition at line 362 of file BasePciCapLib.c.

◆ ComparePciCap()

STATIC INTN EFIAPI ComparePciCap	(	IN CONST VOID *	PciCap1,
		IN CONST VOID *	PciCap2
	)

Compare two PCI_CAP objects based on PCI_CAP.Key.

Parameters

[in]	PciCap1	Pointer to the first PCI_CAP.
[in]	PciCap2	Pointer to the second PCI_CAP.

Return values

<0	If PciCap1 compares less than PciCap2.
0	If PciCap1 compares equal to PciCap2.
>0	If PciCap1 compares greater than PciCap2.

Definition at line 91 of file BasePciCapLib.c.

◆ ComparePciCapKey()

STATIC INTN EFIAPI ComparePciCapKey	(	IN CONST VOID *	PciCapKey,
		IN CONST VOID *	PciCap
	)

Compare a standalone PCI_CAP_KEY against a PCI_CAP containing an embedded PCI_CAP_KEY.

Parameters

[in]	PciCapKey	Pointer to the bare PCI_CAP_KEY.
[in]	PciCap	Pointer to the PCI_CAP with the embedded PCI_CAP_KEY.

Return values

<0	If PciCapKey compares less than PciCap->Key.
0	If PciCapKey compares equal to PciCap->Key.
>0	If PciCapKey compares greater than PciCap->Key.

Definition at line 37 of file BasePciCapLib.c.

◆ ComparePciCapOffset()

STATIC INTN EFIAPI ComparePciCapOffset	(	IN CONST VOID *	PciCap1,
		IN CONST VOID *	PciCap2
	)

Compare two PCI_CAP objects based on PCI_CAP.Offset.

Parameters

[in]	PciCap1	Pointer to the first PCI_CAP.
[in]	PciCap2	Pointer to the second PCI_CAP.

Return values

<0	If PciCap1 compares less than PciCap2.
0	If PciCap1 compares equal to PciCap2.
>0	If PciCap1 compares greater than PciCap2.

Definition at line 152 of file BasePciCapLib.c.

◆ ComparePciCapOffsetKey()

STATIC INTN EFIAPI ComparePciCapOffsetKey	(	IN CONST VOID *	CapHdrOffset,
		IN CONST VOID *	PciCap
	)

Compare the standalone UINT16 config space offset of a capability header against a PCI_CAP containing an embedded Offset.

Parameters

[in]	CapHdrOffset	Pointer to the bare UINT16 config space offset.
[in]	PciCap	Pointer to the PCI_CAP with the embedded Offset.

Return values

<0	If CapHdrOffset compares less than PciCap->Offset.
0	If CapHdrOffset compares equal to PciCap->Offset.
>0	If CapHdrOffset compares greater than PciCap->Offset.

Definition at line 119 of file BasePciCapLib.c.

◆ DebugDumpPciCapList()

STATIC VOID EFIAPI DebugDumpPciCapList ( IN PCI_CAP_LIST * CapList )

Debug dump a PCI_CAP_LIST object at the DEBUG_VERBOSE level.

Parameters

[in] CapList The PCI_CAP_LIST object to dump.

Definition at line 404 of file BasePciCapLib.c.

◆ EmptyAndUninitPciCapCollection()

STATIC VOID EmptyAndUninitPciCapCollection	(	IN OUT ORDERED_COLLECTION *	PciCapCollection,
		IN BOOLEAN	FreePciCap
	)

Empty a collection of PCI_CAP structures, optionally releasing the referenced PCI_CAP structures themselves. Release the collection at last.

Parameters

[in,out]	PciCapCollection	The collection to empty and release.
[in]	FreePciCap	TRUE if the PCI_CAP structures linked by PciCapCollection should be released. When FALSE, the caller is responsible for retaining at least one reference to each PCI_CAP structure originally linked by PciCapCollection.

Definition at line 459 of file BasePciCapLib.c.

◆ InsertPciCap()

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
	)

Insert a new instance of the PCI capability given by (Domain, CapId) in CapList.

Parameters

[in,out]	CapList	The PCI_CAP_LIST into which the new PCI_CAP should be inserted. CapList will own the new PCI_CAP structure.
[in,out]	CapHdrOffsets	Link the new PCI_CAP structure into the (non-owning) CapHdrOffsets collection as well. CapHdrOffsets orders the PCI_CAP structures based on the PCI_CAP.Offset member, and enables the calculation of PCI_CAP.MaxSizeHint.
[in]	Domain	Whether the capability is normal or extended.
[in]	CapId	Capability ID (specific to Domain).
[in]	Offset	Config space offset at which the standard header of the capability starts. The caller is responsible for ensuring that Offset be DWORD aligned. The caller is also responsible for ensuring that Offset be within the config space identified by Domain.
[in]	Version	The version number of the capability. The caller is responsible for passing 0 as Version if Domain is PciCapNormal.

Return values

RETURN_SUCCESS	Insertion successful.
RETURN_OUT_OF_RESOURCES	Memory allocation failed.
RETURN_DEVICE_ERROR	A PCI_CAP with Offset is already linked by CapHdrOffsets. This indicates a loop in the capabilities list being parsed.

Definition at line 208 of file BasePciCapLib.c.

◆ PciCapGetInfo()

RETURN_STATUS EFIAPI PciCapGetInfo	(	IN PCI_CAP *	Cap,
		OUT PCI_CAP_INFO *	Info
	)

Get information about a PCI Capability instance.

Parameters

[in]	Cap	The capability instance to get info about, located with PciCapListFindCap*().
[out]	Info	A PCI_CAP_INFO structure that describes the properties of Cap.

Return values

RETURN_SUCCESS Fields of Info have been set.

Returns: Unspecified error codes, if filling in Info failed for some reason.

Definition at line 940 of file BasePciCapLib.c.

◆ PciCapListFindCap()

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
	)

Locate a capability instance in the parsed capabilities lists.

Parameters

[in]	CapList	The PCI_CAP_LIST object produced by PciCapListInit().
[in]	Domain	Distinguishes whether CapId is 8-bit wide and interpreted in normal config space, or 16-bit wide and interpreted in extended config space. Capability ID definitions are relative to domain.
[in]	CapId	Capability identifier to look up.
[in]	Instance	Domain and CapId may identify a multi-instance capability. When Instance is zero, the first instance of the capability is located (in list traversal order – which may not mean increasing config space offset order). Higher Instance values locate subsequent instances of the same capability (in list traversal order).
[out]	Cap	The capability instance that matches the search criteria. Cap is owned by CapList and becomes invalid when CapList is freed with PciCapListUninit(). PciCapListFindCap() may be called with Cap set to NULL, in order to test the existence of a specific capability instance.

Return values

RETURN_SUCCESS	The capability instance identified by (Domain, CapId, Instance) has been found.
RETURN_NOT_FOUND	The requested (Domain, CapId, Instance) capability instance does not exist.

Definition at line 813 of file BasePciCapLib.c.

◆ PciCapListFindCapVersion()

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
	)

Locate the first instance of the capability given by (Domain, CapId) such that the instance's Version is greater than or equal to MinVersion.

This is a convenience function that may save client code calls to PciCapListFindCap() and PciCapGetInfo().

Parameters

[in]	CapList	The PCI_CAP_LIST object produced by PciCapListInit().
[in]	Domain	Distinguishes whether CapId is 8-bit wide and interpreted in normal config space, or 16-bit wide and interpreted in extended config space. Capability ID definitions are relative to domain.
[in]	CapId	Capability identifier to look up.
[in]	MinVersion	The minimum version that the capability instance is required to have. Note that all capability instances in Domain=PciCapNormal have Version=0.
[out]	Cap	The first capability instance that matches the search criteria. Cap is owned by CapList and becomes invalid when CapList is freed with PciCapListUninit(). PciCapListFindCapVersion() may be called with Cap set to NULL, in order just to test whether the search criteria are satisfiable.

Return values

RETURN_SUCCESS	The first capability instance matching (Domain, CapId, MinVersion) has been located.
RETURN_NOT_FOUND	No capability instance matches (Domain, CapId, MinVersion).

Definition at line 875 of file BasePciCapLib.c.

◆ PciCapListInit()

RETURN_STATUS EFIAPI PciCapListInit	(	IN PCI_CAP_DEV *	PciDevice,
		OUT PCI_CAP_LIST **	CapList
	)

Parse the capabilities lists (both normal and extended, as applicable) of a PCI device.

If the PCI device has no capabilities, that per se will not fail PciCapListInit(); an empty capabilities list will be represented.

If the PCI device is found to be PCI Express, then an attempt will be made to parse the extended capabilities list as well. If the first extended config space access – via PciDevice->ReadConfig() with SourceOffset=0x100 and Size=4 – fails, that per se will not fail PciCapListInit(); the device will be assumed to have no extended capabilities.

Parameters

[in]	PciDevice	Implementation-specific unique representation of the PCI device in the PCI hierarchy.
[out]	CapList	Opaque data structure that holds an in-memory representation of the parsed capabilities lists of PciDevice.

Return values

RETURN_SUCCESS	The capabilities lists have been parsed from config space.
RETURN_OUT_OF_RESOURCES	Memory allocation failed.
RETURN_DEVICE_ERROR	A loop or some other kind of invalid pointer was detected in the capabilities lists of PciDevice.

Returns: Error codes propagated from PciDevice->ReadConfig().

Definition at line 517 of file BasePciCapLib.c.

◆ PciCapListUninit()

VOID EFIAPI PciCapListUninit ( IN PCI_CAP_LIST * CapList )

Free the resources used by CapList.

Parameters

[in] CapList The PCI_CAP_LIST object to free, originally produced by PciCapListInit().

Definition at line 770 of file BasePciCapLib.c.

◆ PciCapRead()

RETURN_STATUS EFIAPI PciCapRead	(	IN PCI_CAP_DEV *	PciDevice,
		IN PCI_CAP *	Cap,
		IN UINT16	SourceOffsetInCap,
		OUT VOID *	DestinationBuffer,
		IN UINT16	Size
	)

Read a slice of a capability instance.

The function performs as few config space accesses as possible (without attempting 64-bit wide accesses). PciCapRead() performs bounds checking on SourceOffsetInCap and Size, and only invokes PciDevice->ReadConfig() if the requested transfer falls within Cap.

Parameters

[in]	PciDevice	Implementation-specific unique representation of the PCI device in the PCI hierarchy.
[in]	Cap	The capability instance to read, located with PciCapListFindCap*().
[in]	SourceOffsetInCap	Source offset relative to the capability header to start reading from. A zero value refers to the first byte of the capability header.
[out]	DestinationBuffer	Buffer to store the read data to.
[in]	Size	The number of bytes to transfer.

Return values

RETURN_SUCCESS	Size bytes have been transferred from Cap to DestinationBuffer.
RETURN_BAD_BUFFER_SIZE	Reading Size bytes starting from SourceOffsetInCap would not (entirely) be contained within Cap, as suggested by PCI_CAP_INFO.MaxSizeHint. No bytes have been read.

Returns: Error codes propagated from PciDevice->ReadConfig(). Fewer than Size bytes may have been read.

Definition at line 1001 of file BasePciCapLib.c.

◆ PciCapWrite()

RETURN_STATUS EFIAPI PciCapWrite	(	IN PCI_CAP_DEV *	PciDevice,
		IN PCI_CAP *	Cap,
		IN UINT16	DestinationOffsetInCap,
		IN VOID *	SourceBuffer,
		IN UINT16	Size
	)

Write a slice of a capability instance.

The function performs as few config space accesses as possible (without attempting 64-bit wide accesses). PciCapWrite() performs bounds checking on DestinationOffsetInCap and Size, and only invokes PciDevice->WriteConfig() if the requested transfer falls within Cap.

Parameters

[in]	PciDevice	Implementation-specific unique representation of the PCI device in the PCI hierarchy.
[in]	Cap	The capability instance to write, located with PciCapListFindCap*().
[in]	DestinationOffsetInCap	Destination offset relative to the capability header to start writing at. A zero value refers to the first byte of the capability header.
[in]	SourceBuffer	Buffer to read the data to be stored from.
[in]	Size	The number of bytes to transfer.

Return values

RETURN_SUCCESS	Size bytes have been transferred from SourceBuffer to Cap.
RETURN_BAD_BUFFER_SIZE	Writing Size bytes starting at DestinationOffsetInCap would not (entirely) be contained within Cap, as suggested by PCI_CAP_INFO.MaxSizeHint. No bytes have been written.

Returns: Error codes propagated from PciDevice->WriteConfig(). Fewer than Size bytes may have been written.

Definition at line 1064 of file BasePciCapLib.c.

Functions

Detailed Description

Function Documentation

◆ CalculatePciCapMaxSizeHint()

◆ ComparePciCap()

◆ ComparePciCapKey()

◆ ComparePciCapOffset()

◆ ComparePciCapOffsetKey()

◆ DebugDumpPciCapList()

◆ EmptyAndUninitPciCapCollection()

◆ InsertPciCap()

◆ PciCapGetInfo()

◆ PciCapListFindCap()

◆ PciCapListFindCapVersion()

◆ PciCapListInit()

◆ PciCapListUninit()

◆ PciCapRead()

◆ PciCapWrite()