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   Convert Base64 ascii string to binary data based on RFC4648.
2789
2790   Produce Null-terminated binary data in the output buffer specified by Destination and DestinationSize.
2791   The binary data is produced by converting the Base64 ascii string specified by Source and SourceLength.
2792
2793   @param Source          Input ASCII characters
2794   @param SourceLength    Number of ASCII characters
2795   @param Destination     Pointer to output buffer
2796   @param DestinationSize Caller is responsible for passing in buffer of at least DestinationSize.
2797                          Set 0 to get the size needed. Set to bytes stored on return.
2798
2799   @retval RETURN_SUCCESS             When binary buffer is filled in.
2800   @retval RETURN_INVALID_PARAMETER   If Source is NULL or DestinationSize is NULL.
2801   @retval RETURN_INVALID_PARAMETER   If SourceLength or DestinationSize is bigger than (MAX_ADDRESS -(UINTN)Destination ).
2802   @retval RETURN_INVALID_PARAMETER   If there is any invalid character in input stream.
2803   @retval RETURN_BUFFER_TOO_SMALL    If buffer length is smaller than required buffer size.
2804
2805  **/
2806 RETURN_STATUS
2807 EFIAPI
2808 Base64Decode (
2809   IN  CONST CHAR8  *Source,
2810   IN        UINTN   SourceLength,
2811   OUT       UINT8  *Destination  OPTIONAL,
2812   IN OUT    UINTN  *DestinationSize
2813   );
2814
2815 /**
2816   Converts an 8-bit value to an 8-bit BCD value.
2817
2818   Converts the 8-bit value specified by Value to BCD. The BCD value is
2819   returned.
2820
2821   If Value >= 100, then ASSERT().
2822
2823   @param  Value The 8-bit value to convert to BCD. Range 0..99.
2824
2825   @return The BCD value.
2826
2827 **/
2828 UINT8
2829 EFIAPI
2830 DecimalToBcd8 (
2831   IN      UINT8                     Value
2832   );
2833
2834
2835 /**
2836   Converts an 8-bit BCD value to an 8-bit value.
2837
2838   Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2839   value is returned.
2840
2841   If Value >= 0xA0, then ASSERT().
2842   If (Value & 0x0F) >= 0x0A, then ASSERT().
2843
2844   @param  Value The 8-bit BCD value to convert to an 8-bit value.
2845
2846   @return The 8-bit value is returned.
2847
2848 **/
2849 UINT8
2850 EFIAPI
2851 BcdToDecimal8 (
2852   IN      UINT8                     Value
2853   );
2854
2855 //
2856 //  File Path Manipulation Functions
2857 //
2858
2859 /**
2860   Removes the last directory or file entry in a path.
2861
2862   @param[in, out] Path    The pointer to the path to modify.
2863
2864   @retval FALSE     Nothing was found to remove.
2865   @retval TRUE      A directory or file was removed.
2866 **/
2867 BOOLEAN
2868 EFIAPI
2869 PathRemoveLastItem(
2870   IN OUT CHAR16 *Path
2871   );
2872
2873 /**
2874   Function to clean up paths.
2875     - Single periods in the path are removed.
2876     - Double periods in the path are removed along with a single parent directory.
2877     - Forward slashes L'/' are converted to backward slashes L'\'.
2878
2879   This will be done inline and the existing buffer may be larger than required
2880   upon completion.
2881
2882   @param[in] Path       The pointer to the string containing the path.
2883
2884   @return       Returns Path, otherwise returns NULL to indicate that an error has occurred.
2885 **/
2886 CHAR16*
2887 EFIAPI
2888 PathCleanUpDirectories(
2889   IN CHAR16 *Path
2890   );
2891
2892 //
2893 // Linked List Functions and Macros
2894 //
2895
2896 /**
2897   Initializes the head node of a doubly linked list that is declared as a
2898   global variable in a module.
2899
2900   Initializes the forward and backward links of a new linked list. After
2901   initializing a linked list with this macro, the other linked list functions
2902   may be used to add and remove nodes from the linked list. This macro results
2903   in smaller executables by initializing the linked list in the data section,
2904   instead if calling the InitializeListHead() function to perform the
2905   equivalent operation.
2906
2907   @param  ListHead  The head note of a list to initialize.
2908
2909 **/
2910 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead)  {&(ListHead), &(ListHead)}
2911
2912
2913 /**
2914   Checks whether FirstEntry and SecondEntry are part of the same doubly-linked
2915   list.
2916
2917   If FirstEntry is NULL, then ASSERT().
2918   If FirstEntry->ForwardLink is NULL, then ASSERT().
2919   If FirstEntry->BackLink is NULL, then ASSERT().
2920   If SecondEntry is NULL, then ASSERT();
2921   If PcdMaximumLinkedListLength is not zero, and List contains more than
2922   PcdMaximumLinkedListLength nodes, then ASSERT().
2923
2924   @param  FirstEntry   A pointer to a node in a linked list.
2925   @param  SecondEntry  A pointer to the node to locate.
2926
2927   @retval TRUE   SecondEntry is in the same doubly-linked list as FirstEntry.
2928   @retval FALSE  SecondEntry isn't in the same doubly-linked list as FirstEntry,
2929                  or FirstEntry is invalid.
2930
2931 **/
2932 BOOLEAN
2933 EFIAPI
2934 IsNodeInList (
2935   IN      CONST LIST_ENTRY      *FirstEntry,
2936   IN      CONST LIST_ENTRY      *SecondEntry
2937   );
2938
2939
2940 /**
2941   Initializes the head node of a doubly linked list, and returns the pointer to
2942   the head node of the doubly linked list.
2943
2944   Initializes the forward and backward links of a new linked list. After
2945   initializing a linked list with this function, the other linked list
2946   functions may be used to add and remove nodes from the linked list. It is up
2947   to the caller of this function to allocate the memory for ListHead.
2948
2949   If ListHead is NULL, then ASSERT().
2950
2951   @param  ListHead  A pointer to the head node of a new doubly linked list.
2952
2953   @return ListHead
2954
2955 **/
2956 LIST_ENTRY *
2957 EFIAPI
2958 InitializeListHead (
2959   IN OUT  LIST_ENTRY                *ListHead
2960   );
2961
2962
2963 /**
2964   Adds a node to the beginning of a doubly linked list, and returns the pointer
2965   to the head node of the doubly linked list.
2966
2967   Adds the node Entry at the beginning of the doubly linked list denoted by
2968   ListHead, and returns ListHead.
2969
2970   If ListHead is NULL, then ASSERT().
2971   If Entry is NULL, then ASSERT().
2972   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2973   InitializeListHead(), then ASSERT().
2974   If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2975   of nodes in ListHead, including the ListHead node, is greater than or
2976   equal to PcdMaximumLinkedListLength, then ASSERT().
2977
2978   @param  ListHead  A pointer to the head node of a doubly linked list.
2979   @param  Entry     A pointer to a node that is to be inserted at the beginning
2980                     of a doubly linked list.
2981
2982   @return ListHead
2983
2984 **/
2985 LIST_ENTRY *
2986 EFIAPI
2987 InsertHeadList (
2988   IN OUT  LIST_ENTRY                *ListHead,
2989   IN OUT  LIST_ENTRY                *Entry
2990   );
2991
2992
2993 /**
2994   Adds a node to the end of a doubly linked list, and returns the pointer to
2995   the head node of the doubly linked list.
2996
2997   Adds the node Entry to the end of the doubly linked list denoted by ListHead,
2998   and returns ListHead.
2999
3000   If ListHead is NULL, then ASSERT().
3001   If Entry is NULL, then ASSERT().
3002   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3003   InitializeListHead(), then ASSERT().
3004   If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
3005   of nodes in ListHead, including the ListHead node, is greater than or
3006   equal to PcdMaximumLinkedListLength, then ASSERT().
3007
3008   @param  ListHead  A pointer to the head node of a doubly linked list.
3009   @param  Entry     A pointer to a node that is to be added at the end of the
3010                     doubly linked list.
3011
3012   @return ListHead
3013
3014 **/
3015 LIST_ENTRY *
3016 EFIAPI
3017 InsertTailList (
3018   IN OUT  LIST_ENTRY                *ListHead,
3019   IN OUT  LIST_ENTRY                *Entry
3020   );
3021
3022
3023 /**
3024   Retrieves the first node of a doubly linked list.
3025
3026   Returns the first node of a doubly linked list.  List must have been
3027   initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3028   If List is empty, then List is returned.
3029
3030   If List is NULL, then ASSERT().
3031   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3032   InitializeListHead(), then ASSERT().
3033   If PcdMaximumLinkedListLength is not zero, and the number of nodes
3034   in List, including the List node, is greater than or equal to
3035   PcdMaximumLinkedListLength, then ASSERT().
3036
3037   @param  List  A pointer to the head node of a doubly linked list.
3038
3039   @return The first node of a doubly linked list.
3040   @retval List  The list is empty.
3041
3042 **/
3043 LIST_ENTRY *
3044 EFIAPI
3045 GetFirstNode (
3046   IN      CONST LIST_ENTRY          *List
3047   );
3048
3049
3050 /**
3051   Retrieves the next node of a doubly linked list.
3052
3053   Returns the node of a doubly linked list that follows Node.
3054   List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3055   or InitializeListHead().  If List is empty, then List is returned.
3056
3057   If List is NULL, then ASSERT().
3058   If Node is NULL, then ASSERT().
3059   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3060   InitializeListHead(), then ASSERT().
3061   If PcdMaximumLinkedListLength is not zero, and List contains more than
3062   PcdMaximumLinkedListLength nodes, then ASSERT().
3063   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3064
3065   @param  List  A pointer to the head node of a doubly linked list.
3066   @param  Node  A pointer to a node in the doubly linked list.
3067
3068   @return The pointer to the next node if one exists. Otherwise List is returned.
3069
3070 **/
3071 LIST_ENTRY *
3072 EFIAPI
3073 GetNextNode (
3074   IN      CONST LIST_ENTRY          *List,
3075   IN      CONST LIST_ENTRY          *Node
3076   );
3077
3078
3079 /**
3080   Retrieves the previous node of a doubly linked list.
3081
3082   Returns the node of a doubly linked list that precedes Node.
3083   List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3084   or InitializeListHead().  If List is empty, then List is returned.
3085
3086   If List is NULL, then ASSERT().
3087   If Node is NULL, then ASSERT().
3088   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3089   InitializeListHead(), then ASSERT().
3090   If PcdMaximumLinkedListLength is not zero, and List contains more than
3091   PcdMaximumLinkedListLength nodes, then ASSERT().
3092   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3093
3094   @param  List  A pointer to the head node of a doubly linked list.
3095   @param  Node  A pointer to a node in the doubly linked list.
3096
3097   @return The pointer to the previous node if one exists. Otherwise List is returned.
3098
3099 **/
3100 LIST_ENTRY *
3101 EFIAPI
3102 GetPreviousNode (
3103   IN      CONST LIST_ENTRY          *List,
3104   IN      CONST LIST_ENTRY          *Node
3105   );
3106
3107
3108 /**
3109   Checks to see if a doubly linked list is empty or not.
3110
3111   Checks to see if the doubly linked list is empty. If the linked list contains
3112   zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
3113
3114   If ListHead is NULL, then ASSERT().
3115   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3116   InitializeListHead(), then ASSERT().
3117   If PcdMaximumLinkedListLength is not zero, and the number of nodes
3118   in List, including the List node, is greater than or equal to
3119   PcdMaximumLinkedListLength, then ASSERT().
3120
3121   @param  ListHead  A pointer to the head node of a doubly linked list.
3122
3123   @retval TRUE  The linked list is empty.
3124   @retval FALSE The linked list is not empty.
3125
3126 **/
3127 BOOLEAN
3128 EFIAPI
3129 IsListEmpty (
3130   IN      CONST LIST_ENTRY          *ListHead
3131   );
3132
3133
3134 /**
3135   Determines if a node in a doubly linked list is the head node of a the same
3136   doubly linked list.  This function is typically used to terminate a loop that
3137   traverses all the nodes in a doubly linked list starting with the head node.
3138
3139   Returns TRUE if Node is equal to List.  Returns FALSE if Node is one of the
3140   nodes in the doubly linked list specified by List.  List must have been
3141   initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3142
3143   If List is NULL, then ASSERT().
3144   If Node is NULL, then ASSERT().
3145   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
3146   then ASSERT().
3147   If PcdMaximumLinkedListLength is not zero, and the number of nodes
3148   in List, including the List node, is greater than or equal to
3149   PcdMaximumLinkedListLength, then ASSERT().
3150   If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
3151   to List, then ASSERT().
3152
3153   @param  List  A pointer to the head node of a doubly linked list.
3154   @param  Node  A pointer to a node in the doubly linked list.
3155
3156   @retval TRUE  Node is the head of the doubly-linked list pointed by List.
3157   @retval FALSE Node is not the head of the doubly-linked list pointed by List.
3158
3159 **/
3160 BOOLEAN
3161 EFIAPI
3162 IsNull (
3163   IN      CONST LIST_ENTRY          *List,
3164   IN      CONST LIST_ENTRY          *Node
3165   );
3166
3167
3168 /**
3169   Determines if a node the last node in a doubly linked list.
3170
3171   Returns TRUE if Node is the last node in the doubly linked list specified by
3172   List. Otherwise, FALSE is returned. List must have been initialized with
3173   INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3174
3175   If List is NULL, then ASSERT().
3176   If Node is NULL, then ASSERT().
3177   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3178   InitializeListHead(), then ASSERT().
3179   If PcdMaximumLinkedListLength is not zero, and the number of nodes
3180   in List, including the List node, is greater than or equal to
3181   PcdMaximumLinkedListLength, then ASSERT().
3182   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3183
3184   @param  List  A pointer to the head node of a doubly linked list.
3185   @param  Node  A pointer to a node in the doubly linked list.
3186
3187   @retval TRUE  Node is the last node in the linked list.
3188   @retval FALSE Node is not the last node in the linked list.
3189
3190 **/
3191 BOOLEAN
3192 EFIAPI
3193 IsNodeAtEnd (
3194   IN      CONST LIST_ENTRY          *List,
3195   IN      CONST LIST_ENTRY          *Node
3196   );
3197
3198
3199 /**
3200   Swaps the location of two nodes in a doubly linked list, and returns the
3201   first node after the swap.
3202
3203   If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
3204   Otherwise, the location of the FirstEntry node is swapped with the location
3205   of the SecondEntry node in a doubly linked list. SecondEntry must be in the
3206   same double linked list as FirstEntry and that double linked list must have
3207   been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3208   SecondEntry is returned after the nodes are swapped.
3209
3210   If FirstEntry is NULL, then ASSERT().
3211   If SecondEntry is NULL, then ASSERT().
3212   If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
3213   same linked list, then ASSERT().
3214   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3215   linked list containing the FirstEntry and SecondEntry nodes, including
3216   the FirstEntry and SecondEntry nodes, is greater than or equal to
3217   PcdMaximumLinkedListLength, then ASSERT().
3218
3219   @param  FirstEntry  A pointer to a node in a linked list.
3220   @param  SecondEntry A pointer to another node in the same linked list.
3221
3222   @return SecondEntry.
3223
3224 **/
3225 LIST_ENTRY *
3226 EFIAPI
3227 SwapListEntries (
3228   IN OUT  LIST_ENTRY                *FirstEntry,
3229   IN OUT  LIST_ENTRY                *SecondEntry
3230   );
3231
3232
3233 /**
3234   Removes a node from a doubly linked list, and returns the node that follows
3235   the removed node.
3236
3237   Removes the node Entry from a doubly linked list. It is up to the caller of
3238   this function to release the memory used by this node if that is required. On
3239   exit, the node following Entry in the doubly linked list is returned. If
3240   Entry is the only node in the linked list, then the head node of the linked
3241   list is returned.
3242
3243   If Entry is NULL, then ASSERT().
3244   If Entry is the head node of an empty list, then ASSERT().
3245   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3246   linked list containing Entry, including the Entry node, is greater than
3247   or equal to PcdMaximumLinkedListLength, then ASSERT().
3248
3249   @param  Entry A pointer to a node in a linked list.
3250
3251   @return Entry.
3252
3253 **/
3254 LIST_ENTRY *
3255 EFIAPI
3256 RemoveEntryList (
3257   IN      CONST LIST_ENTRY          *Entry
3258   );
3259
3260 //
3261 // Math Services
3262 //
3263
3264 /**
3265   Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
3266   with zeros. The shifted value is returned.
3267
3268   This function shifts the 64-bit value Operand to the left by Count bits. The
3269   low Count bits are set to zero. The shifted value is returned.
3270
3271   If Count is greater than 63, then ASSERT().
3272
3273   @param  Operand The 64-bit operand to shift left.
3274   @param  Count   The number of bits to shift left.
3275
3276   @return Operand << Count.
3277
3278 **/
3279 UINT64
3280 EFIAPI
3281 LShiftU64 (
3282   IN      UINT64                    Operand,
3283   IN      UINTN                     Count
3284   );
3285
3286
3287 /**
3288   Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
3289   filled with zeros. The shifted value is returned.
3290
3291   This function shifts the 64-bit value Operand to the right by Count bits. The
3292   high Count bits are set to zero. The shifted value is returned.
3293
3294   If Count is greater than 63, then ASSERT().
3295
3296   @param  Operand The 64-bit operand to shift right.
3297   @param  Count   The number of bits to shift right.
3298
3299   @return Operand >> Count
3300
3301 **/
3302 UINT64
3303 EFIAPI
3304 RShiftU64 (
3305   IN      UINT64                    Operand,
3306   IN      UINTN                     Count
3307   );
3308
3309
3310 /**
3311   Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
3312   with original integer's bit 63. The shifted value is returned.
3313
3314   This function shifts the 64-bit value Operand to the right by Count bits. The
3315   high Count bits are set to bit 63 of Operand.  The shifted value is returned.
3316
3317   If Count is greater than 63, then ASSERT().
3318
3319   @param  Operand The 64-bit operand to shift right.
3320   @param  Count   The number of bits to shift right.
3321
3322   @return Operand >> Count
3323
3324 **/
3325 UINT64
3326 EFIAPI
3327 ARShiftU64 (
3328   IN      UINT64                    Operand,
3329   IN      UINTN                     Count
3330   );
3331
3332
3333 /**
3334   Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
3335   with the high bits that were rotated.
3336
3337   This function rotates the 32-bit value Operand to the left by Count bits. The
3338   low Count bits are fill with the high Count bits of Operand. The rotated
3339   value is returned.
3340
3341   If Count is greater than 31, then ASSERT().
3342
3343   @param  Operand The 32-bit operand to rotate left.
3344   @param  Count   The number of bits to rotate left.
3345
3346   @return Operand << Count
3347
3348 **/
3349 UINT32
3350 EFIAPI
3351 LRotU32 (
3352   IN      UINT32                    Operand,
3353   IN      UINTN                     Count
3354   );
3355
3356
3357 /**
3358   Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
3359   with the low bits that were rotated.
3360
3361   This function rotates the 32-bit value Operand to the right by Count bits.
3362   The high Count bits are fill with the low Count bits of Operand. The rotated
3363   value is returned.
3364
3365   If Count is greater than 31, then ASSERT().
3366
3367   @param  Operand The 32-bit operand to rotate right.
3368   @param  Count   The number of bits to rotate right.
3369
3370   @return Operand >> Count
3371
3372 **/
3373 UINT32
3374 EFIAPI
3375 RRotU32 (
3376   IN      UINT32                    Operand,
3377   IN      UINTN                     Count
3378   );
3379
3380
3381 /**
3382   Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
3383   with the high bits that were rotated.
3384
3385   This function rotates the 64-bit value Operand to the left by Count bits. The
3386   low Count bits are fill with the high Count bits of Operand. The rotated
3387   value is returned.
3388
3389   If Count is greater than 63, then ASSERT().
3390
3391   @param  Operand The 64-bit operand to rotate left.
3392   @param  Count   The number of bits to rotate left.
3393
3394   @return Operand << Count
3395
3396 **/
3397 UINT64
3398 EFIAPI
3399 LRotU64 (
3400   IN      UINT64                    Operand,
3401   IN      UINTN                     Count
3402   );
3403
3404
3405 /**
3406   Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
3407   with the high low bits that were rotated.
3408
3409   This function rotates the 64-bit value Operand to the right by Count bits.
3410   The high Count bits are fill with the low Count bits of Operand. The rotated
3411   value is returned.
3412
3413   If Count is greater than 63, then ASSERT().
3414
3415   @param  Operand The 64-bit operand to rotate right.
3416   @param  Count   The number of bits to rotate right.
3417
3418   @return Operand >> Count
3419
3420 **/
3421 UINT64
3422 EFIAPI
3423 RRotU64 (
3424   IN      UINT64                    Operand,
3425   IN      UINTN                     Count
3426   );
3427
3428
3429 /**
3430   Returns the bit position of the lowest bit set in a 32-bit value.
3431
3432   This function computes the bit position of the lowest bit set in the 32-bit
3433   value specified by Operand. If Operand is zero, then -1 is returned.
3434   Otherwise, a value between 0 and 31 is returned.
3435
3436   @param  Operand The 32-bit operand to evaluate.
3437
3438   @retval 0..31  The lowest bit set in Operand was found.
3439   @retval -1    Operand is zero.
3440
3441 **/
3442 INTN
3443 EFIAPI
3444 LowBitSet32 (
3445   IN      UINT32                    Operand
3446   );
3447
3448
3449 /**
3450   Returns the bit position of the lowest bit set in a 64-bit value.
3451
3452   This function computes the bit position of the lowest bit set in the 64-bit
3453   value specified by Operand. If Operand is zero, then -1 is returned.
3454   Otherwise, a value between 0 and 63 is returned.
3455
3456   @param  Operand The 64-bit operand to evaluate.
3457
3458   @retval 0..63  The lowest bit set in Operand was found.
3459   @retval -1    Operand is zero.
3460
3461
3462 **/
3463 INTN
3464 EFIAPI
3465 LowBitSet64 (
3466   IN      UINT64                    Operand
3467   );
3468
3469
3470 /**
3471   Returns the bit position of the highest bit set in a 32-bit value. Equivalent
3472   to log2(x).
3473
3474   This function computes the bit position of the highest bit set in the 32-bit
3475   value specified by Operand. If Operand is zero, then -1 is returned.
3476   Otherwise, a value between 0 and 31 is returned.
3477
3478   @param  Operand The 32-bit operand to evaluate.
3479
3480   @retval 0..31  Position of the highest bit set in Operand if found.
3481   @retval -1    Operand is zero.
3482
3483 **/
3484 INTN
3485 EFIAPI
3486 HighBitSet32 (
3487   IN      UINT32                    Operand
3488   );
3489
3490
3491 /**
3492   Returns the bit position of the highest bit set in a 64-bit value. Equivalent
3493   to log2(x).
3494
3495   This function computes the bit position of the highest bit set in the 64-bit
3496   value specified by Operand. If Operand is zero, then -1 is returned.
3497   Otherwise, a value between 0 and 63 is returned.
3498
3499   @param  Operand The 64-bit operand to evaluate.
3500
3501   @retval 0..63   Position of the highest bit set in Operand if found.
3502   @retval -1     Operand is zero.
3503
3504 **/
3505 INTN
3506 EFIAPI
3507 HighBitSet64 (
3508   IN      UINT64                    Operand
3509   );
3510
3511
3512 /**
3513   Returns the value of the highest bit set in a 32-bit value. Equivalent to
3514   1 << log2(x).
3515
3516   This function computes the value of the highest bit set in the 32-bit value
3517   specified by Operand. If Operand is zero, then zero is returned.
3518
3519   @param  Operand The 32-bit operand to evaluate.
3520
3521   @return 1 << HighBitSet32(Operand)
3522   @retval 0 Operand is zero.
3523
3524 **/
3525 UINT32
3526 EFIAPI
3527 GetPowerOfTwo32 (
3528   IN      UINT32                    Operand
3529   );
3530
3531
3532 /**
3533   Returns the value of the highest bit set in a 64-bit value. Equivalent to
3534   1 << log2(x).
3535
3536   This function computes the value of the highest bit set in the 64-bit value
3537   specified by Operand. If Operand is zero, then zero is returned.
3538
3539   @param  Operand The 64-bit operand to evaluate.
3540
3541   @return 1 << HighBitSet64(Operand)
3542   @retval 0 Operand is zero.
3543
3544 **/
3545 UINT64
3546 EFIAPI
3547 GetPowerOfTwo64 (
3548   IN      UINT64                    Operand
3549   );
3550
3551
3552 /**
3553   Switches the endianness of a 16-bit integer.
3554
3555   This function swaps the bytes in a 16-bit unsigned value to switch the value
3556   from little endian to big endian or vice versa. The byte swapped value is
3557   returned.
3558
3559   @param  Value A 16-bit unsigned value.
3560
3561   @return The byte swapped Value.
3562
3563 **/
3564 UINT16
3565 EFIAPI
3566 SwapBytes16 (
3567   IN      UINT16                    Value
3568   );
3569
3570
3571 /**
3572   Switches the endianness of a 32-bit integer.
3573
3574   This function swaps the bytes in a 32-bit unsigned value to switch the value
3575   from little endian to big endian or vice versa. The byte swapped value is
3576   returned.
3577
3578   @param  Value A 32-bit unsigned value.
3579
3580   @return The byte swapped Value.
3581
3582 **/
3583 UINT32
3584 EFIAPI
3585 SwapBytes32 (
3586   IN      UINT32                    Value
3587   );
3588
3589
3590 /**
3591   Switches the endianness of a 64-bit integer.
3592
3593   This function swaps the bytes in a 64-bit unsigned value to switch the value
3594   from little endian to big endian or vice versa. The byte swapped value is
3595   returned.
3596
3597   @param  Value A 64-bit unsigned value.
3598
3599   @return The byte swapped Value.
3600
3601 **/
3602 UINT64
3603 EFIAPI
3604 SwapBytes64 (
3605   IN      UINT64                    Value
3606   );
3607
3608
3609 /**
3610   Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
3611   generates a 64-bit unsigned result.
3612
3613   This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
3614   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3615   bit unsigned result is returned.
3616
3617   @param  Multiplicand  A 64-bit unsigned value.
3618   @param  Multiplier    A 32-bit unsigned value.
3619
3620   @return Multiplicand * Multiplier
3621
3622 **/
3623 UINT64
3624 EFIAPI
3625 MultU64x32 (
3626   IN      UINT64                    Multiplicand,
3627   IN      UINT32                    Multiplier
3628   );
3629
3630
3631 /**
3632   Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3633   generates a 64-bit unsigned result.
3634
3635   This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3636   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3637   bit unsigned result is returned.
3638
3639   @param  Multiplicand  A 64-bit unsigned value.
3640   @param  Multiplier    A 64-bit unsigned value.
3641
3642   @return Multiplicand * Multiplier.
3643
3644 **/
3645 UINT64
3646 EFIAPI
3647 MultU64x64 (
3648   IN      UINT64                    Multiplicand,
3649   IN      UINT64                    Multiplier
3650   );
3651
3652
3653 /**
3654   Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3655   64-bit signed result.
3656
3657   This function multiples the 64-bit signed value Multiplicand by the 64-bit
3658   signed value Multiplier and generates a 64-bit signed result. This 64-bit
3659   signed result is returned.
3660
3661   @param  Multiplicand  A 64-bit signed value.
3662   @param  Multiplier    A 64-bit signed value.
3663
3664   @return Multiplicand * Multiplier
3665
3666 **/
3667 INT64
3668 EFIAPI
3669 MultS64x64 (
3670   IN      INT64                     Multiplicand,
3671   IN      INT64                     Multiplier
3672   );
3673
3674
3675 /**
3676   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3677   a 64-bit unsigned result.
3678
3679   This function divides the 64-bit unsigned value Dividend by the 32-bit
3680   unsigned value Divisor and generates a 64-bit unsigned quotient. This
3681   function returns the 64-bit unsigned quotient.
3682
3683   If Divisor is 0, then ASSERT().
3684
3685   @param  Dividend  A 64-bit unsigned value.
3686   @param  Divisor   A 32-bit unsigned value.
3687
3688   @return Dividend / Divisor.
3689
3690 **/
3691 UINT64
3692 EFIAPI
3693 DivU64x32 (
3694   IN      UINT64                    Dividend,
3695   IN      UINT32                    Divisor
3696   );
3697
3698
3699 /**
3700   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3701   a 32-bit unsigned remainder.
3702
3703   This function divides the 64-bit unsigned value Dividend by the 32-bit
3704   unsigned value Divisor and generates a 32-bit remainder. This function
3705   returns the 32-bit unsigned remainder.
3706
3707   If Divisor is 0, then ASSERT().
3708
3709   @param  Dividend  A 64-bit unsigned value.
3710   @param  Divisor   A 32-bit unsigned value.
3711
3712   @return Dividend % Divisor.
3713
3714 **/
3715 UINT32
3716 EFIAPI
3717 ModU64x32 (
3718   IN      UINT64                    Dividend,
3719   IN      UINT32                    Divisor
3720   );
3721
3722
3723 /**
3724   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3725   a 64-bit unsigned result and an optional 32-bit unsigned remainder.
3726
3727   This function divides the 64-bit unsigned value Dividend by the 32-bit
3728   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3729   is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
3730   This function returns the 64-bit unsigned quotient.
3731
3732   If Divisor is 0, then ASSERT().
3733
3734   @param  Dividend  A 64-bit unsigned value.
3735   @param  Divisor   A 32-bit unsigned value.
3736   @param  Remainder A pointer to a 32-bit unsigned value. This parameter is
3737                     optional and may be NULL.
3738
3739   @return Dividend / Divisor.
3740
3741 **/
3742 UINT64
3743 EFIAPI
3744 DivU64x32Remainder (
3745   IN      UINT64                    Dividend,
3746   IN      UINT32                    Divisor,
3747   OUT     UINT32                    *Remainder  OPTIONAL
3748   );
3749
3750
3751 /**
3752   Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
3753   a 64-bit unsigned result and an optional 64-bit unsigned remainder.
3754
3755   This function divides the 64-bit unsigned value Dividend by the 64-bit
3756   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3757   is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
3758   This function returns the 64-bit unsigned quotient.
3759
3760   If Divisor is 0, then ASSERT().
3761
3762   @param  Dividend  A 64-bit unsigned value.
3763   @param  Divisor   A 64-bit unsigned value.
3764   @param  Remainder A pointer to a 64-bit unsigned value. This parameter is
3765                     optional and may be NULL.
3766
3767   @return Dividend / Divisor.
3768
3769 **/
3770 UINT64
3771 EFIAPI
3772 DivU64x64Remainder (
3773   IN      UINT64                    Dividend,
3774   IN      UINT64                    Divisor,
3775   OUT     UINT64                    *Remainder  OPTIONAL
3776   );
3777
3778
3779 /**
3780   Divides a 64-bit signed integer by a 64-bit signed integer and generates a
3781   64-bit signed result and a optional 64-bit signed remainder.
3782
3783   This function divides the 64-bit signed value Dividend by the 64-bit signed
3784   value Divisor and generates a 64-bit signed quotient. If Remainder is not
3785   NULL, then the 64-bit signed remainder is returned in Remainder. This
3786   function returns the 64-bit signed quotient.
3787
3788   It is the caller's responsibility to not call this function with a Divisor of 0.
3789   If Divisor is 0, then the quotient and remainder should be assumed to be
3790   the largest negative integer.
3791
3792   If Divisor is 0, then ASSERT().
3793
3794   @param  Dividend  A 64-bit signed value.
3795   @param  Divisor   A 64-bit signed value.
3796   @param  Remainder A pointer to a 64-bit signed value. This parameter is
3797                     optional and may be NULL.
3798
3799   @return Dividend / Divisor.
3800
3801 **/
3802 INT64
3803 EFIAPI
3804 DivS64x64Remainder (
3805   IN      INT64                     Dividend,
3806   IN      INT64                     Divisor,
3807   OUT     INT64                     *Remainder  OPTIONAL
3808   );
3809
3810
3811 /**
3812   Reads a 16-bit value from memory that may be unaligned.
3813
3814   This function returns the 16-bit value pointed to by Buffer. The function
3815   guarantees that the read operation does not produce an alignment fault.
3816
3817   If the Buffer is NULL, then ASSERT().
3818
3819   @param  Buffer  The pointer to a 16-bit value that may be unaligned.
3820
3821   @return The 16-bit value read from Buffer.
3822
3823 **/
3824 UINT16
3825 EFIAPI
3826 ReadUnaligned16 (
3827   IN CONST UINT16              *Buffer
3828   );
3829
3830
3831 /**
3832   Writes a 16-bit value to memory that may be unaligned.
3833
3834   This function writes the 16-bit value specified by Value to Buffer. Value is
3835   returned. The function guarantees that the write operation does not produce
3836   an alignment fault.
3837
3838   If the Buffer is NULL, then ASSERT().
3839
3840   @param  Buffer  The pointer to a 16-bit value that may be unaligned.
3841   @param  Value   16-bit value to write to Buffer.
3842
3843   @return The 16-bit value to write to Buffer.
3844
3845 **/
3846 UINT16
3847 EFIAPI
3848 WriteUnaligned16 (
3849   OUT UINT16                    *Buffer,
3850   IN  UINT16                    Value
3851   );
3852
3853
3854 /**
3855   Reads a 24-bit value from memory that may be unaligned.
3856
3857   This function returns the 24-bit value pointed to by Buffer. The function
3858   guarantees that the read operation does not produce an alignment fault.
3859
3860   If the Buffer is NULL, then ASSERT().
3861
3862   @param  Buffer  The pointer to a 24-bit value that may be unaligned.
3863
3864   @return The 24-bit value read from Buffer.
3865
3866 **/
3867 UINT32
3868 EFIAPI
3869 ReadUnaligned24 (
3870   IN CONST UINT32              *Buffer
3871   );
3872
3873
3874 /**
3875   Writes a 24-bit value to memory that may be unaligned.
3876
3877   This function writes the 24-bit value specified by Value to Buffer. Value is
3878   returned. The function guarantees that the write operation does not produce
3879   an alignment fault.
3880
3881   If the Buffer is NULL, then ASSERT().
3882
3883   @param  Buffer  The pointer to a 24-bit value that may be unaligned.
3884   @param  Value   24-bit value to write to Buffer.
3885
3886   @return The 24-bit value to write to Buffer.
3887
3888 **/
3889 UINT32
3890 EFIAPI
3891 WriteUnaligned24 (
3892   OUT UINT32                    *Buffer,
3893   IN  UINT32                    Value
3894   );
3895
3896
3897 /**
3898   Reads a 32-bit value from memory that may be unaligned.
3899
3900   This function returns the 32-bit value pointed to by Buffer. The function
3901   guarantees that the read operation does not produce an alignment fault.
3902
3903   If the Buffer is NULL, then ASSERT().
3904
3905   @param  Buffer  The pointer to a 32-bit value that may be unaligned.
3906
3907   @return The 32-bit value read from Buffer.
3908
3909 **/
3910 UINT32
3911 EFIAPI
3912 ReadUnaligned32 (
3913   IN CONST UINT32              *Buffer
3914   );
3915
3916
3917 /**
3918   Writes a 32-bit value to memory that may be unaligned.
3919
3920   This function writes the 32-bit value specified by Value to Buffer. Value is
3921   returned. The function guarantees that the write operation does not produce
3922   an alignment fault.
3923
3924   If the Buffer is NULL, then ASSERT().
3925
3926   @param  Buffer  The pointer to a 32-bit value that may be unaligned.
3927   @param  Value   32-bit value to write to Buffer.
3928
3929   @return The 32-bit value to write to Buffer.
3930
3931 **/
3932 UINT32
3933 EFIAPI
3934 WriteUnaligned32 (
3935   OUT UINT32                    *Buffer,
3936   IN  UINT32                    Value
3937   );
3938
3939
3940 /**
3941   Reads a 64-bit value from memory that may be unaligned.
3942
3943   This function returns the 64-bit value pointed to by Buffer. The function
3944   guarantees that the read operation does not produce an alignment fault.
3945
3946   If the Buffer is NULL, then ASSERT().
3947
3948   @param  Buffer  The pointer to a 64-bit value that may be unaligned.
3949
3950   @return The 64-bit value read from Buffer.
3951
3952 **/
3953 UINT64
3954 EFIAPI
3955 ReadUnaligned64 (
3956   IN CONST UINT64              *Buffer
3957   );
3958
3959
3960 /**
3961   Writes a 64-bit value to memory that may be unaligned.
3962
3963   This function writes the 64-bit value specified by Value to Buffer. Value is
3964   returned. The function guarantees that the write operation does not produce
3965   an alignment fault.
3966
3967   If the Buffer is NULL, then ASSERT().
3968
3969   @param  Buffer  The pointer to a 64-bit value that may be unaligned.
3970   @param  Value   64-bit value to write to Buffer.
3971
3972   @return The 64-bit value to write to Buffer.
3973
3974 **/
3975 UINT64
3976 EFIAPI
3977 WriteUnaligned64 (
3978   OUT UINT64                    *Buffer,
3979   IN  UINT64                    Value
3980   );
3981
3982
3983 //
3984 // Bit Field Functions
3985 //
3986
3987 /**
3988   Returns a bit field from an 8-bit value.
3989
3990   Returns the bitfield specified by the StartBit and the EndBit from Operand.
3991
3992   If 8-bit operations are not supported, then ASSERT().
3993   If StartBit is greater than 7, then ASSERT().
3994   If EndBit is greater than 7, then ASSERT().
3995   If EndBit is less than StartBit, then ASSERT().
3996
3997   @param  Operand   Operand on which to perform the bitfield operation.
3998   @param  StartBit  The ordinal of the least significant bit in the bit field.
3999                     Range 0..7.
4000   @param  EndBit    The ordinal of the most significant bit in the bit field.
4001                     Range 0..7.
4002
4003   @return The bit field read.
4004
4005 **/
4006 UINT8
4007 EFIAPI
4008 BitFieldRead8 (
4009   IN      UINT8                     Operand,
4010   IN      UINTN                     StartBit,
4011   IN      UINTN                     EndBit
4012   );
4013
4014
4015 /**
4016   Writes a bit field to an 8-bit value, and returns the result.
4017
4018   Writes Value to the bit field specified by the StartBit and the EndBit in
4019   Operand. All other bits in Operand are preserved. The new 8-bit value is
4020   returned.
4021
4022   If 8-bit operations are not supported, then ASSERT().
4023   If StartBit is greater than 7, then ASSERT().
4024   If EndBit is greater than 7, then ASSERT().
4025   If EndBit is less than StartBit, then ASSERT().
4026   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4027
4028   @param  Operand   Operand on which to perform the bitfield operation.
4029   @param  StartBit  The ordinal of the least significant bit in the bit field.
4030                     Range 0..7.
4031   @param  EndBit    The ordinal of the most significant bit in the bit field.
4032                     Range 0..7.
4033   @param  Value     New value of the bit field.
4034
4035   @return The new 8-bit value.
4036
4037 **/
4038 UINT8
4039 EFIAPI
4040 BitFieldWrite8 (
4041   IN      UINT8                     Operand,
4042   IN      UINTN                     StartBit,
4043   IN      UINTN                     EndBit,
4044   IN      UINT8                     Value
4045   );
4046
4047
4048 /**
4049   Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
4050   result.
4051
4052   Performs a bitwise OR between the bit field specified by StartBit
4053   and EndBit in Operand and the value specified by OrData. All other bits in
4054   Operand are preserved. The new 8-bit value is returned.
4055
4056   If 8-bit operations are not supported, then ASSERT().
4057   If StartBit is greater than 7, then ASSERT().
4058   If EndBit is greater than 7, then ASSERT().
4059   If EndBit is less than StartBit, then ASSERT().
4060   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4061
4062   @param  Operand   Operand on which to perform the bitfield operation.
4063   @param  StartBit  The ordinal of the least significant bit in the bit field.
4064                     Range 0..7.
4065   @param  EndBit    The ordinal of the most significant bit in the bit field.
4066                     Range 0..7.
4067   @param  OrData    The value to OR with the read value from the value
4068
4069   @return The new 8-bit value.
4070
4071 **/
4072 UINT8
4073 EFIAPI
4074 BitFieldOr8 (
4075   IN      UINT8                     Operand,
4076   IN      UINTN                     StartBit,
4077   IN      UINTN                     EndBit,
4078   IN      UINT8                     OrData
4079   );
4080
4081
4082 /**
4083   Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
4084   the result.
4085
4086   Performs a bitwise AND between the bit field specified by StartBit and EndBit
4087   in Operand and the value specified by AndData. All other bits in Operand are
4088   preserved. The new 8-bit value is returned.
4089
4090   If 8-bit operations are not supported, then ASSERT().
4091   If StartBit is greater than 7, then ASSERT().
4092   If EndBit is greater than 7, then ASSERT().
4093   If EndBit is less than StartBit, then ASSERT().
4094   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4095
4096   @param  Operand   Operand on which to perform the bitfield operation.
4097   @param  StartBit  The ordinal of the least significant bit in the bit field.
4098                     Range 0..7.
4099   @param  EndBit    The ordinal of the most significant bit in the bit field.
4100                     Range 0..7.
4101   @param  AndData   The value to AND with the read value from the value.
4102
4103   @return The new 8-bit value.
4104
4105 **/
4106 UINT8
4107 EFIAPI
4108 BitFieldAnd8 (
4109   IN      UINT8                     Operand,
4110   IN      UINTN                     StartBit,
4111   IN      UINTN                     EndBit,
4112   IN      UINT8                     AndData
4113   );
4114
4115
4116 /**
4117   Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
4118   bitwise OR, and returns the result.
4119
4120   Performs a bitwise AND between the bit field specified by StartBit and EndBit
4121   in Operand and the value specified by AndData, followed by a bitwise
4122   OR with value specified by OrData. All other bits in Operand are
4123   preserved. The new 8-bit value is returned.
4124
4125   If 8-bit operations are not supported, then ASSERT().
4126   If StartBit is greater than 7, then ASSERT().
4127   If EndBit is greater than 7, then ASSERT().
4128   If EndBit is less than StartBit, then ASSERT().
4129   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4130   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4131
4132   @param  Operand   Operand on which to perform the bitfield operation.
4133   @param  StartBit  The ordinal of the least significant bit in the bit field.
4134                     Range 0..7.
4135   @param  EndBit    The ordinal of the most significant bit in the bit field.
4136                     Range 0..7.
4137   @param  AndData   The value to AND with the read value from the value.
4138   @param  OrData    The value to OR with the result of the AND operation.
4139
4140   @return The new 8-bit value.
4141
4142 **/
4143 UINT8
4144 EFIAPI
4145 BitFieldAndThenOr8 (
4146   IN      UINT8                     Operand,
4147   IN      UINTN                     StartBit,
4148   IN      UINTN                     EndBit,
4149   IN      UINT8                     AndData,
4150   IN      UINT8                     OrData
4151   );
4152
4153
4154 /**
4155   Returns a bit field from a 16-bit value.
4156
4157   Returns the bitfield specified by the StartBit and the EndBit from Operand.
4158
4159   If 16-bit operations are not supported, then ASSERT().
4160   If StartBit is greater than 15, then ASSERT().
4161   If EndBit is greater than 15, then ASSERT().
4162   If EndBit is less than StartBit, then ASSERT().
4163
4164   @param  Operand   Operand on which to perform the bitfield operation.
4165   @param  StartBit  The ordinal of the least significant bit in the bit field.
4166                     Range 0..15.
4167   @param  EndBit    The ordinal of the most significant bit in the bit field.
4168                     Range 0..15.
4169
4170   @return The bit field read.
4171
4172 **/
4173 UINT16
4174 EFIAPI
4175 BitFieldRead16 (
4176   IN      UINT16                    Operand,
4177   IN      UINTN                     StartBit,
4178   IN      UINTN                     EndBit
4179   );
4180
4181
4182 /**
4183   Writes a bit field to a 16-bit value, and returns the result.
4184
4185   Writes Value to the bit field specified by the StartBit and the EndBit in
4186   Operand. All other bits in Operand are preserved. The new 16-bit value is
4187   returned.
4188
4189   If 16-bit operations are not supported, then ASSERT().
4190   If StartBit is greater than 15, then ASSERT().
4191   If EndBit is greater than 15, then ASSERT().
4192   If EndBit is less than StartBit, then ASSERT().
4193   If Value 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..15.
4198   @param  EndBit    The ordinal of the most significant bit in the bit field.
4199                     Range 0..15.
4200   @param  Value     New value of the bit field.
4201
4202   @return The new 16-bit value.
4203
4204 **/
4205 UINT16
4206 EFIAPI
4207 BitFieldWrite16 (
4208   IN      UINT16                    Operand,
4209   IN      UINTN                     StartBit,
4210   IN      UINTN                     EndBit,
4211   IN      UINT16                    Value
4212   );
4213
4214
4215 /**
4216   Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
4217   result.
4218
4219   Performs a bitwise OR between the bit field specified by StartBit
4220   and EndBit in Operand and the value specified by OrData. All other bits in
4221   Operand are preserved. The new 16-bit value is returned.
4222
4223   If 16-bit operations are not supported, then ASSERT().
4224   If StartBit is greater than 15, then ASSERT().
4225   If EndBit is greater than 15, then ASSERT().
4226   If EndBit is less than StartBit, then ASSERT().
4227   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4228
4229   @param  Operand   Operand on which to perform the bitfield operation.
4230   @param  StartBit  The ordinal of the least significant bit in the bit field.
4231                     Range 0..15.
4232   @param  EndBit    The ordinal of the most significant bit in the bit field.
4233                     Range 0..15.
4234   @param  OrData    The value to OR with the read value from the value
4235
4236   @return The new 16-bit value.
4237
4238 **/
4239 UINT16
4240 EFIAPI
4241 BitFieldOr16 (
4242   IN      UINT16                    Operand,
4243   IN      UINTN                     StartBit,
4244   IN      UINTN                     EndBit,
4245   IN      UINT16                    OrData
4246   );
4247
4248
4249 /**
4250   Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
4251   the result.
4252
4253   Performs a bitwise AND between the bit field specified by StartBit and EndBit
4254   in Operand and the value specified by AndData. All other bits in Operand are
4255   preserved. The new 16-bit value is returned.
4256
4257   If 16-bit operations are not supported, then ASSERT().
4258   If StartBit is greater than 15, then ASSERT().
4259   If EndBit is greater than 15, then ASSERT().
4260   If EndBit is less than StartBit, then ASSERT().
4261   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4262
4263   @param  Operand   Operand on which to perform the bitfield operation.
4264   @param  StartBit  The ordinal of the least significant bit in the bit field.
4265                     Range 0..15.
4266   @param  EndBit    The ordinal of the most significant bit in the bit field.
4267                     Range 0..15.
4268   @param  AndData   The value to AND with the read value from the value
4269
4270   @return The new 16-bit value.
4271
4272 **/
4273 UINT16
4274 EFIAPI
4275 BitFieldAnd16 (
4276   IN      UINT16                    Operand,
4277   IN      UINTN                     StartBit,
4278   IN      UINTN                     EndBit,
4279   IN      UINT16                    AndData
4280   );
4281
4282
4283 /**
4284   Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
4285   bitwise OR, and returns the result.
4286
4287   Performs a bitwise AND between the bit field specified by StartBit and EndBit
4288   in Operand and the value specified by AndData, followed by a bitwise
4289   OR with value specified by OrData. All other bits in Operand are
4290   preserved. The new 16-bit value is returned.
4291
4292   If 16-bit operations are not supported, then ASSERT().
4293   If StartBit is greater than 15, then ASSERT().
4294   If EndBit is greater than 15, then ASSERT().
4295   If EndBit is less than StartBit, then ASSERT().
4296   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4297   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4298
4299   @param  Operand   Operand on which to perform the bitfield operation.
4300   @param  StartBit  The ordinal of the least significant bit in the bit field.
4301                     Range 0..15.
4302   @param  EndBit    The ordinal of the most significant bit in the bit field.
4303                     Range 0..15.
4304   @param  AndData   The value to AND with the read value from the value.
4305   @param  OrData    The value to OR with the result of the AND operation.
4306
4307   @return The new 16-bit value.
4308
4309 **/
4310 UINT16
4311 EFIAPI
4312 BitFieldAndThenOr16 (
4313   IN      UINT16                    Operand,
4314   IN      UINTN                     StartBit,
4315   IN      UINTN                     EndBit,
4316   IN      UINT16                    AndData,
4317   IN      UINT16                    OrData
4318   );
4319
4320
4321 /**
4322   Returns a bit field from a 32-bit value.
4323
4324   Returns the bitfield specified by the StartBit and the EndBit from Operand.
4325
4326   If 32-bit operations are not supported, then ASSERT().
4327   If StartBit is greater than 31, then ASSERT().
4328   If EndBit is greater than 31, then ASSERT().
4329   If EndBit is less than StartBit, then ASSERT().
4330
4331   @param  Operand   Operand on which to perform the bitfield operation.
4332   @param  StartBit  The ordinal of the least significant bit in the bit field.
4333                     Range 0..31.
4334   @param  EndBit    The ordinal of the most significant bit in the bit field.
4335                     Range 0..31.
4336
4337   @return The bit field read.
4338
4339 **/
4340 UINT32
4341 EFIAPI
4342 BitFieldRead32 (
4343   IN      UINT32                    Operand,
4344   IN      UINTN                     StartBit,
4345   IN      UINTN                     EndBit
4346   );
4347
4348
4349 /**
4350   Writes a bit field to a 32-bit value, and returns the result.
4351
4352   Writes Value to the bit field specified by the StartBit and the EndBit in
4353   Operand. All other bits in Operand are preserved. The new 32-bit value is
4354   returned.
4355
4356   If 32-bit operations are not supported, then ASSERT().
4357   If StartBit is greater than 31, then ASSERT().
4358   If EndBit is greater than 31, then ASSERT().
4359   If EndBit is less than StartBit, then ASSERT().
4360   If Value 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..31.
4365   @param  EndBit    The ordinal of the most significant bit in the bit field.
4366                     Range 0..31.
4367   @param  Value     New value of the bit field.
4368
4369   @return The new 32-bit value.
4370
4371 **/
4372 UINT32
4373 EFIAPI
4374 BitFieldWrite32 (
4375   IN      UINT32                    Operand,
4376   IN      UINTN                     StartBit,
4377   IN      UINTN                     EndBit,
4378   IN      UINT32                    Value
4379   );
4380
4381
4382 /**
4383   Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
4384   result.
4385
4386   Performs a bitwise OR between the bit field specified by StartBit
4387   and EndBit in Operand and the value specified by OrData. All other bits in
4388   Operand are preserved. The new 32-bit value is returned.
4389
4390   If 32-bit operations are not supported, then ASSERT().
4391   If StartBit is greater than 31, then ASSERT().
4392   If EndBit is greater than 31, then ASSERT().
4393   If EndBit is less than StartBit, then ASSERT().
4394   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4395
4396   @param  Operand   Operand on which to perform the bitfield operation.
4397   @param  StartBit  The ordinal of the least significant bit in the bit field.
4398                     Range 0..31.
4399   @param  EndBit    The ordinal of the most significant bit in the bit field.
4400                     Range 0..31.
4401   @param  OrData    The value to OR with the read value from the value.
4402
4403   @return The new 32-bit value.
4404
4405 **/
4406 UINT32
4407 EFIAPI
4408 BitFieldOr32 (
4409   IN      UINT32                    Operand,
4410   IN      UINTN                     StartBit,
4411   IN      UINTN                     EndBit,
4412   IN      UINT32                    OrData
4413   );
4414
4415
4416 /**
4417   Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
4418   the result.
4419
4420   Performs a bitwise AND between the bit field specified by StartBit and EndBit
4421   in Operand and the value specified by AndData. All other bits in Operand are
4422   preserved. The new 32-bit value is returned.
4423
4424   If 32-bit operations are not supported, then ASSERT().
4425   If StartBit is greater than 31, then ASSERT().
4426   If EndBit is greater than 31, then ASSERT().
4427   If EndBit is less than StartBit, then ASSERT().
4428   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4429
4430   @param  Operand   Operand on which to perform the bitfield operation.
4431   @param  StartBit  The ordinal of the least significant bit in the bit field.
4432                     Range 0..31.
4433   @param  EndBit    The ordinal of the most significant bit in the bit field.
4434                     Range 0..31.
4435   @param  AndData   The value to AND with the read value from the value
4436
4437   @return The new 32-bit value.
4438
4439 **/
4440 UINT32
4441 EFIAPI
4442 BitFieldAnd32 (
4443   IN      UINT32                    Operand,
4444   IN      UINTN                     StartBit,
4445   IN      UINTN                     EndBit,
4446   IN      UINT32                    AndData
4447   );
4448
4449
4450 /**
4451   Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
4452   bitwise OR, and returns the result.
4453
4454   Performs a bitwise AND between the bit field specified by StartBit and EndBit
4455   in Operand and the value specified by AndData, followed by a bitwise
4456   OR with value specified by OrData. All other bits in Operand are
4457   preserved. The new 32-bit value is returned.
4458
4459   If 32-bit operations are not supported, then ASSERT().
4460   If StartBit is greater than 31, then ASSERT().
4461   If EndBit is greater than 31, then ASSERT().
4462   If EndBit is less than StartBit, then ASSERT().
4463   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4464   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4465
4466   @param  Operand   Operand on which to perform the bitfield operation.
4467   @param  StartBit  The ordinal of the least significant bit in the bit field.
4468                     Range 0..31.
4469   @param  EndBit    The ordinal of the most significant bit in the bit field.
4470                     Range 0..31.
4471   @param  AndData   The value to AND with the read value from the value.
4472   @param  OrData    The value to OR with the result of the AND operation.
4473
4474   @return The new 32-bit value.
4475
4476 **/
4477 UINT32
4478 EFIAPI
4479 BitFieldAndThenOr32 (
4480   IN      UINT32                    Operand,
4481   IN      UINTN                     StartBit,
4482   IN      UINTN                     EndBit,
4483   IN      UINT32                    AndData,
4484   IN      UINT32                    OrData
4485   );
4486
4487
4488 /**
4489   Returns a bit field from a 64-bit value.
4490
4491   Returns the bitfield specified by the StartBit and the EndBit from Operand.
4492
4493   If 64-bit operations are not supported, then ASSERT().
4494   If StartBit is greater than 63, then ASSERT().
4495   If EndBit is greater than 63, then ASSERT().
4496   If EndBit is less than StartBit, then ASSERT().
4497
4498   @param  Operand   Operand on which to perform the bitfield operation.
4499   @param  StartBit  The ordinal of the least significant bit in the bit field.
4500                     Range 0..63.
4501   @param  EndBit    The ordinal of the most significant bit in the bit field.
4502                     Range 0..63.
4503
4504   @return The bit field read.
4505
4506 **/
4507 UINT64
4508 EFIAPI
4509 BitFieldRead64 (
4510   IN      UINT64                    Operand,
4511   IN      UINTN                     StartBit,
4512   IN      UINTN                     EndBit
4513   );
4514
4515
4516 /**
4517   Writes a bit field to a 64-bit value, and returns the result.
4518
4519   Writes Value to the bit field specified by the StartBit and the EndBit in
4520   Operand. All other bits in Operand are preserved. The new 64-bit value is
4521   returned.
4522
4523   If 64-bit operations are not supported, then ASSERT().
4524   If StartBit is greater than 63, then ASSERT().
4525   If EndBit is greater than 63, then ASSERT().
4526   If EndBit is less than StartBit, then ASSERT().
4527   If Value 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..63.
4532   @param  EndBit    The ordinal of the most significant bit in the bit field.
4533                     Range 0..63.
4534   @param  Value     New value of the bit field.
4535
4536   @return The new 64-bit value.
4537
4538 **/
4539 UINT64
4540 EFIAPI
4541 BitFieldWrite64 (
4542   IN      UINT64                    Operand,
4543   IN      UINTN                     StartBit,
4544   IN      UINTN                     EndBit,
4545   IN      UINT64                    Value
4546   );
4547
4548
4549 /**
4550   Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
4551   result.
4552
4553   Performs a bitwise OR between the bit field specified by StartBit
4554   and EndBit in Operand and the value specified by OrData. All other bits in
4555   Operand are preserved. The new 64-bit value is returned.
4556
4557   If 64-bit operations are not supported, then ASSERT().
4558   If StartBit is greater than 63, then ASSERT().
4559   If EndBit is greater than 63, then ASSERT().
4560   If EndBit is less than StartBit, then ASSERT().
4561   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4562
4563   @param  Operand   Operand on which to perform the bitfield operation.
4564   @param  StartBit  The ordinal of the least significant bit in the bit field.
4565                     Range 0..63.
4566   @param  EndBit    The ordinal of the most significant bit in the bit field.
4567                     Range 0..63.
4568   @param  OrData    The value to OR with the read value from the value
4569
4570   @return The new 64-bit value.
4571
4572 **/
4573 UINT64
4574 EFIAPI
4575 BitFieldOr64 (
4576   IN      UINT64                    Operand,
4577   IN      UINTN                     StartBit,
4578   IN      UINTN                     EndBit,
4579   IN      UINT64                    OrData
4580   );
4581
4582
4583 /**
4584   Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
4585   the result.
4586
4587   Performs a bitwise AND between the bit field specified by StartBit and EndBit
4588   in Operand and the value specified by AndData. All other bits in Operand are
4589   preserved. The new 64-bit value is returned.
4590
4591   If 64-bit operations are not supported, then ASSERT().
4592   If StartBit is greater than 63, then ASSERT().
4593   If EndBit is greater than 63, then ASSERT().
4594   If EndBit is less than StartBit, then ASSERT().
4595   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4596
4597   @param  Operand   Operand on which to perform the bitfield operation.
4598   @param  StartBit  The ordinal of the least significant bit in the bit field.
4599                     Range 0..63.
4600   @param  EndBit    The ordinal of the most significant bit in the bit field.
4601                     Range 0..63.
4602   @param  AndData   The value to AND with the read value from the value
4603
4604   @return The new 64-bit value.
4605
4606 **/
4607 UINT64
4608 EFIAPI
4609 BitFieldAnd64 (
4610   IN      UINT64                    Operand,
4611   IN      UINTN                     StartBit,
4612   IN      UINTN                     EndBit,
4613   IN      UINT64                    AndData
4614   );
4615
4616
4617 /**
4618   Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
4619   bitwise OR, and returns the result.
4620
4621   Performs a bitwise AND between the bit field specified by StartBit and EndBit
4622   in Operand and the value specified by AndData, followed by a bitwise
4623   OR with value specified by OrData. All other bits in Operand are
4624   preserved. The new 64-bit value is returned.
4625
4626   If 64-bit operations are not supported, then ASSERT().
4627   If StartBit is greater than 63, then ASSERT().
4628   If EndBit is greater than 63, then ASSERT().
4629   If EndBit is less than StartBit, then ASSERT().
4630   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4631   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4632
4633   @param  Operand   Operand on which to perform the bitfield operation.
4634   @param  StartBit  The ordinal of the least significant bit in the bit field.
4635                     Range 0..63.
4636   @param  EndBit    The ordinal of the most significant bit in the bit field.
4637                     Range 0..63.
4638   @param  AndData   The value to AND with the read value from the value.
4639   @param  OrData    The value to OR with the result of the AND operation.
4640
4641   @return The new 64-bit value.
4642
4643 **/
4644 UINT64
4645 EFIAPI
4646 BitFieldAndThenOr64 (
4647   IN      UINT64                    Operand,
4648   IN      UINTN                     StartBit,
4649   IN      UINTN                     EndBit,
4650   IN      UINT64                    AndData,
4651   IN      UINT64                    OrData
4652   );
4653
4654 /**
4655   Reads a bit field from a 32-bit value, counts and returns
4656   the number of set bits.
4657
4658   Counts the number of set bits in the  bit field specified by
4659   StartBit and EndBit in Operand. The count is returned.
4660
4661   If StartBit is greater than 31, then ASSERT().
4662   If EndBit is greater than 31, then ASSERT().
4663   If EndBit is less than StartBit, then ASSERT().
4664
4665   @param  Operand   Operand on which to perform the bitfield operation.
4666   @param  StartBit  The ordinal of the least significant bit in the bit field.
4667                     Range 0..31.
4668   @param  EndBit    The ordinal of the most significant bit in the bit field.
4669                     Range 0..31.
4670
4671   @return The number of bits set between StartBit and EndBit.
4672
4673 **/
4674 UINT8
4675 EFIAPI
4676 BitFieldCountOnes32 (
4677   IN       UINT32                   Operand,
4678   IN       UINTN                    StartBit,
4679   IN       UINTN                    EndBit
4680   );
4681
4682 /**
4683    Reads a bit field from a 64-bit value, counts and returns
4684    the number of set bits.
4685
4686    Counts the number of set bits in the  bit field specified by
4687    StartBit and EndBit in Operand. The count is returned.
4688
4689    If StartBit is greater than 63, then ASSERT().
4690    If EndBit is greater than 63, then ASSERT().
4691    If EndBit is less than StartBit, then ASSERT().
4692
4693    @param  Operand   Operand on which to perform the bitfield operation.
4694    @param  StartBit  The ordinal of the least significant bit in the bit field.
4695    Range 0..63.
4696    @param  EndBit    The ordinal of the most significant bit in the bit field.
4697    Range 0..63.
4698
4699    @return The number of bits set between StartBit and EndBit.
4700
4701 **/
4702 UINT8
4703 EFIAPI
4704 BitFieldCountOnes64 (
4705   IN       UINT64                   Operand,
4706   IN       UINTN                    StartBit,
4707   IN       UINTN                    EndBit
4708   );
4709
4710 //
4711 // Base Library Checksum Functions
4712 //
4713
4714 /**
4715   Returns the sum of all elements in a buffer in unit of UINT8.
4716   During calculation, the carry bits are dropped.
4717
4718   This function calculates the sum of all elements in a buffer
4719   in unit of UINT8. The carry bits in result of addition are dropped.
4720   The result is returned as UINT8. If Length is Zero, then Zero is
4721   returned.
4722
4723   If Buffer is NULL, then ASSERT().
4724   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4725
4726   @param  Buffer      The pointer to the buffer to carry out the sum operation.
4727   @param  Length      The size, in bytes, of Buffer.
4728
4729   @return Sum         The sum of Buffer with carry bits dropped during additions.
4730
4731 **/
4732 UINT8
4733 EFIAPI
4734 CalculateSum8 (
4735   IN      CONST UINT8              *Buffer,
4736   IN      UINTN                     Length
4737   );
4738
4739
4740 /**
4741   Returns the two's complement checksum of all elements in a buffer
4742   of 8-bit values.
4743
4744   This function first calculates the sum of the 8-bit values in the
4745   buffer specified by Buffer and Length.  The carry bits in the result
4746   of addition are dropped. Then, the two's complement of the sum is
4747   returned.  If Length is 0, then 0 is returned.
4748
4749   If Buffer is NULL, then ASSERT().
4750   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4751
4752   @param  Buffer      The pointer to the buffer to carry out the checksum operation.
4753   @param  Length      The size, in bytes, of Buffer.
4754
4755   @return Checksum    The two's complement checksum of Buffer.
4756
4757 **/
4758 UINT8
4759 EFIAPI
4760 CalculateCheckSum8 (
4761   IN      CONST UINT8              *Buffer,
4762   IN      UINTN                     Length
4763   );
4764
4765
4766 /**
4767   Returns the sum of all elements in a buffer of 16-bit values.  During
4768   calculation, the carry bits are dropped.
4769
4770   This function calculates the sum of the 16-bit values in the buffer
4771   specified by Buffer and Length. The carry bits in result of addition are dropped.
4772   The 16-bit result is returned.  If Length is 0, then 0 is returned.
4773
4774   If Buffer is NULL, then ASSERT().
4775   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4776   If Length is not aligned on a 16-bit boundary, then ASSERT().
4777   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4778
4779   @param  Buffer      The pointer to the buffer to carry out the sum operation.
4780   @param  Length      The size, in bytes, of Buffer.
4781
4782   @return Sum         The sum of Buffer with carry bits dropped during additions.
4783
4784 **/
4785 UINT16
4786 EFIAPI
4787 CalculateSum16 (
4788   IN      CONST UINT16             *Buffer,
4789   IN      UINTN                     Length
4790   );
4791
4792
4793 /**
4794   Returns the two's complement checksum of all elements in a buffer of
4795   16-bit values.
4796
4797   This function first calculates the sum of the 16-bit values in the buffer
4798   specified by Buffer and Length.  The carry bits in the result of addition
4799   are dropped. Then, the two's complement of the sum is returned.  If Length
4800   is 0, then 0 is returned.
4801
4802   If Buffer is NULL, then ASSERT().
4803   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4804   If Length is not aligned on a 16-bit boundary, then ASSERT().
4805   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4806
4807   @param  Buffer      The pointer to the buffer to carry out the checksum operation.
4808   @param  Length      The size, in bytes, of Buffer.
4809
4810   @return Checksum    The two's complement checksum of Buffer.
4811
4812 **/
4813 UINT16
4814 EFIAPI
4815 CalculateCheckSum16 (
4816   IN      CONST UINT16             *Buffer,
4817   IN      UINTN                     Length
4818   );
4819
4820
4821 /**
4822   Returns the sum of all elements in a buffer of 32-bit values. During
4823   calculation, the carry bits are dropped.
4824
4825   This function calculates the sum of the 32-bit values in the buffer
4826   specified by Buffer and Length. The carry bits in result of addition are dropped.
4827   The 32-bit result is returned. If Length is 0, then 0 is returned.
4828
4829   If Buffer is NULL, then ASSERT().
4830   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4831   If Length is not aligned on a 32-bit boundary, then ASSERT().
4832   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4833
4834   @param  Buffer      The pointer to the buffer to carry out the sum operation.
4835   @param  Length      The size, in bytes, of Buffer.
4836
4837   @return Sum         The sum of Buffer with carry bits dropped during additions.
4838
4839 **/
4840 UINT32
4841 EFIAPI
4842 CalculateSum32 (
4843   IN      CONST UINT32             *Buffer,
4844   IN      UINTN                     Length
4845   );
4846
4847
4848 /**
4849   Returns the two's complement checksum of all elements in a buffer of
4850   32-bit values.
4851
4852   This function first calculates the sum of the 32-bit values in the buffer
4853   specified by Buffer and Length.  The carry bits in the result of addition
4854   are dropped. Then, the two's complement of the sum is returned.  If Length
4855   is 0, then 0 is returned.
4856
4857   If Buffer is NULL, then ASSERT().
4858   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4859   If Length is not aligned on a 32-bit boundary, then ASSERT().
4860   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4861
4862   @param  Buffer      The pointer to the buffer to carry out the checksum operation.
4863   @param  Length      The size, in bytes, of Buffer.
4864
4865   @return Checksum    The two's complement checksum of Buffer.
4866
4867 **/
4868 UINT32
4869 EFIAPI
4870 CalculateCheckSum32 (
4871   IN      CONST UINT32             *Buffer,
4872   IN      UINTN                     Length
4873   );
4874
4875
4876 /**
4877   Returns the sum of all elements in a buffer of 64-bit values.  During
4878   calculation, the carry bits are dropped.
4879
4880   This function calculates the sum of the 64-bit values in the buffer
4881   specified by Buffer and Length. The carry bits in result of addition are dropped.
4882   The 64-bit result is returned.  If Length is 0, then 0 is returned.
4883
4884   If Buffer is NULL, then ASSERT().
4885   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4886   If Length is not aligned on a 64-bit boundary, then ASSERT().
4887   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4888
4889   @param  Buffer      The pointer to the buffer to carry out the sum operation.
4890   @param  Length      The size, in bytes, of Buffer.
4891
4892   @return Sum         The sum of Buffer with carry bits dropped during additions.
4893
4894 **/
4895 UINT64
4896 EFIAPI
4897 CalculateSum64 (
4898   IN      CONST UINT64             *Buffer,
4899   IN      UINTN                     Length
4900   );
4901
4902
4903 /**
4904   Returns the two's complement checksum of all elements in a buffer of
4905   64-bit values.
4906
4907   This function first calculates the sum of the 64-bit values in the buffer
4908   specified by Buffer and Length.  The carry bits in the result of addition
4909   are dropped. Then, the two's complement of the sum is returned.  If Length
4910   is 0, then 0 is returned.
4911
4912   If Buffer is NULL, then ASSERT().
4913   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4914   If Length is not aligned on a 64-bit boundary, then ASSERT().
4915   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4916
4917   @param  Buffer      The pointer to the buffer to carry out the checksum operation.
4918   @param  Length      The size, in bytes, of Buffer.
4919
4920   @return Checksum    The two's complement checksum of Buffer.
4921
4922 **/
4923 UINT64
4924 EFIAPI
4925 CalculateCheckSum64 (
4926   IN      CONST UINT64             *Buffer,
4927   IN      UINTN                     Length
4928   );
4929
4930 /**
4931   Computes and returns a 32-bit CRC for a data buffer.
4932   CRC32 value bases on ITU-T V.42.
4933
4934   If Buffer is NULL, then ASSERT().
4935   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4936
4937   @param[in]  Buffer       A pointer to the buffer on which the 32-bit CRC is to be computed.
4938   @param[in]  Length       The number of bytes in the buffer Data.
4939
4940   @retval Crc32            The 32-bit CRC was computed for the data buffer.
4941
4942 **/
4943 UINT32
4944 EFIAPI
4945 CalculateCrc32(
4946   IN  VOID                         *Buffer,
4947   IN  UINTN                        Length
4948   );
4949
4950 //
4951 // Base Library CPU Functions
4952 //
4953
4954 /**
4955   Function entry point used when a stack switch is requested with SwitchStack()
4956
4957   @param  Context1        Context1 parameter passed into SwitchStack().
4958   @param  Context2        Context2 parameter passed into SwitchStack().
4959
4960 **/
4961 typedef
4962 VOID
4963 (EFIAPI *SWITCH_STACK_ENTRY_POINT)(
4964   IN      VOID                      *Context1,  OPTIONAL
4965   IN      VOID                      *Context2   OPTIONAL
4966   );
4967
4968
4969 /**
4970   Used to serialize load and store operations.
4971
4972   All loads and stores that proceed calls to this function are guaranteed to be
4973   globally visible when this function returns.
4974
4975 **/
4976 VOID
4977 EFIAPI
4978 MemoryFence (
4979   VOID
4980   );
4981
4982
4983 /**
4984   Saves the current CPU context that can be restored with a call to LongJump()
4985   and returns 0.
4986
4987   Saves the current CPU context in the buffer specified by JumpBuffer and
4988   returns 0. The initial call to SetJump() must always return 0. Subsequent
4989   calls to LongJump() cause a non-zero value to be returned by SetJump().
4990
4991   If JumpBuffer is NULL, then ASSERT().
4992   For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4993
4994   NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
4995   The same structure must never be used for more than one CPU architecture context.
4996   For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
4997   SetJump()/LongJump() is not currently supported for the EBC processor type.
4998
4999   @param  JumpBuffer  A pointer to CPU context buffer.
5000
5001   @retval 0 Indicates a return from SetJump().
5002
5003 **/
5004 RETURNS_TWICE
5005 UINTN
5006 EFIAPI
5007 SetJump (
5008   OUT     BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer
5009   );
5010
5011
5012 /**
5013   Restores the CPU context that was saved with SetJump().
5014
5015   Restores the CPU context from the buffer specified by JumpBuffer. This
5016   function never returns to the caller. Instead is resumes execution based on
5017   the state of JumpBuffer.
5018
5019   If JumpBuffer is NULL, then ASSERT().
5020   For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
5021   If Value is 0, then ASSERT().
5022
5023   @param  JumpBuffer  A pointer to CPU context buffer.
5024   @param  Value       The value to return when the SetJump() context is
5025                       restored and must be non-zero.
5026
5027 **/
5028 VOID
5029 EFIAPI
5030 LongJump (
5031   IN      BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer,
5032   IN      UINTN                     Value
5033   );
5034
5035
5036 /**
5037   Enables CPU interrupts.
5038
5039 **/
5040 VOID
5041 EFIAPI
5042 EnableInterrupts (
5043   VOID
5044   );
5045
5046
5047 /**
5048   Disables CPU interrupts.
5049
5050 **/
5051 VOID
5052 EFIAPI
5053 DisableInterrupts (
5054   VOID
5055   );
5056
5057
5058 /**
5059   Disables CPU interrupts and returns the interrupt state prior to the disable
5060   operation.
5061
5062   @retval TRUE  CPU interrupts were enabled on entry to this call.
5063   @retval FALSE CPU interrupts were disabled on entry to this call.
5064
5065 **/
5066 BOOLEAN
5067 EFIAPI
5068 SaveAndDisableInterrupts (
5069   VOID
5070   );
5071
5072
5073 /**
5074   Enables CPU interrupts for the smallest window required to capture any
5075   pending interrupts.
5076
5077 **/
5078 VOID
5079 EFIAPI
5080 EnableDisableInterrupts (
5081   VOID
5082   );
5083
5084
5085 /**
5086   Retrieves the current CPU interrupt state.
5087
5088   Returns TRUE if interrupts are currently enabled. Otherwise
5089   returns FALSE.
5090
5091   @retval TRUE  CPU interrupts are enabled.
5092   @retval FALSE CPU interrupts are disabled.
5093
5094 **/
5095 BOOLEAN
5096 EFIAPI
5097 GetInterruptState (
5098   VOID
5099   );
5100
5101
5102 /**
5103   Set the current CPU interrupt state.
5104
5105   Sets the current CPU interrupt state to the state specified by
5106   InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
5107   InterruptState is FALSE, then interrupts are disabled. InterruptState is
5108   returned.
5109
5110   @param  InterruptState  TRUE if interrupts should enabled. FALSE if
5111                           interrupts should be disabled.
5112
5113   @return InterruptState
5114
5115 **/
5116 BOOLEAN
5117 EFIAPI
5118 SetInterruptState (
5119   IN      BOOLEAN                   InterruptState
5120   );
5121
5122
5123 /**
5124   Requests CPU to pause for a short period of time.
5125
5126   Requests CPU to pause for a short period of time. Typically used in MP
5127   systems to prevent memory starvation while waiting for a spin lock.
5128
5129 **/
5130 VOID
5131 EFIAPI
5132 CpuPause (
5133   VOID
5134   );
5135
5136
5137 /**
5138   Transfers control to a function starting with a new stack.
5139
5140   Transfers control to the function specified by EntryPoint using the
5141   new stack specified by NewStack and passing in the parameters specified
5142   by Context1 and Context2.  Context1 and Context2 are optional and may
5143   be NULL.  The function EntryPoint must never return.  This function
5144   supports a variable number of arguments following the NewStack parameter.
5145   These additional arguments are ignored on IA-32, x64, and EBC architectures.
5146   Itanium processors expect one additional parameter of type VOID * that specifies
5147   the new backing store pointer.
5148
5149   If EntryPoint is NULL, then ASSERT().
5150   If NewStack is NULL, then ASSERT().
5151
5152   @param  EntryPoint  A pointer to function to call with the new stack.
5153   @param  Context1    A pointer to the context to pass into the EntryPoint
5154                       function.
5155   @param  Context2    A pointer to the context to pass into the EntryPoint
5156                       function.
5157   @param  NewStack    A pointer to the new stack to use for the EntryPoint
5158                       function.
5159   @param  ...         This variable argument list is ignored for IA-32, x64, and
5160                       EBC architectures.  For Itanium processors, this variable
5161                       argument list is expected to contain a single parameter of
5162                       type VOID * that specifies the new backing store pointer.
5163
5164
5165 **/
5166 VOID
5167 EFIAPI
5168 SwitchStack (
5169   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
5170   IN      VOID                      *Context1,  OPTIONAL
5171   IN      VOID                      *Context2,  OPTIONAL
5172   IN      VOID                      *NewStack,
5173   ...
5174   );
5175
5176
5177 /**
5178   Generates a breakpoint on the CPU.
5179
5180   Generates a breakpoint on the CPU. The breakpoint must be implemented such
5181   that code can resume normal execution after the breakpoint.
5182
5183 **/
5184 VOID
5185 EFIAPI
5186 CpuBreakpoint (
5187   VOID
5188   );
5189
5190
5191 /**
5192   Executes an infinite loop.
5193
5194   Forces the CPU to execute an infinite loop. A debugger may be used to skip
5195   past the loop and the code that follows the loop must execute properly. This
5196   implies that the infinite loop must not cause the code that follow it to be
5197   optimized away.
5198
5199 **/
5200 VOID
5201 EFIAPI
5202 CpuDeadLoop (
5203   VOID
5204   );
5205
5206
5207 /**
5208   Uses as a barrier to stop speculative execution.
5209
5210   Ensures that no later instruction will execute speculatively, until all prior
5211   instructions have completed.
5212
5213 **/
5214 VOID
5215 EFIAPI
5216 SpeculationBarrier (
5217   VOID
5218   );
5219
5220
5221 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
5222 ///
5223 /// IA32 and x64 Specific Functions.
5224 /// Byte packed structure for 16-bit Real Mode EFLAGS.
5225 ///
5226 typedef union {
5227   struct {
5228     UINT32  CF:1;           ///< Carry Flag.
5229     UINT32  Reserved_0:1;   ///< Reserved.
5230     UINT32  PF:1;           ///< Parity Flag.
5231     UINT32  Reserved_1:1;   ///< Reserved.
5232     UINT32  AF:1;           ///< Auxiliary Carry Flag.
5233     UINT32  Reserved_2:1;   ///< Reserved.
5234     UINT32  ZF:1;           ///< Zero Flag.
5235     UINT32  SF:1;           ///< Sign Flag.
5236     UINT32  TF:1;           ///< Trap Flag.
5237     UINT32  IF:1;           ///< Interrupt Enable Flag.
5238     UINT32  DF:1;           ///< Direction Flag.
5239     UINT32  OF:1;           ///< Overflow Flag.
5240     UINT32  IOPL:2;         ///< I/O Privilege Level.
5241     UINT32  NT:1;           ///< Nested Task.
5242     UINT32  Reserved_3:1;   ///< Reserved.
5243   } Bits;
5244   UINT16    Uint16;
5245 } IA32_FLAGS16;
5246
5247 ///
5248 /// Byte packed structure for EFLAGS/RFLAGS.
5249 /// 32-bits on IA-32.
5250 /// 64-bits on x64.  The upper 32-bits on x64 are reserved.
5251 ///
5252 typedef union {
5253   struct {
5254     UINT32  CF:1;           ///< Carry Flag.
5255     UINT32  Reserved_0:1;   ///< Reserved.
5256     UINT32  PF:1;           ///< Parity Flag.
5257     UINT32  Reserved_1:1;   ///< Reserved.
5258     UINT32  AF:1;           ///< Auxiliary Carry Flag.
5259     UINT32  Reserved_2:1;   ///< Reserved.
5260     UINT32  ZF:1;           ///< Zero Flag.
5261     UINT32  SF:1;           ///< Sign Flag.
5262     UINT32  TF:1;           ///< Trap Flag.
5263     UINT32  IF:1;           ///< Interrupt Enable Flag.
5264     UINT32  DF:1;           ///< Direction Flag.
5265     UINT32  OF:1;           ///< Overflow Flag.
5266     UINT32  IOPL:2;         ///< I/O Privilege Level.
5267     UINT32  NT:1;           ///< Nested Task.
5268     UINT32  Reserved_3:1;   ///< Reserved.
5269     UINT32  RF:1;           ///< Resume Flag.
5270     UINT32  VM:1;           ///< Virtual 8086 Mode.
5271     UINT32  AC:1;           ///< Alignment Check.
5272     UINT32  VIF:1;          ///< Virtual Interrupt Flag.
5273     UINT32  VIP:1;          ///< Virtual Interrupt Pending.
5274     UINT32  ID:1;           ///< ID Flag.
5275     UINT32  Reserved_4:10;  ///< Reserved.
5276   } Bits;
5277   UINTN     UintN;
5278 } IA32_EFLAGS32;
5279
5280 ///
5281 /// Byte packed structure for Control Register 0 (CR0).
5282 /// 32-bits on IA-32.
5283 /// 64-bits on x64.  The upper 32-bits on x64 are reserved.
5284 ///
5285 typedef union {
5286   struct {
5287     UINT32  PE:1;           ///< Protection Enable.
5288     UINT32  MP:1;           ///< Monitor Coprocessor.
5289     UINT32  EM:1;           ///< Emulation.
5290     UINT32  TS:1;           ///< Task Switched.
5291     UINT32  ET:1;           ///< Extension Type.
5292     UINT32  NE:1;           ///< Numeric Error.
5293     UINT32  Reserved_0:10;  ///< Reserved.
5294     UINT32  WP:1;           ///< Write Protect.
5295     UINT32  Reserved_1:1;   ///< Reserved.
5296     UINT32  AM:1;           ///< Alignment Mask.
5297     UINT32  Reserved_2:10;  ///< Reserved.
5298     UINT32  NW:1;           ///< Mot Write-through.
5299     UINT32  CD:1;           ///< Cache Disable.
5300     UINT32  PG:1;           ///< Paging.
5301   } Bits;
5302   UINTN     UintN;
5303 } IA32_CR0;
5304
5305 ///
5306 /// Byte packed structure for Control Register 4 (CR4).
5307 /// 32-bits on IA-32.
5308 /// 64-bits on x64.  The upper 32-bits on x64 are reserved.
5309 ///
5310 typedef union {
5311   struct {
5312     UINT32  VME:1;          ///< Virtual-8086 Mode Extensions.
5313     UINT32  PVI:1;          ///< Protected-Mode Virtual Interrupts.
5314     UINT32  TSD:1;          ///< Time Stamp Disable.
5315     UINT32  DE:1;           ///< Debugging Extensions.
5316     UINT32  PSE:1;          ///< Page Size Extensions.
5317     UINT32  PAE:1;          ///< Physical Address Extension.
5318     UINT32  MCE:1;          ///< Machine Check Enable.
5319     UINT32  PGE:1;          ///< Page Global Enable.
5320     UINT32  PCE:1;          ///< Performance Monitoring Counter
5321                             ///< Enable.
5322     UINT32  OSFXSR:1;       ///< Operating System Support for
5323                             ///< FXSAVE and FXRSTOR instructions
5324     UINT32  OSXMMEXCPT:1;   ///< Operating System Support for
5325                             ///< Unmasked SIMD Floating Point
5326                             ///< Exceptions.
5327     UINT32  Reserved_0:2;   ///< Reserved.
5328     UINT32  VMXE:1;         ///< VMX Enable
5329     UINT32  Reserved_1:18;  ///< Reserved.
5330   } Bits;
5331   UINTN     UintN;
5332 } IA32_CR4;
5333
5334 ///
5335 /// Byte packed structure for a segment descriptor in a GDT/LDT.
5336 ///
5337 typedef union {
5338   struct {
5339     UINT32  LimitLow:16;
5340     UINT32  BaseLow:16;
5341     UINT32  BaseMid:8;
5342     UINT32  Type:4;
5343     UINT32  S:1;
5344     UINT32  DPL:2;
5345     UINT32  P:1;
5346     UINT32  LimitHigh:4;
5347     UINT32  AVL:1;
5348     UINT32  L:1;
5349     UINT32  DB:1;
5350     UINT32  G:1;
5351     UINT32  BaseHigh:8;
5352   } Bits;
5353   UINT64  Uint64;
5354 } IA32_SEGMENT_DESCRIPTOR;
5355
5356 ///
5357 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
5358 ///
5359 #pragma pack (1)
5360 typedef struct {
5361   UINT16  Limit;
5362   UINTN   Base;
5363 } IA32_DESCRIPTOR;
5364 #pragma pack ()
5365
5366 #define IA32_IDT_GATE_TYPE_TASK          0x85
5367 #define IA32_IDT_GATE_TYPE_INTERRUPT_16  0x86
5368 #define IA32_IDT_GATE_TYPE_TRAP_16       0x87
5369 #define IA32_IDT_GATE_TYPE_INTERRUPT_32  0x8E
5370 #define IA32_IDT_GATE_TYPE_TRAP_32       0x8F
5371
5372 #define IA32_GDT_TYPE_TSS               0x9
5373 #define IA32_GDT_ALIGNMENT              8
5374
5375 #if defined (MDE_CPU_IA32)
5376 ///
5377 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
5378 ///
5379 typedef union {
5380   struct {
5381     UINT32  OffsetLow:16;   ///< Offset bits 15..0.
5382     UINT32  Selector:16;    ///< Selector.
5383     UINT32  Reserved_0:8;   ///< Reserved.
5384     UINT32  GateType:8;     ///< Gate Type.  See #defines above.
5385     UINT32  OffsetHigh:16;  ///< Offset bits 31..16.
5386   } Bits;
5387   UINT64  Uint64;
5388 } IA32_IDT_GATE_DESCRIPTOR;
5389
5390 #pragma pack (1)
5391 //
5392 // IA32 Task-State Segment Definition
5393 //
5394 typedef struct {
5395   UINT16    PreviousTaskLink;
5396   UINT16    Reserved_2;
5397   UINT32    ESP0;
5398   UINT16    SS0;
5399   UINT16    Reserved_10;
5400   UINT32    ESP1;
5401   UINT16    SS1;
5402   UINT16    Reserved_18;
5403   UINT32    ESP2;
5404   UINT16    SS2;
5405   UINT16    Reserved_26;
5406   UINT32    CR3;
5407   UINT32    EIP;
5408   UINT32    EFLAGS;
5409   UINT32    EAX;
5410   UINT32    ECX;
5411   UINT32    EDX;
5412   UINT32    EBX;
5413   UINT32    ESP;
5414   UINT32    EBP;
5415   UINT32    ESI;
5416   UINT32    EDI;
5417   UINT16    ES;
5418   UINT16    Reserved_74;
5419   UINT16    CS;
5420   UINT16    Reserved_78;
5421   UINT16    SS;
5422   UINT16    Reserved_82;
5423   UINT16    DS;
5424   UINT16    Reserved_86;
5425   UINT16    FS;
5426   UINT16    Reserved_90;
5427   UINT16    GS;
5428   UINT16    Reserved_94;
5429   UINT16    LDTSegmentSelector;
5430   UINT16    Reserved_98;
5431   UINT16    T;
5432   UINT16    IOMapBaseAddress;
5433 } IA32_TASK_STATE_SEGMENT;
5434
5435 typedef union {
5436   struct {
5437     UINT32  LimitLow:16;    ///< Segment Limit 15..00
5438     UINT32  BaseLow:16;     ///< Base Address  15..00
5439     UINT32  BaseMid:8;      ///< Base Address  23..16
5440     UINT32  Type:4;         ///< Type (1 0 B 1)
5441     UINT32  Reserved_43:1;  ///< 0
5442     UINT32  DPL:2;          ///< Descriptor Privilege Level
5443     UINT32  P:1;            ///< Segment Present
5444     UINT32  LimitHigh:4;    ///< Segment Limit 19..16
5445     UINT32  AVL:1;          ///< Available for use by system software
5446     UINT32  Reserved_52:2;  ///< 0 0
5447     UINT32  G:1;            ///< Granularity
5448     UINT32  BaseHigh:8;     ///< Base Address 31..24
5449   } Bits;
5450   UINT64  Uint64;
5451 } IA32_TSS_DESCRIPTOR;
5452 #pragma pack ()
5453
5454 #endif // defined (MDE_CPU_IA32)
5455
5456 #if defined (MDE_CPU_X64)
5457 ///
5458 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
5459 ///
5460 typedef union {
5461   struct {
5462     UINT32  OffsetLow:16;   ///< Offset bits 15..0.
5463     UINT32  Selector:16;    ///< Selector.
5464     UINT32  Reserved_0:8;   ///< Reserved.
5465     UINT32  GateType:8;     ///< Gate Type.  See #defines above.
5466     UINT32  OffsetHigh:16;  ///< Offset bits 31..16.
5467     UINT32  OffsetUpper:32; ///< Offset bits 63..32.
5468     UINT32  Reserved_1:32;  ///< Reserved.
5469   } Bits;
5470   struct {
5471     UINT64  Uint64;
5472     UINT64  Uint64_1;
5473   } Uint128;
5474 } IA32_IDT_GATE_DESCRIPTOR;
5475
5476 #pragma pack (1)
5477 //
5478 // IA32 Task-State Segment Definition
5479 //
5480 typedef struct {
5481   UINT32    Reserved_0;
5482   UINT64    RSP0;
5483   UINT64    RSP1;
5484   UINT64    RSP2;
5485   UINT64    Reserved_28;
5486   UINT64    IST[7];
5487   UINT64    Reserved_92;
5488   UINT16    Reserved_100;
5489   UINT16    IOMapBaseAddress;
5490 } IA32_TASK_STATE_SEGMENT;
5491
5492 typedef union {
5493   struct {
5494     UINT32  LimitLow:16;    ///< Segment Limit 15..00
5495     UINT32  BaseLow:16;     ///< Base Address  15..00
5496     UINT32  BaseMidl:8;     ///< Base Address  23..16
5497     UINT32  Type:4;         ///< Type (1 0 B 1)
5498     UINT32  Reserved_43:1;  ///< 0
5499     UINT32  DPL:2;          ///< Descriptor Privilege Level
5500     UINT32  P:1;            ///< Segment Present
5501     UINT32  LimitHigh:4;    ///< Segment Limit 19..16
5502     UINT32  AVL:1;          ///< Available for use by system software
5503     UINT32  Reserved_52:2;  ///< 0 0
5504     UINT32  G:1;            ///< Granularity
5505     UINT32  BaseMidh:8;     ///< Base Address  31..24
5506     UINT32  BaseHigh:32;    ///< Base Address  63..32
5507     UINT32  Reserved_96:32; ///< Reserved
5508   } Bits;
5509   struct {
5510     UINT64  Uint64;
5511     UINT64  Uint64_1;
5512   } Uint128;
5513 } IA32_TSS_DESCRIPTOR;
5514 #pragma pack ()
5515
5516 #endif // defined (MDE_CPU_X64)
5517
5518 ///
5519 /// Byte packed structure for an FP/SSE/SSE2 context.
5520 ///
5521 typedef struct {
5522   UINT8  Buffer[512];
5523 } IA32_FX_BUFFER;
5524
5525 ///
5526 /// Structures for the 16-bit real mode thunks.
5527 ///
5528 typedef struct {
5529   UINT32                            Reserved1;
5530   UINT32                            Reserved2;
5531   UINT32                            Reserved3;
5532   UINT32                            Reserved4;
5533   UINT8                             BL;
5534   UINT8                             BH;
5535   UINT16                            Reserved5;
5536   UINT8                             DL;
5537   UINT8                             DH;
5538   UINT16                            Reserved6;
5539   UINT8                             CL;
5540   UINT8                             CH;
5541   UINT16                            Reserved7;
5542   UINT8                             AL;
5543   UINT8                             AH;
5544   UINT16                            Reserved8;
5545 } IA32_BYTE_REGS;
5546
5547 typedef struct {
5548   UINT16                            DI;
5549   UINT16                            Reserved1;
5550   UINT16                            SI;
5551   UINT16                            Reserved2;
5552   UINT16                            BP;
5553   UINT16                            Reserved3;
5554   UINT16                            SP;
5555   UINT16                            Reserved4;
5556   UINT16                            BX;
5557   UINT16                            Reserved5;
5558   UINT16                            DX;
5559   UINT16                            Reserved6;
5560   UINT16                            CX;
5561   UINT16                            Reserved7;
5562   UINT16                            AX;
5563   UINT16                            Reserved8;
5564 } IA32_WORD_REGS;
5565
5566 typedef struct {
5567   UINT32                            EDI;
5568   UINT32                            ESI;
5569   UINT32                            EBP;
5570   UINT32                            ESP;
5571   UINT32                            EBX;
5572   UINT32                            EDX;
5573   UINT32                            ECX;
5574   UINT32                            EAX;
5575   UINT16                            DS;
5576   UINT16                            ES;
5577   UINT16                            FS;
5578   UINT16                            GS;
5579   IA32_EFLAGS32                     EFLAGS;
5580   UINT32                            Eip;
5581   UINT16                            CS;
5582   UINT16                            SS;
5583 } IA32_DWORD_REGS;
5584
5585 typedef union {
5586   IA32_DWORD_REGS                   E;
5587   IA32_WORD_REGS                    X;
5588   IA32_BYTE_REGS                    H;
5589 } IA32_REGISTER_SET;
5590
5591 ///
5592 /// Byte packed structure for an 16-bit real mode thunks.
5593 ///
5594 typedef struct {
5595   IA32_REGISTER_SET                 *RealModeState;
5596   VOID                              *RealModeBuffer;
5597   UINT32                            RealModeBufferSize;
5598   UINT32                            ThunkAttributes;
5599 } THUNK_CONTEXT;
5600
5601 #define THUNK_ATTRIBUTE_BIG_REAL_MODE             0x00000001
5602 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15   0x00000002
5603 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
5604
5605 ///
5606 /// Type definition for representing labels in NASM source code that allow for
5607 /// the patching of immediate operands of IA32 and X64 instructions.
5608 ///
5609 /// While the type is technically defined as a function type (note: not a
5610 /// pointer-to-function type), such labels in NASM source code never stand for
5611 /// actual functions, and identifiers declared with this function type should
5612 /// never be called. This is also why the EFIAPI calling convention specifier
5613 /// is missing from the typedef, and why the typedef does not follow the usual
5614 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID
5615 /// return type and the VOID argument list are merely artifacts.
5616 ///
5617 typedef VOID (X86_ASSEMBLY_PATCH_LABEL) (VOID);
5618
5619 /**
5620   Retrieves CPUID information.
5621
5622   Executes the CPUID instruction with EAX set to the value specified by Index.
5623   This function always returns Index.
5624   If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5625   If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5626   If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5627   If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5628   This function is only available on IA-32 and x64.
5629
5630   @param  Index The 32-bit value to load into EAX prior to invoking the CPUID
5631                 instruction.
5632   @param  Eax   The pointer to the 32-bit EAX value returned by the CPUID
5633                 instruction. This is an optional parameter that may be NULL.
5634   @param  Ebx   The pointer to the 32-bit EBX value returned by the CPUID
5635                 instruction. This is an optional parameter that may be NULL.
5636   @param  Ecx   The pointer to the 32-bit ECX value returned by the CPUID
5637                 instruction. This is an optional parameter that may be NULL.
5638   @param  Edx   The pointer to the 32-bit EDX value returned by the CPUID
5639                 instruction. This is an optional parameter that may be NULL.
5640
5641   @return Index.
5642
5643 **/
5644 UINT32
5645 EFIAPI
5646 AsmCpuid (
5647   IN      UINT32                    Index,
5648   OUT     UINT32                    *Eax,  OPTIONAL
5649   OUT     UINT32                    *Ebx,  OPTIONAL
5650   OUT     UINT32                    *Ecx,  OPTIONAL
5651   OUT     UINT32                    *Edx   OPTIONAL
5652   );
5653
5654
5655 /**
5656   Retrieves CPUID information using an extended leaf identifier.
5657
5658   Executes the CPUID instruction with EAX set to the value specified by Index
5659   and ECX set to the value specified by SubIndex. This function always returns
5660   Index. This function is only available on IA-32 and x64.
5661
5662   If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5663   If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5664   If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5665   If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5666
5667   @param  Index     The 32-bit value to load into EAX prior to invoking the
5668                     CPUID instruction.
5669   @param  SubIndex  The 32-bit value to load into ECX prior to invoking the
5670                     CPUID instruction.
5671   @param  Eax       The pointer to the 32-bit EAX value returned by the CPUID
5672                     instruction. This is an optional parameter that may be
5673                     NULL.
5674   @param  Ebx       The pointer to the 32-bit EBX value returned by the CPUID
5675                     instruction. This is an optional parameter that may be
5676                     NULL.
5677   @param  Ecx       The pointer to the 32-bit ECX value returned by the CPUID
5678                     instruction. This is an optional parameter that may be
5679                     NULL.
5680   @param  Edx       The pointer to the 32-bit EDX value returned by the CPUID
5681                     instruction. This is an optional parameter that may be
5682                     NULL.
5683
5684   @return Index.
5685
5686 **/
5687 UINT32
5688 EFIAPI
5689 AsmCpuidEx (
5690   IN      UINT32                    Index,
5691   IN      UINT32                    SubIndex,
5692   OUT     UINT32                    *Eax,  OPTIONAL
5693   OUT     UINT32                    *Ebx,  OPTIONAL
5694   OUT     UINT32                    *Ecx,  OPTIONAL
5695   OUT     UINT32                    *Edx   OPTIONAL
5696   );
5697
5698
5699 /**
5700   Set CD bit and clear NW bit of CR0 followed by a WBINVD.
5701
5702   Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
5703   and executing a WBINVD instruction.  This function is only available on IA-32 and x64.
5704
5705 **/
5706 VOID
5707 EFIAPI
5708 AsmDisableCache (
5709   VOID
5710   );
5711
5712
5713 /**
5714   Perform a WBINVD and clear both the CD and NW bits of CR0.
5715
5716   Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
5717   bits of CR0 to 0.  This function is only available on IA-32 and x64.
5718
5719 **/
5720 VOID
5721 EFIAPI
5722 AsmEnableCache (
5723   VOID
5724   );
5725
5726
5727 /**
5728   Returns the lower 32-bits of a Machine Specific Register(MSR).
5729
5730   Reads and returns the lower 32-bits of the MSR specified by Index.
5731   No parameter checking is performed on Index, and some Index values may cause
5732   CPU exceptions. The caller must either guarantee that Index is valid, or the
5733   caller must set up exception handlers to catch the exceptions. This function
5734   is only available on IA-32 and x64.
5735
5736   @param  Index The 32-bit MSR index to read.
5737
5738   @return The lower 32 bits of the MSR identified by Index.
5739
5740 **/
5741 UINT32
5742 EFIAPI
5743 AsmReadMsr32 (
5744   IN      UINT32                    Index
5745   );
5746
5747
5748 /**
5749   Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
5750   The upper 32-bits of the MSR are set to zero.
5751
5752   Writes the 32-bit value specified by Value to the MSR specified by Index. The
5753   upper 32-bits of the MSR write are set to zero. The 32-bit value written to
5754   the MSR is returned. No parameter checking is performed on Index or Value,
5755   and some of these may cause CPU exceptions. The caller must either guarantee
5756   that Index and Value are valid, or the caller must establish proper exception
5757   handlers. This function is only available on IA-32 and x64.
5758
5759   @param  Index The 32-bit MSR index to write.
5760   @param  Value The 32-bit value to write to the MSR.
5761
5762   @return Value
5763
5764 **/
5765 UINT32
5766 EFIAPI
5767 AsmWriteMsr32 (
5768   IN      UINT32                    Index,
5769   IN      UINT32                    Value
5770   );
5771
5772
5773 /**
5774   Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
5775   writes the result back to the 64-bit MSR.
5776
5777   Reads the 64-bit MSR specified by Index, performs a bitwise OR
5778   between the lower 32-bits of the read result and the value specified by
5779   OrData, and writes the result to the 64-bit MSR specified by Index. The lower
5780   32-bits of the value written to the MSR is returned. No parameter checking is
5781   performed on Index or OrData, and some of these may cause CPU exceptions. The
5782   caller must either guarantee that Index and OrData are valid, or the caller
5783   must establish proper exception handlers. This function is only available on
5784   IA-32 and x64.
5785
5786   @param  Index   The 32-bit MSR index to write.
5787   @param  OrData  The value to OR with the read value from the MSR.
5788
5789   @return The lower 32-bit value written to the MSR.
5790
5791 **/
5792 UINT32
5793 EFIAPI
5794 AsmMsrOr32 (
5795   IN      UINT32                    Index,
5796   IN      UINT32                    OrData
5797   );
5798
5799
5800 /**
5801   Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
5802   the result back to the 64-bit MSR.
5803
5804   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5805   lower 32-bits of the read result and the value specified by AndData, and
5806   writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
5807   the value written to the MSR is returned. No parameter checking is performed
5808   on Index or AndData, and some of these may cause CPU exceptions. The caller
5809   must either guarantee that Index and AndData are valid, or the caller must
5810   establish proper exception handlers. This function is only available on IA-32
5811   and x64.
5812
5813   @param  Index   The 32-bit MSR index to write.
5814   @param  AndData The value to AND with the read value from the MSR.
5815
5816   @return The lower 32-bit value written to the MSR.
5817
5818 **/
5819 UINT32
5820 EFIAPI
5821 AsmMsrAnd32 (
5822   IN      UINT32                    Index,
5823   IN      UINT32                    AndData
5824   );
5825
5826
5827 /**
5828   Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
5829   on the lower 32-bits, and writes the result back to the 64-bit MSR.
5830
5831   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5832   lower 32-bits of the read result and the value specified by AndData
5833   preserving the upper 32-bits, performs a bitwise OR between the
5834   result of the AND operation and the value specified by OrData, and writes the
5835   result to the 64-bit MSR specified by Address. The lower 32-bits of the value
5836   written to the MSR is returned. No parameter checking is performed on Index,
5837   AndData, or OrData, and some of these may cause CPU exceptions. The caller
5838   must either guarantee that Index, AndData, and OrData are valid, or the
5839   caller must establish proper exception handlers. This function is only
5840   available on IA-32 and x64.
5841
5842   @param  Index   The 32-bit MSR index to write.
5843   @param  AndData The value to AND with the read value from the MSR.
5844   @param  OrData  The value to OR with the result of the AND operation.
5845
5846   @return The lower 32-bit value written to the MSR.
5847
5848 **/
5849 UINT32
5850 EFIAPI
5851 AsmMsrAndThenOr32 (
5852   IN      UINT32                    Index,
5853   IN      UINT32                    AndData,
5854   IN      UINT32                    OrData
5855   );
5856
5857
5858 /**
5859   Reads a bit field of an MSR.
5860
5861   Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
5862   specified by the StartBit and the EndBit. The value of the bit field is
5863   returned. The caller must either guarantee that Index is valid, or the caller
5864   must set up exception handlers to catch the exceptions. This function is only
5865   available on IA-32 and x64.
5866
5867   If StartBit is greater than 31, then ASSERT().
5868   If EndBit is greater than 31, then ASSERT().
5869   If EndBit is less than StartBit, then ASSERT().
5870
5871   @param  Index     The 32-bit MSR index to read.
5872   @param  StartBit  The ordinal of the least significant bit in the bit field.
5873                     Range 0..31.
5874   @param  EndBit    The ordinal of the most significant bit in the bit field.
5875                     Range 0..31.
5876
5877   @return The bit field read from the MSR.
5878
5879 **/
5880 UINT32
5881 EFIAPI
5882 AsmMsrBitFieldRead32 (
5883   IN      UINT32                    Index,
5884   IN      UINTN                     StartBit,
5885   IN      UINTN                     EndBit
5886   );
5887
5888
5889 /**
5890   Writes a bit field to an MSR.
5891
5892   Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
5893   field is specified by the StartBit and the EndBit. All other bits in the
5894   destination MSR are preserved. The lower 32-bits of the MSR written is
5895   returned. The caller must either guarantee that Index and the data written
5896   is valid, or the caller must set up exception handlers to catch the exceptions.
5897   This function is only available on IA-32 and x64.
5898
5899   If StartBit is greater than 31, then ASSERT().
5900   If EndBit is greater than 31, then ASSERT().
5901   If EndBit is less than StartBit, then ASSERT().
5902   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5903
5904   @param  Index     The 32-bit MSR index to write.
5905   @param  StartBit  The ordinal of the least significant bit in the bit field.
5906                     Range 0..31.
5907   @param  EndBit    The ordinal of the most significant bit in the bit field.
5908                     Range 0..31.
5909   @param  Value     New value of the bit field.
5910
5911   @return The lower 32-bit of the value written to the MSR.
5912
5913 **/
5914 UINT32
5915 EFIAPI
5916 AsmMsrBitFieldWrite32 (
5917   IN      UINT32                    Index,
5918   IN      UINTN                     StartBit,
5919   IN      UINTN                     EndBit,
5920   IN      UINT32                    Value
5921   );
5922
5923
5924 /**
5925   Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
5926   result back to the bit field in the 64-bit MSR.
5927
5928   Reads the 64-bit MSR specified by Index, performs a bitwise OR
5929   between the read result and the value specified by OrData, and writes the
5930   result to the 64-bit MSR specified by Index. The lower 32-bits of the value
5931   written to the MSR are returned. Extra left bits in OrData are stripped. The
5932   caller must either guarantee that Index and the data written is valid, or
5933   the caller must set up exception handlers to catch the exceptions. This
5934   function is only available on IA-32 and x64.
5935
5936   If StartBit is greater than 31, then ASSERT().
5937   If EndBit is greater than 31, then ASSERT().
5938   If EndBit is less than StartBit, then ASSERT().
5939   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5940
5941   @param  Index     The 32-bit MSR index to write.
5942   @param  StartBit  The ordinal of the least significant bit in the bit field.
5943                     Range 0..31.
5944   @param  EndBit    The ordinal of the most significant bit in the bit field.
5945                     Range 0..31.
5946   @param  OrData    The value to OR with the read value from the MSR.
5947
5948   @return The lower 32-bit of the value written to the MSR.
5949
5950 **/
5951 UINT32
5952 EFIAPI
5953 AsmMsrBitFieldOr32 (
5954   IN      UINT32                    Index,
5955   IN      UINTN                     StartBit,
5956   IN      UINTN                     EndBit,
5957   IN      UINT32                    OrData
5958   );
5959
5960
5961 /**
5962   Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
5963   result back to the bit field in the 64-bit MSR.
5964
5965   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5966   read result and the value specified by AndData, and writes the result to the
5967   64-bit MSR specified by Index. The lower 32-bits of the value written to the
5968   MSR are returned. Extra left bits in AndData are stripped. The caller must
5969   either guarantee that Index and the data written is valid, or the caller must
5970   set up exception handlers to catch the exceptions. This function is only
5971   available on IA-32 and x64.
5972
5973   If StartBit is greater than 31, then ASSERT().
5974   If EndBit is greater than 31, then ASSERT().
5975   If EndBit is less than StartBit, then ASSERT().
5976   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5977
5978   @param  Index     The 32-bit MSR index to write.
5979   @param  StartBit  The ordinal of the least significant bit in the bit field.
5980                     Range 0..31.
5981   @param  EndBit    The ordinal of the most significant bit in the bit field.
5982                     Range 0..31.
5983   @param  AndData   The value to AND with the read value from the MSR.
5984
5985   @return The lower 32-bit of the value written to the MSR.
5986
5987 **/
5988 UINT32
5989 EFIAPI
5990 AsmMsrBitFieldAnd32 (
5991   IN      UINT32                    Index,
5992   IN      UINTN                     StartBit,
5993   IN      UINTN                     EndBit,
5994   IN      UINT32                    AndData
5995   );
5996
5997
5998 /**
5999   Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6000   bitwise OR, and writes the result back to the bit field in the
6001   64-bit MSR.
6002
6003   Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
6004   bitwise OR between the read result and the value specified by
6005   AndData, and writes the result to the 64-bit MSR specified by Index. The
6006   lower 32-bits of the value written to the MSR are returned. Extra left bits
6007   in both AndData and OrData are stripped. The caller must either guarantee
6008   that Index and the data written is valid, or the caller must set up exception
6009   handlers to catch the exceptions. This function is only available on IA-32
6010   and x64.
6011
6012   If StartBit is greater than 31, then ASSERT().
6013   If EndBit is greater than 31, then ASSERT().
6014   If EndBit is less than StartBit, then ASSERT().
6015   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6016   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6017
6018   @param  Index     The 32-bit MSR index to write.
6019   @param  StartBit  The ordinal of the least significant bit in the bit field.
6020                     Range 0..31.
6021   @param  EndBit    The ordinal of the most significant bit in the bit field.
6022                     Range 0..31.
6023   @param  AndData   The value to AND with the read value from the MSR.
6024   @param  OrData    The value to OR with the result of the AND operation.
6025
6026   @return The lower 32-bit of the value written to the MSR.
6027
6028 **/
6029 UINT32
6030 EFIAPI
6031 AsmMsrBitFieldAndThenOr32 (
6032   IN      UINT32                    Index,
6033   IN      UINTN                     StartBit,
6034   IN      UINTN                     EndBit,
6035   IN      UINT32                    AndData,
6036   IN      UINT32                    OrData
6037   );
6038
6039
6040 /**
6041   Returns a 64-bit Machine Specific Register(MSR).
6042
6043   Reads and returns the 64-bit MSR specified by Index. No parameter checking is
6044   performed on Index, and some Index values may cause CPU exceptions. The
6045   caller must either guarantee that Index is valid, or the caller must set up
6046   exception handlers to catch the exceptions. This function is only available
6047   on IA-32 and x64.
6048
6049   @param  Index The 32-bit MSR index to read.
6050
6051   @return The value of the MSR identified by Index.
6052
6053 **/
6054 UINT64
6055 EFIAPI
6056 AsmReadMsr64 (
6057   IN      UINT32                    Index
6058   );
6059
6060
6061 /**
6062   Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
6063   value.
6064
6065   Writes the 64-bit value specified by Value to the MSR specified by Index. The
6066   64-bit value written to the MSR is returned. No parameter checking is
6067   performed on Index or Value, and some of these may cause CPU exceptions. The
6068   caller must either guarantee that Index and Value are valid, or the caller
6069   must establish proper exception handlers. This function is only available on
6070   IA-32 and x64.
6071
6072   @param  Index The 32-bit MSR index to write.
6073   @param  Value The 64-bit value to write to the MSR.
6074
6075   @return Value
6076
6077 **/
6078 UINT64
6079 EFIAPI
6080 AsmWriteMsr64 (
6081   IN      UINT32                    Index,
6082   IN      UINT64                    Value
6083   );
6084
6085
6086 /**
6087   Reads a 64-bit MSR, performs a bitwise OR, and writes the result
6088   back to the 64-bit MSR.
6089
6090   Reads the 64-bit MSR specified by Index, performs a bitwise OR
6091   between the read result and the value specified by OrData, and writes the
6092   result to the 64-bit MSR specified by Index. The value written to the MSR is
6093   returned. No parameter checking is performed on Index or OrData, and some of
6094   these may cause CPU exceptions. The caller must either guarantee that Index
6095   and OrData are valid, or the caller must establish proper exception handlers.
6096   This function is only available on IA-32 and x64.
6097
6098   @param  Index   The 32-bit MSR index to write.
6099   @param  OrData  The value to OR with the read value from the MSR.
6100
6101   @return The value written back to the MSR.
6102
6103 **/
6104 UINT64
6105 EFIAPI
6106 AsmMsrOr64 (
6107   IN      UINT32                    Index,
6108   IN      UINT64                    OrData
6109   );
6110
6111
6112 /**
6113   Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
6114   64-bit MSR.
6115
6116   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6117   read result and the value specified by OrData, and writes the result to the
6118   64-bit MSR specified by Index. The value written to the MSR is returned. No
6119   parameter checking is performed on Index or OrData, and some of these may
6120   cause CPU exceptions. The caller must either guarantee that Index and OrData
6121   are valid, or the caller must establish proper exception handlers. This
6122   function is only available on IA-32 and x64.
6123
6124   @param  Index   The 32-bit MSR index to write.
6125   @param  AndData The value to AND with the read value from the MSR.
6126
6127   @return The value written back to the MSR.
6128
6129 **/
6130 UINT64
6131 EFIAPI
6132 AsmMsrAnd64 (
6133   IN      UINT32                    Index,
6134   IN      UINT64                    AndData
6135   );
6136
6137
6138 /**
6139   Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
6140   OR, and writes the result back to the 64-bit MSR.
6141
6142   Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
6143   result and the value specified by AndData, performs a bitwise OR
6144   between the result of the AND operation and the value specified by OrData,
6145   and writes the result to the 64-bit MSR specified by Index. The value written
6146   to the MSR is returned. No parameter checking is performed on Index, AndData,
6147   or OrData, and some of these may cause CPU exceptions. The caller must either
6148   guarantee that Index, AndData, and OrData are valid, or the caller must
6149   establish proper exception handlers. This function is only available on IA-32
6150   and x64.
6151
6152   @param  Index   The 32-bit MSR index to write.
6153   @param  AndData The value to AND with the read value from the MSR.
6154   @param  OrData  The value to OR with the result of the AND operation.
6155
6156   @return The value written back to the MSR.
6157
6158 **/
6159 UINT64
6160 EFIAPI
6161 AsmMsrAndThenOr64 (
6162   IN      UINT32                    Index,
6163   IN      UINT64                    AndData,
6164   IN      UINT64                    OrData
6165   );
6166
6167
6168 /**
6169   Reads a bit field of an MSR.
6170
6171   Reads the bit field in the 64-bit MSR. The bit field is specified by the
6172   StartBit and the EndBit. The value of the bit field is returned. The caller
6173   must either guarantee that Index is valid, or the caller must set up
6174   exception handlers to catch the exceptions. This function is only available
6175   on IA-32 and x64.
6176
6177   If StartBit is greater than 63, then ASSERT().
6178   If EndBit is greater than 63, then ASSERT().
6179   If EndBit is less than StartBit, then ASSERT().
6180
6181   @param  Index     The 32-bit MSR index to read.
6182   @param  StartBit  The ordinal of the least significant bit in the bit field.
6183                     Range 0..63.
6184   @param  EndBit    The ordinal of the most significant bit in the bit field.
6185                     Range 0..63.
6186
6187   @return The value read from the MSR.
6188
6189 **/
6190 UINT64
6191 EFIAPI
6192 AsmMsrBitFieldRead64 (
6193   IN      UINT32                    Index,
6194   IN      UINTN                     StartBit,
6195   IN      UINTN                     EndBit
6196   );
6197
6198
6199 /**
6200   Writes a bit field to an MSR.
6201
6202   Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
6203   the StartBit and the EndBit. All other bits in the destination MSR are
6204   preserved. The MSR written is returned. The caller must either guarantee
6205   that Index and the data written is valid, or the caller must set up exception
6206   handlers to catch the exceptions. This function is only available on IA-32 and x64.
6207
6208   If StartBit is greater than 63, then ASSERT().
6209   If EndBit is greater than 63, then ASSERT().
6210   If EndBit is less than StartBit, then ASSERT().
6211   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6212
6213   @param  Index     The 32-bit MSR index to write.
6214   @param  StartBit  The ordinal of the least significant bit in the bit field.
6215                     Range 0..63.
6216   @param  EndBit    The ordinal of the most significant bit in the bit field.
6217                     Range 0..63.
6218   @param  Value     New value of the bit field.
6219
6220   @return The value written back to the MSR.
6221
6222 **/
6223 UINT64
6224 EFIAPI
6225 AsmMsrBitFieldWrite64 (
6226   IN      UINT32                    Index,
6227   IN      UINTN                     StartBit,
6228   IN      UINTN                     EndBit,
6229   IN      UINT64                    Value
6230   );
6231
6232
6233 /**
6234   Reads a bit field in a 64-bit MSR, performs a bitwise OR, and
6235   writes the result back to the bit field in the 64-bit MSR.
6236
6237   Reads the 64-bit MSR specified by Index, performs a bitwise OR
6238   between the read result and the value specified by OrData, and writes the
6239   result to the 64-bit MSR specified by Index. The value written to the MSR is
6240   returned. Extra left bits in OrData are stripped. The caller must either
6241   guarantee that Index and the data written is valid, or the caller must set up
6242   exception handlers to catch the exceptions. This function is only available
6243   on IA-32 and x64.
6244
6245   If StartBit is greater than 63, then ASSERT().
6246   If EndBit is greater than 63, then ASSERT().
6247   If EndBit is less than StartBit, then ASSERT().
6248   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6249
6250   @param  Index     The 32-bit MSR index to write.
6251   @param  StartBit  The ordinal of the least significant bit in the bit field.
6252                     Range 0..63.
6253   @param  EndBit    The ordinal of the most significant bit in the bit field.
6254                     Range 0..63.
6255   @param  OrData    The value to OR with the read value from the bit field.
6256
6257   @return The value written back to the MSR.
6258
6259 **/
6260 UINT64
6261 EFIAPI
6262 AsmMsrBitFieldOr64 (
6263   IN      UINT32                    Index,
6264   IN      UINTN                     StartBit,
6265   IN      UINTN                     EndBit,
6266   IN      UINT64                    OrData
6267   );
6268
6269
6270 /**
6271   Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6272   result back to the bit field in the 64-bit MSR.
6273
6274   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6275   read result and the value specified by AndData, and writes the result to the
6276   64-bit MSR specified by Index. The value written to the MSR is returned.
6277   Extra left bits in AndData are stripped. The caller must either guarantee
6278   that Index and the data written is valid, or the caller must set up exception
6279   handlers to catch the exceptions. This function is only available on IA-32
6280   and x64.
6281
6282   If StartBit is greater than 63, then ASSERT().
6283   If EndBit is greater than 63, then ASSERT().
6284   If EndBit is less than StartBit, then ASSERT().
6285   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6286
6287   @param  Index     The 32-bit MSR index to write.
6288   @param  StartBit  The ordinal of the least significant bit in the bit field.
6289                     Range 0..63.
6290   @param  EndBit    The ordinal of the most significant bit in the bit field.
6291                     Range 0..63.
6292   @param  AndData   The value to AND with the read value from the bit field.
6293
6294   @return The value written back to the MSR.
6295
6296 **/
6297 UINT64
6298 EFIAPI
6299 AsmMsrBitFieldAnd64 (
6300   IN      UINT32                    Index,
6301   IN      UINTN                     StartBit,
6302   IN      UINTN                     EndBit,
6303   IN      UINT64                    AndData
6304   );
6305
6306
6307 /**
6308   Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6309   bitwise OR, and writes the result back to the bit field in the
6310   64-bit MSR.
6311
6312   Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
6313   a bitwise OR between the read result and the value specified by
6314   AndData, and writes the result to the 64-bit MSR specified by Index. The
6315   value written to the MSR is returned. Extra left bits in both AndData and
6316   OrData are stripped. The caller must either guarantee that Index and the data
6317   written is valid, or the caller must set up exception handlers to catch the
6318   exceptions. This function is only available on IA-32 and x64.
6319
6320   If StartBit is greater than 63, then ASSERT().
6321   If EndBit is greater than 63, then ASSERT().
6322   If EndBit is less than StartBit, then ASSERT().
6323   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6324   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6325
6326   @param  Index     The 32-bit MSR index to write.
6327   @param  StartBit  The ordinal of the least significant bit in the bit field.
6328                     Range 0..63.
6329   @param  EndBit    The ordinal of the most significant bit in the bit field.
6330                     Range 0..63.
6331   @param  AndData   The value to AND with the read value from the bit field.
6332   @param  OrData    The value to OR with the result of the AND operation.
6333
6334   @return The value written back to the MSR.
6335
6336 **/
6337 UINT64
6338 EFIAPI
6339 AsmMsrBitFieldAndThenOr64 (
6340   IN      UINT32                    Index,
6341   IN      UINTN                     StartBit,
6342   IN      UINTN                     EndBit,
6343   IN      UINT64                    AndData,
6344   IN      UINT64                    OrData
6345   );
6346
6347
6348 /**
6349   Reads the current value of the EFLAGS register.
6350
6351   Reads and returns the current value of the EFLAGS register. This function is
6352   only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a
6353   64-bit value on x64.
6354
6355   @return EFLAGS on IA-32 or RFLAGS on x64.
6356
6357 **/
6358 UINTN
6359 EFIAPI
6360 AsmReadEflags (
6361   VOID
6362   );
6363
6364
6365 /**
6366   Reads the current value of the Control Register 0 (CR0).
6367
6368   Reads and returns the current value of CR0. This function is only available
6369   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6370   x64.
6371
6372   @return The value of the Control Register 0 (CR0).
6373
6374 **/
6375 UINTN
6376 EFIAPI
6377 AsmReadCr0 (
6378   VOID
6379   );
6380
6381
6382 /**
6383   Reads the current value of the Control Register 2 (CR2).
6384
6385   Reads and returns the current value of CR2. This function is only available
6386   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6387   x64.
6388
6389   @return The value of the Control Register 2 (CR2).
6390
6391 **/
6392 UINTN
6393 EFIAPI
6394 AsmReadCr2 (
6395   VOID
6396   );
6397
6398
6399 /**
6400   Reads the current value of the Control Register 3 (CR3).
6401
6402   Reads and returns the current value of CR3. This function is only available
6403   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6404   x64.
6405
6406   @return The value of the Control Register 3 (CR3).
6407
6408 **/
6409 UINTN
6410 EFIAPI
6411 AsmReadCr3 (
6412   VOID
6413   );
6414
6415
6416 /**
6417   Reads the current value of the Control Register 4 (CR4).
6418
6419   Reads and returns the current value of CR4. This function is only available
6420   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6421   x64.
6422
6423   @return The value of the Control Register 4 (CR4).
6424
6425 **/
6426 UINTN
6427 EFIAPI
6428 AsmReadCr4 (
6429   VOID
6430   );
6431
6432
6433 /**
6434   Writes a value to Control Register 0 (CR0).
6435
6436   Writes and returns a new value to CR0. This function is only available on
6437   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6438
6439   @param  Cr0 The value to write to CR0.
6440
6441   @return The value written to CR0.
6442
6443 **/
6444 UINTN
6445 EFIAPI
6446 AsmWriteCr0 (
6447   UINTN  Cr0
6448   );
6449
6450
6451 /**
6452   Writes a value to Control Register 2 (CR2).
6453
6454   Writes and returns a new value to CR2. This function is only available on
6455   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6456
6457   @param  Cr2 The value to write to CR2.
6458
6459   @return The value written to CR2.
6460
6461 **/
6462 UINTN
6463 EFIAPI
6464 AsmWriteCr2 (
6465   UINTN  Cr2
6466   );
6467
6468
6469 /**
6470   Writes a value to Control Register 3 (CR3).
6471
6472   Writes and returns a new value to CR3. This function is only available on
6473   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6474
6475   @param  Cr3 The value to write to CR3.
6476
6477   @return The value written to CR3.
6478
6479 **/
6480 UINTN
6481 EFIAPI
6482 AsmWriteCr3 (
6483   UINTN  Cr3
6484   );
6485
6486
6487 /**
6488   Writes a value to Control Register 4 (CR4).
6489
6490   Writes and returns a new value to CR4. This function is only available on
6491   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6492
6493   @param  Cr4 The value to write to CR4.
6494
6495   @return The value written to CR4.
6496
6497 **/
6498 UINTN
6499 EFIAPI
6500 AsmWriteCr4 (
6501   UINTN  Cr4
6502   );
6503
6504
6505 /**
6506   Reads the current value of Debug Register 0 (DR0).
6507
6508   Reads and returns the current value of DR0. This function is only available
6509   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6510   x64.
6511
6512   @return The value of Debug Register 0 (DR0).
6513
6514 **/
6515 UINTN
6516 EFIAPI
6517 AsmReadDr0 (
6518   VOID
6519   );
6520
6521
6522 /**
6523   Reads the current value of Debug Register 1 (DR1).
6524
6525   Reads and returns the current value of DR1. This function is only available
6526   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6527   x64.
6528
6529   @return The value of Debug Register 1 (DR1).
6530
6531 **/
6532 UINTN
6533 EFIAPI
6534 AsmReadDr1 (
6535   VOID
6536   );
6537
6538
6539 /**
6540   Reads the current value of Debug Register 2 (DR2).
6541
6542   Reads and returns the current value of DR2. This function is only available
6543   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6544   x64.
6545
6546   @return The value of Debug Register 2 (DR2).
6547
6548 **/
6549 UINTN
6550 EFIAPI
6551 AsmReadDr2 (
6552   VOID
6553   );
6554
6555
6556 /**
6557   Reads the current value of Debug Register 3 (DR3).
6558
6559   Reads and returns the current value of DR3. This function is only available
6560   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6561   x64.
6562
6563   @return The value of Debug Register 3 (DR3).
6564
6565 **/
6566 UINTN
6567 EFIAPI
6568 AsmReadDr3 (
6569   VOID
6570   );
6571
6572
6573 /**
6574   Reads the current value of Debug Register 4 (DR4).
6575
6576   Reads and returns the current value of DR4. This function is only available
6577   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6578   x64.
6579
6580   @return The value of Debug Register 4 (DR4).
6581
6582 **/
6583 UINTN
6584 EFIAPI
6585 AsmReadDr4 (
6586   VOID
6587   );
6588
6589
6590 /**
6591   Reads the current value of Debug Register 5 (DR5).
6592
6593   Reads and returns the current value of DR5. This function is only available
6594   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6595   x64.
6596
6597   @return The value of Debug Register 5 (DR5).
6598
6599 **/
6600 UINTN
6601 EFIAPI
6602 AsmReadDr5 (
6603   VOID
6604   );
6605
6606
6607 /**
6608   Reads the current value of Debug Register 6 (DR6).
6609
6610   Reads and returns the current value of DR6. This function is only available
6611   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6612   x64.
6613
6614   @return The value of Debug Register 6 (DR6).
6615
6616 **/
6617 UINTN
6618 EFIAPI
6619 AsmReadDr6 (
6620   VOID
6621   );
6622
6623
6624 /**
6625   Reads the current value of Debug Register 7 (DR7).
6626
6627   Reads and returns the current value of DR7. This function is only available
6628   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6629   x64.
6630
6631   @return The value of Debug Register 7 (DR7).
6632
6633 **/
6634 UINTN
6635 EFIAPI
6636 AsmReadDr7 (
6637   VOID
6638   );
6639
6640
6641 /**
6642   Writes a value to Debug Register 0 (DR0).
6643
6644   Writes and returns a new value to DR0. This function is only available on
6645   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6646
6647   @param  Dr0 The value to write to Dr0.
6648
6649   @return The value written to Debug Register 0 (DR0).
6650
6651 **/
6652 UINTN
6653 EFIAPI
6654 AsmWriteDr0 (
6655   UINTN  Dr0
6656   );
6657
6658
6659 /**
6660   Writes a value to Debug Register 1 (DR1).
6661
6662   Writes and returns a new value to DR1. This function is only available on
6663   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6664
6665   @param  Dr1 The value to write to Dr1.
6666
6667   @return The value written to Debug Register 1 (DR1).
6668
6669 **/
6670 UINTN
6671 EFIAPI
6672 AsmWriteDr1 (
6673   UINTN  Dr1
6674   );
6675
6676
6677 /**
6678   Writes a value to Debug Register 2 (DR2).
6679
6680   Writes and returns a new value to DR2. This function is only available on
6681   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6682
6683   @param  Dr2 The value to write to Dr2.
6684
6685   @return The value written to Debug Register 2 (DR2).
6686
6687 **/
6688 UINTN
6689 EFIAPI
6690 AsmWriteDr2 (
6691   UINTN  Dr2
6692   );
6693
6694
6695 /**
6696   Writes a value to Debug Register 3 (DR3).
6697
6698   Writes and returns a new value to DR3. This function is only available on
6699   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6700
6701   @param  Dr3 The value to write to Dr3.
6702
6703   @return The value written to Debug Register 3 (DR3).
6704
6705 **/
6706 UINTN
6707 EFIAPI
6708 AsmWriteDr3 (
6709   UINTN  Dr3
6710   );
6711
6712
6713 /**
6714   Writes a value to Debug Register 4 (DR4).
6715
6716   Writes and returns a new value to DR4. This function is only available on
6717   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6718
6719   @param  Dr4 The value to write to Dr4.
6720
6721   @return The value written to Debug Register 4 (DR4).
6722
6723 **/
6724 UINTN
6725 EFIAPI
6726 AsmWriteDr4 (
6727   UINTN  Dr4
6728   );
6729
6730
6731 /**
6732   Writes a value to Debug Register 5 (DR5).
6733
6734   Writes and returns a new value to DR5. This function is only available on
6735   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6736
6737   @param  Dr5 The value to write to Dr5.
6738
6739   @return The value written to Debug Register 5 (DR5).
6740
6741 **/
6742 UINTN
6743 EFIAPI
6744 AsmWriteDr5 (
6745   UINTN  Dr5
6746   );
6747
6748
6749 /**
6750   Writes a value to Debug Register 6 (DR6).
6751
6752   Writes and returns a new value to DR6. This function is only available on
6753   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6754
6755   @param  Dr6 The value to write to Dr6.
6756
6757   @return The value written to Debug Register 6 (DR6).
6758
6759 **/
6760 UINTN
6761 EFIAPI
6762 AsmWriteDr6 (
6763   UINTN  Dr6
6764   );
6765
6766
6767 /**
6768   Writes a value to Debug Register 7 (DR7).
6769
6770   Writes and returns a new value to DR7. This function is only available on
6771   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6772
6773   @param  Dr7 The value to write to Dr7.
6774
6775   @return The value written to Debug Register 7 (DR7).
6776
6777 **/
6778 UINTN
6779 EFIAPI
6780 AsmWriteDr7 (
6781   UINTN  Dr7
6782   );
6783
6784
6785 /**
6786   Reads the current value of Code Segment Register (CS).
6787
6788   Reads and returns the current value of CS. This function is only available on
6789   IA-32 and x64.
6790
6791   @return The current value of CS.
6792
6793 **/
6794 UINT16
6795 EFIAPI
6796 AsmReadCs (
6797   VOID
6798   );
6799
6800
6801 /**
6802   Reads the current value of Data Segment Register (DS).
6803
6804   Reads and returns the current value of DS. This function is only available on
6805   IA-32 and x64.
6806
6807   @return The current value of DS.
6808
6809 **/
6810 UINT16
6811 EFIAPI
6812 AsmReadDs (
6813   VOID
6814   );
6815
6816
6817 /**
6818   Reads the current value of Extra Segment Register (ES).
6819
6820   Reads and returns the current value of ES. This function is only available on
6821   IA-32 and x64.
6822
6823   @return The current value of ES.
6824
6825 **/
6826 UINT16
6827 EFIAPI
6828 AsmReadEs (
6829   VOID
6830   );
6831
6832
6833 /**
6834   Reads the current value of FS Data Segment Register (FS).
6835
6836   Reads and returns the current value of FS. This function is only available on
6837   IA-32 and x64.
6838
6839   @return The current value of FS.
6840
6841 **/
6842 UINT16
6843 EFIAPI
6844 AsmReadFs (
6845   VOID
6846   );
6847
6848
6849 /**
6850   Reads the current value of GS Data Segment Register (GS).
6851
6852   Reads and returns the current value of GS. This function is only available on
6853   IA-32 and x64.
6854
6855   @return The current value of GS.
6856
6857 **/
6858 UINT16
6859 EFIAPI
6860 AsmReadGs (
6861   VOID
6862   );
6863
6864
6865 /**
6866   Reads the current value of Stack Segment Register (SS).
6867
6868   Reads and returns the current value of SS. This function is only available on
6869   IA-32 and x64.
6870
6871   @return The current value of SS.
6872
6873 **/
6874 UINT16
6875 EFIAPI
6876 AsmReadSs (
6877   VOID
6878   );
6879
6880
6881 /**
6882   Reads the current value of Task Register (TR).
6883
6884   Reads and returns the current value of TR. This function is only available on
6885   IA-32 and x64.
6886
6887   @return The current value of TR.
6888
6889 **/
6890 UINT16
6891 EFIAPI
6892 AsmReadTr (
6893   VOID
6894   );
6895
6896
6897 /**
6898   Reads the current Global Descriptor Table Register(GDTR) descriptor.
6899
6900   Reads and returns the current GDTR descriptor and returns it in Gdtr. This
6901   function is only available on IA-32 and x64.
6902
6903   If Gdtr is NULL, then ASSERT().
6904
6905   @param  Gdtr  The pointer to a GDTR descriptor.
6906
6907 **/
6908 VOID
6909 EFIAPI
6910 AsmReadGdtr (
6911   OUT     IA32_DESCRIPTOR           *Gdtr
6912   );
6913
6914
6915 /**
6916   Writes the current Global Descriptor Table Register (GDTR) descriptor.
6917
6918   Writes and the current GDTR descriptor specified by Gdtr. This function is
6919   only available on IA-32 and x64.
6920
6921   If Gdtr is NULL, then ASSERT().
6922
6923   @param  Gdtr  The pointer to a GDTR descriptor.
6924
6925 **/
6926 VOID
6927 EFIAPI
6928 AsmWriteGdtr (
6929   IN      CONST IA32_DESCRIPTOR     *Gdtr
6930   );
6931
6932
6933 /**
6934   Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.
6935
6936   Reads and returns the current IDTR descriptor and returns it in Idtr. This
6937   function is only available on IA-32 and x64.
6938
6939   If Idtr is NULL, then ASSERT().
6940
6941   @param  Idtr  The pointer to a IDTR descriptor.
6942
6943 **/
6944 VOID
6945 EFIAPI
6946 AsmReadIdtr (
6947   OUT     IA32_DESCRIPTOR           *Idtr
6948   );
6949
6950
6951 /**
6952   Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.
6953
6954   Writes the current IDTR descriptor and returns it in Idtr. This function is
6955   only available on IA-32 and x64.
6956
6957   If Idtr is NULL, then ASSERT().
6958
6959   @param  Idtr  The pointer to a IDTR descriptor.
6960
6961 **/
6962 VOID
6963 EFIAPI
6964 AsmWriteIdtr (
6965   IN      CONST IA32_DESCRIPTOR     *Idtr
6966   );
6967
6968
6969 /**
6970   Reads the current Local Descriptor Table Register(LDTR) selector.
6971
6972   Reads and returns the current 16-bit LDTR descriptor value. This function is
6973   only available on IA-32 and x64.
6974
6975   @return The current selector of LDT.
6976
6977 **/
6978 UINT16
6979 EFIAPI
6980 AsmReadLdtr (
6981   VOID
6982   );
6983
6984
6985 /**
6986   Writes the current Local Descriptor Table Register (LDTR) selector.
6987
6988   Writes and the current LDTR descriptor specified by Ldtr. This function is
6989   only available on IA-32 and x64.
6990
6991   @param  Ldtr  16-bit LDTR selector value.
6992
6993 **/
6994 VOID
6995 EFIAPI
6996 AsmWriteLdtr (
6997   IN      UINT16                    Ldtr
6998   );
6999
7000
7001 /**
7002   Save the current floating point/SSE/SSE2 context to a buffer.
7003
7004   Saves the current floating point/SSE/SSE2 state to the buffer specified by
7005   Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
7006   available on IA-32 and x64.
7007
7008   If Buffer is NULL, then ASSERT().
7009   If Buffer is not aligned on a 16-byte boundary, then ASSERT().
7010
7011   @param  Buffer  The pointer to a buffer to save the floating point/SSE/SSE2 context.
7012
7013 **/
7014 VOID
7015 EFIAPI
7016 AsmFxSave (
7017   OUT     IA32_FX_BUFFER            *Buffer
7018   );
7019
7020
7021 /**
7022   Restores the current floating point/SSE/SSE2 context from a buffer.
7023
7024   Restores the current floating point/SSE/SSE2 state from the buffer specified
7025   by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
7026   only available on IA-32 and x64.
7027
7028   If Buffer is NULL, then ASSERT().
7029   If Buffer is not aligned on a 16-byte boundary, then ASSERT().
7030   If Buffer was not saved with AsmFxSave(), then ASSERT().
7031
7032   @param  Buffer  The pointer to a buffer to save the floating point/SSE/SSE2 context.
7033
7034 **/
7035 VOID
7036 EFIAPI
7037 AsmFxRestore (
7038   IN      CONST IA32_FX_BUFFER      *Buffer
7039   );
7040
7041
7042 /**
7043   Reads the current value of 64-bit MMX Register #0 (MM0).
7044
7045   Reads and returns the current value of MM0. This function is only available
7046   on IA-32 and x64.
7047
7048   @return The current value of MM0.
7049
7050 **/
7051 UINT64
7052 EFIAPI
7053 AsmReadMm0 (
7054   VOID
7055   );
7056
7057
7058 /**
7059   Reads the current value of 64-bit MMX Register #1 (MM1).
7060
7061   Reads and returns the current value of MM1. This function is only available
7062   on IA-32 and x64.
7063
7064   @return The current value of MM1.
7065
7066 **/
7067 UINT64
7068 EFIAPI
7069 AsmReadMm1 (
7070   VOID
7071   );
7072
7073
7074 /**
7075   Reads the current value of 64-bit MMX Register #2 (MM2).
7076
7077   Reads and returns the current value of MM2. This function is only available
7078   on IA-32 and x64.
7079
7080   @return The current value of MM2.
7081
7082 **/
7083 UINT64
7084 EFIAPI
7085 AsmReadMm2 (
7086   VOID
7087   );
7088
7089
7090 /**
7091   Reads the current value of 64-bit MMX Register #3 (MM3).
7092
7093   Reads and returns the current value of MM3. This function is only available
7094   on IA-32 and x64.
7095
7096   @return The current value of MM3.
7097
7098 **/
7099 UINT64
7100 EFIAPI
7101 AsmReadMm3 (
7102   VOID
7103   );
7104
7105
7106 /**
7107   Reads the current value of 64-bit MMX Register #4 (MM4).
7108
7109   Reads and returns the current value of MM4. This function is only available
7110   on IA-32 and x64.
7111
7112   @return The current value of MM4.
7113
7114 **/
7115 UINT64
7116 EFIAPI
7117 AsmReadMm4 (
7118   VOID
7119   );
7120
7121
7122 /**
7123   Reads the current value of 64-bit MMX Register #5 (MM5).
7124
7125   Reads and returns the current value of MM5. This function is only available
7126   on IA-32 and x64.
7127
7128   @return The current value of MM5.
7129
7130 **/
7131 UINT64
7132 EFIAPI
7133 AsmReadMm5 (
7134   VOID
7135   );
7136
7137
7138 /**
7139   Reads the current value of 64-bit MMX Register #6 (MM6).
7140
7141   Reads and returns the current value of MM6. This function is only available
7142   on IA-32 and x64.
7143
7144   @return The current value of MM6.
7145
7146 **/
7147 UINT64
7148 EFIAPI
7149 AsmReadMm6 (
7150   VOID
7151   );
7152
7153
7154 /**
7155   Reads the current value of 64-bit MMX Register #7 (MM7).
7156
7157   Reads and returns the current value of MM7. This function is only available
7158   on IA-32 and x64.
7159
7160   @return The current value of MM7.
7161
7162 **/
7163 UINT64
7164 EFIAPI
7165 AsmReadMm7 (
7166   VOID
7167   );
7168
7169
7170 /**
7171   Writes the current value of 64-bit MMX Register #0 (MM0).
7172
7173   Writes the current value of MM0. This function is only available on IA32 and
7174   x64.
7175
7176   @param  Value The 64-bit value to write to MM0.
7177
7178 **/
7179 VOID
7180 EFIAPI
7181 AsmWriteMm0 (
7182   IN      UINT64                    Value
7183   );
7184
7185
7186 /**
7187   Writes the current value of 64-bit MMX Register #1 (MM1).
7188
7189   Writes the current value of MM1. This function is only available on IA32 and
7190   x64.
7191
7192   @param  Value The 64-bit value to write to MM1.
7193
7194 **/
7195 VOID
7196 EFIAPI
7197 AsmWriteMm1 (
7198   IN      UINT64                    Value
7199   );
7200
7201
7202 /**
7203   Writes the current value of 64-bit MMX Register #2 (MM2).
7204
7205   Writes the current value of MM2. This function is only available on IA32 and
7206   x64.
7207
7208   @param  Value The 64-bit value to write to MM2.
7209
7210 **/
7211 VOID
7212 EFIAPI
7213 AsmWriteMm2 (
7214   IN      UINT64                    Value
7215   );
7216
7217
7218 /**
7219   Writes the current value of 64-bit MMX Register #3 (MM3).
7220
7221   Writes the current value of MM3. This function is only available on IA32 and
7222   x64.
7223
7224   @param  Value The 64-bit value to write to MM3.
7225
7226 **/
7227 VOID
7228 EFIAPI
7229 AsmWriteMm3 (
7230   IN      UINT64                    Value
7231   );
7232
7233
7234 /**
7235   Writes the current value of 64-bit MMX Register #4 (MM4).
7236
7237   Writes the current value of MM4. This function is only available on IA32 and
7238   x64.
7239
7240   @param  Value The 64-bit value to write to MM4.
7241
7242 **/
7243 VOID
7244 EFIAPI
7245 AsmWriteMm4 (
7246   IN      UINT64                    Value
7247   );
7248
7249
7250 /**
7251   Writes the current value of 64-bit MMX Register #5 (MM5).
7252
7253   Writes the current value of MM5. This function is only available on IA32 and
7254   x64.
7255
7256   @param  Value The 64-bit value to write to MM5.
7257
7258 **/
7259 VOID
7260 EFIAPI
7261 AsmWriteMm5 (
7262   IN      UINT64                    Value
7263   );
7264
7265
7266 /**
7267   Writes the current value of 64-bit MMX Register #6 (MM6).
7268
7269   Writes the current value of MM6. This function is only available on IA32 and
7270   x64.
7271
7272   @param  Value The 64-bit value to write to MM6.
7273
7274 **/
7275 VOID
7276 EFIAPI
7277 AsmWriteMm6 (
7278   IN      UINT64                    Value
7279   );
7280
7281
7282 /**
7283   Writes the current value of 64-bit MMX Register #7 (MM7).
7284
7285   Writes the current value of MM7. This function is only available on IA32 and
7286   x64.
7287
7288   @param  Value The 64-bit value to write to MM7.
7289
7290 **/
7291 VOID
7292 EFIAPI
7293 AsmWriteMm7 (
7294   IN      UINT64                    Value
7295   );
7296
7297
7298 /**
7299   Reads the current value of Time Stamp Counter (TSC).
7300
7301   Reads and returns the current value of TSC. This function is only available
7302   on IA-32 and x64.
7303
7304   @return The current value of TSC
7305
7306 **/
7307 UINT64
7308 EFIAPI
7309 AsmReadTsc (
7310   VOID
7311   );
7312
7313
7314 /**
7315   Reads the current value of a Performance Counter (PMC).
7316
7317   Reads and returns the current value of performance counter specified by
7318   Index. This function is only available on IA-32 and x64.
7319
7320   @param  Index The 32-bit Performance Counter index to read.
7321
7322   @return The value of the PMC specified by Index.
7323
7324 **/
7325 UINT64
7326 EFIAPI
7327 AsmReadPmc (
7328   IN      UINT32                    Index
7329   );
7330
7331
7332 /**
7333   Sets up a monitor buffer that is used by AsmMwait().
7334
7335   Executes a MONITOR instruction with the register state specified by Eax, Ecx
7336   and Edx. Returns Eax. This function is only available on IA-32 and x64.
7337
7338   @param  Eax The value to load into EAX or RAX before executing the MONITOR
7339               instruction.
7340   @param  Ecx The value to load into ECX or RCX before executing the MONITOR
7341               instruction.
7342   @param  Edx The value to load into EDX or RDX before executing the MONITOR
7343               instruction.
7344
7345   @return Eax
7346
7347 **/
7348 UINTN
7349 EFIAPI
7350 AsmMonitor (
7351   IN      UINTN                     Eax,
7352   IN      UINTN                     Ecx,
7353   IN      UINTN                     Edx
7354   );
7355
7356
7357 /**
7358   Executes an MWAIT instruction.
7359
7360   Executes an MWAIT instruction with the register state specified by Eax and
7361   Ecx. Returns Eax. This function is only available on IA-32 and x64.
7362
7363   @param  Eax The value to load into EAX or RAX before executing the MONITOR
7364               instruction.
7365   @param  Ecx The value to load into ECX or RCX before executing the MONITOR
7366               instruction.
7367
7368   @return Eax
7369
7370 **/
7371 UINTN
7372 EFIAPI
7373 AsmMwait (
7374   IN      UINTN                     Eax,
7375   IN      UINTN                     Ecx
7376   );
7377
7378
7379 /**
7380   Executes a WBINVD instruction.
7381
7382   Executes a WBINVD instruction. This function is only available on IA-32 and
7383   x64.
7384
7385 **/
7386 VOID
7387 EFIAPI
7388 AsmWbinvd (
7389   VOID
7390   );
7391
7392
7393 /**
7394   Executes a INVD instruction.
7395
7396   Executes a INVD instruction. This function is only available on IA-32 and
7397   x64.
7398
7399 **/
7400 VOID
7401 EFIAPI
7402 AsmInvd (
7403   VOID
7404   );
7405
7406
7407 /**
7408   Flushes a cache line from all the instruction and data caches within the
7409   coherency domain of the CPU.
7410
7411   Flushed the cache line specified by LinearAddress, and returns LinearAddress.
7412   This function is only available on IA-32 and x64.
7413
7414   @param  LinearAddress The address of the cache line to flush. If the CPU is
7415                         in a physical addressing mode, then LinearAddress is a
7416                         physical address. If the CPU is in a virtual
7417                         addressing mode, then LinearAddress is a virtual
7418                         address.
7419
7420   @return LinearAddress.
7421 **/
7422 VOID *
7423 EFIAPI
7424 AsmFlushCacheLine (
7425   IN      VOID                      *LinearAddress
7426   );
7427
7428
7429 /**
7430   Enables the 32-bit paging mode on the CPU.
7431
7432   Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7433   must be properly initialized prior to calling this service. This function
7434   assumes the current execution mode is 32-bit protected mode. This function is
7435   only available on IA-32. After the 32-bit paging mode is enabled, control is
7436   transferred to the function specified by EntryPoint using the new stack
7437   specified by NewStack and passing in the parameters specified by Context1 and
7438   Context2. Context1 and Context2 are optional and may be NULL. The function
7439   EntryPoint must never return.
7440
7441   If the current execution mode is not 32-bit protected mode, then ASSERT().
7442   If EntryPoint is NULL, then ASSERT().
7443   If NewStack is NULL, then ASSERT().
7444
7445   There are a number of constraints that must be followed before calling this
7446   function:
7447   1)  Interrupts must be disabled.
7448   2)  The caller must be in 32-bit protected mode with flat descriptors. This
7449       means all descriptors must have a base of 0 and a limit of 4GB.
7450   3)  CR0 and CR4 must be compatible with 32-bit protected mode with flat
7451       descriptors.
7452   4)  CR3 must point to valid page tables that will be used once the transition
7453       is complete, and those page tables must guarantee that the pages for this
7454       function and the stack are identity mapped.
7455
7456   @param  EntryPoint  A pointer to function to call with the new stack after
7457                       paging is enabled.
7458   @param  Context1    A pointer to the context to pass into the EntryPoint
7459                       function as the first parameter after paging is enabled.
7460   @param  Context2    A pointer to the context to pass into the EntryPoint
7461                       function as the second parameter after paging is enabled.
7462   @param  NewStack    A pointer to the new stack to use for the EntryPoint
7463                       function after paging is enabled.
7464
7465 **/
7466 VOID
7467 EFIAPI
7468 AsmEnablePaging32 (
7469   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
7470   IN      VOID                      *Context1,  OPTIONAL
7471   IN      VOID                      *Context2,  OPTIONAL
7472   IN      VOID                      *NewStack
7473   );
7474
7475
7476 /**
7477   Disables the 32-bit paging mode on the CPU.
7478
7479   Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
7480   mode. This function assumes the current execution mode is 32-paged protected
7481   mode. This function is only available on IA-32. After the 32-bit paging mode
7482   is disabled, control is transferred to the function specified by EntryPoint
7483   using the new stack specified by NewStack and passing in the parameters
7484   specified by Context1 and Context2. Context1 and Context2 are optional and
7485   may be NULL. The function EntryPoint must never return.
7486
7487   If the current execution mode is not 32-bit paged mode, then ASSERT().
7488   If EntryPoint is NULL, then ASSERT().
7489   If NewStack is NULL, then ASSERT().
7490
7491   There are a number of constraints that must be followed before calling this
7492   function:
7493   1)  Interrupts must be disabled.
7494   2)  The caller must be in 32-bit paged mode.
7495   3)  CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
7496   4)  CR3 must point to valid page tables that guarantee that the pages for
7497       this function and the stack are identity mapped.
7498
7499   @param  EntryPoint  A pointer to function to call with the new stack after
7500                       paging is disabled.
7501   @param  Context1    A pointer to the context to pass into the EntryPoint
7502                       function as the first parameter after paging is disabled.
7503   @param  Context2    A pointer to the context to pass into the EntryPoint
7504                       function as the second parameter after paging is
7505                       disabled.
7506   @param  NewStack    A pointer to the new stack to use for the EntryPoint
7507                       function after paging is disabled.
7508
7509 **/
7510 VOID
7511 EFIAPI
7512 AsmDisablePaging32 (
7513   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
7514   IN      VOID                      *Context1,  OPTIONAL
7515   IN      VOID                      *Context2,  OPTIONAL
7516   IN      VOID                      *NewStack
7517   );
7518
7519
7520 /**
7521   Enables the 64-bit paging mode on the CPU.
7522
7523   Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7524   must be properly initialized prior to calling this service. This function
7525   assumes the current execution mode is 32-bit protected mode with flat
7526   descriptors. This function is only available on IA-32. After the 64-bit
7527   paging mode is enabled, control is transferred to the function specified by
7528   EntryPoint using the new stack specified by NewStack and passing in the
7529   parameters specified by Context1 and Context2. Context1 and Context2 are
7530   optional and may be 0. The function EntryPoint must never return.
7531
7532   If the current execution mode is not 32-bit protected mode with flat
7533   descriptors, then ASSERT().
7534   If EntryPoint is 0, then ASSERT().
7535   If NewStack is 0, then ASSERT().
7536
7537   @param  Cs          The 16-bit selector to load in the CS before EntryPoint
7538                       is called. The descriptor in the GDT that this selector
7539                       references must be setup for long mode.
7540   @param  EntryPoint  The 64-bit virtual address of the function to call with
7541                       the new stack after paging is enabled.
7542   @param  Context1    The 64-bit virtual address of the context to pass into
7543                       the EntryPoint function as the first parameter after
7544                       paging is enabled.
7545   @param  Context2    The 64-bit virtual address of the context to pass into
7546                       the EntryPoint function as the second parameter after
7547                       paging is enabled.
7548   @param  NewStack    The 64-bit virtual address of the new stack to use for
7549                       the EntryPoint function after paging is enabled.
7550
7551 **/
7552 VOID
7553 EFIAPI
7554 AsmEnablePaging64 (
7555   IN      UINT16                    Cs,
7556   IN      UINT64                    EntryPoint,
7557   IN      UINT64                    Context1,  OPTIONAL
7558   IN      UINT64                    Context2,  OPTIONAL
7559   IN      UINT64                    NewStack
7560   );
7561
7562
7563 /**
7564   Disables the 64-bit paging mode on the CPU.
7565
7566   Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
7567   mode. This function assumes the current execution mode is 64-paging mode.
7568   This function is only available on x64. After the 64-bit paging mode is
7569   disabled, control is transferred to the function specified by EntryPoint
7570   using the new stack specified by NewStack and passing in the parameters
7571   specified by Context1 and Context2. Context1 and Context2 are optional and
7572   may be 0. The function EntryPoint must never return.
7573
7574   If the current execution mode is not 64-bit paged mode, then ASSERT().
7575   If EntryPoint is 0, then ASSERT().
7576   If NewStack is 0, then ASSERT().
7577
7578   @param  Cs          The 16-bit selector to load in the CS before EntryPoint
7579                       is called. The descriptor in the GDT that this selector
7580                       references must be setup for 32-bit protected mode.
7581   @param  EntryPoint  The 64-bit virtual address of the function to call with
7582                       the new stack after paging is disabled.
7583   @param  Context1    The 64-bit virtual address of the context to pass into
7584                       the EntryPoint function as the first parameter after
7585                       paging is disabled.
7586   @param  Context2    The 64-bit virtual address of the context to pass into
7587                       the EntryPoint function as the second parameter after
7588                       paging is disabled.
7589   @param  NewStack    The 64-bit virtual address of the new stack to use for
7590                       the EntryPoint function after paging is disabled.
7591
7592 **/
7593 VOID
7594 EFIAPI
7595 AsmDisablePaging64 (
7596   IN      UINT16                    Cs,
7597   IN      UINT32                    EntryPoint,
7598   IN      UINT32                    Context1,  OPTIONAL
7599   IN      UINT32                    Context2,  OPTIONAL
7600   IN      UINT32                    NewStack
7601   );
7602
7603
7604 //
7605 // 16-bit thunking services
7606 //
7607
7608 /**
7609   Retrieves the properties for 16-bit thunk functions.
7610
7611   Computes the size of the buffer and stack below 1MB required to use the
7612   AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
7613   buffer size is returned in RealModeBufferSize, and the stack size is returned
7614   in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
7615   then the actual minimum stack size is ExtraStackSize plus the maximum number
7616   of bytes that need to be passed to the 16-bit real mode code.
7617
7618   If RealModeBufferSize is NULL, then ASSERT().
7619   If ExtraStackSize is NULL, then ASSERT().
7620
7621   @param  RealModeBufferSize  A pointer to the size of the buffer below 1MB
7622                               required to use the 16-bit thunk functions.
7623   @param  ExtraStackSize      A pointer to the extra size of stack below 1MB
7624                               that the 16-bit thunk functions require for
7625                               temporary storage in the transition to and from
7626                               16-bit real mode.
7627
7628 **/
7629 VOID
7630 EFIAPI
7631 AsmGetThunk16Properties (
7632   OUT     UINT32                    *RealModeBufferSize,
7633   OUT     UINT32                    *ExtraStackSize
7634   );
7635
7636
7637 /**
7638   Prepares all structures a code required to use AsmThunk16().
7639
7640   Prepares all structures and code required to use AsmThunk16().
7641
7642   This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7643   virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7644
7645   If ThunkContext is NULL, then ASSERT().
7646
7647   @param  ThunkContext  A pointer to the context structure that describes the
7648                         16-bit real mode code to call.
7649
7650 **/
7651 VOID
7652 EFIAPI
7653 AsmPrepareThunk16 (
7654   IN OUT  THUNK_CONTEXT             *ThunkContext
7655   );
7656
7657
7658 /**
7659   Transfers control to a 16-bit real mode entry point and returns the results.
7660
7661   Transfers control to a 16-bit real mode entry point and returns the results.
7662   AsmPrepareThunk16() must be called with ThunkContext before this function is used.
7663   This function must be called with interrupts disabled.
7664
7665   The register state from the RealModeState field of ThunkContext is restored just prior
7666   to calling the 16-bit real mode entry point.  This includes the EFLAGS field of RealModeState,
7667   which is used to set the interrupt state when a 16-bit real mode entry point is called.
7668   Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
7669   The stack is initialized to the SS and ESP fields of RealModeState.  Any parameters passed to
7670   the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
7671   The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
7672   so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
7673   and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
7674   point must exit with a RETF instruction. The register state is captured into RealModeState immediately
7675   after the RETF instruction is executed.
7676
7677   If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7678   or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
7679   the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
7680
7681   If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7682   then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
7683   This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
7684
7685   If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
7686   is invoked in big real mode.  Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
7687
7688   If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7689   ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
7690   disable the A20 mask.
7691
7692   If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
7693   ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask.  If this INT 15 call fails,
7694   then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7695
7696   If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
7697   ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7698
7699   If ThunkContext is NULL, then ASSERT().
7700   If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
7701   If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7702   ThunkAttributes, then ASSERT().
7703
7704   This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7705   virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1.
7706
7707   @param  ThunkContext  A pointer to the context structure that describes the
7708                         16-bit real mode code to call.
7709
7710 **/
7711 VOID
7712 EFIAPI
7713 AsmThunk16 (
7714   IN OUT  THUNK_CONTEXT             *ThunkContext
7715   );
7716
7717
7718 /**
7719   Prepares all structures and code for a 16-bit real mode thunk, transfers
7720   control to a 16-bit real mode entry point, and returns the results.
7721
7722   Prepares all structures and code for a 16-bit real mode thunk, transfers
7723   control to a 16-bit real mode entry point, and returns the results. If the
7724   caller only need to perform a single 16-bit real mode thunk, then this
7725   service should be used. If the caller intends to make more than one 16-bit
7726   real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
7727   once and AsmThunk16() can be called for each 16-bit real mode thunk.
7728
7729   This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7730   virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7731
7732   See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
7733
7734   @param  ThunkContext  A pointer to the context structure that describes the
7735                         16-bit real mode code to call.
7736
7737 **/
7738 VOID
7739 EFIAPI
7740 AsmPrepareAndThunk16 (
7741   IN OUT  THUNK_CONTEXT             *ThunkContext
7742   );
7743
7744 /**
7745   Generates a 16-bit random number through RDRAND instruction.
7746
7747   if Rand is NULL, then ASSERT().
7748
7749   @param[out]  Rand     Buffer pointer to store the random result.
7750
7751   @retval TRUE          RDRAND call was successful.
7752   @retval FALSE         Failed attempts to call RDRAND.
7753
7754  **/
7755 BOOLEAN
7756 EFIAPI
7757 AsmRdRand16 (
7758   OUT     UINT16                    *Rand
7759   );
7760
7761 /**
7762   Generates a 32-bit random number through RDRAND instruction.
7763
7764   if Rand is NULL, then ASSERT().
7765
7766   @param[out]  Rand     Buffer pointer to store the random result.
7767
7768   @retval TRUE          RDRAND call was successful.
7769   @retval FALSE         Failed attempts to call RDRAND.
7770
7771 **/
7772 BOOLEAN
7773 EFIAPI
7774 AsmRdRand32 (
7775   OUT     UINT32                    *Rand
7776   );
7777
7778 /**
7779   Generates a 64-bit random number through RDRAND instruction.
7780
7781   if Rand is NULL, then ASSERT().
7782
7783   @param[out]  Rand     Buffer pointer to store the random result.
7784
7785   @retval TRUE          RDRAND call was successful.
7786   @retval FALSE         Failed attempts to call RDRAND.
7787
7788 **/
7789 BOOLEAN
7790 EFIAPI
7791 AsmRdRand64  (
7792   OUT     UINT64                    *Rand
7793   );
7794
7795 /**
7796   Load given selector into TR register.
7797
7798   @param[in] Selector     Task segment selector
7799 **/
7800 VOID
7801 EFIAPI
7802 AsmWriteTr (
7803   IN UINT16 Selector
7804   );
7805
7806 /**
7807   Performs a serializing operation on all load-from-memory instructions that
7808   were issued prior the AsmLfence function.
7809
7810   Executes a LFENCE instruction. This function is only available on IA-32 and x64.
7811
7812 **/
7813 VOID
7814 EFIAPI
7815 AsmLfence (
7816   VOID
7817   );
7818
7819 /**
7820   Patch the immediate operand of an IA32 or X64 instruction such that the byte,
7821   word, dword or qword operand is encoded at the end of the instruction's
7822   binary representation.
7823
7824   This function should be used to update object code that was compiled with
7825   NASM from assembly source code. Example:
7826
7827   NASM source code:
7828
7829         mov     eax, strict dword 0 ; the imm32 zero operand will be patched
7830     ASM_PFX(gPatchCr3):
7831         mov     cr3, eax
7832
7833   C source code:
7834
7835     X86_ASSEMBLY_PATCH_LABEL gPatchCr3;
7836     PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);
7837
7838   @param[out] InstructionEnd  Pointer right past the instruction to patch. The
7839                               immediate operand to patch is expected to
7840                               comprise the trailing bytes of the instruction.
7841                               If InstructionEnd is closer to address 0 than
7842                               ValueSize permits, then ASSERT().
7843
7844   @param[in] PatchValue       The constant to write to the immediate operand.
7845                               The caller is responsible for ensuring that
7846                               PatchValue can be represented in the byte, word,
7847                               dword or qword operand (as indicated through
7848                               ValueSize); otherwise ASSERT().
7849
7850   @param[in] ValueSize        The size of the operand in bytes; must be 1, 2,
7851                               4, or 8. ASSERT() otherwise.
7852 **/
7853 VOID
7854 EFIAPI
7855 PatchInstructionX86 (
7856   OUT X86_ASSEMBLY_PATCH_LABEL *InstructionEnd,
7857   IN  UINT64                   PatchValue,
7858   IN  UINTN                    ValueSize
7859   );
7860
7861 #endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
7862 #endif // !defined (__BASE_LIB__)