EFI PCI IO PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Provides the basic Memory, I/O, PCI configuration, and DMA interfaces that a driver uses to access its PCI controller.

Contents

GUID

#define EFI_PCI_IO_PROTOCOL_GUID \
  {0x4cf5b200,0x68b8,0x4ca5,0x9e,0xec,0xb2,0x3e,0x3f,0x50,0x2,0x9a}

Protocol Interface Structure

#include EFI_PROTOCOL_CONSUMER(PciIo)

extern EFI_GUID gEfiPciIoProtocolGuid;
typedef struct _EFI_PCI_IO_PROTOCOL {
  EFI_PCI_IO_PROTOCOL_POLL_IO_MEM        PollMem;
  EFI_PCI_IO_PROTOCOL_POLL_IO_MEM        PollIo;
  EFI_PCI_IO_PROTOCOL_ACCESS             Mem;
  EFI_PCI_IO_PROTOCOL_ACCESS             Io;
  EFI_PCI_IO_PROTOCOL_CONFIG_ACCESS      Pci;
  EFI_PCI_IO_PROTOCOL_COPY_MEM           CopyMem;
  EFI_PCI_IO_PROTOCOL_MAP                Map;
  EFI_PCI_IO_PROTOCOL_UNMAP              Unmap;
  EFI_PCI_IO_PROTOCOL_ALLOCATE_BUFFER    AllocateBuffer;
  EFI_PCI_IO_PROTOCOL_FREE_BUFFER        FreeBuffer;
  EFI_PCI_IO_PROTOCOL_FLUSH              Flush;
  EFI_PCI_IO_PROTOCOL_GET_LOCATION       GetLocation;
  EFI_PCI_IO_PROTOCOL_ATTRIBUTES         Attributes;
  EFI_PCI_IO_PROTOCOL_GET_BAR_ATTRIBUTES GetBarAttributes;
  EFI_PCI_IO_PROTOCOL_SET_BAR_ATTRIBUTES SetBarAttributes;
  UINT64                                 RomSize;
  VOID                                   *RomImage;
} EFI_PCI_IO_PROTOCOL;

Member

Member Description
PollMem Polls an address in PCI memory space until an exit condition is met, or a timeout occurs.
PollIo Polls an address in PCI I/O space until an exit condition is met, or a timeout occurs.
Mem.Read Allows BAR relative reads to PCI memory space.
Mem.Write Allows BAR relative writes to PCI memory space.
Io.Read Allows BAR relative reads to PCI I/O space.
Io.Write Allows BAR relative writes to PCI I/O space.
Pci.Read Allows PCI controller relative reads to PCI configuration space.
Pci.Write Allows PCI controller relative writes to PCI configuration space.
CopyMem Allows one region of PCI memory space to be copied to another region of PCI memory space.
Map Provides the PCI controller–specific address needed to access system memory for DMA.
Unmap Releases any resources allocated by Map().
AllocateBuffer Allocates pages that are suitable for a common buffer mapping.
FreeBuffer Frees pages that were allocated with AllocateBuffer().
Flush Flushes all PCI posted write transactions to system memory.
GetLocation Retrieves this PCI controller’s current PCI bus number, device number, and function number.
Attributes Performs an operation on the attributes that this PCI controller supports. The operations include getting the set of supported attributes, retrieving the current attributes, setting the current attributes, enabling attributes, and disabling attributes.
GetBarAttributes Gets the attributes that this PCI controller supports setting on a BAR using SetBarAttributes(), and retrieves the list of resource descriptors for a BAR.
SetBarAttributes Sets the attributes for a range of a BAR on a PCI controller.
RomSize The size, in bytes, of the ROM image.
RomImage A pointer to the in memory copy of the ROM image. The PCI Bus Driver is responsible for allocating memory for the ROM image, and copying the contents of the ROM to memory. The contents of this buffer are either from the PCI option ROM that can be accessed through the ROM BAR of the PCI controller, or it is from a platform-specific location. The Attributes() function can be used to determine from which of these two sources the RomImage buffer was initialized.

Related Definitions

