EdkCompatibilityPkg/Foundation/Library/EdkIIGlueLib/Include/Library/EdkIIGlueBaseLib.h

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