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