b45d2a5d7756298449750d1783beb34817df6741
[mirror_edk2.git] / MdeModulePkg / Bus / Pci / PciBusDxe / PciDeviceSupport.h
1 /** @file\r
2   Supporting functions declaration for PCI devices management.\r
3 \r
4 Copyright (c) 2006 - 2018, 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_DEVICE_SUPPORT_H_\r
16 #define _EFI_PCI_DEVICE_SUPPORT_H_\r
17 \r
18 /**\r
19   Initialize the PCI devices pool.\r
20 \r
21 **/\r
22 VOID\r
23 InitializePciDevicePool (\r
24   VOID\r
25   );\r
26 \r
27 /**\r
28   Insert a root bridge into PCI device pool.\r
29 \r
30   @param RootBridge     A pointer to the PCI_IO_DEVICE.\r
31 \r
32 **/\r
33 VOID\r
34 InsertRootBridge (\r
35   IN PCI_IO_DEVICE      *RootBridge\r
36   );\r
37 \r
38 /**\r
39   This function is used to insert a PCI device node under\r
40   a bridge.\r
41 \r
42   @param Bridge         The PCI bridge.\r
43   @param PciDeviceNode  The PCI device needs inserting.\r
44 \r
45 **/\r
46 VOID\r
47 InsertPciDevice (\r
48   IN PCI_IO_DEVICE      *Bridge,\r
49   IN PCI_IO_DEVICE      *PciDeviceNode\r
50   );\r
51 \r
52 /**\r
53   Destroy root bridge and remove it from deivce tree.\r
54 \r
55   @param RootBridge     The bridge want to be removed.\r
56 \r
57 **/\r
58 VOID\r
59 DestroyRootBridge (\r
60   IN PCI_IO_DEVICE      *RootBridge\r
61   );\r
62 \r
63 /**\r
64   Destroy all the pci device node under the bridge.\r
65   Bridge itself is not included.\r
66 \r
67   @param Bridge         A pointer to the PCI_IO_DEVICE.\r
68 \r
69 **/\r
70 VOID\r
71 DestroyPciDeviceTree (\r
72   IN PCI_IO_DEVICE      *Bridge\r
73   );\r
74 \r
75 /**\r
76   Destroy all device nodes under the root bridge\r
77   specified by Controller.\r
78 \r
79   The root bridge itself is also included.\r
80 \r
81   @param  Controller    Root bridge handle.\r
82 \r
83   @retval EFI_SUCCESS   Destory all devcie nodes successfully.\r
84   @retval EFI_NOT_FOUND Cannot find any PCI device under specified\r
85                         root bridge.\r
86 \r
87 **/\r
88 EFI_STATUS\r
89 DestroyRootBridgeByHandle (\r
90   IN EFI_HANDLE        Controller\r
91   );\r
92 \r
93 /**\r
94   This function registers the PCI IO device.\r
95 \r
96   It creates a handle for this PCI IO device (if the handle does not exist), attaches\r
97   appropriate protocols onto the handle, does necessary initialization, and sets up\r
98   parent/child relationship with its bus controller.\r
99 \r
100   @param Controller     An EFI handle for the PCI bus controller.\r
101   @param PciIoDevice    A PCI_IO_DEVICE pointer to the PCI IO device to be registered.\r
102   @param Handle         A pointer to hold the returned EFI handle for the PCI IO device.\r
103 \r
104   @retval EFI_SUCCESS   The PCI device is successfully registered.\r
105   @retval other         An error occurred when registering the PCI device.\r
106 \r
107 **/\r
108 EFI_STATUS\r
109 RegisterPciDevice (\r
110   IN  EFI_HANDLE          Controller,\r
111   IN  PCI_IO_DEVICE       *PciIoDevice,\r
112   OUT EFI_HANDLE          *Handle      OPTIONAL\r
113   );\r
114 \r
115 /**\r
116   This function is used to remove the whole PCI devices on the specified bridge from\r
117   the root bridge.\r
118 \r
119   @param RootBridgeHandle   The root bridge device handle.\r
120   @param Bridge             The bridge device to be removed.\r
121 \r
122 **/\r
123 VOID\r
124 RemoveAllPciDeviceOnBridge (\r
125   EFI_HANDLE               RootBridgeHandle,\r
126   PCI_IO_DEVICE            *Bridge\r
127   );\r
128 \r
129 /**\r
130   This function is used to de-register the PCI IO device.\r
131 \r
132   That includes un-installing PciIo protocol from the specified PCI\r
133   device handle.\r
134 \r
135   @param Controller    An EFI handle for the PCI bus controller.\r
136   @param Handle        PCI device handle.\r
137 \r
138   @retval EFI_SUCCESS  The PCI device is successfully de-registered.\r
139   @retval other        An error occurred when de-registering the PCI device.\r
140 \r
141 **/\r
142 EFI_STATUS\r
143 DeRegisterPciDevice (\r
144   IN  EFI_HANDLE                     Controller,\r
145   IN  EFI_HANDLE                     Handle\r
146   );\r
147 \r
148 /**\r
149   Start to manage the PCI device on the specified root bridge or PCI-PCI Bridge.\r
150 \r
151   @param Controller          The root bridge handle.\r
152   @param RootBridge          A pointer to the PCI_IO_DEVICE.\r
153   @param RemainingDevicePath A pointer to the EFI_DEVICE_PATH_PROTOCOL.\r
154   @param NumberOfChildren    Children number.\r
155   @param ChildHandleBuffer   A pointer to the child handle buffer.\r
156 \r
157   @retval EFI_NOT_READY   Device is not allocated.\r
158   @retval EFI_UNSUPPORTED Device only support PCI-PCI bridge.\r
159   @retval EFI_NOT_FOUND   Can not find the specific device.\r
160   @retval EFI_SUCCESS     Success to start Pci devices on bridge.\r
161 \r
162 **/\r
163 EFI_STATUS\r
164 StartPciDevicesOnBridge (\r
165   IN EFI_HANDLE                          Controller,\r
166   IN PCI_IO_DEVICE                       *RootBridge,\r
167   IN EFI_DEVICE_PATH_PROTOCOL            *RemainingDevicePath,\r
168   IN OUT UINT8                           *NumberOfChildren,\r
169   IN OUT EFI_HANDLE                      *ChildHandleBuffer\r
170   );\r
171 \r
172 /**\r
173   Start to manage all the PCI devices it found previously under\r
174   the entire host bridge.\r
175 \r
176   @param Controller          The root bridge handle.\r
177 \r
178   @retval EFI_NOT_READY   Device is not allocated.\r
179   @retval EFI_SUCCESS     Success to start Pci device on host bridge.\r
180 \r
181 **/\r
182 EFI_STATUS\r
183 StartPciDevices (\r
184   IN EFI_HANDLE                         Controller\r
185   );\r
186 \r
187 /**\r
188   Create root bridge device.\r
189 \r
190   @param RootBridgeHandle    Specified root bridge hanle.\r
191 \r
192   @return The crated root bridge device instance, NULL means no\r
193           root bridge device instance created.\r
194 \r
195 **/\r
196 PCI_IO_DEVICE *\r
197 CreateRootBridge (\r
198   IN EFI_HANDLE                   RootBridgeHandle\r
199   );\r
200 \r
201 /**\r
202   Get root bridge device instance by specific root bridge handle.\r
203 \r
204   @param RootBridgeHandle    Given root bridge handle.\r
205 \r
206   @return The root bridge device instance, NULL means no root bridge\r
207           device instance found.\r
208 \r
209 **/\r
210 PCI_IO_DEVICE *\r
211 GetRootBridgeByHandle (\r
212   EFI_HANDLE RootBridgeHandle\r
213   );\r
214 \r
215 \r
216 /**\r
217   Judege whether Pci device existed.\r
218 \r
219   @param Bridge       Parent bridege instance.\r
220   @param PciIoDevice  Device instance.\r
221 \r
222   @retval TRUE        Pci device existed.\r
223   @retval FALSE       Pci device did not exist.\r
224 \r
225 **/\r
226 BOOLEAN\r
227 PciDeviceExisted (\r
228   IN PCI_IO_DEVICE    *Bridge,\r
229   IN PCI_IO_DEVICE    *PciIoDevice\r
230   );\r
231 \r
232 /**\r
233   Get the active VGA device on the specified Host Bridge.\r
234 \r
235   @param HostBridgeHandle    Host Bridge handle.\r
236 \r
237   @return The active VGA device on the specified Host Bridge.\r
238 \r
239 **/\r
240 PCI_IO_DEVICE *\r
241 LocateVgaDeviceOnHostBridge (\r
242   IN EFI_HANDLE           HostBridgeHandle\r
243   );\r
244 \r
245 /**\r
246   Locate the active VGA device under the bridge.\r
247 \r
248   @param Bridge  PCI IO instance for the bridge.\r
249 \r
250   @return The active VGA device.\r
251 \r
252 **/\r
253 PCI_IO_DEVICE *\r
254 LocateVgaDevice (\r
255   IN PCI_IO_DEVICE        *Bridge\r
256   );\r
257 \r
258 \r
259 /**\r
260   Destroy a pci device node.\r
261 \r
262   All direct or indirect allocated resource for this node will be freed.\r
263 \r
264   @param PciIoDevice  A pointer to the PCI_IO_DEVICE to be destoried.\r
265 \r
266 **/\r
267 VOID\r
268 FreePciDevice (\r
269   IN PCI_IO_DEVICE    *PciIoDevice\r
270   );\r
271 \r
272 #endif\r