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