iPXE
PciRootBridgeIo.h
Go to the documentation of this file.
00001 /** @file
00002   PCI Root Bridge I/O protocol as defined in the UEFI 2.0 specification.
00003 
00004   PCI Root Bridge I/O protocol is used by PCI Bus Driver to perform PCI Memory, PCI I/O,
00005   and PCI Configuration cycles on a PCI Root Bridge. It also provides services to perform
00006   defferent types of bus mastering DMA.
00007 
00008   Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
00009   This program and the accompanying materials
00010   are licensed and made available under the terms and conditions of the BSD License
00011   which accompanies this distribution.  The full text of the license may be found at
00012   http://opensource.org/licenses/bsd-license.php
00013 
00014   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00015   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00016 
00017 **/
00018 
00019 #ifndef __PCI_ROOT_BRIDGE_IO_H__
00020 #define __PCI_ROOT_BRIDGE_IO_H__
00021 
00022 FILE_LICENCE ( BSD3 );
00023 
00024 #include <ipxe/efi/Library/BaseLib.h>
00025 
00026 #define EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID \
00027   { \
00028     0x2f707ebb, 0x4a1a, 0x11d4, {0x9a, 0x38, 0x00, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
00029   }
00030 
00031 typedef struct _EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL;
00032 
00033 ///
00034 /// *******************************************************
00035 /// EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH
00036 /// *******************************************************
00037 ///
00038 typedef enum {
00039   EfiPciWidthUint8,
00040   EfiPciWidthUint16,
00041   EfiPciWidthUint32,
00042   EfiPciWidthUint64,
00043   EfiPciWidthFifoUint8,
00044   EfiPciWidthFifoUint16,
00045   EfiPciWidthFifoUint32,
00046   EfiPciWidthFifoUint64,
00047   EfiPciWidthFillUint8,
00048   EfiPciWidthFillUint16,
00049   EfiPciWidthFillUint32,
00050   EfiPciWidthFillUint64,
00051   EfiPciWidthMaximum
00052 } EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH;
00053 
00054 ///
00055 /// *******************************************************
00056 /// EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_OPERATION
00057 /// *******************************************************
00058 ///
00059 typedef enum {
00060   ///
00061   /// A read operation from system memory by a bus master that is not capable of producing
00062   /// PCI dual address cycles.
00063   ///
00064   EfiPciOperationBusMasterRead,
00065   ///
00066   /// A write operation from system memory by a bus master that is not capable of producing
00067   /// PCI dual address cycles.
00068   ///
00069   EfiPciOperationBusMasterWrite,
00070   ///
00071   /// Provides both read and write access to system memory by both the processor and a bus
00072   /// master that is not capable of producing PCI dual address cycles.
00073   ///
00074   EfiPciOperationBusMasterCommonBuffer,
00075   ///
00076   /// A read operation from system memory by a bus master that is capable of producing PCI
00077   /// dual address cycles.
00078   ///
00079   EfiPciOperationBusMasterRead64,
00080   ///
00081   /// A write operation to system memory by a bus master that is capable of producing PCI
00082   /// dual address cycles.
00083   ///
00084   EfiPciOperationBusMasterWrite64,
00085   ///
00086   /// Provides both read and write access to system memory by both the processor and a bus
00087   /// master that is capable of producing PCI dual address cycles.
00088   ///
00089   EfiPciOperationBusMasterCommonBuffer64,
00090   EfiPciOperationMaximum
00091 } EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_OPERATION;
00092 
00093 #define EFI_PCI_ATTRIBUTE_ISA_MOTHERBOARD_IO          0x0001
00094 #define EFI_PCI_ATTRIBUTE_ISA_IO                      0x0002
00095 #define EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO              0x0004
00096 #define EFI_PCI_ATTRIBUTE_VGA_MEMORY                  0x0008
00097 #define EFI_PCI_ATTRIBUTE_VGA_IO                      0x0010
00098 #define EFI_PCI_ATTRIBUTE_IDE_PRIMARY_IO              0x0020
00099 #define EFI_PCI_ATTRIBUTE_IDE_SECONDARY_IO            0x0040
00100 #define EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE        0x0080
00101 #define EFI_PCI_ATTRIBUTE_MEMORY_CACHED               0x0800
00102 #define EFI_PCI_ATTRIBUTE_MEMORY_DISABLE              0x1000
00103 #define EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE          0x8000
00104 #define EFI_PCI_ATTRIBUTE_ISA_IO_16                   0x10000
00105 #define EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO_16           0x20000
00106 #define EFI_PCI_ATTRIBUTE_VGA_IO_16                   0x40000
00107 
00108 #define EFI_PCI_ATTRIBUTE_VALID_FOR_ALLOCATE_BUFFER   (EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE | EFI_PCI_ATTRIBUTE_MEMORY_CACHED | EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE)
00109 
00110 #define EFI_PCI_ATTRIBUTE_INVALID_FOR_ALLOCATE_BUFFER (~EFI_PCI_ATTRIBUTE_VALID_FOR_ALLOCATE_BUFFER)
00111 
00112 #define EFI_PCI_ADDRESS(bus, dev, func, reg) \
00113   (UINT64) ( \
00114   (((UINTN) bus) << 24) | \
00115   (((UINTN) dev) << 16) | \
00116   (((UINTN) func) << 8) | \
00117   (((UINTN) (reg)) < 256 ? ((UINTN) (reg)) : (UINT64) (LShiftU64 ((UINT64) (reg), 32))))
00118 
00119 typedef struct {
00120   UINT8   Register;
00121   UINT8   Function;
00122   UINT8   Device;
00123   UINT8   Bus;
00124   UINT32  ExtendedRegister;
00125 } EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS;
00126 
00127 /**
00128   Reads from the I/O space of a PCI Root Bridge. Returns when either the polling exit criteria is
00129   satisfied or after a defined duration.
00130 
00131   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
00132   @param  Width                 Signifies the width of the memory or I/O operations.
00133   @param  Address               The base address of the memory or I/O operations.
00134   @param  Mask                  Mask used for the polling criteria.
00135   @param  Value                 The comparison value used for the polling exit criteria.
00136   @param  Delay                 The number of 100 ns units to poll.
00137   @param  Result                Pointer to the last value read from the memory location.
00138 
00139   @retval EFI_SUCCESS           The last data returned from the access matched the poll exit criteria.
00140   @retval EFI_TIMEOUT           Delay expired before a match occurred.
00141   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
00142   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
00143 
00144 **/
00145 typedef
00146 EFI_STATUS
00147 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM)(
00148   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL           *This,
00149   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH    Width,
00150   IN  UINT64                                   Address,
00151   IN  UINT64                                   Mask,
00152   IN  UINT64                                   Value,
00153   IN  UINT64                                   Delay,
00154   OUT UINT64                                   *Result
00155   );
00156 
00157 /**
00158   Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.
00159 
00160   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
00161   @param  Width                 Signifies the width of the memory operations.
00162   @param  Address               The base address of the memory operations.
00163   @param  Count                 The number of memory operations to perform.
00164   @param  Buffer                For read operations, the destination buffer to store the results. For write
00165                                 operations, the source buffer to write data from.
00166 
00167   @retval EFI_SUCCESS           The data was read from or written to the PCI root bridge.
00168   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
00169   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
00170 
00171 **/
00172 typedef
00173 EFI_STATUS
00174 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM)(
00175   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL              *This,
00176   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH    Width,
00177   IN     UINT64                                   Address,
00178   IN     UINTN                                    Count,
00179   IN OUT VOID                                     *Buffer
00180   );
00181 
00182 typedef struct {
00183   ///
00184   /// Read PCI controller registers in the PCI root bridge memory space.
00185   ///
00186   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM  Read;
00187   ///
00188   /// Write PCI controller registers in the PCI root bridge memory space.
00189   ///
00190   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM  Write;
00191 } EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS;
00192 
00193 /**
00194   Enables a PCI driver to copy one region of PCI root bridge memory space to another region of PCI
00195   root bridge memory space.
00196 
00197   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance.
00198   @param  Width                 Signifies the width of the memory operations.
00199   @param  DestAddress           The destination address of the memory operation.
00200   @param  SrcAddress            The source address of the memory operation.
00201   @param  Count                 The number of memory operations to perform.
00202 
00203   @retval EFI_SUCCESS           The data was copied from one memory region to another memory region.
00204   @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
00205   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
00206 
00207 **/
00208 typedef
00209 EFI_STATUS
00210 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_COPY_MEM)(
00211   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL              *This,
00212   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH    Width,
00213   IN     UINT64                                   DestAddress,
00214   IN     UINT64                                   SrcAddress,
00215   IN     UINTN                                    Count
00216   );
00217 
00218 /**
00219   Provides the PCI controller-specific addresses required to access system memory from a
00220   DMA bus master.
00221 
00222   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
00223   @param  Operation             Indicates if the bus master is going to read or write to system memory.
00224   @param  HostAddress           The system memory address to map to the PCI controller.
00225   @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes
00226                                 that were mapped.
00227   @param  DeviceAddress         The resulting map address for the bus master PCI controller to use to
00228                                 access the hosts HostAddress.
00229   @param  Mapping               A resulting value to pass to Unmap().
00230 
00231   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
00232   @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.
00233   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
00234   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
00235   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
00236 
00237 **/
00238 typedef
00239 EFI_STATUS
00240 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_MAP)(
00241   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL                *This,
00242   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_OPERATION  Operation,
00243   IN     VOID                                       *HostAddress,
00244   IN OUT UINTN                                      *NumberOfBytes,
00245   OUT    EFI_PHYSICAL_ADDRESS                       *DeviceAddress,
00246   OUT    VOID                                       **Mapping
00247   );
00248 
00249 /**
00250   Completes the Map() operation and releases any corresponding resources.
00251 
00252   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
00253   @param  Mapping               The mapping value returned from Map().
00254 
00255   @retval EFI_SUCCESS           The range was unmapped.
00256   @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
00257   @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.
00258 
00259 **/
00260 typedef
00261 EFI_STATUS
00262 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_UNMAP)(
00263   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL           *This,
00264   IN  VOID                                     *Mapping
00265   );
00266 
00267 /**
00268   Allocates pages that are suitable for an EfiPciOperationBusMasterCommonBuffer or
00269   EfiPciOperationBusMasterCommonBuffer64 mapping.
00270 
00271   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
00272   @param  Type                  This parameter is not used and must be ignored.
00273   @param  MemoryType            The type of memory to allocate, EfiBootServicesData or
00274                                 EfiRuntimeServicesData.
00275   @param  Pages                 The number of pages to allocate.
00276   @param  HostAddress           A pointer to store the base system memory address of the
00277                                 allocated range.
00278   @param  Attributes            The requested bit mask of attributes for the allocated range.
00279 
00280   @retval EFI_SUCCESS           The requested memory pages were allocated.
00281   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
00282                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
00283   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
00284   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
00285 
00286 **/
00287 typedef
00288 EFI_STATUS
00289 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ALLOCATE_BUFFER)(
00290   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL              *This,
00291   IN     EFI_ALLOCATE_TYPE                        Type,
00292   IN     EFI_MEMORY_TYPE                          MemoryType,
00293   IN     UINTN                                    Pages,
00294   IN OUT VOID                                     **HostAddress,
00295   IN     UINT64                                   Attributes
00296   );
00297 
00298 /**
00299   Frees memory that was allocated with AllocateBuffer().
00300 
00301   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
00302   @param  Pages                 The number of pages to free.
00303   @param  HostAddress           The base system memory address of the allocated range.
00304 
00305   @retval EFI_SUCCESS           The requested memory pages were freed.
00306   @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
00307                                 was not allocated with AllocateBuffer().
00308 
00309 **/
00310 typedef
00311 EFI_STATUS
00312 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FREE_BUFFER)(
00313   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL           *This,
00314   IN  UINTN                                    Pages,
00315   IN  VOID                                     *HostAddress
00316   );
00317 
00318 /**
00319   Flushes all PCI posted write transactions from a PCI host bridge to system memory.
00320 
00321   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
00322 
00323   @retval EFI_SUCCESS           The PCI posted write transactions were flushed from the PCI host
00324                                 bridge to system memory.
00325   @retval EFI_DEVICE_ERROR      The PCI posted write transactions were not flushed from the PCI
00326                                 host bridge due to a hardware error.
00327 
00328 **/
00329 typedef
00330 EFI_STATUS
00331 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FLUSH)(
00332   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL  *This
00333   );
00334 
00335 /**
00336   Gets the attributes that a PCI root bridge supports setting with SetAttributes(), and the
00337   attributes that a PCI root bridge is currently using.
00338 
00339   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
00340   @param  Supports              A pointer to the mask of attributes that this PCI root bridge supports
00341                                 setting with SetAttributes().
00342   @param  Attributes            A pointer to the mask of attributes that this PCI root bridge is currently
00343                                 using.
00344 
00345   @retval EFI_SUCCESS           If Supports is not NULL, then the attributes that the PCI root
00346                                 bridge supports is returned in Supports. If Attributes is
00347                                 not NULL, then the attributes that the PCI root bridge is currently
00348                                 using is returned in Attributes.
00349   @retval EFI_INVALID_PARAMETER Both Supports and Attributes are NULL.
00350 
00351 
00352 **/
00353 typedef
00354 EFI_STATUS
00355 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GET_ATTRIBUTES)(
00356   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL           *This,
00357   OUT UINT64                                   *Supports,
00358   OUT UINT64                                   *Attributes
00359   );
00360 
00361 /**
00362   Sets attributes for a resource range on a PCI root bridge.
00363 
00364   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
00365   @param  Attributes            The mask of attributes to set.
00366   @param  ResourceBase          A pointer to the base address of the resource range to be modified by the
00367                                 attributes specified by Attributes.
00368   @param  ResourceLength        A pointer to the length of the resource range to be modified by the
00369                                 attributes specified by Attributes.
00370 
00371   @retval EFI_SUCCESS           The set of attributes specified by Attributes for the resource
00372                                 range specified by ResourceBase and ResourceLength
00373                                 were set on the PCI root bridge, and the actual resource range is
00374                                 returned in ResuourceBase and ResourceLength.
00375   @retval EFI_UNSUPPORTED       A bit is set in Attributes that is not supported by the PCI Root
00376                                 Bridge.
00377   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to set the attributes on the
00378                                 resource range specified by BaseAddress and Length.
00379   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
00380 
00381 **/
00382 typedef
00383 EFI_STATUS
00384 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_SET_ATTRIBUTES)(
00385   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL              *This,
00386   IN     UINT64                                   Attributes,
00387   IN OUT UINT64                                   *ResourceBase,
00388   IN OUT UINT64                                   *ResourceLength
00389   );
00390 
00391 /**
00392   Retrieves the current resource settings of this PCI root bridge in the form of a set of ACPI 2.0
00393   resource descriptors.
00394 
00395   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
00396   @param  Resources             A pointer to the ACPI 2.0 resource descriptors that describe the current
00397                                 configuration of this PCI root bridge.
00398 
00399   @retval EFI_SUCCESS           The current configuration of this PCI root bridge was returned in
00400                                 Resources.
00401   @retval EFI_UNSUPPORTED       The current configuration of this PCI root bridge could not be
00402                                 retrieved.
00403 
00404 **/
00405 typedef
00406 EFI_STATUS
00407 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION)(
00408   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL          *This,
00409   OUT VOID                                     **Resources
00410   );
00411 
00412 ///
00413 /// Provides the basic Memory, I/O, PCI configuration, and DMA interfaces that are
00414 /// used to abstract accesses to PCI controllers behind a PCI Root Bridge Controller.
00415 ///
00416 struct _EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL {
00417   ///
00418   /// The EFI_HANDLE of the PCI Host Bridge of which this PCI Root Bridge is a member.
00419   ///
00420   EFI_HANDLE                                      ParentHandle;
00421   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM     PollMem;
00422   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM     PollIo;
00423   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS          Mem;
00424   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS          Io;
00425   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS          Pci;
00426   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_COPY_MEM        CopyMem;
00427   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_MAP             Map;
00428   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_UNMAP           Unmap;
00429   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ALLOCATE_BUFFER AllocateBuffer;
00430   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FREE_BUFFER     FreeBuffer;
00431   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FLUSH           Flush;
00432   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GET_ATTRIBUTES  GetAttributes;
00433   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_SET_ATTRIBUTES  SetAttributes;
00434   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION   Configuration;
00435 
00436   ///
00437   /// The segment number that this PCI root bridge resides.
00438   ///
00439   UINT32                                          SegmentNumber;
00440 };
00441 
00442 extern EFI_GUID gEfiPciRootBridgeIoProtocolGuid;
00443 
00444 #endif