iPXE
PciRootBridgeIo.h
Go to the documentation of this file.
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 - 2011, Intel Corporation. All rights reserved.<BR>
9  This program and the accompanying materials
10  are licensed and made available under the terms and conditions of the BSD License
11  which accompanies this distribution. The full text of the license may be found at
12  http://opensource.org/licenses/bsd-license.php
13 
14  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
15  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 
17 **/
18 
19 #ifndef __PCI_ROOT_BRIDGE_IO_H__
20 #define __PCI_ROOT_BRIDGE_IO_H__
21 
22 FILE_LICENCE ( BSD3 );
23 
25 
26 #define EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GUID \
27  { \
28  0x2f707ebb, 0x4a1a, 0x11d4, {0x9a, 0x38, 0x00, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
29  }
30 
32 
33 ///
34 /// *******************************************************
35 /// EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH
36 /// *******************************************************
37 ///
38 typedef enum {
53 
54 ///
55 /// *******************************************************
56 /// EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_OPERATION
57 /// *******************************************************
58 ///
59 typedef enum {
60  ///
61  /// A read operation from system memory by a bus master that is not capable of producing
62  /// PCI dual address cycles.
63  ///
65  ///
66  /// A write operation from system memory by a bus master that is not capable of producing
67  /// PCI dual address cycles.
68  ///
70  ///
71  /// Provides both read and write access to system memory by both the processor and a bus
72  /// master that is not capable of producing PCI dual address cycles.
73  ///
75  ///
76  /// A read operation from system memory by a bus master that is capable of producing PCI
77  /// dual address cycles.
78  ///
80  ///
81  /// A write operation to system memory by a bus master that is capable of producing PCI
82  /// dual address cycles.
83  ///
85  ///
86  /// Provides both read and write access to system memory by both the processor and a bus
87  /// master that is capable of producing PCI dual address cycles.
88  ///
92 
93 #define EFI_PCI_ATTRIBUTE_ISA_MOTHERBOARD_IO 0x0001
94 #define EFI_PCI_ATTRIBUTE_ISA_IO 0x0002
95 #define EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO 0x0004
96 #define EFI_PCI_ATTRIBUTE_VGA_MEMORY 0x0008
97 #define EFI_PCI_ATTRIBUTE_VGA_IO 0x0010
98 #define EFI_PCI_ATTRIBUTE_IDE_PRIMARY_IO 0x0020
99 #define EFI_PCI_ATTRIBUTE_IDE_SECONDARY_IO 0x0040
100 #define EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE 0x0080
101 #define EFI_PCI_ATTRIBUTE_MEMORY_CACHED 0x0800
102 #define EFI_PCI_ATTRIBUTE_MEMORY_DISABLE 0x1000
103 #define EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE 0x8000
104 #define EFI_PCI_ATTRIBUTE_ISA_IO_16 0x10000
105 #define EFI_PCI_ATTRIBUTE_VGA_PALETTE_IO_16 0x20000
106 #define EFI_PCI_ATTRIBUTE_VGA_IO_16 0x40000
107 
108 #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)
109 
110 #define EFI_PCI_ATTRIBUTE_INVALID_FOR_ALLOCATE_BUFFER (~EFI_PCI_ATTRIBUTE_VALID_FOR_ALLOCATE_BUFFER)
111 
112 #define EFI_PCI_ADDRESS(bus, dev, func, reg) \
113  (UINT64) ( \
114  (((UINTN) bus) << 24) | \
115  (((UINTN) dev) << 16) | \
116  (((UINTN) func) << 8) | \
117  (((UINTN) (reg)) < 256 ? ((UINTN) (reg)) : (UINT64) (LShiftU64 ((UINT64) (reg), 32))))
118 
119 typedef struct {
126 
127 /**
128  Reads from the I/O space of a PCI Root Bridge. Returns when either the polling exit criteria is
129  satisfied or after a defined duration.
130 
131  @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
132  @param Width Signifies the width of the memory or I/O operations.
133  @param Address The base address of the memory or I/O operations.
134  @param Mask Mask used for the polling criteria.
135  @param Value The comparison value used for the polling exit criteria.
136  @param Delay The number of 100 ns units to poll.
137  @param Result Pointer to the last value read from the memory location.
138 
139  @retval EFI_SUCCESS The last data returned from the access matched the poll exit criteria.
140  @retval EFI_TIMEOUT Delay expired before a match occurred.
141  @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
142  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
143 
144 **/
145 typedef
150  IN UINT64 Address,
151  IN UINT64 Mask,
152  IN UINT64 Value,
153  IN UINT64 Delay,
154  OUT UINT64 *Result
155  );
156 
157 /**
158  Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.
159 
160  @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
161  @param Width Signifies the width of the memory operations.
162  @param Address The base address of the memory operations.
163  @param Count The number of memory operations to perform.
164  @param Buffer For read operations, the destination buffer to store the results. For write
165  operations, the source buffer to write data from.
166 
167  @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
168  @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
169  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
170 
171 **/
172 typedef
177  IN UINT64 Address,
178  IN UINTN Count,
179  IN OUT VOID *Buffer
180  );
181 
182 typedef struct {
183  ///
184  /// Read PCI controller registers in the PCI root bridge memory space.
185  ///
187  ///
188  /// Write PCI controller registers in the PCI root bridge memory space.
189  ///
192 
193 /**
194  Enables a PCI driver to copy one region of PCI root bridge memory space to another region of PCI
195  root bridge memory space.
196 
197  @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance.
198  @param Width Signifies the width of the memory operations.
199  @param DestAddress The destination address of the memory operation.
200  @param SrcAddress The source address of the memory operation.
201  @param Count The number of memory operations to perform.
202 
203  @retval EFI_SUCCESS The data was copied from one memory region to another memory region.
204  @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
205  @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
206 
207 **/
208 typedef
213  IN UINT64 DestAddress,
214  IN UINT64 SrcAddress,
215  IN UINTN Count
216  );
217 
218 /**
219  Provides the PCI controller-specific addresses required to access system memory from a
220  DMA bus master.
221 
222  @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
223  @param Operation Indicates if the bus master is going to read or write to system memory.
224  @param HostAddress The system memory address to map to the PCI controller.
225  @param NumberOfBytes On input the number of bytes to map. On output the number of bytes
226  that were mapped.
227  @param DeviceAddress The resulting map address for the bus master PCI controller to use to
228  access the hosts HostAddress.
229  @param Mapping A resulting value to pass to Unmap().
230 
231  @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
232  @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
233  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
234  @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
235  @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.
236 
237 **/
238 typedef
243  IN VOID *HostAddress,
244  IN OUT UINTN *NumberOfBytes,
245  OUT EFI_PHYSICAL_ADDRESS *DeviceAddress,
246  OUT VOID **Mapping
247  );
248 
249 /**
250  Completes the Map() operation and releases any corresponding resources.
251 
252  @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
253  @param Mapping The mapping value returned from Map().
254 
255  @retval EFI_SUCCESS The range was unmapped.
256  @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
257  @retval EFI_DEVICE_ERROR The data was not committed to the target system memory.
258 
259 **/
260 typedef
264  IN VOID *Mapping
265  );
266 
267 /**
268  Allocates pages that are suitable for an EfiPciOperationBusMasterCommonBuffer or
269  EfiPciOperationBusMasterCommonBuffer64 mapping.
270 
271  @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
272  @param Type This parameter is not used and must be ignored.
273  @param MemoryType The type of memory to allocate, EfiBootServicesData or
274  EfiRuntimeServicesData.
275  @param Pages The number of pages to allocate.
276  @param HostAddress A pointer to store the base system memory address of the
277  allocated range.
278  @param Attributes The requested bit mask of attributes for the allocated range.
279 
280  @retval EFI_SUCCESS The requested memory pages were allocated.
281  @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are
282  MEMORY_WRITE_COMBINE and MEMORY_CACHED.
283  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
284  @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
285 
286 **/
287 typedef
292  IN EFI_MEMORY_TYPE MemoryType,
293  IN UINTN Pages,
294  IN OUT VOID **HostAddress,
295  IN UINT64 Attributes
296  );
297 
298 /**
299  Frees memory that was allocated with AllocateBuffer().
300 
301  @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
302  @param Pages The number of pages to free.
303  @param HostAddress The base system memory address of the allocated range.
304 
305  @retval EFI_SUCCESS The requested memory pages were freed.
306  @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
307  was not allocated with AllocateBuffer().
308 
309 **/
310 typedef
314  IN UINTN Pages,
315  IN VOID *HostAddress
316  );
317 
318 /**
319  Flushes all PCI posted write transactions from a PCI host bridge to system memory.
320 
321  @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
322 
323  @retval EFI_SUCCESS The PCI posted write transactions were flushed from the PCI host
324  bridge to system memory.
325  @retval EFI_DEVICE_ERROR The PCI posted write transactions were not flushed from the PCI
326  host bridge due to a hardware error.
327 
328 **/
329 typedef
333  );
334 
335 /**
336  Gets the attributes that a PCI root bridge supports setting with SetAttributes(), and the
337  attributes that a PCI root bridge is currently using.
338 
339  @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
340  @param Supports A pointer to the mask of attributes that this PCI root bridge supports
341  setting with SetAttributes().
342  @param Attributes A pointer to the mask of attributes that this PCI root bridge is currently
343  using.
344 
345  @retval EFI_SUCCESS If Supports is not NULL, then the attributes that the PCI root
346  bridge supports is returned in Supports. If Attributes is
347  not NULL, then the attributes that the PCI root bridge is currently
348  using is returned in Attributes.
349  @retval EFI_INVALID_PARAMETER Both Supports and Attributes are NULL.
350 
351 
352 **/
353 typedef
357  OUT UINT64 *Supports,
358  OUT UINT64 *Attributes
359  );
360 
361 /**
362  Sets attributes for a resource range on a PCI root bridge.
363 
364  @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
365  @param Attributes The mask of attributes to set.
366  @param ResourceBase A pointer to the base address of the resource range to be modified by the
367  attributes specified by Attributes.
368  @param ResourceLength A pointer to the length of the resource range to be modified by the
369  attributes specified by Attributes.
370 
371  @retval EFI_SUCCESS The set of attributes specified by Attributes for the resource
372  range specified by ResourceBase and ResourceLength
373  were set on the PCI root bridge, and the actual resource range is
374  returned in ResuourceBase and ResourceLength.
375  @retval EFI_UNSUPPORTED A bit is set in Attributes that is not supported by the PCI Root
376  Bridge.
377  @retval EFI_OUT_OF_RESOURCES There are not enough resources to set the attributes on the
378  resource range specified by BaseAddress and Length.
379  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
380 
381 **/
382 typedef
386  IN UINT64 Attributes,
387  IN OUT UINT64 *ResourceBase,
388  IN OUT UINT64 *ResourceLength
389  );
390 
391 /**
392  Retrieves the current resource settings of this PCI root bridge in the form of a set of ACPI 2.0
393  resource descriptors.
394 
395  @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
396  @param Resources A pointer to the ACPI 2.0 resource descriptors that describe the current
397  configuration of this PCI root bridge.
398 
399  @retval EFI_SUCCESS The current configuration of this PCI root bridge was returned in
400  Resources.
401  @retval EFI_UNSUPPORTED The current configuration of this PCI root bridge could not be
402  retrieved.
403 
404 **/
405 typedef
409  OUT VOID **Resources
410  );
411 
412 ///
413 /// Provides the basic Memory, I/O, PCI configuration, and DMA interfaces that are
414 /// used to abstract accesses to PCI controllers behind a PCI Root Bridge Controller.
415 ///
417  ///
418  /// The EFI_HANDLE of the PCI Host Bridge of which this PCI Root Bridge is a member.
419  ///
435 
436  ///
437  /// The segment number that this PCI root bridge resides.
438  ///
440 };
441 
443 
444 #endif
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ALLOCATE_BUFFER AllocateBuffer
A read operation from system memory by a bus master that is capable of producing PCI dual address cyc...
UINT16 Mask
Definition: Acpi10.h:161
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FLUSH Flush
UINT8 Type
Definition: Acpi10.h:141
128 bit buffer containing a unique identifier value.
Definition: Base.h:263
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS Mem
FILE_LICENCE(BSD3)
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)
Reads from the I/O space of a PCI Root Bridge.
EFI_HANDLE ParentHandle
The EFI_HANDLE of the PCI Host Bridge of which this PCI Root Bridge is a member.
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_UNMAP Unmap
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FREE_BUFFER FreeBuffer
EFI_GUID gEfiPciRootBridgeIoProtocolGuid
unsigned int UINT32
Definition: ProcessorBind.h:56
A write operation to system memory by a bus master that is capable of producing PCI dual address cycl...
unsigned char UINT8
Definition: ProcessorBind.h:62
UINT64 EFI_PHYSICAL_ADDRESS
64-bit physical memory address.
Definition: UefiBaseType.h:56
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION Configuration
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, IN OUT UINT64 *ResourceLength)
Sets attributes for a resource range on a PCI root bridge.
#define OUT
Definition: mlx_utils.h:29
EFI_MEMORY_TYPE
Enumeration of memory types introduced in UEFI.
Provides both read and write access to system memory by both the processor and a bus master that is c...
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM Write
Write PCI controller registers in the PCI root bridge memory space.
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH
Provides string functions, linked list functions, math functions, synchronization functions,...
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS Io
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_ACCESS Pci
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM PollIo
#define EFIAPI
UINT32 SegmentNumber
The segment number that this PCI root bridge resides.
SEGOFF16_t Buffer
Buffer address.
Definition: pxe_api.h:65
A write operation from system memory by a bus master that is not capable of producing PCI dual addres...
UINT64 UINTN
Unsigned value of native width.
Definition: ProcessorBind.h:71
A read operation from system memory by a bus master that is not capable of producing PCI dual address...
unsigned long Address
Definition: etherboot.h:21
EFI_STATUS(EFIAPI * EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_UNMAP)(IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This, IN VOID *Mapping)
Completes the Map() operation and releases any corresponding resources.
#define VOID
Undeclared type.
Definition: Base.h:319
unsigned long long UINT64
Definition: ProcessorBind.h:54
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_OPERATION
Provides both read and write access to system memory by both the processor and a bus master that is n...
#define IN
Definition: mlx_utils.h:28
Provides the basic Memory, I/O, PCI configuration, and DMA interfaces that are used to abstract acces...
EFI_ALLOCATE_TYPE
Enumeration of EFI memory allocation types.
Definition: UefiSpec.h:34
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_SET_ATTRIBUTES SetAttributes
EFI_STATUS(EFIAPI * EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_FLUSH)(IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This)
Flushes all PCI posted write transactions from a PCI host bridge to system memory.
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GET_ATTRIBUTES GetAttributes
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:35
EFI_STATUS(EFIAPI * EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION)(IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This, OUT VOID **Resources)
Retrieves the current resource settings of this PCI root bridge in the form of a set of ACPI 2....
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_COPY_MEM CopyMem
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, IN OUT VOID **HostAddress, IN UINT64 Attributes)
Allocates pages that are suitable for an EfiPciOperationBusMasterCommonBuffer or EfiPciOperationBusMa...
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM Read
Read PCI controller registers in the PCI root bridge memory space.
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)
Enables a PCI driver to copy one region of PCI root bridge memory space to another region of PCI root...
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_POLL_IO_MEM PollMem
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)
Frees memory that was allocated with AllocateBuffer().
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)
Provides the PCI controller-specific addresses required to access system memory from a DMA bus master...
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_MAP Map
Definition: efi.h:55
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)
Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.
Resources
Definition: 3c90x.h:226
EFI_STATUS(EFIAPI * EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_GET_ATTRIBUTES)(IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This, OUT UINT64 *Supports, OUT UINT64 *Attributes)
Gets the attributes that a PCI root bridge supports setting with SetAttributes(), and the attributes ...