#define EFI_PCI_IO_PASS_THROUGH_BAR 0xff
#define EFI_PCI_IO_ATTRIBUTE_ISA_MOTHERBOARD_IO    0x0001
#define EFI_PCI_IO_ATTRIBUTE_ISA_IO                0x0002
#define EFI_PCI_IO_ATTRIBUTE_VGA_PALETTE_IO        0x0004
#define EFI_PCI_IO_ATTRIBUTE_VGA_MEMORY            0x0008
#define EFI_PCI_IO_ATTRIBUTE_VGA_IO                0x0010
#define EFI_PCI_IO_ATTRIBUTE_IDE_PRIMARY_IO        0x0020
#define EFI_PCI_IO_ATTRIBUTE_IDE_SECONDARY_IO      0x0040
#define EFI_PCI_IO_ATTRIBUTE_MEMORY_WRITE_COMBINE  0x0080
#define EFI_PCI_IO_ATTRIBUTE_IO                    0x0100
#define EFI_PCI_IO_ATTRIBUTE_MEMORY                0x0200
#define EFI_PCI_IO_ATTRIBUTE_BUS_MASTER            0x0400
#define EFI_PCI_IO_ATTRIBUTE_MEMORY_CACHED         0x0800
#define EFI_PCI_IO_ATTRIBUTE_MEMORY_DISABLE        0x1000
#define EFI_PCI_IO_ATTRIBUTE_EMBEDDED_DEVICE       0x2000
#define EFI_PCI_IO_ATTRIBUTE_EMBEDDED_ROM          0x4000
#define EFI_PCI_IO_ATTRIBUTE_DUAL_ADDRESS_CYCLE    0x8000
#define EFI_PCI_IO_ATTRIBUTE_ISA_IO_16             0x10000
#define EFI_PCI_IO_ATTRIBUTE_VGA_PALETTE_IO_16     0x20000
#define EFI_PCI_IO_ATTRIBUTE_VGA_IO_16             0x40000
Attribute Description
EFI_PCI_IO_ATTRIBUTE_ISA_IO_16 If this bit is set, then the PCI I/O cycles between 0x100 and 0x3FF are forwarded to the PCI controller using a 16-bit address decoder on address bits 0..15. Address bits 16..31 must be zero. This bit is used to forward I/O cycles for legacy ISA devices. If this bit is set, then the PCI Host Bus Controller and all the PCI to PCI bridges between the PCI Host Bus Controller and the PCI Controller are configured to forward these PCI I/O cycles. This bit may not be combined with EFI_PCI_IO_ATTRIBUTE_ISA_IO.
EFI_PCI_IO_ATTRIBUTE_VGA_PALETTE_IO_16 If this bit is set, then the PCI I/O write cycles for 0x3C6, 0x3C8, and 0x3C9 are forwarded to the PCI controller using a 16-bit address decoder on address bits 0..15. Address bits 16..31 must be zero. This bit is used to forward I/O write cycles to the VGA palette registers on a PCI controller. If this bit is set, then the PCI Host Bus Controller and all the PCI to PCI bridges between the PCI Host Bus Controller and the PCI Controller are configured to forward these PCI I/O cycles. This bit may not be combined with EFI_PCI_IO_ATTRIBUTE_VGA_IO or EFI_PCI_IO_ATTRIBUTE_VGA_PALETTE_IO.
EFI_PCI_IO_ATTRIBUTE_VGA_IO_16 If this bit is set, then the PCI I/O cycles in the ranges 0x3B0–0x3BB and 0x3C0–0x3DF are forwarded to the PCI controller using a 16-bit address decoder on address bits 0..15. Address bits 16..31 must be zero. This bit is used to forward I/O cycles for a VGA controller to a PCI controller. If this bit is set, then the PCI Host Bus Controller and all the PCI to PCI bridges between the PCI Host Bus Controller and the PCI Controller are configured to forward these PCI I/O cycles. This bit may not be combined with EFI_PCI_IO_ATTRIBUTE_VGA_IO or EFI_PCI_IO_ATTRIBUTE_VGA_PALETTE_IO. Because EFI_PCI_IO_ATTRIBUTE_VGA_IO_16 also includes the I/O range described by EFI_PCI_IO_ATTRIBUTE_VGA_PALETTE_IO_16, the EFI_PCI_IO_ATTRIBUTE_VGA_PALETTE_IO_16 bit is ignored if EFI_PCI_IO_ATTRIBUTE_VGA_IO_16 is set.
EFI_PCI_IO_ATTRIBUTE_ISA_MOTHERBOARD_IO If this bit is set, then the PCI I/O cycles between 0x00000000 and 0x000000FF are forwarded to the PCI controller. This bit is used to forward I/O cycles for ISA motherboard devices. If this bit is set, then the PCI Host Bus Controller and all the PCI to PCI bridges between the PCI Host Bus Controller and the PCI Controller are configured to forward these PCI I/O cycles.
EFI_PCI_IO_ATTRIBUTE_ISA_IO If this bit is set, then the PCI I/O cycles between 0x100 and 0x3FF are forwarded to the PCI controller using a 10-bit address decoder on address bits 0..9. Address bits 10..15 are not decoded, and address bits 16..31 must be zero. This bit is used to forward I/O cycles for legacy ISA devices. If this bit is set, then the PCI Host Bus Controller and all the PCI to PCI bridges between the PCI Host Bus Controller and the PCI Controller are configured to forward these PCI I/O cycles.
EFI_PCI_IO_ATTRIBUTE_VGA_PALETTE_IO If this bit is set, then the PCI I/O write cycles for 0x3C6, 0x3C8, and 0x3C9 are forwarded to the PCI controller using a 10-bit address decoder on address bits 0..9. Address bits 10..15 are not decoded, and address bits 16..31 must be zero. This bit is used to forward I/O write cycles to the VGA palette registers on a PCI controller. If this bit is set, then the PCI Host Bus Controller and all the PCI to PCI bridges between the PCI Host Bus Controller and the PCI Controller are configured to forward these PCI I/O cycles.
EFI_PCI_IO_ATTRIBUTE_VGA_MEMORY If this bit is set, then the PCI memory cycles between 0xA0000 and 0xBFFFF are forwarded to the PCI controller. This bit is used to forward memory cycles for a VGA frame buffer on a PCI controller. If this bit is set, then the PCI Host Bus Controller and all the PCI to PCI bridges between the PCI Host Bus Controller and the PCI Controller are configured to forward these PCI Memory cycles.
EFI_PCI_IO_ATTRIBUTE_VGA_IO If this bit is set, then the PCI I/O cycles in the ranges 0x3B0-0x3BB and 0x3C0-0x3DF are forwarded to the PCI controller using a 10-bit address decoder on address bits 0..9. Address bits 10..15 are not decoded, and the address bits 16..31 must be zero. This bit is used to forward I/O cycles for a VGA controller to a PCI controller. If this bit is set, then the PCI Host Bus Controller and all the PCI to PCI bridges between the PCI Host Bus Controller and the PCI Controller are configured to forward these PCI I/O cycles. Since EFI_PCI_IO_ATTRIBUTE_VGA_IO also includes the I/O range described by EFI_PCI_IO_ATTRIBUTE_VGA_PALETTE_IO, the EFI_PCI_IO_ATTRIBUTE_VGA_PALETTE_IO bit is ignored if EFI_PCI_IO_ATTRIBUTE_VGA_IO is set.
EFI_PCI_IO_ATTRIBUTE_IDE_PRIMARY_IO If this bit is set, then the PCI I/O cycles in the ranges 0x1F0-0x1F7 and 0x3F6-0x3F7 are forwarded to a PCI controller using a 16-bit address decoder on address bits 0..15. Address bits 16..31 must be zero. This bit is used to forward I/O cycles for a Primary IDE controller to a PCI controller. If this bit is set, then the PCI Host Bus Controller and all the PCI to PCI bridges between the PCI Host Bus Controller and the PCI Controller are configured to forward these PCI I/O cycles.
EFI_PCI_IO_ATTRIBUTE_IDE_SECONDARY_IO If this bit is set, then the PCI I/O cycles in the ranges 0x170-0x177 and 0x376-0x377 are forwarded to a PCI controller using a 16-bit address decoder on address bits 0..15. Address bits 16..31 must be zero. This bit is used to forward I/O cycles for a Secondary IDE controller to a PCI controller. If this bit is set, then the PCI Host Bus Controller and all the PCI to PCI bridges between the PCI Host Bus Controller and the PCI Controller are configured to forward these PCI I/O cycles.
EFI_PCI_IO_ATTRIBUTE_MEMORY_WRITE_COMBINE If this bit is set, then this platform supports changing the attributes of a PCI memory range so that the memory range is accessed in a write combining mode. This bit is used to improve the write performance to a memory buffer on a PCI controller. By default, PCI memory ranges are not accessed in a write combining mode.
EFI_PCI_IO_ATTRIBUTE_MEMORY_CACHED If this bit is set, then this platform supports changing the attributes of a PCI memory range so that the memory range is accessed in a cached mode. By default, PCI memory ranges are accessed noncached.
EFI_PCI_IO_ATTRIBUTE_IO If this bit is set, then the PCI device will decode the PCI I/O cycles that the device is configured to decode.
EFI_PCI_IO_ATTRIBUTE_MEMORY If this bit is set, then the PCI device will decode the PCI Memory cycles that the device is configured to decode.
EFI_PCI_IO_ATTRIBUTE_BUS_MASTER If this bit is set, then the PCI device is allowed to act as a bus master on the PCI bus.
EFI_PCI_IO_ATTRIBUTE_MEMORY_DISABLE If this bit is set, then this platform supports changing the attributes of a PCI memory range so that the memory range is disabled, and can no longer be accessed. By default, all PCI memory ranges are enabled.
EFI_PCI_IO_ATTRIBUTE_EMBEDDED_DEVICE If this bit is set, then the PCI controller is an embedded device that is typically a component on the system board. If this bit is clear, then this PCI controller is part of an adapter that is populating one of the systems PCI slots.
EFI_PCI_IO_ATTRIBUTE_EMBEDDED_ROM If this bit is set, then the PCI option ROM described by the RomImage and RomSize fields is not from ROM BAR of the PCI controller. If this bit is clear, then the RomImage and RomSize fields were initialized based on the PCI option ROM found through the ROM BAR of the PCI controller.
EFI_PCI_IO_ATTRIBUTE_DUAL_ADDRESS_CYCLE If this bit is set, then the PCI controller is capable of producing PCI Dual Address Cycles, so it is able to access a 64-bit address space. If this bit is not set, then the PCI controller is not capable of producing PCI Dual Address Cycles, so it is only able to access a 32-bit address space.

