EFI PCI ROOT BRIDGE IO PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Provides the basic Memory, I/O, PCI configuration, and DMA interfaces that are used to abstract accesses to PCI controllers behind a PCI Root Bridge Controller.

Contents

GUID

#define EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID \
  {0x2F707EBB,0x4A1A,0x11d4,0x9A,0x38,0x00,0x90,0x27,0x3F,0xC1,0x4D}

Protocol Interface Structure

#include EFI_PCI_CONSUMER(PciRootBridgeIo)

extern EFI_GUID gEfiPciRootBridgeIoProtocolGuid;
typedef struct _EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL {
  EFI_HANDLE                                      ParentHandle;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM     PollMem;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM     PollIo;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS          Mem;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS          Io;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS          Pci;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_COPY_MEM        CopyMem;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_MAP             Map;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_UNMAP           Unmap;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ALLOCATE_BUFFER AllocateBuffer;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FREE_BUFFER     FreeBuffer;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FLUSH           Flush;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GET_ATTRIBUTES  GetAttributes;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_SET_ATTRIBUTES  SetAttributes;
  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION   Configuration;
  UINT32                                          SegmentNumber;
} EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL;

Parameters

Parameter Description
ParentHandle The EFI_HANDLE of the PCI Host Bridge of which this PCI Root Bridge is a member.
PollMem Polls an address in memory mapped I/O space until an exit condition is met, or a timeout occurs.
PollIo Polls an address in I/O space until an exit condition is met, or a timeout occurs.
Mem.Read Allows reads from memory mapped I/O space.
Mem.Write Allows writes to memory mapped I/O space.
Io.Read Allows reads from I/O space.
Io.Write Allows writes to I/O space.
Pci.Read Allows reads from PCI configuration space.
Pci.Write Allows writes to PCI configuration space.
CopyMem Allows one region of PCI root bridge memory space to be copied to another region of PCI root bridge memory space.
Map Provides the PCI controller–specific addresses 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 Free pages that were allocated with AllocateBuffer().
Flush Flushes all PCI posted write transactions to system memory.
GetAttributes Gets the attributes that a PCI root bridge supports setting with SetAttributes(), and the attributes that a PCI root bridge is currently using.
SetAttributes Sets attributes for a resource range on a PCI root bridge.
Configuration Gets the current resource settings for this PCI root bridge.
SegmentNumber The segment number that this PCI root bridge resides.

Related Definitions

#define EFI_PCI_ATTRIBUTE_ISA_MOTHERBOARD_IO   0x0001
#define EFI_PCI_ATTRIBUTE_ISA_IO               0x0002
#define EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO       0x0004
#define EFI_PCI_ATTRIBUTE_VGA_MEMORY           0x0008
#define EFI_PCI_ATTRIBUTE_VGA_IO               0x0010
#define EFI_PCI_ATTRIBUTE_IDE_PRIMARY_IO       0x0020
#define EFI_PCI_ATTRIBUTE_IDE_SECONDARY_IO     0x0040
#define EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE 0x0080
#define EFI_PCI_ATTRIBUTE_MEMORY_CACHED        0x0800
#define EFI_PCI_ATTRIBUTE_MEMORY_DISABLE       0x1000
#define EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE   0x8000
#define EFI_PCI_ATTRIBUTE_ISA_IO_16            0x10000
#define EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO_16    0x20000
#define EFI_PCI_ATTRIBUTE_VGA_IO_16            0x40000
Attribute Description
EFI_PCI_ATTRIBUTE_ISA_IO_16 If this bit is set, then the PCI I/O cycles between 0x100 and 0x3FF are forwarded onto a PCI root bridge 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 onto a PCI root bridge. This bit may not be combined with EFI_PCI_ATTRIBUTE_ISA_IO.
EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO_16 If this bit is set, then the PCI I/O write cycles for 0x3C6, 0x3C8, and 0x3C9 are forwarded onto a PCI root bridge 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 onto a PCI root bridge. This bit may not be combined with EFI_PCI_ATTRIBUTE_VGA_IO or EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO.
EFI_PCI_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 onto a PCI root bridge 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 onto a PCI root bridge. This bit may not be combined with EFI_PCI_ATTRIBUTE_VGA_IO or EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO. Because EFI_PCI_ATTRIBUTE_VGA_IO_16 also includes the I/O range described by EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO_16, the EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO_16 bit is ignored if EFI_PCI_ATTRIBUTE_VGA_IO_16 is set.
EFI_PCI_ATTRIBUTE_ISA_MOTHERBOARD_IO If this bit is set, then the PCI I/O cycles between 0x00000000 and 0x000000FF are forwarded onto a PCI root bridge. This bit is used to forward I/O cycles for ISA motherboard devices onto a PCI root bridge.
EFI_PCI_ATTRIBUTE_ISA_IO If this bit is set, then the PCI I/O cycles between 0x100 and 0x3FF are forwarded onto a PCI root bridge 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 onto a PCI root bridge.
EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO If this bit is set, then the PCI I/O write cycles for 0x3C6, 0x3C8, and 0x3C9 are forwarded onto a PCI root bridge 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 onto a PCI root bridge.
EFI_PCI_ATTRIBUTE_VGA_MEMORY If this bit is set, then the PCI memory cycles between 0xA0000 and 0xBFFFF are forwarded onto a PCI root bridge. This bit is used to forward memory cycles for a VGA frame buffer onto a PCI root bridge.
EFI_PCI_ATTRIBUTE_VGA_IO If this bit is set, then the PCI I/O cycles in the ranges 0x3B0-0x3BB and 0x3C0-0x3DF are forwarded onto a PCI root bridge 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 onto a PCI root bridge. Since EFI_PCI_ATTRIBUTE_ENABLE_VGA_IO also includes the I/O range described by EFI_PCI_ATTRIBUTE_ENABLE_VGA_PALETTE_IO, the EFI_PCI_ATTRIBUTE_ENABLE_VGA_PALETTE_IO bit is ignored if EFI_PCI_ATTRIBUTE_ENABLE_VGA_IO is set.
EFI_PCI_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 onto a PCI root bridge 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 onto a PCI root bridge.
EFI_PCI_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 onto a PCI root bridge 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 onto a PCI root bridge.
EFI_PCI_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. By default, PCI memory ranges are not accessed in a write combining mode.

