1 /** @file
2   PCI Hot Plug support functions declaration for PCI Bus module.
3 
4 Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
6 
7 **/
8 
9 #ifndef _EFI_PCI_HOT_PLUG_SUPPORT_H_
10 #define _EFI_PCI_HOT_PLUG_SUPPORT_H_
11 
12 //
13 // stall 1 second, its unit is 100ns
14 //
15 #define STALL_1_SECOND        1000000
16 
17 //
18 // PCI Hot Plug controller private data
19 //
20 typedef struct {
21   EFI_EVENT Event;
22   BOOLEAN   Found;
23   BOOLEAN   Initialized;
24   VOID      *Padding;
25 } ROOT_HPC_DATA;
26 
27 //
28 // Reference of some global variables
29 //
30 extern EFI_PCI_HOT_PLUG_INIT_PROTOCOL *gPciHotPlugInit;
31 extern EFI_HPC_LOCATION               *gPciRootHpcPool;
32 extern ROOT_HPC_DATA                  *gPciRootHpcData;
33 
34 /**
35   Event notification function to set Hot Plug controller status.
36 
37   @param  Event                    The event that invoke this function.
38   @param  Context                  The calling context, pointer to ROOT_HPC_DATA.
39 
40 **/
41 VOID
42 EFIAPI
43 PciHPCInitialized (
44   IN EFI_EVENT    Event,
45   IN VOID         *Context
46   );
47 
48 /**
49   Compare two device paths to check if they are exactly same.
50 
51   @param DevicePath1    A pointer to the first device path data structure.
52   @param DevicePath2    A pointer to the second device path data structure.
53 
54   @retval TRUE    They are same.
55   @retval FALSE   They are not same.
56 
57 **/
58 BOOLEAN
59 EfiCompareDevicePath (
60   IN EFI_DEVICE_PATH_PROTOCOL *DevicePath1,
61   IN EFI_DEVICE_PATH_PROTOCOL *DevicePath2
62   );
63 
64 /**
65   Check hot plug support and initialize root hot plug private data.
66 
67   If Hot Plug is supported by the platform, call PCI Hot Plug Init protocol
68   to get PCI Hot Plug controller's information and constructor the root hot plug
69   private data structure.
70 
71   @retval EFI_SUCCESS           They are same.
72   @retval EFI_UNSUPPORTED       No PCI Hot Plug controller on the platform.
73   @retval EFI_OUT_OF_RESOURCES  No memory to constructor root hot plug private
74                                 data structure.
75 
76 **/
77 EFI_STATUS
78 InitializeHotPlugSupport (
79   VOID
80   );
81 
82 /**
83   Test whether PCI device is hot plug bus.
84 
85   @param PciIoDevice  PCI device instance.
86 
87   @retval TRUE    PCI device is a hot plug bus.
88   @retval FALSE   PCI device is not a hot plug bus.
89 
90 **/
91 BOOLEAN
92 IsPciHotPlugBus (
93   PCI_IO_DEVICE                       *PciIoDevice
94   );
95 
96 /**
97   Test whether device path is for root pci hot plug bus.
98 
99   @param HpbDevicePath  A pointer to device path data structure to be tested.
100   @param HpIndex        If HpIndex is not NULL, return the index of root hot
101                         plug in global array when TRUE is returned.
102 
103   @retval TRUE          The device path is for root pci hot plug bus.
104   @retval FALSE         The device path is not for root pci hot plug bus.
105 
106 **/
107 BOOLEAN
108 IsRootPciHotPlugBus (
109   IN  EFI_DEVICE_PATH_PROTOCOL        *HpbDevicePath,
110   OUT UINTN                           *HpIndex    OPTIONAL
111   );
112 
113 /**
114   Test whether device path is for root pci hot plug controller.
115 
116   @param HpcDevicePath  A pointer to device path data structure to be tested.
117   @param HpIndex        If HpIndex is not NULL, return the index of root hot
118                         plug in global array when TRUE is returned.
119 
120   @retval TRUE          The device path is for root pci hot plug controller.
121   @retval FALSE         The device path is not for root pci hot plug controller.
122 
123 **/
124 BOOLEAN
125 IsRootPciHotPlugController (
126   IN EFI_DEVICE_PATH_PROTOCOL         *HpcDevicePath,
127   OUT UINTN                           *HpIndex
128   );
129 
130 /**
131   Creating event object for PCI Hot Plug controller.
132 
133   @param  HpIndex   Index of hot plug device in global array.
134   @param  Event     The returned event that invoke this function.
135 
136   @return Status of create event.
137 
138 **/
139 EFI_STATUS
140 CreateEventForHpc (
141   IN  UINTN      HpIndex,
142   OUT EFI_EVENT  *Event
143   );
144 
145 /**
146   Wait for all root PCI Hot Plug controller finished initializing.
147 
148   @param TimeoutInMicroSeconds  Microseconds to wait for all root HPCs' initialization.
149 
150   @retval EFI_SUCCESS           All HPCs initialization finished.
151   @retval EFI_TIMEOUT           Not ALL HPCs initialization finished in Microseconds.
152 
153 **/
154 EFI_STATUS
155 AllRootHPCInitialized (
156   IN  UINTN           TimeoutInMicroSeconds
157   );
158 
159 /**
160   Check whether PCI-PCI bridge has PCI Hot Plug capability register block.
161 
162   @param PciIoDevice    A Pointer to the PCI-PCI bridge.
163 
164   @retval TRUE    PCI device is HPC.
165   @retval FALSE   PCI device is not HPC.
166 
167 **/
168 BOOLEAN
169 IsSHPC (
170   IN PCI_IO_DEVICE                      *PciIoDevice
171   );
172 
173 /**
174   Check whether PciIoDevice supports PCIe hotplug.
175 
176   This is equivalent to the following condition:
177   - the device is either a PCIe switch downstream port or a root port,
178   - and the device has the SlotImplemented bit set in its PCIe capability
179     register,
180   - and the device has the HotPlugCapable bit set in its slot capabilities
181     register.
182 
183   @param[in] PciIoDevice  The device being checked.
184 
185   @retval TRUE   PciIoDevice is a PCIe port that accepts a hot-plugged device.
186   @retval FALSE  Otherwise.
187 
188 **/
189 BOOLEAN
190 SupportsPcieHotplug (
191   IN PCI_IO_DEVICE                      *PciIoDevice
192   );
193 
194 /**
195   Get resource padding if the specified PCI bridge is a hot plug bus.
196 
197   @param PciIoDevice    PCI bridge instance.
198 
199 **/
200 VOID
201 GetResourcePaddingForHpb (
202   IN PCI_IO_DEVICE      *PciIoDevice
203   );
204 
205 #endif
206