Data Structures
struct	PCI_CAP_DEV

struct	PCI_CAP_INFO

Typedefs
typedef struct PCI_CAP_DEV	PCI_CAP_DEV

typedef IN UINT16	SourceOffset

typedef IN UINT16 OUT VOID *	DestinationBuffer

typedef IN UINT16 OUT VOID IN UINT16	Size

typedef IN UINT16	DestinationOffset

typedef IN UINT16 IN VOID *	SourceBuffer

typedef struct PCI_CAP_LIST	PCI_CAP_LIST

typedef struct PCI_CAP	PCI_CAP

Enumerations
enum	PCI_CAP_DOMAIN { PciCapNormal, PciCapExtended }

Functions
typedef	RETURN_STATUS (EFIAPI PCI_CAP_DEV_READ_CONFIG)(IN PCI_CAP_DEV PciDevice

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)

RETURN_STATUS EFIAPI	PciCapListFindCapVersion (IN PCI_CAP_LIST CapList, IN PCI_CAP_DOMAIN Domain, IN UINT16 CapId, IN UINT8 MinVersion, OUT PCI_CAP *Cap)

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

Library class to 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

Typedef Documentation

typedef IN UINT16 OUT VOID* DestinationBuffer

typedef IN UINT16 DestinationOffset

typedef struct PCI_CAP PCI_CAP

typedef struct PCI_CAP_DEV PCI_CAP_DEV

typedef struct PCI_CAP_LIST PCI_CAP_LIST

typedef IN UINT16 IN VOID IN UINT16 Size

typedef IN UINT16 IN VOID* SourceBuffer

typedef IN UINT16 SourceOffset

Enumeration Type Documentation

enum PCI_CAP_DOMAIN

Enumerator
PciCapNormal
PciCapExtended

Function Documentation

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.

RETURN_STATUS EFIAPI PciCapListFindCap	(	IN PCI_CAP_LIST *	CapList,
		IN PCI_CAP_DOMAIN	Domain,
		IN UINT16	CapId,
		IN UINT16	Instance,
		OUT PCI_CAP **	Cap
	)

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.

RETURN_STATUS EFIAPI PciCapListFindCapVersion	(	IN PCI_CAP_LIST *	CapList,
		IN PCI_CAP_DOMAIN	Domain,
		IN UINT16	CapId,
		IN UINT8	MinVersion,
		OUT PCI_CAP **	Cap
	)

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).

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().

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().

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.

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.

typedef RETURN_STATUS ( EFIAPI * PCI_CAP_DEV_WRITE_CONFIG )

Read the config space of a given PCI device (both normal and extended).

PCI_CAP_DEV_READ_CONFIG performs as few config space accesses as possible (without attempting 64-bit wide accesses).

PCI_CAP_DEV_READ_CONFIG returns an unspecified error if accessing Size bytes from SourceOffset exceeds the config space limit of the PCI device. Fewer than Size bytes may have been read in this case.

Parameters

[in]	PciDevice	Implementation-specific unique representation of the PCI device in the PCI hierarchy.
[in]	SourceOffset	Source offset in the config space of the PCI device to start reading from.
[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 config space to DestinationBuffer.

Returns: Unspecified error codes. Fewer than Size bytes may have been read.

Write the config space of a given PCI device (both normal and extended).

PCI_CAP_DEV_WRITE_CONFIG performs as few config space accesses as possible (without attempting 64-bit wide accesses).

PCI_CAP_DEV_WRITE_CONFIG returns an unspecified error if accessing Size bytes at DestinationOffset exceeds the config space limit of the PCI device. Fewer than Size bytes may have been written in this case.

Parameters

[in]	PciDevice	Implementation-specific unique representation of the PCI device in the PCI hierarchy.
[in]	DestinationOffset	Destination offset in the config space of the PCI device to start writing at.
[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 config space.

Returns: Unspecified error codes. Fewer than Size bytes may have been written.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation