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