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 - 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_
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
67 /// Reset the host bridge PCI apertures and internal data structures.
68 /// PCI enumerator should issue this notification before starting fresh
69 /// enumeration process. Enumeration cannot be restarted after sending
70 /// any other notification such as EfiPciHostBridgeBeginBusAllocation.
72 EfiPciHostBridgeBeginEnumeration
,
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 EfiPciHostBridgeBeginBusAllocation
,
82 /// The bus allocation and bus programming phase is complete. No specific
83 /// action is required here. This notification can be used to perform any
84 /// chipset specific programming.
86 EfiPciHostBridgeEndBusAllocation
,
89 /// The resource allocation phase is about to begin.No specific action is
90 /// required here. This notification can be used to perform any chipset specific programming.
92 EfiPciHostBridgeBeginResourceAllocation
,
95 /// Allocate resources per previously submitted requests for all the PCI Root
96 /// Bridges. These resource settings are returned on the next call to
97 /// GetProposedResources().
99 EfiPciHostBridgeAllocateResources
,
102 /// Program the Host Bridge hardware to decode previously allocated resources
103 /// (proposed resources) for all the PCI Root Bridges.
105 EfiPciHostBridgeSetResources
,
108 /// De-allocate previously allocated resources previously for all the PCI
109 /// Root Bridges and reset the I/O and memory apertures to initial state.
111 EfiPciHostBridgeFreeResources
,
114 /// The resource allocation phase is completed. No specific action is required
115 /// here. This notification can be used to perform any chipset specific programming.
117 EfiPciHostBridgeEndResourceAllocation
118 } EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE
;
121 /// EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE
125 /// This notification is only applicable to PCI-PCI bridges and
126 /// indicates that the PCI enumerator is about to begin enumerating
127 /// the bus behind the PCI-PCI Bridge. This notification is sent after
128 /// the primary bus number, the secondary bus number and the subordinate
129 /// bus number registers in the PCI-PCI Bridge are programmed to valid
130 /// (not necessary final) values
132 EfiPciBeforeChildBusEnumeration
,
135 /// This notification is sent before the PCI enumerator probes BAR registers
136 /// for every valid PCI function.
138 EfiPciBeforeResourceCollection
139 } EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE
;
142 Enter a certain phase of the PCI enumeration process
144 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance
145 @param Phase The phase during enumeration
147 @retval EFI_SUCCESS Success
148 @retval EFI_OUT_OF_RESOURCES If SubmitResources ( ) could not allocate resources
149 @retval EFI_INVALID_PARAMETER The Phase is invalid
150 @retval EFI_NOT_READY This phase cannot be entered at this time
151 @retval EFI_DEVICE_ERROR SetResources failed due to HW error.
156 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE
)(
157 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
158 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase
163 Return the device handle of the next PCI root bridge that is associated with
166 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
167 @param RootBridgeHandle Returns the device handle of the next PCI Root Bridge.
168 On input, it holds the RootBridgeHandle returned by the most
169 recent call to GetNextRootBridge().The handle for the first
170 PCI Root Bridge is returned if RootBridgeHandle is NULL on input
172 @retval EFI_SUCCESS Success
173 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
174 @retval EFI_NOT_FOUND There are no more PCI root bridge device handles.
179 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE
)(
180 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
181 IN OUT EFI_HANDLE
*RootBridgeHandle
186 Returns the attributes of a PCI Root Bridge.
188 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
189 @param RootBridgeHandle The device handle of the PCI Root Bridge
190 that the caller is interested in
191 @param Attribute The pointer to attributes of the PCI Root Bridge
193 @retval EFI_SUCCESS Success
194 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
195 @retval EFI_INVALID_PARAMETER Attributes is NULL
200 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES
)(
201 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
202 IN EFI_HANDLE RootBridgeHandle
,
203 OUT UINT64
*Attributes
208 This is the request from the PCI enumerator to set up
209 the specified PCI Root Bridge for bus enumeration process.
211 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
212 @param RootBridgeHandle The PCI Root Bridge to be set up
213 @param Configuration Pointer to the pointer to the PCI bus resource descriptor
215 @retval EFI_SUCCESS Success
216 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
217 @retval EFI_DEVICE_ERROR Request failed due to hardware error
218 @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources
223 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION
)(
224 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
225 IN EFI_HANDLE RootBridgeHandle
,
226 OUT VOID
**Configuration
231 This function programs the PCI Root Bridge hardware so that
232 it decodes the specified PCI bus range
234 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
235 @param RootBridgeHandle The PCI Root Bridge whose bus range is to be programmed
236 @param Configuration The pointer to the PCI bus resource descriptor
238 @retval EFI_SUCCESS Success
239 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
240 @retval EFI_INVALID_PARAMETER Configuration is NULL
241 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor
242 @retval EFI_INVALID_PARAMETER Configuration contains one or more memory or IO ACPI resource descriptor
243 @retval EFI_INVALID_PARAMETER Address Range Minimum or Address Range Length fields in Configuration
244 are invalid for this Root Bridge.
245 @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource descriptor
246 @retval EFI_DEVICE_ERROR Request failed due to hardware error
247 @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources
252 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS
)(
253 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
254 IN EFI_HANDLE RootBridgeHandle
,
255 IN VOID
*Configuration
260 Submits the I/O and memory resource requirements for the specified PCI Root Bridge
262 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
263 @param RootBridgeHandle The PCI Root Bridge whose I/O and memory resource requirements
265 @param Configuration The pointer to the PCI I/O and PCI memory resource descriptor
267 @retval EFI_SUCCESS Success
268 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
269 @retval EFI_INVALID_PARAMETER Configuration is NULL
270 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor
271 @retval EFI_INVALID_PARAMETER Configuration includes a resource descriptor of unsupported type
276 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES
)(
277 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
278 IN EFI_HANDLE RootBridgeHandle
,
279 IN VOID
*Configuration
284 This function returns the proposed resource settings for the specified
287 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
288 @param RootBridgeHandle The PCI Root Bridge handle
289 @param Configuration The pointer to the pointer to the PCI I/O
290 and memory resource descriptor
292 @retval EFI_SUCCESS Success
293 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
294 @retval EFI_DEVICE_ERROR Request failed due to hardware error
295 @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources
300 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES
)(
301 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
302 IN EFI_HANDLE RootBridgeHandle
,
303 OUT VOID
**Configuration
309 This function is called for all the PCI controllers that the PCI
310 bus driver finds. Can be used to Preprogram the controller.
312 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
313 @param RootBridgeHandle The PCI Root Bridge handle
314 @param PciBusAddress Address of the controller on the PCI bus
315 @param Phase The Phase during resource allocation
317 @retval EFI_SUCCESS Success
318 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
319 @retval EFI_DEVICE_ERROR Device pre-initialization failed due to hardware error.
324 (EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER
)(
325 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
*This
,
326 IN EFI_HANDLE RootBridgeHandle
,
327 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress
,
328 IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase
332 Provides the basic interfaces to abstract a PCI host bridge resource allocation.
334 struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
{
336 /// The notification from the PCI bus enumerator that it is about to enter
337 /// a certain phase during the enumeration process.
339 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE NotifyPhase
;
342 /// Retrieves the device handle for the next PCI root bridge that is produced by the
343 /// host bridge to which this instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is attached.
345 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE GetNextRootBridge
;
348 /// Retrieves the allocation-related attributes of a PCI root bridge.
350 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES GetAllocAttributes
;
353 /// Sets up a PCI root bridge for bus enumeration.
355 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION StartBusEnumeration
;
358 /// Sets up the PCI root bridge so that it decodes a specific range of bus numbers.
360 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS SetBusNumbers
;
363 /// Submits the resource requirements for the specified PCI root bridge.
365 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES SubmitResources
;
368 /// Returns the proposed resource assignment for the specified PCI root bridges.
370 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES GetProposedResources
;
373 /// Provides hooks from the PCI bus driver to every PCI controller
374 /// (device/function) at various stages of the PCI enumeration process that
375 /// allow the host bridge driver to preinitialize individual PCI controllers
376 /// before enumeration.
378 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER PreprocessController
;
381 extern EFI_GUID gEfiPciHostBridgeResourceAllocationProtocolGuid
;