MdePkg/Include/Protocol/PciRootBridgeIo.h

   1 /** @file
   2   PCI Root Bridge I/O protocol as defined in the UEFI 2.0 specification.
   3
   4   PCI Root Bridge I/O protocol is used by PCI Bus Driver to perform PCI Memory, PCI I/O,
   5   and PCI Configuration cycles on a PCI Root Bridge. It also provides services to perform
   6   defferent types of bus mastering DMA.
   7
   8   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   9   SPDX-License-Identifier: BSD-2-Clause-Patent
  10
  11 **/
  12
  13 #ifndef __PCI_ROOT_BRIDGE_IO_H__
  14 #define __PCI_ROOT_BRIDGE_IO_H__
  15
  16 #include <Library/BaseLib.h>
  17
  18 #define EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID \
  19   { \
  20     0x2f707ebb, 0x4a1a, 0x11d4, {0x9a, 0x38, 0x00, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
  21   }
  22
  23 typedef struct _EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL;
  24
  25 ///
  26 /// *******************************************************
  27 /// EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH
  28 /// *******************************************************
  29 ///
  30 typedef enum {
  31   EfiPciWidthUint8,
  32   EfiPciWidthUint16,
  33   EfiPciWidthUint32,
  34   EfiPciWidthUint64,
  35   EfiPciWidthFifoUint8,
  36   EfiPciWidthFifoUint16,
  37   EfiPciWidthFifoUint32,
  38   EfiPciWidthFifoUint64,
  39   EfiPciWidthFillUint8,
  40   EfiPciWidthFillUint16,
  41   EfiPciWidthFillUint32,
  42   EfiPciWidthFillUint64,
  43   EfiPciWidthMaximum
  44 } EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH;
  45
  46 ///
  47 /// *******************************************************
  48 /// EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_OPERATION
  49 /// *******************************************************
  50 ///
  51 typedef enum {
  52   ///
  53   /// A read operation from system memory by a bus master that is not capable of producing
  54   /// PCI dual address cycles.
  55   ///
  56   EfiPciOperationBusMasterRead,
  57   ///
  58   /// A write operation from system memory by a bus master that is not capable of producing
  59   /// PCI dual address cycles.
  60   ///
  61   EfiPciOperationBusMasterWrite,
  62   ///
  63   /// Provides both read and write access to system memory by both the processor and a bus
  64   /// master that is not capable of producing PCI dual address cycles.
  65   ///
  66   EfiPciOperationBusMasterCommonBuffer,
  67   ///
  68   /// A read operation from system memory by a bus master that is capable of producing PCI
  69   /// dual address cycles.
  70   ///
  71   EfiPciOperationBusMasterRead64,
  72   ///
  73   /// A write operation to system memory by a bus master that is capable of producing PCI
  74   /// dual address cycles.
  75   ///
  76   EfiPciOperationBusMasterWrite64,
  77   ///
  78   /// Provides both read and write access to system memory by both the processor and a bus
  79   /// master that is capable of producing PCI dual address cycles.
  80   ///
  81   EfiPciOperationBusMasterCommonBuffer64,
  82   EfiPciOperationMaximum
  83 } EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_OPERATION;
  84
  85 #define EFI_PCI_ATTRIBUTE_ISA_MOTHERBOARD_IO    0x0001
  86 #define EFI_PCI_ATTRIBUTE_ISA_IO                0x0002
  87 #define EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO        0x0004
  88 #define EFI_PCI_ATTRIBUTE_VGA_MEMORY            0x0008
  89 #define EFI_PCI_ATTRIBUTE_VGA_IO                0x0010
  90 #define EFI_PCI_ATTRIBUTE_IDE_PRIMARY_IO        0x0020
  91 #define EFI_PCI_ATTRIBUTE_IDE_SECONDARY_IO      0x0040
  92 #define EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE  0x0080
  93 #define EFI_PCI_ATTRIBUTE_MEMORY_CACHED         0x0800
  94 #define EFI_PCI_ATTRIBUTE_MEMORY_DISABLE        0x1000
  95 #define EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE    0x8000
  96 #define EFI_PCI_ATTRIBUTE_ISA_IO_16             0x10000
  97 #define EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO_16     0x20000
  98 #define EFI_PCI_ATTRIBUTE_VGA_IO_16             0x40000
  99
 100 #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)
 101
 102 #define EFI_PCI_ATTRIBUTE_INVALID_FOR_ALLOCATE_BUFFER  (~EFI_PCI_ATTRIBUTE_VALID_FOR_ALLOCATE_BUFFER)
 103
 104 #define EFI_PCI_ADDRESS(bus, dev, func, reg) \
 105   (UINT64) ( \
 106   (((UINTN) bus) << 24) | \
 107   (((UINTN) dev) << 16) | \
 108   (((UINTN) func) << 8) | \
 109   (((UINTN) (reg)) < 256 ? ((UINTN) (reg)) : (UINT64) (LShiftU64 ((UINT64) (reg), 32))))
 110
 111 typedef struct {
 112   UINT8     Register;
 113   UINT8     Function;
 114   UINT8     Device;
 115   UINT8     Bus;
 116   UINT32    ExtendedRegister;
 117 } EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS;
 118
 119 /**
 120   Reads from the I/O space of a PCI Root Bridge. Returns when either the polling exit criteria is
 121   satisfied or after a defined duration.
 122
 123   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 124   @param  Width                 Signifies the width of the memory or I/O operations.
 125   @param  Address               The base address of the memory or I/O operations.
 126   @param  Mask                  Mask used for the polling criteria.
 127   @param  Value                 The comparison value used for the polling exit criteria.
 128   @param  Delay                 The number of 100 ns units to poll.
 129   @param  Result                Pointer to the last value read from the memory location.
 130
 131   @retval EFI_SUCCESS           The last data returned from the access matched the poll exit criteria.
 132   @retval EFI_TIMEOUT           Delay expired before a match occurred.
 133   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 134   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 135
 136 **/
 137 typedef
 138 EFI_STATUS
 139 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM)(
 140   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL           *This,
 141   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH    Width,
 142   IN  UINT64                                   Address,
 143   IN  UINT64                                   Mask,
 144   IN  UINT64                                   Value,
 145   IN  UINT64                                   Delay,
 146   OUT UINT64                                   *Result
 147   );
 148
 149 /**
 150   Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.
 151
 152   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 153   @param  Width                 Signifies the width of the memory operations.
 154   @param  Address               The base address of the memory operations.
 155   @param  Count                 The number of memory operations to perform.
 156   @param  Buffer                For read operations, the destination buffer to store the results. For write
 157                                 operations, the source buffer to write data from.
 158
 159   @retval EFI_SUCCESS           The data was read from or written to the PCI root bridge.
 160   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 161   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 162
 163 **/
 164 typedef
 165 EFI_STATUS
 166 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM)(
 167   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL              *This,
 168   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH    Width,
 169   IN     UINT64                                   Address,
 170   IN     UINTN                                    Count,
 171   IN OUT VOID                                     *Buffer
 172   );
 173
 174 typedef struct {
 175   ///
 176   /// Read PCI controller registers in the PCI root bridge memory space.
 177   ///
 178   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM    Read;
 179   ///
 180   /// Write PCI controller registers in the PCI root bridge memory space.
 181   ///
 182   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM    Write;
 183 } EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS;
 184
 185 /**
 186   Enables a PCI driver to copy one region of PCI root bridge memory space to another region of PCI
 187   root bridge memory space.
 188
 189   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance.
 190   @param  Width                 Signifies the width of the memory operations.
 191   @param  DestAddress           The destination address of the memory operation.
 192   @param  SrcAddress            The source address of the memory operation.
 193   @param  Count                 The number of memory operations to perform.
 194
 195   @retval EFI_SUCCESS           The data was copied from one memory region to another memory region.
 196   @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
 197   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 198
 199 **/
 200 typedef
 201 EFI_STATUS
 202 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_COPY_MEM)(
 203   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL              *This,
 204   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH    Width,
 205   IN     UINT64                                   DestAddress,
 206   IN     UINT64                                   SrcAddress,
 207   IN     UINTN                                    Count
 208   );
 209
 210 /**
 211   Provides the PCI controller-specific addresses required to access system memory from a
 212   DMA bus master.
 213
 214   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 215   @param  Operation             Indicates if the bus master is going to read or write to system memory.
 216   @param  HostAddress           The system memory address to map to the PCI controller.
 217   @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes
 218                                 that were mapped.
 219   @param  DeviceAddress         The resulting map address for the bus master PCI controller to use to
 220                                 access the hosts HostAddress.
 221   @param  Mapping               A resulting value to pass to Unmap().
 222
 223   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
 224   @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.
 225   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 226   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 227   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
 228
 229 **/
 230 typedef
 231 EFI_STATUS
 232 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_MAP)(
 233   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL                *This,
 234   IN     EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_OPERATION  Operation,
 235   IN     VOID                                       *HostAddress,
 236   IN OUT UINTN                                      *NumberOfBytes,
 237   OUT    EFI_PHYSICAL_ADDRESS                       *DeviceAddress,
 238   OUT    VOID                                       **Mapping
 239   );
 240
 241 /**
 242   Completes the Map() operation and releases any corresponding resources.
 243
 244   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 245   @param  Mapping               The mapping value returned from Map().
 246
 247   @retval EFI_SUCCESS           The range was unmapped.
 248   @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
 249   @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.
 250
 251 **/
 252 typedef
 253 EFI_STATUS
 254 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_UNMAP)(
 255   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL           *This,
 256   IN  VOID                                     *Mapping
 257   );
 258
 259 /**
 260   Allocates pages that are suitable for an EfiPciOperationBusMasterCommonBuffer or
 261   EfiPciOperationBusMasterCommonBuffer64 mapping.
 262
 263   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 264   @param  Type                  This parameter is not used and must be ignored.
 265   @param  MemoryType            The type of memory to allocate, EfiBootServicesData or
 266                                 EfiRuntimeServicesData.
 267   @param  Pages                 The number of pages to allocate.
 268   @param  HostAddress           A pointer to store the base system memory address of the
 269                                 allocated range.
 270   @param  Attributes            The requested bit mask of attributes for the allocated range.
 271
 272   @retval EFI_SUCCESS           The requested memory pages were allocated.
 273   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
 274                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
 275   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 276   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 277
 278 **/
 279 typedef
 280 EFI_STATUS
 281 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ALLOCATE_BUFFER)(
 282   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL              *This,
 283   IN     EFI_ALLOCATE_TYPE                        Type,
 284   IN     EFI_MEMORY_TYPE                          MemoryType,
 285   IN     UINTN                                    Pages,
 286   IN OUT VOID                                     **HostAddress,
 287   IN     UINT64                                   Attributes
 288   );
 289
 290 /**
 291   Frees memory that was allocated with AllocateBuffer().
 292
 293   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 294   @param  Pages                 The number of pages to free.
 295   @param  HostAddress           The base system memory address of the allocated range.
 296
 297   @retval EFI_SUCCESS           The requested memory pages were freed.
 298   @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
 299                                 was not allocated with AllocateBuffer().
 300
 301 **/
 302 typedef
 303 EFI_STATUS
 304 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FREE_BUFFER)(
 305   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL           *This,
 306   IN  UINTN                                    Pages,
 307   IN  VOID                                     *HostAddress
 308   );
 309
 310 /**
 311   Flushes all PCI posted write transactions from a PCI host bridge to system memory.
 312
 313   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 314
 315   @retval EFI_SUCCESS           The PCI posted write transactions were flushed from the PCI host
 316                                 bridge to system memory.
 317   @retval EFI_DEVICE_ERROR      The PCI posted write transactions were not flushed from the PCI
 318                                 host bridge due to a hardware error.
 319
 320 **/
 321 typedef
 322 EFI_STATUS
 323 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FLUSH)(
 324   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL  *This
 325   );
 326
 327 /**
 328   Gets the attributes that a PCI root bridge supports setting with SetAttributes(), and the
 329   attributes that a PCI root bridge is currently using.
 330
 331   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 332   @param  Supports              A pointer to the mask of attributes that this PCI root bridge supports
 333                                 setting with SetAttributes().
 334   @param  Attributes            A pointer to the mask of attributes that this PCI root bridge is currently
 335                                 using.
 336
 337   @retval EFI_SUCCESS           If Supports is not NULL, then the attributes that the PCI root
 338                                 bridge supports is returned in Supports. If Attributes is
 339                                 not NULL, then the attributes that the PCI root bridge is currently
 340                                 using is returned in Attributes.
 341   @retval EFI_INVALID_PARAMETER Both Supports and Attributes are NULL.
 342
 343
 344 **/
 345 typedef
 346 EFI_STATUS
 347 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GET_ATTRIBUTES)(
 348   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL           *This,
 349   OUT UINT64                                   *Supports,
 350   OUT UINT64                                   *Attributes
 351   );
 352
 353 /**
 354   Sets attributes for a resource range on a PCI root bridge.
 355
 356   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 357   @param  Attributes            The mask of attributes to set.
 358   @param  ResourceBase          A pointer to the base address of the resource range to be modified by the
 359                                 attributes specified by Attributes.
 360   @param  ResourceLength        A pointer to the length of the resource range to be modified by the
 361                                 attributes specified by Attributes.
 362
 363   @retval EFI_SUCCESS           The set of attributes specified by Attributes for the resource
 364                                 range specified by ResourceBase and ResourceLength
 365                                 were set on the PCI root bridge, and the actual resource range is
 366                                 returned in ResuourceBase and ResourceLength.
 367   @retval EFI_UNSUPPORTED       A bit is set in Attributes that is not supported by the PCI Root
 368                                 Bridge.
 369   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to set the attributes on the
 370                                 resource range specified by BaseAddress and Length.
 371   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 372
 373 **/
 374 typedef
 375 EFI_STATUS
 376 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_SET_ATTRIBUTES)(
 377   IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL              *This,
 378   IN     UINT64                                   Attributes,
 379   IN OUT UINT64                                   *ResourceBase,
 380   IN OUT UINT64                                   *ResourceLength
 381   );
 382
 383 /**
 384   Retrieves the current resource settings of this PCI root bridge in the form of a set of ACPI
 385   resource descriptors.
 386
 387   @param  This                  A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
 388   @param  Resources             A pointer to the resource descriptors that describe the current
 389                                 configuration of this PCI root bridge.
 390
 391   @retval EFI_SUCCESS           The current configuration of this PCI root bridge was returned in
 392                                 Resources.
 393   @retval EFI_UNSUPPORTED       The current configuration of this PCI root bridge could not be
 394                                 retrieved.
 395
 396 **/
 397 typedef
 398 EFI_STATUS
 399 (EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION)(
 400   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL          *This,
 401   OUT VOID                                     **Resources
 402   );
 403
 404 ///
 405 /// Provides the basic Memory, I/O, PCI configuration, and DMA interfaces that are
 406 /// used to abstract accesses to PCI controllers behind a PCI Root Bridge Controller.
 407 ///
 408 struct _EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL {
 409   ///
 410   /// The EFI_HANDLE of the PCI Host Bridge of which this PCI Root Bridge is a member.
 411   ///
 412   EFI_HANDLE                                         ParentHandle;
 413   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM        PollMem;
 414   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM        PollIo;
 415   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS             Mem;
 416   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS             Io;
 417   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS             Pci;
 418   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_COPY_MEM           CopyMem;
 419   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_MAP                Map;
 420   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_UNMAP              Unmap;
 421   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ALLOCATE_BUFFER    AllocateBuffer;
 422   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FREE_BUFFER        FreeBuffer;
 423   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FLUSH              Flush;
 424   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GET_ATTRIBUTES     GetAttributes;
 425   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_SET_ATTRIBUTES     SetAttributes;
 426   EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION      Configuration;
 427
 428   ///
 429   /// The segment number that this PCI root bridge resides.
 430   ///
 431   UINT32                                             SegmentNumber;
 432 };
 433
 434 extern EFI_GUID  gEfiPciRootBridgeIoProtocolGuid;
 435
 436 #endif