EdkCompatibilityPkg/Foundation/Library/Dxe/Include/EfiCommonLib.h

   1 /*++
   2
   3 Copyright (c) 2004 - 2007, 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     EfiCommonLib.h
  15
  16 Abstract:
  17
  18   Light weight lib to support EFI drivers.
  19
  20 --*/
  21
  22 #ifndef _EFI_COMMON_LIB_H_
  23 #define _EFI_COMMON_LIB_H_
  24
  25 EFI_STATUS
  26 EfiLibGetSystemConfigurationTable (
  27   IN EFI_GUID *TableGuid,
  28   IN OUT VOID **Table
  29   )
  30 /*++
  31
  32 Routine Description:
  33
  34   Return the EFI 1.0 System Tabl entry with TableGuid
  35
  36 Arguments:
  37
  38   TableGuid - Name of entry to return in the system table
  39   Table     - Pointer in EFI system table associated with TableGuid
  40
  41 Returns:
  42
  43   EFI_SUCCESS - Table returned;
  44   EFI_NOT_FOUND - TableGuid not in EFI system table
  45
  46 --*/
  47 ;
  48
  49 //
  50 // ASPrint and AvSPrint definitions you must include the specific library
  51 // to get the expected behavior from the two functions
  52 // PEI:  PeiLib
  53 // Graphics:  Dxe\Graphics\Unicode  Dxe\Graphics\ASCII
  54 // ASCII: Dxe\Print\ASCII
  55 // Unicode: Dxe\Print\Unicode
  56 //
  57 UINTN
  58 ASPrint (
  59   OUT CHAR8       *Buffer,
  60   IN UINTN        BufferSize,
  61   IN CONST CHAR8  *Format,
  62   ...
  63   )
  64 /*++
  65
  66 Routine Description:
  67
  68   Process format and place the results in Buffer for narrow chars.
  69
  70 Arguments:
  71
  72   Buffer      - Narrow char buffer to print the results of the parsing of Format into.
  73   BufferSize  - Maximum number of characters to put into buffer.
  74   Format      - Format string
  75   ...         - Vararg list consumed by processing Format.
  76
  77 Returns:
  78
  79   Number of characters printed.
  80
  81 --*/
  82 ;
  83
  84 UINTN
  85 AvSPrint (
  86   OUT CHAR8       *StartOfBuffer,
  87   IN  UINTN       StrSize,
  88   IN  CONST CHAR8 *Format,
  89   IN  VA_LIST     Marker
  90   )
  91 /*++
  92
  93 Routine Description:
  94
  95   Internal implementation of ASPrint.
  96   Process format and place the results in Buffer for narrow chars.
  97
  98 Arguments:
  99
 100   StartOfBuffer - Narrow char buffer to print the results of the parsing of Format into.
 101   StrSize       - Maximum number of characters to put into buffer.
 102   FormatString  - Format string
 103   Marker        - Vararg list consumed by processing Format.
 104
 105 Returns:
 106
 107   Number of characters printed.
 108
 109 --*/
 110 ;
 111
 112 //
 113 // Lib functions which can be used in both PEI and DXE pahse
 114 //
 115 EFI_STATUS
 116 EfiInitializeCommonDriverLib (
 117   IN EFI_HANDLE   ImageHandle,
 118   IN VOID         *SystemTable
 119   )
 120 /*++
 121
 122 Routine Description:
 123
 124   Initialize lib function calling phase: PEI or DXE
 125
 126 Arguments:
 127
 128   ImageHandle     - The firmware allocated handle for the EFI image.
 129
 130   SystemTable     - A pointer to the EFI System Table.
 131
 132 Returns:
 133
 134   EFI_STATUS always returns EFI_SUCCESS
 135
 136 --*/
 137 ;
 138
 139 EFI_STATUS
 140 EfiCommonIoRead (
 141   IN  UINT8       Width,
 142   IN  UINTN       Address,
 143   IN  UINTN       Count,
 144   IN  OUT VOID    *Buffer
 145   )
 146 /*++
 147
 148 Routine Description:
 149
 150   Io read operation.
 151
 152 Arguments:
 153
 154   Width   - Width of read operation
 155   Address - Start IO address to read
 156   Count   - Read count
 157   Buffer  - Buffer to store result
 158
 159 Returns:
 160
 161   Status code
 162
 163 --*/
 164 ;
 165
 166 EFI_STATUS
 167 EfiCommonIoWrite (
 168   IN  UINT8       Width,
 169   IN  UINTN       Address,
 170   IN  UINTN       Count,
 171   IN  OUT VOID    *Buffer
 172   )
 173 /*++
 174
 175 Routine Description:
 176
 177   Io write operation.
 178
 179 Arguments:
 180
 181   Width   - Width of write operation
 182   Address - Start IO address to write
 183   Count   - Write count
 184   Buffer  - Buffer to write to the address
 185
 186 Returns:
 187
 188   Status code
 189
 190 --*/
 191 ;
 192
 193 EFI_STATUS
 194 EfiCommonPciRead (
 195   IN  UINT8       Width,
 196   IN  UINT64      Address,
 197   IN  UINTN       Count,
 198   IN  OUT VOID    *Buffer
 199   )
 200 /*++
 201
 202 Routine Description:
 203
 204   Pci read operation
 205
 206 Arguments:
 207
 208   Width   - Width of PCI read
 209   Address - PCI address to read
 210   Count   - Read count
 211   Buffer  - Output buffer for the read
 212
 213 Returns:
 214
 215   Status code
 216
 217 --*/
 218 ;
 219
 220 EFI_STATUS
 221 EfiCommonPciWrite (
 222   IN  UINT8       Width,
 223   IN  UINT64      Address,
 224   IN  UINTN       Count,
 225   IN  OUT VOID    *Buffer
 226   )
 227 /*++
 228
 229 Routine Description:
 230
 231   Pci write operation
 232
 233 Arguments:
 234
 235   Width   - Width of PCI write
 236   Address - PCI address to write
 237   Count   - Write count
 238   Buffer  - Buffer to write to the address
 239
 240 Returns:
 241
 242   Status code
 243
 244 --*/
 245 ;
 246
 247 BOOLEAN
 248 EfiCompareGuid (
 249   IN EFI_GUID *Guid1,
 250   IN EFI_GUID *Guid2
 251   )
 252 /*++
 253
 254 Routine Description:
 255
 256   Compares two GUIDs
 257
 258 Arguments:
 259
 260   Guid1 - guid to compare
 261
 262   Guid2 - guid to compare
 263
 264 Returns:
 265   TRUE     if Guid1 == Guid2
 266   FALSE    if Guid1 != Guid2
 267
 268 --*/
 269 ;
 270
 271 VOID
 272 EfiCommonLibSetMem (
 273   IN VOID   *Buffer,
 274   IN UINTN  Size,
 275   IN UINT8  Value
 276   )
 277 /*++
 278
 279 Routine Description:
 280
 281   Set Buffer to Value for Size bytes.
 282
 283 Arguments:
 284
 285   Buffer  - Memory to set.
 286
 287   Size    - Number of bytes to set
 288
 289   Value   - Value of the set operation.
 290
 291 Returns:
 292
 293   None
 294
 295 --*/
 296 ;
 297
 298 VOID
 299 EfiCommonLibCopyMem (
 300   IN VOID     *Destination,
 301   IN VOID     *Source,
 302   IN UINTN    Length
 303   )
 304 /*++
 305
 306 Routine Description:
 307
 308   Copy Length bytes from Source to Destination.
 309
 310 Arguments:
 311
 312   Destination - Target of copy
 313
 314   Source      - Place to copy from
 315
 316   Length      - Number of bytes to copy
 317
 318 Returns:
 319
 320   None
 321
 322 --*/
 323 ;
 324
 325 INTN
 326 EfiCompareMem (
 327   IN VOID     *MemOne,
 328   IN VOID     *MemTwo,
 329   IN UINTN    Len
 330   )
 331 /*++
 332
 333 Routine Description:
 334
 335   Compares two memory buffers of a given length.
 336
 337 Arguments:
 338
 339   MemOne - First memory buffer
 340
 341   MemTwo - Second memory buffer
 342
 343   Len    - Length of Mem1 and Mem2 memory regions to compare
 344
 345 Returns:
 346
 347   = 0     if MemOne == MemTwo
 348
 349   > 0     if MemOne > MemTwo
 350
 351   < 0     if MemOne < MemTwo
 352
 353 --*/
 354 ;
 355
 356 VOID
 357 EfiCommonLibZeroMem (
 358   IN VOID     *Buffer,
 359   IN UINTN    Size
 360   )
 361 /*++
 362
 363 Routine Description:
 364
 365   Set Buffer to 0 for Size bytes.
 366
 367 Arguments:
 368
 369   Buffer  - Memory to set.
 370
 371   Size    - Number of bytes to set
 372
 373 Returns:
 374
 375   None
 376
 377 --*/
 378 ;
 379
 380 //
 381 // Min Max
 382 //
 383 #define EFI_MIN(a, b) (((a) < (b)) ? (a) : (b))
 384 #define EFI_MAX(a, b) (((a) > (b)) ? (a) : (b))
 385
 386 //
 387 // Align a pointer. The pointer represented by ptr is aligned to the bound.
 388 // The resulting pointer is always equal or greater (by no more than bound-1)
 389 // than the ptr. I.e., if the ptr is already aligned, the result will be equal to ptr.
 390 // Valid values for bound are powers of two: 2, 4, 8, 16, 32 etc.
 391 // The returned pointer is VOID* this assignment-compatible with all pointer types.
 392 //
 393 #define EFI_ALIGN(ptr, bound) ((VOID *) (((UINTN) (ptr) + ((UINTN) (bound) - 1)) &~((UINTN) (bound) - 1)))
 394
 395 //
 396 // Alignment tests.
 397 //
 398 #define EFI_UINTN_ALIGN_MASK    (sizeof (UINTN) - 1)
 399 #define EFI_UINTN_ALIGNED(ptr)  (((UINTN) (ptr)) & EFI_UINTN_ALIGN_MASK)
 400
 401 //
 402 // Integer division with rounding to the nearest rather than truncating.
 403 // For example 8/3=2 but EFI_IDIV_ROUND(8,3)=3. 1/3=0 and EFI_IDIV_ROUND(1,3)=0.
 404 // A half is rounded up e.g., EFI_IDIV_ROUND(1,2)=1 but 1/2=0.
 405 //
 406 #define EFI_IDIV_ROUND(r, s)  ((r) / (s) + (((2 * ((r) % (s))) < (s)) ? 0 : 1))
 407
 408 //
 409 // ReportStatusCode.c init
 410 //
 411 VOID  *
 412 EfiConstructStatusCodeData (
 413   IN  UINT16                    DataSize,
 414   IN  EFI_GUID                  *TypeGuid,
 415   IN OUT  EFI_STATUS_CODE_DATA  *Data
 416   )
 417 /*++
 418
 419 Routine Description:
 420
 421   Construct stanader header for optional data passed into ReportStatusCode
 422
 423 Arguments:
 424
 425   DataSize - Size of optional data. Does not include EFI_STATUS_CODE_DATA header
 426   TypeGuid - GUID to place in EFI_STATUS_CODE_DATA
 427   Data     - Buffer to use.
 428
 429 Returns:
 430
 431   Return pointer to Data buffer pointing past the end of EFI_STATUS_CODE_DATA
 432
 433 --*/
 434 ;
 435
 436 EFI_STATUS
 437 EfiDebugVPrintWorker (
 438   IN  UINTN                   ErrorLevel,
 439   IN  CHAR8                   *Format,
 440   IN  VA_LIST                 Marker,
 441   IN  UINTN                   BufferSize,
 442   IN OUT VOID                 *Buffer
 443   )
 444 /*++
 445
 446 Routine Description:
 447
 448   Worker function for DEBUG(). If Error Logging hub is loaded log ASSERT
 449   information. If Error Logging hub is not loaded do nothing.
 450
 451   We use UINT64 buffers due to IPF alignment concerns.
 452
 453 Arguments:
 454
 455   ErrorLevel - If error level is set do the debug print.
 456
 457   Format     - String to use for the print, followed by Print arguments.
 458
 459   Marker     - VarArgs
 460
 461   BufferSize - Size of Buffer.
 462
 463   Buffer     - Caller allocated buffer, contains ReportStatusCode extended data
 464
 465 Returns:
 466
 467   Status code
 468
 469 --*/
 470 ;
 471
 472 EFI_STATUS
 473 EfiDebugAssertWorker (
 474   IN CHAR8                    *FileName,
 475   IN INTN                     LineNumber,
 476   IN CHAR8                    *Description,
 477   IN UINTN                    BufferSize,
 478   IN OUT VOID                 *Buffer
 479   )
 480 /*++
 481
 482 Routine Description:
 483
 484   Worker function for ASSERT (). If Error Logging hub is loaded log ASSERT
 485   information. If Error Logging hub is not loaded DEADLOOP ().
 486
 487   We use UINT64 buffers due to IPF alignment concerns.
 488
 489 Arguments:
 490
 491   FileName    - File name of failing routine.
 492
 493   LineNumber  - Line number of failing ASSERT().
 494
 495   Description - Description, usually the assertion,
 496
 497   BufferSize - Size of Buffer.
 498
 499   Buffer     - Caller allocated buffer, contains ReportStatusCode extendecd data
 500
 501 Returns:
 502
 503   Status code
 504
 505 --*/
 506 ;
 507
 508 BOOLEAN
 509 ReportStatusCodeExtractAssertInfo (
 510   IN EFI_STATUS_CODE_TYPE     CodeType,
 511   IN EFI_STATUS_CODE_VALUE    Value,
 512   IN EFI_STATUS_CODE_DATA     *Data,
 513   OUT CHAR8                   **Filename,
 514   OUT CHAR8                   **Description,
 515   OUT UINT32                  *LineNumber
 516   )
 517 /*++
 518
 519 Routine Description:
 520
 521   Extract assert information from status code data.
 522
 523 Arguments:
 524
 525   CodeType    - Code type
 526   Value       - Code value
 527   Data        - Optional data associated with this status code.
 528   Filename    - Filename extracted from Data
 529   Description - Description extracted from Data
 530   LineNumber  - Line number extracted from Data
 531
 532 Returns:
 533
 534   TRUE      - Successfully extracted
 535
 536   FALSE     - Extraction failed
 537
 538 --*/
 539 ;
 540
 541 BOOLEAN
 542 ReportStatusCodeExtractDebugInfo (
 543   IN EFI_STATUS_CODE_DATA     *Data,
 544   OUT UINT32                  *ErrorLevel,
 545   OUT VA_LIST                 *Marker,
 546   OUT CHAR8                   **Format
 547   )
 548 /*++
 549
 550 Routine Description:
 551
 552   Extract debug information from status code data.
 553
 554 Arguments:
 555
 556   Data        - Optional data associated with status code.
 557   ErrorLevel  - Error level extracted from Data
 558   Marker      - VA_LIST extracted from Data
 559   Format      - Format string extracted from Data
 560
 561 Returns:
 562
 563   TRUE      - Successfully extracted
 564
 565   FALSE     - Extraction failed
 566
 567 --*/
 568 ;
 569
 570 BOOLEAN
 571 CodeTypeToPostCode (
 572   IN  EFI_STATUS_CODE_TYPE    CodeType,
 573   IN EFI_STATUS_CODE_VALUE    Value,
 574   OUT UINT8                   *PostCode
 575   )
 576 /*++
 577
 578 Routine Description:
 579
 580   Convert code value to an 8 bit post code
 581
 582 Arguments:
 583
 584   CodeType  - Code type
 585   Value     - Code value
 586   PostCode  - Post code as output
 587
 588 Returns:
 589
 590   TRUE    - Successfully converted
 591
 592   FALSE   - Convertion failed
 593
 594 --*/
 595 ;
 596
 597 //
 598 // math.c
 599 //
 600 UINT64
 601 MultU64x32 (
 602   IN  UINT64  Multiplicand,
 603   IN  UINTN   Multiplier
 604   )
 605 /*++
 606
 607 Routine Description:
 608
 609   This routine allows a 64 bit value to be multiplied with a 32 bit
 610   value returns 64bit result.
 611   No checking if the result is greater than 64bits
 612
 613 Arguments:
 614
 615   Multiplicand  - multiplicand
 616   Multiplier    - multiplier
 617
 618 Returns:
 619
 620   Multiplicand * Multiplier
 621
 622 --*/
 623 ;
 624
 625 UINT64
 626 DivU64x32 (
 627   IN  UINT64  Dividend,
 628   IN  UINTN   Divisor,
 629   OUT UINTN   *Remainder OPTIONAL
 630   )
 631 /*++
 632
 633 Routine Description:
 634
 635   This routine allows a 64 bit value to be divided with a 32 bit value returns
 636   64bit result and the Remainder.
 637
 638 Arguments:
 639
 640   Dividend  - dividend
 641   Divisor   - divisor
 642   Remainder - buffer for remainder
 643
 644 Returns:
 645
 646   Dividend  / Divisor
 647   Remainder = Dividend mod Divisor
 648
 649 --*/
 650 ;
 651
 652 UINT64
 653 RShiftU64 (
 654   IN  UINT64  Operand,
 655   IN  UINTN   Count
 656   )
 657 /*++
 658
 659 Routine Description:
 660
 661   This routine allows a 64 bit value to be right shifted by 32 bits and returns the
 662   shifted value.
 663   Count is valid up 63. (Only Bits 0-5 is valid for Count)
 664
 665 Arguments:
 666
 667   Operand - Value to be shifted
 668   Count   - Number of times to shift right.
 669
 670 Returns:
 671
 672   Value shifted right identified by the Count.
 673
 674 --*/
 675 ;
 676
 677 UINT64
 678 LShiftU64 (
 679   IN  UINT64  Operand,
 680   IN  UINTN   Count
 681   )
 682 /*++
 683
 684 Routine Description:
 685
 686   This routine allows a 64 bit value to be left shifted by 32 bits and
 687   returns the shifted value.
 688   Count is valid up 63. (Only Bits 0-5 is valid for Count)
 689
 690 Arguments:
 691
 692   Operand - Value to be shifted
 693   Count   - Number of times to shift left.
 694
 695 Returns:
 696
 697   Value shifted left identified by the Count.
 698
 699 --*/
 700 ;
 701
 702 UINT64
 703 Power10U64 (
 704   IN UINT64   Operand,
 705   IN UINTN    Power
 706   )
 707 /*++
 708
 709 Routine Description:
 710
 711   Raise 10 to the power of Power, and multiply the result with Operand
 712
 713 Arguments:
 714
 715   Operand  - multiplicand
 716   Power    - power
 717
 718 Returns:
 719
 720   Operand * 10 ^ Power
 721
 722 --*/
 723 ;
 724
 725 UINT8
 726 Log2 (
 727   IN UINT64   Operand
 728   )
 729 /*++
 730
 731 Routine Description:
 732
 733   Calculates and floors logarithms based on 2
 734
 735 Arguments:
 736
 737   Operand - value to calculate logarithm
 738
 739 Returns:
 740
 741   The largest integer that is less than or equal
 742   to the logarithm of Operand based on 2
 743
 744 --*/
 745 ;
 746
 747 UINT64
 748 GetPowerOfTwo (
 749   IN  UINT64  Input
 750   )
 751 /*++
 752
 753 Routine Description:
 754
 755   Calculates the largest integer that is both
 756   a power of two and less than Input
 757
 758 Arguments:
 759
 760   Input  - value to calculate power of two
 761
 762 Returns:
 763
 764   the largest integer that is both  a power of
 765   two and less than Input
 766
 767 --*/
 768 ;
 769
 770 //
 771 // Unicode String primatives
 772 //
 773 VOID
 774 EfiStrCpy (
 775   IN CHAR16   *Destination,
 776   IN CHAR16   *Source
 777   )
 778 /*++
 779
 780 Routine Description:
 781   Copy the Unicode string Source to Destination.
 782
 783 Arguments:
 784   Destination - Location to copy string
 785   Source      - String to copy
 786
 787 Returns:
 788   NONE
 789
 790 --*/
 791 ;
 792
 793 VOID
 794 EfiStrnCpy (
 795   OUT CHAR16    *Dst,
 796   IN  CHAR16    *Src,
 797   IN  UINTN     Length
 798   )
 799 /*++
 800
 801 Routine Description:
 802   Copy a string from source to destination
 803
 804 Arguments:
 805   Dst              Destination string
 806   Src              Source string
 807   Length           Length of destination string
 808
 809 Returns:
 810
 811 --*/
 812 ;
 813
 814 UINTN
 815 EfiStrLen (
 816   IN CHAR16   *String
 817   )
 818 /*++
 819
 820 Routine Description:
 821   Return the number of Unicode characters in String. This is not the same as
 822   the length of the string in bytes.
 823
 824 Arguments:
 825   String - String to process
 826
 827 Returns:
 828   Number of Unicode characters in String
 829
 830 --*/
 831 ;
 832
 833 UINTN
 834 EfiStrSize (
 835   IN CHAR16   *String
 836   )
 837 /*++
 838
 839 Routine Description:
 840   Return the number bytes in the Unicode String. This is not the same as
 841   the length of the string in characters. The string size includes the NULL
 842
 843 Arguments:
 844   String - String to process
 845
 846 Returns:
 847   Number of bytes in String
 848
 849 --*/
 850 ;
 851
 852 INTN
 853 EfiStrCmp (
 854   IN CHAR16   *String,
 855   IN CHAR16   *String2
 856   )
 857 /*++
 858
 859 Routine Description:
 860   Return the alphabetic relationship between two stirngs.
 861
 862 Arguments:
 863   String - Compare to String2
 864
 865   String2 - Compare to String
 866
 867 Returns:
 868   0     - Identical
 869
 870   > 0   - String is alphabeticly greater than String2
 871
 872   < 0   - String is alphabeticly less than String2
 873
 874 --*/
 875 ;
 876
 877 INTN
 878 EfiStrnCmp (
 879   IN CHAR16   *String,
 880   IN CHAR16   *String2,
 881   IN UINTN    Length
 882   )
 883 /*++
 884
 885 Routine Description:
 886   This function compares the Unicode string String to the Unicode
 887   string String2 for len characters.  If the first len characters
 888   of String is identical to the first len characters of String2,
 889   then 0 is returned.  If substring of String sorts lexicographically
 890   after String2, the function returns a number greater than 0. If
 891   substring of String sorts lexicographically before String2, the
 892   function returns a number less than 0.
 893
 894 Arguments:
 895   String  - Compare to String2
 896   String2 - Compare to String
 897   Length  - Number of Unicode characters to compare
 898
 899 Returns:
 900   0     - The substring of String and String2 is identical.
 901   > 0   - The substring of String sorts lexicographically after String2
 902   < 0   - The substring of String sorts lexicographically before String2
 903
 904 --*/
 905 ;
 906
 907 VOID
 908 EfiStrCat (
 909   IN CHAR16   *Destination,
 910   IN CHAR16   *Source
 911   )
 912 /*++
 913
 914 Routine Description:
 915   Concatinate Source on the end of Destination
 916
 917 Arguments:
 918   Destination - String to added to the end of.
 919   Source      - String to concatinate.
 920
 921 Returns:
 922   NONE
 923
 924 --*/
 925 ;
 926
 927 VOID
 928 EfiStrnCat (
 929   IN CHAR16   *Dest,
 930   IN CHAR16   *Src,
 931   IN UINTN    Length
 932   )
 933 /*++
 934
 935 Routine Description:
 936   Concatinate Source on the end of Destination
 937
 938 Arguments:
 939   Dst              Destination string
 940   Src              Source string
 941   Length           Length of destination string
 942
 943 Returns:
 944
 945 --*/
 946 ;
 947
 948 UINTN
 949 EfiAsciiStrLen (
 950   IN CHAR8   *String
 951   )
 952 /*++
 953
 954 Routine Description:
 955   Return the number of Ascii characters in String. This is not the same as
 956   the length of the string in bytes.
 957
 958 Arguments:
 959   String - String to process
 960
 961 Returns:
 962   Number of Unicode characters in String
 963
 964 --*/
 965 ;
 966
 967 CHAR8 *
 968 EfiAsciiStrCpy (
 969   IN CHAR8    *Destination,
 970   IN CHAR8    *Source
 971   )
 972 /*++
 973
 974 Routine Description:
 975   Copy the Ascii string Source to Destination.
 976
 977 Arguments:
 978   Destination - Location to copy string
 979   Source      - String to copy
 980
 981 Returns:
 982   Pointer just pass the end of Destination
 983
 984 --*/
 985 ;
 986
 987 VOID
 988 EfiAsciiStrnCpy (
 989   OUT CHAR8     *Dst,
 990   IN  CHAR8     *Src,
 991   IN  UINTN     Length
 992   )
 993 /*++
 994
 995 Routine Description:
 996   Copy the Ascii string from source to destination
 997
 998 Arguments:
 999   Dst              Destination string
1000   Src              Source string
1001   Length           Length of destination string
1002
1003 Returns:
1004
1005 --*/
1006 ;
1007
1008 UINTN
1009 EfiAsciiStrSize (
1010   IN CHAR8   *String
1011   )
1012 /*++
1013
1014 Routine Description:
1015   Return the number bytes in the Ascii String. This is not the same as
1016   the length of the string in characters. The string size includes the NULL
1017
1018 Arguments:
1019   String - String to process
1020
1021 Returns:
1022   Number of bytes in String
1023
1024 --*/
1025 ;
1026
1027
1028 INTN
1029 EfiAsciiStrCmp (
1030   IN CHAR8   *String,
1031   IN CHAR8   *String2
1032   )
1033 /*++
1034
1035 Routine Description:
1036   Compare the Ascii string pointed by String to the string pointed by String2.
1037
1038 Arguments:
1039   String - String to process
1040
1041   String2 - The other string to process
1042
1043 Returns:
1044   Return a positive integer if String is lexicall greater than String2; Zero if
1045   the two strings are identical; and a negative interger if String is lexically
1046   less than String2.
1047 --*/
1048 ;
1049
1050 INTN
1051 EfiAsciiStrnCmp (
1052   IN CHAR8    *String,
1053   IN CHAR8    *String2,
1054   IN UINTN    Length
1055   )
1056 /*++
1057
1058 Routine Description:
1059   This function compares the ASCII string String to the ASCII
1060   string String2 for len characters.  If the first len characters
1061   of String is identical to the first len characters of String2,
1062   then 0 is returned.  If substring of String sorts lexicographically
1063   after String2, the function returns a number greater than 0. If
1064   substring of String sorts lexicographically before String2, the
1065   function returns a number less than 0.
1066
1067 Arguments:
1068   String  - Compare to String2
1069   String2 - Compare to String
1070   Length  - Number of ASCII characters to compare
1071
1072 Returns:
1073   0     - The substring of String and String2 is identical.
1074   > 0   - The substring of String sorts lexicographically after String2
1075   < 0   - The substring of String sorts lexicographically before String2
1076
1077 --*/
1078 ;
1079
1080 VOID
1081 EfiAsciiStrCat (
1082   IN CHAR8   *Destination,
1083   IN CHAR8   *Source
1084   )
1085 /*++
1086
1087 Routine Description:
1088   Concatinate Source on the end of Destination
1089
1090 Arguments:
1091   Destination - String to added to the end of.
1092   Source      - String to concatinate.
1093
1094 Returns:
1095   NONE
1096
1097 --*/
1098 ;
1099
1100 VOID
1101 EfiAsciiStrnCat (
1102   IN CHAR8   *Destination,
1103   IN CHAR8   *Source,
1104   IN UINTN   Length
1105   )
1106 /*++
1107
1108 Routine Description:
1109   Concatinate Source on the end of Destination
1110
1111 Arguments:
1112   Destination - String to added to the end of.
1113   Source      - String to concatinate.
1114
1115 Returns:
1116   NONE
1117
1118 --*/
1119 ;
1120
1121 //
1122 // Print primitives
1123 //
1124 #define LEFT_JUSTIFY  0x01
1125 #define PREFIX_SIGN   0x02
1126 #define PREFIX_BLANK  0x04
1127 #define COMMA_TYPE    0x08
1128 #define LONG_TYPE     0x10
1129 #define PREFIX_ZERO   0x20
1130
1131 //
1132 // Length of temp string buffer to store value string.
1133 //
1134 #define CHARACTER_NUMBER_FOR_VALUE  30
1135
1136 UINTN
1137 EfiValueToHexStr (
1138   IN  OUT CHAR16  *Buffer,
1139   IN  UINT64      Value,
1140   IN  UINTN       Flags,
1141   IN  UINTN       Width
1142   )
1143 /*++
1144
1145 Routine Description:
1146
1147   VSPrint worker function that prints a Value as a hex number in Buffer
1148
1149 Arguments:
1150
1151   Buffer - Location to place ascii hex string of Value.
1152
1153   Value  - Hex value to convert to a string in Buffer.
1154
1155   Flags  - Flags to use in printing Hex string, see file header for details.
1156
1157   Width  - Width of hex value.
1158
1159 Returns:
1160
1161   Number of characters printed.
1162
1163 --*/
1164 ;
1165
1166 UINTN
1167 EfiValueToString (
1168   IN  OUT CHAR16  *Buffer,
1169   IN  INT64       Value,
1170   IN  UINTN       Flags,
1171   IN  UINTN       Width
1172   )
1173 /*++
1174
1175 Routine Description:
1176
1177   VSPrint worker function that prints a Value as a decimal number in Buffer
1178
1179 Arguments:
1180
1181   Buffer - Location to place ascii decimal number string of Value.
1182
1183   Value  - Decimal value to convert to a string in Buffer.
1184
1185   Flags  - Flags to use in printing decimal string, see file header for details.
1186
1187   Width  - Width of hex value.
1188
1189 Returns:
1190
1191   Number of characters printed.
1192
1193 --*/
1194 ;
1195
1196 BOOLEAN
1197 IsHexDigit (
1198   OUT UINT8       *Digit,
1199   IN  CHAR16      Char
1200   )
1201 /*++
1202
1203   Routine Description:
1204     Determines if a Unicode character is a hexadecimal digit.
1205     The test is case insensitive.
1206
1207   Arguments:
1208     Digit - Pointer to byte that receives the value of the hex character.
1209     Char  - Unicode character to test.
1210
1211   Returns:
1212     TRUE  - If the character is a hexadecimal digit.
1213     FALSE - Otherwise.
1214
1215 --*/
1216 ;
1217
1218 CHAR16
1219 NibbleToHexChar (
1220   UINT8 Nibble
1221   )
1222 /*++
1223
1224   Routine Description:
1225     Converts the low nibble of a byte  to hex unicode character.
1226
1227   Arguments:
1228     Nibble - lower nibble of a byte.
1229
1230   Returns:
1231     Hex unicode character.
1232
1233 --*/
1234 ;
1235
1236 EFI_STATUS
1237 HexStringToBuf (
1238   IN OUT UINT8                     *Buf,
1239   IN OUT UINTN                     *Len,
1240   IN     CHAR16                    *Str,
1241   OUT    UINTN                     *ConvertedStrLen OPTIONAL
1242   )
1243 /*++
1244
1245   Routine Description:
1246     Converts Unicode string to binary buffer.
1247     The conversion may be partial.
1248     The first character in the string that is not hex digit stops the conversion.
1249     At a minimum, any blob of data could be represented as a hex string.
1250
1251   Arguments:
1252     Buf    - Pointer to buffer that receives the data.
1253     Len    - Length in bytes of the buffer to hold converted data.
1254                 If routine return with EFI_SUCCESS, containing length of converted data.
1255                 If routine return with EFI_BUFFER_TOO_SMALL, containg length of buffer desired.
1256     Str    - String to be converted from.
1257     ConvertedStrLen - Length of the Hex String consumed.
1258
1259   Returns:
1260     EFI_SUCCESS: Routine Success.
1261     EFI_BUFFER_TOO_SMALL: The buffer is too small to hold converted data.
1262     EFI_
1263
1264 --*/
1265 ;
1266
1267 EFI_STATUS
1268 BufToHexString (
1269   IN OUT CHAR16                     *Str,
1270   IN OUT UINTN                      *HexStringBufferLength,
1271   IN     UINT8                      *Buf,
1272   IN     UINTN                      Len
1273   )
1274 /*++
1275
1276   Routine Description:
1277     Converts binary buffer to Unicode string.
1278     At a minimum, any blob of data could be represented as a hex string.
1279
1280   Arguments:
1281     Str - Pointer to the string.
1282     HexStringBufferLength - Length in bytes of buffer to hold the hex string. Includes tailing '\0' character.
1283                                         If routine return with EFI_SUCCESS, containing length of hex string buffer.
1284                                         If routine return with EFI_BUFFER_TOO_SMALL, containg length of hex string buffer desired.
1285     Buf - Buffer to be converted from.
1286     Len - Length in bytes of the buffer to be converted.
1287
1288   Returns:
1289     EFI_SUCCESS: Routine success.
1290     EFI_BUFFER_TOO_SMALL: The hex string buffer is too small.
1291
1292 --*/
1293 ;
1294
1295 VOID
1296 EfiStrTrim (
1297   IN OUT CHAR16   *str,
1298   IN     CHAR16   CharC
1299   )
1300 /*++
1301
1302 Routine Description:
1303
1304   Removes (trims) specified leading and trailing characters from a string.
1305
1306 Arguments:
1307
1308   str     - Pointer to the null-terminated string to be trimmed. On return,
1309             str will hold the trimmed string.
1310   CharC       - Character will be trimmed from str.
1311
1312 Returns:
1313
1314   None
1315
1316 --*/
1317 ;
1318 CHAR16*
1319 EfiStrStr (
1320   IN  CHAR16  *String,
1321   IN  CHAR16  *StrCharSet
1322   )
1323 /*++
1324
1325 Routine Description:
1326
1327   Find a substring.
1328
1329 Arguments:
1330
1331   String      - Null-terminated string to search.
1332   StrCharSet  - Null-terminated string to search for.
1333
1334 Returns:
1335   The address of the first occurrence of the matching substring if successful, or NULL otherwise.
1336 --*/
1337 ;
1338
1339 CHAR8*
1340 EfiAsciiStrStr (
1341   IN  CHAR8  *String,
1342   IN  CHAR8  *StrCharSet
1343   )
1344 /*++
1345
1346 Routine Description:
1347
1348   Find a Ascii substring.
1349
1350 Arguments:
1351
1352   String      - Null-terminated Ascii string to search.
1353   StrCharSet  - Null-terminated Ascii string to search for.
1354
1355 Returns:
1356   The address of the first occurrence of the matching Ascii substring if successful, or NULL otherwise.
1357 --*/
1358 ;
1359 #endif