2 This file declares Pci Host Bridge Resource Allocation Protocol
4 Copyright (c) 2007, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13 Module Name: PciHostBridgeResourceAllocation.h
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
54 // EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE
57 EfiPciHostBridgeBeginEnumeration
,
58 EfiPciHostBridgeBeginBusAllocation
,
59 EfiPciHostBridgeEndBusAllocation
,
60 EfiPciHostBridgeBeginResourceAllocation
,
61 EfiPciHostBridgeAllocateResources
,
62 EfiPciHostBridgeSetResources
,
63 EfiPciHostBridgeFreeResources
,
64 EfiPciHostBridgeEndResourceAllocation
65 } EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE
;
68 // EfiPciHostBridgeBeginEnumeration
69 // Reset the host bridge PCI apertures and internal data structures.
70 // PCI enumerator should issue this notification before starting fresh
71 // enumeration process. Enumeration cannot be restarted after sending
72 // any other notification such as EfiPciHostBridgeBeginBusAllocation.
74 // EfiPciHostBridgeBeginBusAllocation
75 // The bus allocation phase is about to begin. No specific action
76 // is required here. This notification can be used to perform any
77 // chipset specific programming.
79 // EfiPciHostBridgeEndBusAllocation
80 // The bus allocation and bus programming phase is complete. No specific
81 // action is required here. This notification can be used to perform any
82 // chipset specific programming.
84 // EfiPciHostBridgeBeginResourceAllocation
85 // The resource allocation phase is about to begin.No specific action is
86 // required here. This notification can be used to perform any chipset specific programming.
88 // EfiPciHostBridgeAllocateResources
89 // Allocate resources per previously submitted requests for all the PCI Root
90 // Bridges. These resource settings are returned on the next call to
91 // GetProposedResources().
93 // EfiPciHostBridgeSetResources
94 // Program the Host Bridge hardware to decode previously allocated resources
95 // (proposed resources) for all the PCI Root Bridges.
97 // EfiPciHostBridgeFreeResources
98 // De-allocate previously allocated resources previously for all the PCI
99 // Root Bridges and reset the I/O and memory apertures to initial state.
101 // EfiPciHostBridgeEndResourceAllocation
102 // The resource allocation phase is completed. No specific action is required
103 // here. This notification can be used to perform any chipset specific programming.
108 // EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE
111 EfiPciBeforeChildBusEnumeration
,
112 EfiPciBeforeResourceCollection
113 } EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE
;
116 // EfiPciBeforeChildBusEnumeration
117 // This notification is only applicable to PCI-PCI bridges and
118 // indicates that the PCI enumerator is about to begin enumerating
119 // the bus behind the PCI-PCI Bridge. This notification is sent after
120 // the primary bus number, the secondary bus number and the subordinate
121 // bus number registers in the PCI-PCI Bridge are programmed to valid
122 // (not necessary final) values
124 // EfiPciBeforeResourceCollection
125 // This notification is sent before the PCI enumerator probes BAR registers
126 // for every valid PCI function.
131 Enter a certain phase of the PCI enumeration process
133 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance
134 @param Phase The phase during enumeration
136 @retval EFI_SUCCESS Success
137 @retval EFI_OUT_OF_RESOURCES If SubmitResources ( ) could not allocate resources
138 @retval EFI_NOT_READY This phase cannot be entered at this time
139 @retval EFI_DEVICE_ERROR SetResources failed due to HW error.
144 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE
) (
145 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
146 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase
151 Return the device handle of the next PCI root bridge that is associated with
154 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
155 @param RootBridgeHandle Returns the device handle of the next PCI Root Bridge.
156 On input, it holds the RootBridgeHandle returned by the most
157 recent call to GetNextRootBridge().The handle for the first
158 PCI Root Bridge is returned if RootBridgeHandle is NULL on input
160 @retval EFI_SUCCESS Success
161 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
166 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE
) (
167 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
168 IN OUT EFI_HANDLE
*RootBridgeHandle
173 Returns the attributes of a PCI Root Bridge.
175 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
176 @param RootBridgeHandle The device handle of the PCI Root Bridge
177 that the caller is interested in
178 @param Attribute The pointer to attributes of the PCI Root Bridge
180 @retval EFI_SUCCESS Success
181 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
182 @retval EFI_INVALID_PARAMETER Attributes is NULL
187 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES
) (
188 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
189 IN EFI_HANDLE RootBridgeHandle
,
190 OUT UINT64
*Attributes
195 This is the request from the PCI enumerator to set up
196 the specified PCI Root Bridge for bus enumeration process.
198 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
199 @param RootBridgeHandle The PCI Root Bridge to be set up
200 @param Configuration Pointer to the pointer to the PCI bus resource descriptor
202 @retval EFI_SUCCESS Success
203 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
204 @retval EFI_DEVICE_ERROR Request failed due to hardware error
205 @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources
210 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION
) (
211 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
212 IN EFI_HANDLE RootBridgeHandle
,
213 OUT VOID
**Configuration
218 This function programs the PCI Root Bridge hardware so that
219 it decodes the specified PCI bus range
221 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
222 @param RootBridgeHandle The PCI Root Bridge whose bus range is to be programmed
223 @param Configuration The pointer to the PCI bus resource descriptor
225 @retval EFI_SUCCESS Success
226 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
227 @retval EFI_INVALID_PARAMETER Configuration is NULL
228 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor
229 @retval EFI_INVALID_PARAMETER Configuration contains one or more memory or IO ACPI resource descriptor
230 @retval EFI_INVALID_PARAMETER Address Range Minimum or Address Range Length fields in Configuration
231 are invalid for this Root Bridge.
232 @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource descriptor
233 @retval EFI_DEVICE_ERROR Request failed due to hardware error
234 @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources
239 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS
) (
240 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
241 IN EFI_HANDLE RootBridgeHandle
,
242 IN VOID
*Configuration
247 Submits the I/O and memory resource requirements for the specified PCI Root Bridge
249 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
250 @param RootBridgeHandle The PCI Root Bridge whose I/O and memory resource requirements
252 @param Configuration The pointer to the PCI I/O and PCI memory resource descriptor
254 @retval EFI_SUCCESS Success
255 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
256 @retval EFI_INVALID_PARAMETER Configuration is NULL
257 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor
258 @retval EFI_INVALID_PARAMETER Configuration includes a resource descriptor of unsupported type
263 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES
) (
264 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
265 IN EFI_HANDLE RootBridgeHandle
,
266 IN VOID
*Configuration
271 This function returns the proposed resource settings for the specified
274 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
275 @param RootBridgeHandle The PCI Root Bridge handle
276 @param Configuration The pointer to the pointer to the PCI I/O
277 and memory resource descriptor
279 @retval EFI_SUCCESS Success
280 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
281 @retval EFI_DEVICE_ERROR Request failed due to hardware error
282 @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources
287 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES
) (
288 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
289 IN EFI_HANDLE RootBridgeHandle
,
290 OUT VOID
**Configuration
296 This function is called for all the PCI controllers that the PCI
297 bus driver finds. Can be used to Preprogram the controller.
299 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
300 @param RootBridgeHandle The PCI Root Bridge handle
301 @param PciBusAddress Address of the controller on the PCI bus
302 @param Phase The Phase during resource allocation
304 @retval EFI_SUCCESS Success
305 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
306 @retval EFI_DEVICE_ERROR Device pre-initialization failed due to hardware error.
311 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER
) (
312 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
313 IN EFI_HANDLE RootBridgeHandle
,
314 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress
,
315 IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase
319 @par Protocol Description:
320 Provides the basic interfaces to abstract a PCI host bridge resource allocation.
323 The notification from the PCI bus enumerator that it is about to enter
324 a certain phase during the enumeration process.
326 @param GetNextRootBridge
327 Retrieves the device handle for the next PCI root bridge that is produced by the
328 host bridge to which this instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is attached.
330 @param GetAllocAttributes
331 Retrieves the allocation-related attributes of a PCI root bridge.
333 @param StartBusEnumeration
334 Sets up a PCI root bridge for bus enumeration.
337 Sets up the PCI root bridge so that it decodes a specific range of bus numbers.
339 @param SubmitResources
340 Submits the resource requirements for the specified PCI root bridge.
342 @param GetProposedResources
343 Returns the proposed resource assignment for the specified PCI root bridges.
345 @param PreprocessController
346 Provides hooks from the PCI bus driver to every PCI controller
347 (device/function) at various stages of the PCI enumeration process that
348 allow the host bridge driver to preinitialize individual PCI controllers
352 struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
{
353 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE NotifyPhase
;
354 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE GetNextRootBridge
;
355 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES GetAllocAttributes
;
356 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION StartBusEnumeration
;
357 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS SetBusNumbers
;
358 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES SubmitResources
;
359 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES GetProposedResources
;
360 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER PreprocessController
;
363 extern EFI_GUID gEfiPciHostBridgeResourceAllocationProtocolGuid
;