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