EFI_PCI_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_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_ATTRIBUTE_DUAL_ADDRESS_CYCLE This bit may only be used in the Attributes parameter to AllocateBuffer(). If this bit is set, then the PCI controller that is requesting a buffer through AllocateBuffer() 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 that is requesting a buffer through AllocateBuffer() 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_ROOT_BRIDGE_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_ROOT_BRIDGE_IO_PROTOCOL instance for each PCI root bridge in a system. Embedded systems, desktops, and workstations will typically only have one PCI root bridge. High-end servers may have multiple PCI root bridges. A device driver that wishes to manage a PCI bus in a system will have to retrieve the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance that is associated with the PCI bus to be managed. A device handle for a PCI Root Bridge will minimally contain an EFI_DEVICE_PATH_PROTOCOL instance and an EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance. The PCI bus driver can look at the EFI_DEVICE_PATH_PROTOCOL instances to determine which EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance to use.

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_ROOT_BRIDGE_IO_PROTOCOL APIs that are used for each DMA operation type.

DMA Bus Master Read Operation

  • Call Map() for EfiPciOperationBusMasterRead or EfiPciOperationBusMasterRead64.
  • 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 or EfiPciOperationBusMasterRead64.
  • 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 EfiPciOperationBusMasterCommonBuffer or EfiPciOperationBusMasterCommonBuffer64.
  • 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 Root Bridge. Returns when either the polling exit criteria is satisfied or after a defined duration.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM) (
  IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL       *This,
  IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH Width,
  IN  UINT64                                Address,
  IN  UINT64                                Mask,
  IN  UINT64                                Value,
  IN  UINT64                                Delay,
  OUT UINT64                                *Result
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
Width Signifies the width of the memory operations.
Address The base address of the memory operations. The caller is responsible for aligning Address if required.
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 Address 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 PCI memory read access no matter how small Delay may be. If Delay is zero, 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 EfiPciWidthUint8, EfiPciWidthUint16, EfiPciWidthUint32, or EfiPciWidthUint64, 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 Root Bridge on a platform might require. For example on some platforms, width requests of EfiPciWidthUint64 are not supported.

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 Codes 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_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 Root Bridge. Returns when either the polling exit criteria is satisfied or after a defined duration.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM) (
  IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL       *This,
  IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH Width,
  IN  UINT64                                Address,
  IN  UINT64                                Mask,
  IN  UINT64                                Value,
  IN  UINT64                                Delay,
  OUT UINT64                                *Result
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
Width Signifies the width of the I/O operations.
Address The base address of the I/O operations. The caller is responsible for aligning Address if required.
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 Address 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 zero, 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 EfiPciWidthUint8, EfiPciWidthUint16, EfiPciWidthUint32, or EfiPciWidthUint64, 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 Root Bridge on a platform might require. For example on some platforms, width requests of EfiPciWidthUint64 do not work.

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 last data returned from the access matched the poll exit criteria.
EFI_INVALID_PARAMETER Width is invalid.
EFI_INVALID_PARAMETER Result is NULL.
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()

Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM) (
  IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL   *This,
  IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH Width,
  IN UINT64                            Address,
  IN UINTN                             Count,
  IN OUT VOID                          *Buffer
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
Width Signifies the width of the memory operation.
Address The base address of the memory operation. The caller is responsible for aligning the Address if required.
Count The number of memory operations to perform. Bytes moved is Width size * Count, starting at Address.
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 PCI controller registers in the PCI root bridge memory space.

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

If Width is EfiPciWidthUint8, EfiPciWidthUint16, EfiPciWidthUint32, or EfiPciWidthUint64, then both Address and Buffer are incremented for each of the Count operations performed.

If Width is EfiPciWidthFifoUint8, EfiPciWidthFifoUint16, EfiPciWidthFifoUint32, or EfiPciWidthFifoUint64, 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 EfiPciWidthFillUint8, EfiPciWidthFillUint16, EfiPciWidthFillUint32, or EfiPciWidthFillUint64, 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 read 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 root bridge.
EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
EFI_INVALID_PARAMETER Buffer is NULL.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

Io()

Io.Read()

Io.Write()

Enables a PCI driver to access PCI controller registers in the PCI root bridge I/O space.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM) (
  IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL       *This,
  IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH Width,
  IN UINT64                                Address,
  IN UINTN                                 Count,
  IN OUT VOID                              *Buffer
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
Width Signifies the width of the memory operations.
Address The base address of the I/O operation. The caller is responsible for aligning the Address if required.
Count The number of I/O operations to perform. Bytes moved is Width size * Count, starting at Address.
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 the PCI root bridge I/O space.

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

If Width is EfiPciWidthUint8, EfiPciWidthUint16, EfiPciWidthUint32, or EfiPciWidthUint64, then both Address and Buffer are incremented for each of the Count operations performed.

If Width is EfiPciWidthFifoUint8, EfiPciWidthFifoUint16, EfiPciWidthFifoUint32, or EfiPciWidthFifoUint64, 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 EfiPciWidthFillUint8, EfiPciWidthFillUint16, EfiPciWidthFillUint32, or EfiPciWidthFillUint64, 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 root bridge.
EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
EFI_INVALID_PARAMETER Buffer is NULL.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

Pci()

Pci.Read()

Pci.Write()

Enables a PCI driver to access PCI controller registers in a PCI root bridge’s configuration space.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM) (
  IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL       *This,
  IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH Width,
  IN     UINT64                                Address,
  IN     UINTN                                 Count,
  IN OUT VOID                                  *Buffer
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
Width Signifies the width of the memory operations.
Address The address 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 Address.
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 a PCI controller.

The PCI Configuration operations are carried out exactly as requested. The caller is responsible for any alignment and PCI configuration width issues that a PCI Root Bridge on a platform might require. For example on some platforms, width requests of EfiPciWidthUint64 do not work.

If Width is EfiPciWidthUint8, EfiPciWidthUint16, EfiPciWidthUint32, or EfiPciWidthUint64, then both Address and Buffer are incremented for each of the Count operations performed.

If Width is EfiPciWidthFifoUint8, EfiPciWidthFifoUint16, EfiPciWidthFifoUint32, or EfiPciWidthFifoUint64, 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 EfiPciWidthFillUint8, EfiPciWidthFillUint16, EfiPciWidthFillUint32, or EfiPciWidthFillUint64, 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 root bridge.
EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
EFI_INVALID_PARAMETER Buffer is NULL.
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 root bridge memory space to another region of PCI root bridge memory space.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_COPY_MEM) (
  IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL       *This,
  IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH Width,
  IN UINT64                                DestAddress,
  IN UINT64                                SrcAddress,
  IN UINTN                                 Count
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance.
Width Signifies the width of the memory operations.
DestAddress The destination address of the memory operation. The caller is responsible for aligning the DestAddress if required.
SrcAddress The source address of the memory operation. The caller is responsible for aligning the SrcAddress if required.
Count The number of memory operations to perform. Bytes moved is Width size * Count, starting at DestAddress and SrcAddress.

Description
The CopyMem() function enables a PCI driver to copy one region of PCI root bridge memory space to another region of PCI root bridge memory space. This is especially useful for video scroll operation 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 root bridge on a platform might require. For example on some platforms, width requests of EfiPciWidthUint64 do not work.

If Width is EfiPciWidthUint8, EfiPciWidthUint16, EfiPciWidthUint32, or EfiPciWidthUint64, then Count read/write transactions are performed to move the contents of the SrcAddress buffer to the DestAddress buffer. The implementation must be reentrant, and it must handle overlapping SrcAddress and DestAddress 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 SrcAddress and DestAddress buffers. If either the SrcAddress buffer or the DestAddress buffer crosses the top of the processor’s address space, then the result of the copy operation is unpredictable.

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

  • If DestAddress > SrcAddress and DestAddress < (SrcAddress + Width size * Count), then the data should be copied from the SrcAddress buffer to the DestAddress buffer starting from the end of buffers and working toward the beginning of the buffers.
  • Otherwise, the data should be copied from the SrcAddress buffer to the DestAddress 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 for this PCI root bridge.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

Map()

Provides the PCI controller–specific addresses required to access system memory from a DMA bus master.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_MAP) (
  IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL           *This,
  IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_OPERATION Operation,
  IN     VOID                                      *HostAddress,
  IN OUT UINTN                                     *NumberOfBytes,
  OUT    EFI_PHYSICAL_ADDRESS                      *DeviceAddress,
  OUT    VOID                                      **Mapping
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
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 system memory’s HostAddress. This address cannot be used by the processor to access the contents of the buffer specified by HostAddress.
Mapping The value to pass to Unmap() when the bus master DMA operation is complete.

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 single write data transfer, then EfiPciOperationBusMasterRead, EfiPciOperationBusMasterRead64, EfiPciOperationBusMasterWrite, or EfiPciOperationBusMasterWrite64 is used and the range is unmapped to complete the operation. If performing an EfiPciOperationBusMasterRead or EfiPciOperationBusMasterRead64 operation, all the data must be present in system memory before Map() is performed. Similarly, if performing an EfiPciOperation-BusMasterWrite or EfiPciOperationBusMasterWrite64 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 EfiPciOperation-BusMasterCommonBuffer or EfiPciOperationBusMasterCommonBuffer64. However, only memory allocated via the AllocateBuffer() interface can be mapped for this type of operation.

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

Parameter 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_ROOT_BRIDGE_IO_PROTOCOL_UNMAP) (
  IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This,
  IN VOID                            *Mapping
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
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 EfiPciOperationBusMasterWrite or EfiPciOperationBusMasterWrite64, 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_INVALID_PARAMETER Mapping is not a value that was returned by Map().
EFI_DEVICE_ERROR The data was not committed to the target system memory.

AllocateBuffer()

Allocates pages that are suitable for an EfiPciOperationBusMasterCommonBuffer or EfiPciOperationBusMasterCommonBuffer64 mapping.

Prototype

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

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
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, EFI_PCI_ATTRIBUTE_MEMORY_CACHED, and EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE 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 EfiPciOperationBusMasterCommonBuffer or EfiPciOperationBusMasterCommonBuffer64 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 EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE bit of Attributes is 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.

If the EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE bit of Attributes is 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.

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, MEMORY_CACHED, and DUAL_ADDRESS_CYCLE.
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_ROOT_BRIDGE_IO_PROTOCOL_FREE_BUFFER) (
  IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This,
  IN UINTN                           Pages,
  IN VOID                            *HostAddress
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
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_ROOT_BRIDGE_IO_PROTOCOL_FLUSH) (
  IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

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.

GetAttributes()

Gets the attributes that a PCI root bridge supports setting with SetAttributes(), and the attributes that a PCI root bridge is currently using.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GET_ATTRIBUTES) (
  IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This,
  OUT UINT64                          *Supports OPTIONAL,
  OUT UINT64                          *Attributes OPTIONAL
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
Supports A pointer to the mask of attributes that this PCI root bridge supports setting with SetAttributes(). The available attributes are listed in Section 13.2. This is an optional parameter that may be NULL.
Attributes A pointer to the mask of attributes that this PCI root bridge is currently using. The available attributes are listed in Section 13.2. This is an optional parameter that may be NULL.

Description
The GetAttributes() function returns the mask of attributes that this PCI root bridge supports and the mask of attributes that the PCI root bridge is currently using. If Supports is not NULL, then Supports is set to the mask of attributes that the PCI root bridge supports. If Attributes is not NULL, then Attributes is set to the mask of attributes that the PCI root bridge is currently using. If both Supports and Attributes are NULL, then EFI_INVALID_PARAMETER is returned. Otherwise, EFI_SUCCESS is returned.

If a bit is set in Supports, then the PCI root bridge supports this attribute type, and a call can be made to SetAttributes() using that attribute type. If a bit is set in Attributes, then the PCI root bridge is currently using that attribute type. Since a PCI host bus may be composed of more than one PCI root bridge, different Attributes values may be returned by different PCI root bridges.

Status Codes Returned

Status Code Description
EFI_SUCCESS If Supports is not NULL, then the attributes that the PCI root bridge supports is returned in Supports. If Attributes is not NULL, then the attributes that the PCI root bridge is currently using is returned in Attributes.
EFI_INVALID_PARAMETER Both Supports and Attributes are NULL.

SetAttributes()

Sets attributes for a resource range on a PCI root bridge.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_SET_ATTRIBUTES) (
  IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This,
  IN     UINT64                          Attributes,
  IN OUT UINT64                          *ResourceBase OPTIONAL,
  IN OUT UINT64                          *ResourceLength OPTIONAL
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
Attributes The mask of attributes to set. If the attribute bit MEMORY_WRITE_COMBINE, MEMORY_CACHED, or MEMORY_DISABLE is set, then the resource range is specified by ResourceBase and ResourceLength. If MEMORY_WRITE_COMBINE, MEMORY_CACHED, and MEMORY_DISABLE are not set, then ResourceBase and ResourceLength are ignored, and may be NULL.
ResourceBase A pointer to the base address of the resource range to be modified by the attributes specified by Attributes. On return, *ResourceBase will be set 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. This parameter is only used if the MEMORY_WRITE_COMBINE bit, the MEMORY_CACHED bit, or the MEMORY_DISABLE bit of Attributes is set. Otherwise, it is ignored, and may be NULL.
ResourceLength A pointer to the length of the resource range to be modified by the attributes specified by Attributes. On return, *ResourceLength will be set 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. This parameter is only used if the MEMORY_WRITE_COMBINE bit, the MEMORY_CACHED bit, or the MEMORY_DISABLE bit of Attributes is set. Otherwise, it is ignored, and may be NULL.

Description
The SetAttributes() function sets the attributes specified in Attributes for the PCI root bridge on the resource range specified by ResourceBase and ResourceLength. 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 ResourceBase and ResourceLength. 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 root bridge, then the actual resource range is returned in ResourceBase and ResourceLength, and EFI_SUCCESS is returned.

If the attributes specified by Attributes are not supported by the PCI root bridge, then EFI_UNSUPPORTED is returned. The set of supported attributes for a PCI root bridge can be found by calling GetAttributes().

If either ResourceBase or ResourceLength are NULL, and a resource range is required for the attributes specified in Attributes, then EFI_INVALID_PARAMETER is returned.

If more than one resource range is required for the set of attributes specified by Attributes, 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 ResourceBase and ResourceLength were set on the PCI root bridge, and the actual resource range is returned in ResuourceBase and ResourceLength.
EFI_UNSUPPORTED A bit is set in Attributes that is not supported by the PCI Root Bridge. The supported attribute bits are reported by GetAttributes().
EFI_INVALID_PARAMETER More than one attribute bit is set in Attributes that requires a resource range.
EFI_INVALID_PARAMETER A resource range is required, and ResourceBase is NULL.
EFI_INVALID_PARAMETER A resource range is required, and ResourceLength is NULL.
EFI_OUT_OF_RESOURCES There are not enough resources to set the attributes on the resource range specified by BaseAddress and Length.

Configuration()

Retrieves the current resource settings of this PCI root bridge in the form of a set of ACPI 2.0 resource descriptors.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION) (
  IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This,
  OUT VOID                            **Resources
  );

Parameters

Parameter Description
This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
Resources A pointer to the ACPI 2.0 resource descriptors that describe the current configuration of this PCI root bridge. The storage for the ACPI 2.0 resource descriptors is allocated by this function. The caller must treat the return buffer as read-only data, and the buffer must not be freed by the caller.

Description
The Configuration() function retrieves a set of ACPI 2.0 resource descriptors that contains the current configuration of this PCI root bridge. If the current configuration can be retrieved, then it is returned in Resources and EFI_SUCCESS is returned. See “Related Definitions” below for the resource descriptor types that are supported by this function. If the current configuration cannot be retrieved, then EFI_UNSUPPORTED is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The current configuration of this PCI root bridge was returned in Resources.
EFI_UNSUPPORTED The current configuration of this PCI root bridge could not be retrieved

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

Personal tools