MdePkg/Include/Library/BaseLib.h

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