MdePkg/Include/Library/BaseLib.h

   1 /** @file
   2   Provides string functions, linked list functions, math functions, synchronization
   3   functions, file path functions, and CPU architecture-specific functions.
   4
   5 Copyright (c) 2006 - 2021, Intel Corporation. All rights reserved.<BR>
   6 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
   7 Copyright (c) Microsoft Corporation.<BR>
   8 Portions Copyright (c) 2020, Hewlett Packard Enterprise Development LP. All rights reserved.<BR>
   9 Portions Copyright (c) 2022, Loongson Technology Corporation Limited. All rights reserved.<BR>
  10
  11 SPDX-License-Identifier: BSD-2-Clause-Patent
  12
  13 **/
  14
  15 #ifndef __BASE_LIB__
  16 #define __BASE_LIB__
  17
  18 //
  19 // Definitions for architecture-specific types
  20 //
  21 #if   defined (MDE_CPU_IA32)
  22 ///
  23 /// The IA-32 architecture context buffer used by SetJump() and LongJump().
  24 ///
  25 typedef struct {
  26   UINT32    Ebx;
  27   UINT32    Esi;
  28   UINT32    Edi;
  29   UINT32    Ebp;
  30   UINT32    Esp;
  31   UINT32    Eip;
  32   UINT32    Ssp;
  33 } BASE_LIBRARY_JUMP_BUFFER;
  34
  35 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT  4
  36
  37 #endif // defined (MDE_CPU_IA32)
  38
  39 #if defined (MDE_CPU_X64)
  40 ///
  41 /// The x64 architecture context buffer used by SetJump() and LongJump().
  42 ///
  43 typedef struct {
  44   UINT64    Rbx;
  45   UINT64    Rsp;
  46   UINT64    Rbp;
  47   UINT64    Rdi;
  48   UINT64    Rsi;
  49   UINT64    R12;
  50   UINT64    R13;
  51   UINT64    R14;
  52   UINT64    R15;
  53   UINT64    Rip;
  54   UINT64    MxCsr;
  55   UINT8     XmmBuffer[160];                         ///< XMM6-XMM15.
  56   UINT64    Ssp;
  57 } BASE_LIBRARY_JUMP_BUFFER;
  58
  59 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT  8
  60
  61 #endif // defined (MDE_CPU_X64)
  62
  63 #if defined (MDE_CPU_EBC)
  64 ///
  65 /// The EBC context buffer used by SetJump() and LongJump().
  66 ///
  67 typedef struct {
  68   UINT64    R0;
  69   UINT64    R1;
  70   UINT64    R2;
  71   UINT64    R3;
  72   UINT64    IP;
  73 } BASE_LIBRARY_JUMP_BUFFER;
  74
  75 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT  8
  76
  77 #endif // defined (MDE_CPU_EBC)
  78
  79 #if defined (MDE_CPU_ARM)
  80
  81 typedef struct {
  82   UINT32    R3;  ///< A copy of R13.
  83   UINT32    R4;
  84   UINT32    R5;
  85   UINT32    R6;
  86   UINT32    R7;
  87   UINT32    R8;
  88   UINT32    R9;
  89   UINT32    R10;
  90   UINT32    R11;
  91   UINT32    R12;
  92   UINT32    R14;
  93 } BASE_LIBRARY_JUMP_BUFFER;
  94
  95 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT  4
  96
  97 #endif // defined (MDE_CPU_ARM)
  98
  99 #if defined (MDE_CPU_AARCH64)
 100 typedef struct {
 101   // GP regs
 102   UINT64    X19;
 103   UINT64    X20;
 104   UINT64    X21;
 105   UINT64    X22;
 106   UINT64    X23;
 107   UINT64    X24;
 108   UINT64    X25;
 109   UINT64    X26;
 110   UINT64    X27;
 111   UINT64    X28;
 112   UINT64    FP;
 113   UINT64    LR;
 114   UINT64    IP0;
 115
 116   // FP regs
 117   UINT64    D8;
 118   UINT64    D9;
 119   UINT64    D10;
 120   UINT64    D11;
 121   UINT64    D12;
 122   UINT64    D13;
 123   UINT64    D14;
 124   UINT64    D15;
 125 } BASE_LIBRARY_JUMP_BUFFER;
 126
 127 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT  8
 128
 129 #endif // defined (MDE_CPU_AARCH64)
 130
 131 #if defined (MDE_CPU_RISCV64)
 132 ///
 133 /// The RISC-V architecture context buffer used by SetJump() and LongJump().
 134 ///
 135 typedef struct {
 136   UINT64    RA;
 137   UINT64    S0;
 138   UINT64    S1;
 139   UINT64    S2;
 140   UINT64    S3;
 141   UINT64    S4;
 142   UINT64    S5;
 143   UINT64    S6;
 144   UINT64    S7;
 145   UINT64    S8;
 146   UINT64    S9;
 147   UINT64    S10;
 148   UINT64    S11;
 149   UINT64    SP;
 150 } BASE_LIBRARY_JUMP_BUFFER;
 151
 152 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT  8
 153
 154 #endif // defined (MDE_CPU_RISCV64)
 155
 156 #if defined (MDE_CPU_LOONGARCH64)
 157 ///
 158 /// The LoongArch architecture context buffer used by SetJump() and LongJump()
 159 ///
 160 typedef struct {
 161   UINT64    S0;
 162   UINT64    S1;
 163   UINT64    S2;
 164   UINT64    S3;
 165   UINT64    S4;
 166   UINT64    S5;
 167   UINT64    S6;
 168   UINT64    S7;
 169   UINT64    S8;
 170   UINT64    SP;
 171   UINT64    FP;
 172   UINT64    RA;
 173 } BASE_LIBRARY_JUMP_BUFFER;
 174
 175 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT  8
 176
 177 #endif // defined (MDE_CPU_LOONGARCH64)
 178
 179 //
 180 // String Services
 181 //
 182
 183 /**
 184   Returns the length of a Null-terminated Unicode string.
 185
 186   This function is similar as strlen_s defined in C11.
 187
 188   If String is not aligned on a 16-bit boundary, then ASSERT().
 189
 190   @param  String   A pointer to a Null-terminated Unicode string.
 191   @param  MaxSize  The maximum number of Destination Unicode
 192                    char, including terminating null char.
 193
 194   @retval 0        If String is NULL.
 195   @retval MaxSize  If there is no null character in the first MaxSize characters of String.
 196   @return The number of characters that percede the terminating null character.
 197
 198 **/
 199 UINTN
 200 EFIAPI
 201 StrnLenS (
 202   IN CONST CHAR16  *String,
 203   IN UINTN         MaxSize
 204   );
 205
 206 /**
 207   Returns the size of a Null-terminated Unicode string in bytes, including the
 208   Null terminator.
 209
 210   This function returns the size of the Null-terminated Unicode string
 211   specified by String in bytes, including the Null terminator.
 212
 213   If String is not aligned on a 16-bit boundary, then ASSERT().
 214
 215   @param  String   A pointer to a Null-terminated Unicode string.
 216   @param  MaxSize  The maximum number of Destination Unicode
 217                    char, including the Null terminator.
 218
 219   @retval 0  If String is NULL.
 220   @retval (sizeof (CHAR16) * (MaxSize + 1))
 221              If there is no Null terminator in the first MaxSize characters of
 222              String.
 223   @return The size of the Null-terminated Unicode string in bytes, including
 224           the Null terminator.
 225
 226 **/
 227 UINTN
 228 EFIAPI
 229 StrnSizeS (
 230   IN CONST CHAR16  *String,
 231   IN UINTN         MaxSize
 232   );
 233
 234 /**
 235   Copies the string pointed to by Source (including the terminating null char)
 236   to the array pointed to by Destination.
 237
 238   This function is similar as strcpy_s defined in C11.
 239
 240   If Destination is not aligned on a 16-bit boundary, then ASSERT().
 241   If Source is not aligned on a 16-bit boundary, then ASSERT().
 242
 243   If an error is returned, then the Destination is unmodified.
 244
 245   @param  Destination              A pointer to a Null-terminated Unicode string.
 246   @param  DestMax                  The maximum number of Destination Unicode
 247                                    char, including terminating null char.
 248   @param  Source                   A pointer to a Null-terminated Unicode string.
 249
 250   @retval RETURN_SUCCESS           String is copied.
 251   @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than StrLen(Source).
 252   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
 253                                    If Source is NULL.
 254                                    If PcdMaximumUnicodeStringLength is not zero,
 255                                     and DestMax is greater than
 256                                     PcdMaximumUnicodeStringLength.
 257                                    If DestMax is 0.
 258   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
 259 **/
 260 RETURN_STATUS
 261 EFIAPI
 262 StrCpyS (
 263   OUT CHAR16        *Destination,
 264   IN  UINTN         DestMax,
 265   IN  CONST CHAR16  *Source
 266   );
 267
 268 /**
 269   Copies not more than Length successive char from the string pointed to by
 270   Source to the array pointed to by Destination. If no null char is copied from
 271   Source, then Destination[Length] is always set to null.
 272
 273   This function is similar as strncpy_s defined in C11.
 274
 275   If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
 276   If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
 277
 278   If an error is returned, then the Destination is unmodified.
 279
 280   @param  Destination              A pointer to a Null-terminated Unicode string.
 281   @param  DestMax                  The maximum number of Destination Unicode
 282                                    char, including terminating null char.
 283   @param  Source                   A pointer to a Null-terminated Unicode string.
 284   @param  Length                   The maximum number of Unicode characters to copy.
 285
 286   @retval RETURN_SUCCESS           String is copied.
 287   @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than
 288                                    MIN(StrLen(Source), Length).
 289   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
 290                                    If Source is NULL.
 291                                    If PcdMaximumUnicodeStringLength is not zero,
 292                                     and DestMax is greater than
 293                                     PcdMaximumUnicodeStringLength.
 294                                    If DestMax is 0.
 295   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
 296 **/
 297 RETURN_STATUS
 298 EFIAPI
 299 StrnCpyS (
 300   OUT CHAR16        *Destination,
 301   IN  UINTN         DestMax,
 302   IN  CONST CHAR16  *Source,
 303   IN  UINTN         Length
 304   );
 305
 306 /**
 307   Appends a copy of the string pointed to by Source (including the terminating
 308   null char) to the end of the string pointed to by Destination.
 309
 310   This function is similar as strcat_s defined in C11.
 311
 312   If Destination is not aligned on a 16-bit boundary, then ASSERT().
 313   If Source is not aligned on a 16-bit boundary, then ASSERT().
 314
 315   If an error is returned, then the Destination is unmodified.
 316
 317   @param  Destination              A pointer to a Null-terminated Unicode string.
 318   @param  DestMax                  The maximum number of Destination Unicode
 319                                    char, including terminating null char.
 320   @param  Source                   A pointer to a Null-terminated Unicode string.
 321
 322   @retval RETURN_SUCCESS           String is appended.
 323   @retval RETURN_BAD_BUFFER_SIZE   If DestMax is NOT greater than
 324                                    StrLen(Destination).
 325   @retval RETURN_BUFFER_TOO_SMALL  If (DestMax - StrLen(Destination)) is NOT
 326                                    greater than StrLen(Source).
 327   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
 328                                    If Source is NULL.
 329                                    If PcdMaximumUnicodeStringLength is not zero,
 330                                     and DestMax is greater than
 331                                     PcdMaximumUnicodeStringLength.
 332                                    If DestMax is 0.
 333   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
 334 **/
 335 RETURN_STATUS
 336 EFIAPI
 337 StrCatS (
 338   IN OUT CHAR16        *Destination,
 339   IN     UINTN         DestMax,
 340   IN     CONST CHAR16  *Source
 341   );
 342
 343 /**
 344   Appends not more than Length successive char from the string pointed to by
 345   Source to the end of the string pointed to by Destination. If no null char is
 346   copied from Source, then Destination[StrLen(Destination) + Length] is always
 347   set to null.
 348
 349   This function is similar as strncat_s defined in C11.
 350
 351   If Destination is not aligned on a 16-bit boundary, then ASSERT().
 352   If Source is not aligned on a 16-bit boundary, then ASSERT().
 353
 354   If an error is returned, then the Destination is unmodified.
 355
 356   @param  Destination              A pointer to a Null-terminated Unicode string.
 357   @param  DestMax                  The maximum number of Destination Unicode
 358                                    char, including terminating null char.
 359   @param  Source                   A pointer to a Null-terminated Unicode string.
 360   @param  Length                   The maximum number of Unicode characters to copy.
 361
 362   @retval RETURN_SUCCESS           String is appended.
 363   @retval RETURN_BAD_BUFFER_SIZE   If DestMax is NOT greater than
 364                                    StrLen(Destination).
 365   @retval RETURN_BUFFER_TOO_SMALL  If (DestMax - StrLen(Destination)) is NOT
 366                                    greater than MIN(StrLen(Source), Length).
 367   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
 368                                    If Source is NULL.
 369                                    If PcdMaximumUnicodeStringLength is not zero,
 370                                     and DestMax is greater than
 371                                     PcdMaximumUnicodeStringLength.
 372                                    If DestMax is 0.
 373   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
 374 **/
 375 RETURN_STATUS
 376 EFIAPI
 377 StrnCatS (
 378   IN OUT CHAR16        *Destination,
 379   IN     UINTN         DestMax,
 380   IN     CONST CHAR16  *Source,
 381   IN     UINTN         Length
 382   );
 383
 384 /**
 385   Convert a Null-terminated Unicode decimal string to a value of type UINTN.
 386
 387   This function outputs a value of type UINTN by interpreting the contents of
 388   the Unicode string specified by String as a decimal number. The format of the
 389   input Unicode string String is:
 390
 391                   [spaces] [decimal digits].
 392
 393   The valid decimal digit character is in the range [0-9]. The function will
 394   ignore the pad space, which includes spaces or tab characters, before
 395   [decimal digits]. The running zero in the beginning of [decimal digits] will
 396   be ignored. Then, the function stops at the first character that is a not a
 397   valid decimal character or a Null-terminator, whichever one comes first.
 398
 399   If String is not aligned in a 16-bit boundary, then ASSERT().
 400
 401   If String has no valid decimal digits in the above format, then 0 is stored
 402   at the location pointed to by Data.
 403   If the number represented by String exceeds the range defined by UINTN, then
 404   MAX_UINTN is stored at the location pointed to by Data.
 405
 406   If EndPointer is not NULL, a pointer to the character that stopped the scan
 407   is stored at the location pointed to by EndPointer. If String has no valid
 408   decimal digits right after the optional pad spaces, the value of String is
 409   stored at the location pointed to by EndPointer.
 410
 411   @param  String                   Pointer to a Null-terminated Unicode string.
 412   @param  EndPointer               Pointer to character that stops scan.
 413   @param  Data                     Pointer to the converted value.
 414
 415   @retval RETURN_SUCCESS           Value is translated from String.
 416   @retval RETURN_INVALID_PARAMETER If String is NULL.
 417                                    If Data is NULL.
 418                                    If PcdMaximumUnicodeStringLength is not
 419                                    zero, and String contains more than
 420                                    PcdMaximumUnicodeStringLength Unicode
 421                                    characters, not including the
 422                                    Null-terminator.
 423   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
 424                                    the range defined by UINTN.
 425
 426 **/
 427 RETURN_STATUS
 428 EFIAPI
 429 StrDecimalToUintnS (
 430   IN  CONST CHAR16  *String,
 431   OUT       CHAR16  **EndPointer   OPTIONAL,
 432   OUT       UINTN   *Data
 433   );
 434
 435 /**
 436   Convert a Null-terminated Unicode decimal string to a value of type UINT64.
 437
 438   This function outputs a value of type UINT64 by interpreting the contents of
 439   the Unicode string specified by String as a decimal number. The format of the
 440   input Unicode string String is:
 441
 442                   [spaces] [decimal digits].
 443
 444   The valid decimal digit character is in the range [0-9]. The function will
 445   ignore the pad space, which includes spaces or tab characters, before
 446   [decimal digits]. The running zero in the beginning of [decimal digits] will
 447   be ignored. Then, the function stops at the first character that is a not a
 448   valid decimal character or a Null-terminator, whichever one comes first.
 449
 450   If String is not aligned in a 16-bit boundary, then ASSERT().
 451
 452   If String has no valid decimal digits in the above format, then 0 is stored
 453   at the location pointed to by Data.
 454   If the number represented by String exceeds the range defined by UINT64, then
 455   MAX_UINT64 is stored at the location pointed to by Data.
 456
 457   If EndPointer is not NULL, a pointer to the character that stopped the scan
 458   is stored at the location pointed to by EndPointer. If String has no valid
 459   decimal digits right after the optional pad spaces, the value of String is
 460   stored at the location pointed to by EndPointer.
 461
 462   @param  String                   Pointer to a Null-terminated Unicode string.
 463   @param  EndPointer               Pointer to character that stops scan.
 464   @param  Data                     Pointer to the converted value.
 465
 466   @retval RETURN_SUCCESS           Value is translated from String.
 467   @retval RETURN_INVALID_PARAMETER If String is NULL.
 468                                    If Data is NULL.
 469                                    If PcdMaximumUnicodeStringLength is not
 470                                    zero, and String contains more than
 471                                    PcdMaximumUnicodeStringLength Unicode
 472                                    characters, not including the
 473                                    Null-terminator.
 474   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
 475                                    the range defined by UINT64.
 476
 477 **/
 478 RETURN_STATUS
 479 EFIAPI
 480 StrDecimalToUint64S (
 481   IN  CONST CHAR16  *String,
 482   OUT       CHAR16  **EndPointer   OPTIONAL,
 483   OUT       UINT64  *Data
 484   );
 485
 486 /**
 487   Convert a Null-terminated Unicode hexadecimal string to a value of type
 488   UINTN.
 489
 490   This function outputs a value of type UINTN by interpreting the contents of
 491   the Unicode string specified by String as a hexadecimal number. The format of
 492   the input Unicode string String is:
 493
 494                   [spaces][zeros][x][hexadecimal digits].
 495
 496   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
 497   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
 498   If "x" appears in the input string, it must be prefixed with at least one 0.
 499   The function will ignore the pad space, which includes spaces or tab
 500   characters, before [zeros], [x] or [hexadecimal digit]. The running zero
 501   before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
 502   after [x] or the first valid hexadecimal digit. Then, the function stops at
 503   the first character that is a not a valid hexadecimal character or NULL,
 504   whichever one comes first.
 505
 506   If String is not aligned in a 16-bit boundary, then ASSERT().
 507
 508   If String has no valid hexadecimal digits in the above format, then 0 is
 509   stored at the location pointed to by Data.
 510   If the number represented by String exceeds the range defined by UINTN, then
 511   MAX_UINTN is stored at the location pointed to by Data.
 512
 513   If EndPointer is not NULL, a pointer to the character that stopped the scan
 514   is stored at the location pointed to by EndPointer. If String has no valid
 515   hexadecimal digits right after the optional pad spaces, the value of String
 516   is stored at the location pointed to by EndPointer.
 517
 518   @param  String                   Pointer to a Null-terminated Unicode string.
 519   @param  EndPointer               Pointer to character that stops scan.
 520   @param  Data                     Pointer to the converted value.
 521
 522   @retval RETURN_SUCCESS           Value is translated from String.
 523   @retval RETURN_INVALID_PARAMETER If String is NULL.
 524                                    If Data is NULL.
 525                                    If PcdMaximumUnicodeStringLength is not
 526                                    zero, and String contains more than
 527                                    PcdMaximumUnicodeStringLength Unicode
 528                                    characters, not including the
 529                                    Null-terminator.
 530   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
 531                                    the range defined by UINTN.
 532
 533 **/
 534 RETURN_STATUS
 535 EFIAPI
 536 StrHexToUintnS (
 537   IN  CONST CHAR16  *String,
 538   OUT       CHAR16  **EndPointer   OPTIONAL,
 539   OUT       UINTN   *Data
 540   );
 541
 542 /**
 543   Convert a Null-terminated Unicode hexadecimal string to a value of type
 544   UINT64.
 545
 546   This function outputs a value of type UINT64 by interpreting the contents of
 547   the Unicode string specified by String as a hexadecimal number. The format of
 548   the input Unicode string String is:
 549
 550                   [spaces][zeros][x][hexadecimal digits].
 551
 552   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
 553   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
 554   If "x" appears in the input string, it must be prefixed with at least one 0.
 555   The function will ignore the pad space, which includes spaces or tab
 556   characters, before [zeros], [x] or [hexadecimal digit]. The running zero
 557   before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
 558   after [x] or the first valid hexadecimal digit. Then, the function stops at
 559   the first character that is a not a valid hexadecimal character or NULL,
 560   whichever one comes first.
 561
 562   If String is not aligned in a 16-bit boundary, then ASSERT().
 563
 564   If String has no valid hexadecimal digits in the above format, then 0 is
 565   stored at the location pointed to by Data.
 566   If the number represented by String exceeds the range defined by UINT64, then
 567   MAX_UINT64 is stored at the location pointed to by Data.
 568
 569   If EndPointer is not NULL, a pointer to the character that stopped the scan
 570   is stored at the location pointed to by EndPointer. If String has no valid
 571   hexadecimal digits right after the optional pad spaces, the value of String
 572   is stored at the location pointed to by EndPointer.
 573
 574   @param  String                   Pointer to a Null-terminated Unicode string.
 575   @param  EndPointer               Pointer to character that stops scan.
 576   @param  Data                     Pointer to the converted value.
 577
 578   @retval RETURN_SUCCESS           Value is translated from String.
 579   @retval RETURN_INVALID_PARAMETER If String is NULL.
 580                                    If Data is NULL.
 581                                    If PcdMaximumUnicodeStringLength is not
 582                                    zero, and String contains more than
 583                                    PcdMaximumUnicodeStringLength Unicode
 584                                    characters, not including the
 585                                    Null-terminator.
 586   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
 587                                    the range defined by UINT64.
 588
 589 **/
 590 RETURN_STATUS
 591 EFIAPI
 592 StrHexToUint64S (
 593   IN  CONST CHAR16  *String,
 594   OUT       CHAR16  **EndPointer   OPTIONAL,
 595   OUT       UINT64  *Data
 596   );
 597
 598 /**
 599   Returns the length of a Null-terminated Ascii string.
 600
 601   This function is similar as strlen_s defined in C11.
 602
 603   @param  String   A pointer to a Null-terminated Ascii string.
 604   @param  MaxSize  The maximum number of Destination Ascii
 605                    char, including terminating null char.
 606
 607   @retval 0        If String is NULL.
 608   @retval MaxSize  If there is no null character in the first MaxSize characters of String.
 609   @return The number of characters that percede the terminating null character.
 610
 611 **/
 612 UINTN
 613 EFIAPI
 614 AsciiStrnLenS (
 615   IN CONST CHAR8  *String,
 616   IN UINTN        MaxSize
 617   );
 618
 619 /**
 620   Returns the size of a Null-terminated Ascii string in bytes, including the
 621   Null terminator.
 622
 623   This function returns the size of the Null-terminated Ascii string specified
 624   by String in bytes, including the Null terminator.
 625
 626   @param  String   A pointer to a Null-terminated Ascii string.
 627   @param  MaxSize  The maximum number of Destination Ascii
 628                    char, including the Null terminator.
 629
 630   @retval 0  If String is NULL.
 631   @retval (sizeof (CHAR8) * (MaxSize + 1))
 632              If there is no Null terminator in the first MaxSize characters of
 633              String.
 634   @return The size of the Null-terminated Ascii string in bytes, including the
 635           Null terminator.
 636
 637 **/
 638 UINTN
 639 EFIAPI
 640 AsciiStrnSizeS (
 641   IN CONST CHAR8  *String,
 642   IN UINTN        MaxSize
 643   );
 644
 645 /**
 646   Copies the string pointed to by Source (including the terminating null char)
 647   to the array pointed to by Destination.
 648
 649   This function is similar as strcpy_s defined in C11.
 650
 651   If an error is returned, then the Destination is unmodified.
 652
 653   @param  Destination              A pointer to a Null-terminated Ascii string.
 654   @param  DestMax                  The maximum number of Destination Ascii
 655                                    char, including terminating null char.
 656   @param  Source                   A pointer to a Null-terminated Ascii string.
 657
 658   @retval RETURN_SUCCESS           String is copied.
 659   @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than StrLen(Source).
 660   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
 661                                    If Source is NULL.
 662                                    If PcdMaximumAsciiStringLength is not zero,
 663                                     and DestMax is greater than
 664                                     PcdMaximumAsciiStringLength.
 665                                    If DestMax is 0.
 666   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
 667 **/
 668 RETURN_STATUS
 669 EFIAPI
 670 AsciiStrCpyS (
 671   OUT CHAR8        *Destination,
 672   IN  UINTN        DestMax,
 673   IN  CONST CHAR8  *Source
 674   );
 675
 676 /**
 677   Copies not more than Length successive char from the string pointed to by
 678   Source to the array pointed to by Destination. If no null char is copied from
 679   Source, then Destination[Length] is always set to null.
 680
 681   This function is similar as strncpy_s defined in C11.
 682
 683   If an error is returned, then the Destination is unmodified.
 684
 685   @param  Destination              A pointer to a Null-terminated Ascii string.
 686   @param  DestMax                  The maximum number of Destination Ascii
 687                                    char, including terminating null char.
 688   @param  Source                   A pointer to a Null-terminated Ascii string.
 689   @param  Length                   The maximum number of Ascii characters to copy.
 690
 691   @retval RETURN_SUCCESS           String is copied.
 692   @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than
 693                                    MIN(StrLen(Source), Length).
 694   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
 695                                    If Source is NULL.
 696                                    If PcdMaximumAsciiStringLength is not zero,
 697                                     and DestMax is greater than
 698                                     PcdMaximumAsciiStringLength.
 699                                    If DestMax is 0.
 700   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
 701 **/
 702 RETURN_STATUS
 703 EFIAPI
 704 AsciiStrnCpyS (
 705   OUT CHAR8        *Destination,
 706   IN  UINTN        DestMax,
 707   IN  CONST CHAR8  *Source,
 708   IN  UINTN        Length
 709   );
 710
 711 /**
 712   Appends a copy of the string pointed to by Source (including the terminating
 713   null char) to the end of the string pointed to by Destination.
 714
 715   This function is similar as strcat_s defined in C11.
 716
 717   If an error is returned, then the Destination is unmodified.
 718
 719   @param  Destination              A pointer to a Null-terminated Ascii string.
 720   @param  DestMax                  The maximum number of Destination Ascii
 721                                    char, including terminating null char.
 722   @param  Source                   A pointer to a Null-terminated Ascii string.
 723
 724   @retval RETURN_SUCCESS           String is appended.
 725   @retval RETURN_BAD_BUFFER_SIZE   If DestMax is NOT greater than
 726                                    StrLen(Destination).
 727   @retval RETURN_BUFFER_TOO_SMALL  If (DestMax - StrLen(Destination)) is NOT
 728                                    greater than StrLen(Source).
 729   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
 730                                    If Source is NULL.
 731                                    If PcdMaximumAsciiStringLength is not zero,
 732                                     and DestMax is greater than
 733                                     PcdMaximumAsciiStringLength.
 734                                    If DestMax is 0.
 735   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
 736 **/
 737 RETURN_STATUS
 738 EFIAPI
 739 AsciiStrCatS (
 740   IN OUT CHAR8        *Destination,
 741   IN     UINTN        DestMax,
 742   IN     CONST CHAR8  *Source
 743   );
 744
 745 /**
 746   Appends not more than Length successive char from the string pointed to by
 747   Source to the end of the string pointed to by Destination. If no null char is
 748   copied from Source, then Destination[StrLen(Destination) + Length] is always
 749   set to null.
 750
 751   This function is similar as strncat_s defined in C11.
 752
 753   If an error is returned, then the Destination is unmodified.
 754
 755   @param  Destination              A pointer to a Null-terminated Ascii string.
 756   @param  DestMax                  The maximum number of Destination Ascii
 757                                    char, including terminating null char.
 758   @param  Source                   A pointer to a Null-terminated Ascii string.
 759   @param  Length                   The maximum number of Ascii characters to copy.
 760
 761   @retval RETURN_SUCCESS           String is appended.
 762   @retval RETURN_BAD_BUFFER_SIZE   If DestMax is NOT greater than
 763                                    StrLen(Destination).
 764   @retval RETURN_BUFFER_TOO_SMALL  If (DestMax - StrLen(Destination)) is NOT
 765                                    greater than MIN(StrLen(Source), Length).
 766   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
 767                                    If Source is NULL.
 768                                    If PcdMaximumAsciiStringLength is not zero,
 769                                     and DestMax is greater than
 770                                     PcdMaximumAsciiStringLength.
 771                                    If DestMax is 0.
 772   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
 773 **/
 774 RETURN_STATUS
 775 EFIAPI
 776 AsciiStrnCatS (
 777   IN OUT CHAR8        *Destination,
 778   IN     UINTN        DestMax,
 779   IN     CONST CHAR8  *Source,
 780   IN     UINTN        Length
 781   );
 782
 783 /**
 784   Convert a Null-terminated Ascii decimal string to a value of type UINTN.
 785
 786   This function outputs a value of type UINTN by interpreting the contents of
 787   the Ascii string specified by String as a decimal number. The format of the
 788   input Ascii string String is:
 789
 790                   [spaces] [decimal digits].
 791
 792   The valid decimal digit character is in the range [0-9]. The function will
 793   ignore the pad space, which includes spaces or tab characters, before
 794   [decimal digits]. The running zero in the beginning of [decimal digits] will
 795   be ignored. Then, the function stops at the first character that is a not a
 796   valid decimal character or a Null-terminator, whichever one comes first.
 797
 798   If String has no valid decimal digits in the above format, then 0 is stored
 799   at the location pointed to by Data.
 800   If the number represented by String exceeds the range defined by UINTN, then
 801   MAX_UINTN is stored at the location pointed to by Data.
 802
 803   If EndPointer is not NULL, a pointer to the character that stopped the scan
 804   is stored at the location pointed to by EndPointer. If String has no valid
 805   decimal digits right after the optional pad spaces, the value of String is
 806   stored at the location pointed to by EndPointer.
 807
 808   @param  String                   Pointer to a Null-terminated Ascii string.
 809   @param  EndPointer               Pointer to character that stops scan.
 810   @param  Data                     Pointer to the converted value.
 811
 812   @retval RETURN_SUCCESS           Value is translated from String.
 813   @retval RETURN_INVALID_PARAMETER If String is NULL.
 814                                    If Data is NULL.
 815                                    If PcdMaximumAsciiStringLength is not zero,
 816                                    and String contains more than
 817                                    PcdMaximumAsciiStringLength Ascii
 818                                    characters, not including the
 819                                    Null-terminator.
 820   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
 821                                    the range defined by UINTN.
 822
 823 **/
 824 RETURN_STATUS
 825 EFIAPI
 826 AsciiStrDecimalToUintnS (
 827   IN  CONST CHAR8  *String,
 828   OUT       CHAR8  **EndPointer   OPTIONAL,
 829   OUT       UINTN  *Data
 830   );
 831
 832 /**
 833   Convert a Null-terminated Ascii decimal string to a value of type UINT64.
 834
 835   This function outputs a value of type UINT64 by interpreting the contents of
 836   the Ascii string specified by String as a decimal number. The format of the
 837   input Ascii string String is:
 838
 839                   [spaces] [decimal digits].
 840
 841   The valid decimal digit character is in the range [0-9]. The function will
 842   ignore the pad space, which includes spaces or tab characters, before
 843   [decimal digits]. The running zero in the beginning of [decimal digits] will
 844   be ignored. Then, the function stops at the first character that is a not a
 845   valid decimal character or a Null-terminator, whichever one comes first.
 846
 847   If String has no valid decimal digits in the above format, then 0 is stored
 848   at the location pointed to by Data.
 849   If the number represented by String exceeds the range defined by UINT64, then
 850   MAX_UINT64 is stored at the location pointed to by Data.
 851
 852   If EndPointer is not NULL, a pointer to the character that stopped the scan
 853   is stored at the location pointed to by EndPointer. If String has no valid
 854   decimal digits right after the optional pad spaces, the value of String is
 855   stored at the location pointed to by EndPointer.
 856
 857   @param  String                   Pointer to a Null-terminated Ascii string.
 858   @param  EndPointer               Pointer to character that stops scan.
 859   @param  Data                     Pointer to the converted value.
 860
 861   @retval RETURN_SUCCESS           Value is translated from String.
 862   @retval RETURN_INVALID_PARAMETER If String is NULL.
 863                                    If Data is NULL.
 864                                    If PcdMaximumAsciiStringLength is not zero,
 865                                    and String contains more than
 866                                    PcdMaximumAsciiStringLength Ascii
 867                                    characters, not including the
 868                                    Null-terminator.
 869   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
 870                                    the range defined by UINT64.
 871
 872 **/
 873 RETURN_STATUS
 874 EFIAPI
 875 AsciiStrDecimalToUint64S (
 876   IN  CONST CHAR8   *String,
 877   OUT       CHAR8   **EndPointer   OPTIONAL,
 878   OUT       UINT64  *Data
 879   );
 880
 881 /**
 882   Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
 883
 884   This function outputs a value of type UINTN by interpreting the contents of
 885   the Ascii string specified by String as a hexadecimal number. The format of
 886   the input Ascii string String is:
 887
 888                   [spaces][zeros][x][hexadecimal digits].
 889
 890   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
 891   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
 892   "x" appears in the input string, it must be prefixed with at least one 0. The
 893   function will ignore the pad space, which includes spaces or tab characters,
 894   before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
 895   [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
 896   the first valid hexadecimal digit. Then, the function stops at the first
 897   character that is a not a valid hexadecimal character or Null-terminator,
 898   whichever on comes first.
 899
 900   If String has no valid hexadecimal digits in the above format, then 0 is
 901   stored at the location pointed to by Data.
 902   If the number represented by String exceeds the range defined by UINTN, then
 903   MAX_UINTN is stored at the location pointed to by Data.
 904
 905   If EndPointer is not NULL, a pointer to the character that stopped the scan
 906   is stored at the location pointed to by EndPointer. If String has no valid
 907   hexadecimal digits right after the optional pad spaces, the value of String
 908   is stored at the location pointed to by EndPointer.
 909
 910   @param  String                   Pointer to a Null-terminated Ascii string.
 911   @param  EndPointer               Pointer to character that stops scan.
 912   @param  Data                     Pointer to the converted value.
 913
 914   @retval RETURN_SUCCESS           Value is translated from String.
 915   @retval RETURN_INVALID_PARAMETER If String is NULL.
 916                                    If Data is NULL.
 917                                    If PcdMaximumAsciiStringLength is not zero,
 918                                    and String contains more than
 919                                    PcdMaximumAsciiStringLength Ascii
 920                                    characters, not including the
 921                                    Null-terminator.
 922   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
 923                                    the range defined by UINTN.
 924
 925 **/
 926 RETURN_STATUS
 927 EFIAPI
 928 AsciiStrHexToUintnS (
 929   IN  CONST CHAR8  *String,
 930   OUT       CHAR8  **EndPointer   OPTIONAL,
 931   OUT       UINTN  *Data
 932   );
 933
 934 /**
 935   Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
 936
 937   This function outputs a value of type UINT64 by interpreting the contents of
 938   the Ascii string specified by String as a hexadecimal number. The format of
 939   the input Ascii string String is:
 940
 941                   [spaces][zeros][x][hexadecimal digits].
 942
 943   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
 944   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
 945   "x" appears in the input string, it must be prefixed with at least one 0. The
 946   function will ignore the pad space, which includes spaces or tab characters,
 947   before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
 948   [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
 949   the first valid hexadecimal digit. Then, the function stops at the first
 950   character that is a not a valid hexadecimal character or Null-terminator,
 951   whichever on comes first.
 952
 953   If String has no valid hexadecimal digits in the above format, then 0 is
 954   stored at the location pointed to by Data.
 955   If the number represented by String exceeds the range defined by UINT64, then
 956   MAX_UINT64 is stored at the location pointed to by Data.
 957
 958   If EndPointer is not NULL, a pointer to the character that stopped the scan
 959   is stored at the location pointed to by EndPointer. If String has no valid
 960   hexadecimal digits right after the optional pad spaces, the value of String
 961   is stored at the location pointed to by EndPointer.
 962
 963   @param  String                   Pointer to a Null-terminated Ascii string.
 964   @param  EndPointer               Pointer to character that stops scan.
 965   @param  Data                     Pointer to the converted value.
 966
 967   @retval RETURN_SUCCESS           Value is translated from String.
 968   @retval RETURN_INVALID_PARAMETER If String is NULL.
 969                                    If Data is NULL.
 970                                    If PcdMaximumAsciiStringLength is not zero,
 971                                    and String contains more than
 972                                    PcdMaximumAsciiStringLength Ascii
 973                                    characters, not including the
 974                                    Null-terminator.
 975   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
 976                                    the range defined by UINT64.
 977
 978 **/
 979 RETURN_STATUS
 980 EFIAPI
 981 AsciiStrHexToUint64S (
 982   IN  CONST CHAR8   *String,
 983   OUT       CHAR8   **EndPointer   OPTIONAL,
 984   OUT       UINT64  *Data
 985   );
 986
 987 /**
 988   Returns the length of a Null-terminated Unicode string.
 989
 990   This function returns the number of Unicode characters in the Null-terminated
 991   Unicode string specified by String.
 992
 993   If String is NULL, then ASSERT().
 994   If String is not aligned on a 16-bit boundary, then ASSERT().
 995   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
 996   PcdMaximumUnicodeStringLength Unicode characters not including the
 997   Null-terminator, then ASSERT().
 998
 999   @param  String  Pointer to a Null-terminated Unicode string.
1000
1001   @return The length of String.
1002
1003 **/
1004 UINTN
1005 EFIAPI
1006 StrLen (
1007   IN      CONST CHAR16  *String
1008   );
1009
1010 /**
1011   Returns the size of a Null-terminated Unicode string in bytes, including the
1012   Null terminator.
1013
1014   This function returns the size, in bytes, of the Null-terminated Unicode string
1015   specified by String.
1016
1017   If String is NULL, then ASSERT().
1018   If String is not aligned on a 16-bit boundary, then ASSERT().
1019   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1020   PcdMaximumUnicodeStringLength Unicode characters not including the
1021   Null-terminator, then ASSERT().
1022
1023   @param  String  The pointer to a Null-terminated Unicode string.
1024
1025   @return The size of String.
1026
1027 **/
1028 UINTN
1029 EFIAPI
1030 StrSize (
1031   IN      CONST CHAR16  *String
1032   );
1033
1034 /**
1035   Compares two Null-terminated Unicode strings, and returns the difference
1036   between the first mismatched Unicode characters.
1037
1038   This function compares the Null-terminated Unicode string FirstString to the
1039   Null-terminated Unicode string SecondString. If FirstString is identical to
1040   SecondString, then 0 is returned. Otherwise, the value returned is the first
1041   mismatched Unicode character in SecondString subtracted from the first
1042   mismatched Unicode character in FirstString.
1043
1044   If FirstString is NULL, then ASSERT().
1045   If FirstString is not aligned on a 16-bit boundary, then ASSERT().
1046   If SecondString is NULL, then ASSERT().
1047   If SecondString is not aligned on a 16-bit boundary, then ASSERT().
1048   If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
1049   than PcdMaximumUnicodeStringLength Unicode characters not including the
1050   Null-terminator, then ASSERT().
1051   If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
1052   than PcdMaximumUnicodeStringLength Unicode characters, not including the
1053   Null-terminator, then ASSERT().
1054
1055   @param  FirstString   The pointer to a Null-terminated Unicode string.
1056   @param  SecondString  The pointer to a Null-terminated Unicode string.
1057
1058   @retval 0      FirstString is identical to SecondString.
1059   @return others FirstString is not identical to SecondString.
1060
1061 **/
1062 INTN
1063 EFIAPI
1064 StrCmp (
1065   IN      CONST CHAR16  *FirstString,
1066   IN      CONST CHAR16  *SecondString
1067   );
1068
1069 /**
1070   Compares up to a specified length the contents of two Null-terminated Unicode strings,
1071   and returns the difference between the first mismatched Unicode characters.
1072
1073   This function compares the Null-terminated Unicode string FirstString to the
1074   Null-terminated Unicode string SecondString. At most, Length Unicode
1075   characters will be compared. If Length is 0, then 0 is returned. If
1076   FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1077   value returned is the first mismatched Unicode character in SecondString
1078   subtracted from the first mismatched Unicode character in FirstString.
1079
1080   If Length > 0 and FirstString is NULL, then ASSERT().
1081   If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
1082   If Length > 0 and SecondString is NULL, then ASSERT().
1083   If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
1084   If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1085   PcdMaximumUnicodeStringLength, then ASSERT().
1086   If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
1087   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1088   then ASSERT().
1089   If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
1090   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1091   then ASSERT().
1092
1093   @param  FirstString   The pointer to a Null-terminated Unicode string.
1094   @param  SecondString  The pointer to a Null-terminated Unicode string.
1095   @param  Length        The maximum number of Unicode characters to compare.
1096
1097   @retval 0      FirstString is identical to SecondString.
1098   @return others FirstString is not identical to SecondString.
1099
1100 **/
1101 INTN
1102 EFIAPI
1103 StrnCmp (
1104   IN      CONST CHAR16  *FirstString,
1105   IN      CONST CHAR16  *SecondString,
1106   IN      UINTN         Length
1107   );
1108
1109 /**
1110   Returns the first occurrence of a Null-terminated Unicode sub-string
1111   in a Null-terminated Unicode string.
1112
1113   This function scans the contents of the Null-terminated Unicode string
1114   specified by String and returns the first occurrence of SearchString.
1115   If SearchString is not found in String, then NULL is returned.  If
1116   the length of SearchString is zero, then String is returned.
1117
1118   If String is NULL, then ASSERT().
1119   If String is not aligned on a 16-bit boundary, then ASSERT().
1120   If SearchString is NULL, then ASSERT().
1121   If SearchString is not aligned on a 16-bit boundary, then ASSERT().
1122
1123   If PcdMaximumUnicodeStringLength is not zero, and SearchString
1124   or String contains more than PcdMaximumUnicodeStringLength Unicode
1125   characters, not including the Null-terminator, then ASSERT().
1126
1127   @param  String          The pointer to a Null-terminated Unicode string.
1128   @param  SearchString    The pointer to a Null-terminated Unicode string to search for.
1129
1130   @retval NULL            If the SearchString does not appear in String.
1131   @return others          If there is a match.
1132
1133 **/
1134 CHAR16 *
1135 EFIAPI
1136 StrStr (
1137   IN      CONST CHAR16  *String,
1138   IN      CONST CHAR16  *SearchString
1139   );
1140
1141 /**
1142   Convert a Null-terminated Unicode decimal string to a value of
1143   type UINTN.
1144
1145   This function returns a value of type UINTN by interpreting the contents
1146   of the Unicode string specified by String as a decimal number. The format
1147   of the input Unicode string String is:
1148
1149                   [spaces] [decimal digits].
1150
1151   The valid decimal digit character is in the range [0-9]. The
1152   function will ignore the pad space, which includes spaces or
1153   tab characters, before [decimal digits]. The running zero in the
1154   beginning of [decimal digits] will be ignored. Then, the function
1155   stops at the first character that is a not a valid decimal character
1156   or a Null-terminator, whichever one comes first.
1157
1158   If String is NULL, then ASSERT().
1159   If String is not aligned in a 16-bit boundary, then ASSERT().
1160   If String has only pad spaces, then 0 is returned.
1161   If String has no pad spaces or valid decimal digits,
1162   then 0 is returned.
1163   If the number represented by String overflows according
1164   to the range defined by UINTN, then MAX_UINTN is returned.
1165
1166   If PcdMaximumUnicodeStringLength is not zero, and String contains
1167   more than PcdMaximumUnicodeStringLength Unicode characters not including
1168   the Null-terminator, then ASSERT().
1169
1170   @param  String      The pointer to a Null-terminated Unicode string.
1171
1172   @retval Value translated from String.
1173
1174 **/
1175 UINTN
1176 EFIAPI
1177 StrDecimalToUintn (
1178   IN      CONST CHAR16  *String
1179   );
1180
1181 /**
1182   Convert a Null-terminated Unicode decimal string to a value of
1183   type UINT64.
1184
1185   This function returns a value of type UINT64 by interpreting the contents
1186   of the Unicode string specified by String as a decimal number. The format
1187   of the input Unicode string String is:
1188
1189                   [spaces] [decimal digits].
1190
1191   The valid decimal digit character is in the range [0-9]. The
1192   function will ignore the pad space, which includes spaces or
1193   tab characters, before [decimal digits]. The running zero in the
1194   beginning of [decimal digits] will be ignored. Then, the function
1195   stops at the first character that is a not a valid decimal character
1196   or a Null-terminator, whichever one comes first.
1197
1198   If String is NULL, then ASSERT().
1199   If String is not aligned in a 16-bit boundary, then ASSERT().
1200   If String has only pad spaces, then 0 is returned.
1201   If String has no pad spaces or valid decimal digits,
1202   then 0 is returned.
1203   If the number represented by String overflows according
1204   to the range defined by UINT64, then MAX_UINT64 is returned.
1205
1206   If PcdMaximumUnicodeStringLength is not zero, and String contains
1207   more than PcdMaximumUnicodeStringLength Unicode characters not including
1208   the Null-terminator, then ASSERT().
1209
1210   @param  String          The pointer to a Null-terminated Unicode string.
1211
1212   @retval Value translated from String.
1213
1214 **/
1215 UINT64
1216 EFIAPI
1217 StrDecimalToUint64 (
1218   IN      CONST CHAR16  *String
1219   );
1220
1221 /**
1222   Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
1223
1224   This function returns a value of type UINTN by interpreting the contents
1225   of the Unicode string specified by String as a hexadecimal number.
1226   The format of the input Unicode string String is:
1227
1228                   [spaces][zeros][x][hexadecimal digits].
1229
1230   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1231   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1232   If "x" appears in the input string, it must be prefixed with at least one 0.
1233   The function will ignore the pad space, which includes spaces or tab characters,
1234   before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1235   [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1236   first valid hexadecimal digit. Then, the function stops at the first character
1237   that is a not a valid hexadecimal character or NULL, whichever one comes first.
1238
1239   If String is NULL, then ASSERT().
1240   If String is not aligned in a 16-bit boundary, then ASSERT().
1241   If String has only pad spaces, then zero is returned.
1242   If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1243   then zero is returned.
1244   If the number represented by String overflows according to the range defined by
1245   UINTN, then MAX_UINTN is returned.
1246
1247   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1248   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1249   then ASSERT().
1250
1251   @param  String          The pointer to a Null-terminated Unicode string.
1252
1253   @retval Value translated from String.
1254
1255 **/
1256 UINTN
1257 EFIAPI
1258 StrHexToUintn (
1259   IN      CONST CHAR16  *String
1260   );
1261
1262 /**
1263   Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
1264
1265   This function returns a value of type UINT64 by interpreting the contents
1266   of the Unicode string specified by String as a hexadecimal number.
1267   The format of the input Unicode string String is
1268
1269                   [spaces][zeros][x][hexadecimal digits].
1270
1271   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1272   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1273   If "x" appears in the input string, it must be prefixed with at least one 0.
1274   The function will ignore the pad space, which includes spaces or tab characters,
1275   before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1276   [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1277   first valid hexadecimal digit. Then, the function stops at the first character that is
1278   a not a valid hexadecimal character or NULL, whichever one comes first.
1279
1280   If String is NULL, then ASSERT().
1281   If String is not aligned in a 16-bit boundary, then ASSERT().
1282   If String has only pad spaces, then zero is returned.
1283   If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1284   then zero is returned.
1285   If the number represented by String overflows according to the range defined by
1286   UINT64, then MAX_UINT64 is returned.
1287
1288   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1289   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1290   then ASSERT().
1291
1292   @param  String          The pointer to a Null-terminated Unicode string.
1293
1294   @retval Value translated from String.
1295
1296 **/
1297 UINT64
1298 EFIAPI
1299 StrHexToUint64 (
1300   IN      CONST CHAR16  *String
1301   );
1302
1303 /**
1304   Convert a Null-terminated Unicode string to IPv6 address and prefix length.
1305
1306   This function outputs a value of type IPv6_ADDRESS and may output a value
1307   of type UINT8 by interpreting the contents of the Unicode string specified
1308   by String. The format of the input Unicode string String is as follows:
1309
1310                   X:X:X:X:X:X:X:X[/P]
1311
1312   X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1313   [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1314   memory address and high byte is stored in high memory address. P contains decimal
1315   digit characters in the range [0-9]. The running zero in the beginning of P will
1316   be ignored. /P is optional.
1317
1318   When /P is not in the String, the function stops at the first character that is
1319   not a valid hexadecimal digit character after eight X's are converted.
1320
1321   When /P is in the String, the function stops at the first character that is not
1322   a valid decimal digit character after P is converted.
1323
1324   "::" can be used to compress one or more groups of X when X contains only 0.
1325   The "::" can only appear once in the String.
1326
1327   If String is not aligned in a 16-bit boundary, then ASSERT().
1328
1329   If EndPointer is not NULL and Address is translated from String, a pointer
1330   to the character that stopped the scan is stored at the location pointed to
1331   by EndPointer.
1332
1333   @param  String                   Pointer to a Null-terminated Unicode string.
1334   @param  EndPointer               Pointer to character that stops scan.
1335   @param  Address                  Pointer to the converted IPv6 address.
1336   @param  PrefixLength             Pointer to the converted IPv6 address prefix
1337                                    length. MAX_UINT8 is returned when /P is
1338                                    not in the String.
1339
1340   @retval RETURN_SUCCESS           Address is translated from String.
1341   @retval RETURN_INVALID_PARAMETER If String is NULL.
1342                                    If Data is NULL.
1343   @retval RETURN_UNSUPPORTED       If X contains more than four hexadecimal
1344                                     digit characters.
1345                                    If String contains "::" and number of X
1346                                     is not less than 8.
1347                                    If P starts with character that is not a
1348                                     valid decimal digit character.
1349                                    If the decimal number converted from P
1350                                     exceeds 128.
1351
1352 **/
1353 RETURN_STATUS
1354 EFIAPI
1355 StrToIpv6Address (
1356   IN  CONST CHAR16  *String,
1357   OUT CHAR16        **EndPointer  OPTIONAL,
1358   OUT IPv6_ADDRESS  *Address,
1359   OUT UINT8         *PrefixLength OPTIONAL
1360   );
1361
1362 /**
1363   Convert a Null-terminated Unicode string to IPv4 address and prefix length.
1364
1365   This function outputs a value of type IPv4_ADDRESS and may output a value
1366   of type UINT8 by interpreting the contents of the Unicode string specified
1367   by String. The format of the input Unicode string String is as follows:
1368
1369                   D.D.D.D[/P]
1370
1371   D and P are decimal digit characters in the range [0-9]. The running zero in
1372   the beginning of D and P will be ignored. /P is optional.
1373
1374   When /P is not in the String, the function stops at the first character that is
1375   not a valid decimal digit character after four D's are converted.
1376
1377   When /P is in the String, the function stops at the first character that is not
1378   a valid decimal digit character after P is converted.
1379
1380   If String is not aligned in a 16-bit boundary, then ASSERT().
1381
1382   If EndPointer is not NULL and Address is translated from String, a pointer
1383   to the character that stopped the scan is stored at the location pointed to
1384   by EndPointer.
1385
1386   @param  String                   Pointer to a Null-terminated Unicode string.
1387   @param  EndPointer               Pointer to character that stops scan.
1388   @param  Address                  Pointer to the converted IPv4 address.
1389   @param  PrefixLength             Pointer to the converted IPv4 address prefix
1390                                    length. MAX_UINT8 is returned when /P is
1391                                    not in the String.
1392
1393   @retval RETURN_SUCCESS           Address is translated from String.
1394   @retval RETURN_INVALID_PARAMETER If String is NULL.
1395                                    If Data is NULL.
1396   @retval RETURN_UNSUPPORTED       If String is not in the correct format.
1397                                    If any decimal number converted from D
1398                                     exceeds 255.
1399                                    If the decimal number converted from P
1400                                     exceeds 32.
1401
1402 **/
1403 RETURN_STATUS
1404 EFIAPI
1405 StrToIpv4Address (
1406   IN  CONST CHAR16  *String,
1407   OUT CHAR16        **EndPointer  OPTIONAL,
1408   OUT IPv4_ADDRESS  *Address,
1409   OUT UINT8         *PrefixLength OPTIONAL
1410   );
1411
1412 #define GUID_STRING_LENGTH  36
1413
1414 /**
1415   Convert a Null-terminated Unicode GUID string to a value of type
1416   EFI_GUID.
1417
1418   This function outputs a GUID value by interpreting the contents of
1419   the Unicode string specified by String. The format of the input
1420   Unicode string String consists of 36 characters, as follows:
1421
1422                   aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
1423
1424   The pairs aa - pp are two characters in the range [0-9], [a-f] and
1425   [A-F], with each pair representing a single byte hexadecimal value.
1426
1427   The mapping between String and the EFI_GUID structure is as follows:
1428                   aa          Data1[24:31]
1429                   bb          Data1[16:23]
1430                   cc          Data1[8:15]
1431                   dd          Data1[0:7]
1432                   ee          Data2[8:15]
1433                   ff          Data2[0:7]
1434                   gg          Data3[8:15]
1435                   hh          Data3[0:7]
1436                   ii          Data4[0:7]
1437                   jj          Data4[8:15]
1438                   kk          Data4[16:23]
1439                   ll          Data4[24:31]
1440                   mm          Data4[32:39]
1441                   nn          Data4[40:47]
1442                   oo          Data4[48:55]
1443                   pp          Data4[56:63]
1444
1445   If String is not aligned in a 16-bit boundary, then ASSERT().
1446
1447   @param  String                   Pointer to a Null-terminated Unicode string.
1448   @param  Guid                     Pointer to the converted GUID.
1449
1450   @retval RETURN_SUCCESS           Guid is translated from String.
1451   @retval RETURN_INVALID_PARAMETER If String is NULL.
1452                                    If Data is NULL.
1453   @retval RETURN_UNSUPPORTED       If String is not as the above format.
1454
1455 **/
1456 RETURN_STATUS
1457 EFIAPI
1458 StrToGuid (
1459   IN  CONST CHAR16  *String,
1460   OUT GUID          *Guid
1461   );
1462
1463 /**
1464   Convert a Null-terminated Unicode hexadecimal string to a byte array.
1465
1466   This function outputs a byte array by interpreting the contents of
1467   the Unicode string specified by String in hexadecimal format. The format of
1468   the input Unicode string String is:
1469
1470                   [XX]*
1471
1472   X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
1473   The function decodes every two hexadecimal digit characters as one byte. The
1474   decoding stops after Length of characters and outputs Buffer containing
1475   (Length / 2) bytes.
1476
1477   If String is not aligned in a 16-bit boundary, then ASSERT().
1478
1479   @param  String                   Pointer to a Null-terminated Unicode string.
1480   @param  Length                   The number of Unicode characters to decode.
1481   @param  Buffer                   Pointer to the converted bytes array.
1482   @param  MaxBufferSize            The maximum size of Buffer.
1483
1484   @retval RETURN_SUCCESS           Buffer is translated from String.
1485   @retval RETURN_INVALID_PARAMETER If String is NULL.
1486                                    If Data is NULL.
1487                                    If Length is not multiple of 2.
1488                                    If PcdMaximumUnicodeStringLength is not zero,
1489                                     and Length is greater than
1490                                     PcdMaximumUnicodeStringLength.
1491   @retval RETURN_UNSUPPORTED       If Length of characters from String contain
1492                                     a character that is not valid hexadecimal
1493                                     digit characters, or a Null-terminator.
1494   @retval RETURN_BUFFER_TOO_SMALL  If MaxBufferSize is less than (Length / 2).
1495 **/
1496 RETURN_STATUS
1497 EFIAPI
1498 StrHexToBytes (
1499   IN  CONST CHAR16  *String,
1500   IN  UINTN         Length,
1501   OUT UINT8         *Buffer,
1502   IN  UINTN         MaxBufferSize
1503   );
1504
1505 /**
1506   Convert a Null-terminated Unicode string to a Null-terminated
1507   ASCII string.
1508
1509   This function is similar to AsciiStrCpyS.
1510
1511   This function converts the content of the Unicode string Source
1512   to the ASCII string Destination by copying the lower 8 bits of
1513   each Unicode character. The function terminates the ASCII string
1514   Destination by appending a Null-terminator character at the end.
1515
1516   The caller is responsible to make sure Destination points to a buffer with size
1517   equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1518
1519   If any Unicode characters in Source contain non-zero value in
1520   the upper 8 bits, then ASSERT().
1521
1522   If Source is not aligned on a 16-bit boundary, then ASSERT().
1523
1524   If an error is returned, then the Destination is unmodified.
1525
1526   @param  Source        The pointer to a Null-terminated Unicode string.
1527   @param  Destination   The pointer to a Null-terminated ASCII string.
1528   @param  DestMax       The maximum number of Destination Ascii
1529                         char, including terminating null char.
1530
1531   @retval RETURN_SUCCESS           String is converted.
1532   @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than StrLen(Source).
1533   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1534                                    If Source is NULL.
1535                                    If PcdMaximumAsciiStringLength is not zero,
1536                                     and DestMax is greater than
1537                                     PcdMaximumAsciiStringLength.
1538                                    If PcdMaximumUnicodeStringLength is not zero,
1539                                     and DestMax is greater than
1540                                     PcdMaximumUnicodeStringLength.
1541                                    If DestMax is 0.
1542   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
1543
1544 **/
1545 RETURN_STATUS
1546 EFIAPI
1547 UnicodeStrToAsciiStrS (
1548   IN      CONST CHAR16  *Source,
1549   OUT     CHAR8         *Destination,
1550   IN      UINTN         DestMax
1551   );
1552
1553 /**
1554   Convert not more than Length successive characters from a Null-terminated
1555   Unicode string to a Null-terminated Ascii string. If no null char is copied
1556   from Source, then Destination[Length] is always set to null.
1557
1558   This function converts not more than Length successive characters from the
1559   Unicode string Source to the Ascii string Destination by copying the lower 8
1560   bits of each Unicode character. The function terminates the Ascii string
1561   Destination by appending a Null-terminator character at the end.
1562
1563   The caller is responsible to make sure Destination points to a buffer with size
1564   equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1565
1566   If any Unicode characters in Source contain non-zero value in the upper 8
1567   bits, then ASSERT().
1568   If Source is not aligned on a 16-bit boundary, then ASSERT().
1569
1570   If an error is returned, then the Destination is unmodified.
1571
1572   @param  Source             The pointer to a Null-terminated Unicode string.
1573   @param  Length             The maximum number of Unicode characters to
1574                              convert.
1575   @param  Destination        The pointer to a Null-terminated Ascii string.
1576   @param  DestMax            The maximum number of Destination Ascii
1577                              char, including terminating null char.
1578   @param  DestinationLength  The number of Unicode characters converted.
1579
1580   @retval RETURN_SUCCESS            String is converted.
1581   @retval RETURN_INVALID_PARAMETER  If Destination is NULL.
1582                                     If Source is NULL.
1583                                     If DestinationLength is NULL.
1584                                     If PcdMaximumAsciiStringLength is not zero,
1585                                     and Length or DestMax is greater than
1586                                     PcdMaximumAsciiStringLength.
1587                                     If PcdMaximumUnicodeStringLength is not
1588                                     zero, and Length or DestMax is greater than
1589                                     PcdMaximumUnicodeStringLength.
1590                                     If DestMax is 0.
1591   @retval RETURN_BUFFER_TOO_SMALL   If DestMax is NOT greater than
1592                                     MIN(StrLen(Source), Length).
1593   @retval RETURN_ACCESS_DENIED      If Source and Destination overlap.
1594
1595 **/
1596 RETURN_STATUS
1597 EFIAPI
1598 UnicodeStrnToAsciiStrS (
1599   IN      CONST CHAR16  *Source,
1600   IN      UINTN         Length,
1601   OUT     CHAR8         *Destination,
1602   IN      UINTN         DestMax,
1603   OUT     UINTN         *DestinationLength
1604   );
1605
1606 /**
1607   Returns the length of a Null-terminated ASCII string.
1608
1609   This function returns the number of ASCII characters in the Null-terminated
1610   ASCII string specified by String.
1611
1612   If Length > 0 and Destination is NULL, then ASSERT().
1613   If Length > 0 and Source is NULL, then ASSERT().
1614   If PcdMaximumAsciiStringLength is not zero and String contains more than
1615   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1616   then ASSERT().
1617
1618   @param  String  The pointer to a Null-terminated ASCII string.
1619
1620   @return The length of String.
1621
1622 **/
1623 UINTN
1624 EFIAPI
1625 AsciiStrLen (
1626   IN      CONST CHAR8  *String
1627   );
1628
1629 /**
1630   Returns the size of a Null-terminated ASCII string in bytes, including the
1631   Null terminator.
1632
1633   This function returns the size, in bytes, of the Null-terminated ASCII string
1634   specified by String.
1635
1636   If String is NULL, then ASSERT().
1637   If PcdMaximumAsciiStringLength is not zero and String contains more than
1638   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1639   then ASSERT().
1640
1641   @param  String  The pointer to a Null-terminated ASCII string.
1642
1643   @return The size of String.
1644
1645 **/
1646 UINTN
1647 EFIAPI
1648 AsciiStrSize (
1649   IN      CONST CHAR8  *String
1650   );
1651
1652 /**
1653   Compares two Null-terminated ASCII strings, and returns the difference
1654   between the first mismatched ASCII characters.
1655
1656   This function compares the Null-terminated ASCII string FirstString to the
1657   Null-terminated ASCII string SecondString. If FirstString is identical to
1658   SecondString, then 0 is returned. Otherwise, the value returned is the first
1659   mismatched ASCII character in SecondString subtracted from the first
1660   mismatched ASCII character in FirstString.
1661
1662   If FirstString is NULL, then ASSERT().
1663   If SecondString is NULL, then ASSERT().
1664   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1665   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1666   then ASSERT().
1667   If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1668   than PcdMaximumAsciiStringLength ASCII characters not including the
1669   Null-terminator, then ASSERT().
1670
1671   @param  FirstString   The pointer to a Null-terminated ASCII string.
1672   @param  SecondString  The pointer to a Null-terminated ASCII string.
1673
1674   @retval ==0      FirstString is identical to SecondString.
1675   @retval !=0      FirstString is not identical to SecondString.
1676
1677 **/
1678 INTN
1679 EFIAPI
1680 AsciiStrCmp (
1681   IN      CONST CHAR8  *FirstString,
1682   IN      CONST CHAR8  *SecondString
1683   );
1684
1685 /**
1686   Performs a case insensitive comparison of two Null-terminated ASCII strings,
1687   and returns the difference between the first mismatched ASCII characters.
1688
1689   This function performs a case insensitive comparison of the Null-terminated
1690   ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1691   FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1692   value returned is the first mismatched lower case ASCII character in
1693   SecondString subtracted from the first mismatched lower case ASCII character
1694   in FirstString.
1695
1696   If FirstString is NULL, then ASSERT().
1697   If SecondString is NULL, then ASSERT().
1698   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1699   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1700   then ASSERT().
1701   If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1702   than PcdMaximumAsciiStringLength ASCII characters not including the
1703   Null-terminator, then ASSERT().
1704
1705   @param  FirstString   The pointer to a Null-terminated ASCII string.
1706   @param  SecondString  The pointer to a Null-terminated ASCII string.
1707
1708   @retval ==0    FirstString is identical to SecondString using case insensitive
1709                  comparisons.
1710   @retval !=0    FirstString is not identical to SecondString using case
1711                  insensitive comparisons.
1712
1713 **/
1714 INTN
1715 EFIAPI
1716 AsciiStriCmp (
1717   IN      CONST CHAR8  *FirstString,
1718   IN      CONST CHAR8  *SecondString
1719   );
1720
1721 /**
1722   Compares two Null-terminated ASCII strings with maximum lengths, and returns
1723   the difference between the first mismatched ASCII characters.
1724
1725   This function compares the Null-terminated ASCII string FirstString to the
1726   Null-terminated ASCII  string SecondString. At most, Length ASCII characters
1727   will be compared. If Length is 0, then 0 is returned. If FirstString is
1728   identical to SecondString, then 0 is returned. Otherwise, the value returned
1729   is the first mismatched ASCII character in SecondString subtracted from the
1730   first mismatched ASCII character in FirstString.
1731
1732   If Length > 0 and FirstString is NULL, then ASSERT().
1733   If Length > 0 and SecondString is NULL, then ASSERT().
1734   If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1735   PcdMaximumAsciiStringLength, then ASSERT().
1736   If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
1737   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1738   then ASSERT().
1739   If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
1740   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1741   then ASSERT().
1742
1743   @param  FirstString   The pointer to a Null-terminated ASCII string.
1744   @param  SecondString  The pointer to a Null-terminated ASCII string.
1745   @param  Length        The maximum number of ASCII characters for compare.
1746
1747   @retval ==0       FirstString is identical to SecondString.
1748   @retval !=0       FirstString is not identical to SecondString.
1749
1750 **/
1751 INTN
1752 EFIAPI
1753 AsciiStrnCmp (
1754   IN      CONST CHAR8  *FirstString,
1755   IN      CONST CHAR8  *SecondString,
1756   IN      UINTN        Length
1757   );
1758
1759 /**
1760   Returns the first occurrence of a Null-terminated ASCII sub-string
1761   in a Null-terminated ASCII string.
1762
1763   This function scans the contents of the ASCII string specified by String
1764   and returns the first occurrence of SearchString. If SearchString is not
1765   found in String, then NULL is returned. If the length of SearchString is zero,
1766   then String is returned.
1767
1768   If String is NULL, then ASSERT().
1769   If SearchString is NULL, then ASSERT().
1770
1771   If PcdMaximumAsciiStringLength is not zero, and SearchString or
1772   String contains more than PcdMaximumAsciiStringLength Unicode characters
1773   not including the Null-terminator, then ASSERT().
1774
1775   @param  String          The pointer to a Null-terminated ASCII string.
1776   @param  SearchString    The pointer to a Null-terminated ASCII string to search for.
1777
1778   @retval NULL            If the SearchString does not appear in String.
1779   @retval others          If there is a match return the first occurrence of SearchingString.
1780                           If the length of SearchString is zero,return String.
1781
1782 **/
1783 CHAR8 *
1784 EFIAPI
1785 AsciiStrStr (
1786   IN      CONST CHAR8  *String,
1787   IN      CONST CHAR8  *SearchString
1788   );
1789
1790 /**
1791   Convert a Null-terminated ASCII decimal string to a value of type
1792   UINTN.
1793
1794   This function returns a value of type UINTN by interpreting the contents
1795   of the ASCII string String as a decimal number. The format of the input
1796   ASCII string String is:
1797
1798                     [spaces] [decimal digits].
1799
1800   The valid decimal digit character is in the range [0-9]. The function will
1801   ignore the pad space, which includes spaces or tab characters, before the digits.
1802   The running zero in the beginning of [decimal digits] will be ignored. Then, the
1803   function stops at the first character that is a not a valid decimal character or
1804   Null-terminator, whichever on comes first.
1805
1806   If String has only pad spaces, then 0 is returned.
1807   If String has no pad spaces or valid decimal digits, then 0 is returned.
1808   If the number represented by String overflows according to the range defined by
1809   UINTN, then MAX_UINTN is returned.
1810   If String is NULL, then ASSERT().
1811   If PcdMaximumAsciiStringLength is not zero, and String contains more than
1812   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1813   then ASSERT().
1814
1815   @param  String          The pointer to a Null-terminated ASCII string.
1816
1817   @retval The value translated from String.
1818
1819 **/
1820 UINTN
1821 EFIAPI
1822 AsciiStrDecimalToUintn (
1823   IN      CONST CHAR8  *String
1824   );
1825
1826 /**
1827   Convert a Null-terminated ASCII decimal string to a value of type
1828   UINT64.
1829
1830   This function returns a value of type UINT64 by interpreting the contents
1831   of the ASCII string String as a decimal number. The format of the input
1832   ASCII string String is:
1833
1834                     [spaces] [decimal digits].
1835
1836   The valid decimal digit character is in the range [0-9]. The function will
1837   ignore the pad space, which includes spaces or tab characters, before the digits.
1838   The running zero in the beginning of [decimal digits] will be ignored. Then, the
1839   function stops at the first character that is a not a valid decimal character or
1840   Null-terminator, whichever on comes first.
1841
1842   If String has only pad spaces, then 0 is returned.
1843   If String has no pad spaces or valid decimal digits, then 0 is returned.
1844   If the number represented by String overflows according to the range defined by
1845   UINT64, then MAX_UINT64 is returned.
1846   If String is NULL, then ASSERT().
1847   If PcdMaximumAsciiStringLength is not zero, and String contains more than
1848   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1849   then ASSERT().
1850
1851   @param  String          The pointer to a Null-terminated ASCII string.
1852
1853   @retval Value translated from String.
1854
1855 **/
1856 UINT64
1857 EFIAPI
1858 AsciiStrDecimalToUint64 (
1859   IN      CONST CHAR8  *String
1860   );
1861
1862 /**
1863   Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1864
1865   This function returns a value of type UINTN by interpreting the contents of
1866   the ASCII string String as a hexadecimal number. The format of the input ASCII
1867   string String is:
1868
1869                   [spaces][zeros][x][hexadecimal digits].
1870
1871   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1872   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1873   appears in the input string, it must be prefixed with at least one 0. The function
1874   will ignore the pad space, which includes spaces or tab characters, before [zeros],
1875   [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1876   will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1877   digit. Then, the function stops at the first character that is a not a valid
1878   hexadecimal character or Null-terminator, whichever on comes first.
1879
1880   If String has only pad spaces, then 0 is returned.
1881   If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1882   0 is returned.
1883
1884   If the number represented by String overflows according to the range defined by UINTN,
1885   then MAX_UINTN is returned.
1886   If String is NULL, then ASSERT().
1887   If PcdMaximumAsciiStringLength is not zero,
1888   and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1889   the Null-terminator, then ASSERT().
1890
1891   @param  String          The pointer to a Null-terminated ASCII string.
1892
1893   @retval Value translated from String.
1894
1895 **/
1896 UINTN
1897 EFIAPI
1898 AsciiStrHexToUintn (
1899   IN      CONST CHAR8  *String
1900   );
1901
1902 /**
1903   Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1904
1905   This function returns a value of type UINT64 by interpreting the contents of
1906   the ASCII string String as a hexadecimal number. The format of the input ASCII
1907   string String is:
1908
1909                   [spaces][zeros][x][hexadecimal digits].
1910
1911   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1912   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1913   appears in the input string, it must be prefixed with at least one 0. The function
1914   will ignore the pad space, which includes spaces or tab characters, before [zeros],
1915   [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1916   will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1917   digit. Then, the function stops at the first character that is a not a valid
1918   hexadecimal character or Null-terminator, whichever on comes first.
1919
1920   If String has only pad spaces, then 0 is returned.
1921   If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1922   0 is returned.
1923
1924   If the number represented by String overflows according to the range defined by UINT64,
1925   then MAX_UINT64 is returned.
1926   If String is NULL, then ASSERT().
1927   If PcdMaximumAsciiStringLength is not zero,
1928   and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1929   the Null-terminator, then ASSERT().
1930
1931   @param  String          The pointer to a Null-terminated ASCII string.
1932
1933   @retval Value translated from String.
1934
1935 **/
1936 UINT64
1937 EFIAPI
1938 AsciiStrHexToUint64 (
1939   IN      CONST CHAR8  *String
1940   );
1941
1942 /**
1943   Convert a Null-terminated ASCII string to IPv6 address and prefix length.
1944
1945   This function outputs a value of type IPv6_ADDRESS and may output a value
1946   of type UINT8 by interpreting the contents of the ASCII string specified
1947   by String. The format of the input ASCII string String is as follows:
1948
1949                   X:X:X:X:X:X:X:X[/P]
1950
1951   X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1952   [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1953   memory address and high byte is stored in high memory address. P contains decimal
1954   digit characters in the range [0-9]. The running zero in the beginning of P will
1955   be ignored. /P is optional.
1956
1957   When /P is not in the String, the function stops at the first character that is
1958   not a valid hexadecimal digit character after eight X's are converted.
1959
1960   When /P is in the String, the function stops at the first character that is not
1961   a valid decimal digit character after P is converted.
1962
1963   "::" can be used to compress one or more groups of X when X contains only 0.
1964   The "::" can only appear once in the String.
1965
1966   If EndPointer is not NULL and Address is translated from String, a pointer
1967   to the character that stopped the scan is stored at the location pointed to
1968   by EndPointer.
1969
1970   @param  String                   Pointer to a Null-terminated ASCII string.
1971   @param  EndPointer               Pointer to character that stops scan.
1972   @param  Address                  Pointer to the converted IPv6 address.
1973   @param  PrefixLength             Pointer to the converted IPv6 address prefix
1974                                    length. MAX_UINT8 is returned when /P is
1975                                    not in the String.
1976
1977   @retval RETURN_SUCCESS           Address is translated from String.
1978   @retval RETURN_INVALID_PARAMETER If String is NULL.
1979                                    If Data is NULL.
1980   @retval RETURN_UNSUPPORTED       If X contains more than four hexadecimal
1981                                     digit characters.
1982                                    If String contains "::" and number of X
1983                                     is not less than 8.
1984                                    If P starts with character that is not a
1985                                     valid decimal digit character.
1986                                    If the decimal number converted from P
1987                                     exceeds 128.
1988
1989 **/
1990 RETURN_STATUS
1991 EFIAPI
1992 AsciiStrToIpv6Address (
1993   IN  CONST CHAR8   *String,
1994   OUT CHAR8         **EndPointer  OPTIONAL,
1995   OUT IPv6_ADDRESS  *Address,
1996   OUT UINT8         *PrefixLength OPTIONAL
1997   );
1998
1999 /**
2000   Convert a Null-terminated ASCII string to IPv4 address and prefix length.
2001
2002   This function outputs a value of type IPv4_ADDRESS and may output a value
2003   of type UINT8 by interpreting the contents of the ASCII string specified
2004   by String. The format of the input ASCII string String is as follows:
2005
2006                   D.D.D.D[/P]
2007
2008   D and P are decimal digit characters in the range [0-9]. The running zero in
2009   the beginning of D and P will be ignored. /P is optional.
2010
2011   When /P is not in the String, the function stops at the first character that is
2012   not a valid decimal digit character after four D's are converted.
2013
2014   When /P is in the String, the function stops at the first character that is not
2015   a valid decimal digit character after P is converted.
2016
2017   If EndPointer is not NULL and Address is translated from String, a pointer
2018   to the character that stopped the scan is stored at the location pointed to
2019   by EndPointer.
2020
2021   @param  String                   Pointer to a Null-terminated ASCII string.
2022   @param  EndPointer               Pointer to character that stops scan.
2023   @param  Address                  Pointer to the converted IPv4 address.
2024   @param  PrefixLength             Pointer to the converted IPv4 address prefix
2025                                    length. MAX_UINT8 is returned when /P is
2026                                    not in the String.
2027
2028   @retval RETURN_SUCCESS           Address is translated from String.
2029   @retval RETURN_INVALID_PARAMETER If String is NULL.
2030                                    If Data is NULL.
2031   @retval RETURN_UNSUPPORTED       If String is not in the correct format.
2032                                    If any decimal number converted from D
2033                                     exceeds 255.
2034                                    If the decimal number converted from P
2035                                     exceeds 32.
2036
2037 **/
2038 RETURN_STATUS
2039 EFIAPI
2040 AsciiStrToIpv4Address (
2041   IN  CONST CHAR8   *String,
2042   OUT CHAR8         **EndPointer  OPTIONAL,
2043   OUT IPv4_ADDRESS  *Address,
2044   OUT UINT8         *PrefixLength OPTIONAL
2045   );
2046
2047 /**
2048   Convert a Null-terminated ASCII GUID string to a value of type
2049   EFI_GUID.
2050
2051   This function outputs a GUID value by interpreting the contents of
2052   the ASCII string specified by String. The format of the input
2053   ASCII string String consists of 36 characters, as follows:
2054
2055                   aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
2056
2057   The pairs aa - pp are two characters in the range [0-9], [a-f] and
2058   [A-F], with each pair representing a single byte hexadecimal value.
2059
2060   The mapping between String and the EFI_GUID structure is as follows:
2061                   aa          Data1[24:31]
2062                   bb          Data1[16:23]
2063                   cc          Data1[8:15]
2064                   dd          Data1[0:7]
2065                   ee          Data2[8:15]
2066                   ff          Data2[0:7]
2067                   gg          Data3[8:15]
2068                   hh          Data3[0:7]
2069                   ii          Data4[0:7]
2070                   jj          Data4[8:15]
2071                   kk          Data4[16:23]
2072                   ll          Data4[24:31]
2073                   mm          Data4[32:39]
2074                   nn          Data4[40:47]
2075                   oo          Data4[48:55]
2076                   pp          Data4[56:63]
2077
2078   @param  String                   Pointer to a Null-terminated ASCII string.
2079   @param  Guid                     Pointer to the converted GUID.
2080
2081   @retval RETURN_SUCCESS           Guid is translated from String.
2082   @retval RETURN_INVALID_PARAMETER If String is NULL.
2083                                    If Data is NULL.
2084   @retval RETURN_UNSUPPORTED       If String is not as the above format.
2085
2086 **/
2087 RETURN_STATUS
2088 EFIAPI
2089 AsciiStrToGuid (
2090   IN  CONST CHAR8  *String,
2091   OUT GUID         *Guid
2092   );
2093
2094 /**
2095   Convert a Null-terminated ASCII hexadecimal string to a byte array.
2096
2097   This function outputs a byte array by interpreting the contents of
2098   the ASCII string specified by String in hexadecimal format. The format of
2099   the input ASCII string String is:
2100
2101                   [XX]*
2102
2103   X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
2104   The function decodes every two hexadecimal digit characters as one byte. The
2105   decoding stops after Length of characters and outputs Buffer containing
2106   (Length / 2) bytes.
2107
2108   @param  String                   Pointer to a Null-terminated ASCII string.
2109   @param  Length                   The number of ASCII characters to decode.
2110   @param  Buffer                   Pointer to the converted bytes array.
2111   @param  MaxBufferSize            The maximum size of Buffer.
2112
2113   @retval RETURN_SUCCESS           Buffer is translated from String.
2114   @retval RETURN_INVALID_PARAMETER If String is NULL.
2115                                    If Data is NULL.
2116                                    If Length is not multiple of 2.
2117                                    If PcdMaximumAsciiStringLength is not zero,
2118                                     and Length is greater than
2119                                     PcdMaximumAsciiStringLength.
2120   @retval RETURN_UNSUPPORTED       If Length of characters from String contain
2121                                     a character that is not valid hexadecimal
2122                                     digit characters, or a Null-terminator.
2123   @retval RETURN_BUFFER_TOO_SMALL  If MaxBufferSize is less than (Length / 2).
2124 **/
2125 RETURN_STATUS
2126 EFIAPI
2127 AsciiStrHexToBytes (
2128   IN  CONST CHAR8  *String,
2129   IN  UINTN        Length,
2130   OUT UINT8        *Buffer,
2131   IN  UINTN        MaxBufferSize
2132   );
2133
2134 /**
2135   Convert one Null-terminated ASCII string to a Null-terminated
2136   Unicode string.
2137
2138   This function is similar to StrCpyS.
2139
2140   This function converts the contents of the ASCII string Source to the Unicode
2141   string Destination. The function terminates the Unicode string Destination by
2142   appending a Null-terminator character at the end.
2143
2144   The caller is responsible to make sure Destination points to a buffer with size
2145   equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2146
2147   If Destination is not aligned on a 16-bit boundary, then ASSERT().
2148
2149   If an error is returned, then the Destination is unmodified.
2150
2151   @param  Source        The pointer to a Null-terminated ASCII string.
2152   @param  Destination   The pointer to a Null-terminated Unicode string.
2153   @param  DestMax       The maximum number of Destination Unicode
2154                         char, including terminating null char.
2155
2156   @retval RETURN_SUCCESS           String is converted.
2157   @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than StrLen(Source).
2158   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2159                                    If Source is NULL.
2160                                    If PcdMaximumUnicodeStringLength is not zero,
2161                                     and DestMax is greater than
2162                                     PcdMaximumUnicodeStringLength.
2163                                    If PcdMaximumAsciiStringLength is not zero,
2164                                     and DestMax is greater than
2165                                     PcdMaximumAsciiStringLength.
2166                                    If DestMax is 0.
2167   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
2168
2169 **/
2170 RETURN_STATUS
2171 EFIAPI
2172 AsciiStrToUnicodeStrS (
2173   IN      CONST CHAR8  *Source,
2174   OUT     CHAR16       *Destination,
2175   IN      UINTN        DestMax
2176   );
2177
2178 /**
2179   Convert not more than Length successive characters from a Null-terminated
2180   Ascii string to a Null-terminated Unicode string. If no null char is copied
2181   from Source, then Destination[Length] is always set to null.
2182
2183   This function converts not more than Length successive characters from the
2184   Ascii string Source to the Unicode string Destination. The function
2185   terminates the Unicode string Destination by appending a Null-terminator
2186   character at the end.
2187
2188   The caller is responsible to make sure Destination points to a buffer with
2189   size not smaller than
2190   ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2191
2192   If Destination is not aligned on a 16-bit boundary, then ASSERT().
2193
2194   If an error is returned, then Destination and DestinationLength are
2195   unmodified.
2196
2197   @param  Source             The pointer to a Null-terminated Ascii string.
2198   @param  Length             The maximum number of Ascii characters to convert.
2199   @param  Destination        The pointer to a Null-terminated Unicode string.
2200   @param  DestMax            The maximum number of Destination Unicode char,
2201                              including terminating null char.
2202   @param  DestinationLength  The number of Ascii characters converted.
2203
2204   @retval RETURN_SUCCESS            String is converted.
2205   @retval RETURN_INVALID_PARAMETER  If Destination is NULL.
2206                                     If Source is NULL.
2207                                     If DestinationLength is NULL.
2208                                     If PcdMaximumUnicodeStringLength is not
2209                                     zero, and Length or DestMax is greater than
2210                                     PcdMaximumUnicodeStringLength.
2211                                     If PcdMaximumAsciiStringLength is not zero,
2212                                     and Length or DestMax is greater than
2213                                     PcdMaximumAsciiStringLength.
2214                                     If DestMax is 0.
2215   @retval RETURN_BUFFER_TOO_SMALL   If DestMax is NOT greater than
2216                                     MIN(AsciiStrLen(Source), Length).
2217   @retval RETURN_ACCESS_DENIED      If Source and Destination overlap.
2218
2219 **/
2220 RETURN_STATUS
2221 EFIAPI
2222 AsciiStrnToUnicodeStrS (
2223   IN      CONST CHAR8  *Source,
2224   IN      UINTN        Length,
2225   OUT     CHAR16       *Destination,
2226   IN      UINTN        DestMax,
2227   OUT     UINTN        *DestinationLength
2228   );
2229
2230 /**
2231   Convert a Unicode character to upper case only if
2232   it maps to a valid small-case ASCII character.
2233
2234   This internal function only deal with Unicode character
2235   which maps to a valid small-case ASCII character, i.e.
2236   L'a' to L'z'. For other Unicode character, the input character
2237   is returned directly.
2238
2239   @param  Char  The character to convert.
2240
2241   @retval LowerCharacter   If the Char is with range L'a' to L'z'.
2242   @retval Unchanged        Otherwise.
2243
2244 **/
2245 CHAR16
2246 EFIAPI
2247 CharToUpper (
2248   IN      CHAR16  Char
2249   );
2250
2251 /**
2252   Converts a lowercase Ascii character to upper one.
2253
2254   If Chr is lowercase Ascii character, then converts it to upper one.
2255
2256   If Value >= 0xA0, then ASSERT().
2257   If (Value & 0x0F) >= 0x0A, then ASSERT().
2258
2259   @param  Chr   one Ascii character
2260
2261   @return The uppercase value of Ascii character
2262
2263 **/
2264 CHAR8
2265 EFIAPI
2266 AsciiCharToUpper (
2267   IN      CHAR8  Chr
2268   );
2269
2270 /**
2271   Convert binary data to a Base64 encoded ascii string based on RFC4648.
2272
2273   Produce a Null-terminated Ascii string in the output buffer specified by Destination and DestinationSize.
2274   The Ascii string is produced by converting the data string specified by Source and SourceLength.
2275
2276   @param Source           Input UINT8 data
2277   @param SourceLength     Number of UINT8 bytes of data
2278   @param Destination      Pointer to output string buffer
2279   @param DestinationSize  Size of ascii buffer. Set to 0 to get the size needed.
2280                           Caller is responsible for passing in buffer of DestinationSize
2281
2282   @retval RETURN_SUCCESS             When ascii buffer is filled in.
2283   @retval RETURN_INVALID_PARAMETER   If Source is NULL or DestinationSize is NULL.
2284   @retval RETURN_INVALID_PARAMETER   If SourceLength or DestinationSize is bigger than (MAX_ADDRESS - (UINTN)Destination).
2285   @retval RETURN_BUFFER_TOO_SMALL    If SourceLength is 0 and DestinationSize is <1.
2286   @retval RETURN_BUFFER_TOO_SMALL    If Destination is NULL or DestinationSize is smaller than required buffersize.
2287
2288 **/
2289 RETURN_STATUS
2290 EFIAPI
2291 Base64Encode (
2292   IN  CONST UINT8  *Source,
2293   IN        UINTN  SourceLength,
2294   OUT       CHAR8  *Destination  OPTIONAL,
2295   IN OUT    UINTN  *DestinationSize
2296   );
2297
2298 /**
2299   Decode Base64 ASCII encoded data to 8-bit binary representation, based on
2300   RFC4648.
2301
2302   Decoding occurs according to "Table 1: The Base 64 Alphabet" in RFC4648.
2303
2304   Whitespace is ignored at all positions:
2305   - 0x09 ('\t') horizontal tab
2306   - 0x0A ('\n') new line
2307   - 0x0B ('\v') vertical tab
2308   - 0x0C ('\f') form feed
2309   - 0x0D ('\r') carriage return
2310   - 0x20 (' ')  space
2311
2312   The minimum amount of required padding (with ASCII 0x3D, '=') is tolerated
2313   and enforced at the end of the Base64 ASCII encoded data, and only there.
2314
2315   Other characters outside of the encoding alphabet cause the function to
2316   reject the Base64 ASCII encoded data.
2317
2318   @param[in] Source               Array of CHAR8 elements containing the Base64
2319                                   ASCII encoding. May be NULL if SourceSize is
2320                                   zero.
2321
2322   @param[in] SourceSize           Number of CHAR8 elements in Source.
2323
2324   @param[out] Destination         Array of UINT8 elements receiving the decoded
2325                                   8-bit binary representation. Allocated by the
2326                                   caller. May be NULL if DestinationSize is
2327                                   zero on input. If NULL, decoding is
2328                                   performed, but the 8-bit binary
2329                                   representation is not stored. If non-NULL and
2330                                   the function returns an error, the contents
2331                                   of Destination are indeterminate.
2332
2333   @param[in,out] DestinationSize  On input, the number of UINT8 elements that
2334                                   the caller allocated for Destination. On
2335                                   output, if the function returns
2336                                   RETURN_SUCCESS or RETURN_BUFFER_TOO_SMALL,
2337                                   the number of UINT8 elements that are
2338                                   required for decoding the Base64 ASCII
2339                                   representation. If the function returns a
2340                                   value different from both RETURN_SUCCESS and
2341                                   RETURN_BUFFER_TOO_SMALL, then DestinationSize
2342                                   is indeterminate on output.
2343
2344   @retval RETURN_SUCCESS            SourceSize CHAR8 elements at Source have
2345                                     been decoded to on-output DestinationSize
2346                                     UINT8 elements at Destination. Note that
2347                                     RETURN_SUCCESS covers the case when
2348                                     DestinationSize is zero on input, and
2349                                     Source decodes to zero bytes (due to
2350                                     containing at most ignored whitespace).
2351
2352   @retval RETURN_BUFFER_TOO_SMALL   The input value of DestinationSize is not
2353                                     large enough for decoding SourceSize CHAR8
2354                                     elements at Source. The required number of
2355                                     UINT8 elements has been stored to
2356                                     DestinationSize.
2357
2358   @retval RETURN_INVALID_PARAMETER  DestinationSize is NULL.
2359
2360   @retval RETURN_INVALID_PARAMETER  Source is NULL, but SourceSize is not zero.
2361
2362   @retval RETURN_INVALID_PARAMETER  Destination is NULL, but DestinationSize is
2363                                     not zero on input.
2364
2365   @retval RETURN_INVALID_PARAMETER  Source is non-NULL, and (Source +
2366                                     SourceSize) would wrap around MAX_ADDRESS.
2367
2368   @retval RETURN_INVALID_PARAMETER  Destination is non-NULL, and (Destination +
2369                                     DestinationSize) would wrap around
2370                                     MAX_ADDRESS, as specified on input.
2371
2372   @retval RETURN_INVALID_PARAMETER  None of Source and Destination are NULL,
2373                                     and CHAR8[SourceSize] at Source overlaps
2374                                     UINT8[DestinationSize] at Destination, as
2375                                     specified on input.
2376
2377   @retval RETURN_INVALID_PARAMETER  Invalid CHAR8 element encountered in
2378                                     Source.
2379 **/
2380 RETURN_STATUS
2381 EFIAPI
2382 Base64Decode (
2383   IN     CONST CHAR8  *Source          OPTIONAL,
2384   IN     UINTN        SourceSize,
2385   OUT    UINT8        *Destination     OPTIONAL,
2386   IN OUT UINTN        *DestinationSize
2387   );
2388
2389 /**
2390   Converts an 8-bit value to an 8-bit BCD value.
2391
2392   Converts the 8-bit value specified by Value to BCD. The BCD value is
2393   returned.
2394
2395   If Value >= 100, then ASSERT().
2396
2397   @param  Value The 8-bit value to convert to BCD. Range 0..99.
2398
2399   @return The BCD value.
2400
2401 **/
2402 UINT8
2403 EFIAPI
2404 DecimalToBcd8 (
2405   IN      UINT8  Value
2406   );
2407
2408 /**
2409   Converts an 8-bit BCD value to an 8-bit value.
2410
2411   Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2412   value is returned.
2413
2414   If Value >= 0xA0, then ASSERT().
2415   If (Value & 0x0F) >= 0x0A, then ASSERT().
2416
2417   @param  Value The 8-bit BCD value to convert to an 8-bit value.
2418
2419   @return The 8-bit value is returned.
2420
2421 **/
2422 UINT8
2423 EFIAPI
2424 BcdToDecimal8 (
2425   IN      UINT8  Value
2426   );
2427
2428 //
2429 //  File Path Manipulation Functions
2430 //
2431
2432 /**
2433   Removes the last directory or file entry in a path.
2434
2435   @param[in, out] Path    The pointer to the path to modify.
2436
2437   @retval FALSE     Nothing was found to remove.
2438   @retval TRUE      A directory or file was removed.
2439 **/
2440 BOOLEAN
2441 EFIAPI
2442 PathRemoveLastItem (
2443   IN OUT CHAR16  *Path
2444   );
2445
2446 /**
2447   Function to clean up paths.
2448     - Single periods in the path are removed.
2449     - Double periods in the path are removed along with a single parent directory.
2450     - Forward slashes L'/' are converted to backward slashes L'\'.
2451
2452   This will be done inline and the existing buffer may be larger than required
2453   upon completion.
2454
2455   @param[in] Path       The pointer to the string containing the path.
2456
2457   @return       Returns Path, otherwise returns NULL to indicate that an error has occurred.
2458 **/
2459 CHAR16 *
2460 EFIAPI
2461 PathCleanUpDirectories (
2462   IN CHAR16  *Path
2463   );
2464
2465 //
2466 // Linked List Functions and Macros
2467 //
2468
2469 /**
2470   Initializes the head node of a doubly linked list that is declared as a
2471   global variable in a module.
2472
2473   Initializes the forward and backward links of a new linked list. After
2474   initializing a linked list with this macro, the other linked list functions
2475   may be used to add and remove nodes from the linked list. This macro results
2476   in smaller executables by initializing the linked list in the data section,
2477   instead if calling the InitializeListHead() function to perform the
2478   equivalent operation.
2479
2480   @param  ListHead  The head note of a list to initialize.
2481
2482 **/
2483 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead)  {&(ListHead), &(ListHead)}
2484
2485 /**
2486   Iterates over each node in a doubly linked list using each node's forward link.
2487
2488   @param  Entry     A pointer to a list node used as a loop cursor during iteration
2489   @param  ListHead  The head node of the doubly linked list
2490
2491 **/
2492 #define BASE_LIST_FOR_EACH(Entry, ListHead)    \
2493   for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink)
2494
2495 /**
2496   Iterates over each node in a doubly linked list using each node's forward link
2497   with safety against node removal.
2498
2499   This macro uses NextEntry to temporarily store the next list node so the node
2500   pointed to by Entry may be deleted in the current loop iteration step and
2501   iteration can continue from the node pointed to by NextEntry.
2502
2503   @param  Entry     A pointer to a list node used as a loop cursor during iteration
2504   @param  NextEntry A pointer to a list node used to temporarily store the next node
2505   @param  ListHead  The head node of the doubly linked list
2506
2507 **/
2508 #define BASE_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead)            \
2509   for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\
2510       Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink)
2511
2512 /**
2513   Checks whether FirstEntry and SecondEntry are part of the same doubly-linked
2514   list.
2515
2516   If FirstEntry is NULL, then ASSERT().
2517   If FirstEntry->ForwardLink is NULL, then ASSERT().
2518   If FirstEntry->BackLink is NULL, then ASSERT().
2519   If SecondEntry is NULL, then ASSERT();
2520   If PcdMaximumLinkedListLength is not zero, and List contains more than
2521   PcdMaximumLinkedListLength nodes, then ASSERT().
2522
2523   @param  FirstEntry   A pointer to a node in a linked list.
2524   @param  SecondEntry  A pointer to the node to locate.
2525
2526   @retval TRUE   SecondEntry is in the same doubly-linked list as FirstEntry.
2527   @retval FALSE  SecondEntry isn't in the same doubly-linked list as FirstEntry,
2528                  or FirstEntry is invalid.
2529
2530 **/
2531 BOOLEAN
2532 EFIAPI
2533 IsNodeInList (
2534   IN      CONST LIST_ENTRY  *FirstEntry,
2535   IN      CONST LIST_ENTRY  *SecondEntry
2536   );
2537
2538 /**
2539   Initializes the head node of a doubly linked list, and returns the pointer to
2540   the head node of the doubly linked list.
2541
2542   Initializes the forward and backward links of a new linked list. After
2543   initializing a linked list with this function, the other linked list
2544   functions may be used to add and remove nodes from the linked list. It is up
2545   to the caller of this function to allocate the memory for ListHead.
2546
2547   If ListHead is NULL, then ASSERT().
2548
2549   @param  ListHead  A pointer to the head node of a new doubly linked list.
2550
2551   @return ListHead
2552
2553 **/
2554 LIST_ENTRY *
2555 EFIAPI
2556 InitializeListHead (
2557   IN OUT  LIST_ENTRY  *ListHead
2558   );
2559
2560 /**
2561   Adds a node to the beginning of a doubly linked list, and returns the pointer
2562   to the head node of the doubly linked list.
2563
2564   Adds the node Entry at the beginning of the doubly linked list denoted by
2565   ListHead, and returns ListHead.
2566
2567   If ListHead is NULL, then ASSERT().
2568   If Entry is NULL, then ASSERT().
2569   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2570   InitializeListHead(), then ASSERT().
2571   If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2572   of nodes in ListHead, including the ListHead node, is greater than or
2573   equal to PcdMaximumLinkedListLength, then ASSERT().
2574
2575   @param  ListHead  A pointer to the head node of a doubly linked list.
2576   @param  Entry     A pointer to a node that is to be inserted at the beginning
2577                     of a doubly linked list.
2578
2579   @return ListHead
2580
2581 **/
2582 LIST_ENTRY *
2583 EFIAPI
2584 InsertHeadList (
2585   IN OUT  LIST_ENTRY  *ListHead,
2586   IN OUT  LIST_ENTRY  *Entry
2587   );
2588
2589 /**
2590   Adds a node to the end of a doubly linked list, and returns the pointer to
2591   the head node of the doubly linked list.
2592
2593   Adds the node Entry to the end of the doubly linked list denoted by ListHead,
2594   and returns ListHead.
2595
2596   If ListHead is NULL, then ASSERT().
2597   If Entry is NULL, then ASSERT().
2598   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2599   InitializeListHead(), then ASSERT().
2600   If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2601   of nodes in ListHead, including the ListHead node, is greater than or
2602   equal to PcdMaximumLinkedListLength, then ASSERT().
2603
2604   @param  ListHead  A pointer to the head node of a doubly linked list.
2605   @param  Entry     A pointer to a node that is to be added at the end of the
2606                     doubly linked list.
2607
2608   @return ListHead
2609
2610 **/
2611 LIST_ENTRY *
2612 EFIAPI
2613 InsertTailList (
2614   IN OUT  LIST_ENTRY  *ListHead,
2615   IN OUT  LIST_ENTRY  *Entry
2616   );
2617
2618 /**
2619   Retrieves the first node of a doubly linked list.
2620
2621   Returns the first node of a doubly linked list.  List must have been
2622   initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2623   If List is empty, then List is returned.
2624
2625   If List is NULL, then ASSERT().
2626   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2627   InitializeListHead(), then ASSERT().
2628   If PcdMaximumLinkedListLength is not zero, and the number of nodes
2629   in List, including the List node, is greater than or equal to
2630   PcdMaximumLinkedListLength, then ASSERT().
2631
2632   @param  List  A pointer to the head node of a doubly linked list.
2633
2634   @return The first node of a doubly linked list.
2635   @retval List  The list is empty.
2636
2637 **/
2638 LIST_ENTRY *
2639 EFIAPI
2640 GetFirstNode (
2641   IN      CONST LIST_ENTRY  *List
2642   );
2643
2644 /**
2645   Retrieves the next node of a doubly linked list.
2646
2647   Returns the node of a doubly linked list that follows Node.
2648   List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2649   or InitializeListHead().  If List is empty, then List is returned.
2650
2651   If List is NULL, then ASSERT().
2652   If Node is NULL, then ASSERT().
2653   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2654   InitializeListHead(), then ASSERT().
2655   If PcdMaximumLinkedListLength is not zero, and List contains more than
2656   PcdMaximumLinkedListLength nodes, then ASSERT().
2657   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2658
2659   @param  List  A pointer to the head node of a doubly linked list.
2660   @param  Node  A pointer to a node in the doubly linked list.
2661
2662   @return The pointer to the next node if one exists. Otherwise List is returned.
2663
2664 **/
2665 LIST_ENTRY *
2666 EFIAPI
2667 GetNextNode (
2668   IN      CONST LIST_ENTRY  *List,
2669   IN      CONST LIST_ENTRY  *Node
2670   );
2671
2672 /**
2673   Retrieves the previous node of a doubly linked list.
2674
2675   Returns the node of a doubly linked list that precedes Node.
2676   List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2677   or InitializeListHead().  If List is empty, then List is returned.
2678
2679   If List is NULL, then ASSERT().
2680   If Node is NULL, then ASSERT().
2681   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2682   InitializeListHead(), then ASSERT().
2683   If PcdMaximumLinkedListLength is not zero, and List contains more than
2684   PcdMaximumLinkedListLength nodes, then ASSERT().
2685   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2686
2687   @param  List  A pointer to the head node of a doubly linked list.
2688   @param  Node  A pointer to a node in the doubly linked list.
2689
2690   @return The pointer to the previous node if one exists. Otherwise List is returned.
2691
2692 **/
2693 LIST_ENTRY *
2694 EFIAPI
2695 GetPreviousNode (
2696   IN      CONST LIST_ENTRY  *List,
2697   IN      CONST LIST_ENTRY  *Node
2698   );
2699
2700 /**
2701   Checks to see if a doubly linked list is empty or not.
2702
2703   Checks to see if the doubly linked list is empty. If the linked list contains
2704   zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
2705
2706   If ListHead is NULL, then ASSERT().
2707   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2708   InitializeListHead(), then ASSERT().
2709   If PcdMaximumLinkedListLength is not zero, and the number of nodes
2710   in List, including the List node, is greater than or equal to
2711   PcdMaximumLinkedListLength, then ASSERT().
2712
2713   @param  ListHead  A pointer to the head node of a doubly linked list.
2714
2715   @retval TRUE  The linked list is empty.
2716   @retval FALSE The linked list is not empty.
2717
2718 **/
2719 BOOLEAN
2720 EFIAPI
2721 IsListEmpty (
2722   IN      CONST LIST_ENTRY  *ListHead
2723   );
2724
2725 /**
2726   Determines if a node in a doubly linked list is the head node of a the same
2727   doubly linked list.  This function is typically used to terminate a loop that
2728   traverses all the nodes in a doubly linked list starting with the head node.
2729
2730   Returns TRUE if Node is equal to List.  Returns FALSE if Node is one of the
2731   nodes in the doubly linked list specified by List.  List must have been
2732   initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2733
2734   If List is NULL, then ASSERT().
2735   If Node is NULL, then ASSERT().
2736   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
2737   then ASSERT().
2738   If PcdMaximumLinkedListLength is not zero, and the number of nodes
2739   in List, including the List node, is greater than or equal to
2740   PcdMaximumLinkedListLength, then ASSERT().
2741   If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
2742   to List, then ASSERT().
2743
2744   @param  List  A pointer to the head node of a doubly linked list.
2745   @param  Node  A pointer to a node in the doubly linked list.
2746
2747   @retval TRUE  Node is the head of the doubly-linked list pointed by List.
2748   @retval FALSE Node is not the head of the doubly-linked list pointed by List.
2749
2750 **/
2751 BOOLEAN
2752 EFIAPI
2753 IsNull (
2754   IN      CONST LIST_ENTRY  *List,
2755   IN      CONST LIST_ENTRY  *Node
2756   );
2757
2758 /**
2759   Determines if a node the last node in a doubly linked list.
2760
2761   Returns TRUE if Node is the last node in the doubly linked list specified by
2762   List. Otherwise, FALSE is returned. List must have been initialized with
2763   INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2764
2765   If List is NULL, then ASSERT().
2766   If Node is NULL, then ASSERT().
2767   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2768   InitializeListHead(), then ASSERT().
2769   If PcdMaximumLinkedListLength is not zero, and the number of nodes
2770   in List, including the List node, is greater than or equal to
2771   PcdMaximumLinkedListLength, then ASSERT().
2772   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2773
2774   @param  List  A pointer to the head node of a doubly linked list.
2775   @param  Node  A pointer to a node in the doubly linked list.
2776
2777   @retval TRUE  Node is the last node in the linked list.
2778   @retval FALSE Node is not the last node in the linked list.
2779
2780 **/
2781 BOOLEAN
2782 EFIAPI
2783 IsNodeAtEnd (
2784   IN      CONST LIST_ENTRY  *List,
2785   IN      CONST LIST_ENTRY  *Node
2786   );
2787
2788 /**
2789   Swaps the location of two nodes in a doubly linked list, and returns the
2790   first node after the swap.
2791
2792   If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
2793   Otherwise, the location of the FirstEntry node is swapped with the location
2794   of the SecondEntry node in a doubly linked list. SecondEntry must be in the
2795   same double linked list as FirstEntry and that double linked list must have
2796   been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2797   SecondEntry is returned after the nodes are swapped.
2798
2799   If FirstEntry is NULL, then ASSERT().
2800   If SecondEntry is NULL, then ASSERT().
2801   If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
2802   same linked list, then ASSERT().
2803   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
2804   linked list containing the FirstEntry and SecondEntry nodes, including
2805   the FirstEntry and SecondEntry nodes, is greater than or equal to
2806   PcdMaximumLinkedListLength, then ASSERT().
2807
2808   @param  FirstEntry  A pointer to a node in a linked list.
2809   @param  SecondEntry A pointer to another node in the same linked list.
2810
2811   @return SecondEntry.
2812
2813 **/
2814 LIST_ENTRY *
2815 EFIAPI
2816 SwapListEntries (
2817   IN OUT  LIST_ENTRY  *FirstEntry,
2818   IN OUT  LIST_ENTRY  *SecondEntry
2819   );
2820
2821 /**
2822   Removes a node from a doubly linked list, and returns the node that follows
2823   the removed node.
2824
2825   Removes the node Entry from a doubly linked list. It is up to the caller of
2826   this function to release the memory used by this node if that is required. On
2827   exit, the node following Entry in the doubly linked list is returned. If
2828   Entry is the only node in the linked list, then the head node of the linked
2829   list is returned.
2830
2831   If Entry is NULL, then ASSERT().
2832   If Entry is the head node of an empty list, then ASSERT().
2833   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
2834   linked list containing Entry, including the Entry node, is greater than
2835   or equal to PcdMaximumLinkedListLength, then ASSERT().
2836
2837   @param  Entry A pointer to a node in a linked list.
2838
2839   @return Entry.
2840
2841 **/
2842 LIST_ENTRY *
2843 EFIAPI
2844 RemoveEntryList (
2845   IN      CONST LIST_ENTRY  *Entry
2846   );
2847
2848 //
2849 // Math Services
2850 //
2851
2852 /**
2853   Prototype for comparison function for any two element types.
2854
2855   @param[in] Buffer1                  The pointer to first buffer.
2856   @param[in] Buffer2                  The pointer to second buffer.
2857
2858   @retval 0                           Buffer1 equal to Buffer2.
2859   @return <0                          Buffer1 is less than Buffer2.
2860   @return >0                          Buffer1 is greater than Buffer2.
2861 **/
2862 typedef
2863 INTN
2864 (EFIAPI *BASE_SORT_COMPARE)(
2865   IN CONST VOID                 *Buffer1,
2866   IN CONST VOID                 *Buffer2
2867   );
2868
2869 /**
2870   This function is identical to perform QuickSort,
2871   except that is uses the pre-allocated buffer so the in place sorting does not need to
2872   allocate and free buffers constantly.
2873
2874   Each element must be equal sized.
2875
2876   if BufferToSort is NULL, then ASSERT.
2877   if CompareFunction is NULL, then ASSERT.
2878   if BufferOneElement is NULL, then ASSERT.
2879   if ElementSize is < 1, then ASSERT.
2880
2881   if Count is < 2 then perform no action.
2882
2883   @param[in, out] BufferToSort   on call a Buffer of (possibly sorted) elements
2884                                  on return a buffer of sorted elements
2885   @param[in] Count               the number of elements in the buffer to sort
2886   @param[in] ElementSize         Size of an element in bytes
2887   @param[in] CompareFunction     The function to call to perform the comparison
2888                                  of any 2 elements
2889   @param[out] BufferOneElement   Caller provided buffer whose size equals to ElementSize.
2890                                  It's used by QuickSort() for swapping in sorting.
2891 **/
2892 VOID
2893 EFIAPI
2894 QuickSort (
2895   IN OUT VOID                 *BufferToSort,
2896   IN CONST UINTN              Count,
2897   IN CONST UINTN              ElementSize,
2898   IN       BASE_SORT_COMPARE  CompareFunction,
2899   OUT VOID                    *BufferOneElement
2900   );
2901
2902 /**
2903   Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
2904   with zeros. The shifted value is returned.
2905
2906   This function shifts the 64-bit value Operand to the left by Count bits. The
2907   low Count bits are set to zero. The shifted value is returned.
2908
2909   If Count is greater than 63, then ASSERT().
2910
2911   @param  Operand The 64-bit operand to shift left.
2912   @param  Count   The number of bits to shift left.
2913
2914   @return Operand << Count.
2915
2916 **/
2917 UINT64
2918 EFIAPI
2919 LShiftU64 (
2920   IN      UINT64  Operand,
2921   IN      UINTN   Count
2922   );
2923
2924 /**
2925   Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
2926   filled with zeros. The shifted value is returned.
2927
2928   This function shifts the 64-bit value Operand to the right by Count bits. The
2929   high Count bits are set to zero. The shifted value is returned.
2930
2931   If Count is greater than 63, then ASSERT().
2932
2933   @param  Operand The 64-bit operand to shift right.
2934   @param  Count   The number of bits to shift right.
2935
2936   @return Operand >> Count
2937
2938 **/
2939 UINT64
2940 EFIAPI
2941 RShiftU64 (
2942   IN      UINT64  Operand,
2943   IN      UINTN   Count
2944   );
2945
2946 /**
2947   Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
2948   with original integer's bit 63. The shifted value is returned.
2949
2950   This function shifts the 64-bit value Operand to the right by Count bits. The
2951   high Count bits are set to bit 63 of Operand.  The shifted value is returned.
2952
2953   If Count is greater than 63, then ASSERT().
2954
2955   @param  Operand The 64-bit operand to shift right.
2956   @param  Count   The number of bits to shift right.
2957
2958   @return Operand >> Count
2959
2960 **/
2961 UINT64
2962 EFIAPI
2963 ARShiftU64 (
2964   IN      UINT64  Operand,
2965   IN      UINTN   Count
2966   );
2967
2968 /**
2969   Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
2970   with the high bits that were rotated.
2971
2972   This function rotates the 32-bit value Operand to the left by Count bits. The
2973   low Count bits are fill with the high Count bits of Operand. The rotated
2974   value is returned.
2975
2976   If Count is greater than 31, then ASSERT().
2977
2978   @param  Operand The 32-bit operand to rotate left.
2979   @param  Count   The number of bits to rotate left.
2980
2981   @return Operand << Count
2982
2983 **/
2984 UINT32
2985 EFIAPI
2986 LRotU32 (
2987   IN      UINT32  Operand,
2988   IN      UINTN   Count
2989   );
2990
2991 /**
2992   Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
2993   with the low bits that were rotated.
2994
2995   This function rotates the 32-bit value Operand to the right by Count bits.
2996   The high Count bits are fill with the low Count bits of Operand. The rotated
2997   value is returned.
2998
2999   If Count is greater than 31, then ASSERT().
3000
3001   @param  Operand The 32-bit operand to rotate right.
3002   @param  Count   The number of bits to rotate right.
3003
3004   @return Operand >> Count
3005
3006 **/
3007 UINT32
3008 EFIAPI
3009 RRotU32 (
3010   IN      UINT32  Operand,
3011   IN      UINTN   Count
3012   );
3013
3014 /**
3015   Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
3016   with the high bits that were rotated.
3017
3018   This function rotates the 64-bit value Operand to the left by Count bits. The
3019   low Count bits are fill with the high Count bits of Operand. The rotated
3020   value is returned.
3021
3022   If Count is greater than 63, then ASSERT().
3023
3024   @param  Operand The 64-bit operand to rotate left.
3025   @param  Count   The number of bits to rotate left.
3026
3027   @return Operand << Count
3028
3029 **/
3030 UINT64
3031 EFIAPI
3032 LRotU64 (
3033   IN      UINT64  Operand,
3034   IN      UINTN   Count
3035   );
3036
3037 /**
3038   Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
3039   with the high low bits that were rotated.
3040
3041   This function rotates the 64-bit value Operand to the right by Count bits.
3042   The high Count bits are fill with the low Count bits of Operand. The rotated
3043   value is returned.
3044
3045   If Count is greater than 63, then ASSERT().
3046
3047   @param  Operand The 64-bit operand to rotate right.
3048   @param  Count   The number of bits to rotate right.
3049
3050   @return Operand >> Count
3051
3052 **/
3053 UINT64
3054 EFIAPI
3055 RRotU64 (
3056   IN      UINT64  Operand,
3057   IN      UINTN   Count
3058   );
3059
3060 /**
3061   Returns the bit position of the lowest bit set in a 32-bit value.
3062
3063   This function computes the bit position of the lowest bit set in the 32-bit
3064   value specified by Operand. If Operand is zero, then -1 is returned.
3065   Otherwise, a value between 0 and 31 is returned.
3066
3067   @param  Operand The 32-bit operand to evaluate.
3068
3069   @retval 0..31  The lowest bit set in Operand was found.
3070   @retval -1    Operand is zero.
3071
3072 **/
3073 INTN
3074 EFIAPI
3075 LowBitSet32 (
3076   IN      UINT32  Operand
3077   );
3078
3079 /**
3080   Returns the bit position of the lowest bit set in a 64-bit value.
3081
3082   This function computes the bit position of the lowest bit set in the 64-bit
3083   value specified by Operand. If Operand is zero, then -1 is returned.
3084   Otherwise, a value between 0 and 63 is returned.
3085
3086   @param  Operand The 64-bit operand to evaluate.
3087
3088   @retval 0..63  The lowest bit set in Operand was found.
3089   @retval -1    Operand is zero.
3090
3091
3092 **/
3093 INTN
3094 EFIAPI
3095 LowBitSet64 (
3096   IN      UINT64  Operand
3097   );
3098
3099 /**
3100   Returns the bit position of the highest bit set in a 32-bit value. Equivalent
3101   to log2(x).
3102
3103   This function computes the bit position of the highest bit set in the 32-bit
3104   value specified by Operand. If Operand is zero, then -1 is returned.
3105   Otherwise, a value between 0 and 31 is returned.
3106
3107   @param  Operand The 32-bit operand to evaluate.
3108
3109   @retval 0..31  Position of the highest bit set in Operand if found.
3110   @retval -1    Operand is zero.
3111
3112 **/
3113 INTN
3114 EFIAPI
3115 HighBitSet32 (
3116   IN      UINT32  Operand
3117   );
3118
3119 /**
3120   Returns the bit position of the highest bit set in a 64-bit value. Equivalent
3121   to log2(x).
3122
3123   This function computes the bit position of the highest bit set in the 64-bit
3124   value specified by Operand. If Operand is zero, then -1 is returned.
3125   Otherwise, a value between 0 and 63 is returned.
3126
3127   @param  Operand The 64-bit operand to evaluate.
3128
3129   @retval 0..63   Position of the highest bit set in Operand if found.
3130   @retval -1     Operand is zero.
3131
3132 **/
3133 INTN
3134 EFIAPI
3135 HighBitSet64 (
3136   IN      UINT64  Operand
3137   );
3138
3139 /**
3140   Returns the value of the highest bit set in a 32-bit value. Equivalent to
3141   1 << log2(x).
3142
3143   This function computes the value of the highest bit set in the 32-bit value
3144   specified by Operand. If Operand is zero, then zero is returned.
3145
3146   @param  Operand The 32-bit operand to evaluate.
3147
3148   @return 1 << HighBitSet32(Operand)
3149   @retval 0 Operand is zero.
3150
3151 **/
3152 UINT32
3153 EFIAPI
3154 GetPowerOfTwo32 (
3155   IN      UINT32  Operand
3156   );
3157
3158 /**
3159   Returns the value of the highest bit set in a 64-bit value. Equivalent to
3160   1 << log2(x).
3161
3162   This function computes the value of the highest bit set in the 64-bit value
3163   specified by Operand. If Operand is zero, then zero is returned.
3164
3165   @param  Operand The 64-bit operand to evaluate.
3166
3167   @return 1 << HighBitSet64(Operand)
3168   @retval 0 Operand is zero.
3169
3170 **/
3171 UINT64
3172 EFIAPI
3173 GetPowerOfTwo64 (
3174   IN      UINT64  Operand
3175   );
3176
3177 /**
3178   Switches the endianness of a 16-bit integer.
3179
3180   This function swaps the bytes in a 16-bit unsigned value to switch the value
3181   from little endian to big endian or vice versa. The byte swapped value is
3182   returned.
3183
3184   @param  Value A 16-bit unsigned value.
3185
3186   @return The byte swapped Value.
3187
3188 **/
3189 UINT16
3190 EFIAPI
3191 SwapBytes16 (
3192   IN      UINT16  Value
3193   );
3194
3195 /**
3196   Switches the endianness of a 32-bit integer.
3197
3198   This function swaps the bytes in a 32-bit unsigned value to switch the value
3199   from little endian to big endian or vice versa. The byte swapped value is
3200   returned.
3201
3202   @param  Value A 32-bit unsigned value.
3203
3204   @return The byte swapped Value.
3205
3206 **/
3207 UINT32
3208 EFIAPI
3209 SwapBytes32 (
3210   IN      UINT32  Value
3211   );
3212
3213 /**
3214   Switches the endianness of a 64-bit integer.
3215
3216   This function swaps the bytes in a 64-bit unsigned value to switch the value
3217   from little endian to big endian or vice versa. The byte swapped value is
3218   returned.
3219
3220   @param  Value A 64-bit unsigned value.
3221
3222   @return The byte swapped Value.
3223
3224 **/
3225 UINT64
3226 EFIAPI
3227 SwapBytes64 (
3228   IN      UINT64  Value
3229   );
3230
3231 /**
3232   Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
3233   generates a 64-bit unsigned result.
3234
3235   This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
3236   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3237   bit unsigned result is returned.
3238
3239   @param  Multiplicand  A 64-bit unsigned value.
3240   @param  Multiplier    A 32-bit unsigned value.
3241
3242   @return Multiplicand * Multiplier
3243
3244 **/
3245 UINT64
3246 EFIAPI
3247 MultU64x32 (
3248   IN      UINT64  Multiplicand,
3249   IN      UINT32  Multiplier
3250   );
3251
3252 /**
3253   Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3254   generates a 64-bit unsigned result.
3255
3256   This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3257   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3258   bit unsigned result is returned.
3259
3260   @param  Multiplicand  A 64-bit unsigned value.
3261   @param  Multiplier    A 64-bit unsigned value.
3262
3263   @return Multiplicand * Multiplier.
3264
3265 **/
3266 UINT64
3267 EFIAPI
3268 MultU64x64 (
3269   IN      UINT64  Multiplicand,
3270   IN      UINT64  Multiplier
3271   );
3272
3273 /**
3274   Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3275   64-bit signed result.
3276
3277   This function multiples the 64-bit signed value Multiplicand by the 64-bit
3278   signed value Multiplier and generates a 64-bit signed result. This 64-bit
3279   signed result is returned.
3280
3281   @param  Multiplicand  A 64-bit signed value.
3282   @param  Multiplier    A 64-bit signed value.
3283
3284   @return Multiplicand * Multiplier
3285
3286 **/
3287 INT64
3288 EFIAPI
3289 MultS64x64 (
3290   IN      INT64  Multiplicand,
3291   IN      INT64  Multiplier
3292   );
3293
3294 /**
3295   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3296   a 64-bit unsigned result.
3297
3298   This function divides the 64-bit unsigned value Dividend by the 32-bit
3299   unsigned value Divisor and generates a 64-bit unsigned quotient. This
3300   function returns the 64-bit unsigned quotient.
3301
3302   If Divisor is 0, then ASSERT().
3303
3304   @param  Dividend  A 64-bit unsigned value.
3305   @param  Divisor   A 32-bit unsigned value.
3306
3307   @return Dividend / Divisor.
3308
3309 **/
3310 UINT64
3311 EFIAPI
3312 DivU64x32 (
3313   IN      UINT64  Dividend,
3314   IN      UINT32  Divisor
3315   );
3316
3317 /**
3318   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3319   a 32-bit unsigned remainder.
3320
3321   This function divides the 64-bit unsigned value Dividend by the 32-bit
3322   unsigned value Divisor and generates a 32-bit remainder. This function
3323   returns the 32-bit unsigned remainder.
3324
3325   If Divisor is 0, then ASSERT().
3326
3327   @param  Dividend  A 64-bit unsigned value.
3328   @param  Divisor   A 32-bit unsigned value.
3329
3330   @return Dividend % Divisor.
3331
3332 **/
3333 UINT32
3334 EFIAPI
3335 ModU64x32 (
3336   IN      UINT64  Dividend,
3337   IN      UINT32  Divisor
3338   );
3339
3340 /**
3341   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3342   a 64-bit unsigned result and an optional 32-bit unsigned remainder.
3343
3344   This function divides the 64-bit unsigned value Dividend by the 32-bit
3345   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3346   is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
3347   This function returns the 64-bit unsigned quotient.
3348
3349   If Divisor is 0, then ASSERT().
3350
3351   @param  Dividend  A 64-bit unsigned value.
3352   @param  Divisor   A 32-bit unsigned value.
3353   @param  Remainder A pointer to a 32-bit unsigned value. This parameter is
3354                     optional and may be NULL.
3355
3356   @return Dividend / Divisor.
3357
3358 **/
3359 UINT64
3360 EFIAPI
3361 DivU64x32Remainder (
3362   IN      UINT64  Dividend,
3363   IN      UINT32  Divisor,
3364   OUT     UINT32  *Remainder  OPTIONAL
3365   );
3366
3367 /**
3368   Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
3369   a 64-bit unsigned result and an optional 64-bit unsigned remainder.
3370
3371   This function divides the 64-bit unsigned value Dividend by the 64-bit
3372   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3373   is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
3374   This function returns the 64-bit unsigned quotient.
3375
3376   If Divisor is 0, then ASSERT().
3377
3378   @param  Dividend  A 64-bit unsigned value.
3379   @param  Divisor   A 64-bit unsigned value.
3380   @param  Remainder A pointer to a 64-bit unsigned value. This parameter is
3381                     optional and may be NULL.
3382
3383   @return Dividend / Divisor.
3384
3385 **/
3386 UINT64
3387 EFIAPI
3388 DivU64x64Remainder (
3389   IN      UINT64  Dividend,
3390   IN      UINT64  Divisor,
3391   OUT     UINT64  *Remainder  OPTIONAL
3392   );
3393
3394 /**
3395   Divides a 64-bit signed integer by a 64-bit signed integer and generates a
3396   64-bit signed result and a optional 64-bit signed remainder.
3397
3398   This function divides the 64-bit signed value Dividend by the 64-bit signed
3399   value Divisor and generates a 64-bit signed quotient. If Remainder is not
3400   NULL, then the 64-bit signed remainder is returned in Remainder. This
3401   function returns the 64-bit signed quotient.
3402
3403   It is the caller's responsibility to not call this function with a Divisor of 0.
3404   If Divisor is 0, then the quotient and remainder should be assumed to be
3405   the largest negative integer.
3406
3407   If Divisor is 0, then ASSERT().
3408
3409   @param  Dividend  A 64-bit signed value.
3410   @param  Divisor   A 64-bit signed value.
3411   @param  Remainder A pointer to a 64-bit signed value. This parameter is
3412                     optional and may be NULL.
3413
3414   @return Dividend / Divisor.
3415
3416 **/
3417 INT64
3418 EFIAPI
3419 DivS64x64Remainder (
3420   IN      INT64  Dividend,
3421   IN      INT64  Divisor,
3422   OUT     INT64  *Remainder  OPTIONAL
3423   );
3424
3425 /**
3426   Reads a 16-bit value from memory that may be unaligned.
3427
3428   This function returns the 16-bit value pointed to by Buffer. The function
3429   guarantees that the read operation does not produce an alignment fault.
3430
3431   If the Buffer is NULL, then ASSERT().
3432
3433   @param  Buffer  The pointer to a 16-bit value that may be unaligned.
3434
3435   @return The 16-bit value read from Buffer.
3436
3437 **/
3438 UINT16
3439 EFIAPI
3440 ReadUnaligned16 (
3441   IN CONST UINT16  *Buffer
3442   );
3443
3444 /**
3445   Writes a 16-bit value to memory that may be unaligned.
3446
3447   This function writes the 16-bit value specified by Value to Buffer. Value is
3448   returned. The function guarantees that the write operation does not produce
3449   an alignment fault.
3450
3451   If the Buffer is NULL, then ASSERT().
3452
3453   @param  Buffer  The pointer to a 16-bit value that may be unaligned.
3454   @param  Value   16-bit value to write to Buffer.
3455
3456   @return The 16-bit value to write to Buffer.
3457
3458 **/
3459 UINT16
3460 EFIAPI
3461 WriteUnaligned16 (
3462   OUT UINT16  *Buffer,
3463   IN  UINT16  Value
3464   );
3465
3466 /**
3467   Reads a 24-bit value from memory that may be unaligned.
3468
3469   This function returns the 24-bit value pointed to by Buffer. The function
3470   guarantees that the read operation does not produce an alignment fault.
3471
3472   If the Buffer is NULL, then ASSERT().
3473
3474   @param  Buffer  The pointer to a 24-bit value that may be unaligned.
3475
3476   @return The 24-bit value read from Buffer.
3477
3478 **/
3479 UINT32
3480 EFIAPI
3481 ReadUnaligned24 (
3482   IN CONST UINT32  *Buffer
3483   );
3484
3485 /**
3486   Writes a 24-bit value to memory that may be unaligned.
3487
3488   This function writes the 24-bit value specified by Value to Buffer. Value is
3489   returned. The function guarantees that the write operation does not produce
3490   an alignment fault.
3491
3492   If the Buffer is NULL, then ASSERT().
3493
3494   @param  Buffer  The pointer to a 24-bit value that may be unaligned.
3495   @param  Value   24-bit value to write to Buffer.
3496
3497   @return The 24-bit value to write to Buffer.
3498
3499 **/
3500 UINT32
3501 EFIAPI
3502 WriteUnaligned24 (
3503   OUT UINT32  *Buffer,
3504   IN  UINT32  Value
3505   );
3506
3507 /**
3508   Reads a 32-bit value from memory that may be unaligned.
3509
3510   This function returns the 32-bit value pointed to by Buffer. The function
3511   guarantees that the read operation does not produce an alignment fault.
3512
3513   If the Buffer is NULL, then ASSERT().
3514
3515   @param  Buffer  The pointer to a 32-bit value that may be unaligned.
3516
3517   @return The 32-bit value read from Buffer.
3518
3519 **/
3520 UINT32
3521 EFIAPI
3522 ReadUnaligned32 (
3523   IN CONST UINT32  *Buffer
3524   );
3525
3526 /**
3527   Writes a 32-bit value to memory that may be unaligned.
3528
3529   This function writes the 32-bit value specified by Value to Buffer. Value is
3530   returned. The function guarantees that the write operation does not produce
3531   an alignment fault.
3532
3533   If the Buffer is NULL, then ASSERT().
3534
3535   @param  Buffer  The pointer to a 32-bit value that may be unaligned.
3536   @param  Value   32-bit value to write to Buffer.
3537
3538   @return The 32-bit value to write to Buffer.
3539
3540 **/
3541 UINT32
3542 EFIAPI
3543 WriteUnaligned32 (
3544   OUT UINT32  *Buffer,
3545   IN  UINT32  Value
3546   );
3547
3548 /**
3549   Reads a 64-bit value from memory that may be unaligned.
3550
3551   This function returns the 64-bit value pointed to by Buffer. The function
3552   guarantees that the read operation does not produce an alignment fault.
3553
3554   If the Buffer is NULL, then ASSERT().
3555
3556   @param  Buffer  The pointer to a 64-bit value that may be unaligned.
3557
3558   @return The 64-bit value read from Buffer.
3559
3560 **/
3561 UINT64
3562 EFIAPI
3563 ReadUnaligned64 (
3564   IN CONST UINT64  *Buffer
3565   );
3566
3567 /**
3568   Writes a 64-bit value to memory that may be unaligned.
3569
3570   This function writes the 64-bit value specified by Value to Buffer. Value is
3571   returned. The function guarantees that the write operation does not produce
3572   an alignment fault.
3573
3574   If the Buffer is NULL, then ASSERT().
3575
3576   @param  Buffer  The pointer to a 64-bit value that may be unaligned.
3577   @param  Value   64-bit value to write to Buffer.
3578
3579   @return The 64-bit value to write to Buffer.
3580
3581 **/
3582 UINT64
3583 EFIAPI
3584 WriteUnaligned64 (
3585   OUT UINT64  *Buffer,
3586   IN  UINT64  Value
3587   );
3588
3589 //
3590 // Bit Field Functions
3591 //
3592
3593 /**
3594   Returns a bit field from an 8-bit value.
3595
3596   Returns the bitfield specified by the StartBit and the EndBit from Operand.
3597
3598   If 8-bit operations are not supported, then ASSERT().
3599   If StartBit is greater than 7, then ASSERT().
3600   If EndBit is greater than 7, then ASSERT().
3601   If EndBit is less than StartBit, then ASSERT().
3602
3603   @param  Operand   Operand on which to perform the bitfield operation.
3604   @param  StartBit  The ordinal of the least significant bit in the bit field.
3605                     Range 0..7.
3606   @param  EndBit    The ordinal of the most significant bit in the bit field.
3607                     Range 0..7.
3608
3609   @return The bit field read.
3610
3611 **/
3612 UINT8
3613 EFIAPI
3614 BitFieldRead8 (
3615   IN      UINT8  Operand,
3616   IN      UINTN  StartBit,
3617   IN      UINTN  EndBit
3618   );
3619
3620 /**
3621   Writes a bit field to an 8-bit value, and returns the result.
3622
3623   Writes Value to the bit field specified by the StartBit and the EndBit in
3624   Operand. All other bits in Operand are preserved. The new 8-bit value is
3625   returned.
3626
3627   If 8-bit operations are not supported, then ASSERT().
3628   If StartBit is greater than 7, then ASSERT().
3629   If EndBit is greater than 7, then ASSERT().
3630   If EndBit is less than StartBit, then ASSERT().
3631   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3632
3633   @param  Operand   Operand on which to perform the bitfield operation.
3634   @param  StartBit  The ordinal of the least significant bit in the bit field.
3635                     Range 0..7.
3636   @param  EndBit    The ordinal of the most significant bit in the bit field.
3637                     Range 0..7.
3638   @param  Value     New value of the bit field.
3639
3640   @return The new 8-bit value.
3641
3642 **/
3643 UINT8
3644 EFIAPI
3645 BitFieldWrite8 (
3646   IN      UINT8  Operand,
3647   IN      UINTN  StartBit,
3648   IN      UINTN  EndBit,
3649   IN      UINT8  Value
3650   );
3651
3652 /**
3653   Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
3654   result.
3655
3656   Performs a bitwise OR between the bit field specified by StartBit
3657   and EndBit in Operand and the value specified by OrData. All other bits in
3658   Operand are preserved. The new 8-bit value is returned.
3659
3660   If 8-bit operations are not supported, then ASSERT().
3661   If StartBit is greater than 7, then ASSERT().
3662   If EndBit is greater than 7, then ASSERT().
3663   If EndBit is less than StartBit, then ASSERT().
3664   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3665
3666   @param  Operand   Operand on which to perform the bitfield operation.
3667   @param  StartBit  The ordinal of the least significant bit in the bit field.
3668                     Range 0..7.
3669   @param  EndBit    The ordinal of the most significant bit in the bit field.
3670                     Range 0..7.
3671   @param  OrData    The value to OR with the read value from the value
3672
3673   @return The new 8-bit value.
3674
3675 **/
3676 UINT8
3677 EFIAPI
3678 BitFieldOr8 (
3679   IN      UINT8  Operand,
3680   IN      UINTN  StartBit,
3681   IN      UINTN  EndBit,
3682   IN      UINT8  OrData
3683   );
3684
3685 /**
3686   Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
3687   the result.
3688
3689   Performs a bitwise AND between the bit field specified by StartBit and EndBit
3690   in Operand and the value specified by AndData. All other bits in Operand are
3691   preserved. The new 8-bit value is returned.
3692
3693   If 8-bit operations are not supported, then ASSERT().
3694   If StartBit is greater than 7, then ASSERT().
3695   If EndBit is greater than 7, then ASSERT().
3696   If EndBit is less than StartBit, then ASSERT().
3697   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3698
3699   @param  Operand   Operand on which to perform the bitfield operation.
3700   @param  StartBit  The ordinal of the least significant bit in the bit field.
3701                     Range 0..7.
3702   @param  EndBit    The ordinal of the most significant bit in the bit field.
3703                     Range 0..7.
3704   @param  AndData   The value to AND with the read value from the value.
3705
3706   @return The new 8-bit value.
3707
3708 **/
3709 UINT8
3710 EFIAPI
3711 BitFieldAnd8 (
3712   IN      UINT8  Operand,
3713   IN      UINTN  StartBit,
3714   IN      UINTN  EndBit,
3715   IN      UINT8  AndData
3716   );
3717
3718 /**
3719   Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
3720   bitwise OR, and returns the result.
3721
3722   Performs a bitwise AND between the bit field specified by StartBit and EndBit
3723   in Operand and the value specified by AndData, followed by a bitwise
3724   OR with value specified by OrData. All other bits in Operand are
3725   preserved. The new 8-bit value is returned.
3726
3727   If 8-bit operations are not supported, then ASSERT().
3728   If StartBit is greater than 7, then ASSERT().
3729   If EndBit is greater than 7, then ASSERT().
3730   If EndBit is less than StartBit, then ASSERT().
3731   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3732   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3733
3734   @param  Operand   Operand on which to perform the bitfield operation.
3735   @param  StartBit  The ordinal of the least significant bit in the bit field.
3736                     Range 0..7.
3737   @param  EndBit    The ordinal of the most significant bit in the bit field.
3738                     Range 0..7.
3739   @param  AndData   The value to AND with the read value from the value.
3740   @param  OrData    The value to OR with the result of the AND operation.
3741
3742   @return The new 8-bit value.
3743
3744 **/
3745 UINT8
3746 EFIAPI
3747 BitFieldAndThenOr8 (
3748   IN      UINT8  Operand,
3749   IN      UINTN  StartBit,
3750   IN      UINTN  EndBit,
3751   IN      UINT8  AndData,
3752   IN      UINT8  OrData
3753   );
3754
3755 /**
3756   Returns a bit field from a 16-bit value.
3757
3758   Returns the bitfield specified by the StartBit and the EndBit from Operand.
3759
3760   If 16-bit operations are not supported, then ASSERT().
3761   If StartBit is greater than 15, then ASSERT().
3762   If EndBit is greater than 15, then ASSERT().
3763   If EndBit is less than StartBit, then ASSERT().
3764
3765   @param  Operand   Operand on which to perform the bitfield operation.
3766   @param  StartBit  The ordinal of the least significant bit in the bit field.
3767                     Range 0..15.
3768   @param  EndBit    The ordinal of the most significant bit in the bit field.
3769                     Range 0..15.
3770
3771   @return The bit field read.
3772
3773 **/
3774 UINT16
3775 EFIAPI
3776 BitFieldRead16 (
3777   IN      UINT16  Operand,
3778   IN      UINTN   StartBit,
3779   IN      UINTN   EndBit
3780   );
3781
3782 /**
3783   Writes a bit field to a 16-bit value, and returns the result.
3784
3785   Writes Value to the bit field specified by the StartBit and the EndBit in
3786   Operand. All other bits in Operand are preserved. The new 16-bit value is
3787   returned.
3788
3789   If 16-bit operations are not supported, then ASSERT().
3790   If StartBit is greater than 15, then ASSERT().
3791   If EndBit is greater than 15, then ASSERT().
3792   If EndBit is less than StartBit, then ASSERT().
3793   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3794
3795   @param  Operand   Operand on which to perform the bitfield operation.
3796   @param  StartBit  The ordinal of the least significant bit in the bit field.
3797                     Range 0..15.
3798   @param  EndBit    The ordinal of the most significant bit in the bit field.
3799                     Range 0..15.
3800   @param  Value     New value of the bit field.
3801
3802   @return The new 16-bit value.
3803
3804 **/
3805 UINT16
3806 EFIAPI
3807 BitFieldWrite16 (
3808   IN      UINT16  Operand,
3809   IN      UINTN   StartBit,
3810   IN      UINTN   EndBit,
3811   IN      UINT16  Value
3812   );
3813
3814 /**
3815   Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
3816   result.
3817
3818   Performs a bitwise OR between the bit field specified by StartBit
3819   and EndBit in Operand and the value specified by OrData. All other bits in
3820   Operand are preserved. The new 16-bit value is returned.
3821
3822   If 16-bit operations are not supported, then ASSERT().
3823   If StartBit is greater than 15, then ASSERT().
3824   If EndBit is greater than 15, then ASSERT().
3825   If EndBit is less than StartBit, then ASSERT().
3826   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3827
3828   @param  Operand   Operand on which to perform the bitfield operation.
3829   @param  StartBit  The ordinal of the least significant bit in the bit field.
3830                     Range 0..15.
3831   @param  EndBit    The ordinal of the most significant bit in the bit field.
3832                     Range 0..15.
3833   @param  OrData    The value to OR with the read value from the value
3834
3835   @return The new 16-bit value.
3836
3837 **/
3838 UINT16
3839 EFIAPI
3840 BitFieldOr16 (
3841   IN      UINT16  Operand,
3842   IN      UINTN   StartBit,
3843   IN      UINTN   EndBit,
3844   IN      UINT16  OrData
3845   );
3846
3847 /**
3848   Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
3849   the result.
3850
3851   Performs a bitwise AND between the bit field specified by StartBit and EndBit
3852   in Operand and the value specified by AndData. All other bits in Operand are
3853   preserved. The new 16-bit value is returned.
3854
3855   If 16-bit operations are not supported, then ASSERT().
3856   If StartBit is greater than 15, then ASSERT().
3857   If EndBit is greater than 15, then ASSERT().
3858   If EndBit is less than StartBit, then ASSERT().
3859   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3860
3861   @param  Operand   Operand on which to perform the bitfield operation.
3862   @param  StartBit  The ordinal of the least significant bit in the bit field.
3863                     Range 0..15.
3864   @param  EndBit    The ordinal of the most significant bit in the bit field.
3865                     Range 0..15.
3866   @param  AndData   The value to AND with the read value from the value
3867
3868   @return The new 16-bit value.
3869
3870 **/
3871 UINT16
3872 EFIAPI
3873 BitFieldAnd16 (
3874   IN      UINT16  Operand,
3875   IN      UINTN   StartBit,
3876   IN      UINTN   EndBit,
3877   IN      UINT16  AndData
3878   );
3879
3880 /**
3881   Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
3882   bitwise OR, and returns the result.
3883
3884   Performs a bitwise AND between the bit field specified by StartBit and EndBit
3885   in Operand and the value specified by AndData, followed by a bitwise
3886   OR with value specified by OrData. All other bits in Operand are
3887   preserved. The new 16-bit value is returned.
3888
3889   If 16-bit operations are not supported, then ASSERT().
3890   If StartBit is greater than 15, then ASSERT().
3891   If EndBit is greater than 15, then ASSERT().
3892   If EndBit is less than StartBit, then ASSERT().
3893   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3894   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3895
3896   @param  Operand   Operand on which to perform the bitfield operation.
3897   @param  StartBit  The ordinal of the least significant bit in the bit field.
3898                     Range 0..15.
3899   @param  EndBit    The ordinal of the most significant bit in the bit field.
3900                     Range 0..15.
3901   @param  AndData   The value to AND with the read value from the value.
3902   @param  OrData    The value to OR with the result of the AND operation.
3903
3904   @return The new 16-bit value.
3905
3906 **/
3907 UINT16
3908 EFIAPI
3909 BitFieldAndThenOr16 (
3910   IN      UINT16  Operand,
3911   IN      UINTN   StartBit,
3912   IN      UINTN   EndBit,
3913   IN      UINT16  AndData,
3914   IN      UINT16  OrData
3915   );
3916
3917 /**
3918   Returns a bit field from a 32-bit value.
3919
3920   Returns the bitfield specified by the StartBit and the EndBit from Operand.
3921
3922   If 32-bit operations are not supported, then ASSERT().
3923   If StartBit is greater than 31, then ASSERT().
3924   If EndBit is greater than 31, then ASSERT().
3925   If EndBit is less than StartBit, then ASSERT().
3926
3927   @param  Operand   Operand on which to perform the bitfield operation.
3928   @param  StartBit  The ordinal of the least significant bit in the bit field.
3929                     Range 0..31.
3930   @param  EndBit    The ordinal of the most significant bit in the bit field.
3931                     Range 0..31.
3932
3933   @return The bit field read.
3934
3935 **/
3936 UINT32
3937 EFIAPI
3938 BitFieldRead32 (
3939   IN      UINT32  Operand,
3940   IN      UINTN   StartBit,
3941   IN      UINTN   EndBit
3942   );
3943
3944 /**
3945   Writes a bit field to a 32-bit value, and returns the result.
3946
3947   Writes Value to the bit field specified by the StartBit and the EndBit in
3948   Operand. All other bits in Operand are preserved. The new 32-bit value is
3949   returned.
3950
3951   If 32-bit operations are not supported, then ASSERT().
3952   If StartBit is greater than 31, then ASSERT().
3953   If EndBit is greater than 31, then ASSERT().
3954   If EndBit is less than StartBit, then ASSERT().
3955   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3956
3957   @param  Operand   Operand on which to perform the bitfield operation.
3958   @param  StartBit  The ordinal of the least significant bit in the bit field.
3959                     Range 0..31.
3960   @param  EndBit    The ordinal of the most significant bit in the bit field.
3961                     Range 0..31.
3962   @param  Value     New value of the bit field.
3963
3964   @return The new 32-bit value.
3965
3966 **/
3967 UINT32
3968 EFIAPI
3969 BitFieldWrite32 (
3970   IN      UINT32  Operand,
3971   IN      UINTN   StartBit,
3972   IN      UINTN   EndBit,
3973   IN      UINT32  Value
3974   );
3975
3976 /**
3977   Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
3978   result.
3979
3980   Performs a bitwise OR between the bit field specified by StartBit
3981   and EndBit in Operand and the value specified by OrData. All other bits in
3982   Operand are preserved. The new 32-bit value is returned.
3983
3984   If 32-bit operations are not supported, then ASSERT().
3985   If StartBit is greater than 31, then ASSERT().
3986   If EndBit is greater than 31, then ASSERT().
3987   If EndBit is less than StartBit, then ASSERT().
3988   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3989
3990   @param  Operand   Operand on which to perform the bitfield operation.
3991   @param  StartBit  The ordinal of the least significant bit in the bit field.
3992                     Range 0..31.
3993   @param  EndBit    The ordinal of the most significant bit in the bit field.
3994                     Range 0..31.
3995   @param  OrData    The value to OR with the read value from the value.
3996
3997   @return The new 32-bit value.
3998
3999 **/
4000 UINT32
4001 EFIAPI
4002 BitFieldOr32 (
4003   IN      UINT32  Operand,
4004   IN      UINTN   StartBit,
4005   IN      UINTN   EndBit,
4006   IN      UINT32  OrData
4007   );
4008
4009 /**
4010   Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
4011   the result.
4012
4013   Performs a bitwise AND between the bit field specified by StartBit and EndBit
4014   in Operand and the value specified by AndData. All other bits in Operand are
4015   preserved. The new 32-bit value is returned.
4016
4017   If 32-bit operations are not supported, then ASSERT().
4018   If StartBit is greater than 31, then ASSERT().
4019   If EndBit is greater than 31, then ASSERT().
4020   If EndBit is less than StartBit, then ASSERT().
4021   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4022
4023   @param  Operand   Operand on which to perform the bitfield operation.
4024   @param  StartBit  The ordinal of the least significant bit in the bit field.
4025                     Range 0..31.
4026   @param  EndBit    The ordinal of the most significant bit in the bit field.
4027                     Range 0..31.
4028   @param  AndData   The value to AND with the read value from the value
4029
4030   @return The new 32-bit value.
4031
4032 **/
4033 UINT32
4034 EFIAPI
4035 BitFieldAnd32 (
4036   IN      UINT32  Operand,
4037   IN      UINTN   StartBit,
4038   IN      UINTN   EndBit,
4039   IN      UINT32  AndData
4040   );
4041
4042 /**
4043   Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
4044   bitwise OR, and returns the result.
4045
4046   Performs a bitwise AND between the bit field specified by StartBit and EndBit
4047   in Operand and the value specified by AndData, followed by a bitwise
4048   OR with value specified by OrData. All other bits in Operand are
4049   preserved. The new 32-bit value is returned.
4050
4051   If 32-bit operations are not supported, then ASSERT().
4052   If StartBit is greater than 31, then ASSERT().
4053   If EndBit is greater than 31, then ASSERT().
4054   If EndBit is less than StartBit, then ASSERT().
4055   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4056   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4057
4058   @param  Operand   Operand on which to perform the bitfield operation.
4059   @param  StartBit  The ordinal of the least significant bit in the bit field.
4060                     Range 0..31.
4061   @param  EndBit    The ordinal of the most significant bit in the bit field.
4062                     Range 0..31.
4063   @param  AndData   The value to AND with the read value from the value.
4064   @param  OrData    The value to OR with the result of the AND operation.
4065
4066   @return The new 32-bit value.
4067
4068 **/
4069 UINT32
4070 EFIAPI
4071 BitFieldAndThenOr32 (
4072   IN      UINT32  Operand,
4073   IN      UINTN   StartBit,
4074   IN      UINTN   EndBit,
4075   IN      UINT32  AndData,
4076   IN      UINT32  OrData
4077   );
4078
4079 /**
4080   Returns a bit field from a 64-bit value.
4081
4082   Returns the bitfield specified by the StartBit and the EndBit from Operand.
4083
4084   If 64-bit operations are not supported, then ASSERT().
4085   If StartBit is greater than 63, then ASSERT().
4086   If EndBit is greater than 63, then ASSERT().
4087   If EndBit is less than StartBit, then ASSERT().
4088
4089   @param  Operand   Operand on which to perform the bitfield operation.
4090   @param  StartBit  The ordinal of the least significant bit in the bit field.
4091                     Range 0..63.
4092   @param  EndBit    The ordinal of the most significant bit in the bit field.
4093                     Range 0..63.
4094
4095   @return The bit field read.
4096
4097 **/
4098 UINT64
4099 EFIAPI
4100 BitFieldRead64 (
4101   IN      UINT64  Operand,
4102   IN      UINTN   StartBit,
4103   IN      UINTN   EndBit
4104   );
4105
4106 /**
4107   Writes a bit field to a 64-bit value, and returns the result.
4108
4109   Writes Value to the bit field specified by the StartBit and the EndBit in
4110   Operand. All other bits in Operand are preserved. The new 64-bit value is
4111   returned.
4112
4113   If 64-bit operations are not supported, then ASSERT().
4114   If StartBit is greater than 63, then ASSERT().
4115   If EndBit is greater than 63, then ASSERT().
4116   If EndBit is less than StartBit, then ASSERT().
4117   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4118
4119   @param  Operand   Operand on which to perform the bitfield operation.
4120   @param  StartBit  The ordinal of the least significant bit in the bit field.
4121                     Range 0..63.
4122   @param  EndBit    The ordinal of the most significant bit in the bit field.
4123                     Range 0..63.
4124   @param  Value     New value of the bit field.
4125
4126   @return The new 64-bit value.
4127
4128 **/
4129 UINT64
4130 EFIAPI
4131 BitFieldWrite64 (
4132   IN      UINT64  Operand,
4133   IN      UINTN   StartBit,
4134   IN      UINTN   EndBit,
4135   IN      UINT64  Value
4136   );
4137
4138 /**
4139   Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
4140   result.
4141
4142   Performs a bitwise OR between the bit field specified by StartBit
4143   and EndBit in Operand and the value specified by OrData. All other bits in
4144   Operand are preserved. The new 64-bit value is returned.
4145
4146   If 64-bit operations are not supported, then ASSERT().
4147   If StartBit is greater than 63, then ASSERT().
4148   If EndBit is greater than 63, then ASSERT().
4149   If EndBit is less than StartBit, then ASSERT().
4150   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4151
4152   @param  Operand   Operand on which to perform the bitfield operation.
4153   @param  StartBit  The ordinal of the least significant bit in the bit field.
4154                     Range 0..63.
4155   @param  EndBit    The ordinal of the most significant bit in the bit field.
4156                     Range 0..63.
4157   @param  OrData    The value to OR with the read value from the value
4158
4159   @return The new 64-bit value.
4160
4161 **/
4162 UINT64
4163 EFIAPI
4164 BitFieldOr64 (
4165   IN      UINT64  Operand,
4166   IN      UINTN   StartBit,
4167   IN      UINTN   EndBit,
4168   IN      UINT64  OrData
4169   );
4170
4171 /**
4172   Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
4173   the result.
4174
4175   Performs a bitwise AND between the bit field specified by StartBit and EndBit
4176   in Operand and the value specified by AndData. All other bits in Operand are
4177   preserved. The new 64-bit value is returned.
4178
4179   If 64-bit operations are not supported, then ASSERT().
4180   If StartBit is greater than 63, then ASSERT().
4181   If EndBit is greater than 63, then ASSERT().
4182   If EndBit is less than StartBit, then ASSERT().
4183   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4184
4185   @param  Operand   Operand on which to perform the bitfield operation.
4186   @param  StartBit  The ordinal of the least significant bit in the bit field.
4187                     Range 0..63.
4188   @param  EndBit    The ordinal of the most significant bit in the bit field.
4189                     Range 0..63.
4190   @param  AndData   The value to AND with the read value from the value
4191
4192   @return The new 64-bit value.
4193
4194 **/
4195 UINT64
4196 EFIAPI
4197 BitFieldAnd64 (
4198   IN      UINT64  Operand,
4199   IN      UINTN   StartBit,
4200   IN      UINTN   EndBit,
4201   IN      UINT64  AndData
4202   );
4203
4204 /**
4205   Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
4206   bitwise OR, and returns the result.
4207
4208   Performs a bitwise AND between the bit field specified by StartBit and EndBit
4209   in Operand and the value specified by AndData, followed by a bitwise
4210   OR with value specified by OrData. All other bits in Operand are
4211   preserved. The new 64-bit value is returned.
4212
4213   If 64-bit operations are not supported, then ASSERT().
4214   If StartBit is greater than 63, then ASSERT().
4215   If EndBit is greater than 63, then ASSERT().
4216   If EndBit is less than StartBit, then ASSERT().
4217   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4218   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4219
4220   @param  Operand   Operand on which to perform the bitfield operation.
4221   @param  StartBit  The ordinal of the least significant bit in the bit field.
4222                     Range 0..63.
4223   @param  EndBit    The ordinal of the most significant bit in the bit field.
4224                     Range 0..63.
4225   @param  AndData   The value to AND with the read value from the value.
4226   @param  OrData    The value to OR with the result of the AND operation.
4227
4228   @return The new 64-bit value.
4229
4230 **/
4231 UINT64
4232 EFIAPI
4233 BitFieldAndThenOr64 (
4234   IN      UINT64  Operand,
4235   IN      UINTN   StartBit,
4236   IN      UINTN   EndBit,
4237   IN      UINT64  AndData,
4238   IN      UINT64  OrData
4239   );
4240
4241 /**
4242   Reads a bit field from a 32-bit value, counts and returns
4243   the number of set bits.
4244
4245   Counts the number of set bits in the  bit field specified by
4246   StartBit and EndBit in Operand. The count is returned.
4247
4248   If StartBit is greater than 31, then ASSERT().
4249   If EndBit is greater than 31, then ASSERT().
4250   If EndBit is less than StartBit, then ASSERT().
4251
4252   @param  Operand   Operand on which to perform the bitfield operation.
4253   @param  StartBit  The ordinal of the least significant bit in the bit field.
4254                     Range 0..31.
4255   @param  EndBit    The ordinal of the most significant bit in the bit field.
4256                     Range 0..31.
4257
4258   @return The number of bits set between StartBit and EndBit.
4259
4260 **/
4261 UINT8
4262 EFIAPI
4263 BitFieldCountOnes32 (
4264   IN       UINT32  Operand,
4265   IN       UINTN   StartBit,
4266   IN       UINTN   EndBit
4267   );
4268
4269 /**
4270    Reads a bit field from a 64-bit value, counts and returns
4271    the number of set bits.
4272
4273    Counts the number of set bits in the  bit field specified by
4274    StartBit and EndBit in Operand. The count is returned.
4275
4276    If StartBit is greater than 63, then ASSERT().
4277    If EndBit is greater than 63, then ASSERT().
4278    If EndBit is less than StartBit, then ASSERT().
4279
4280    @param  Operand   Operand on which to perform the bitfield operation.
4281    @param  StartBit  The ordinal of the least significant bit in the bit field.
4282    Range 0..63.
4283    @param  EndBit    The ordinal of the most significant bit in the bit field.
4284    Range 0..63.
4285
4286    @return The number of bits set between StartBit and EndBit.
4287
4288 **/
4289 UINT8
4290 EFIAPI
4291 BitFieldCountOnes64 (
4292   IN       UINT64  Operand,
4293   IN       UINTN   StartBit,
4294   IN       UINTN   EndBit
4295   );
4296
4297 //
4298 // Base Library Checksum Functions
4299 //
4300
4301 /**
4302   Returns the sum of all elements in a buffer in unit of UINT8.
4303   During calculation, the carry bits are dropped.
4304
4305   This function calculates the sum of all elements in a buffer
4306   in unit of UINT8. The carry bits in result of addition are dropped.
4307   The result is returned as UINT8. If Length is Zero, then Zero is
4308   returned.
4309
4310   If Buffer is NULL, then ASSERT().
4311   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4312
4313   @param  Buffer      The pointer to the buffer to carry out the sum operation.
4314   @param  Length      The size, in bytes, of Buffer.
4315
4316   @return Sum         The sum of Buffer with carry bits dropped during additions.
4317
4318 **/
4319 UINT8
4320 EFIAPI
4321 CalculateSum8 (
4322   IN      CONST UINT8  *Buffer,
4323   IN      UINTN        Length
4324   );
4325
4326 /**
4327   Returns the two's complement checksum of all elements in a buffer
4328   of 8-bit values.
4329
4330   This function first calculates the sum of the 8-bit values in the
4331   buffer specified by Buffer and Length.  The carry bits in the result
4332   of addition are dropped. Then, the two's complement of the sum is
4333   returned.  If Length is 0, then 0 is returned.
4334
4335   If Buffer is NULL, then ASSERT().
4336   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4337
4338   @param  Buffer      The pointer to the buffer to carry out the checksum operation.
4339   @param  Length      The size, in bytes, of Buffer.
4340
4341   @return Checksum    The two's complement checksum of Buffer.
4342
4343 **/
4344 UINT8
4345 EFIAPI
4346 CalculateCheckSum8 (
4347   IN      CONST UINT8  *Buffer,
4348   IN      UINTN        Length
4349   );
4350
4351 /**
4352   Returns the sum of all elements in a buffer of 16-bit values.  During
4353   calculation, the carry bits are dropped.
4354
4355   This function calculates the sum of the 16-bit values in the buffer
4356   specified by Buffer and Length. The carry bits in result of addition are dropped.
4357   The 16-bit result is returned.  If Length is 0, then 0 is returned.
4358
4359   If Buffer is NULL, then ASSERT().
4360   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4361   If Length is not aligned on a 16-bit boundary, then ASSERT().
4362   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4363
4364   @param  Buffer      The pointer to the buffer to carry out the sum operation.
4365   @param  Length      The size, in bytes, of Buffer.
4366
4367   @return Sum         The sum of Buffer with carry bits dropped during additions.
4368
4369 **/
4370 UINT16
4371 EFIAPI
4372 CalculateSum16 (
4373   IN      CONST UINT16  *Buffer,
4374   IN      UINTN         Length
4375   );
4376
4377 /**
4378   Returns the two's complement checksum of all elements in a buffer of
4379   16-bit values.
4380
4381   This function first calculates the sum of the 16-bit values in the buffer
4382   specified by Buffer and Length.  The carry bits in the result of addition
4383   are dropped. Then, the two's complement of the sum is returned.  If Length
4384   is 0, then 0 is returned.
4385
4386   If Buffer is NULL, then ASSERT().
4387   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4388   If Length is not aligned on a 16-bit boundary, then ASSERT().
4389   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4390
4391   @param  Buffer      The pointer to the buffer to carry out the checksum operation.
4392   @param  Length      The size, in bytes, of Buffer.
4393
4394   @return Checksum    The two's complement checksum of Buffer.
4395
4396 **/
4397 UINT16
4398 EFIAPI
4399 CalculateCheckSum16 (
4400   IN      CONST UINT16  *Buffer,
4401   IN      UINTN         Length
4402   );
4403
4404 /**
4405   Returns the sum of all elements in a buffer of 32-bit values. During
4406   calculation, the carry bits are dropped.
4407
4408   This function calculates the sum of the 32-bit values in the buffer
4409   specified by Buffer and Length. The carry bits in result of addition are dropped.
4410   The 32-bit result is returned. If Length is 0, then 0 is returned.
4411
4412   If Buffer is NULL, then ASSERT().
4413   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4414   If Length is not aligned on a 32-bit boundary, then ASSERT().
4415   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4416
4417   @param  Buffer      The pointer to the buffer to carry out the sum operation.
4418   @param  Length      The size, in bytes, of Buffer.
4419
4420   @return Sum         The sum of Buffer with carry bits dropped during additions.
4421
4422 **/
4423 UINT32
4424 EFIAPI
4425 CalculateSum32 (
4426   IN      CONST UINT32  *Buffer,
4427   IN      UINTN         Length
4428   );
4429
4430 /**
4431   Returns the two's complement checksum of all elements in a buffer of
4432   32-bit values.
4433
4434   This function first calculates the sum of the 32-bit values in the buffer
4435   specified by Buffer and Length.  The carry bits in the result of addition
4436   are dropped. Then, the two's complement of the sum is returned.  If Length
4437   is 0, then 0 is returned.
4438
4439   If Buffer is NULL, then ASSERT().
4440   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4441   If Length is not aligned on a 32-bit boundary, then ASSERT().
4442   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4443
4444   @param  Buffer      The pointer to the buffer to carry out the checksum operation.
4445   @param  Length      The size, in bytes, of Buffer.
4446
4447   @return Checksum    The two's complement checksum of Buffer.
4448
4449 **/
4450 UINT32
4451 EFIAPI
4452 CalculateCheckSum32 (
4453   IN      CONST UINT32  *Buffer,
4454   IN      UINTN         Length
4455   );
4456
4457 /**
4458   Returns the sum of all elements in a buffer of 64-bit values.  During
4459   calculation, the carry bits are dropped.
4460
4461   This function calculates the sum of the 64-bit values in the buffer
4462   specified by Buffer and Length. The carry bits in result of addition are dropped.
4463   The 64-bit result is returned.  If Length is 0, then 0 is returned.
4464
4465   If Buffer is NULL, then ASSERT().
4466   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4467   If Length is not aligned on a 64-bit boundary, then ASSERT().
4468   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4469
4470   @param  Buffer      The pointer to the buffer to carry out the sum operation.
4471   @param  Length      The size, in bytes, of Buffer.
4472
4473   @return Sum         The sum of Buffer with carry bits dropped during additions.
4474
4475 **/
4476 UINT64
4477 EFIAPI
4478 CalculateSum64 (
4479   IN      CONST UINT64  *Buffer,
4480   IN      UINTN         Length
4481   );
4482
4483 /**
4484   Returns the two's complement checksum of all elements in a buffer of
4485   64-bit values.
4486
4487   This function first calculates the sum of the 64-bit values in the buffer
4488   specified by Buffer and Length.  The carry bits in the result of addition
4489   are dropped. Then, the two's complement of the sum is returned.  If Length
4490   is 0, then 0 is returned.
4491
4492   If Buffer is NULL, then ASSERT().
4493   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4494   If Length is not aligned on a 64-bit boundary, then ASSERT().
4495   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4496
4497   @param  Buffer      The pointer to the buffer to carry out the checksum operation.
4498   @param  Length      The size, in bytes, of Buffer.
4499
4500   @return Checksum    The two's complement checksum of Buffer.
4501
4502 **/
4503 UINT64
4504 EFIAPI
4505 CalculateCheckSum64 (
4506   IN      CONST UINT64  *Buffer,
4507   IN      UINTN         Length
4508   );
4509
4510 /**
4511   Computes and returns a 32-bit CRC for a data buffer.
4512   CRC32 value bases on ITU-T V.42.
4513
4514   If Buffer is NULL, then ASSERT().
4515   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4516
4517   @param[in]  Buffer       A pointer to the buffer on which the 32-bit CRC is to be computed.
4518   @param[in]  Length       The number of bytes in the buffer Data.
4519
4520   @retval Crc32            The 32-bit CRC was computed for the data buffer.
4521
4522 **/
4523 UINT32
4524 EFIAPI
4525 CalculateCrc32 (
4526   IN  VOID   *Buffer,
4527   IN  UINTN  Length
4528   );
4529
4530 /**
4531    Calculates the CRC16-ANSI checksum of the given buffer.
4532
4533    @param[in]      Buffer        Pointer to the buffer.
4534    @param[in]      Length        Length of the buffer, in bytes.
4535    @param[in]      InitialValue  Initial value of the CRC.
4536
4537    @return The CRC16-ANSI checksum.
4538 **/
4539 UINT16
4540 EFIAPI
4541 CalculateCrc16Ansi (
4542   IN  CONST VOID  *Buffer,
4543   IN  UINTN       Length,
4544   IN  UINT16      InitialValue
4545   );
4546
4547 /**
4548    Calculates the CRC32c checksum of the given buffer.
4549
4550    @param[in]      Buffer        Pointer to the buffer.
4551    @param[in]      Length        Length of the buffer, in bytes.
4552    @param[in]      InitialValue  Initial value of the CRC.
4553
4554    @return The CRC32c checksum.
4555 **/
4556 UINT32
4557 EFIAPI
4558 CalculateCrc32c (
4559   IN CONST VOID  *Buffer,
4560   IN UINTN       Length,
4561   IN UINT32      InitialValue
4562   );
4563
4564 //
4565 // Base Library CPU Functions
4566 //
4567
4568 /**
4569   Function entry point used when a stack switch is requested with SwitchStack()
4570
4571   @param  Context1        Context1 parameter passed into SwitchStack().
4572   @param  Context2        Context2 parameter passed into SwitchStack().
4573 **/
4574 typedef
4575 VOID
4576 (EFIAPI *SWITCH_STACK_ENTRY_POINT)(
4577   IN      VOID                      *Context1   OPTIONAL,
4578   IN      VOID                      *Context2   OPTIONAL
4579   );
4580
4581 /**
4582   Used to serialize load and store operations.
4583
4584   All loads and stores that proceed calls to this function are guaranteed to be
4585   globally visible when this function returns.
4586
4587 **/
4588 VOID
4589 EFIAPI
4590 MemoryFence (
4591   VOID
4592   );
4593
4594 /**
4595   Saves the current CPU context that can be restored with a call to LongJump()
4596   and returns 0.
4597
4598   Saves the current CPU context in the buffer specified by JumpBuffer and
4599   returns 0. The initial call to SetJump() must always return 0. Subsequent
4600   calls to LongJump() cause a non-zero value to be returned by SetJump().
4601
4602   If JumpBuffer is NULL, then ASSERT().
4603   For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4604
4605   NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
4606   The same structure must never be used for more than one CPU architecture context.
4607   For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
4608   SetJump()/LongJump() is not currently supported for the EBC processor type.
4609
4610   @param  JumpBuffer  A pointer to CPU context buffer.
4611
4612   @retval 0 Indicates a return from SetJump().
4613
4614 **/
4615 RETURNS_TWICE
4616 UINTN
4617 EFIAPI
4618 SetJump (
4619   OUT     BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer
4620   );
4621
4622 /**
4623   Restores the CPU context that was saved with SetJump().
4624
4625   Restores the CPU context from the buffer specified by JumpBuffer. This
4626   function never returns to the caller. Instead is resumes execution based on
4627   the state of JumpBuffer.
4628
4629   If JumpBuffer is NULL, then ASSERT().
4630   For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4631   If Value is 0, then ASSERT().
4632
4633   @param  JumpBuffer  A pointer to CPU context buffer.
4634   @param  Value       The value to return when the SetJump() context is
4635                       restored and must be non-zero.
4636
4637 **/
4638 VOID
4639 EFIAPI
4640 LongJump (
4641   IN      BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer,
4642   IN      UINTN                     Value
4643   );
4644
4645 /**
4646   Enables CPU interrupts.
4647
4648 **/
4649 VOID
4650 EFIAPI
4651 EnableInterrupts (
4652   VOID
4653   );
4654
4655 /**
4656   Disables CPU interrupts.
4657
4658 **/
4659 VOID
4660 EFIAPI
4661 DisableInterrupts (
4662   VOID
4663   );
4664
4665 /**
4666   Disables CPU interrupts and returns the interrupt state prior to the disable
4667   operation.
4668
4669   @retval TRUE  CPU interrupts were enabled on entry to this call.
4670   @retval FALSE CPU interrupts were disabled on entry to this call.
4671
4672 **/
4673 BOOLEAN
4674 EFIAPI
4675 SaveAndDisableInterrupts (
4676   VOID
4677   );
4678
4679 /**
4680   Enables CPU interrupts for the smallest window required to capture any
4681   pending interrupts.
4682
4683 **/
4684 VOID
4685 EFIAPI
4686 EnableDisableInterrupts (
4687   VOID
4688   );
4689
4690 /**
4691   Retrieves the current CPU interrupt state.
4692
4693   Returns TRUE if interrupts are currently enabled. Otherwise
4694   returns FALSE.
4695
4696   @retval TRUE  CPU interrupts are enabled.
4697   @retval FALSE CPU interrupts are disabled.
4698
4699 **/
4700 BOOLEAN
4701 EFIAPI
4702 GetInterruptState (
4703   VOID
4704   );
4705
4706 /**
4707   Set the current CPU interrupt state.
4708
4709   Sets the current CPU interrupt state to the state specified by
4710   InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
4711   InterruptState is FALSE, then interrupts are disabled. InterruptState is
4712   returned.
4713
4714   @param  InterruptState  TRUE if interrupts should enabled. FALSE if
4715                           interrupts should be disabled.
4716
4717   @return InterruptState
4718
4719 **/
4720 BOOLEAN
4721 EFIAPI
4722 SetInterruptState (
4723   IN      BOOLEAN  InterruptState
4724   );
4725
4726 /**
4727   Requests CPU to pause for a short period of time.
4728
4729   Requests CPU to pause for a short period of time. Typically used in MP
4730   systems to prevent memory starvation while waiting for a spin lock.
4731
4732 **/
4733 VOID
4734 EFIAPI
4735 CpuPause (
4736   VOID
4737   );
4738
4739 /**
4740   Transfers control to a function starting with a new stack.
4741
4742   Transfers control to the function specified by EntryPoint using the
4743   new stack specified by NewStack and passing in the parameters specified
4744   by Context1 and Context2.  Context1 and Context2 are optional and may
4745   be NULL.  The function EntryPoint must never return.  This function
4746   supports a variable number of arguments following the NewStack parameter.
4747   These additional arguments are ignored on IA-32, x64, and EBC architectures.
4748   Itanium processors expect one additional parameter of type VOID * that specifies
4749   the new backing store pointer.
4750
4751   If EntryPoint is NULL, then ASSERT().
4752   If NewStack is NULL, then ASSERT().
4753
4754   @param  EntryPoint  A pointer to function to call with the new stack.
4755   @param  Context1    A pointer to the context to pass into the EntryPoint
4756                       function.
4757   @param  Context2    A pointer to the context to pass into the EntryPoint
4758                       function.
4759   @param  NewStack    A pointer to the new stack to use for the EntryPoint
4760                       function.
4761   @param  ...         This variable argument list is ignored for IA-32, x64, and
4762                       EBC architectures.  For Itanium processors, this variable
4763                       argument list is expected to contain a single parameter of
4764                       type VOID * that specifies the new backing store pointer.
4765
4766
4767 **/
4768 VOID
4769 EFIAPI
4770 SwitchStack (
4771   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
4772   IN      VOID                      *Context1   OPTIONAL,
4773   IN      VOID                      *Context2   OPTIONAL,
4774   IN      VOID                      *NewStack,
4775   ...
4776   );
4777
4778 /**
4779   Generates a breakpoint on the CPU.
4780
4781   Generates a breakpoint on the CPU. The breakpoint must be implemented such
4782   that code can resume normal execution after the breakpoint.
4783
4784 **/
4785 VOID
4786 EFIAPI
4787 CpuBreakpoint (
4788   VOID
4789   );
4790
4791 /**
4792   Executes an infinite loop.
4793
4794   Forces the CPU to execute an infinite loop. A debugger may be used to skip
4795   past the loop and the code that follows the loop must execute properly. This
4796   implies that the infinite loop must not cause the code that follow it to be
4797   optimized away.
4798
4799 **/
4800 VOID
4801 EFIAPI
4802 CpuDeadLoop (
4803   VOID
4804   );
4805
4806 /**
4807   Uses as a barrier to stop speculative execution.
4808
4809   Ensures that no later instruction will execute speculatively, until all prior
4810   instructions have completed.
4811
4812 **/
4813 VOID
4814 EFIAPI
4815 SpeculationBarrier (
4816   VOID
4817   );
4818
4819 #if defined (MDE_CPU_X64) || defined (MDE_CPU_IA32)
4820
4821 /**
4822   The TDCALL instruction causes a VM exit to the Intel TDX module.  It is
4823   used to call guest-side Intel TDX functions, either local or a TD exit
4824   to the host VMM, as selected by Leaf.
4825
4826   @param[in]      Leaf        Leaf number of TDCALL instruction
4827   @param[in]      Arg1        Arg1
4828   @param[in]      Arg2        Arg2
4829   @param[in]      Arg3        Arg3
4830   @param[in,out]  Results  Returned result of the Leaf function
4831
4832   @return 0               A successful call
4833   @return Other           See individual leaf functions
4834 **/
4835 UINTN
4836 EFIAPI
4837 TdCall (
4838   IN UINT64    Leaf,
4839   IN UINT64    Arg1,
4840   IN UINT64    Arg2,
4841   IN UINT64    Arg3,
4842   IN OUT VOID  *Results
4843   );
4844
4845 /**
4846   TDVMALL is a leaf function 0 for TDCALL. It helps invoke services from the
4847   host VMM to pass/receive information.
4848
4849   @param[in]     Leaf        Number of sub-functions
4850   @param[in]     Arg1        Arg1
4851   @param[in]     Arg2        Arg2
4852   @param[in]     Arg3        Arg3
4853   @param[in]     Arg4        Arg4
4854   @param[in,out] Results     Returned result of the sub-function
4855
4856   @return 0               A successful call
4857   @return Other           See individual sub-functions
4858
4859 **/
4860 UINTN
4861 EFIAPI
4862 TdVmCall (
4863   IN UINT64    Leaf,
4864   IN UINT64    Arg1,
4865   IN UINT64    Arg2,
4866   IN UINT64    Arg3,
4867   IN UINT64    Arg4,
4868   IN OUT VOID  *Results
4869   );
4870
4871 /**
4872   Probe if TD is enabled.
4873
4874   @return TRUE    TD is enabled.
4875   @return FALSE   TD is not enabled.
4876 **/
4877 BOOLEAN
4878 EFIAPI
4879 TdIsEnabled (
4880   VOID
4881   );
4882
4883 #endif
4884
4885 #if defined (MDE_CPU_X64)
4886 //
4887 // The page size for the PVALIDATE instruction
4888 //
4889 typedef enum {
4890   PvalidatePageSize4K = 0,
4891   PvalidatePageSize2MB,
4892 } PVALIDATE_PAGE_SIZE;
4893
4894 //
4895 // PVALIDATE Return Code.
4896 //
4897 #define PVALIDATE_RET_SUCCESS        0
4898 #define PVALIDATE_RET_FAIL_INPUT     1
4899 #define PVALIDATE_RET_SIZE_MISMATCH  6
4900
4901 //
4902 // The PVALIDATE instruction did not make any changes to the RMP entry.
4903 //
4904 #define PVALIDATE_RET_NO_RMPUPDATE  255
4905
4906 /**
4907  Execute a PVALIDATE instruction to validate or to rescinds validation of a guest
4908  page's RMP entry.
4909
4910  The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1.
4911
4912  The function is available on X64.
4913
4914  @param[in]    PageSize         The page size to use.
4915  @param[in]    Validate         If TRUE, validate the guest virtual address
4916                                 otherwise invalidate the guest virtual address.
4917  @param[in]    Address          The guest virtual address.
4918
4919  @retval PVALIDATE_RET_SUCCESS        The PVALIDATE instruction succeeded, and
4920                                       updated the RMP entry.
4921  @retval PVALIDATE_RET_NO_RMPUPDATE   The PVALIDATE instruction succeeded, but
4922                                       did not update the RMP entry.
4923  @return                              Failure code from the PVALIDATE
4924                                       instruction.
4925 **/
4926 UINT32
4927 EFIAPI
4928 AsmPvalidate (
4929   IN   PVALIDATE_PAGE_SIZE  PageSize,
4930   IN   BOOLEAN              Validate,
4931   IN   PHYSICAL_ADDRESS     Address
4932   );
4933
4934 //
4935 // RDX settings for RMPADJUST
4936 //
4937 #define RMPADJUST_VMPL_MAX               3
4938 #define RMPADJUST_VMPL_MASK              0xFF
4939 #define RMPADJUST_VMPL_SHIFT             0
4940 #define RMPADJUST_PERMISSION_MASK_MASK   0xFF
4941 #define RMPADJUST_PERMISSION_MASK_SHIFT  8
4942 #define RMPADJUST_VMSA_PAGE_BIT          BIT16
4943
4944 /**
4945   Adjusts the permissions of an SEV-SNP guest page.
4946
4947   Executes a RMPADJUST instruction with the register state specified by Rax,
4948   Rcx, and Rdx. Returns Eax. This function is only available on X64.
4949
4950   The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1.
4951
4952   @param[in]  Rax   The value to load into RAX before executing the RMPADJUST
4953                     instruction.
4954   @param[in]  Rcx   The value to load into RCX before executing the RMPADJUST
4955                     instruction.
4956   @param[in]  Rdx   The value to load into RDX before executing the RMPADJUST
4957                     instruction.
4958
4959   @return     Eax
4960 **/
4961 UINT32
4962 EFIAPI
4963 AsmRmpAdjust (
4964   IN      UINT64  Rax,
4965   IN      UINT64  Rcx,
4966   IN      UINT64  Rdx
4967   );
4968
4969 #endif
4970
4971 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
4972 ///
4973 /// IA32 and x64 Specific Functions.
4974 /// Byte packed structure for 16-bit Real Mode EFLAGS.
4975 ///
4976 typedef union {
4977   struct {
4978     UINT32    CF         : 1; ///< Carry Flag.
4979     UINT32    Reserved_0 : 1; ///< Reserved.
4980     UINT32    PF         : 1; ///< Parity Flag.
4981     UINT32    Reserved_1 : 1; ///< Reserved.
4982     UINT32    AF         : 1; ///< Auxiliary Carry Flag.
4983     UINT32    Reserved_2 : 1; ///< Reserved.
4984     UINT32    ZF         : 1; ///< Zero Flag.
4985     UINT32    SF         : 1; ///< Sign Flag.
4986     UINT32    TF         : 1; ///< Trap Flag.
4987     UINT32    IF         : 1; ///< Interrupt Enable Flag.
4988     UINT32    DF         : 1; ///< Direction Flag.
4989     UINT32    OF         : 1; ///< Overflow Flag.
4990     UINT32    IOPL       : 2; ///< I/O Privilege Level.
4991     UINT32    NT         : 1; ///< Nested Task.
4992     UINT32    Reserved_3 : 1; ///< Reserved.
4993   } Bits;
4994   UINT16    Uint16;
4995 } IA32_FLAGS16;
4996
4997 ///
4998 /// Byte packed structure for EFLAGS/RFLAGS.
4999 /// 32-bits on IA-32.
5000 /// 64-bits on x64.  The upper 32-bits on x64 are reserved.
5001 ///
5002 typedef union {
5003   struct {
5004     UINT32    CF         : 1;  ///< Carry Flag.
5005     UINT32    Reserved_0 : 1;  ///< Reserved.
5006     UINT32    PF         : 1;  ///< Parity Flag.
5007     UINT32    Reserved_1 : 1;  ///< Reserved.
5008     UINT32    AF         : 1;  ///< Auxiliary Carry Flag.
5009     UINT32    Reserved_2 : 1;  ///< Reserved.
5010     UINT32    ZF         : 1;  ///< Zero Flag.
5011     UINT32    SF         : 1;  ///< Sign Flag.
5012     UINT32    TF         : 1;  ///< Trap Flag.
5013     UINT32    IF         : 1;  ///< Interrupt Enable Flag.
5014     UINT32    DF         : 1;  ///< Direction Flag.
5015     UINT32    OF         : 1;  ///< Overflow Flag.
5016     UINT32    IOPL       : 2;  ///< I/O Privilege Level.
5017     UINT32    NT         : 1;  ///< Nested Task.
5018     UINT32    Reserved_3 : 1;  ///< Reserved.
5019     UINT32    RF         : 1;  ///< Resume Flag.
5020     UINT32    VM         : 1;  ///< Virtual 8086 Mode.
5021     UINT32    AC         : 1;  ///< Alignment Check.
5022     UINT32    VIF        : 1;  ///< Virtual Interrupt Flag.
5023     UINT32    VIP        : 1;  ///< Virtual Interrupt Pending.
5024     UINT32    ID         : 1;  ///< ID Flag.
5025     UINT32    Reserved_4 : 10; ///< Reserved.
5026   } Bits;
5027   UINTN    UintN;
5028 } IA32_EFLAGS32;
5029
5030 ///
5031 /// Byte packed structure for Control Register 0 (CR0).
5032 /// 32-bits on IA-32.
5033 /// 64-bits on x64.  The upper 32-bits on x64 are reserved.
5034 ///
5035 typedef union {
5036   struct {
5037     UINT32    PE         : 1;  ///< Protection Enable.
5038     UINT32    MP         : 1;  ///< Monitor Coprocessor.
5039     UINT32    EM         : 1;  ///< Emulation.
5040     UINT32    TS         : 1;  ///< Task Switched.
5041     UINT32    ET         : 1;  ///< Extension Type.
5042     UINT32    NE         : 1;  ///< Numeric Error.
5043     UINT32    Reserved_0 : 10; ///< Reserved.
5044     UINT32    WP         : 1;  ///< Write Protect.
5045     UINT32    Reserved_1 : 1;  ///< Reserved.
5046     UINT32    AM         : 1;  ///< Alignment Mask.
5047     UINT32    Reserved_2 : 10; ///< Reserved.
5048     UINT32    NW         : 1;  ///< Mot Write-through.
5049     UINT32    CD         : 1;  ///< Cache Disable.
5050     UINT32    PG         : 1;  ///< Paging.
5051   } Bits;
5052   UINTN    UintN;
5053 } IA32_CR0;
5054
5055 ///
5056 /// Byte packed structure for Control Register 4 (CR4).
5057 /// 32-bits on IA-32.
5058 /// 64-bits on x64.  The upper 32-bits on x64 are reserved.
5059 ///
5060 typedef union {
5061   struct {
5062     UINT32    VME        : 1; ///< Virtual-8086 Mode Extensions.
5063     UINT32    PVI        : 1; ///< Protected-Mode Virtual Interrupts.
5064     UINT32    TSD        : 1; ///< Time Stamp Disable.
5065     UINT32    DE         : 1; ///< Debugging Extensions.
5066     UINT32    PSE        : 1; ///< Page Size Extensions.
5067     UINT32    PAE        : 1; ///< Physical Address Extension.
5068     UINT32    MCE        : 1; ///< Machine Check Enable.
5069     UINT32    PGE        : 1; ///< Page Global Enable.
5070     UINT32    PCE        : 1; ///< Performance Monitoring Counter
5071                               ///< Enable.
5072     UINT32    OSFXSR     : 1; ///< Operating System Support for
5073                               ///< FXSAVE and FXRSTOR instructions
5074     UINT32    OSXMMEXCPT : 1; ///< Operating System Support for
5075                               ///< Unmasked SIMD Floating Point
5076                               ///< Exceptions.
5077     UINT32    UMIP       : 1; ///< User-Mode Instruction Prevention.
5078     UINT32    LA57       : 1; ///< Linear Address 57bit.
5079     UINT32    VMXE       : 1; ///< VMX Enable.
5080     UINT32    SMXE       : 1; ///< SMX Enable.
5081     UINT32    Reserved_3 : 1; ///< Reserved.
5082     UINT32    FSGSBASE   : 1; ///< FSGSBASE Enable.
5083     UINT32    PCIDE      : 1; ///< PCID Enable.
5084     UINT32    OSXSAVE    : 1; ///< XSAVE and Processor Extended States Enable.
5085     UINT32    Reserved_4 : 1; ///< Reserved.
5086     UINT32    SMEP       : 1; ///< SMEP Enable.
5087     UINT32    SMAP       : 1; ///< SMAP Enable.
5088     UINT32    PKE        : 1; ///< Protection-Key Enable.
5089     UINT32    Reserved_5 : 9; ///< Reserved.
5090   } Bits;
5091   UINTN    UintN;
5092 } IA32_CR4;
5093
5094 ///
5095 /// Byte packed structure for a segment descriptor in a GDT/LDT.
5096 ///
5097 typedef union {
5098   struct {
5099     UINT32    LimitLow  : 16;
5100     UINT32    BaseLow   : 16;
5101     UINT32    BaseMid   : 8;
5102     UINT32    Type      : 4;
5103     UINT32    S         : 1;
5104     UINT32    DPL       : 2;
5105     UINT32    P         : 1;
5106     UINT32    LimitHigh : 4;
5107     UINT32    AVL       : 1;
5108     UINT32    L         : 1;
5109     UINT32    DB        : 1;
5110     UINT32    G         : 1;
5111     UINT32    BaseHigh  : 8;
5112   } Bits;
5113   UINT64    Uint64;
5114 } IA32_SEGMENT_DESCRIPTOR;
5115
5116 ///
5117 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
5118 ///
5119   #pragma pack (1)
5120 typedef struct {
5121   UINT16    Limit;
5122   UINTN     Base;
5123 } IA32_DESCRIPTOR;
5124   #pragma pack ()
5125
5126 #define IA32_IDT_GATE_TYPE_TASK          0x85
5127 #define IA32_IDT_GATE_TYPE_INTERRUPT_16  0x86
5128 #define IA32_IDT_GATE_TYPE_TRAP_16       0x87
5129 #define IA32_IDT_GATE_TYPE_INTERRUPT_32  0x8E
5130 #define IA32_IDT_GATE_TYPE_TRAP_32       0x8F
5131
5132 #define IA32_GDT_TYPE_TSS   0x9
5133 #define IA32_GDT_ALIGNMENT  8
5134
5135   #if defined (MDE_CPU_IA32)
5136 ///
5137 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
5138 ///
5139 typedef union {
5140   struct {
5141     UINT32    OffsetLow  : 16; ///< Offset bits 15..0.
5142     UINT32    Selector   : 16; ///< Selector.
5143     UINT32    Reserved_0 : 8;  ///< Reserved.
5144     UINT32    GateType   : 8;  ///< Gate Type.  See #defines above.
5145     UINT32    OffsetHigh : 16; ///< Offset bits 31..16.
5146   } Bits;
5147   UINT64    Uint64;
5148 } IA32_IDT_GATE_DESCRIPTOR;
5149
5150     #pragma pack (1)
5151 //
5152 // IA32 Task-State Segment Definition
5153 //
5154 typedef struct {
5155   UINT16    PreviousTaskLink;
5156   UINT16    Reserved_2;
5157   UINT32    ESP0;
5158   UINT16    SS0;
5159   UINT16    Reserved_10;
5160   UINT32    ESP1;
5161   UINT16    SS1;
5162   UINT16    Reserved_18;
5163   UINT32    ESP2;
5164   UINT16    SS2;
5165   UINT16    Reserved_26;
5166   UINT32    CR3;
5167   UINT32    EIP;
5168   UINT32    EFLAGS;
5169   UINT32    EAX;
5170   UINT32    ECX;
5171   UINT32    EDX;
5172   UINT32    EBX;
5173   UINT32    ESP;
5174   UINT32    EBP;
5175   UINT32    ESI;
5176   UINT32    EDI;
5177   UINT16    ES;
5178   UINT16    Reserved_74;
5179   UINT16    CS;
5180   UINT16    Reserved_78;
5181   UINT16    SS;
5182   UINT16    Reserved_82;
5183   UINT16    DS;
5184   UINT16    Reserved_86;
5185   UINT16    FS;
5186   UINT16    Reserved_90;
5187   UINT16    GS;
5188   UINT16    Reserved_94;
5189   UINT16    LDTSegmentSelector;
5190   UINT16    Reserved_98;
5191   UINT16    T;
5192   UINT16    IOMapBaseAddress;
5193 } IA32_TASK_STATE_SEGMENT;
5194
5195 typedef union {
5196   struct {
5197     UINT32    LimitLow    : 16; ///< Segment Limit 15..00
5198     UINT32    BaseLow     : 16; ///< Base Address  15..00
5199     UINT32    BaseMid     : 8;  ///< Base Address  23..16
5200     UINT32    Type        : 4;  ///< Type (1 0 B 1)
5201     UINT32    Reserved_43 : 1;  ///< 0
5202     UINT32    DPL         : 2;  ///< Descriptor Privilege Level
5203     UINT32    P           : 1;  ///< Segment Present
5204     UINT32    LimitHigh   : 4;  ///< Segment Limit 19..16
5205     UINT32    AVL         : 1;  ///< Available for use by system software
5206     UINT32    Reserved_52 : 2;  ///< 0 0
5207     UINT32    G           : 1;  ///< Granularity
5208     UINT32    BaseHigh    : 8;  ///< Base Address 31..24
5209   } Bits;
5210   UINT64    Uint64;
5211 } IA32_TSS_DESCRIPTOR;
5212     #pragma pack ()
5213
5214   #endif // defined (MDE_CPU_IA32)
5215
5216   #if defined (MDE_CPU_X64)
5217 ///
5218 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
5219 ///
5220 typedef union {
5221   struct {
5222     UINT32    OffsetLow   : 16; ///< Offset bits 15..0.
5223     UINT32    Selector    : 16; ///< Selector.
5224     UINT32    Reserved_0  : 8;  ///< Reserved.
5225     UINT32    GateType    : 8;  ///< Gate Type.  See #defines above.
5226     UINT32    OffsetHigh  : 16; ///< Offset bits 31..16.
5227     UINT32    OffsetUpper : 32; ///< Offset bits 63..32.
5228     UINT32    Reserved_1  : 32; ///< Reserved.
5229   } Bits;
5230   struct {
5231     UINT64    Uint64;
5232     UINT64    Uint64_1;
5233   } Uint128;
5234 } IA32_IDT_GATE_DESCRIPTOR;
5235
5236     #pragma pack (1)
5237 //
5238 // IA32 Task-State Segment Definition
5239 //
5240 typedef struct {
5241   UINT32    Reserved_0;
5242   UINT64    RSP0;
5243   UINT64    RSP1;
5244   UINT64    RSP2;
5245   UINT64    Reserved_28;
5246   UINT64    IST[7];
5247   UINT64    Reserved_92;
5248   UINT16    Reserved_100;
5249   UINT16    IOMapBaseAddress;
5250 } IA32_TASK_STATE_SEGMENT;
5251
5252 typedef union {
5253   struct {
5254     UINT32    LimitLow    : 16; ///< Segment Limit 15..00
5255     UINT32    BaseLow     : 16; ///< Base Address  15..00
5256     UINT32    BaseMidl    : 8;  ///< Base Address  23..16
5257     UINT32    Type        : 4;  ///< Type (1 0 B 1)
5258     UINT32    Reserved_43 : 1;  ///< 0
5259     UINT32    DPL         : 2;  ///< Descriptor Privilege Level
5260     UINT32    P           : 1;  ///< Segment Present
5261     UINT32    LimitHigh   : 4;  ///< Segment Limit 19..16
5262     UINT32    AVL         : 1;  ///< Available for use by system software
5263     UINT32    Reserved_52 : 2;  ///< 0 0
5264     UINT32    G           : 1;  ///< Granularity
5265     UINT32    BaseMidh    : 8;  ///< Base Address  31..24
5266     UINT32    BaseHigh    : 32; ///< Base Address  63..32
5267     UINT32    Reserved_96 : 32; ///< Reserved
5268   } Bits;
5269   struct {
5270     UINT64    Uint64;
5271     UINT64    Uint64_1;
5272   } Uint128;
5273 } IA32_TSS_DESCRIPTOR;
5274     #pragma pack ()
5275
5276   #endif // defined (MDE_CPU_X64)
5277
5278 ///
5279 /// Byte packed structure for an FP/SSE/SSE2 context.
5280 ///
5281 typedef struct {
5282   UINT8    Buffer[512];
5283 } IA32_FX_BUFFER;
5284
5285 ///
5286 /// Structures for the 16-bit real mode thunks.
5287 ///
5288 typedef struct {
5289   UINT32    Reserved1;
5290   UINT32    Reserved2;
5291   UINT32    Reserved3;
5292   UINT32    Reserved4;
5293   UINT8     BL;
5294   UINT8     BH;
5295   UINT16    Reserved5;
5296   UINT8     DL;
5297   UINT8     DH;
5298   UINT16    Reserved6;
5299   UINT8     CL;
5300   UINT8     CH;
5301   UINT16    Reserved7;
5302   UINT8     AL;
5303   UINT8     AH;
5304   UINT16    Reserved8;
5305 } IA32_BYTE_REGS;
5306
5307 typedef struct {
5308   UINT16    DI;
5309   UINT16    Reserved1;
5310   UINT16    SI;
5311   UINT16    Reserved2;
5312   UINT16    BP;
5313   UINT16    Reserved3;
5314   UINT16    SP;
5315   UINT16    Reserved4;
5316   UINT16    BX;
5317   UINT16    Reserved5;
5318   UINT16    DX;
5319   UINT16    Reserved6;
5320   UINT16    CX;
5321   UINT16    Reserved7;
5322   UINT16    AX;
5323   UINT16    Reserved8;
5324 } IA32_WORD_REGS;
5325
5326 typedef struct {
5327   UINT32           EDI;
5328   UINT32           ESI;
5329   UINT32           EBP;
5330   UINT32           ESP;
5331   UINT32           EBX;
5332   UINT32           EDX;
5333   UINT32           ECX;
5334   UINT32           EAX;
5335   UINT16           DS;
5336   UINT16           ES;
5337   UINT16           FS;
5338   UINT16           GS;
5339   IA32_EFLAGS32    EFLAGS;
5340   UINT32           Eip;
5341   UINT16           CS;
5342   UINT16           SS;
5343 } IA32_DWORD_REGS;
5344
5345 typedef union {
5346   IA32_DWORD_REGS    E;
5347   IA32_WORD_REGS     X;
5348   IA32_BYTE_REGS     H;
5349 } IA32_REGISTER_SET;
5350
5351 ///
5352 /// Byte packed structure for an 16-bit real mode thunks.
5353 ///
5354 typedef struct {
5355   IA32_REGISTER_SET    *RealModeState;
5356   VOID                 *RealModeBuffer;
5357   UINT32               RealModeBufferSize;
5358   UINT32               ThunkAttributes;
5359 } THUNK_CONTEXT;
5360
5361 #define THUNK_ATTRIBUTE_BIG_REAL_MODE              0x00000001
5362 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15    0x00000002
5363 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL  0x00000004
5364
5365 ///
5366 /// Type definition for representing labels in NASM source code that allow for
5367 /// the patching of immediate operands of IA32 and X64 instructions.
5368 ///
5369 /// While the type is technically defined as a function type (note: not a
5370 /// pointer-to-function type), such labels in NASM source code never stand for
5371 /// actual functions, and identifiers declared with this function type should
5372 /// never be called. This is also why the EFIAPI calling convention specifier
5373 /// is missing from the typedef, and why the typedef does not follow the usual
5374 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID
5375 /// return type and the VOID argument list are merely artifacts.
5376 ///
5377 typedef VOID (X86_ASSEMBLY_PATCH_LABEL) (
5378   VOID
5379   );
5380
5381 /**
5382   Retrieves CPUID information.
5383
5384   Executes the CPUID instruction with EAX set to the value specified by Index.
5385   This function always returns Index.
5386   If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5387   If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5388   If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5389   If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5390   This function is only available on IA-32 and x64.
5391
5392   @param  Index The 32-bit value to load into EAX prior to invoking the CPUID
5393                 instruction.
5394   @param  Eax   The pointer to the 32-bit EAX value returned by the CPUID
5395                 instruction. This is an optional parameter that may be NULL.
5396   @param  Ebx   The pointer to the 32-bit EBX value returned by the CPUID
5397                 instruction. This is an optional parameter that may be NULL.
5398   @param  Ecx   The pointer to the 32-bit ECX value returned by the CPUID
5399                 instruction. This is an optional parameter that may be NULL.
5400   @param  Edx   The pointer to the 32-bit EDX value returned by the CPUID
5401                 instruction. This is an optional parameter that may be NULL.
5402
5403   @return Index.
5404
5405 **/
5406 UINT32
5407 EFIAPI
5408 AsmCpuid (
5409   IN      UINT32  Index,
5410   OUT     UINT32  *Eax   OPTIONAL,
5411   OUT     UINT32  *Ebx   OPTIONAL,
5412   OUT     UINT32  *Ecx   OPTIONAL,
5413   OUT     UINT32  *Edx   OPTIONAL
5414   );
5415
5416 /**
5417   Retrieves CPUID information using an extended leaf identifier.
5418
5419   Executes the CPUID instruction with EAX set to the value specified by Index
5420   and ECX set to the value specified by SubIndex. This function always returns
5421   Index. This function is only available on IA-32 and x64.
5422
5423   If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5424   If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5425   If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5426   If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5427
5428   @param  Index     The 32-bit value to load into EAX prior to invoking the
5429                     CPUID instruction.
5430   @param  SubIndex  The 32-bit value to load into ECX prior to invoking the
5431                     CPUID instruction.
5432   @param  Eax       The pointer to the 32-bit EAX value returned by the CPUID
5433                     instruction. This is an optional parameter that may be
5434                     NULL.
5435   @param  Ebx       The pointer to the 32-bit EBX value returned by the CPUID
5436                     instruction. This is an optional parameter that may be
5437                     NULL.
5438   @param  Ecx       The pointer to the 32-bit ECX value returned by the CPUID
5439                     instruction. This is an optional parameter that may be
5440                     NULL.
5441   @param  Edx       The pointer to the 32-bit EDX value returned by the CPUID
5442                     instruction. This is an optional parameter that may be
5443                     NULL.
5444
5445   @return Index.
5446
5447 **/
5448 UINT32
5449 EFIAPI
5450 AsmCpuidEx (
5451   IN      UINT32  Index,
5452   IN      UINT32  SubIndex,
5453   OUT     UINT32  *Eax   OPTIONAL,
5454   OUT     UINT32  *Ebx   OPTIONAL,
5455   OUT     UINT32  *Ecx   OPTIONAL,
5456   OUT     UINT32  *Edx   OPTIONAL
5457   );
5458
5459 /**
5460   Set CD bit and clear NW bit of CR0 followed by a WBINVD.
5461
5462   Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
5463   and executing a WBINVD instruction.  This function is only available on IA-32 and x64.
5464
5465 **/
5466 VOID
5467 EFIAPI
5468 AsmDisableCache (
5469   VOID
5470   );
5471
5472 /**
5473   Perform a WBINVD and clear both the CD and NW bits of CR0.
5474
5475   Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
5476   bits of CR0 to 0.  This function is only available on IA-32 and x64.
5477
5478 **/
5479 VOID
5480 EFIAPI
5481 AsmEnableCache (
5482   VOID
5483   );
5484
5485 /**
5486   Returns the lower 32-bits of a Machine Specific Register(MSR).
5487
5488   Reads and returns the lower 32-bits of the MSR specified by Index.
5489   No parameter checking is performed on Index, and some Index values may cause
5490   CPU exceptions. The caller must either guarantee that Index is valid, or the
5491   caller must set up exception handlers to catch the exceptions. This function
5492   is only available on IA-32 and x64.
5493
5494   @param  Index The 32-bit MSR index to read.
5495
5496   @return The lower 32 bits of the MSR identified by Index.
5497
5498 **/
5499 UINT32
5500 EFIAPI
5501 AsmReadMsr32 (
5502   IN      UINT32  Index
5503   );
5504
5505 /**
5506   Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
5507   The upper 32-bits of the MSR are set to zero.
5508
5509   Writes the 32-bit value specified by Value to the MSR specified by Index. The
5510   upper 32-bits of the MSR write are set to zero. The 32-bit value written to
5511   the MSR is returned. No parameter checking is performed on Index or Value,
5512   and some of these may cause CPU exceptions. The caller must either guarantee
5513   that Index and Value are valid, or the caller must establish proper exception
5514   handlers. This function is only available on IA-32 and x64.
5515
5516   @param  Index The 32-bit MSR index to write.
5517   @param  Value The 32-bit value to write to the MSR.
5518
5519   @return Value
5520
5521 **/
5522 UINT32
5523 EFIAPI
5524 AsmWriteMsr32 (
5525   IN      UINT32  Index,
5526   IN      UINT32  Value
5527   );
5528
5529 /**
5530   Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
5531   writes the result back to the 64-bit MSR.
5532
5533   Reads the 64-bit MSR specified by Index, performs a bitwise OR
5534   between the lower 32-bits of the read result and the value specified by
5535   OrData, and writes the result to the 64-bit MSR specified by Index. The lower
5536   32-bits of the value written to the MSR is returned. No parameter checking is
5537   performed on Index or OrData, and some of these may cause CPU exceptions. The
5538   caller must either guarantee that Index and OrData are valid, or the caller
5539   must establish proper exception handlers. This function is only available on
5540   IA-32 and x64.
5541
5542   @param  Index   The 32-bit MSR index to write.
5543   @param  OrData  The value to OR with the read value from the MSR.
5544
5545   @return The lower 32-bit value written to the MSR.
5546
5547 **/
5548 UINT32
5549 EFIAPI
5550 AsmMsrOr32 (
5551   IN      UINT32  Index,
5552   IN      UINT32  OrData
5553   );
5554
5555 /**
5556   Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
5557   the result back to the 64-bit MSR.
5558
5559   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5560   lower 32-bits of the read result and the value specified by AndData, and
5561   writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
5562   the value written to the MSR is returned. No parameter checking is performed
5563   on Index or AndData, and some of these may cause CPU exceptions. The caller
5564   must either guarantee that Index and AndData are valid, or the caller must
5565   establish proper exception handlers. This function is only available on IA-32
5566   and x64.
5567
5568   @param  Index   The 32-bit MSR index to write.
5569   @param  AndData The value to AND with the read value from the MSR.
5570
5571   @return The lower 32-bit value written to the MSR.
5572
5573 **/
5574 UINT32
5575 EFIAPI
5576 AsmMsrAnd32 (
5577   IN      UINT32  Index,
5578   IN      UINT32  AndData
5579   );
5580
5581 /**
5582   Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
5583   on the lower 32-bits, and writes the result back to the 64-bit MSR.
5584
5585   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5586   lower 32-bits of the read result and the value specified by AndData
5587   preserving the upper 32-bits, performs a bitwise OR between the
5588   result of the AND operation and the value specified by OrData, and writes the
5589   result to the 64-bit MSR specified by Address. The lower 32-bits of the value
5590   written to the MSR is returned. No parameter checking is performed on Index,
5591   AndData, or OrData, and some of these may cause CPU exceptions. The caller
5592   must either guarantee that Index, AndData, and OrData are valid, or the
5593   caller must establish proper exception handlers. This function is only
5594   available on IA-32 and x64.
5595
5596   @param  Index   The 32-bit MSR index to write.
5597   @param  AndData The value to AND with the read value from the MSR.
5598   @param  OrData  The value to OR with the result of the AND operation.
5599
5600   @return The lower 32-bit value written to the MSR.
5601
5602 **/
5603 UINT32
5604 EFIAPI
5605 AsmMsrAndThenOr32 (
5606   IN      UINT32  Index,
5607   IN      UINT32  AndData,
5608   IN      UINT32  OrData
5609   );
5610
5611 /**
5612   Reads a bit field of an MSR.
5613
5614   Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
5615   specified by the StartBit and the EndBit. The value of the bit field is
5616   returned. The caller must either guarantee that Index is valid, or the caller
5617   must set up exception handlers to catch the exceptions. This function is only
5618   available on IA-32 and x64.
5619
5620   If StartBit is greater than 31, then ASSERT().
5621   If EndBit is greater than 31, then ASSERT().
5622   If EndBit is less than StartBit, then ASSERT().
5623
5624   @param  Index     The 32-bit MSR index to read.
5625   @param  StartBit  The ordinal of the least significant bit in the bit field.
5626                     Range 0..31.
5627   @param  EndBit    The ordinal of the most significant bit in the bit field.
5628                     Range 0..31.
5629
5630   @return The bit field read from the MSR.
5631
5632 **/
5633 UINT32
5634 EFIAPI
5635 AsmMsrBitFieldRead32 (
5636   IN      UINT32  Index,
5637   IN      UINTN   StartBit,
5638   IN      UINTN   EndBit
5639   );
5640
5641 /**
5642   Writes a bit field to an MSR.
5643
5644   Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
5645   field is specified by the StartBit and the EndBit. All other bits in the
5646   destination MSR are preserved. The lower 32-bits of the MSR written is
5647   returned. The caller must either guarantee that Index and the data written
5648   is valid, or the caller must set up exception handlers to catch the exceptions.
5649   This function is only available on IA-32 and x64.
5650
5651   If StartBit is greater than 31, then ASSERT().
5652   If EndBit is greater than 31, then ASSERT().
5653   If EndBit is less than StartBit, then ASSERT().
5654   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5655
5656   @param  Index     The 32-bit MSR index to write.
5657   @param  StartBit  The ordinal of the least significant bit in the bit field.
5658                     Range 0..31.
5659   @param  EndBit    The ordinal of the most significant bit in the bit field.
5660                     Range 0..31.
5661   @param  Value     New value of the bit field.
5662
5663   @return The lower 32-bit of the value written to the MSR.
5664
5665 **/
5666 UINT32
5667 EFIAPI
5668 AsmMsrBitFieldWrite32 (
5669   IN      UINT32  Index,
5670   IN      UINTN   StartBit,
5671   IN      UINTN   EndBit,
5672   IN      UINT32  Value
5673   );
5674
5675 /**
5676   Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
5677   result back to the bit field in the 64-bit MSR.
5678
5679   Reads the 64-bit MSR specified by Index, performs a bitwise OR
5680   between the read result and the value specified by OrData, and writes the
5681   result to the 64-bit MSR specified by Index. The lower 32-bits of the value
5682   written to the MSR are returned. Extra left bits in OrData are stripped. The
5683   caller must either guarantee that Index and the data written is valid, or
5684   the caller must set up exception handlers to catch the exceptions. This
5685   function is only available on IA-32 and x64.
5686
5687   If StartBit is greater than 31, then ASSERT().
5688   If EndBit is greater than 31, then ASSERT().
5689   If EndBit is less than StartBit, then ASSERT().
5690   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5691
5692   @param  Index     The 32-bit MSR index to write.
5693   @param  StartBit  The ordinal of the least significant bit in the bit field.
5694                     Range 0..31.
5695   @param  EndBit    The ordinal of the most significant bit in the bit field.
5696                     Range 0..31.
5697   @param  OrData    The value to OR with the read value from the MSR.
5698
5699   @return The lower 32-bit of the value written to the MSR.
5700
5701 **/
5702 UINT32
5703 EFIAPI
5704 AsmMsrBitFieldOr32 (
5705   IN      UINT32  Index,
5706   IN      UINTN   StartBit,
5707   IN      UINTN   EndBit,
5708   IN      UINT32  OrData
5709   );
5710
5711 /**
5712   Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
5713   result back to the bit field in the 64-bit MSR.
5714
5715   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5716   read result and the value specified by AndData, and writes the result to the
5717   64-bit MSR specified by Index. The lower 32-bits of the value written to the
5718   MSR are returned. Extra left bits in AndData are stripped. The caller must
5719   either guarantee that Index and the data written is valid, or the caller must
5720   set up exception handlers to catch the exceptions. This function is only
5721   available on IA-32 and x64.
5722
5723   If StartBit is greater than 31, then ASSERT().
5724   If EndBit is greater than 31, then ASSERT().
5725   If EndBit is less than StartBit, then ASSERT().
5726   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5727
5728   @param  Index     The 32-bit MSR index to write.
5729   @param  StartBit  The ordinal of the least significant bit in the bit field.
5730                     Range 0..31.
5731   @param  EndBit    The ordinal of the most significant bit in the bit field.
5732                     Range 0..31.
5733   @param  AndData   The value to AND with the read value from the MSR.
5734
5735   @return The lower 32-bit of the value written to the MSR.
5736
5737 **/
5738 UINT32
5739 EFIAPI
5740 AsmMsrBitFieldAnd32 (
5741   IN      UINT32  Index,
5742   IN      UINTN   StartBit,
5743   IN      UINTN   EndBit,
5744   IN      UINT32  AndData
5745   );
5746
5747 /**
5748   Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
5749   bitwise OR, and writes the result back to the bit field in the
5750   64-bit MSR.
5751
5752   Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
5753   bitwise OR between the read result and the value specified by
5754   AndData, and writes the result to the 64-bit MSR specified by Index. The
5755   lower 32-bits of the value written to the MSR are returned. Extra left bits
5756   in both AndData and OrData are stripped. The caller must either guarantee
5757   that Index and the data written is valid, or the caller must set up exception
5758   handlers to catch the exceptions. This function is only available on IA-32
5759   and x64.
5760
5761   If StartBit is greater than 31, then ASSERT().
5762   If EndBit is greater than 31, then ASSERT().
5763   If EndBit is less than StartBit, then ASSERT().
5764   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5765   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5766
5767   @param  Index     The 32-bit MSR index to write.
5768   @param  StartBit  The ordinal of the least significant bit in the bit field.
5769                     Range 0..31.
5770   @param  EndBit    The ordinal of the most significant bit in the bit field.
5771                     Range 0..31.
5772   @param  AndData   The value to AND with the read value from the MSR.
5773   @param  OrData    The value to OR with the result of the AND operation.
5774
5775   @return The lower 32-bit of the value written to the MSR.
5776
5777 **/
5778 UINT32
5779 EFIAPI
5780 AsmMsrBitFieldAndThenOr32 (
5781   IN      UINT32  Index,
5782   IN      UINTN   StartBit,
5783   IN      UINTN   EndBit,
5784   IN      UINT32  AndData,
5785   IN      UINT32  OrData
5786   );
5787
5788 /**
5789   Returns a 64-bit Machine Specific Register(MSR).
5790
5791   Reads and returns the 64-bit MSR specified by Index. No parameter checking is
5792   performed on Index, and some Index values may cause CPU exceptions. The
5793   caller must either guarantee that Index is valid, or the caller must set up
5794   exception handlers to catch the exceptions. This function is only available
5795   on IA-32 and x64.
5796
5797   @param  Index The 32-bit MSR index to read.
5798
5799   @return The value of the MSR identified by Index.
5800
5801 **/
5802 UINT64
5803 EFIAPI
5804 AsmReadMsr64 (
5805   IN      UINT32  Index
5806   );
5807
5808 /**
5809   Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
5810   value.
5811
5812   Writes the 64-bit value specified by Value to the MSR specified by Index. The
5813   64-bit value written to the MSR is returned. No parameter checking is
5814   performed on Index or Value, and some of these may cause CPU exceptions. The
5815   caller must either guarantee that Index and Value are valid, or the caller
5816   must establish proper exception handlers. This function is only available on
5817   IA-32 and x64.
5818
5819   @param  Index The 32-bit MSR index to write.
5820   @param  Value The 64-bit value to write to the MSR.
5821
5822   @return Value
5823
5824 **/
5825 UINT64
5826 EFIAPI
5827 AsmWriteMsr64 (
5828   IN      UINT32  Index,
5829   IN      UINT64  Value
5830   );
5831
5832 /**
5833   Reads a 64-bit MSR, performs a bitwise OR, and writes the result
5834   back to the 64-bit MSR.
5835
5836   Reads the 64-bit MSR specified by Index, performs a bitwise OR
5837   between the read result and the value specified by OrData, and writes the
5838   result to the 64-bit MSR specified by Index. The value written to the MSR is
5839   returned. No parameter checking is performed on Index or OrData, and some of
5840   these may cause CPU exceptions. The caller must either guarantee that Index
5841   and OrData are valid, or the caller must establish proper exception handlers.
5842   This function is only available on IA-32 and x64.
5843
5844   @param  Index   The 32-bit MSR index to write.
5845   @param  OrData  The value to OR with the read value from the MSR.
5846
5847   @return The value written back to the MSR.
5848
5849 **/
5850 UINT64
5851 EFIAPI
5852 AsmMsrOr64 (
5853   IN      UINT32  Index,
5854   IN      UINT64  OrData
5855   );
5856
5857 /**
5858   Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
5859   64-bit MSR.
5860
5861   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5862   read result and the value specified by OrData, and writes the result to the
5863   64-bit MSR specified by Index. The value written to the MSR is returned. No
5864   parameter checking is performed on Index or OrData, and some of these may
5865   cause CPU exceptions. The caller must either guarantee that Index and OrData
5866   are valid, or the caller must establish proper exception handlers. This
5867   function is only available on IA-32 and x64.
5868
5869   @param  Index   The 32-bit MSR index to write.
5870   @param  AndData The value to AND with the read value from the MSR.
5871
5872   @return The value written back to the MSR.
5873
5874 **/
5875 UINT64
5876 EFIAPI
5877 AsmMsrAnd64 (
5878   IN      UINT32  Index,
5879   IN      UINT64  AndData
5880   );
5881
5882 /**
5883   Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
5884   OR, and writes the result back to the 64-bit MSR.
5885
5886   Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
5887   result and the value specified by AndData, performs a bitwise OR
5888   between the result of the AND operation and the value specified by OrData,
5889   and writes the result to the 64-bit MSR specified by Index. The value written
5890   to the MSR is returned. No parameter checking is performed on Index, AndData,
5891   or OrData, and some of these may cause CPU exceptions. The caller must either
5892   guarantee that Index, AndData, and OrData are valid, or the caller must
5893   establish proper exception handlers. This function is only available on IA-32
5894   and x64.
5895
5896   @param  Index   The 32-bit MSR index to write.
5897   @param  AndData The value to AND with the read value from the MSR.
5898   @param  OrData  The value to OR with the result of the AND operation.
5899
5900   @return The value written back to the MSR.
5901
5902 **/
5903 UINT64
5904 EFIAPI
5905 AsmMsrAndThenOr64 (
5906   IN      UINT32  Index,
5907   IN      UINT64  AndData,
5908   IN      UINT64  OrData
5909   );
5910
5911 /**
5912   Reads a bit field of an MSR.
5913
5914   Reads the bit field in the 64-bit MSR. The bit field is specified by the
5915   StartBit and the EndBit. The value of the bit field is returned. The caller
5916   must either guarantee that Index is valid, or the caller must set up
5917   exception handlers to catch the exceptions. This function is only available
5918   on IA-32 and x64.
5919
5920   If StartBit is greater than 63, then ASSERT().
5921   If EndBit is greater than 63, then ASSERT().
5922   If EndBit is less than StartBit, then ASSERT().
5923
5924   @param  Index     The 32-bit MSR index to read.
5925   @param  StartBit  The ordinal of the least significant bit in the bit field.
5926                     Range 0..63.
5927   @param  EndBit    The ordinal of the most significant bit in the bit field.
5928                     Range 0..63.
5929
5930   @return The value read from the MSR.
5931
5932 **/
5933 UINT64
5934 EFIAPI
5935 AsmMsrBitFieldRead64 (
5936   IN      UINT32  Index,
5937   IN      UINTN   StartBit,
5938   IN      UINTN   EndBit
5939   );
5940
5941 /**
5942   Writes a bit field to an MSR.
5943
5944   Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
5945   the StartBit and the EndBit. All other bits in the destination MSR are
5946   preserved. The MSR written is returned. The caller must either guarantee
5947   that Index and the data written is valid, or the caller must set up exception
5948   handlers to catch the exceptions. This function is only available on IA-32 and x64.
5949
5950   If StartBit is greater than 63, then ASSERT().
5951   If EndBit is greater than 63, then ASSERT().
5952   If EndBit is less than StartBit, then ASSERT().
5953   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5954
5955   @param  Index     The 32-bit MSR index to write.
5956   @param  StartBit  The ordinal of the least significant bit in the bit field.
5957                     Range 0..63.
5958   @param  EndBit    The ordinal of the most significant bit in the bit field.
5959                     Range 0..63.
5960   @param  Value     New value of the bit field.
5961
5962   @return The value written back to the MSR.
5963
5964 **/
5965 UINT64
5966 EFIAPI
5967 AsmMsrBitFieldWrite64 (
5968   IN      UINT32  Index,
5969   IN      UINTN   StartBit,
5970   IN      UINTN   EndBit,
5971   IN      UINT64  Value
5972   );
5973
5974 /**
5975   Reads a bit field in a 64-bit MSR, performs a bitwise OR, and
5976   writes the result back to the bit field in the 64-bit MSR.
5977
5978   Reads the 64-bit MSR specified by Index, performs a bitwise OR
5979   between the read result and the value specified by OrData, and writes the
5980   result to the 64-bit MSR specified by Index. The value written to the MSR is
5981   returned. Extra left bits in OrData are stripped. The caller must either
5982   guarantee that Index and the data written is valid, or the caller must set up
5983   exception handlers to catch the exceptions. This function is only available
5984   on IA-32 and x64.
5985
5986   If StartBit is greater than 63, then ASSERT().
5987   If EndBit is greater than 63, then ASSERT().
5988   If EndBit is less than StartBit, then ASSERT().
5989   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5990
5991   @param  Index     The 32-bit MSR index to write.
5992   @param  StartBit  The ordinal of the least significant bit in the bit field.
5993                     Range 0..63.
5994   @param  EndBit    The ordinal of the most significant bit in the bit field.
5995                     Range 0..63.
5996   @param  OrData    The value to OR with the read value from the bit field.
5997
5998   @return The value written back to the MSR.
5999
6000 **/
6001 UINT64
6002 EFIAPI
6003 AsmMsrBitFieldOr64 (
6004   IN      UINT32  Index,
6005   IN      UINTN   StartBit,
6006   IN      UINTN   EndBit,
6007   IN      UINT64  OrData
6008   );
6009
6010 /**
6011   Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6012   result back to the bit field in the 64-bit MSR.
6013
6014   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6015   read result and the value specified by AndData, and writes the result to the
6016   64-bit MSR specified by Index. The value written to the MSR is returned.
6017   Extra left bits in AndData are stripped. The caller must either guarantee
6018   that Index and the data written is valid, or the caller must set up exception
6019   handlers to catch the exceptions. This function is only available on IA-32
6020   and x64.
6021
6022   If StartBit is greater than 63, then ASSERT().
6023   If EndBit is greater than 63, then ASSERT().
6024   If EndBit is less than StartBit, then ASSERT().
6025   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6026
6027   @param  Index     The 32-bit MSR index to write.
6028   @param  StartBit  The ordinal of the least significant bit in the bit field.
6029                     Range 0..63.
6030   @param  EndBit    The ordinal of the most significant bit in the bit field.
6031                     Range 0..63.
6032   @param  AndData   The value to AND with the read value from the bit field.
6033
6034   @return The value written back to the MSR.
6035
6036 **/
6037 UINT64
6038 EFIAPI
6039 AsmMsrBitFieldAnd64 (
6040   IN      UINT32  Index,
6041   IN      UINTN   StartBit,
6042   IN      UINTN   EndBit,
6043   IN      UINT64  AndData
6044   );
6045
6046 /**
6047   Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6048   bitwise OR, and writes the result back to the bit field in the
6049   64-bit MSR.
6050
6051   Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
6052   a bitwise OR between the read result and the value specified by
6053   AndData, and writes the result to the 64-bit MSR specified by Index. The
6054   value written to the MSR is returned. Extra left bits in both AndData and
6055   OrData are stripped. The caller must either guarantee that Index and the data
6056   written is valid, or the caller must set up exception handlers to catch the
6057   exceptions. This function is only available on IA-32 and x64.
6058
6059   If StartBit is greater than 63, then ASSERT().
6060   If EndBit is greater than 63, then ASSERT().
6061   If EndBit is less than StartBit, then ASSERT().
6062   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6063   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6064
6065   @param  Index     The 32-bit MSR index to write.
6066   @param  StartBit  The ordinal of the least significant bit in the bit field.
6067                     Range 0..63.
6068   @param  EndBit    The ordinal of the most significant bit in the bit field.
6069                     Range 0..63.
6070   @param  AndData   The value to AND with the read value from the bit field.
6071   @param  OrData    The value to OR with the result of the AND operation.
6072
6073   @return The value written back to the MSR.
6074
6075 **/
6076 UINT64
6077 EFIAPI
6078 AsmMsrBitFieldAndThenOr64 (
6079   IN      UINT32  Index,
6080   IN      UINTN   StartBit,
6081   IN      UINTN   EndBit,
6082   IN      UINT64  AndData,
6083   IN      UINT64  OrData
6084   );
6085
6086 /**
6087   Reads the current value of the EFLAGS register.
6088
6089   Reads and returns the current value of the EFLAGS register. This function is
6090   only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a
6091   64-bit value on x64.
6092
6093   @return EFLAGS on IA-32 or RFLAGS on x64.
6094
6095 **/
6096 UINTN
6097 EFIAPI
6098 AsmReadEflags (
6099   VOID
6100   );
6101
6102 /**
6103   Reads the current value of the Control Register 0 (CR0).
6104
6105   Reads and returns the current value of CR0. This function is only available
6106   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6107   x64.
6108
6109   @return The value of the Control Register 0 (CR0).
6110
6111 **/
6112 UINTN
6113 EFIAPI
6114 AsmReadCr0 (
6115   VOID
6116   );
6117
6118 /**
6119   Reads the current value of the Control Register 2 (CR2).
6120
6121   Reads and returns the current value of CR2. This function is only available
6122   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6123   x64.
6124
6125   @return The value of the Control Register 2 (CR2).
6126
6127 **/
6128 UINTN
6129 EFIAPI
6130 AsmReadCr2 (
6131   VOID
6132   );
6133
6134 /**
6135   Reads the current value of the Control Register 3 (CR3).
6136
6137   Reads and returns the current value of CR3. This function is only available
6138   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6139   x64.
6140
6141   @return The value of the Control Register 3 (CR3).
6142
6143 **/
6144 UINTN
6145 EFIAPI
6146 AsmReadCr3 (
6147   VOID
6148   );
6149
6150 /**
6151   Reads the current value of the Control Register 4 (CR4).
6152
6153   Reads and returns the current value of CR4. This function is only available
6154   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6155   x64.
6156
6157   @return The value of the Control Register 4 (CR4).
6158
6159 **/
6160 UINTN
6161 EFIAPI
6162 AsmReadCr4 (
6163   VOID
6164   );
6165
6166 /**
6167   Writes a value to Control Register 0 (CR0).
6168
6169   Writes and returns a new value to CR0. This function is only available on
6170   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6171
6172   @param  Cr0 The value to write to CR0.
6173
6174   @return The value written to CR0.
6175
6176 **/
6177 UINTN
6178 EFIAPI
6179 AsmWriteCr0 (
6180   UINTN  Cr0
6181   );
6182
6183 /**
6184   Writes a value to Control Register 2 (CR2).
6185
6186   Writes and returns a new value to CR2. This function is only available on
6187   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6188
6189   @param  Cr2 The value to write to CR2.
6190
6191   @return The value written to CR2.
6192
6193 **/
6194 UINTN
6195 EFIAPI
6196 AsmWriteCr2 (
6197   UINTN  Cr2
6198   );
6199
6200 /**
6201   Writes a value to Control Register 3 (CR3).
6202
6203   Writes and returns a new value to CR3. This function is only available on
6204   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6205
6206   @param  Cr3 The value to write to CR3.
6207
6208   @return The value written to CR3.
6209
6210 **/
6211 UINTN
6212 EFIAPI
6213 AsmWriteCr3 (
6214   UINTN  Cr3
6215   );
6216
6217 /**
6218   Writes a value to Control Register 4 (CR4).
6219
6220   Writes and returns a new value to CR4. This function is only available on
6221   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6222
6223   @param  Cr4 The value to write to CR4.
6224
6225   @return The value written to CR4.
6226
6227 **/
6228 UINTN
6229 EFIAPI
6230 AsmWriteCr4 (
6231   UINTN  Cr4
6232   );
6233
6234 /**
6235   Reads the current value of Debug Register 0 (DR0).
6236
6237   Reads and returns the current value of DR0. This function is only available
6238   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6239   x64.
6240
6241   @return The value of Debug Register 0 (DR0).
6242
6243 **/
6244 UINTN
6245 EFIAPI
6246 AsmReadDr0 (
6247   VOID
6248   );
6249
6250 /**
6251   Reads the current value of Debug Register 1 (DR1).
6252
6253   Reads and returns the current value of DR1. This function is only available
6254   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6255   x64.
6256
6257   @return The value of Debug Register 1 (DR1).
6258
6259 **/
6260 UINTN
6261 EFIAPI
6262 AsmReadDr1 (
6263   VOID
6264   );
6265
6266 /**
6267   Reads the current value of Debug Register 2 (DR2).
6268
6269   Reads and returns the current value of DR2. This function is only available
6270   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6271   x64.
6272
6273   @return The value of Debug Register 2 (DR2).
6274
6275 **/
6276 UINTN
6277 EFIAPI
6278 AsmReadDr2 (
6279   VOID
6280   );
6281
6282 /**
6283   Reads the current value of Debug Register 3 (DR3).
6284
6285   Reads and returns the current value of DR3. This function is only available
6286   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6287   x64.
6288
6289   @return The value of Debug Register 3 (DR3).
6290
6291 **/
6292 UINTN
6293 EFIAPI
6294 AsmReadDr3 (
6295   VOID
6296   );
6297
6298 /**
6299   Reads the current value of Debug Register 4 (DR4).
6300
6301   Reads and returns the current value of DR4. This function is only available
6302   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6303   x64.
6304
6305   @return The value of Debug Register 4 (DR4).
6306
6307 **/
6308 UINTN
6309 EFIAPI
6310 AsmReadDr4 (
6311   VOID
6312   );
6313
6314 /**
6315   Reads the current value of Debug Register 5 (DR5).
6316
6317   Reads and returns the current value of DR5. This function is only available
6318   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6319   x64.
6320
6321   @return The value of Debug Register 5 (DR5).
6322
6323 **/
6324 UINTN
6325 EFIAPI
6326 AsmReadDr5 (
6327   VOID
6328   );
6329
6330 /**
6331   Reads the current value of Debug Register 6 (DR6).
6332
6333   Reads and returns the current value of DR6. This function is only available
6334   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6335   x64.
6336
6337   @return The value of Debug Register 6 (DR6).
6338
6339 **/
6340 UINTN
6341 EFIAPI
6342 AsmReadDr6 (
6343   VOID
6344   );
6345
6346 /**
6347   Reads the current value of Debug Register 7 (DR7).
6348
6349   Reads and returns the current value of DR7. This function is only available
6350   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6351   x64.
6352
6353   @return The value of Debug Register 7 (DR7).
6354
6355 **/
6356 UINTN
6357 EFIAPI
6358 AsmReadDr7 (
6359   VOID
6360   );
6361
6362 /**
6363   Writes a value to Debug Register 0 (DR0).
6364
6365   Writes and returns a new value to DR0. This function is only available on
6366   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6367
6368   @param  Dr0 The value to write to Dr0.
6369
6370   @return The value written to Debug Register 0 (DR0).
6371
6372 **/
6373 UINTN
6374 EFIAPI
6375 AsmWriteDr0 (
6376   UINTN  Dr0
6377   );
6378
6379 /**
6380   Writes a value to Debug Register 1 (DR1).
6381
6382   Writes and returns a new value to DR1. This function is only available on
6383   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6384
6385   @param  Dr1 The value to write to Dr1.
6386
6387   @return The value written to Debug Register 1 (DR1).
6388
6389 **/
6390 UINTN
6391 EFIAPI
6392 AsmWriteDr1 (
6393   UINTN  Dr1
6394   );
6395
6396 /**
6397   Writes a value to Debug Register 2 (DR2).
6398
6399   Writes and returns a new value to DR2. This function is only available on
6400   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6401
6402   @param  Dr2 The value to write to Dr2.
6403
6404   @return The value written to Debug Register 2 (DR2).
6405
6406 **/
6407 UINTN
6408 EFIAPI
6409 AsmWriteDr2 (
6410   UINTN  Dr2
6411   );
6412
6413 /**
6414   Writes a value to Debug Register 3 (DR3).
6415
6416   Writes and returns a new value to DR3. This function is only available on
6417   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6418
6419   @param  Dr3 The value to write to Dr3.
6420
6421   @return The value written to Debug Register 3 (DR3).
6422
6423 **/
6424 UINTN
6425 EFIAPI
6426 AsmWriteDr3 (
6427   UINTN  Dr3
6428   );
6429
6430 /**
6431   Writes a value to Debug Register 4 (DR4).
6432
6433   Writes and returns a new value to DR4. This function is only available on
6434   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6435
6436   @param  Dr4 The value to write to Dr4.
6437
6438   @return The value written to Debug Register 4 (DR4).
6439
6440 **/
6441 UINTN
6442 EFIAPI
6443 AsmWriteDr4 (
6444   UINTN  Dr4
6445   );
6446
6447 /**
6448   Writes a value to Debug Register 5 (DR5).
6449
6450   Writes and returns a new value to DR5. This function is only available on
6451   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6452
6453   @param  Dr5 The value to write to Dr5.
6454
6455   @return The value written to Debug Register 5 (DR5).
6456
6457 **/
6458 UINTN
6459 EFIAPI
6460 AsmWriteDr5 (
6461   UINTN  Dr5
6462   );
6463
6464 /**
6465   Writes a value to Debug Register 6 (DR6).
6466
6467   Writes and returns a new value to DR6. This function is only available on
6468   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6469
6470   @param  Dr6 The value to write to Dr6.
6471
6472   @return The value written to Debug Register 6 (DR6).
6473
6474 **/
6475 UINTN
6476 EFIAPI
6477 AsmWriteDr6 (
6478   UINTN  Dr6
6479   );
6480
6481 /**
6482   Writes a value to Debug Register 7 (DR7).
6483
6484   Writes and returns a new value to DR7. This function is only available on
6485   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6486
6487   @param  Dr7 The value to write to Dr7.
6488
6489   @return The value written to Debug Register 7 (DR7).
6490
6491 **/
6492 UINTN
6493 EFIAPI
6494 AsmWriteDr7 (
6495   UINTN  Dr7
6496   );
6497
6498 /**
6499   Reads the current value of Code Segment Register (CS).
6500
6501   Reads and returns the current value of CS. This function is only available on
6502   IA-32 and x64.
6503
6504   @return The current value of CS.
6505
6506 **/
6507 UINT16
6508 EFIAPI
6509 AsmReadCs (
6510   VOID
6511   );
6512
6513 /**
6514   Reads the current value of Data Segment Register (DS).
6515
6516   Reads and returns the current value of DS. This function is only available on
6517   IA-32 and x64.
6518
6519   @return The current value of DS.
6520
6521 **/
6522 UINT16
6523 EFIAPI
6524 AsmReadDs (
6525   VOID
6526   );
6527
6528 /**
6529   Reads the current value of Extra Segment Register (ES).
6530
6531   Reads and returns the current value of ES. This function is only available on
6532   IA-32 and x64.
6533
6534   @return The current value of ES.
6535
6536 **/
6537 UINT16
6538 EFIAPI
6539 AsmReadEs (
6540   VOID
6541   );
6542
6543 /**
6544   Reads the current value of FS Data Segment Register (FS).
6545
6546   Reads and returns the current value of FS. This function is only available on
6547   IA-32 and x64.
6548
6549   @return The current value of FS.
6550
6551 **/
6552 UINT16
6553 EFIAPI
6554 AsmReadFs (
6555   VOID
6556   );
6557
6558 /**
6559   Reads the current value of GS Data Segment Register (GS).
6560
6561   Reads and returns the current value of GS. This function is only available on
6562   IA-32 and x64.
6563
6564   @return The current value of GS.
6565
6566 **/
6567 UINT16
6568 EFIAPI
6569 AsmReadGs (
6570   VOID
6571   );
6572
6573 /**
6574   Reads the current value of Stack Segment Register (SS).
6575
6576   Reads and returns the current value of SS. This function is only available on
6577   IA-32 and x64.
6578
6579   @return The current value of SS.
6580
6581 **/
6582 UINT16
6583 EFIAPI
6584 AsmReadSs (
6585   VOID
6586   );
6587
6588 /**
6589   Reads the current value of Task Register (TR).
6590
6591   Reads and returns the current value of TR. This function is only available on
6592   IA-32 and x64.
6593
6594   @return The current value of TR.
6595
6596 **/
6597 UINT16
6598 EFIAPI
6599 AsmReadTr (
6600   VOID
6601   );
6602
6603 /**
6604   Reads the current Global Descriptor Table Register(GDTR) descriptor.
6605
6606   Reads and returns the current GDTR descriptor and returns it in Gdtr. This
6607   function is only available on IA-32 and x64.
6608
6609   If Gdtr is NULL, then ASSERT().
6610
6611   @param  Gdtr  The pointer to a GDTR descriptor.
6612
6613 **/
6614 VOID
6615 EFIAPI
6616 AsmReadGdtr (
6617   OUT     IA32_DESCRIPTOR  *Gdtr
6618   );
6619
6620 /**
6621   Writes the current Global Descriptor Table Register (GDTR) descriptor.
6622
6623   Writes and the current GDTR descriptor specified by Gdtr. This function is
6624   only available on IA-32 and x64.
6625
6626   If Gdtr is NULL, then ASSERT().
6627
6628   @param  Gdtr  The pointer to a GDTR descriptor.
6629
6630 **/
6631 VOID
6632 EFIAPI
6633 AsmWriteGdtr (
6634   IN      CONST IA32_DESCRIPTOR  *Gdtr
6635   );
6636
6637 /**
6638   Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.
6639
6640   Reads and returns the current IDTR descriptor and returns it in Idtr. This
6641   function is only available on IA-32 and x64.
6642
6643   If Idtr is NULL, then ASSERT().
6644
6645   @param  Idtr  The pointer to a IDTR descriptor.
6646
6647 **/
6648 VOID
6649 EFIAPI
6650 AsmReadIdtr (
6651   OUT     IA32_DESCRIPTOR  *Idtr
6652   );
6653
6654 /**
6655   Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.
6656
6657   Writes the current IDTR descriptor and returns it in Idtr. This function is
6658   only available on IA-32 and x64.
6659
6660   If Idtr is NULL, then ASSERT().
6661
6662   @param  Idtr  The pointer to a IDTR descriptor.
6663
6664 **/
6665 VOID
6666 EFIAPI
6667 AsmWriteIdtr (
6668   IN      CONST IA32_DESCRIPTOR  *Idtr
6669   );
6670
6671 /**
6672   Reads the current Local Descriptor Table Register(LDTR) selector.
6673
6674   Reads and returns the current 16-bit LDTR descriptor value. This function is
6675   only available on IA-32 and x64.
6676
6677   @return The current selector of LDT.
6678
6679 **/
6680 UINT16
6681 EFIAPI
6682 AsmReadLdtr (
6683   VOID
6684   );
6685
6686 /**
6687   Writes the current Local Descriptor Table Register (LDTR) selector.
6688
6689   Writes and the current LDTR descriptor specified by Ldtr. This function is
6690   only available on IA-32 and x64.
6691
6692   @param  Ldtr  16-bit LDTR selector value.
6693
6694 **/
6695 VOID
6696 EFIAPI
6697 AsmWriteLdtr (
6698   IN      UINT16  Ldtr
6699   );
6700
6701 /**
6702   Save the current floating point/SSE/SSE2 context to a buffer.
6703
6704   Saves the current floating point/SSE/SSE2 state to the buffer specified by
6705   Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
6706   available on IA-32 and x64.
6707
6708   If Buffer is NULL, then ASSERT().
6709   If Buffer is not aligned on a 16-byte boundary, then ASSERT().
6710
6711   @param  Buffer  The pointer to a buffer to save the floating point/SSE/SSE2 context.
6712
6713 **/
6714 VOID
6715 EFIAPI
6716 AsmFxSave (
6717   OUT     IA32_FX_BUFFER  *Buffer
6718   );
6719
6720 /**
6721   Restores the current floating point/SSE/SSE2 context from a buffer.
6722
6723   Restores the current floating point/SSE/SSE2 state from the buffer specified
6724   by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
6725   only available on IA-32 and x64.
6726
6727   If Buffer is NULL, then ASSERT().
6728   If Buffer is not aligned on a 16-byte boundary, then ASSERT().
6729   If Buffer was not saved with AsmFxSave(), then ASSERT().
6730
6731   @param  Buffer  The pointer to a buffer to save the floating point/SSE/SSE2 context.
6732
6733 **/
6734 VOID
6735 EFIAPI
6736 AsmFxRestore (
6737   IN      CONST IA32_FX_BUFFER  *Buffer
6738   );
6739
6740 /**
6741   Reads the current value of 64-bit MMX Register #0 (MM0).
6742
6743   Reads and returns the current value of MM0. This function is only available
6744   on IA-32 and x64.
6745
6746   @return The current value of MM0.
6747
6748 **/
6749 UINT64
6750 EFIAPI
6751 AsmReadMm0 (
6752   VOID
6753   );
6754
6755 /**
6756   Reads the current value of 64-bit MMX Register #1 (MM1).
6757
6758   Reads and returns the current value of MM1. This function is only available
6759   on IA-32 and x64.
6760
6761   @return The current value of MM1.
6762
6763 **/
6764 UINT64
6765 EFIAPI
6766 AsmReadMm1 (
6767   VOID
6768   );
6769
6770 /**
6771   Reads the current value of 64-bit MMX Register #2 (MM2).
6772
6773   Reads and returns the current value of MM2. This function is only available
6774   on IA-32 and x64.
6775
6776   @return The current value of MM2.
6777
6778 **/
6779 UINT64
6780 EFIAPI
6781 AsmReadMm2 (
6782   VOID
6783   );
6784
6785 /**
6786   Reads the current value of 64-bit MMX Register #3 (MM3).
6787
6788   Reads and returns the current value of MM3. This function is only available
6789   on IA-32 and x64.
6790
6791   @return The current value of MM3.
6792
6793 **/
6794 UINT64
6795 EFIAPI
6796 AsmReadMm3 (
6797   VOID
6798   );
6799
6800 /**
6801   Reads the current value of 64-bit MMX Register #4 (MM4).
6802
6803   Reads and returns the current value of MM4. This function is only available
6804   on IA-32 and x64.
6805
6806   @return The current value of MM4.
6807
6808 **/
6809 UINT64
6810 EFIAPI
6811 AsmReadMm4 (
6812   VOID
6813   );
6814
6815 /**
6816   Reads the current value of 64-bit MMX Register #5 (MM5).
6817
6818   Reads and returns the current value of MM5. This function is only available
6819   on IA-32 and x64.
6820
6821   @return The current value of MM5.
6822
6823 **/
6824 UINT64
6825 EFIAPI
6826 AsmReadMm5 (
6827   VOID
6828   );
6829
6830 /**
6831   Reads the current value of 64-bit MMX Register #6 (MM6).
6832
6833   Reads and returns the current value of MM6. This function is only available
6834   on IA-32 and x64.
6835
6836   @return The current value of MM6.
6837
6838 **/
6839 UINT64
6840 EFIAPI
6841 AsmReadMm6 (
6842   VOID
6843   );
6844
6845 /**
6846   Reads the current value of 64-bit MMX Register #7 (MM7).
6847
6848   Reads and returns the current value of MM7. This function is only available
6849   on IA-32 and x64.
6850
6851   @return The current value of MM7.
6852
6853 **/
6854 UINT64
6855 EFIAPI
6856 AsmReadMm7 (
6857   VOID
6858   );
6859
6860 /**
6861   Writes the current value of 64-bit MMX Register #0 (MM0).
6862
6863   Writes the current value of MM0. This function is only available on IA32 and
6864   x64.
6865
6866   @param  Value The 64-bit value to write to MM0.
6867
6868 **/
6869 VOID
6870 EFIAPI
6871 AsmWriteMm0 (
6872   IN      UINT64  Value
6873   );
6874
6875 /**
6876   Writes the current value of 64-bit MMX Register #1 (MM1).
6877
6878   Writes the current value of MM1. This function is only available on IA32 and
6879   x64.
6880
6881   @param  Value The 64-bit value to write to MM1.
6882
6883 **/
6884 VOID
6885 EFIAPI
6886 AsmWriteMm1 (
6887   IN      UINT64  Value
6888   );
6889
6890 /**
6891   Writes the current value of 64-bit MMX Register #2 (MM2).
6892
6893   Writes the current value of MM2. This function is only available on IA32 and
6894   x64.
6895
6896   @param  Value The 64-bit value to write to MM2.
6897
6898 **/
6899 VOID
6900 EFIAPI
6901 AsmWriteMm2 (
6902   IN      UINT64  Value
6903   );
6904
6905 /**
6906   Writes the current value of 64-bit MMX Register #3 (MM3).
6907
6908   Writes the current value of MM3. This function is only available on IA32 and
6909   x64.
6910
6911   @param  Value The 64-bit value to write to MM3.
6912
6913 **/
6914 VOID
6915 EFIAPI
6916 AsmWriteMm3 (
6917   IN      UINT64  Value
6918   );
6919
6920 /**
6921   Writes the current value of 64-bit MMX Register #4 (MM4).
6922
6923   Writes the current value of MM4. This function is only available on IA32 and
6924   x64.
6925
6926   @param  Value The 64-bit value to write to MM4.
6927
6928 **/
6929 VOID
6930 EFIAPI
6931 AsmWriteMm4 (
6932   IN      UINT64  Value
6933   );
6934
6935 /**
6936   Writes the current value of 64-bit MMX Register #5 (MM5).
6937
6938   Writes the current value of MM5. This function is only available on IA32 and
6939   x64.
6940
6941   @param  Value The 64-bit value to write to MM5.
6942
6943 **/
6944 VOID
6945 EFIAPI
6946 AsmWriteMm5 (
6947   IN      UINT64  Value
6948   );
6949
6950 /**
6951   Writes the current value of 64-bit MMX Register #6 (MM6).
6952
6953   Writes the current value of MM6. This function is only available on IA32 and
6954   x64.
6955
6956   @param  Value The 64-bit value to write to MM6.
6957
6958 **/
6959 VOID
6960 EFIAPI
6961 AsmWriteMm6 (
6962   IN      UINT64  Value
6963   );
6964
6965 /**
6966   Writes the current value of 64-bit MMX Register #7 (MM7).
6967
6968   Writes the current value of MM7. This function is only available on IA32 and
6969   x64.
6970
6971   @param  Value The 64-bit value to write to MM7.
6972
6973 **/
6974 VOID
6975 EFIAPI
6976 AsmWriteMm7 (
6977   IN      UINT64  Value
6978   );
6979
6980 /**
6981   Reads the current value of Time Stamp Counter (TSC).
6982
6983   Reads and returns the current value of TSC. This function is only available
6984   on IA-32 and x64.
6985
6986   @return The current value of TSC
6987
6988 **/
6989 UINT64
6990 EFIAPI
6991 AsmReadTsc (
6992   VOID
6993   );
6994
6995 /**
6996   Reads the current value of a Performance Counter (PMC).
6997
6998   Reads and returns the current value of performance counter specified by
6999   Index. This function is only available on IA-32 and x64.
7000
7001   @param  Index The 32-bit Performance Counter index to read.
7002
7003   @return The value of the PMC specified by Index.
7004
7005 **/
7006 UINT64
7007 EFIAPI
7008 AsmReadPmc (
7009   IN      UINT32  Index
7010   );
7011
7012 /**
7013   Sets up a monitor buffer that is used by AsmMwait().
7014
7015   Executes a MONITOR instruction with the register state specified by Eax, Ecx
7016   and Edx. Returns Eax. This function is only available on IA-32 and x64.
7017
7018   @param  Eax The value to load into EAX or RAX before executing the MONITOR
7019               instruction.
7020   @param  Ecx The value to load into ECX or RCX before executing the MONITOR
7021               instruction.
7022   @param  Edx The value to load into EDX or RDX before executing the MONITOR
7023               instruction.
7024
7025   @return Eax
7026
7027 **/
7028 UINTN
7029 EFIAPI
7030 AsmMonitor (
7031   IN      UINTN  Eax,
7032   IN      UINTN  Ecx,
7033   IN      UINTN  Edx
7034   );
7035
7036 /**
7037   Executes an MWAIT instruction.
7038
7039   Executes an MWAIT instruction with the register state specified by Eax and
7040   Ecx. Returns Eax. This function is only available on IA-32 and x64.
7041
7042   @param  Eax The value to load into EAX or RAX before executing the MONITOR
7043               instruction.
7044   @param  Ecx The value to load into ECX or RCX before executing the MONITOR
7045               instruction.
7046
7047   @return Eax
7048
7049 **/
7050 UINTN
7051 EFIAPI
7052 AsmMwait (
7053   IN      UINTN  Eax,
7054   IN      UINTN  Ecx
7055   );
7056
7057 /**
7058   Executes a WBINVD instruction.
7059
7060   Executes a WBINVD instruction. This function is only available on IA-32 and
7061   x64.
7062
7063 **/
7064 VOID
7065 EFIAPI
7066 AsmWbinvd (
7067   VOID
7068   );
7069
7070 /**
7071   Executes a INVD instruction.
7072
7073   Executes a INVD instruction. This function is only available on IA-32 and
7074   x64.
7075
7076 **/
7077 VOID
7078 EFIAPI
7079 AsmInvd (
7080   VOID
7081   );
7082
7083 /**
7084   Flushes a cache line from all the instruction and data caches within the
7085   coherency domain of the CPU.
7086
7087   Flushed the cache line specified by LinearAddress, and returns LinearAddress.
7088   This function is only available on IA-32 and x64.
7089
7090   @param  LinearAddress The address of the cache line to flush. If the CPU is
7091                         in a physical addressing mode, then LinearAddress is a
7092                         physical address. If the CPU is in a virtual
7093                         addressing mode, then LinearAddress is a virtual
7094                         address.
7095
7096   @return LinearAddress.
7097 **/
7098 VOID *
7099 EFIAPI
7100 AsmFlushCacheLine (
7101   IN      VOID  *LinearAddress
7102   );
7103
7104 /**
7105   Enables the 32-bit paging mode on the CPU.
7106
7107   Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7108   must be properly initialized prior to calling this service. This function
7109   assumes the current execution mode is 32-bit protected mode. This function is
7110   only available on IA-32. After the 32-bit paging mode is enabled, control is
7111   transferred to the function specified by EntryPoint using the new stack
7112   specified by NewStack and passing in the parameters specified by Context1 and
7113   Context2. Context1 and Context2 are optional and may be NULL. The function
7114   EntryPoint must never return.
7115
7116   If the current execution mode is not 32-bit protected mode, then ASSERT().
7117   If EntryPoint is NULL, then ASSERT().
7118   If NewStack is NULL, then ASSERT().
7119
7120   There are a number of constraints that must be followed before calling this
7121   function:
7122   1)  Interrupts must be disabled.
7123   2)  The caller must be in 32-bit protected mode with flat descriptors. This
7124       means all descriptors must have a base of 0 and a limit of 4GB.
7125   3)  CR0 and CR4 must be compatible with 32-bit protected mode with flat
7126       descriptors.
7127   4)  CR3 must point to valid page tables that will be used once the transition
7128       is complete, and those page tables must guarantee that the pages for this
7129       function and the stack are identity mapped.
7130
7131   @param  EntryPoint  A pointer to function to call with the new stack after
7132                       paging is enabled.
7133   @param  Context1    A pointer to the context to pass into the EntryPoint
7134                       function as the first parameter after paging is enabled.
7135   @param  Context2    A pointer to the context to pass into the EntryPoint
7136                       function as the second parameter after paging is enabled.
7137   @param  NewStack    A pointer to the new stack to use for the EntryPoint
7138                       function after paging is enabled.
7139
7140 **/
7141 VOID
7142 EFIAPI
7143 AsmEnablePaging32 (
7144   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
7145   IN      VOID                      *Context1   OPTIONAL,
7146   IN      VOID                      *Context2   OPTIONAL,
7147   IN      VOID                      *NewStack
7148   );
7149
7150 /**
7151   Disables the 32-bit paging mode on the CPU.
7152
7153   Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
7154   mode. This function assumes the current execution mode is 32-paged protected
7155   mode. This function is only available on IA-32. After the 32-bit paging mode
7156   is disabled, control is transferred to the function specified by EntryPoint
7157   using the new stack specified by NewStack and passing in the parameters
7158   specified by Context1 and Context2. Context1 and Context2 are optional and
7159   may be NULL. The function EntryPoint must never return.
7160
7161   If the current execution mode is not 32-bit paged mode, then ASSERT().
7162   If EntryPoint is NULL, then ASSERT().
7163   If NewStack is NULL, then ASSERT().
7164
7165   There are a number of constraints that must be followed before calling this
7166   function:
7167   1)  Interrupts must be disabled.
7168   2)  The caller must be in 32-bit paged mode.
7169   3)  CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
7170   4)  CR3 must point to valid page tables that guarantee that the pages for
7171       this function and the stack are identity mapped.
7172
7173   @param  EntryPoint  A pointer to function to call with the new stack after
7174                       paging is disabled.
7175   @param  Context1    A pointer to the context to pass into the EntryPoint
7176                       function as the first parameter after paging is disabled.
7177   @param  Context2    A pointer to the context to pass into the EntryPoint
7178                       function as the second parameter after paging is
7179                       disabled.
7180   @param  NewStack    A pointer to the new stack to use for the EntryPoint
7181                       function after paging is disabled.
7182
7183 **/
7184 VOID
7185 EFIAPI
7186 AsmDisablePaging32 (
7187   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
7188   IN      VOID                      *Context1   OPTIONAL,
7189   IN      VOID                      *Context2   OPTIONAL,
7190   IN      VOID                      *NewStack
7191   );
7192
7193 /**
7194   Enables the 64-bit paging mode on the CPU.
7195
7196   Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7197   must be properly initialized prior to calling this service. This function
7198   assumes the current execution mode is 32-bit protected mode with flat
7199   descriptors. This function is only available on IA-32. After the 64-bit
7200   paging mode is enabled, control is transferred to the function specified by
7201   EntryPoint using the new stack specified by NewStack and passing in the
7202   parameters specified by Context1 and Context2. Context1 and Context2 are
7203   optional and may be 0. The function EntryPoint must never return.
7204
7205   If the current execution mode is not 32-bit protected mode with flat
7206   descriptors, then ASSERT().
7207   If EntryPoint is 0, then ASSERT().
7208   If NewStack is 0, then ASSERT().
7209
7210   @param  Cs          The 16-bit selector to load in the CS before EntryPoint
7211                       is called. The descriptor in the GDT that this selector
7212                       references must be setup for long mode.
7213   @param  EntryPoint  The 64-bit virtual address of the function to call with
7214                       the new stack after paging is enabled.
7215   @param  Context1    The 64-bit virtual address of the context to pass into
7216                       the EntryPoint function as the first parameter after
7217                       paging is enabled.
7218   @param  Context2    The 64-bit virtual address of the context to pass into
7219                       the EntryPoint function as the second parameter after
7220                       paging is enabled.
7221   @param  NewStack    The 64-bit virtual address of the new stack to use for
7222                       the EntryPoint function after paging is enabled.
7223
7224 **/
7225 VOID
7226 EFIAPI
7227 AsmEnablePaging64 (
7228   IN      UINT16  Cs,
7229   IN      UINT64  EntryPoint,
7230   IN      UINT64  Context1   OPTIONAL,
7231   IN      UINT64  Context2   OPTIONAL,
7232   IN      UINT64  NewStack
7233   );
7234
7235 /**
7236   Disables the 64-bit paging mode on the CPU.
7237
7238   Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
7239   mode. This function assumes the current execution mode is 64-paging mode.
7240   This function is only available on x64. After the 64-bit paging mode is
7241   disabled, control is transferred to the function specified by EntryPoint
7242   using the new stack specified by NewStack and passing in the parameters
7243   specified by Context1 and Context2. Context1 and Context2 are optional and
7244   may be 0. The function EntryPoint must never return.
7245
7246   If the current execution mode is not 64-bit paged mode, then ASSERT().
7247   If EntryPoint is 0, then ASSERT().
7248   If NewStack is 0, then ASSERT().
7249
7250   @param  Cs          The 16-bit selector to load in the CS before EntryPoint
7251                       is called. The descriptor in the GDT that this selector
7252                       references must be setup for 32-bit protected mode.
7253   @param  EntryPoint  The 64-bit virtual address of the function to call with
7254                       the new stack after paging is disabled.
7255   @param  Context1    The 64-bit virtual address of the context to pass into
7256                       the EntryPoint function as the first parameter after
7257                       paging is disabled.
7258   @param  Context2    The 64-bit virtual address of the context to pass into
7259                       the EntryPoint function as the second parameter after
7260                       paging is disabled.
7261   @param  NewStack    The 64-bit virtual address of the new stack to use for
7262                       the EntryPoint function after paging is disabled.
7263
7264 **/
7265 VOID
7266 EFIAPI
7267 AsmDisablePaging64 (
7268   IN      UINT16  Cs,
7269   IN      UINT32  EntryPoint,
7270   IN      UINT32  Context1   OPTIONAL,
7271   IN      UINT32  Context2   OPTIONAL,
7272   IN      UINT32  NewStack
7273   );
7274
7275 //
7276 // 16-bit thunking services
7277 //
7278
7279 /**
7280   Retrieves the properties for 16-bit thunk functions.
7281
7282   Computes the size of the buffer and stack below 1MB required to use the
7283   AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
7284   buffer size is returned in RealModeBufferSize, and the stack size is returned
7285   in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
7286   then the actual minimum stack size is ExtraStackSize plus the maximum number
7287   of bytes that need to be passed to the 16-bit real mode code.
7288
7289   If RealModeBufferSize is NULL, then ASSERT().
7290   If ExtraStackSize is NULL, then ASSERT().
7291
7292   @param  RealModeBufferSize  A pointer to the size of the buffer below 1MB
7293                               required to use the 16-bit thunk functions.
7294   @param  ExtraStackSize      A pointer to the extra size of stack below 1MB
7295                               that the 16-bit thunk functions require for
7296                               temporary storage in the transition to and from
7297                               16-bit real mode.
7298
7299 **/
7300 VOID
7301 EFIAPI
7302 AsmGetThunk16Properties (
7303   OUT     UINT32  *RealModeBufferSize,
7304   OUT     UINT32  *ExtraStackSize
7305   );
7306
7307 /**
7308   Prepares all structures a code required to use AsmThunk16().
7309
7310   Prepares all structures and code required to use AsmThunk16().
7311
7312   This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7313   virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7314
7315   If ThunkContext is NULL, then ASSERT().
7316
7317   @param  ThunkContext  A pointer to the context structure that describes the
7318                         16-bit real mode code to call.
7319
7320 **/
7321 VOID
7322 EFIAPI
7323 AsmPrepareThunk16 (
7324   IN OUT  THUNK_CONTEXT  *ThunkContext
7325   );
7326
7327 /**
7328   Transfers control to a 16-bit real mode entry point and returns the results.
7329
7330   Transfers control to a 16-bit real mode entry point and returns the results.
7331   AsmPrepareThunk16() must be called with ThunkContext before this function is used.
7332   This function must be called with interrupts disabled.
7333
7334   The register state from the RealModeState field of ThunkContext is restored just prior
7335   to calling the 16-bit real mode entry point.  This includes the EFLAGS field of RealModeState,
7336   which is used to set the interrupt state when a 16-bit real mode entry point is called.
7337   Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
7338   The stack is initialized to the SS and ESP fields of RealModeState.  Any parameters passed to
7339   the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
7340   The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
7341   so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
7342   and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
7343   point must exit with a RETF instruction. The register state is captured into RealModeState immediately
7344   after the RETF instruction is executed.
7345
7346   If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7347   or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
7348   the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
7349
7350   If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7351   then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
7352   This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
7353
7354   If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
7355   is invoked in big real mode.  Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
7356
7357   If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7358   ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
7359   disable the A20 mask.
7360
7361   If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
7362   ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask.  If this INT 15 call fails,
7363   then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7364
7365   If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
7366   ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7367
7368   If ThunkContext is NULL, then ASSERT().
7369   If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
7370   If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7371   ThunkAttributes, then ASSERT().
7372
7373   This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7374   virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1.
7375
7376   @param  ThunkContext  A pointer to the context structure that describes the
7377                         16-bit real mode code to call.
7378
7379 **/
7380 VOID
7381 EFIAPI
7382 AsmThunk16 (
7383   IN OUT  THUNK_CONTEXT  *ThunkContext
7384   );
7385
7386 /**
7387   Prepares all structures and code for a 16-bit real mode thunk, transfers
7388   control to a 16-bit real mode entry point, and returns the results.
7389
7390   Prepares all structures and code for a 16-bit real mode thunk, transfers
7391   control to a 16-bit real mode entry point, and returns the results. If the
7392   caller only need to perform a single 16-bit real mode thunk, then this
7393   service should be used. If the caller intends to make more than one 16-bit
7394   real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
7395   once and AsmThunk16() can be called for each 16-bit real mode thunk.
7396
7397   This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7398   virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7399
7400   See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
7401
7402   @param  ThunkContext  A pointer to the context structure that describes the
7403                         16-bit real mode code to call.
7404
7405 **/
7406 VOID
7407 EFIAPI
7408 AsmPrepareAndThunk16 (
7409   IN OUT  THUNK_CONTEXT  *ThunkContext
7410   );
7411
7412 /**
7413   Generates a 16-bit random number through RDRAND instruction.
7414
7415   if Rand is NULL, then ASSERT().
7416
7417   @param[out]  Rand     Buffer pointer to store the random result.
7418
7419   @retval TRUE          RDRAND call was successful.
7420   @retval FALSE         Failed attempts to call RDRAND.
7421
7422  **/
7423 BOOLEAN
7424 EFIAPI
7425 AsmRdRand16 (
7426   OUT     UINT16  *Rand
7427   );
7428
7429 /**
7430   Generates a 32-bit random number through RDRAND instruction.
7431
7432   if Rand is NULL, then ASSERT().
7433
7434   @param[out]  Rand     Buffer pointer to store the random result.
7435
7436   @retval TRUE          RDRAND call was successful.
7437   @retval FALSE         Failed attempts to call RDRAND.
7438
7439 **/
7440 BOOLEAN
7441 EFIAPI
7442 AsmRdRand32 (
7443   OUT     UINT32  *Rand
7444   );
7445
7446 /**
7447   Generates a 64-bit random number through RDRAND instruction.
7448
7449   if Rand is NULL, then ASSERT().
7450
7451   @param[out]  Rand     Buffer pointer to store the random result.
7452
7453   @retval TRUE          RDRAND call was successful.
7454   @retval FALSE         Failed attempts to call RDRAND.
7455
7456 **/
7457 BOOLEAN
7458 EFIAPI
7459 AsmRdRand64  (
7460   OUT     UINT64  *Rand
7461   );
7462
7463 /**
7464   Load given selector into TR register.
7465
7466   @param[in] Selector     Task segment selector
7467 **/
7468 VOID
7469 EFIAPI
7470 AsmWriteTr (
7471   IN UINT16  Selector
7472   );
7473
7474 /**
7475   Performs a serializing operation on all load-from-memory instructions that
7476   were issued prior the AsmLfence function.
7477
7478   Executes a LFENCE instruction. This function is only available on IA-32 and x64.
7479
7480 **/
7481 VOID
7482 EFIAPI
7483 AsmLfence (
7484   VOID
7485   );
7486
7487 /**
7488   Executes a XGETBV instruction
7489
7490   Executes a XGETBV instruction. This function is only available on IA-32 and
7491   x64.
7492
7493   @param[in] Index        Extended control register index
7494
7495   @return                 The current value of the extended control register
7496 **/
7497 UINT64
7498 EFIAPI
7499 AsmXGetBv (
7500   IN UINT32  Index
7501   );
7502
7503 /**
7504   Executes a XSETBV instruction to write a 64-bit value to a Extended Control
7505   Register(XCR), and returns the value.
7506
7507   Writes the 64-bit value specified by Value to the XCR specified by Index. The
7508   64-bit value written to the XCR is returned. No parameter checking is
7509   performed on Index or Value, and some of these may cause CPU exceptions. The
7510   caller must either guarantee that Index and Value are valid, or the caller
7511   must establish proper exception handlers. This function is only available on
7512   IA-32 and x64.
7513
7514   @param  Index The 32-bit XCR index to write.
7515   @param  Value The 64-bit value to write to the XCR.
7516
7517   @return Value
7518
7519 **/
7520 UINT64
7521 EFIAPI
7522 AsmXSetBv (
7523   IN UINT32  Index,
7524   IN UINT64  Value
7525   );
7526
7527 /**
7528   Executes a VMGEXIT instruction (VMMCALL with a REP prefix)
7529
7530   Executes a VMGEXIT instruction. This function is only available on IA-32 and
7531   x64.
7532
7533 **/
7534 VOID
7535 EFIAPI
7536 AsmVmgExit (
7537   VOID
7538   );
7539
7540 /**
7541   Patch the immediate operand of an IA32 or X64 instruction such that the byte,
7542   word, dword or qword operand is encoded at the end of the instruction's
7543   binary representation.
7544
7545   This function should be used to update object code that was compiled with
7546   NASM from assembly source code. Example:
7547
7548   NASM source code:
7549
7550         mov     eax, strict dword 0 ; the imm32 zero operand will be patched
7551     ASM_PFX(gPatchCr3):
7552         mov     cr3, eax
7553
7554   C source code:
7555
7556     X86_ASSEMBLY_PATCH_LABEL gPatchCr3;
7557     PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);
7558
7559   @param[out] InstructionEnd  Pointer right past the instruction to patch. The
7560                               immediate operand to patch is expected to
7561                               comprise the trailing bytes of the instruction.
7562                               If InstructionEnd is closer to address 0 than
7563                               ValueSize permits, then ASSERT().
7564
7565   @param[in] PatchValue       The constant to write to the immediate operand.
7566                               The caller is responsible for ensuring that
7567                               PatchValue can be represented in the byte, word,
7568                               dword or qword operand (as indicated through
7569                               ValueSize); otherwise ASSERT().
7570
7571   @param[in] ValueSize        The size of the operand in bytes; must be 1, 2,
7572                               4, or 8. ASSERT() otherwise.
7573 **/
7574 VOID
7575 EFIAPI
7576 PatchInstructionX86 (
7577   OUT X86_ASSEMBLY_PATCH_LABEL  *InstructionEnd,
7578   IN  UINT64                    PatchValue,
7579   IN  UINTN                     ValueSize
7580   );
7581
7582 #endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
7583 #endif // !defined (__BASE_LIB__)