Description

The EFI_PCI_IO_PROTOCOL provides the basic Memory, I/O, PCI configuration, and DMA interfaces that are used to abstract accesses to PCI controllers. There is one EFI_PCI_IO_PROTOCOL instance for each PCI controller on a PCI bus. A device driver that wishes to manage a PCI controller in a system will have to retrieve the EFI_PCI_IO_PROTOCOL instance that is associated with the PCI controller. A device handle for a PCI controller will minimally contain an EFI_DEVICE_PATH_PROTOCOL instance and an EFI_PCI_IO_PROTOCOL instance.

Bus mastering PCI controllers can use the DMA services for DMA operations. There are three basic types of bus mastering DMA that is supported by this protocol. These are DMA reads by a bus master, DMA writes by a bus master, and common buffer DMA. The DMA read and write operations may need to be broken into smaller chunks. The caller of Map() must pay attention to the number of bytes that were mapped, and if required, loop until the entire buffer has been transferred. The following is a list of the different bus mastering DMA operations that are supported, and the sequence of EFI_PCI_IO_PROTOCOL interfaces that are used for each DMA operation type.

DMA Bus Master Read Operation

  • Call Map() for EfiPciIoOperationBusMasterRead.
  • Program the DMA Bus Master with the DeviceAddress returned by Map().
  • Start the DMA Bus Master.
  • Wait for DMA Bus Master to complete the read operation.
  • Call Unmap().

DMA Bus Master Write Operation

  • Call Map() for EfiPciOperationBusMasterWrite.
  • Program the DMA Bus Master with the DeviceAddress returned by Map().
  • Start the DMA Bus Master.
  • Wait for DMA Bus Master to complete the write operation.
  • Perform a PCI controller specific read transaction to flush all PCI write buffers (See PCI Specification Section 3.2.5.2) .
  • Call Flush().
  • Call Unmap().

DMA Bus Master Common Buffer Operation

  • Call AllocateBuffer() to allocate a common buffer.
  • Call Map() for EfiPciIoOperationBusMasterCommonBuffer.
  • Program the DMA Bus Master with the DeviceAddress returned by Map().
  • The common buffer can now be accessed equally by the processor and the DMA bus master.
  • Call Unmap().
  • Call FreeBuffer().

PollMem()

