92d7c5ac17b99b7f5158ef67aeef8fa3c5125e40
[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / PciHostBridgeResourceAllocation.h
1 /** @file
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.
5
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
11
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.
14
15 @par Revision Reference:
16 This protocol is defined in Framework of EFI Pci Host Bridge Resource Allocation Protocol Spec
17 Version 0.9
18
19 **/
20
21 #ifndef _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_
22 #define _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_
23
24 #include <PiDxe.h>
25 #include <Protocol/PciRootBridgeIo.h>
26
27 #define EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GUID \
28 { 0xCF8034BE, 0x6768, 0x4d8b, {0xB7,0x39,0x7C,0xCE,0x68,0x3A,0x9F,0xBE }}
29
30
31 typedef struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL;
32
33
34 //
35 // EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTES
36 //
37
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.
42 //
43 #define EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM 1
44
45 //
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.
50 //
51 #define EFI_PCI_HOST_BRIDGE_MEM64_DECODE 2
52
53
54 //
55 // EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE
56 //
57 typedef enum {
58 EfiPciHostBridgeBeginEnumeration,
59 EfiPciHostBridgeBeginBusAllocation,
60 EfiPciHostBridgeEndBusAllocation,
61 EfiPciHostBridgeBeginResourceAllocation,
62 EfiPciHostBridgeAllocateResources,
63 EfiPciHostBridgeSetResources,
64 EfiPciHostBridgeFreeResources,
65 EfiPciHostBridgeEndResourceAllocation
66 } EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE;
67
68 //
69 // EfiPciHostBridgeBeginEnumeration
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.
74 //
75 // EfiPciHostBridgeBeginBusAllocation
76 // The bus allocation phase is about to begin. No specific action
77 // is required here. This notification can be used to perform any
78 // chipset specific programming.
79 //
80 // EfiPciHostBridgeEndBusAllocation
81 // The bus allocation and bus programming phase is complete. No specific
82 // action is required here. This notification can be used to perform any
83 // chipset specific programming.
84 //
85 // EfiPciHostBridgeBeginResourceAllocation
86 // The resource allocation phase is about to begin.No specific action is
87 // required here. This notification can be used to perform any chipset specific programming.
88 //
89 // EfiPciHostBridgeAllocateResources
90 // Allocate resources per previously submitted requests for all the PCI Root
91 // Bridges. These resource settings are returned on the next call to
92 // GetProposedResources().
93 //
94 // EfiPciHostBridgeSetResources
95 // Program the Host Bridge hardware to decode previously allocated resources
96 // (proposed resources) for all the PCI Root Bridges.
97 //
98 // EfiPciHostBridgeFreeResources
99 // De-allocate previously allocated resources previously for all the PCI
100 // Root Bridges and reset the I/O and memory apertures to initial state.
101 //
102 // EfiPciHostBridgeEndResourceAllocation
103 // The resource allocation phase is completed. No specific action is required
104 // here. This notification can be used to perform any chipset specific programming.
105
106
107
108 //
109 // EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE
110 //
111 typedef enum {
112 EfiPciBeforeChildBusEnumeration,
113 EfiPciBeforeResourceCollection
114 } EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE;
115
116 //
117 // EfiPciBeforeChildBusEnumeration
118 // This notification is only applicable to PCI-PCI bridges and
119 // indicates that the PCI enumerator is about to begin enumerating
120 // the bus behind the PCI-PCI Bridge. This notification is sent after
121 // the primary bus number, the secondary bus number and the subordinate
122 // bus number registers in the PCI-PCI Bridge are programmed to valid
123 // (not necessary final) values
124 //
125 // EfiPciBeforeResourceCollection
126 // This notification is sent before the PCI enumerator probes BAR registers
127 // for every valid PCI function.
128 //
129
130
131 /**
132 Enter a certain phase of the PCI enumeration process
133
134 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance
135 @param Phase The phase during enumeration
136
137 @retval EFI_SUCCESS Success
138 @retval EFI_OUT_OF_RESOURCES If SubmitResources ( ) could not allocate resources
139 @retval EFI_NOT_READY This phase cannot be entered at this time
140 @retval EFI_DEVICE_ERROR SetResources failed due to HW error.
141
142 **/
143 typedef
144 EFI_STATUS
145 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE) (
146 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
147 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase
148 );
149
150
151 /**
152 Return the device handle of the next PCI root bridge that is associated with
153 this Host Bridge
154
155 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
156 @param RootBridgeHandle Returns the device handle of the next PCI Root Bridge.
157 On input, it holds the RootBridgeHandle returned by the most
158 recent call to GetNextRootBridge().The handle for the first
159 PCI Root Bridge is returned if RootBridgeHandle is NULL on input
160
161 @retval EFI_SUCCESS Success
162 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
163
164 **/
165 typedef
166 EFI_STATUS
167 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE) (
168 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
169 IN OUT EFI_HANDLE *RootBridgeHandle
170 );
171
172
173 /**
174 Returns the attributes of a PCI Root Bridge.
175
176 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
177 @param RootBridgeHandle The device handle of the PCI Root Bridge
178 that the caller is interested in
179 @param Attribute The pointer to attributes of the PCI Root Bridge
180
181 @retval EFI_SUCCESS Success
182 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
183 @retval EFI_INVALID_PARAMETER Attributes is NULL
184
185 **/
186 typedef
187 EFI_STATUS
188 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES) (
189 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
190 IN EFI_HANDLE RootBridgeHandle,
191 OUT UINT64 *Attributes
192 );
193
194
195 /**
196 This is the request from the PCI enumerator to set up
197 the specified PCI Root Bridge for bus enumeration process.
198
199 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
200 @param RootBridgeHandle The PCI Root Bridge to be set up
201 @param Configuration Pointer to the pointer to the PCI bus resource descriptor
202
203 @retval EFI_SUCCESS Success
204 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
205 @retval EFI_DEVICE_ERROR Request failed due to hardware error
206 @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources
207
208 **/
209 typedef
210 EFI_STATUS
211 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION) (
212 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
213 IN EFI_HANDLE RootBridgeHandle,
214 OUT VOID **Configuration
215 );
216
217
218 /**
219 This function programs the PCI Root Bridge hardware so that
220 it decodes the specified PCI bus range
221
222 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
223 @param RootBridgeHandle The PCI Root Bridge whose bus range is to be programmed
224 @param Configuration The pointer to the PCI bus resource descriptor
225
226 @retval EFI_SUCCESS Success
227 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
228 @retval EFI_INVALID_PARAMETER Configuration is NULL
229 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor
230 @retval EFI_INVALID_PARAMETER Configuration contains one or more memory or IO ACPI resource descriptor
231 @retval EFI_INVALID_PARAMETER Address Range Minimum or Address Range Length fields in Configuration
232 are invalid for this Root Bridge.
233 @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource descriptor
234 @retval EFI_DEVICE_ERROR Request failed due to hardware error
235 @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources
236
237 **/
238 typedef
239 EFI_STATUS
240 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS) (
241 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
242 IN EFI_HANDLE RootBridgeHandle,
243 IN VOID *Configuration
244 );
245
246
247 /**
248 Submits the I/O and memory resource requirements for the specified PCI Root Bridge
249
250 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
251 @param RootBridgeHandle The PCI Root Bridge whose I/O and memory resource requirements
252 are being submitted
253 @param Configuration The pointer to the PCI I/O and PCI memory resource descriptor
254
255 @retval EFI_SUCCESS Success
256 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
257 @retval EFI_INVALID_PARAMETER Configuration is NULL
258 @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor
259 @retval EFI_INVALID_PARAMETER Configuration includes a resource descriptor of unsupported type
260
261 **/
262 typedef
263 EFI_STATUS
264 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES) (
265 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
266 IN EFI_HANDLE RootBridgeHandle,
267 IN VOID *Configuration
268 );
269
270
271 /**
272 This function returns the proposed resource settings for the specified
273 PCI Root Bridge
274
275 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
276 @param RootBridgeHandle The PCI Root Bridge handle
277 @param Configuration The pointer to the pointer to the PCI I/O
278 and memory resource descriptor
279
280 @retval EFI_SUCCESS Success
281 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
282 @retval EFI_DEVICE_ERROR Request failed due to hardware error
283 @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources
284
285 **/
286 typedef
287 EFI_STATUS
288 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES) (
289 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
290 IN EFI_HANDLE RootBridgeHandle,
291 OUT VOID **Configuration
292 );
293
294
295
296 /**
297 This function is called for all the PCI controllers that the PCI
298 bus driver finds. Can be used to Preprogram the controller.
299
300 @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
301 @param RootBridgeHandle The PCI Root Bridge handle
302 @param PciBusAddress Address of the controller on the PCI bus
303 @param Phase The Phase during resource allocation
304
305 @retval EFI_SUCCESS Success
306 @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid
307 @retval EFI_DEVICE_ERROR Device pre-initialization failed due to hardware error.
308
309 **/
310 typedef
311 EFI_STATUS
312 (EFIAPI *EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER) (
313 IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
314 IN EFI_HANDLE RootBridgeHandle,
315 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress,
316 IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase
317 );
318
319 /**
320 @par Protocol Description:
321 Provides the basic interfaces to abstract a PCI host bridge resource allocation.
322
323 @param NotifyPhase
324 The notification from the PCI bus enumerator that it is about to enter
325 a certain phase during the enumeration process.
326
327 @param GetNextRootBridge
328 Retrieves the device handle for the next PCI root bridge that is produced by the
329 host bridge to which this instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is attached.
330
331 @param GetAllocAttributes
332 Retrieves the allocation-related attributes of a PCI root bridge.
333
334 @param StartBusEnumeration
335 Sets up a PCI root bridge for bus enumeration.
336
337 @param SetBusNumbers
338 Sets up the PCI root bridge so that it decodes a specific range of bus numbers.
339
340 @param SubmitResources
341 Submits the resource requirements for the specified PCI root bridge.
342
343 @param GetProposedResources
344 Returns the proposed resource assignment for the specified PCI root bridges.
345
346 @param PreprocessController
347 Provides hooks from the PCI bus driver to every PCI controller
348 (device/function) at various stages of the PCI enumeration process that
349 allow the host bridge driver to preinitialize individual PCI controllers
350 before enumeration.
351
352 **/
353 struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL {
354 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE NotifyPhase;
355 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE GetNextRootBridge;
356 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES GetAllocAttributes;
357 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION StartBusEnumeration;
358 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS SetBusNumbers;
359 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES SubmitResources;
360 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES GetProposedResources;
361 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER PreprocessController;
362 };
363
364 extern EFI_GUID gEfiPciHostBridgeResourceAllocationProtocolGuid;
365
366 #endif