Initial import.
[mirror_edk2.git] / Tools / Source / TianoTools / Common / PeiLib / PeiLib.h
1 /*++
2
3 Copyright (c) 2004, Intel Corporation
4 All rights reserved. This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
8
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
11
12 Module Name:
13
14 PeiLib.h
15
16 Abstract:
17
18 PEI Library Functions
19
20 --*/
21
22 #ifndef _PEI_LIB_H_
23 #define _PEI_LIB_H_
24
25 #include "Tiano.h"
26 #include "Pei.h"
27 #include "peiHobLib.h"
28 #include EFI_PROTOCOL_DEFINITION (Decompress)
29 #include EFI_PROTOCOL_DEFINITION (TianoDecompress)
30 #include EFI_GUID_DEFINITION (PeiPeCoffLoader)
31
32 VOID
33 PeiCopyMem (
34 IN VOID *Destination,
35 IN VOID *Source,
36 IN UINTN Length
37 )
38 /*++
39
40 Routine Description:
41
42 Copy Length bytes from Source to Destination.
43
44 Arguments:
45
46 Destination - Target of copy
47
48 Source - Place to copy from
49
50 Length - Number of bytes to copy
51
52 Returns:
53
54 None
55
56 --*/
57 ;
58
59 VOID
60 ZeroMem (
61 IN VOID *Buffer,
62 IN UINTN Size
63 )
64 /*++
65
66 Routine Description:
67
68 Set Buffer to zero for Size bytes.
69
70 Arguments:
71
72 Buffer - Memory to set.
73
74 Size - Number of bytes to set
75
76 Returns:
77
78 None
79
80 --*/
81 ;
82
83 VOID
84 CopyMem (
85 IN VOID *Destination,
86 IN VOID *Source,
87 IN UINTN Length
88 )
89 /*++
90
91 Routine Description:
92
93 Copy Length bytes from Source to Destination.
94
95 Arguments:
96
97 Destination - Target of copy
98
99 Source - Place to copy from
100
101 Length - Number of bytes to copy
102
103 Returns:
104
105 None
106
107 --*/
108 ;
109
110 BOOLEAN
111 CompareGuid (
112 IN EFI_GUID *Guid1,
113 IN EFI_GUID *Guid2
114 )
115 /*++
116
117 Routine Description:
118
119 Compares two GUIDs
120
121 Arguments:
122
123 Guid1 - guid to compare
124 Guid2 - guid to compare
125
126 Returns:
127 = TRUE if Guid1 == Guid2
128 = FALSE if Guid1 != Guid2
129
130 --*/
131 ;
132
133 EFI_STATUS
134 InstallEfiPeiPeCoffLoader (
135 IN EFI_PEI_SERVICES **PeiServices,
136 IN EFI_PEI_PE_COFF_LOADER_PROTOCOL **This,
137 IN EFI_PEI_PPI_DESCRIPTOR *ThisPpi
138 )
139 /*++
140
141 Routine Description:
142
143 Install EFI Pei PE coff loader protocol.
144
145 Arguments:
146
147 PeiServices - The PEI core services table.
148
149 This - Pointer to get Pei PE coff loader protocol as output
150
151 ThisPpi - Passed in as EFI_NT_LOAD_AS_DLL_PPI on NT_EMULATOR platform
152
153 Returns:
154
155 EFI_SUCCESS
156
157 --*/
158 ;
159
160 EFI_STATUS
161 InstallEfiDecompress (
162 EFI_DECOMPRESS_PROTOCOL **This
163 )
164 /*++
165
166 Routine Description:
167
168 Install EFI decompress protocol.
169
170 Arguments:
171
172 This - Pointer to get decompress protocol as output
173
174 Returns:
175
176 EFI_SUCCESS - EFI decompress protocol successfully installed.
177
178 --*/
179 ;
180
181 EFI_STATUS
182 InstallTianoDecompress (
183 EFI_TIANO_DECOMPRESS_PROTOCOL **This
184 )
185 /*++
186
187 Routine Description:
188
189 Install Tiano decompress protocol.
190
191 Arguments:
192
193 This - Pointer to get decompress protocol as output
194
195 Returns:
196
197 EFI_SUCCESS - Tiano decompress protocol successfully installed.
198
199 --*/
200 ;
201
202 VOID
203 PeiPerfMeasure (
204 EFI_PEI_SERVICES **PeiServices,
205 IN UINT16 *Token,
206 IN EFI_FFS_FILE_HEADER *FileHeader,
207 IN BOOLEAN EntryExit,
208 IN UINT64 Value
209 )
210 /*++
211
212 Routine Description:
213
214 Log a timestamp count.
215
216 Arguments:
217
218 PeiServices - Pointer to the PEI Core Services table
219
220 Token - Pointer to Token Name
221
222 FileHeader - Pointer to the file header
223
224 EntryExit - Indicates start or stop measurement
225
226 Value - The start time or the stop time
227
228 Returns:
229
230 --*/
231 ;
232
233 EFI_STATUS
234 GetTimerValue (
235 OUT UINT64 *TimerValue
236 )
237 /*++
238
239 Routine Description:
240
241 Get timer value.
242
243 Arguments:
244
245 TimerValue - Pointer to the returned timer value
246
247 Returns:
248
249 EFI_SUCCESS - Successfully got timer value
250
251 --*/
252 ;
253
254 #ifdef EFI_PEI_PERFORMANCE
255 #define PEI_PERF_START(Ps, Token, FileHeader, Value) PeiPerfMeasure (Ps, Token, FileHeader, FALSE, Value)
256 #define PEI_PERF_END(Ps, Token, FileHeader, Value) PeiPerfMeasure (Ps, Token, FileHeader, TRUE, Value)
257 #else
258 #define PEI_PERF_START(Ps, Token, FileHeader, Value)
259 #define PEI_PERF_END(Ps, Token, FileHeader, Value)
260 #endif
261
262 #ifdef EFI_NT_EMULATOR
263 EFI_STATUS
264 PeCoffLoaderWinNtLoadAsDll (
265 IN CHAR8 *PdbFileName,
266 IN VOID **ImageEntryPoint,
267 OUT VOID **ModHandle
268 )
269 /*++
270
271 Routine Description:
272
273 Loads the .DLL file is present when a PE/COFF file is loaded. This provides source level
274 debugging for drivers that have cooresponding .DLL files on the local system.
275
276 Arguments:
277
278 PdbFileName - The name of the .PDB file. This was found from the PE/COFF
279 file's debug directory entry.
280
281 ImageEntryPoint - A pointer to the DLL entry point of the .DLL file was loaded.
282
283 ModHandle - Pointer to loaded library.
284
285 Returns:
286
287 EFI_SUCCESS - The .DLL file was loaded, and the DLL entry point is returned in ImageEntryPoint
288
289 EFI_NOT_FOUND - The .DLL file could not be found
290
291 EFI_UNSUPPORTED - The .DLL file was loaded, but the entry point to the .DLL file could not
292 determined.
293
294 --*/
295 ;
296
297 #endif
298 //
299 // hob.c
300 //
301 EFI_STATUS
302 PeiBuildHobModule (
303 IN EFI_PEI_SERVICES **PeiServices,
304 IN EFI_GUID *ModuleName,
305 IN EFI_PHYSICAL_ADDRESS Module,
306 IN UINT64 ModuleLength,
307 IN EFI_PHYSICAL_ADDRESS EntryPoint
308 )
309 /*++
310
311 Routine Description:
312
313 Builds a HOB for a loaded PE32 module
314
315 Arguments:
316
317 PeiServices - The PEI core services table.
318 ModuleName - The GUID File Name of the module
319 Memory - The 64 bit physical address of the module
320 ModuleLength - The length of the module in bytes
321 EntryPoint - The 64 bit physical address of the entry point
322 to the module
323
324 Returns:
325
326 EFI_SUCCESS - Hob is successfully built.
327 Others - Errors occur while creating new Hob
328
329 --*/
330 ;
331
332 EFI_STATUS
333 PeiBuildHobResourceDescriptor (
334 IN EFI_PEI_SERVICES **PeiServices,
335 IN EFI_RESOURCE_TYPE ResourceType,
336 IN EFI_RESOURCE_ATTRIBUTE_TYPE ResourceAttribute,
337 IN EFI_PHYSICAL_ADDRESS PhysicalStart,
338 IN UINT64 NumberOfBytes
339 )
340 /*++
341
342 Routine Description:
343
344 Builds a HOB that describes a chunck of system memory
345
346 Arguments:
347
348 PeiServices - The PEI core services table.
349
350 ResourceType - The type of resource described by this HOB
351
352 ResourceAttribute - The resource attributes of the memory described by this HOB
353
354 PhysicalStart - The 64 bit physical address of memory described by this HOB
355
356 NumberOfBytes - The length of the memoty described by this HOB in bytes
357
358 Returns:
359
360 EFI_SUCCESS - Hob is successfully built.
361 Others - Errors occur while creating new Hob
362
363 --*/
364 ;
365
366 EFI_STATUS
367 PeiBuildHobGuid (
368 IN EFI_PEI_SERVICES **PeiServices,
369 IN EFI_GUID *Guid,
370 IN UINTN DataLength,
371 IN OUT VOID **Hob
372 )
373 /*++
374
375 Routine Description:
376
377 Builds a custom HOB that is tagged with a GUID for identification
378
379 Arguments:
380
381 PeiServices - The PEI core services table.
382
383 Guid - The GUID of the custome HOB type
384
385 DataLength - The size of the data payload for the GUIDed HOB
386
387 Hob - Pointer to the Hob
388
389 Returns:
390
391 EFI_SUCCESS - Hob is successfully built.
392 Others - Errors occur while creating new Hob
393
394 --*/
395 ;
396
397 EFI_STATUS
398 PeiBuildHobGuidData (
399 IN EFI_PEI_SERVICES **PeiServices,
400 IN EFI_GUID *Guid,
401 IN VOID *Data,
402 IN UINTN DataLength
403 )
404 /*++
405
406 Routine Description:
407
408 Builds a custom HOB that is tagged with a GUID for identification
409
410 Arguments:
411
412 PeiServices - The PEI core services table.
413
414 Guid - The GUID of the custome HOB type
415
416 Data - The data to be copied into the GUIDed HOB data field.
417
418 DataLength - The data field length.
419
420 Returns:
421
422 EFI_SUCCESS - Hob is successfully built.
423 Others - Errors occur while creating new Hob
424
425 --*/
426 ;
427
428 EFI_STATUS
429 PeiBuildHobFv (
430 IN EFI_PEI_SERVICES **PeiServices,
431 IN EFI_PHYSICAL_ADDRESS BaseAddress,
432 IN UINT64 Length
433 )
434 /*++
435
436 Routine Description:
437
438 Builds a Firmware Volume HOB
439
440 Arguments:
441
442 PeiServices - The PEI core services table.
443
444 BaseAddress - The base address of the Firmware Volume
445
446 Length - The size of the Firmware Volume in bytes
447
448 Returns:
449
450 EFI_SUCCESS - Hob is successfully built.
451 Others - Errors occur while creating new Hob
452
453 --*/
454 ;
455
456 EFI_STATUS
457 PeiBuildHobCpu (
458 IN EFI_PEI_SERVICES **PeiServices,
459 IN UINT8 SizeOfMemorySpace,
460 IN UINT8 SizeOfIoSpace
461 )
462 /*++
463
464 Routine Description:
465
466 Builds a HOB for the CPU
467
468 Arguments:
469
470 PeiServices - The PEI core services table.
471
472 SizeOfMemorySpace - Identifies the maximum
473 physical memory addressibility of the processor.
474
475 SizeOfIoSpace - Identifies the maximum physical I/O addressibility
476 of the processor.
477
478 Returns:
479
480 EFI_SUCCESS - Hob is successfully built.
481 Others - Errors occur while creating new Hob
482
483 --*/
484 ;
485
486 EFI_STATUS
487 PeiBuildHobStack (
488 IN EFI_PEI_SERVICES **PeiServices,
489 IN EFI_PHYSICAL_ADDRESS BaseAddress,
490 IN UINT64 Length
491 )
492 /*++
493
494 Routine Description:
495
496 Builds a HOB for the Stack
497
498 Arguments:
499
500 PeiServices - The PEI core services table.
501
502 BaseAddress - The 64 bit physical address of the Stack
503
504 Length - The length of the stack in bytes
505
506 Returns:
507
508 EFI_SUCCESS - Hob is successfully built.
509 Others - Errors occur while creating new Hob
510
511 --*/
512 ;
513
514 EFI_STATUS
515 PeiBuildHobBspStore (
516 IN EFI_PEI_SERVICES **PeiServices,
517 IN EFI_PHYSICAL_ADDRESS BaseAddress,
518 IN UINT64 Length,
519 IN EFI_MEMORY_TYPE MemoryType
520 )
521 /*++
522
523 Routine Description:
524
525 Builds a HOB for the bsp store
526
527 Arguments:
528
529 PeiServices - The PEI core services table.
530
531 BaseAddress - The 64 bit physical address of the bsp store
532
533 Length - The length of the bsp store in bytes
534
535 MemoryType - Memory type
536
537 Returns:
538
539 EFI_SUCCESS - Hob is successfully built.
540 Others - Errors occur while creating new Hob
541
542 --*/
543 ;
544
545 EFI_STATUS
546 PeiBuildHobMemoryAllocation (
547 IN EFI_PEI_SERVICES **PeiServices,
548 IN EFI_PHYSICAL_ADDRESS BaseAddress,
549 IN UINT64 Length,
550 IN EFI_GUID *Name,
551 IN EFI_MEMORY_TYPE MemoryType
552 )
553 /*++
554
555 Routine Description:
556
557 Builds a HOB for the memory allocation
558
559 Arguments:
560
561 PeiServices - The PEI core services table.
562
563 BaseAddress - The 64 bit physical address of the memory
564
565 Length - The length of the memory allocation in bytes
566
567 Name - Name for Hob
568
569 MemoryType - Memory type
570
571 Returns:
572
573 EFI_SUCCESS - Hob is successfully built.
574 Others - Errors occur while creating new Hob
575
576 --*/
577 ;
578
579 //
580 // print.c
581 //
582 UINTN
583 AvSPrint (
584 OUT CHAR8 *StartOfBuffer,
585 IN UINTN StrSize,
586 IN CONST CHAR8 *Format,
587 IN VA_LIST Marker
588 )
589 /*++
590
591 Routine Description:
592
593 AvSPrint function to process format and place the results in Buffer. Since a
594 VA_LIST is used this rountine allows the nesting of Vararg routines. Thus
595 this is the main print working routine
596
597 Arguments:
598
599 StartOfBuffer - Ascii buffer to print the results of the parsing of Format into.
600
601 StrSize - Maximum number of characters to put into buffer. Zero means
602 no limit.
603
604 FormatString - Ascii format string see file header for more details.
605
606 Marker - Vararg list consumed by processing Format.
607
608 Returns:
609
610 Number of characters printed.
611
612 --*/
613 ;
614
615 UINTN
616 ASPrint (
617 OUT CHAR8 *Buffer,
618 IN UINTN BufferSize,
619 IN CONST CHAR8 *Format,
620 ...
621 )
622 /*++
623
624 Routine Description:
625
626 ASPrint function to process format and place the results in Buffer.
627
628 Arguments:
629
630 Buffer - Ascii buffer to print the results of the parsing of Format into.
631
632 BufferSize - Maximum number of characters to put into buffer. Zero means no
633 limit.
634
635 Format - Ascii format string see file header for more details.
636
637 ... - Vararg list consumed by processing Format.
638
639 Returns:
640
641 Number of characters printed.
642
643 --*/
644 ;
645
646 //
647 // math.c
648 //
649 UINT64
650 MultU64x32 (
651 IN UINT64 Multiplicand,
652 IN UINTN Multiplier
653 )
654 /*++
655
656 Routine Description:
657
658 This routine allows a 64 bit value to be multiplied with a 32 bit
659 value returns 64bit result.
660 No checking if the result is greater than 64bits
661
662 Arguments:
663
664 Multiplicand - multiplicand
665 Multiplier - multiplier
666
667 Returns:
668
669 Multiplicand * Multiplier
670
671 --*/
672 ;
673
674 UINT64
675 DivU64x32 (
676 IN UINT64 Dividend,
677 IN UINTN Divisor,
678 OUT UINTN *Remainder OPTIONAL
679 )
680 /*++
681
682 Routine Description:
683
684 This routine allows a 64 bit value to be divided with a 32 bit value returns
685 64bit result and the Remainder.
686 N.B. only works for 31bit divisors!!
687
688 Arguments:
689
690 Dividend - dividend
691 Divisor - divisor
692 Remainder - buffer for remainder
693
694 Returns:
695
696 Dividend / Divisor
697 Remainder = Dividend mod Divisor
698
699 --*/
700 ;
701
702 UINT64
703 RShiftU64 (
704 IN UINT64 Operand,
705 IN UINTN Count
706 )
707 /*++
708
709 Routine Description:
710
711 This routine allows a 64 bit value to be right shifted by 32 bits and returns the
712 shifted value.
713 Count is valid up 63. (Only Bits 0-5 is valid for Count)
714
715 Arguments:
716
717 Operand - Value to be shifted
718 Count - Number of times to shift right.
719
720 Returns:
721
722 Value shifted right identified by the Count.
723
724 --*/
725 ;
726
727 UINT64
728 LShiftU64 (
729 IN UINT64 Operand,
730 IN UINTN Count
731 )
732 /*++
733
734 Routine Description:
735
736 This routine allows a 64 bit value to be left shifted by 32 bits and
737 returns the shifted value.
738 Count is valid up 63. (Only Bits 0-5 is valid for Count)
739
740 Arguments:
741
742 Operand - Value to be shifted
743 Count - Number of times to shift left.
744
745 Returns:
746
747 Value shifted left identified by the Count.
748
749 --*/
750 ;
751
752 VOID
753 RegisterNativeCpuIo (
754 IN EFI_PEI_SERVICES **PeiServices,
755 IN VOID *CpuIo
756 )
757 /*++
758
759 Routine Description:
760
761 Register a native Cpu IO
762
763 Arguments:
764
765 PeiServices - Calling context
766 CpuIo - CpuIo instance to register
767
768 Returns:
769
770 None
771
772 --*/
773 ;
774
775 VOID
776 GetNativeCpuIo (
777 IN EFI_PEI_SERVICES **PeiServices,
778 OUT VOID **CpuIo
779 )
780 /*++
781
782 Routine Description:
783
784 Get registered Cpu IO.
785
786 Arguments:
787
788 PeiServices - Calling context
789 CpuIo - CpuIo instance registered before
790
791 Returns:
792
793 None
794
795 --*/
796 ;
797
798 #endif