Reads from the memory space of a PCI controller. Returns when either the polling exit criteria is satisfied or after a defined duration.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_POLL_IO_MEM) (
  IN  EFI_PCI_IO_PROTOCOL        *This,
  IN  EFI_PCI_IO_PROTOCOL_WIDTH  Width,
  IN  UINT8                      BarIndex,
  IN  UINT64                     Offset,
  IN  UINT64                     Mask,
  IN  UINT64                     Value,
  IN  UINT64                     Delay,
  OUT UINT64                     *Result
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
Width Signifies the width of the memory operations.
BarIndex The BAR index of the standard PCI Configuration header to use as the base address for the memory operation to perform. This allows all drivers to use BAR relative addressing. The legal range for this field is 0..5. However, the value EFI_PCI_IO_PASS_THROUGH_BAR can be used to bypass the BAR relative addressing and pass Offset to the PCI Root Bridge I/O Protocol unchanged.
Offset The offset within the selected BAR to start the memory operation.
Mask Mask used for the polling criteria. Bytes above Width in Mask are ignored. The bits in the bytes below Width which are zero in Mask are ignored when polling the memory address.
Value The comparison value used for the polling exit criteria.
Delay The number of 100 ns units to poll. Note that timer available may be of poorer granularity.
Result Pointer to the last value read from the memory location.

Description
This function provides a standard way to poll a PCI memory location. A PCI memory read operation is performed at the PCI memory address specified by BarIndex and Offset for the width specified by Width. The result of this PCI memory read operation is stored in Result. This PCI memory read operation is repeated until either a timeout of Delay 100 ns units has expired, or (Result & Mask) is equal to Value.

This function will always perform at least one memory access no matter how small Delay may be. If Delay is 0, then Result will be returned with a status of EFI_SUCCESS even if Result does not match the exit criteria. If Delay expires, then EFI_TIMEOUT is returned.

If Width is not EfiPciIoWidthUint8, EfiPciIoWidthUint16, EfiPciIoWidthUint32, or EfiPciIoWidthUint64, then EFI_INVALID_PARAMETER is returned.

The memory operations are carried out exactly as requested. The caller is responsible for satisfying any alignment and memory width restrictions that a PCI controller on a platform might require. For example on some platforms, width requests of EfiPciIoWidthUint64 do not work.

All the PCI transactions generated by this function are guaranteed to be completed before this function returns. However, if the memory mapped I/O region being accessed by this function has the EFI_PCI_ATTRIBUTE_MEMORY_CACHED attribute set, then the transactions will follow the ordering rules defined by the processor architecture.

Status Codes Returned

Status Code Description
EFI_SUCCESS The last data returned from the access matched the poll exit criteria.
EFI_INVALID_PARAMETER Width is invalid.
EFI_INVALID_PARAMETER Result is NULL.
EFI_UNSUPPORTED BarIndex not valid for this PCI controller.
EFI_UNSUPPORTED Offset is not valid for the BarIndex of this PCI controller.
EFI_TIMEOUT Delay expired before a match occurred.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

PollIo()

Reads from the I/O space of a PCI controller. Returns when either the polling exit criteria is satisfied or after a defined duration.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_POLL_IO_MEM) (
  IN  EFI_PCI_IO_PROTOCOL        *This,
  IN  EFI_PCI_IO_PROTOCOL_WIDTH  Width,
  IN  UINT8                      BarIndex,
  IN  UINT64                     Offset,
  IN  UINT64                     Mask,
  IN  UINT64                     Value,
  IN  UINT64                     Delay,
  OUT UINT64                     *Result
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
Width Signifies the width of the I/O operations.
BarIndex The BAR index of the standard PCI Configuration header to use as the base address for the I/O operation to perform. This allows all drivers to use BAR relative addressing. The legal range for this field is 0..5. However, the value EFI_PCI_IO_PASS_THROUGH_BAR can be used to bypass the BAR relative addressing and pass Offset to the PCI Root Bridge I/O Protocol unchanged.
Offset The offset within the selected BAR to start the I/O operation.
Mask Mask used for the polling criteria. Bytes above Width in Mask are ignored. The bits in the bytes below Width which are zero in Mask are ignored when polling the I/O address.
Value The comparison value used for the polling exit criteria.
Delay The number of 100 ns units to poll. Note that timer available may be of poorer granularity.
Result Pointer to the last value read from the memory location.

Description
This function provides a standard way to poll a PCI I/O location. A PCI I/O read operation is performed at the PCI I/O address specified by BarIndex and Offset for the width specified by Width. The result of this PCI I/O read operation is stored in Result. This PCI I/O read operation is repeated until either a timeout of Delay 100 ns units has expired, or (Result & Mask) is equal to Value.

This function will always perform at least one I/O access no matter how small Delay may be. If Delay is 0, then Result will be returned with a status of EFI_SUCCESS even if Result does not match the exit criteria. If Delay expires, then EFI_TIMEOUT is returned.

If Width is not EfiPciIoWidthUint8, EfiPciIoWidthUint16, EfiPciIoWidthUint32, or EfiPciIoWidthUint64, then EFI_INVALID_PARAMETER is returned.

The I/O operations are carried out exactly as requested. The caller is responsible satisfying any alignment and I/O width restrictions that the PCI controller on a platform might require. For example on some platforms, width requests of EfiPciIoWidthUint64 do not work.

All the PCI read transactions generated by this function are guaranteed to be completed before this function returns.

Status Codes Returned

Status Code Description
EFI_SUCCESS The last data returned from the access matched the poll exit criteria.
EFI_INVALID_PARAMETER Width is invalid.
EFI_INVALID_PARAMETER Result is NULL.
EFI_UNSUPPORTED BarIndex not valid for this PCI controller.
EFI_UNSUPPORTED Offset is not valid for the PCI BAR specified by BarIndex.
EFI_TIMEOUT Delay expired before a match occurred.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

Mem()

Mem.Read()

Mem.Write()

Enable a PCI driver to access PCI controller registers in the PCI memory space.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_MEM) (
  IN     EFI_PCI_IO_PROTOCOL       *This,
  IN     EFI_PCI_IO_PROTOCOL_WIDTH Width,
  IN     UINT8                     BarIndex,
  IN     UINT64                    Offset,
  IN     UINTN                     Count,
  IN OUT VOID                      *Buffer
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
Width Signifies the width of the memory operations.
BarIndex The BAR index of the standard PCI Configuration header to use as the base address for the memory operation to perform. This allows all drivers to use BAR relative addressing. The legal range for this field is 0..5. However, the value EFI_PCI_IO_PASS_THROUGH_BAR can be used to bypass the BAR relative addressing and pass Offset to the PCI Root Bridge I/O Protocol unchanged.
Offset The offset within the selected BAR to start the memory operation.
Count The number of memory operations to perform. Bytes moved is Width size * Count, starting at Offset.
Buffer For read operations, the destination buffer to store the results. For write operations, the source buffer to write data from.

Description
The Mem.Read(), and Mem.Write() functions enable a driver to access controller registers in the PCI memory space.

The I/O operations are carried out exactly as requested. The caller is responsible for any alignment and I/O width issues which the bus, device, platform, or type of I/O might require. For example on some platforms, width requests of EfiPciIoWidthUint64 do not work.

If Width is EfiPciIoWidthUint8, EfiPciIoWidthUint16, EfiPciIoWidthUint32, or EfiPciIoWidthUint64, then both Address and Buffer are incremented for each of the Count operations performed.

If Width is EfiPciIoWidthFifoUint8, EfiPciIoWidthFifoUint16, EfiPciIoWidthFifoUint32, or EfiPciIoWidthFifoUint64, then only Buffer is incremented for each of the Count operations performed. The read or write operation is performed Count times on the same Address.

If Width is EfiPciIoWidthFillUint8, EfiPciIoWidthFillUint16, EfiPciIoWidthFillUint32, or EfiPciIoWidthFillUint64, then only Address is incremented for each of the Count operations performed. The read or write operation is performed Count times from the first element of Buffer.

All the PCI transactions generated by this function are guaranteed to be completed before this function returns. All the PCI write transactions generated by this function will follow the write ordering and completion rules defined in the PCI Specification. However, if the memory-mapped I/O region being accessed by this function has the EFI_PCI_ATTRIBUTE_MEMORY_CACHED attribute set, then the transactions will follow the ordering rules defined by the processor architecture.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was read from or written to the PCI controller.
EFI_INVALID_PARAMETER Width is invalid.
EFI_INVALID_PARAMETER Buffer is NULL.
EFI_UNSUPPORTED BarIndex not valid for this PCI controller.
EFI_UNSUPPORTED The address range specified by Offset, Width, and Count is not valid for the PCI BAR specified by BarIndex.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

Io()

Io.Read()

Io.Write()

Enable a PCI driver to access PCI controller registers in the PCI I/O space.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_MEM) (
  IN     EFI_PCI_IO_PROTOCOL       *This,
  IN     EFI_PCI_IO_PROTOCOL_WIDTH Width,
  IN     UINT8                     BarIndex,
  IN     UINT64                    Offset,
  IN     UINTN                     Count,
  IN OUT VOID                      *Buffer
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
Width Signifies the width of the memory operations.
BarIndex The BAR index in the standard PCI Configuration header to use as the base address for the I/O operation to perform. This allows all drivers to use BAR relative addressing. The legal range for this field is 0..5. However, the value EFI_PCI_IO_PASS_THROUGH_BAR can be used to bypass the BAR relative addressing and pass Offset to the PCI Root Bridge I/O Protocol unchanged.
Offset The offset within the selected BAR to start the I/O operation.
Count The number of I/O operations to perform. Bytes moved is Width size * Count, starting at Offset.
Buffer For read operations, the destination buffer to store the results. For write operations, the source buffer to write data from.


Description
The Io.Read(), and Io.Write() functions enable a driver to access PCI controller registers in PCI I/O space.

The I/O operations are carried out exactly as requested. The caller is responsible for any alignment and I/O width issues which the bus, device, platform, or type of I/O might require. For example on some platforms, width requests of EfiPciIoWidthUint64 do not work.

If Width is EfiPciIoWidthUint8, EfiPciIoWidthUint16, EfiPciIoWidthUint32, or EfiPciIoWidthUint64, then both Address and Buffer are incremented for each of the Count operations performed.

If Width is EfiPciIoWidthFifoUint8, EfiPciIoWidthFifoUint16, EfiPciIoWidthFifoUint32, or EfiPciIoWidthFifoUint64, then only Buffer is incremented for each of the Count operations performed. The read or write operation is performed Count times on the same Address.

If Width is EfiPciIoWidthFillUint8, EfiPciIoWidthFillUint16, EfiPciIoWidthFillUint32, or EfiPciIoWidthFillUint64, then only Address is incremented for each of the Count operations performed. The read or write operation is performed Count times from the first element of Buffer.

All the PCI transactions generated by this function are guaranteed to be completed before this function returns.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was read from or written to the PCI controller.
EFI_INVALID_PARAMETER Width is invalid.
EFI_INVALID_PARAMETER Buffer is NULL.
EFI_UNSUPPORTED BarIndex not valid for this PCI controller.
EFI_UNSUPPORTED The address range specified by Offset, Width, and Count is not valid for the PCI BAR specified by BarIndex.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

Pci()

Pci.Read()

Pci.Write()

Enable a PCI driver to access PCI controller registers in PCI configuration space.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_CONFIG) (
  IN     EFI_PCI_IO_PROTOCOL       *This,
  IN     EFI_PCI_IO_PROTOCOL_WIDTH Width,
  IN     UINT32                    Offset,
  IN     UINTN                     Count,
  IN OUT VOID                      *Buffer
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
Width Signifies the width of the memory operations.
Offset The offset within the PCI configuration space for the PCI controller.
Count The number of PCI configuration operations to perform. Bytes moved is Width size * Count, starting at Offset.
Buffer For read operations, the destination buffer to store the results. For write operations, the source buffer to write data from.

Description
The Pci.Read() and Pci.Write() functions enable a driver to access PCI configuration registers for the PCI controller.

The PCI Configuration operations are carried out exactly as requested. The caller is responsible for any alignment and I/O width issues which the bus, device, platform, or type of I/O might require. For example on some platforms, width requests of EfiPciIoWidthUint64 do not work.

If Width is EfiPciIoWidthUint8, EfiPciIoWidthUint16, EfiPciIoWidthUint32, or EfiPciIoWidthUint64, then both Address and Buffer are incremented for each of the Count operations performed.

If Width is EfiPciIoWidthFifoUint8, EfiPciIoWidthFifoUint16, EfiPciIoWidthFifoUint32, or EfiPciIoWidthFifoUint64, then only Buffer is incremented for each of the Count operations performed. The read or write operation is performed Count times on the same Address.

If Width is EfiPciIoWidthFillUint8, EfiPciIoWidthFillUint16, EfiPciIoWidthFillUint32, or EfiPciIoWidthFillUint64, then only Address is incremented for each of the Count operations performed. The read or write operation is performed Count times from the first element of Buffer.

All the PCI transactions generated by this function are guaranteed to be completed before this function returns.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was read from or written to the PCI controller.
EFI_INVALID_PARAMETER Width is invalid.
EFI_INVALID_PARAMETER Buffer is NULL.
EFI_UNSUPPORTED The address range specified by Offset, Width, and Count is not valid for the PCI configuration header of the PCI controller.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

CopyMem()

Enables a PCI driver to copy one region of PCI memory space to another region of PCI memory space.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_COPY_MEM) (
  IN EFI_PCI_IO_PROTOCOL       *This,
  IN EFI_PCI_IO_PROTOCOL_WIDTH Width,
  IN UINT8                     DestBarIndex,
  IN UINT64                    DestOffset,
  IN UINT8                     SrcBarIndex,
  IN UINT64                    SrcOffset,
  IN UINTN                     Count
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
Width Signifies the width of the memory operations.
DestBarIndex The BAR index in the standard PCI Configuration header to use as the base address for the memory operation to perform. This allows all drivers to use BAR relative addressing. The legal range for this field is 0..5. However, the value EFI_PCI_IO_PASS_THROUGH_BAR can be used to bypass the BAR relative addressing and pass Offset to the PCI Root Bridge I/O Protocol unchanged.
DestOffset The destination offset within the BAR specified by DestBarIndex to start the memory writes for the copy operation. The caller is responsible for aligning the DestOffset if required.
SrcBarIndex The BAR index in the standard PCI Configuration header to use as the base address for the memory operation to perform. This allows all drivers to use BAR relative addressing. The legal range for this field is 0..5. However, the value EFI_PCI_IO_PASS_THROUGH_BAR can be used to bypass the BAR relative addressing and pass Offset to the PCI Root Bridge I/O Protocol unchanged.
SrcOffset The source offset within the BAR specified by SrcBarIndex to start the memory reads for the copy operation. The caller is responsible for aligning the SrcOffset if required.
Count The number of memory operations to perform. Bytes moved is Width size * Count, starting at DestOffset and SrcOffset.

Description
The CopyMem() function enables a PCI driver to copy one region of PCI memory space to another region of PCI memory space on a PCI controller. This is especially useful for video scroll operations on a memory mapped video buffer.

The memory operations are carried out exactly as requested. The caller is responsible for satisfying any alignment and memory width restrictions that a PCI controller on a platform might require. For example on some platforms, width requests of EfiPciIoWidthUint64 do not work.

If Width is EfiPciWidthUint8, EfiPciWidthUint16, EfiPciWidthUint32, or EfiPciWidthUint64, then Count read/write transactions are performed to move the contents of the SrcOffset buffer to the DestOffset buffer. The implementation must be reentrant, and it must handle overlapping SrcOffset and DestOffset buffers. This means that the implementation of CopyMem() must choose the correct direction of the copy operation based on the type of overlap that exists between the SrcOffset and DestOffset buffers. If either the SrcOffset buffer or the DestOffset buffer crosses the top of the processor’s address space, then the result of the copy operation is unpredictable.

The contents of the DestOffset buffer on exit from this service must match the contents of the SrcOffset buffer on entry to this service. Due to potential overlaps, the contents of the SrcOffset buffer may be modified by this service. The following rules can be used to guarantee the correct behavior:

  • If DestOffset > SrcOffset and DestOffset < (SrcOffset + Width size * Count), then the data should be copied from the SrcOffset buffer to the DestOffset buffer starting from the end of buffers and working toward the beginning of the buffers.
  • Otherwise, the data should be copied from the SrcOffset buffer to the DestOffset buffer starting from the beginning of the buffers and working toward the end of the buffers.

All the PCI transactions generated by this function are guaranteed to be completed before this function returns. All the PCI write transactions generated by this function will follow the write ordering and completion rules defined in the PCI Specification. However, if the memory-mapped I/O region being accessed by this function has the EFI_PCI_ATTRIBUTE_MEMORY_CACHED attribute set, then the transactions will follow the ordering rules defined by the processor architecture.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was copied from one memory region to another memory region.
EFI_INVALID_PARAMETER Width is invalid.
EFI_UNSUPPORTED DestBarIndex not valid for this PCI controller.
EFI_UNSUPPORTED SrcBarIndex not valid for this PCI controller.
EFI_UNSUPPORTED The address range specified by DestOffset, Width, and Count is not valid for the PCI BAR specified by DestBarIndex.
EFI_UNSUPPORTED The address range specified by SrcOffset, Width, and Count is not valid for the PCI BAR specified by SrcBarIndex.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

Map()

Provides the PCI controller–specific addresses needed to access system memory.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_MAP) (
  IN     EFI_PCI_IO_PROTOCOL           *This,
  IN     EFI_PCI_IO_PROTOCOL_OPERATION Operation,
  IN     VOID                          *HostAddress,
  IN OUT UINTN                         *NumberOfBytes,
  OUT    EFI_PHYSICAL_ADDRESS          *DeviceAddress,
  OUT    VOID                          **Mapping
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
Operation Indicates if the bus master is going to read or write to system memory.
HostAddress The system memory address to map to the PCI controller.
NumberOfBytes On input the number of bytes to map. On output the number of bytes that were mapped.
DeviceAddress The resulting map address for the bus master PCI controller to use to access the hosts HostAddress. This address cannot be used by the processor to access the contents of the buffer specified by HostAddress.
Mapping A resulting value to pass to Unmap().

Description
The Map() function provides the PCI controller–specific addresses needed to access system memory. This function is used to map system memory for PCI bus master DMA accesses.

All PCI bus master accesses must be performed through their mapped addresses and such mappings must be freed with Unmap() when complete. If the bus master access is a single read or write data transfer, then EfiPciIoOperationBusMasterRead or EfiPciIoOperation-BusMasterWrite is used and the range is unmapped to complete the operation. If performing an EfiPciIoOperationBusMasterRead operation, all the data must be present in system memory before the Map() is performed. Similarly, if performing an EfiPciIoOperation-BusMasterWrite, the data cannot be properly accessed in system memory until Unmap() is performed.

Bus master operations that require both read and write access or require multiple host device interactions within the same mapped region must use EfiPciIoOperation-BusMasterCommonBuffer. However, only memory allocated via the AllocateBuffer() interface can be mapped for this operation type.

In all mapping requests the resulting NumberOfBytes actually mapped may be less than the requested amount. In this case, the DMA operation will have to be broken up into smaller chunks. The Map() function will map as much of the DMA operation as it can at one time. The caller may have to loop on Map() and Unmap() in order to complete a large DMA transfer.

Status Codes Returned

Status Code Description
EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
EFI_INVALID_PARAMETER Operation is invalid.
EFI_INVALID_PARAMETER HostAddress is NULL.
EFI_INVALID_PARAMETER NumberOfBytes is NULL.
EFI_INVALID_PARAMETER DeviceAddress is NULL.
EFI_INVALID_PARAMETER Mapping is NULL.
EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
EFI_DEVICE_ERROR The system hardware could not map the requested address.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

Unmap()

Completes the Map() operation and releases any corresponding resources.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_UNMAP) (
  IN EFI_PCI_IO_PROTOCOL *This,
  IN VOID                *Mapping
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
Mapping The mapping value returned from Map().

Description
The Unmap() function completes the Map() operation and releases any corresponding resources. If the operation was an EfiPciIoOperationBusMasterWrite, the data is committed to the target system memory. Any resources used for the mapping are freed.

Status Codes Returned

Status Code Description
EFI_SUCCESS The range was unmapped.
EFI_DEVICE_ERROR The data was not committed to the target system memory.

AllocateBuffer()

Allocates pages that are suitable for an EfiPciIoOperationBusMasterCommonBuffer mapping.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_ALLOCATE_BUFFER) (
  IN  EFI_PCI_IO_PROTOCOL  *This,
  IN  EFI_ALLOCATE_TYPE    Type,
  IN  EFI_MEMORY_TYPE      MemoryType,
  IN  UINTN                Pages,
  OUT VOID                 **HostAddress,
  IN  UINT64               Attributes
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
Type This parameter is not used and must be ignored.
MemoryType The type of memory to allocate, EfiBootServicesData or EfiRuntimeServicesData.
Pages The number of pages to allocate.
HostAddress A pointer to store the base system memory address of the allocated range.
Attributes The requested bit mask of attributes for the allocated range. Only the attributes EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE, and EFI_PCI_ATTRIBUTE_MEMORY_CACHED may be used with this function. If any other bits are set, then EFI_UNSUPPORTED is returned. This function may choose to ignore this bit mask. The EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE, and EFI_PCI_ATTRIBUTE_MEMORY_CACHED attributes provide a hint to the implementation that may improve the performance of the calling driver. The implementation may choose any default for the memory attributes including write combining, cached, both, or neither as long as the allocated buffer can be seen equally by both the processor and the PCI bus master.

Description
The AllocateBuffer() function allocates pages that are suitable for an EfiPciIoOperationBusMasterCommonBuffer mapping. This means that the buffer allocated by this function must support simultaneous access by both the processor and a PCI Bus Master. The device address that the PCI Bus Master uses to access the buffer can be retrieved with a call to Map().

If the current attributes of the PCI controller has the EFI_PCI_IO_ATTRIBUTE_DUAL_ ADDRESS_CYCLE bit set, then when the buffer allocated by this function is mapped with a call to Map(), the device address that is returned by Map() must be within the 64-bit device address space of the PCI Bus Master. The attributes for a PCI controller can be managed by calling Attributes().

If the current attributes for the PCI controller has the EFI_PCI_IO_ATTRIBUTE_DUAL_ ADDRESS_CYCLE bit clear, then when the buffer allocated by this function is mapped with a call to Map(), the device address that is returned by Map() must be within the 32-bit device address space of the PCI Bus Master. The attributes for a PCI controller can be managed by calling Attributes().

If the memory allocation specified by MemoryType and Pages cannot be satisfied, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The requested memory pages were allocated.
EFI_INVALID_PARAMETER MemoryType is invalid.
EFI_INVALID_PARAMETER HostAddress is NULL.
EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are MEMORY_WRITE_COMBINE and MEMORY_CACHED.
EFI_OUT_OF_RESOURCES The memory pages could not be allocated.

FreeBuffer()

Frees memory that was allocated with AllocateBuffer() .

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_FREE_BUFFER) (
  IN EFI_PCI_IO_PROTOCOL *This,
  IN UINTN               Pages,
  IN VOID                *HostAddress
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
Pages The number of pages to free.
HostAddress The base system memory address of the allocated range.

Description
The FreeBuffer() function frees memory that was allocated with AllocateBuffer().

Status Codes Returned

Status Code Description
EFI_SUCCESS The requested memory pages were freed.
EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages was not allocated with AllocateBuffer().

Flush()

Flushes all PCI posted write transactions from a PCI host bridge to system memory.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_FLUSH) (
  IN EFI_PCI_IO_PROTOCOL *This
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.

Description
The Flush() function flushes any PCI posted write transactions from a PCI host bridge to system memory. Posted write transactions are generated by PCI bus masters when they perform write transactions to target addresses in system memory.

This function does not flush posted write transactions from any PCI bridges. A PCI controller specific action must be taken to guarantee that the posted write transactions have been flushed from the PCI controller and from all the PCI bridges into the PCI host bridge. This is typically done with a PCI read transaction from the PCI controller prior to calling Flush().

If the PCI controller specific action required to flush the PCI posted write transactions has been performed, and this function returns EFI_SUCCESS, then the PCI bus master’s view and the processor’s view of system memory are guaranteed to be coherent. If the PCI posted write transactions cannot be flushed from the PCI host bridge, then the PCI bus master and processor are not guaranteed to have a coherent view of system memory, and EFI_DEVICE_ERROR is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The PCI posted write transactions were flushed from the PCI host bridge to system memory.
EFI_DEVICE_ERROR The PCI posted write transactions were not flushed from the PCI host bridge due to a hardware error.

GetLocation()

Retrieves this PCI controller’s current PCI bus number, device number, and function number.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_GET_LOCATION) (
  IN EFI_PCI_IO_PROTOCOL *This,
  OUT UINTN                  *SegmentNumber,
  OUT UINTN                  *BusNumber,
  OUT UINTN                  *DeviceNumber,
  OUT UINTN                  *FunctionNumber
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
SegmentNumber The PCI controller’s current PCI segment number.
BusNumber The PCI controller’s current PCI bus number.
DeviceNumber The PCI controller’s current PCI device number.
FunctionNumber The PCI controller’s current PCI function number.

Description
The GetLocation() function retrieves a PCI controller’s current location on a PCI Host Bridge. This is specified by a PCI segment number, PCI bus number, PCI device number, and PCI function number. These values can be used with the PCI Root Bridge I/O Protocol to perform PCI configuration cycles on the PCI controller, or any of its peer PCI controller’s on the same PCI Host Bridge.

Status Codes Returned

Status Code Description
EFI_SUCCESS The PCI controller location was returned.
EFI_INVALID_PARAMETER SegmentNumber is NULL.
EFI_INVALID_PARAMETER BusNumber is NULL.
EFI_INVALID_PARAMETER DeviceNumber is NULL.
EFI_INVALID_PARAMETER FunctionNumber is NULL.


Attributes()

Performs an operation on the attributes that this PCI controller supports. The operations include getting the set of supported attributes, retrieving the current attributes, setting the current attributes, enabling attributes, and disabling attributes.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_ATTRIBUTES) (
  IN  EFI_PCI_IO_PROTOCOL                     *This,
  IN  EFI_PCI_IO_PROTOCOL_ATTRIBUTE_OPERATION Operation,
  IN  UINT64                                  Attributes,
  OUT UINT64                                  *Result OPTIONAL
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
Operation The operation to perform on the attributes for this PCI controller.
Attributes -
Result A pointer to the result mask of attributes that are returned for the Get and Supported operations. This is an optional parameter that may be NULL for the Set, Enable, and Disable operations.

Description
The Attributes() function performs an operation on the attributes associated with this PCI controller. If Operation is greater than or equal to the maximum operation value, then EFI_INVALID_PARAMETER is returned. If Operation is Get or Supported, and Result is NULL, then EFI_INVALID_PARAMETER is returned. If Operation is Set, Enable, or Disable for an attribute that is not supported by the PCI controller, then EFI_UNSUPPORTED is returned. Otherwise, the operation is performed as described in “Related Definitions” and EFI_SUCCESS is returned. It is possible for this function to return EFI_UNSUPPORTED even if the PCI controller supports the attribute. This can occur when the PCI root bridge does not support the attribute. For example, if VGA I/O and VGA Memory transactions cannot be forwarded onto PCI root bridge #2, then a request by a PCI VGA driver to enable the VGA_IO and VGA_MEMORY bits will fail even though a PCI VGA controller behind PCI root bridge #2 is able to decode these transactions.

This function will also return EFI_UNSUPPORTED if more than one PCI controller on the same PCI root bridge has already successfully requested one of the ISA addressing attributes. For example, if one PCI VGA controller had already requested the VGA_IO and VGA_MEMORY attributes, then a second PCI VGA controller on the same root bridge cannot succeed in requesting those same attributes. This restriction applies to the ISA-, VGA-, and IDE-related attributes.

Status Codes Returned

Status Code Description
EFI_SUCCESS The operation on the PCI controller's attributes was completed. If the operation was Get or Supported, then the attribute mask is returned in Result.
EFI_INVALID_PARAMETER Operation is greater than or equal to EfiPciIoAttributeOperationMaximum.
EFI_INVALID_PARAMETER Operation is Get and Result is NULL.
EFI_INVALID_PARAMETER Operation is Supported and Result is NULL.
EFI_UNSUPPORTED Operation is Set, and one or more of the bits set in Attributes are not supported by this PCI controller or one of its parent bridges.
EFI_UNSUPPORTED Operation is Enable, and one or more of the bits set in Attributes are not supported by this PCI controller or one of its parent bridges.
EFI_UNSUPPORTED Operation is Disable, and one or more of the bits set in Attributes are not supported by this PCI controller or one of its parent bridges.

GetBarAttributes()

Gets the attributes that this PCI controller supports setting on a BAR using SetBarAttributes(), and retrieves the list of resource descriptors for a BAR.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_GET_BAR_ATTRIBUTES) (
  IN  EFI_PCI_IO_PROTOCOL *This,
  IN  UINT8               BarIndex,
  OUT UINT64              *Supports OPTIONAL,
  OUT VOID                **Resources OPTIONAL
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
BarIndex The BAR index of the standard PCI Configuration header to use as the base address for resource range. The legal range for this field is 0..5.
Supports A pointer to the mask of attributes that this PCI controller supports setting for this BAR with SetBarAttributes(). The list of attributes is listed in Section 13.4. This is an optional parameter that may be NULL.
Resources A pointer to the ACPI 2.0 resource descriptors that describe the current configuration of this BAR of the PCI controller. This buffer is allocated for the caller with the Boot Service AllocatePool(). It is the caller’s responsibility to free the buffer with the Boot Service FreePool(). This is an optional parameter that may be NULL.

Description
The GetBarAttributes() function returns in Supports the mask of attributes that the PCI controller supports setting for the BAR specified by BarIndex. It also returns in Resources a list of ACPI 2.0 resource descriptors for the BAR specified by BarIndex. Both Supports and Resources are optional parameters. If both Supports and Resources are NULL, then EFI_INVALID_PARAMETER is returned. It is the caller’s responsibility to free Resources with the Boot Service FreePool() when the caller is done with the contents of Resources. If there are not enough resources to allocate Resources, then EFI_OUT_OF_RESOURCES is returned.

If a bit is set in Supports, then the PCI controller supports this attribute type for the BAR specified by BarIndex, and a call can be made to SetBarAttributes() using that attribute type.

Status Codes Returned

Status Code Description
EFI_SUCCESS If Supports is not NULL, then the attributes that the PCI controller supports are returned in Supports. If Resources is not NULL, then the ACPI 2.0 resource descriptors that the PCI controller is currently using are returned in Resources.
EFI_OUT_OF_RESOURCES There are not enough resources available to allocate Resources.
EFI_UNSUPPORTED BarIndex not valid for this PCI controller.
EFI_INVALID_PARAMETER Both Supports and Attributes are NULL.

SetBarAttributes()

Sets the attributes for a range of a BAR on a PCI controller.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_IO_PROTOCOL_SET_BAR_ATTRIBUTES) (
  IN     EFI_PCI_IO_PROTOCOL *This,
  IN     UINT64              Attributes,
  IN     UINT8               BarIndex,
  IN OUT UINT64              *Offset,
  IN OUT UINT64              *Length
  );

