2 This file declares Pci Host Bridge Resource Allocation Protocol which
3 Provides the basic interfaces to abstract a PCI host bridge resource allocation. This protocol is
4 mandatory if the system includes PCI devices.
6 Copyright (c) 2007, 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_
25 #include <Protocol/PciRootBridgeIo.h>
27 #define EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GUID \
28 { 0xCF8034BE, 0x6768, 0x4d8b, {0xB7,0x39,0x7C,0xCE,0x68,0x3A,0x9F,0xBE }}
31 typedef struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
;
35 // EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTES
38 // If this bit is set, then the PCI Root Bridge does not
39 // support separate windows for Non-prefetchable and Prefetchable
40 // memory. A PCI bus driver needs to include requests for Prefetchable
41 // memory in the Non-prefetchable memory pool.
43 #define EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM 1
46 // If this bit is set, then the PCI Root Bridge supports
47 // 64 bit memory windows. If this bit is not set,
48 // the PCI bus driver needs to include requests for 64 bit
49 // memory address in the corresponding 32 bit memory pool.
51 #define EFI_PCI_HOST_BRIDGE_MEM64_DECODE 2
53 typedef UINT64 EFI_RESOURCE_ALLOCATION_STATUS
;
55 /// The request of this resource type could be fulfilled.
56 #define EFI_RESOURCE_SATISFIED 0x0000000000000000ULL
58 /// The request of this resource type could not be fulfilled for its
59 /// absence in the host bridge resource pool.
60 #define EFI_RESOURCE_NOT_SATISFIED 0xFFFFFFFFFFFFFFFFULL
63 // EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE
66 EfiPciHostBridgeBeginEnumeration
,
67 EfiPciHostBridgeBeginBusAllocation
,
68 EfiPciHostBridgeEndBusAllocation
,
69 EfiPciHostBridgeBeginResourceAllocation
,
70 EfiPciHostBridgeAllocateResources
,
71 EfiPciHostBridgeSetResources
,
72 EfiPciHostBridgeFreeResources
,
73 EfiPciHostBridgeEndResourceAllocation
74 } EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE
;
77 // EfiPciHostBridgeBeginEnumeration
78 // Reset the host bridge PCI apertures and internal data structures.
79 // PCI enumerator should issue this notification before starting fresh
80 // enumeration process. Enumeration cannot be restarted after sending
81 // any other notification such as EfiPciHostBridgeBeginBusAllocation.
83 // EfiPciHostBridgeBeginBusAllocation
84 // The bus allocation phase is about to begin. No specific action
85 // is required here. This notification can be used to perform any
86 // chipset specific programming.
88 // EfiPciHostBridgeEndBusAllocation
89 // The bus allocation and bus programming phase is complete. No specific
90 // action is required here. This notification can be used to perform any
91 // chipset specific programming.
93 // EfiPciHostBridgeBeginResourceAllocation
94 // The resource allocation phase is about to begin.No specific action is
95 // required here. This notification can be used to perform any chipset specific programming.
97 // EfiPciHostBridgeAllocateResources
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 // EfiPciHostBridgeSetResources
103 // Program the Host Bridge hardware to decode previously allocated resources
104 // (proposed resources) for all the PCI Root Bridges.
106 // EfiPciHostBridgeFreeResources
107 // De-allocate previously allocated resources previously for all the PCI
108 // Root Bridges and reset the I/O and memory apertures to initial state.
110 // EfiPciHostBridgeEndResourceAllocation
111 // The resource allocation phase is completed. No specific action is required
112 // here. This notification can be used to perform any chipset specific programming.
117 // EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE
120 EfiPciBeforeChildBusEnumeration
,
121 EfiPciBeforeResourceCollection
122 } EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE
;
125 // EfiPciBeforeChildBusEnumeration
126 // This notification is only applicable to PCI-PCI bridges and
127 // indicates that the PCI enumerator is about to begin enumerating
128 // the bus behind the PCI-PCI Bridge. This notification is sent after
129 // the primary bus number, the secondary bus number and the subordinate
130 // bus number registers in the PCI-PCI Bridge are programmed to valid
131 // (not necessary final) values
133 // EfiPciBeforeResourceCollection
134 // This notification is sent before the PCI enumerator probes BAR registers
135 // for every valid PCI function.
140 Enter a certain phase of the PCI enumeration process
142 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance
143 @param Phase The phase during enumeration
145 @retval EFI_SUCCESS Success
146 @retval EFI_OUT_OF_RESOURCES If SubmitResources ( ) could not allocate resources
147 @retval EFI_INVALID_PARAMETER The Phase is invalid
148 @retval EFI_NOT_READY This phase cannot be entered at this time
149 @retval EFI_DEVICE_ERROR SetResources failed due to HW error.
154 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE
)(
155 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
156 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase
161 Return the device handle of the next PCI root bridge that is associated with
164 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
165 @param RootBridgeHandle Returns the device handle of the next PCI Root Bridge.
166 On input, it holds the RootBridgeHandle returned by the most
167 recent call to GetNextRootBridge().The handle for the first
168 PCI Root Bridge is returned if RootBridgeHandle is NULL on input
170 @retval EFI_SUCCESS Success
171 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
172 @retval EFI_NOT_FOUND There are no more PCI root bridge device handles.
177 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE
)(
178 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
179 IN OUT EFI_HANDLE
*RootBridgeHandle
184 Returns the attributes of a PCI Root Bridge.
186 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
187 @param RootBridgeHandle The device handle of the PCI Root Bridge
188 that the caller is interested in
189 @param Attribute The pointer to attributes of the PCI Root Bridge
191 @retval EFI_SUCCESS Success
192 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
193 @retval EFI_INVALID_PARAMETER Attributes is NULL
198 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES
)(
199 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
200 IN EFI_HANDLE RootBridgeHandle
,
201 OUT UINT64
*Attributes
206 This is the request from the PCI enumerator to set up
207 the specified PCI Root Bridge for bus enumeration process.
209 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
210 @param RootBridgeHandle The PCI Root Bridge to be set up
211 @param Configuration Pointer to the pointer to the PCI bus resource descriptor
213 @retval EFI_SUCCESS Success
214 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
215 @retval EFI_DEVICE_ERROR Request failed due to hardware error
216 @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources
221 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION
)(
222 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
223 IN EFI_HANDLE RootBridgeHandle
,
224 OUT VOID
**Configuration
229 This function programs the PCI Root Bridge hardware so that
230 it decodes the specified PCI bus range
232 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
233 @param RootBridgeHandle The PCI Root Bridge whose bus range is to be programmed
234 @param Configuration The pointer to the PCI bus resource descriptor
236 @retval EFI_SUCCESS Success
237 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
238 @retval EFI_INVALID_PARAMETER Configuration is NULL
239 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor
240 @retval EFI_INVALID_PARAMETER Configuration contains one or more memory or IO ACPI resource descriptor
241 @retval EFI_INVALID_PARAMETER Address Range Minimum or Address Range Length fields in Configuration
242 are invalid for this Root Bridge.
243 @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource descriptor
244 @retval EFI_DEVICE_ERROR Request failed due to hardware error
245 @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources
250 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS
)(
251 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
252 IN EFI_HANDLE RootBridgeHandle
,
253 IN VOID
*Configuration
258 Submits the I/O and memory resource requirements for the specified PCI Root Bridge
260 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
261 @param RootBridgeHandle The PCI Root Bridge whose I/O and memory resource requirements
263 @param Configuration The pointer to the PCI I/O and PCI memory resource descriptor
265 @retval EFI_SUCCESS Success
266 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
267 @retval EFI_INVALID_PARAMETER Configuration is NULL
268 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor
269 @retval EFI_INVALID_PARAMETER Configuration includes a resource descriptor of unsupported type
274 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES
)(
275 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
276 IN EFI_HANDLE RootBridgeHandle
,
277 IN VOID
*Configuration
282 This function returns the proposed resource settings for the specified
285 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
286 @param RootBridgeHandle The PCI Root Bridge handle
287 @param Configuration The pointer to the pointer to the PCI I/O
288 and memory resource descriptor
290 @retval EFI_SUCCESS Success
291 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
292 @retval EFI_DEVICE_ERROR Request failed due to hardware error
293 @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources
298 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES
)(
299 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
300 IN EFI_HANDLE RootBridgeHandle
,
301 OUT VOID
**Configuration
307 This function is called for all the PCI controllers that the PCI
308 bus driver finds. Can be used to Preprogram the controller.
310 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
311 @param RootBridgeHandle The PCI Root Bridge handle
312 @param PciBusAddress Address of the controller on the PCI bus
313 @param Phase The Phase during resource allocation
315 @retval EFI_SUCCESS Success
316 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
317 @retval EFI_DEVICE_ERROR Device pre-initialization failed due to hardware error.
322 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER
)(
323 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
324 IN EFI_HANDLE RootBridgeHandle
,
325 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress
,
326 IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase
330 @par Protocol Description:
331 Provides the basic interfaces to abstract a PCI host bridge resource allocation.
334 The notification from the PCI bus enumerator that it is about to enter
335 a certain phase during the enumeration process.
337 @param GetNextRootBridge
338 Retrieves the device handle for the next PCI root bridge that is produced by the
339 host bridge to which this instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is attached.
341 @param GetAllocAttributes
342 Retrieves the allocation-related attributes of a PCI root bridge.
344 @param StartBusEnumeration
345 Sets up a PCI root bridge for bus enumeration.
348 Sets up the PCI root bridge so that it decodes a specific range of bus numbers.
350 @param SubmitResources
351 Submits the resource requirements for the specified PCI root bridge.
353 @param GetProposedResources
354 Returns the proposed resource assignment for the specified PCI root bridges.
356 @param PreprocessController
357 Provides hooks from the PCI bus driver to every PCI controller
358 (device/function) at various stages of the PCI enumeration process that
359 allow the host bridge driver to preinitialize individual PCI controllers
363 struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
{
364 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE NotifyPhase
;
365 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE GetNextRootBridge
;
366 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES GetAllocAttributes
;
367 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION StartBusEnumeration
;
368 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS SetBusNumbers
;
369 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES SubmitResources
;
370 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES GetProposedResources
;
371 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER PreprocessController
;
374 extern EFI_GUID gEfiPciHostBridgeResourceAllocationProtocolGuid
;