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 //
 263 // hob.c
 264 //
 265 EFI_STATUS
 266 PeiBuildHobModule (
 267   IN EFI_PEI_SERVICES            **PeiServices,
 268   IN EFI_GUID                    *ModuleName,
 269   IN EFI_PHYSICAL_ADDRESS        Module,
 270   IN UINT64                      ModuleLength,
 271   IN EFI_PHYSICAL_ADDRESS        EntryPoint
 272   )
 273 /*++
 274
 275 Routine Description:
 276
 277   Builds a HOB for a loaded PE32 module
 278
 279 Arguments:
 280
 281   PeiServices               - The PEI core services table.
 282   ModuleName                - The GUID File Name of the module
 283   Memory                    - The 64 bit physical address of the module
 284   ModuleLength              - The length of the module in bytes
 285   EntryPoint                - The 64 bit physical address of the entry point
 286                               to the module
 287
 288 Returns:
 289
 290   EFI_SUCCESS               - Hob is successfully built.
 291   Others                    - Errors occur while creating new Hob
 292
 293 --*/
 294 ;
 295
 296 EFI_STATUS
 297 PeiBuildHobResourceDescriptor (
 298   IN EFI_PEI_SERVICES            **PeiServices,
 299   IN EFI_RESOURCE_TYPE           ResourceType,
 300   IN EFI_RESOURCE_ATTRIBUTE_TYPE ResourceAttribute,
 301   IN EFI_PHYSICAL_ADDRESS        PhysicalStart,
 302   IN UINT64                      NumberOfBytes
 303   )
 304 /*++
 305
 306 Routine Description:
 307
 308   Builds a HOB that describes a chunck of system memory
 309
 310 Arguments:
 311
 312   PeiServices        - The PEI core services table.
 313
 314   ResourceType       - The type of resource described by this HOB
 315
 316   ResourceAttribute  - The resource attributes of the memory described by this HOB
 317
 318   PhysicalStart      - The 64 bit physical address of memory described by this HOB
 319
 320   NumberOfBytes      - The length of the memoty described by this HOB in bytes
 321
 322 Returns:
 323
 324   EFI_SUCCESS     - Hob is successfully built.
 325   Others          - Errors occur while creating new Hob
 326
 327 --*/
 328 ;
 329
 330 EFI_STATUS
 331 PeiBuildHobGuid (
 332   IN EFI_PEI_SERVICES            **PeiServices,
 333   IN EFI_GUID                    *Guid,
 334   IN UINTN                       DataLength,
 335   IN OUT VOID                    **Hob
 336   )
 337 /*++
 338
 339 Routine Description:
 340
 341   Builds a custom HOB that is tagged with a GUID for identification
 342
 343 Arguments:
 344
 345   PeiServices - The PEI core services table.
 346
 347   Guid        - The GUID of the custome HOB type
 348
 349   DataLength  - The size of the data payload for the GUIDed HOB
 350
 351   Hob         - Pointer to the Hob
 352
 353 Returns:
 354
 355   EFI_SUCCESS   - Hob is successfully built.
 356   Others        - Errors occur while creating new Hob
 357
 358 --*/
 359 ;
 360
 361 EFI_STATUS
 362 PeiBuildHobGuidData (
 363   IN EFI_PEI_SERVICES            **PeiServices,
 364   IN EFI_GUID                    *Guid,
 365   IN VOID                        *Data,
 366   IN UINTN                       DataLength
 367   )
 368 /*++
 369
 370 Routine Description:
 371
 372   Builds a custom HOB that is tagged with a GUID for identification
 373
 374 Arguments:
 375
 376   PeiServices - The PEI core services table.
 377
 378   Guid        - The GUID of the custome HOB type
 379
 380   Data        - The data to be copied into the GUIDed HOB data field.
 381
 382   DataLength  - The data field length.
 383
 384 Returns:
 385
 386   EFI_SUCCESS   - Hob is successfully built.
 387   Others        - Errors occur while creating new Hob
 388
 389 --*/
 390 ;
 391
 392 EFI_STATUS
 393 PeiBuildHobFv (
 394   IN EFI_PEI_SERVICES            **PeiServices,
 395   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 396   IN UINT64                      Length
 397   )
 398 /*++
 399
 400 Routine Description:
 401
 402   Builds a Firmware Volume HOB
 403
 404 Arguments:
 405
 406   PeiServices - The PEI core services table.
 407
 408   BaseAddress - The base address of the Firmware Volume
 409
 410   Length      - The size of the Firmware Volume in bytes
 411
 412 Returns:
 413
 414   EFI_SUCCESS   - Hob is successfully built.
 415   Others        - Errors occur while creating new Hob
 416
 417 --*/
 418 ;
 419
 420 EFI_STATUS
 421 PeiBuildHobCpu (
 422   IN EFI_PEI_SERVICES            **PeiServices,
 423   IN UINT8                       SizeOfMemorySpace,
 424   IN UINT8                       SizeOfIoSpace
 425   )
 426 /*++
 427
 428 Routine Description:
 429
 430   Builds a HOB for the CPU
 431
 432 Arguments:
 433
 434   PeiServices               - The PEI core services table.
 435
 436   SizeOfMemorySpace         - Identifies the maximum
 437                               physical memory addressibility of the processor.
 438
 439   SizeOfIoSpace             - Identifies the maximum physical I/O addressibility
 440                               of the processor.
 441
 442 Returns:
 443
 444   EFI_SUCCESS               - Hob is successfully built.
 445   Others                    - Errors occur while creating new Hob
 446
 447 --*/
 448 ;
 449
 450 EFI_STATUS
 451 PeiBuildHobStack (
 452   IN EFI_PEI_SERVICES            **PeiServices,
 453   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 454   IN UINT64                      Length
 455   )
 456 /*++
 457
 458 Routine Description:
 459
 460   Builds a HOB for the Stack
 461
 462 Arguments:
 463
 464   PeiServices               - The PEI core services table.
 465
 466   BaseAddress               - The 64 bit physical address of the Stack
 467
 468   Length                    - The length of the stack in bytes
 469
 470 Returns:
 471
 472   EFI_SUCCESS               - Hob is successfully built.
 473   Others                    - Errors occur while creating new Hob
 474
 475 --*/
 476 ;
 477
 478 EFI_STATUS
 479 PeiBuildHobBspStore (
 480   IN EFI_PEI_SERVICES            **PeiServices,
 481   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 482   IN UINT64                      Length,
 483   IN EFI_MEMORY_TYPE             MemoryType
 484   )
 485 /*++
 486
 487 Routine Description:
 488
 489   Builds a HOB for the bsp store
 490
 491 Arguments:
 492
 493   PeiServices               - The PEI core services table.
 494
 495   BaseAddress               - The 64 bit physical address of the bsp store
 496
 497   Length                    - The length of the bsp store in bytes
 498
 499   MemoryType                - Memory type
 500
 501 Returns:
 502
 503   EFI_SUCCESS               - Hob is successfully built.
 504   Others                    - Errors occur while creating new Hob
 505
 506 --*/
 507 ;
 508
 509 EFI_STATUS
 510 PeiBuildHobMemoryAllocation (
 511   IN EFI_PEI_SERVICES            **PeiServices,
 512   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 513   IN UINT64                      Length,
 514   IN EFI_GUID                    *Name,
 515   IN EFI_MEMORY_TYPE             MemoryType
 516   )
 517 /*++
 518
 519 Routine Description:
 520
 521   Builds a HOB for the memory allocation
 522
 523 Arguments:
 524
 525   PeiServices               - The PEI core services table.
 526
 527   BaseAddress               - The 64 bit physical address of the memory
 528
 529   Length                    - The length of the memory allocation in bytes
 530
 531   Name                      - Name for Hob
 532
 533   MemoryType                - Memory type
 534
 535 Returns:
 536
 537   EFI_SUCCESS               - Hob is successfully built.
 538   Others                    - Errors occur while creating new Hob
 539
 540 --*/
 541 ;
 542
 543 //
 544 // print.c
 545 //
 546 UINTN
 547 AvSPrint (
 548   OUT CHAR8       *StartOfBuffer,
 549   IN  UINTN       StrSize,
 550   IN  CONST CHAR8 *Format,
 551   IN  VA_LIST     Marker
 552   )
 553 /*++
 554
 555 Routine Description:
 556
 557   AvSPrint function to process format and place the results in Buffer. Since a
 558   VA_LIST is used this rountine allows the nesting of Vararg routines. Thus
 559   this is the main print working routine
 560
 561 Arguments:
 562
 563   StartOfBuffer - Ascii buffer to print the results of the parsing of Format into.
 564
 565   StrSize       - Maximum number of characters to put into buffer. Zero means
 566                   no limit.
 567
 568   FormatString  - Ascii format string see file header for more details.
 569
 570   Marker        - Vararg list consumed by processing Format.
 571
 572 Returns:
 573
 574   Number of characters printed.
 575
 576 --*/
 577 ;
 578
 579 UINTN
 580 ASPrint (
 581   OUT CHAR8       *Buffer,
 582   IN UINTN        BufferSize,
 583   IN CONST CHAR8  *Format,
 584   ...
 585   )
 586 /*++
 587
 588 Routine Description:
 589
 590   ASPrint function to process format and place the results in Buffer.
 591
 592 Arguments:
 593
 594   Buffer     - Ascii buffer to print the results of the parsing of Format into.
 595
 596   BufferSize - Maximum number of characters to put into buffer. Zero means no
 597                limit.
 598
 599   Format - Ascii format string see file header for more details.
 600
 601   ...    - Vararg list consumed by processing Format.
 602
 603 Returns:
 604
 605   Number of characters printed.
 606
 607 --*/
 608 ;
 609
 610 //
 611 // math.c
 612 //
 613 UINT64
 614 MultU64x32 (
 615   IN  UINT64  Multiplicand,
 616   IN  UINTN   Multiplier
 617   )
 618 /*++
 619
 620 Routine Description:
 621
 622   This routine allows a 64 bit value to be multiplied with a 32 bit
 623   value returns 64bit result.
 624   No checking if the result is greater than 64bits
 625
 626 Arguments:
 627
 628   Multiplicand  - multiplicand
 629   Multiplier    - multiplier
 630
 631 Returns:
 632
 633   Multiplicand * Multiplier
 634
 635 --*/
 636 ;
 637
 638 UINT64
 639 DivU64x32 (
 640   IN  UINT64  Dividend,
 641   IN  UINTN   Divisor,
 642   OUT UINTN   *Remainder OPTIONAL
 643   )
 644 /*++
 645
 646 Routine Description:
 647
 648   This routine allows a 64 bit value to be divided with a 32 bit value returns
 649   64bit result and the Remainder.
 650   N.B. only works for 31bit divisors!!
 651
 652 Arguments:
 653
 654   Dividend  - dividend
 655   Divisor   - divisor
 656   Remainder - buffer for remainder
 657
 658 Returns:
 659
 660   Dividend  / Divisor
 661   Remainder = Dividend mod Divisor
 662
 663 --*/
 664 ;
 665
 666 UINT64
 667 RShiftU64 (
 668   IN  UINT64  Operand,
 669   IN  UINTN   Count
 670   )
 671 /*++
 672
 673 Routine Description:
 674
 675   This routine allows a 64 bit value to be right shifted by 32 bits and returns the
 676   shifted value.
 677   Count is valid up 63. (Only Bits 0-5 is valid for Count)
 678
 679 Arguments:
 680
 681   Operand - Value to be shifted
 682   Count   - Number of times to shift right.
 683
 684 Returns:
 685
 686   Value shifted right identified by the Count.
 687
 688 --*/
 689 ;
 690
 691 UINT64
 692 LShiftU64 (
 693   IN  UINT64  Operand,
 694   IN  UINTN   Count
 695   )
 696 /*++
 697
 698 Routine Description:
 699
 700   This routine allows a 64 bit value to be left shifted by 32 bits and
 701   returns the shifted value.
 702   Count is valid up 63. (Only Bits 0-5 is valid for Count)
 703
 704 Arguments:
 705
 706   Operand - Value to be shifted
 707   Count   - Number of times to shift left.
 708
 709 Returns:
 710
 711   Value shifted left identified by the Count.
 712
 713 --*/
 714 ;
 715
 716 VOID
 717 RegisterNativeCpuIo (
 718   IN EFI_PEI_SERVICES         **PeiServices,
 719   IN VOID                     *CpuIo
 720   )
 721 /*++
 722
 723 Routine Description:
 724
 725   Register a native Cpu IO
 726
 727 Arguments:
 728
 729   PeiServices - Calling context
 730   CpuIo       - CpuIo instance to register
 731
 732 Returns:
 733
 734   None
 735
 736 --*/
 737 ;
 738
 739 VOID
 740 GetNativeCpuIo (
 741   IN EFI_PEI_SERVICES         **PeiServices,
 742   OUT VOID                    **CpuIo
 743   )
 744 /*++
 745
 746 Routine Description:
 747
 748   Get registered Cpu IO.
 749
 750 Arguments:
 751
 752   PeiServices - Calling context
 753   CpuIo       - CpuIo instance registered before
 754
 755 Returns:
 756
 757   None
 758
 759 --*/
 760 ;
 761
 762 #endif