Parameters

Parameters Description
This A pointer to the EFI_PCI_IO_PROTOCOL instance.
Attributes The mask of attributes to set for the resource range specified by BarIndex, Offset, and Length.
BarIndex The BAR index of the standard PCI Configuration header to use as the base address for the resource range. The legal range for this field is 0..5.
Offset A pointer to the BAR relative base address of the resource range to be modified by the attributes specified by Attributes. On return, *Offset will be set to the actual base address of the resource range. Not all resources can be set to a byte boundary, so the actual base address may differ from the one passed in by the caller.
Length A pointer to the length of the resource range to be modified by the attributes specified by Attributes. On return, *Length will be set to the actual length of the resource range. Not all resources can be set to a byte boundary, so the actual length may differ from the one passed in by the caller.

Description
The SetBarAttributes() function sets the attributes specified in Attributes for the PCI controller on the resource range specified by BarIndex, Offset, and Length. Since the granularity of setting these attributes may vary from resource type to resource type, and from platform to platform, the actual resource range and the one passed in by the caller may differ. As a result, this function may set the attributes specified by Attributes on a larger resource range than the caller requested. The actual range is returned in Offset and Length. The caller is responsible for verifying that the actual range for which the attributes were set is acceptable.

If the attributes are set on the PCI controller, then the actual resource range is returned in Offset and Length, and EFI_SUCCESS is returned. Many of the attribute types also require that the state of the PCI Host Bus Controller and the state of any PCI to PCI bridges between the PCI Host Bus Controller and the PCI Controller to be modified. This function will only return EFI_SUCCESS is all of these state changes are made. The PCI Controller may support a combination of attributes, but unless the PCI Host Bus Controller and the PCI to PCI bridges also support that same combination of attributes, then this call will return an error.

If the attributes specified by Attributes, or the resource range specified by BarIndex, Offset, and Length are not supported by the PCI controller, then EFI_UNSUPPORTED is returned. The set of supported attributes for the PCI controller can be found by calling GetBarAttributes().

If either Offset or Length is NULL then EFI_INVALID_PARAMETER is returned.

If there are not enough resources available to set the attributes, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The set of attributes specified by Attributes for the resource range specified by BarIndex, Offset, and Length were set on the PCI controller, and the actual resource range is returned in Offset and Length.
EFI_UNSUPPORTED The set of attributes specified by Attributes is not supported by the PCI controller for the resource range specified by BarIndex, Offset, and Length.
EFI_INVALID_PARAMETER Offset is NULL.
EFI_INVALID_PARAMETER Length is NULL.
EFI_OUT_OF_RESOURCES There are not enough resources to set the attributes on the resource range specified by BarIndex, Offset, and Length.

Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.

Personal tools