2 The Header file of the Pci Host Bridge Driver
4 Copyright (C) 2015, Red Hat, Inc.
5 Copyright (c) 2008 - 2010, Intel Corporation. All rights reserved.<BR>
7 This program and the accompanying materials are licensed and made available
8 under the terms and conditions of the BSD License which accompanies this
9 distribution. The full text of the license may be found at
10 http://opensource.org/licenses/bsd-license.php
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #ifndef _PCI_HOST_BRIDGE_H_
17 #define _PCI_HOST_BRIDGE_H_
21 #include <IndustryStandard/Pci.h>
22 #include <IndustryStandard/Acpi.h>
24 #include <Protocol/PciHostBridgeResourceAllocation.h>
25 #include <Protocol/PciRootBridgeIo.h>
26 #include <Protocol/Metronome.h>
27 #include <Protocol/DevicePath.h>
30 #include <Library/BaseLib.h>
31 #include <Library/DebugLib.h>
32 #include <Library/BaseMemoryLib.h>
33 #include <Library/MemoryAllocationLib.h>
34 #include <Library/UefiLib.h>
35 #include <Library/UefiBootServicesTableLib.h>
36 #include <Library/DxeServicesTableLib.h>
37 #include <Library/DevicePathLib.h>
38 #include <Library/IoLib.h>
39 #include <Library/PciLib.h>
41 #define MAX_PCI_DEVICE_NUMBER 31
42 #define MAX_PCI_FUNCTION_NUMBER 7
43 #define MAX_PCI_REG_ADDRESS 0xFF
51 #define PCI_HOST_BRIDGE_SIGNATURE SIGNATURE_32('e', 'h', 's', 't')
54 EFI_HANDLE HostBridgeHandle
;
56 BOOLEAN ResourceSubmited
;
58 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL ResAlloc
;
59 } PCI_HOST_BRIDGE_INSTANCE
;
61 #define INSTANCE_FROM_RESOURCE_ALLOCATION_THIS(a) \
62 CR(a, PCI_HOST_BRIDGE_INSTANCE, ResAlloc, PCI_HOST_BRIDGE_SIGNATURE)
65 // HostBridge Resource Allocation interface
69 These are the notifications from the PCI bus driver that it is about to enter
70 a certain phase of the PCI enumeration process.
72 This member function can be used to notify the host bridge driver to perform
73 specific actions, including any chipset-specific initialization, so that the
74 chipset is ready to enter the next phase. Eight notification points are
75 defined at this time. See belows:
77 EfiPciHostBridgeBeginEnumeration Resets the host bridge PCI apertures
78 and internal data structures. The PCI
79 enumerator should issue this
80 notification before starting a fresh
81 enumeration process. Enumeration
82 cannot be restarted after sending any
83 other notification such as
84 EfiPciHostBridgeBeginBusAllocation.
86 EfiPciHostBridgeBeginBusAllocation The bus allocation phase is about to
87 begin. No specific action is required
88 here. This notification can be used to
89 perform any chipset-specific
92 EfiPciHostBridgeEndBusAllocation The bus allocation and bus programming
93 phase is complete. No specific action
94 is required here. This notification
95 can be used to perform any
96 chipset-specific programming.
98 EfiPciHostBridgeBeginResourceAllocation
99 The resource allocation phase is about
100 to begin. No specific action is
101 required here. This notification can
102 be used to perform any
103 chipset-specific programming.
105 EfiPciHostBridgeAllocateResources Allocates resources per previously
106 submitted requests for all the PCI
107 root bridges. These resource settings
108 are returned on the next call to
109 GetProposedResources(). Before calling
110 NotifyPhase() with a Phase of
111 EfiPciHostBridgeAllocateResource, the
112 PCI bus enumerator is responsible for
113 gathering I/O and memory requests for
114 all the PCI root bridges and
115 submitting these requests using
116 SubmitResources(). This function pads
117 the resource amount to suit the root
118 bridge hardware, takes care of
119 dependencies between the PCI root
120 bridges, and calls the Global
121 Coherency Domain (GCD) with the
122 allocation request. In the case of
123 padding, the allocated range could be
124 bigger than what was requested.
126 EfiPciHostBridgeSetResources Programs the host bridge hardware to
127 decode previously allocated resources
128 (proposed resources) for all the PCI
129 root bridges. After the hardware is
130 programmed, reassigning resources will
131 not be supported. The bus settings are
134 EfiPciHostBridgeFreeResources Deallocates resources that were
135 previously allocated for all the PCI
136 root bridges and resets the I/O and
137 memory apertures to their initial
138 state. The bus settings are not
139 affected. If the request to allocate
140 resources fails, the PCI enumerator
141 can use this notification to
142 deallocate previous resources, adjust
143 the requests, and retry allocation.
145 EfiPciHostBridgeEndResourceAllocation The resource allocation phase is
146 completed. No specific action is
147 required here. This notification can
148 be used to perform any chipsetspecific
151 @param[in] This The instance pointer of
152 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
154 @param[in] Phase The phase during enumeration
156 @retval EFI_NOT_READY This phase cannot be entered at this time. For
157 example, this error is valid for a Phase of
158 EfiPciHostBridgeAllocateResources if
159 SubmitResources() has not been called for one
160 or more PCI root bridges before this call
162 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.
163 This error is valid for a Phase of
164 EfiPciHostBridgeSetResources.
166 @retval EFI_INVALID_PARAMETER Invalid phase parameter
168 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a
169 lack of resources. This error is valid for a
170 Phase of EfiPciHostBridgeAllocateResources if
171 the previously submitted resource requests
172 cannot be fulfilled or were only partially
175 @retval EFI_SUCCESS The notification was accepted without any
181 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
182 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase
186 Return the device handle of the next PCI root bridge that is associated with
189 This function is called multiple times to retrieve the device handles of all
190 the PCI root bridges that are associated with this PCI host bridge. Each PCI
191 host bridge is associated with one or more PCI root bridges. On each call,
192 the handle that was returned by the previous call is passed into the
193 interface, and on output the interface returns the device handle of the next
194 PCI root bridge. The caller can use the handle to obtain the instance of the
195 EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL for that root bridge. When there are no more
196 PCI root bridges to report, the interface returns EFI_NOT_FOUND. A PCI
197 enumerator must enumerate the PCI root bridges in the order that they are
198 returned by this function.
200 For D945 implementation, there is only one root bridge in PCI host bridge.
202 @param[in] This The instance pointer of
203 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
205 @param[in, out] RootBridgeHandle Returns the device handle of the next PCI
208 @retval EFI_SUCCESS If parameter RootBridgeHandle = NULL, then
209 return the first Rootbridge handle of the
210 specific Host bridge and return EFI_SUCCESS.
212 @retval EFI_NOT_FOUND Can not find the any more root bridge in
213 specific host bridge.
215 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not an EFI_HANDLE that was
216 returned on a previous call to
222 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
223 IN OUT EFI_HANDLE
*RootBridgeHandle
227 Returns the allocation attributes of a PCI root bridge.
229 The function returns the allocation attributes of a specific PCI root bridge.
230 The attributes can vary from one PCI root bridge to another. These attributes
231 are different from the decode-related attributes that are returned by the
232 EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.GetAttributes() member function. The
233 RootBridgeHandle parameter is used to specify the instance of the PCI root
234 bridge. The device handles of all the root bridges that are associated with
235 this host bridge must be obtained by calling GetNextRootBridge(). The
236 attributes are static in the sense that they do not change during or after
237 the enumeration process. The hardware may provide mechanisms to change the
238 attributes on the fly, but such changes must be completed before
239 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is installed. The permitted
240 values of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTES are defined in
241 "Related Definitions" below. The caller uses these attributes to combine
242 multiple resource requests.
244 For example, if the flag EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM is set, the PCI
245 bus enumerator needs to include requests for the prefetchable memory in the
246 nonprefetchable memory pool and not request any prefetchable memory.
248 Attribute Description
249 ------------------------------------ ---------------------------------------
250 EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM If this bit is set, then the PCI root
251 bridge does not support separate
252 windows for nonprefetchable and
253 prefetchable memory. A PCI bus driver
254 needs to include requests for
255 prefetchable memory in the
256 nonprefetchable memory pool.
258 EFI_PCI_HOST_BRIDGE_MEM64_DECODE If this bit is set, then the PCI root
259 bridge supports 64-bit memory windows.
260 If this bit is not set, the PCI bus
261 driver needs to include requests for a
262 64-bit memory address in the
263 corresponding 32-bit memory pool.
265 @param[in] This The instance pointer of
266 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
268 @param[in] RootBridgeHandle The device handle of the PCI root bridge in
269 which the caller is interested. Type
270 EFI_HANDLE is defined in
271 InstallProtocolInterface() in the UEFI 2.0
274 @param[out] Attributes The pointer to attribte of root bridge, it is
277 @retval EFI_INVALID_PARAMETER Attribute pointer is NULL
279 @retval EFI_INVALID_PARAMETER RootBridgehandle is invalid.
281 @retval EFI_SUCCESS Success to get attribute of interested root
287 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
288 IN EFI_HANDLE RootBridgeHandle
,
289 OUT UINT64
*Attributes
293 Sets up the specified PCI root bridge for the bus enumeration process.
295 This member function sets up the root bridge for bus enumeration and returns
296 the PCI bus range over which the search should be performed in ACPI 2.0
297 resource descriptor format.
300 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
303 @param[in] RootBridgeHandle The PCI Root Bridge to be set up.
305 @param[out] Configuration Pointer to the pointer to the PCI bus resource
308 @retval EFI_INVALID_PARAMETER Invalid Root bridge's handle
310 @retval EFI_OUT_OF_RESOURCES Fail to allocate ACPI resource descriptor tag.
312 @retval EFI_SUCCESS Sucess to allocate ACPI resource descriptor.
317 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
318 IN EFI_HANDLE RootBridgeHandle
,
319 OUT VOID
**Configuration
323 Programs the PCI root bridge hardware so that it decodes the specified PCI
326 This member function programs the specified PCI root bridge to decode the bus
327 range that is specified by the input parameter Configuration.
328 The bus range information is specified in terms of the ACPI 2.0 resource
332 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
335 @param[in] RootBridgeHandle The PCI Root Bridge whose bus range is to be
338 @param[in] Configuration The pointer to the PCI bus resource descriptor
340 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge
343 @retval EFI_INVALID_PARAMETER Configuration is NULL.
345 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI
346 2.0 resource descriptor.
348 @retval EFI_INVALID_PARAMETER Configuration does not include a valid ACPI
349 2.0 bus resource descriptor.
351 @retval EFI_INVALID_PARAMETER Configuration includes valid ACPI 2.0 resource
352 descriptors other than bus descriptors.
354 @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid
355 ACPI resource descriptors.
357 @retval EFI_INVALID_PARAMETER "Address Range Minimum" is invalid for this
360 @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this
363 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.
365 @retval EFI_SUCCESS The bus range for the PCI root bridge was
371 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
372 IN EFI_HANDLE RootBridgeHandle
,
373 IN VOID
*Configuration
377 Submits the I/O and memory resource requirements for the specified PCI root
380 This function is used to submit all the I/O and memory resources that are
381 required by the specified PCI root bridge. The input parameter Configuration
382 is used to specify the following:
383 - The various types of resources that are required
384 - The associated lengths in terms of ACPI 2.0 resource descriptor format
386 @param[in] This Pointer to the
387 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
390 @param[in] RootBridgeHandle The PCI root bridge whose I/O and memory
391 resource requirements are being submitted.
393 @param[in] Configuration The pointer to the PCI I/O and PCI memory
396 @retval EFI_SUCCESS The I/O and memory resource requests for a PCI
397 root bridge were accepted.
399 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge
402 @retval EFI_INVALID_PARAMETER Configuration is NULL.
404 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI
405 2.0 resource descriptor.
407 @retval EFI_INVALID_PARAMETER Configuration includes requests for one or
408 more resource types that are not supported by
409 this PCI root bridge. This error will happen
410 if the caller did not combine resources
411 according to Attributes that were returned by
412 GetAllocAttributes().
414 @retval EFI_INVALID_PARAMETER Address Range Maximum" is invalid.
416 @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this PCI
419 @retval EFI_INVALID_PARAMETER "Address Space Granularity" is invalid for
420 this PCI root bridge.
425 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
426 IN EFI_HANDLE RootBridgeHandle
,
427 IN VOID
*Configuration
431 Returns the proposed resource settings for the specified PCI root bridge.
433 This member function returns the proposed resource settings for the
434 specified PCI root bridge. The proposed resource settings are prepared when
435 NotifyPhase() is called with a Phase of EfiPciHostBridgeAllocateResources.
436 The output parameter Configuration specifies the following:
437 - The various types of resources, excluding bus resources, that are
439 - The associated lengths in terms of ACPI 2.0 resource descriptor format
441 @param[in] This Pointer to the
442 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
445 @param[in] RootBridgeHandle The PCI root bridge handle. Type EFI_HANDLE is
446 defined in InstallProtocolInterface() in the
447 UEFI 2.0 Specification.
449 @param[out] Configuration The pointer to the pointer to the PCI I/O and
450 memory resource descriptor.
452 @retval EFI_SUCCESS The requested parameters were returned.
454 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge
457 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.
459 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a
464 GetProposedResources(
465 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
466 IN EFI_HANDLE RootBridgeHandle
,
467 OUT VOID
**Configuration
471 Provides the hooks from the PCI bus driver to every PCI controller
472 (device/function) at various stages of the PCI enumeration process that allow
473 the host bridge driver to preinitialize individual PCI controllers before
476 This function is called during the PCI enumeration process. No specific
477 action is expected from this member function. It allows the host bridge
478 driver to preinitialize individual PCI controllers before enumeration.
480 @param This Pointer to the
481 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
484 @param RootBridgeHandle The associated PCI root bridge handle. Type
485 EFI_HANDLE is defined in InstallProtocolInterface()
486 in the UEFI 2.0 Specification.
488 @param PciAddress The address of the PCI device on the PCI bus. This
489 address can be passed to the
490 EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL member functions to
491 access the PCI configuration space of the device.
492 See Table 12-1 in the UEFI 2.0 Specification for the
494 EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS.
496 @param Phase The phase of the PCI device enumeration.
498 @retval EFI_SUCCESS The requested parameters were returned.
500 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge
503 @retval EFI_INVALID_PARAMETER Phase is not a valid phase that is defined
505 EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE.
507 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.
508 The PCI enumerator should not enumerate this
509 device, including its child devices if it is
514 PreprocessController (
515 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
516 IN EFI_HANDLE RootBridgeHandle
,
517 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress
,
518 IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase
523 // Define resource status constant
525 #define EFI_RESOURCE_NONEXISTENT 0xFFFFFFFFFFFFFFFFULL
526 #define EFI_RESOURCE_LESS 0xFFFFFFFFFFFFFFFEULL
530 // Driver Instance Data Prototypes
534 EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_OPERATION Operation
;
537 EFI_PHYSICAL_ADDRESS HostAddress
;
538 EFI_PHYSICAL_ADDRESS MappedHostAddress
;
542 ACPI_HID_DEVICE_PATH AcpiDevicePath
;
543 EFI_DEVICE_PATH_PROTOCOL EndDevicePath
;
544 } EFI_PCI_ROOT_BRIDGE_DEVICE_PATH
;
555 } PCI_ROOT_BRIDGE_RESOURCE_APERTURE
;
576 PCI_RESOURCE_TYPE Type
;
585 EFI_ACPI_ADDRESS_SPACE_DESCRIPTOR SpaceDesc
[TypeMax
];
586 EFI_ACPI_END_TAG_DESCRIPTOR EndDesc
;
587 } RESOURCE_CONFIGURATION
;
590 #define PCI_ROOT_BRIDGE_SIGNATURE SIGNATURE_32('e', '2', 'p', 'b')
596 UINT64 RootBridgeAttrib
;
601 // Specific for this memory controller: Bus, I/O, Mem
603 PCI_RES_NODE ResAllocNode
[6];
606 // Addressing for Memory and I/O and Bus arrange
615 EFI_PCI_ROOT_BRIDGE_DEVICE_PATH DevicePath
;
616 EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL Io
;
618 RESOURCE_CONFIGURATION ConfigBuffer
;
619 } PCI_ROOT_BRIDGE_INSTANCE
;
623 // Driver Instance Data Macros
625 #define DRIVER_INSTANCE_FROM_PCI_ROOT_BRIDGE_IO_THIS(a) \
626 CR(a, PCI_ROOT_BRIDGE_INSTANCE, Io, PCI_ROOT_BRIDGE_SIGNATURE)
629 #define DRIVER_INSTANCE_FROM_LIST_ENTRY(a) \
630 CR(a, PCI_ROOT_BRIDGE_INSTANCE, Link, PCI_ROOT_BRIDGE_SIGNATURE)
634 Construct the Pci Root Bridge Io protocol
636 @param Protocol Point to protocol instance
637 @param HostBridgeHandle Handle of host bridge
638 @param Attri Attribute of host bridge
639 @param ResAperture ResourceAperture for host bridge
641 @retval EFI_SUCCESS Success to initialize the Pci Root Bridge.
644 RootBridgeConstructor (
645 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
*Protocol
,
646 IN EFI_HANDLE HostBridgeHandle
,
648 IN PCI_ROOT_BRIDGE_RESOURCE_APERTURE
*ResAperture