2 This file declares Pci Host Bridge Resource Allocation Protocol which
3 Provides the basic interfaces to abstract a PCI host bridge resource allocation.
4 This protocol is mandatory if the system includes PCI devices.
6 Copyright (c) 2007 - 2009, Intel Corporation
7 All rights reserved. This program and the accompanying materials
8 are licensed and made available under the terms and conditions of the BSD License
9 which accompanies this 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.
15 @par Revision Reference:
16 This protocol is defined in Framework of EFI Pci Host Bridge Resource Allocation Protocol Spec
21 #ifndef _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_
22 #define _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_
24 #include <Protocol/PciRootBridgeIo.h>
26 #define EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GUID \
27 { 0xCF8034BE, 0x6768, 0x4d8b, {0xB7,0x39,0x7C,0xCE,0x68,0x3A,0x9F,0xBE }}
30 typedef struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
;
34 // EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTES
37 /// If this bit is set, then the PCI Root Bridge does not
38 /// support separate windows for Non-prefetchable and Prefetchable
39 /// memory. A PCI bus driver needs to include requests for Prefetchable
40 /// memory in the Non-prefetchable memory pool.
42 #define EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM 1
45 /// If this bit is set, then the PCI Root Bridge supports
46 /// 64 bit memory windows. If this bit is not set,
47 /// the PCI bus driver needs to include requests for 64 bit
48 /// memory address in the corresponding 32 bit memory pool.
50 #define EFI_PCI_HOST_BRIDGE_MEM64_DECODE 2
52 typedef UINT64 EFI_RESOURCE_ALLOCATION_STATUS
;
55 /// The request of this resource type could be fulfilled.
57 #define EFI_RESOURCE_SATISFIED 0x0000000000000000ULL
60 /// The request of this resource type could not be fulfilled for its
61 /// absence in the host bridge resource pool.
63 #define EFI_RESOURCE_NOT_SATISFIED 0xFFFFFFFFFFFFFFFFULL
66 // EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE
70 /// Reset the host bridge PCI apertures and internal data structures.
71 /// PCI enumerator should issue this notification before starting fresh
72 /// enumeration process. Enumeration cannot be restarted after sending
73 /// any other notification such as EfiPciHostBridgeBeginBusAllocation.
75 EfiPciHostBridgeBeginEnumeration
,
78 /// The bus allocation phase is about to begin. No specific action
79 /// is required here. This notification can be used to perform any
80 /// chipset specific programming.
82 EfiPciHostBridgeBeginBusAllocation
,
85 /// The bus allocation and bus programming phase is complete. No specific
86 /// action is required here. This notification can be used to perform any
87 /// chipset specific programming.
89 EfiPciHostBridgeEndBusAllocation
,
92 /// The resource allocation phase is about to begin.No specific action is
93 /// required here. This notification can be used to perform any chipset specific programming.
95 EfiPciHostBridgeBeginResourceAllocation
,
98 /// Allocate resources per previously submitted requests for all the PCI Root
99 /// Bridges. These resource settings are returned on the next call to
100 /// GetProposedResources().
102 EfiPciHostBridgeAllocateResources
,
105 /// Program the Host Bridge hardware to decode previously allocated resources
106 /// (proposed resources) for all the PCI Root Bridges.
108 EfiPciHostBridgeSetResources
,
111 /// De-allocate previously allocated resources previously for all the PCI
112 /// Root Bridges and reset the I/O and memory apertures to initial state.
114 EfiPciHostBridgeFreeResources
,
117 /// The resource allocation phase is completed. No specific action is required
118 /// here. This notification can be used to perform any chipset specific programming.
120 EfiPciHostBridgeEndResourceAllocation
121 } EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE
;
124 /// Definitions of 2 notification points.
128 /// This notification is only applicable to PCI-PCI bridges and
129 /// indicates that the PCI enumerator is about to begin enumerating
130 /// the bus behind the PCI-PCI Bridge. This notification is sent after
131 /// the primary bus number, the secondary bus number and the subordinate
132 /// bus number registers in the PCI-PCI Bridge are programmed to valid
133 /// (not necessary final) values
135 EfiPciBeforeChildBusEnumeration
,
138 /// This notification is sent before the PCI enumerator probes BAR registers
139 /// for every valid PCI function.
141 EfiPciBeforeResourceCollection
142 } EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE
;
145 These are the notifications from the PCI bus driver that it is about to enter a certain phase of the PCI
148 @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
150 @param Phase The phase during enumeration
152 @retval EFI_SUCCESS The notification was accepted without any errors.
153 @retval EFI_INVALID_PARAMETER The Phase is invalid.
154 @retval EFI_NOT_READY This phase cannot be entered at this time. For example, this error
155 is valid for a Phase of EfiPciHostBridgeAllocateResources if
156 SubmitResources() has not been called for one or more
157 PCI root bridges before this call.
158 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. This error is valid for
159 a Phase of EfiPciHostBridgeSetResources.
160 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
161 This error is valid for a Phase of EfiPciHostBridgeAllocateResources
162 if the previously submitted resource requests cannot be fulfilled or were only
168 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE
)(
169 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
170 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase
175 Returns the device handle of the next PCI root bridge that is associated with this host bridge.
177 @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
179 @param RootBridgeHandle Returns the device handle of the next PCI root bridge. On input, it holds the
180 RootBridgeHandle that was returned by the most recent call to
181 GetNextRootBridge(). If RootBridgeHandle is NULL on input, the handle
182 for the first PCI root bridge is returned.
184 @retval EFI_SUCCESS The requested attribute information was returned.
185 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not an EFI_HANDLE that was returned
186 on a previous call to GetNextRootBridge().
187 @retval EFI_NOT_FOUND There are no more PCI root bridge device handles.
192 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE
)(
193 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
194 IN OUT EFI_HANDLE
*RootBridgeHandle
199 Returns the allocation attributes of a PCI root bridge.
201 @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
203 @param RootBridgeHandle The device handle of the PCI root bridge in which the caller is interested.
204 @param Attribute The pointer to attributes of the PCI root bridge.
206 @retval EFI_SUCCESS The requested attribute information was returned.
207 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle.
208 @retval EFI_INVALID_PARAMETER Attributes is NULL.
213 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES
)(
214 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
215 IN EFI_HANDLE RootBridgeHandle
,
216 OUT UINT64
*Attributes
221 Sets up the specified PCI root bridge for the bus enumeration process.
223 @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
225 @param RootBridgeHandle The PCI root bridge to be set up.
226 @param Configuration Pointer to the pointer to the PCI bus resource descriptor.
228 @retval EFI_SUCCESS The PCI root bridge was set up and the bus range was returned in
230 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle.
231 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.
232 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
237 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION
)(
238 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
239 IN EFI_HANDLE RootBridgeHandle
,
240 OUT VOID
**Configuration
245 Programs the PCI root bridge hardware so that it decodes the specified PCI bus range.
247 @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
249 @param RootBridgeHandle The PCI root bridge whose bus range is to be programmed.
250 @param Configuration The pointer to the PCI bus resource descriptor..
252 @retval EFI_SUCCESS The bus range for the PCI root bridge was programmed.
253 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle.
254 @retval EFI_INVALID_PARAMETER Configuration is NULL
255 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0)
257 @retval EFI_INVALID_PARAMETER Configuration does not include a valid ACPI 2.0 bus resource
259 @retval EFI_INVALID_PARAMETER Configuration includes valid ACPI (2.0 & 3.0) resource
260 descriptors other than bus descriptors.
261 @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource
263 @retval EFI_INVALID_PARAMETER "Address Range Minimum" is invalid for this root bridge.
264 @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this root bridge.
265 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.
270 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS
)(
271 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
272 IN EFI_HANDLE RootBridgeHandle
,
273 IN VOID
*Configuration
278 Submits the I/O and memory resource requirements for the specified PCI root bridge.
280 @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
282 @param RootBridgeHandle The PCI root bridge whose I/O and memory resource requirements are being
284 @param Configuration The pointer to the PCI I/O and PCI memory resource descriptor.
286 @retval EFI_SUCCESS The I/O and memory resource requests for a PCI root bridge were
288 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle.
289 @retval EFI_INVALID_PARAMETER Configuration is NULL.
290 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0)
292 @retval EFI_INVALID_PARAMETER Configuration includes requests for one or more resource
293 types that are not supported by this PCI root bridge. This error will
294 happen if the caller did not combine resources according to
295 Attributes that were returned by GetAllocAttributes().
296 @retval EFI_INVALID_PARAMETER "Address Range Maximum" is invalid.
297 @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this PCI root bridge.
298 @retval EFI_INVALID_PARAMETER "Address Space Granularity" is invalid for this PCI root bridge.
303 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES
)(
304 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
305 IN EFI_HANDLE RootBridgeHandle
,
306 IN VOID
*Configuration
311 Returns the proposed resource settings for the specified PCI root bridge.
313 @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
315 @param RootBridgeHandle The PCI root bridge handle.
316 @param Configuration The pointer to the pointer to the PCI I/O and memory resource descriptor.
318 @retval EFI_SUCCESS The requested parameters were returned.
319 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle.
320 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.
321 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
326 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES
)(
327 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
328 IN EFI_HANDLE RootBridgeHandle
,
329 OUT VOID
**Configuration
335 Provides the hooks from the PCI bus driver to every PCI controller (device/function) at various
336 stages of the PCI enumeration process that allow the host bridge driver to preinitialize individual
337 PCI controllers before enumeration.
339 @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
340 @param RootBridgeHandle The associated PCI root bridge handle.
341 @param PciAddress The address of the PCI device on the PCI bus.
342 @param Phase The phase of the PCI device enumeration.
344 @retval EFI_SUCCESS The requested parameters were returned.
345 @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle.
346 @retval EFI_INVALID_PARAMETER Phase is not a valid phase that is defined in
347 EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE.
348 @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. The PCI enumerator
349 should not enumerate this device, including its child devices if it is
355 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER
)(
356 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
357 IN EFI_HANDLE RootBridgeHandle
,
358 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress
,
359 IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase
363 /// Provides the basic interfaces to abstract a PCI host bridge resource allocation.
365 struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
{
367 /// The notification from the PCI bus enumerator that it is about to enter
368 /// a certain phase during the enumeration process.
370 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE NotifyPhase
;
373 /// Retrieves the device handle for the next PCI root bridge that is produced by the
374 /// host bridge to which this instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is attached.
376 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE GetNextRootBridge
;
379 /// Retrieves the allocation-related attributes of a PCI root bridge.
381 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES GetAllocAttributes
;
384 /// Sets up a PCI root bridge for bus enumeration.
386 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION StartBusEnumeration
;
389 /// Sets up the PCI root bridge so that it decodes a specific range of bus numbers.
391 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS SetBusNumbers
;
394 /// Submits the resource requirements for the specified PCI root bridge.
396 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES SubmitResources
;
399 /// Returns the proposed resource assignment for the specified PCI root bridges.
401 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES GetProposedResources
;
404 /// Provides hooks from the PCI bus driver to every PCI controller
405 /// (device/function) at various stages of the PCI enumeration process that
406 /// allow the host bridge driver to preinitialize individual PCI controllers
407 /// before enumeration.
409 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER PreprocessController
;
412 extern EFI_GUID gEfiPciHostBridgeResourceAllocationProtocolGuid
;