MdeModulePkg/PciBus: Correct typos
[mirror_edk2.git] / MdeModulePkg / Bus / Pci / PciBusDxe / PciEnumeratorSupport.h
1 /** @file
2 PCI enumeration support functions declaration for PCI Bus module.
3
4 Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
5 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
9
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.
12
13 **/
14
15 #ifndef _EFI_PCI_ENUMERATOR_SUPPORT_H_
16 #define _EFI_PCI_ENUMERATOR_SUPPORT_H_
17
18 /**
19 This routine is used to check whether the pci device is present.
20
21 @param PciRootBridgeIo Pointer to instance of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
22 @param Pci Output buffer for PCI device configuration space.
23 @param Bus PCI bus NO.
24 @param Device PCI device NO.
25 @param Func PCI Func NO.
26
27 @retval EFI_NOT_FOUND PCI device not present.
28 @retval EFI_SUCCESS PCI device is found.
29
30 **/
31 EFI_STATUS
32 PciDevicePresent (
33 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *PciRootBridgeIo,
34 OUT PCI_TYPE00 *Pci,
35 IN UINT8 Bus,
36 IN UINT8 Device,
37 IN UINT8 Func
38 );
39
40 /**
41 Collect all the resource information under this root bridge.
42
43 A database that records all the information about pci device subject to this
44 root bridge will then be created.
45
46 @param Bridge Parent bridge instance.
47 @param StartBusNumber Bus number of beginning.
48
49 @retval EFI_SUCCESS PCI device is found.
50 @retval other Some error occurred when reading PCI bridge information.
51
52 **/
53 EFI_STATUS
54 PciPciDeviceInfoCollector (
55 IN PCI_IO_DEVICE *Bridge,
56 IN UINT8 StartBusNumber
57 );
58
59 /**
60 Search required device and create PCI device instance.
61
62 @param Bridge Parent bridge instance.
63 @param Pci Input PCI device information block.
64 @param Bus PCI bus NO.
65 @param Device PCI device NO.
66 @param Func PCI func NO.
67 @param PciDevice Output of searched PCI device instance.
68
69 @retval EFI_SUCCESS Successfully created PCI device instance.
70 @retval EFI_OUT_OF_RESOURCES Cannot get PCI device information.
71
72 **/
73 EFI_STATUS
74 PciSearchDevice (
75 IN PCI_IO_DEVICE *Bridge,
76 IN PCI_TYPE00 *Pci,
77 IN UINT8 Bus,
78 IN UINT8 Device,
79 IN UINT8 Func,
80 OUT PCI_IO_DEVICE **PciDevice
81 );
82
83 /**
84 Create PCI device instance for PCI device.
85
86 @param Bridge Parent bridge instance.
87 @param Pci Input PCI device information block.
88 @param Bus PCI device Bus NO.
89 @param Device PCI device Device NO.
90 @param Func PCI device's func NO.
91
92 @return Created PCI device instance.
93
94 **/
95 PCI_IO_DEVICE *
96 GatherDeviceInfo (
97 IN PCI_IO_DEVICE *Bridge,
98 IN PCI_TYPE00 *Pci,
99 IN UINT8 Bus,
100 IN UINT8 Device,
101 IN UINT8 Func
102 );
103
104 /**
105 Create PCI device instance for PCI-PCI bridge.
106
107 @param Bridge Parent bridge instance.
108 @param Pci Input PCI device information block.
109 @param Bus PCI device Bus NO.
110 @param Device PCI device Device NO.
111 @param Func PCI device's func NO.
112
113 @return Created PCI device instance.
114
115 **/
116 PCI_IO_DEVICE *
117 GatherPpbInfo (
118 IN PCI_IO_DEVICE *Bridge,
119 IN PCI_TYPE00 *Pci,
120 IN UINT8 Bus,
121 IN UINT8 Device,
122 IN UINT8 Func
123 );
124
125 /**
126 Create PCI device instance for PCI Card bridge device.
127
128 @param Bridge Parent bridge instance.
129 @param Pci Input PCI device information block.
130 @param Bus PCI device Bus NO.
131 @param Device PCI device Device NO.
132 @param Func PCI device's func NO.
133
134 @return Created PCI device instance.
135
136 **/
137 PCI_IO_DEVICE *
138 GatherP2CInfo (
139 IN PCI_IO_DEVICE *Bridge,
140 IN PCI_TYPE00 *Pci,
141 IN UINT8 Bus,
142 IN UINT8 Device,
143 IN UINT8 Func
144 );
145
146 /**
147 Create device path for pci device.
148
149 @param ParentDevicePath Parent bridge's path.
150 @param PciIoDevice Pci device instance.
151
152 @return Device path protocol instance for specific pci device.
153
154 **/
155 EFI_DEVICE_PATH_PROTOCOL *
156 CreatePciDevicePath (
157 IN EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath,
158 IN PCI_IO_DEVICE *PciIoDevice
159 );
160
161 /**
162 Check whether the PCI IOV VF bar is existed or not.
163
164 @param PciIoDevice A pointer to the PCI_IO_DEVICE.
165 @param Offset The offset.
166 @param BarLengthValue The bar length value returned.
167 @param OriginalBarValue The original bar value returned.
168
169 @retval EFI_NOT_FOUND The bar doesn't exist.
170 @retval EFI_SUCCESS The bar exist.
171
172 **/
173 EFI_STATUS
174 VfBarExisted (
175 IN PCI_IO_DEVICE *PciIoDevice,
176 IN UINTN Offset,
177 OUT UINT32 *BarLengthValue,
178 OUT UINT32 *OriginalBarValue
179 );
180
181 /**
182 Check whether the bar is existed or not.
183
184 @param PciIoDevice A pointer to the PCI_IO_DEVICE.
185 @param Offset The offset.
186 @param BarLengthValue The bar length value returned.
187 @param OriginalBarValue The original bar value returned.
188
189 @retval EFI_NOT_FOUND The bar doesn't exist.
190 @retval EFI_SUCCESS The bar exist.
191
192 **/
193 EFI_STATUS
194 BarExisted (
195 IN PCI_IO_DEVICE *PciIoDevice,
196 IN UINTN Offset,
197 OUT UINT32 *BarLengthValue,
198 OUT UINT32 *OriginalBarValue
199 );
200
201 /**
202 Test whether the device can support given attributes.
203
204 @param PciIoDevice Pci device instance.
205 @param Command Input command register value, and
206 returned supported register value.
207 @param BridgeControl Input bridge control value for PPB or P2C, and
208 returned supported bridge control value.
209 @param OldCommand Returned and stored old command register offset.
210 @param OldBridgeControl Returned and stored old Bridge control value for PPB or P2C.
211
212 **/
213 VOID
214 PciTestSupportedAttribute (
215 IN PCI_IO_DEVICE *PciIoDevice,
216 IN OUT UINT16 *Command,
217 IN OUT UINT16 *BridgeControl,
218 OUT UINT16 *OldCommand,
219 OUT UINT16 *OldBridgeControl
220 );
221
222 /**
223 Set the supported or current attributes of a PCI device.
224
225 @param PciIoDevice Structure pointer for PCI device.
226 @param Command Command register value.
227 @param BridgeControl Bridge control value for PPB or P2C.
228 @param Option Make a choice of EFI_SET_SUPPORTS or EFI_SET_ATTRIBUTES.
229
230 **/
231 VOID
232 PciSetDeviceAttribute (
233 IN PCI_IO_DEVICE *PciIoDevice,
234 IN UINT16 Command,
235 IN UINT16 BridgeControl,
236 IN UINTN Option
237 );
238
239 /**
240 Determine if the device can support Fast Back to Back attribute.
241
242 @param PciIoDevice Pci device instance.
243 @param StatusIndex Status register value.
244
245 @retval EFI_SUCCESS This device support Fast Back to Back attribute.
246 @retval EFI_UNSUPPORTED This device doesn't support Fast Back to Back attribute.
247
248 **/
249 EFI_STATUS
250 GetFastBackToBackSupport (
251 IN PCI_IO_DEVICE *PciIoDevice,
252 IN UINT8 StatusIndex
253 );
254
255 /**
256 Determine the related attributes of all devices under a Root Bridge.
257
258 @param PciIoDevice PCI device instance.
259
260 **/
261 EFI_STATUS
262 DetermineDeviceAttribute (
263 IN PCI_IO_DEVICE *PciIoDevice
264 );
265
266 /**
267 This routine is used to update the bar information for those incompatible PCI device.
268
269 @param PciIoDevice Input Pci device instance. Output Pci device instance with updated
270 Bar information.
271
272 @retval EFI_SUCCESS Successfully updated bar information.
273 @retval EFI_UNSUPPORTED Given PCI device doesn't belong to incompatible PCI device list.
274
275 **/
276 EFI_STATUS
277 UpdatePciInfo (
278 IN OUT PCI_IO_DEVICE *PciIoDevice
279 );
280
281 /**
282 This routine will update the alignment with the new alignment.
283
284 @param Alignment Input Old alignment. Output updated alignment.
285 @param NewAlignment New alignment.
286
287 **/
288 VOID
289 SetNewAlign (
290 IN OUT UINT64 *Alignment,
291 IN UINT64 NewAlignment
292 );
293
294 /**
295 Parse PCI bar information and fill them into PCI device instance.
296
297 @param PciIoDevice Pci device instance.
298 @param Offset Bar offset.
299 @param BarIndex Bar index.
300
301 @return Next bar offset.
302
303 **/
304 UINTN
305 PciParseBar (
306 IN PCI_IO_DEVICE *PciIoDevice,
307 IN UINTN Offset,
308 IN UINTN BarIndex
309 );
310
311 /**
312 Parse PCI IOV VF bar information and fill them into PCI device instance.
313
314 @param PciIoDevice Pci device instance.
315 @param Offset Bar offset.
316 @param BarIndex Bar index.
317
318 @return Next bar offset.
319
320 **/
321 UINTN
322 PciIovParseVfBar (
323 IN PCI_IO_DEVICE *PciIoDevice,
324 IN UINTN Offset,
325 IN UINTN BarIndex
326 );
327
328 /**
329 This routine is used to initialize the bar of a PCI device.
330
331 @param PciIoDevice Pci device instance.
332
333 @note It can be called typically when a device is going to be rejected.
334
335 **/
336 VOID
337 InitializePciDevice (
338 IN PCI_IO_DEVICE *PciIoDevice
339 );
340
341 /**
342 This routine is used to initialize the bar of a PCI-PCI Bridge device.
343
344 @param PciIoDevice PCI-PCI bridge device instance.
345
346 **/
347 VOID
348 InitializePpb (
349 IN PCI_IO_DEVICE *PciIoDevice
350 );
351
352 /**
353 This routine is used to initialize the bar of a PCI Card Bridge device.
354
355 @param PciIoDevice PCI Card bridge device.
356
357 **/
358 VOID
359 InitializeP2C (
360 IN PCI_IO_DEVICE *PciIoDevice
361 );
362
363 /**
364 Create and initialize general PCI I/O device instance for
365 PCI device/bridge device/hotplug bridge device.
366
367 @param Bridge Parent bridge instance.
368 @param Pci Input Pci information block.
369 @param Bus Device Bus NO.
370 @param Device Device device NO.
371 @param Func Device func NO.
372
373 @return Instance of PCI device. NULL means no instance created.
374
375 **/
376 PCI_IO_DEVICE *
377 CreatePciIoDevice (
378 IN PCI_IO_DEVICE *Bridge,
379 IN PCI_TYPE00 *Pci,
380 IN UINT8 Bus,
381 IN UINT8 Device,
382 IN UINT8 Func
383 );
384
385 /**
386 This routine is used to enumerate entire pci bus system
387 in a given platform.
388
389 It is only called on the second start on the same Root Bridge.
390
391 @param Controller Parent bridge handler.
392
393 @retval EFI_SUCCESS PCI enumeration finished successfully.
394 @retval other Some error occurred when enumerating the pci bus system.
395
396 **/
397 EFI_STATUS
398 PciEnumeratorLight (
399 IN EFI_HANDLE Controller
400 );
401
402 /**
403 Get bus range from PCI resource descriptor list.
404
405 @param Descriptors A pointer to the address space descriptor.
406 @param MinBus The min bus returned.
407 @param MaxBus The max bus returned.
408 @param BusRange The bus range returned.
409
410 @retval EFI_SUCCESS Successfully got bus range.
411 @retval EFI_NOT_FOUND Can not find the specific bus.
412
413 **/
414 EFI_STATUS
415 PciGetBusRange (
416 IN EFI_ACPI_ADDRESS_SPACE_DESCRIPTOR **Descriptors,
417 OUT UINT16 *MinBus,
418 OUT UINT16 *MaxBus,
419 OUT UINT16 *BusRange
420 );
421
422 /**
423 This routine can be used to start the root bridge.
424
425 @param RootBridgeDev Pci device instance.
426
427 @retval EFI_SUCCESS This device started.
428 @retval other Failed to get PCI Root Bridge I/O protocol.
429
430 **/
431 EFI_STATUS
432 StartManagingRootBridge (
433 IN PCI_IO_DEVICE *RootBridgeDev
434 );
435
436 /**
437 This routine can be used to check whether a PCI device should be rejected when light enumeration.
438
439 @param PciIoDevice Pci device instance.
440
441 @retval TRUE This device should be rejected.
442 @retval FALSE This device shouldn't be rejected.
443
444 **/
445 BOOLEAN
446 IsPciDeviceRejected (
447 IN PCI_IO_DEVICE *PciIoDevice
448 );
449
450 /**
451 Reset all bus number from specific bridge.
452
453 @param Bridge Parent specific bridge.
454 @param StartBusNumber Start bus number.
455
456 **/
457 VOID
458 ResetAllPpbBusNumber (
459 IN PCI_IO_DEVICE *Bridge,
460 IN UINT8 StartBusNumber
461 );
462
463 /**
464 Dump the PPB padding resource information.
465
466 @param PciIoDevice PCI IO instance.
467 @param ResourceType The desired resource type to dump.
468 PciBarTypeUnknown means to dump all types of resources.
469 **/
470 VOID
471 DumpPpbPaddingResource (
472 IN PCI_IO_DEVICE *PciIoDevice,
473 IN PCI_BAR_TYPE ResourceType
474 );
475
476 #endif