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