2 The Header file of the Pci Host Bridge Driver
4 Copyright (c) 2008 - 2010, Intel Corporation. All rights reserved.<BR>
6 This program and the accompanying materials are licensed and made available
7 under the terms and conditions of the BSD License which accompanies this
8 distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 #ifndef _PCI_HOST_BRIDGE_H_
16 #define _PCI_HOST_BRIDGE_H_
20 #include <IndustryStandard/Pci.h>
21 #include <IndustryStandard/Acpi.h>
23 #include <Protocol/PciHostBridgeResourceAllocation.h>
24 #include <Protocol/PciRootBridgeIo.h>
25 #include <Protocol/Metronome.h>
26 #include <Protocol/DevicePath.h>
29 #include <Library/BaseLib.h>
30 #include <Library/DebugLib.h>
31 #include <Library/BaseMemoryLib.h>
32 #include <Library/MemoryAllocationLib.h>
33 #include <Library/UefiLib.h>
34 #include <Library/UefiBootServicesTableLib.h>
35 #include <Library/DxeServicesTableLib.h>
36 #include <Library/DevicePathLib.h>
37 #include <Library/IoLib.h>
38 #include <Library/PciLib.h>
41 // Hard code the host bridge number in the platform.
42 // In this chipset, there is only one host bridge.
44 #define HOST_BRIDGE_NUMBER 1
46 #define MAX_PCI_DEVICE_NUMBER 31
47 #define MAX_PCI_FUNCTION_NUMBER 7
48 #define MAX_PCI_REG_ADDRESS 0xFF
56 #define PCI_HOST_BRIDGE_SIGNATURE SIGNATURE_32('e', 'h', 's', 't')
59 EFI_HANDLE HostBridgeHandle
;
60 UINTN RootBridgeNumber
;
62 BOOLEAN ResourceSubmited
;
64 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL ResAlloc
;
65 } PCI_HOST_BRIDGE_INSTANCE
;
67 #define INSTANCE_FROM_RESOURCE_ALLOCATION_THIS(a) \
68 CR(a, PCI_HOST_BRIDGE_INSTANCE, ResAlloc, PCI_HOST_BRIDGE_SIGNATURE)
71 // HostBridge Resource Allocation interface
75 These are the notifications from the PCI bus driver that it is about to enter
76 a certain phase of the PCI enumeration process.
78 This member function can be used to notify the host bridge driver to perform
79 specific actions, including any chipset-specific initialization, so that the
80 chipset is ready to enter the next phase. Eight notification points are
81 defined at this time. See belows:
83 EfiPciHostBridgeBeginEnumeration Resets the host bridge PCI apertures
84 and internal data structures. The PCI
85 enumerator should issue this
86 notification before starting a fresh
87 enumeration process. Enumeration
88 cannot be restarted after sending any
89 other notification such as
90 EfiPciHostBridgeBeginBusAllocation.
92 EfiPciHostBridgeBeginBusAllocation The bus allocation phase is about to
93 begin. No specific action is required
94 here. This notification can be used to
95 perform any chipset-specific
98 EfiPciHostBridgeEndBusAllocation The bus allocation and bus programming
99 phase is complete. No specific action
100 is required here. This notification
101 can be used to perform any
102 chipset-specific programming.
104 EfiPciHostBridgeBeginResourceAllocation
105 The resource allocation phase is about
106 to begin. No specific action is
107 required here. This notification can
108 be used to perform any
109 chipset-specific programming.
111 EfiPciHostBridgeAllocateResources Allocates resources per previously
112 submitted requests for all the PCI
113 root bridges. These resource settings
114 are returned on the next call to
115 GetProposedResources(). Before calling
116 NotifyPhase() with a Phase of
117 EfiPciHostBridgeAllocateResource, the
118 PCI bus enumerator is responsible for
119 gathering I/O and memory requests for
120 all the PCI root bridges and
121 submitting these requests using
122 SubmitResources(). This function pads
123 the resource amount to suit the root
124 bridge hardware, takes care of
125 dependencies between the PCI root
126 bridges, and calls the Global
127 Coherency Domain (GCD) with the
128 allocation request. In the case of
129 padding, the allocated range could be
130 bigger than what was requested.
132 EfiPciHostBridgeSetResources Programs the host bridge hardware to
133 decode previously allocated resources
134 (proposed resources) for all the PCI
135 root bridges. After the hardware is
136 programmed, reassigning resources will
137 not be supported. The bus settings are
140 EfiPciHostBridgeFreeResources Deallocates resources that were
141 previously allocated for all the PCI
142 root bridges and resets the I/O and
143 memory apertures to their initial
144 state. The bus settings are not
145 affected. If the request to allocate
146 resources fails, the PCI enumerator
147 can use this notification to
148 deallocate previous resources, adjust
149 the requests, and retry allocation.
151 EfiPciHostBridgeEndResourceAllocation The resource allocation phase is
152 completed. No specific action is
153 required here. This notification can
154 be used to perform any chipsetspecific
157 @param[in] This The instance pointer of
158 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
160 @param[in] Phase The phase during enumeration
162 @retval EFI_NOT_READY This phase cannot be entered at this time. For
163 example, this error is valid for a Phase of
164 EfiPciHostBridgeAllocateResources if
165 SubmitResources() has not been called for one
166 or more PCI root bridges before this call
168 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.
169 This error is valid for a Phase of
170 EfiPciHostBridgeSetResources.
172 @retval EFI_INVALID_PARAMETER Invalid phase parameter
174 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a
175 lack of resources. This error is valid for a
176 Phase of EfiPciHostBridgeAllocateResources if
177 the previously submitted resource requests
178 cannot be fulfilled or were only partially
181 @retval EFI_SUCCESS The notification was accepted without any
187 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
188 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase
192 Return the device handle of the next PCI root bridge that is associated with
195 This function is called multiple times to retrieve the device handles of all
196 the PCI root bridges that are associated with this PCI host bridge. Each PCI
197 host bridge is associated with one or more PCI root bridges. On each call,
198 the handle that was returned by the previous call is passed into the
199 interface, and on output the interface returns the device handle of the next
200 PCI root bridge. The caller can use the handle to obtain the instance of the
201 EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL for that root bridge. When there are no more
202 PCI root bridges to report, the interface returns EFI_NOT_FOUND. A PCI
203 enumerator must enumerate the PCI root bridges in the order that they are
204 returned by this function.
206 For D945 implementation, there is only one root bridge in PCI host bridge.
208 @param[in] This The instance pointer of
209 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
211 @param[in, out] RootBridgeHandle Returns the device handle of the next PCI
214 @retval EFI_SUCCESS If parameter RootBridgeHandle = NULL, then
215 return the first Rootbridge handle of the
216 specific Host bridge and return EFI_SUCCESS.
218 @retval EFI_NOT_FOUND Can not find the any more root bridge in
219 specific host bridge.
221 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not an EFI_HANDLE that was
222 returned on a previous call to
228 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
229 IN OUT EFI_HANDLE
*RootBridgeHandle
233 Returns the allocation attributes of a PCI root bridge.
235 The function returns the allocation attributes of a specific PCI root bridge.
236 The attributes can vary from one PCI root bridge to another. These attributes
237 are different from the decode-related attributes that are returned by the
238 EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.GetAttributes() member function. The
239 RootBridgeHandle parameter is used to specify the instance of the PCI root
240 bridge. The device handles of all the root bridges that are associated with
241 this host bridge must be obtained by calling GetNextRootBridge(). The
242 attributes are static in the sense that they do not change during or after
243 the enumeration process. The hardware may provide mechanisms to change the
244 attributes on the fly, but such changes must be completed before
245 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is installed. The permitted
246 values of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTES are defined in
247 "Related Definitions" below. The caller uses these attributes to combine
248 multiple resource requests.
250 For example, if the flag EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM is set, the PCI
251 bus enumerator needs to include requests for the prefetchable memory in the
252 nonprefetchable memory pool and not request any prefetchable memory.
254 Attribute Description
255 ------------------------------------ ---------------------------------------
256 EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM If this bit is set, then the PCI root
257 bridge does not support separate
258 windows for nonprefetchable and
259 prefetchable memory. A PCI bus driver
260 needs to include requests for
261 prefetchable memory in the
262 nonprefetchable memory pool.
264 EFI_PCI_HOST_BRIDGE_MEM64_DECODE If this bit is set, then the PCI root
265 bridge supports 64-bit memory windows.
266 If this bit is not set, the PCI bus
267 driver needs to include requests for a
268 64-bit memory address in the
269 corresponding 32-bit memory pool.
271 @param[in] This The instance pointer of
272 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
274 @param[in] RootBridgeHandle The device handle of the PCI root bridge in
275 which the caller is interested. Type
276 EFI_HANDLE is defined in
277 InstallProtocolInterface() in the UEFI 2.0
280 @param[out] Attributes The pointer to attribte of root bridge, it is
283 @retval EFI_INVALID_PARAMETER Attribute pointer is NULL
285 @retval EFI_INVALID_PARAMETER RootBridgehandle is invalid.
287 @retval EFI_SUCCESS Success to get attribute of interested root
293 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
294 IN EFI_HANDLE RootBridgeHandle
,
295 OUT UINT64
*Attributes
299 Sets up the specified PCI root bridge for the bus enumeration process.
301 This member function sets up the root bridge for bus enumeration and returns
302 the PCI bus range over which the search should be performed in ACPI 2.0
303 resource descriptor format.
306 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
309 @param[in] RootBridgeHandle The PCI Root Bridge to be set up.
311 @param[out] Configuration Pointer to the pointer to the PCI bus resource
314 @retval EFI_INVALID_PARAMETER Invalid Root bridge's handle
316 @retval EFI_OUT_OF_RESOURCES Fail to allocate ACPI resource descriptor tag.
318 @retval EFI_SUCCESS Sucess to allocate ACPI resource descriptor.
323 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
324 IN EFI_HANDLE RootBridgeHandle
,
325 OUT VOID
**Configuration
329 Programs the PCI root bridge hardware so that it decodes the specified PCI
332 This member function programs the specified PCI root bridge to decode the bus
333 range that is specified by the input parameter Configuration.
334 The bus range information is specified in terms of the ACPI 2.0 resource
338 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
341 @param[in] RootBridgeHandle The PCI Root Bridge whose bus range is to be
344 @param[in] Configuration The pointer to the PCI bus resource descriptor
346 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge
349 @retval EFI_INVALID_PARAMETER Configuration is NULL.
351 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI
352 2.0 resource descriptor.
354 @retval EFI_INVALID_PARAMETER Configuration does not include a valid ACPI
355 2.0 bus resource descriptor.
357 @retval EFI_INVALID_PARAMETER Configuration includes valid ACPI 2.0 resource
358 descriptors other than bus descriptors.
360 @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid
361 ACPI resource descriptors.
363 @retval EFI_INVALID_PARAMETER "Address Range Minimum" is invalid for this
366 @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this
369 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.
371 @retval EFI_SUCCESS The bus range for the PCI root bridge was
377 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
378 IN EFI_HANDLE RootBridgeHandle
,
379 IN VOID
*Configuration
383 Submits the I/O and memory resource requirements for the specified PCI root
386 This function is used to submit all the I/O and memory resources that are
387 required by the specified PCI root bridge. The input parameter Configuration
388 is used to specify the following:
389 - The various types of resources that are required
390 - The associated lengths in terms of ACPI 2.0 resource descriptor format
392 @param[in] This Pointer to the
393 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
396 @param[in] RootBridgeHandle The PCI root bridge whose I/O and memory
397 resource requirements are being submitted.
399 @param[in] Configuration The pointer to the PCI I/O and PCI memory
402 @retval EFI_SUCCESS The I/O and memory resource requests for a PCI
403 root bridge were accepted.
405 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge
408 @retval EFI_INVALID_PARAMETER Configuration is NULL.
410 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI
411 2.0 resource descriptor.
413 @retval EFI_INVALID_PARAMETER Configuration includes requests for one or
414 more resource types that are not supported by
415 this PCI root bridge. This error will happen
416 if the caller did not combine resources
417 according to Attributes that were returned by
418 GetAllocAttributes().
420 @retval EFI_INVALID_PARAMETER Address Range Maximum" is invalid.
422 @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this PCI
425 @retval EFI_INVALID_PARAMETER "Address Space Granularity" is invalid for
426 this PCI root bridge.
431 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
432 IN EFI_HANDLE RootBridgeHandle
,
433 IN VOID
*Configuration
437 Returns the proposed resource settings for the specified PCI root bridge.
439 This member function returns the proposed resource settings for the
440 specified PCI root bridge. The proposed resource settings are prepared when
441 NotifyPhase() is called with a Phase of EfiPciHostBridgeAllocateResources.
442 The output parameter Configuration specifies the following:
443 - The various types of resources, excluding bus resources, that are
445 - The associated lengths in terms of ACPI 2.0 resource descriptor format
447 @param[in] This Pointer to the
448 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
451 @param[in] RootBridgeHandle The PCI root bridge handle. Type EFI_HANDLE is
452 defined in InstallProtocolInterface() in the
453 UEFI 2.0 Specification.
455 @param[out] Configuration The pointer to the pointer to the PCI I/O and
456 memory resource descriptor.
458 @retval EFI_SUCCESS The requested parameters were returned.
460 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge
463 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.
465 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a
470 GetProposedResources(
471 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
472 IN EFI_HANDLE RootBridgeHandle
,
473 OUT VOID
**Configuration
477 Provides the hooks from the PCI bus driver to every PCI controller
478 (device/function) at various stages of the PCI enumeration process that allow
479 the host bridge driver to preinitialize individual PCI controllers before
482 This function is called during the PCI enumeration process. No specific
483 action is expected from this member function. It allows the host bridge
484 driver to preinitialize individual PCI controllers before enumeration.
486 @param This Pointer to the
487 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
490 @param RootBridgeHandle The associated PCI root bridge handle. Type
491 EFI_HANDLE is defined in InstallProtocolInterface()
492 in the UEFI 2.0 Specification.
494 @param PciAddress The address of the PCI device on the PCI bus. This
495 address can be passed to the
496 EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL member functions to
497 access the PCI configuration space of the device.
498 See Table 12-1 in the UEFI 2.0 Specification for the
500 EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS.
502 @param Phase The phase of the PCI device enumeration.
504 @retval EFI_SUCCESS The requested parameters were returned.
506 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge
509 @retval EFI_INVALID_PARAMETER Phase is not a valid phase that is defined
511 EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE.
513 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.
514 The PCI enumerator should not enumerate this
515 device, including its child devices if it is
520 PreprocessController (
521 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
522 IN EFI_HANDLE RootBridgeHandle
,
523 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress
,
524 IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase
529 // Define resource status constant
531 #define EFI_RESOURCE_NONEXISTENT 0xFFFFFFFFFFFFFFFFULL
532 #define EFI_RESOURCE_LESS 0xFFFFFFFFFFFFFFFEULL
536 // Driver Instance Data Prototypes
540 EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_OPERATION Operation
;
543 EFI_PHYSICAL_ADDRESS HostAddress
;
544 EFI_PHYSICAL_ADDRESS MappedHostAddress
;
548 ACPI_HID_DEVICE_PATH AcpiDevicePath
;
549 EFI_DEVICE_PATH_PROTOCOL EndDevicePath
;
550 } EFI_PCI_ROOT_BRIDGE_DEVICE_PATH
;
561 } PCI_ROOT_BRIDGE_RESOURCE_APERTURE
;
582 PCI_RESOURCE_TYPE Type
;
589 #define PCI_ROOT_BRIDGE_SIGNATURE SIGNATURE_32('e', '2', 'p', 'b')
595 UINT64 RootBridgeAttrib
;
600 // Specific for this memory controller: Bus, I/O, Mem
602 PCI_RES_NODE ResAllocNode
[6];
605 // Addressing for Memory and I/O and Bus arrange
614 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
615 EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL Io
;
617 } PCI_ROOT_BRIDGE_INSTANCE
;
621 // Driver Instance Data Macros
623 #define DRIVER_INSTANCE_FROM_PCI_ROOT_BRIDGE_IO_THIS(a) \
624 CR(a, PCI_ROOT_BRIDGE_INSTANCE, Io, PCI_ROOT_BRIDGE_SIGNATURE)
627 #define DRIVER_INSTANCE_FROM_LIST_ENTRY(a) \
628 CR(a, PCI_ROOT_BRIDGE_INSTANCE, Link, PCI_ROOT_BRIDGE_SIGNATURE)
632 Construct the Pci Root Bridge Io protocol
634 @param Protocol Point to protocol instance
635 @param HostBridgeHandle Handle of host bridge
636 @param Attri Attribute of host bridge
637 @param ResAperture ResourceAperture for host bridge
639 @retval EFI_SUCCESS Success to initialize the Pci Root Bridge.
642 RootBridgeConstructor (
643 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
*Protocol
,
644 IN EFI_HANDLE HostBridgeHandle
,
646 IN PCI_ROOT_BRIDGE_RESOURCE_APERTURE
*ResAperture