MdeModulePkg/PciBus: Correct typos
[mirror_edk2.git] / MdeModulePkg / Bus / Pci / PciBusDxe / PciResourceSupport.h
1 /** @file\r
2   PCI resources support functions declaration for PCI Bus module.\r
3 \r
4 Copyright (c) 2006 - 2019, 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_RESOURCE_SUPPORT_H_\r
16 #define _EFI_PCI_RESOURCE_SUPPORT_H_\r
17 \r
18 typedef enum {\r
19   PciResUsageTypical,\r
20   PciResUsagePadding\r
21 } PCI_RESOURCE_USAGE;\r
22 \r
23 #define PCI_RESOURCE_SIGNATURE  SIGNATURE_32 ('p', 'c', 'r', 'c')\r
24 \r
25 typedef struct {\r
26   UINT32              Signature;\r
27   LIST_ENTRY          Link;\r
28   LIST_ENTRY          ChildList;\r
29   PCI_IO_DEVICE       *PciDev;\r
30   UINT64              Alignment;\r
31   UINT64              Offset;\r
32   UINT8               Bar;\r
33   PCI_BAR_TYPE        ResType;\r
34   UINT64              Length;\r
35   BOOLEAN             Reserved;\r
36   PCI_RESOURCE_USAGE  ResourceUsage;\r
37   BOOLEAN             Virtual;\r
38 } PCI_RESOURCE_NODE;\r
39 \r
40 #define RESOURCE_NODE_FROM_LINK(a) \\r
41   CR (a, PCI_RESOURCE_NODE, Link, PCI_RESOURCE_SIGNATURE)\r
42 \r
43 /**\r
44   The function is used to skip VGA range.\r
45 \r
46   @param Start    Returned start address including VGA range.\r
47   @param Length   The length of VGA range.\r
48 \r
49 **/\r
50 VOID\r
51 SkipVGAAperture (\r
52   OUT UINT64   *Start,\r
53   IN  UINT64   Length\r
54   );\r
55 \r
56 /**\r
57   This function is used to skip ISA aliasing aperture.\r
58 \r
59   @param Start    Returned start address including ISA aliasing aperture.\r
60   @param Length   The length of ISA aliasing aperture.\r
61 \r
62 **/\r
63 VOID\r
64 SkipIsaAliasAperture (\r
65   OUT UINT64   *Start,\r
66   IN  UINT64   Length\r
67   );\r
68 \r
69 /**\r
70   This function inserts a resource node into the resource list.\r
71   The resource list is sorted in descend order.\r
72 \r
73   @param Bridge  PCI resource node for bridge.\r
74   @param ResNode Resource node want to be inserted.\r
75 \r
76 **/\r
77 VOID\r
78 InsertResourceNode (\r
79   IN OUT PCI_RESOURCE_NODE   *Bridge,\r
80   IN     PCI_RESOURCE_NODE   *ResNode\r
81   );\r
82 \r
83 /**\r
84   This routine is used to merge two different resource trees in need of\r
85   resource degradation.\r
86 \r
87   For example, if an upstream PPB doesn't support,\r
88   prefetchable memory decoding, the PCI bus driver will choose to call this function\r
89   to merge prefetchable memory resource list into normal memory list.\r
90 \r
91   If the TypeMerge is TRUE, Res resource type is changed to the type of destination resource\r
92   type.\r
93   If Dst is NULL or Res is NULL, ASSERT ().\r
94 \r
95   @param Dst        Point to destination resource tree.\r
96   @param Res        Point to source resource tree.\r
97   @param TypeMerge  If the TypeMerge is TRUE, Res resource type is changed to the type of\r
98                     destination resource type.\r
99 \r
100 **/\r
101 VOID\r
102 MergeResourceTree (\r
103   IN PCI_RESOURCE_NODE   *Dst,\r
104   IN PCI_RESOURCE_NODE   *Res,\r
105   IN BOOLEAN             TypeMerge\r
106   );\r
107 \r
108 /**\r
109   This function is used to calculate the IO16 aperture\r
110   for a bridge.\r
111 \r
112   @param Bridge    PCI resource node for bridge.\r
113 \r
114 **/\r
115 VOID\r
116 CalculateApertureIo16 (\r
117   IN PCI_RESOURCE_NODE    *Bridge\r
118   );\r
119 \r
120 /**\r
121   This function is used to calculate the resource aperture\r
122   for a given bridge device.\r
123 \r
124   @param Bridge      PCI resource node for given bridge device.\r
125 \r
126 **/\r
127 VOID\r
128 CalculateResourceAperture (\r
129   IN PCI_RESOURCE_NODE    *Bridge\r
130   );\r
131 \r
132 /**\r
133   Get IO/Memory resource info for given PCI device.\r
134 \r
135   @param PciDev     Pci device instance.\r
136   @param IoNode     Resource info node for IO .\r
137   @param Mem32Node  Resource info node for 32-bit memory.\r
138   @param PMem32Node Resource info node for 32-bit Prefetchable Memory.\r
139   @param Mem64Node  Resource info node for 64-bit memory.\r
140   @param PMem64Node Resource info node for 64-bit Prefetchable Memory.\r
141 \r
142 **/\r
143 VOID\r
144 GetResourceFromDevice (\r
145   IN     PCI_IO_DEVICE     *PciDev,\r
146   IN OUT PCI_RESOURCE_NODE *IoNode,\r
147   IN OUT PCI_RESOURCE_NODE *Mem32Node,\r
148   IN OUT PCI_RESOURCE_NODE *PMem32Node,\r
149   IN OUT PCI_RESOURCE_NODE *Mem64Node,\r
150   IN OUT PCI_RESOURCE_NODE *PMem64Node\r
151   );\r
152 \r
153 /**\r
154   This function is used to create a resource node.\r
155 \r
156   @param PciDev       Pci device instance.\r
157   @param Length       Length of Io/Memory resource.\r
158   @param Alignment    Alignment of resource.\r
159   @param Bar          Bar index.\r
160   @param ResType      Type of resource: IO/Memory.\r
161   @param ResUsage     Resource usage.\r
162 \r
163   @return PCI resource node created for given PCI device.\r
164           NULL means PCI resource node is not created.\r
165 \r
166 **/\r
167 PCI_RESOURCE_NODE *\r
168 CreateResourceNode (\r
169   IN PCI_IO_DEVICE         *PciDev,\r
170   IN UINT64                Length,\r
171   IN UINT64                Alignment,\r
172   IN UINT8                 Bar,\r
173   IN PCI_BAR_TYPE          ResType,\r
174   IN PCI_RESOURCE_USAGE    ResUsage\r
175   );\r
176 \r
177 /**\r
178   This function is used to create a IOV VF resource node.\r
179 \r
180   @param PciDev       Pci device instance.\r
181   @param Length       Length of Io/Memory resource.\r
182   @param Alignment    Alignment of resource.\r
183   @param Bar          Bar index.\r
184   @param ResType      Type of resource: IO/Memory.\r
185   @param ResUsage     Resource usage.\r
186 \r
187   @return PCI resource node created for given VF PCI device.\r
188           NULL means PCI resource node is not created.\r
189 \r
190 **/\r
191 PCI_RESOURCE_NODE *\r
192 CreateVfResourceNode (\r
193   IN PCI_IO_DEVICE         *PciDev,\r
194   IN UINT64                Length,\r
195   IN UINT64                Alignment,\r
196   IN UINT8                 Bar,\r
197   IN PCI_BAR_TYPE          ResType,\r
198   IN PCI_RESOURCE_USAGE    ResUsage\r
199   );\r
200 \r
201 /**\r
202   This function is used to extract resource request from\r
203   device node list.\r
204 \r
205   @param Bridge     Pci device instance.\r
206   @param IoNode     Resource info node for IO.\r
207   @param Mem32Node  Resource info node for 32-bit memory.\r
208   @param PMem32Node Resource info node for 32-bit Prefetchable Memory.\r
209   @param Mem64Node  Resource info node for 64-bit memory.\r
210   @param PMem64Node Resource info node for 64-bit Prefetchable Memory.\r
211 \r
212 **/\r
213 VOID\r
214 CreateResourceMap (\r
215   IN     PCI_IO_DEVICE     *Bridge,\r
216   IN OUT PCI_RESOURCE_NODE *IoNode,\r
217   IN OUT PCI_RESOURCE_NODE *Mem32Node,\r
218   IN OUT PCI_RESOURCE_NODE *PMem32Node,\r
219   IN OUT PCI_RESOURCE_NODE *Mem64Node,\r
220   IN OUT PCI_RESOURCE_NODE *PMem64Node\r
221   );\r
222 \r
223 /**\r
224   This function is used to do the resource padding for a specific platform.\r
225 \r
226   @param PciDev     Pci device instance.\r
227   @param IoNode     Resource info node for IO.\r
228   @param Mem32Node  Resource info node for 32-bit memory.\r
229   @param PMem32Node Resource info node for 32-bit Prefetchable Memory.\r
230   @param Mem64Node  Resource info node for 64-bit memory.\r
231   @param PMem64Node Resource info node for 64-bit Prefetchable Memory.\r
232 \r
233 **/\r
234 VOID\r
235 ResourcePaddingPolicy (\r
236   IN PCI_IO_DEVICE     *PciDev,\r
237   IN PCI_RESOURCE_NODE *IoNode,\r
238   IN PCI_RESOURCE_NODE *Mem32Node,\r
239   IN PCI_RESOURCE_NODE *PMem32Node,\r
240   IN PCI_RESOURCE_NODE *Mem64Node,\r
241   IN PCI_RESOURCE_NODE *PMem64Node\r
242   );\r
243 \r
244 /**\r
245   This function is used to degrade resource if the upstream bridge\r
246   doesn't support certain resource. Degradation path is\r
247   PMEM64 -> MEM64  -> MEM32\r
248   PMEM64 -> PMEM32 -> MEM32\r
249   IO32   -> IO16.\r
250 \r
251   @param Bridge     Pci device instance.\r
252   @param Mem32Node  Resource info node for 32-bit memory.\r
253   @param PMem32Node Resource info node for 32-bit Prefetchable Memory.\r
254   @param Mem64Node  Resource info node for 64-bit memory.\r
255   @param PMem64Node Resource info node for 64-bit Prefetchable Memory.\r
256 \r
257 **/\r
258 VOID\r
259 DegradeResource (\r
260   IN PCI_IO_DEVICE     *Bridge,\r
261   IN PCI_RESOURCE_NODE *Mem32Node,\r
262   IN PCI_RESOURCE_NODE *PMem32Node,\r
263   IN PCI_RESOURCE_NODE *Mem64Node,\r
264   IN PCI_RESOURCE_NODE *PMem64Node\r
265   );\r
266 \r
267 /**\r
268   Test whether bridge device support decode resource.\r
269 \r
270   @param Bridge    Bridge device instance.\r
271   @param Decode    Decode type according to resource type.\r
272 \r
273   @return TRUE     The bridge device support decode resource.\r
274   @return FALSE    The bridge device don't support decode resource.\r
275 \r
276 **/\r
277 BOOLEAN\r
278 BridgeSupportResourceDecode (\r
279   IN PCI_IO_DEVICE *Bridge,\r
280   IN UINT32        Decode\r
281   );\r
282 \r
283 /**\r
284   This function is used to program the resource allocated\r
285   for each resource node under specified bridge.\r
286 \r
287   @param Base     Base address of resource to be programmed.\r
288   @param Bridge   PCI resource node for the bridge device.\r
289 \r
290   @retval EFI_SUCCESS            Successfully to program all resources\r
291                                  on given PCI bridge device.\r
292   @retval EFI_OUT_OF_RESOURCES   Base is all one.\r
293 \r
294 **/\r
295 EFI_STATUS\r
296 ProgramResource (\r
297   IN UINT64            Base,\r
298   IN PCI_RESOURCE_NODE *Bridge\r
299   );\r
300 \r
301 /**\r
302   Program Bar register for PCI device.\r
303 \r
304   @param Base  Base address for PCI device resource to be programmed.\r
305   @param Node  Point to resource node structure.\r
306 \r
307 **/\r
308 VOID\r
309 ProgramBar (\r
310   IN UINT64            Base,\r
311   IN PCI_RESOURCE_NODE *Node\r
312   );\r
313 \r
314 /**\r
315   Program IOV VF Bar register for PCI device.\r
316 \r
317   @param Base  Base address for PCI device resource to be programmed.\r
318   @param Node  Point to resource node structure.\r
319 \r
320 **/\r
321 EFI_STATUS\r
322 ProgramVfBar (\r
323   IN UINT64            Base,\r
324   IN PCI_RESOURCE_NODE *Node\r
325   );\r
326 \r
327 /**\r
328   Program PCI-PCI bridge aperture.\r
329 \r
330   @param Base  Base address for resource.\r
331   @param Node  Point to resource node structure.\r
332 \r
333 **/\r
334 VOID\r
335 ProgramPpbApperture (\r
336   IN UINT64            Base,\r
337   IN PCI_RESOURCE_NODE *Node\r
338   );\r
339 \r
340 /**\r
341   Program parent bridge for Option Rom.\r
342 \r
343   @param PciDevice      Pci device instance.\r
344   @param OptionRomBase  Base address for Option Rom.\r
345   @param Enable         Enable or disable PCI memory.\r
346 \r
347 **/\r
348 VOID\r
349 ProgramUpstreamBridgeForRom (\r
350   IN PCI_IO_DEVICE   *PciDevice,\r
351   IN UINT32          OptionRomBase,\r
352   IN BOOLEAN         Enable\r
353   );\r
354 \r
355 /**\r
356   Test whether resource exists for a bridge.\r
357 \r
358   @param Bridge  Point to resource node for a bridge.\r
359 \r
360   @retval TRUE   There is resource on the given bridge.\r
361   @retval FALSE  There isn't resource on the given bridge.\r
362 \r
363 **/\r
364 BOOLEAN\r
365 ResourceRequestExisted (\r
366   IN PCI_RESOURCE_NODE    *Bridge\r
367   );\r
368 \r
369 /**\r
370   Initialize resource pool structure.\r
371 \r
372   @param ResourcePool Point to resource pool structure. This pool\r
373                       is reset to all zero when returned.\r
374   @param ResourceType Type of resource.\r
375 \r
376 **/\r
377 VOID\r
378 InitializeResourcePool (\r
379   IN OUT PCI_RESOURCE_NODE   *ResourcePool,\r
380   IN     PCI_BAR_TYPE        ResourceType\r
381   );\r
382 \r
383 /**\r
384   Destroy given resource tree.\r
385 \r
386   @param Bridge  PCI resource root node of resource tree.\r
387 \r
388 **/\r
389 VOID\r
390 DestroyResourceTree (\r
391   IN PCI_RESOURCE_NODE *Bridge\r
392   );\r
393 \r
394 /**\r
395   Insert resource padding for P2C.\r
396 \r
397   @param PciDev     Pci device instance.\r
398   @param IoNode     Resource info node for IO.\r
399   @param Mem32Node  Resource info node for 32-bit memory.\r
400   @param PMem32Node Resource info node for 32-bit Prefetchable Memory.\r
401   @param Mem64Node  Resource info node for 64-bit memory.\r
402   @param PMem64Node Resource info node for 64-bit Prefetchable Memory.\r
403 \r
404 **/\r
405 VOID\r
406 ResourcePaddingForCardBusBridge (\r
407   IN PCI_IO_DEVICE        *PciDev,\r
408   IN PCI_RESOURCE_NODE    *IoNode,\r
409   IN PCI_RESOURCE_NODE    *Mem32Node,\r
410   IN PCI_RESOURCE_NODE    *PMem32Node,\r
411   IN PCI_RESOURCE_NODE    *Mem64Node,\r
412   IN PCI_RESOURCE_NODE    *PMem64Node\r
413   );\r
414 \r
415 /**\r
416   Program PCI Card device register for given resource node.\r
417 \r
418   @param Base    Base address of PCI Card device to be programmed.\r
419   @param Node    Given resource node.\r
420 \r
421 **/\r
422 VOID\r
423 ProgramP2C (\r
424   IN UINT64            Base,\r
425   IN PCI_RESOURCE_NODE *Node\r
426   );\r
427 \r
428 /**\r
429   Create padding resource node.\r
430 \r
431   @param PciDev     Pci device instance.\r
432   @param IoNode     Resource info node for IO.\r
433   @param Mem32Node  Resource info node for 32-bit memory.\r
434   @param PMem32Node Resource info node for 32-bit Prefetchable Memory.\r
435   @param Mem64Node  Resource info node for 64-bit memory.\r
436   @param PMem64Node Resource info node for 64-bit Prefetchable Memory.\r
437 \r
438 **/\r
439 VOID\r
440 ApplyResourcePadding (\r
441   IN PCI_IO_DEVICE         *PciDev,\r
442   IN PCI_RESOURCE_NODE     *IoNode,\r
443   IN PCI_RESOURCE_NODE     *Mem32Node,\r
444   IN PCI_RESOURCE_NODE     *PMem32Node,\r
445   IN PCI_RESOURCE_NODE     *Mem64Node,\r
446   IN PCI_RESOURCE_NODE     *PMem64Node\r
447   );\r
448 \r
449 /**\r
450   Get padding resource for PCI-PCI bridge.\r
451 \r
452   @param  PciIoDevice     PCI-PCI bridge device instance.\r
453 \r
454   @note   Feature flag PcdPciBusHotplugDeviceSupport determines\r
455           whether need to pad resource for them.\r
456 **/\r
457 VOID\r
458 GetResourcePaddingPpb (\r
459   IN  PCI_IO_DEVICE                  *PciIoDevice\r
460   );\r
461 \r
462 #endif\r