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

   1 /*++
   2
   3 Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR>
   4 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_X64)
  93 //
  94 // X64 context buffer used by SetJump() and LongJump()
  95 //
  96 typedef struct {
  97   UINT64                            Rbx;
  98   UINT64                            Rsp;
  99   UINT64                            Rbp;
 100   UINT64                            Rdi;
 101   UINT64                            Rsi;
 102   UINT64                            R12;
 103   UINT64                            R13;
 104   UINT64                            R14;
 105   UINT64                            R15;
 106   UINT64                            Rip;
 107   UINT64                            MxCsr;
 108   UINT8                             XmmBuffer[160]; ///< XMM6-XMM15.
 109 } BASE_LIBRARY_JUMP_BUFFER;
 110
 111 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
 112
 113 #elif defined (MDE_CPU_EBC)
 114 //
 115 // EBC context buffer used by SetJump() and LongJump()
 116 //
 117 typedef struct {
 118   UINT64                            R0;
 119   UINT64                            R1;
 120   UINT64                            R2;
 121   UINT64                            R3;
 122   UINT64                            IP;
 123 } BASE_LIBRARY_JUMP_BUFFER;
 124
 125 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
 126
 127 #else
 128 #error Unknown Processor Type
 129 #endif
 130
 131 //
 132 // String Services
 133 //
 134
 135 /**
 136   Copies one Null-terminated Unicode string to another Null-terminated Unicode
 137   string and returns the new Unicode string.
 138
 139   This function copies the contents of the Unicode string Source to the Unicode
 140   string Destination, and returns Destination. If Source and Destination
 141   overlap, then the results are undefined.
 142
 143   If Destination is NULL, then ASSERT().
 144   If Destination is not aligned on a 16-bit boundary, then ASSERT().
 145   If Source is NULL, then ASSERT().
 146   If Source is not aligned on a 16-bit boundary, then ASSERT().
 147   If Source and Destination overlap, then ASSERT().
 148   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
 149   PcdMaximumUnicodeStringLength Unicode characters not including the
 150   Null-terminator, then ASSERT().
 151
 152   @param  Destination Pointer to a Null-terminated Unicode string.
 153   @param  Source      Pointer to a Null-terminated Unicode string.
 154
 155   @return Destiantion
 156
 157 **/
 158 CHAR16 *
 159 EFIAPI
 160 GlueStrCpy (
 161   OUT     CHAR16                    *Destination,
 162   IN      CONST CHAR16              *Source
 163   );
 164
 165
 166 /**
 167   Copies one Null-terminated Unicode string with a maximum length to another
 168   Null-terminated Unicode string with a maximum length and returns the new
 169   Unicode string.
 170
 171   This function copies the contents of the Unicode string Source to the Unicode
 172   string Destination, and returns Destination. At most, Length Unicode
 173   characters are copied from Source to Destination. If Length is 0, then
 174   Destination is returned unmodified. If Length is greater that the number of
 175   Unicode characters in Source, then Destination is padded with Null Unicode
 176   characters. If Source and Destination overlap, then the results are
 177   undefined.
 178
 179   If Length > 0 and Destination is NULL, then ASSERT().
 180   If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
 181   If Length > 0 and Source is NULL, then ASSERT().
 182   If Length > 0 and Source is not aligned on a 16-bit bounadry, then ASSERT().
 183   If Source and Destination overlap, then ASSERT().
 184   If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
 185   PcdMaximumUnicodeStringLength, then ASSERT().
 186   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
 187   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
 188   then ASSERT().
 189
 190   @param  Destination Pointer to a Null-terminated Unicode string.
 191   @param  Source      Pointer to a Null-terminated Unicode string.
 192   @param  Length      Maximum number of Unicode characters to copy.
 193
 194   @return Destination
 195
 196 **/
 197 CHAR16 *
 198 EFIAPI
 199 GlueStrnCpy (
 200   OUT     CHAR16                    *Destination,
 201   IN      CONST CHAR16              *Source,
 202   IN      UINTN                     Length
 203   );
 204
 205
 206 /**
 207   Returns the length of a Null-terminated Unicode string.
 208
 209   This function returns the number of Unicode characters in the Null-terminated
 210   Unicode string specified by String.
 211
 212   If String is NULL, then ASSERT().
 213   If String is not aligned on a 16-bit boundary, then ASSERT().
 214   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
 215   PcdMaximumUnicodeStringLength Unicode characters not including the
 216   Null-terminator, then ASSERT().
 217
 218   @param  String  Pointer to a Null-terminated Unicode string.
 219
 220   @return The length of String.
 221
 222 **/
 223 UINTN
 224 EFIAPI
 225 GlueStrLen (
 226   IN      CONST CHAR16              *String
 227   );
 228
 229
 230 /**
 231   Returns the size of a Null-terminated Unicode string in bytes, including the
 232   Null terminator.
 233
 234   This function returns the size, in bytes, of the Null-terminated Unicode
 235   string specified by String.
 236
 237   If String is NULL, then ASSERT().
 238   If String is not aligned on a 16-bit boundary, then ASSERT().
 239   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
 240   PcdMaximumUnicodeStringLength Unicode characters not including the
 241   Null-terminator, then ASSERT().
 242
 243   @param  String  Pointer to a Null-terminated Unicode string.
 244
 245   @return The size of String.
 246
 247 **/
 248 UINTN
 249 EFIAPI
 250 GlueStrSize (
 251   IN      CONST CHAR16              *String
 252   );
 253
 254
 255 /**
 256   Compares two Null-terminated Unicode strings, and returns the difference
 257   between the first mismatched Unicode characters.
 258
 259   This function compares the Null-terminated Unicode string FirstString to the
 260   Null-terminated Unicode string SecondString. If FirstString is identical to
 261   SecondString, then 0 is returned. Otherwise, the value returned is the first
 262   mismatched Unicode character in SecondString subtracted from the first
 263   mismatched Unicode character in FirstString.
 264
 265   If FirstString is NULL, then ASSERT().
 266   If FirstString is not aligned on a 16-bit boundary, then ASSERT().
 267   If SecondString is NULL, then ASSERT().
 268   If SecondString is not aligned on a 16-bit boundary, then ASSERT().
 269   If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
 270   than PcdMaximumUnicodeStringLength Unicode characters not including the
 271   Null-terminator, then ASSERT().
 272   If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
 273   than PcdMaximumUnicodeStringLength Unicode characters not including the
 274   Null-terminator, then ASSERT().
 275
 276   @param  FirstString   Pointer to a Null-terminated Unicode string.
 277   @param  SecondString  Pointer to a Null-terminated Unicode string.
 278
 279   @retval 0   FirstString is identical to SecondString.
 280   @retval !=0 FirstString is not identical to SecondString.
 281
 282 **/
 283 INTN
 284 EFIAPI
 285 GlueStrCmp (
 286   IN      CONST CHAR16              *FirstString,
 287   IN      CONST CHAR16              *SecondString
 288   );
 289
 290
 291 /**
 292   Compares two Null-terminated Unicode strings with maximum lengths, and
 293   returns the difference between the first mismatched Unicode characters.
 294
 295   This function compares the Null-terminated Unicode string FirstString to the
 296   Null-terminated Unicode string SecondString. At most, Length Unicode
 297   characters will be compared. If Length is 0, then 0 is returned. If
 298   FirstString is identical to SecondString, then 0 is returned. Otherwise, the
 299   value returned is the first mismatched Unicode character in SecondString
 300   subtracted from the first mismatched Unicode character in FirstString.
 301
 302   If Length > 0 and FirstString is NULL, then ASSERT().
 303   If Length > 0 and FirstString is not aligned on a 16-bit bounadary, then ASSERT().
 304   If Length > 0 and SecondString is NULL, then ASSERT().
 305   If Length > 0 and SecondString is not aligned on a 16-bit bounadary, then ASSERT().
 306   If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
 307   PcdMaximumUnicodeStringLength, then ASSERT().
 308   If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
 309   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
 310   then ASSERT().
 311   If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
 312   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
 313   then ASSERT().
 314
 315   @param  FirstString   Pointer to a Null-terminated Unicode string.
 316   @param  SecondString  Pointer to a Null-terminated Unicode string.
 317   @param  Length        Maximum number of Unicode characters to compare.
 318
 319   @retval 0   FirstString is identical to SecondString.
 320   @retval !=0 FirstString is not identical to SecondString.
 321
 322 **/
 323 INTN
 324 EFIAPI
 325 GlueStrnCmp (
 326   IN      CONST CHAR16              *FirstString,
 327   IN      CONST CHAR16              *SecondString,
 328   IN      UINTN                     Length
 329   );
 330
 331
 332 /**
 333   Concatenates one Null-terminated Unicode string to another Null-terminated
 334   Unicode string, and returns the concatenated Unicode string.
 335
 336   This function concatenates two Null-terminated Unicode strings. The contents
 337   of Null-terminated Unicode string Source are concatenated to the end of
 338   Null-terminated Unicode string Destination. The Null-terminated concatenated
 339   Unicode String is returned. If Source and Destination overlap, then the
 340   results are undefined.
 341
 342   If Destination is NULL, then ASSERT().
 343   If Destination is not aligned on a 16-bit bounadary, then ASSERT().
 344   If Source is NULL, then ASSERT().
 345   If Source is not aligned on a 16-bit bounadary, then ASSERT().
 346   If Source and Destination overlap, then ASSERT().
 347   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
 348   than PcdMaximumUnicodeStringLength Unicode characters not including the
 349   Null-terminator, then ASSERT().
 350   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
 351   PcdMaximumUnicodeStringLength Unicode characters not including the
 352   Null-terminator, then ASSERT().
 353   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
 354   and Source results in a Unicode string with more than
 355   PcdMaximumUnicodeStringLength Unicode characters not including the
 356   Null-terminator, then ASSERT().
 357
 358   @param  Destination Pointer to a Null-terminated Unicode string.
 359   @param  Source      Pointer to a Null-terminated Unicode string.
 360
 361   @return Destination
 362
 363 **/
 364 CHAR16 *
 365 EFIAPI
 366 GlueStrCat (
 367   IN OUT  CHAR16                    *Destination,
 368   IN      CONST CHAR16              *Source
 369   );
 370
 371
 372 /**
 373   Concatenates one Null-terminated Unicode string with a maximum length to the
 374   end of another Null-terminated Unicode string, and returns the concatenated
 375   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, and Destination is returned. At
 380   most, Length Unicode characters are concatenated from Source to the end of
 381   Destination, and Destination is always Null-terminated. If Length is 0, then
 382   Destination is returned unmodified. If Source and Destination overlap, then
 383   the results are undefined.
 384
 385   If Destination is NULL, then ASSERT().
 386   If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
 387   If Length > 0 and Source is NULL, then ASSERT().
 388   If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
 389   If Source and Destination overlap, then ASSERT().
 390   If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
 391   PcdMaximumUnicodeStringLength, then ASSERT().
 392   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
 393   than PcdMaximumUnicodeStringLength Unicode characters, not including the
 394   Null-terminator, then ASSERT().
 395   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
 396   PcdMaximumUnicodeStringLength Unicode characters, not including the
 397   Null-terminator, then ASSERT().
 398   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
 399   and Source results in a Unicode string with more than PcdMaximumUnicodeStringLength
 400   Unicode characters, not including the Null-terminator, then ASSERT().
 401
 402   @param  Destination Pointer to a Null-terminated Unicode string.
 403   @param  Source      Pointer to a Null-terminated Unicode string.
 404   @param  Length      Maximum number of Unicode characters to concatenate from
 405                       Source.
 406
 407   @return Destination
 408
 409 **/
 410 CHAR16 *
 411 EFIAPI
 412 GlueStrnCat (
 413   IN OUT  CHAR16                    *Destination,
 414   IN      CONST CHAR16              *Source,
 415   IN      UINTN                     Length
 416   );
 417
 418 /**
 419   Returns the first occurance of a Null-terminated Unicode sub-string
 420   in a Null-terminated Unicode string.
 421
 422   This function scans the contents of the Null-terminated Unicode string
 423   specified by String and returns the first occurrence of SearchString.
 424   If SearchString is not found in String, then NULL is returned.  If
 425   the length of SearchString is zero, then String is
 426   returned.
 427
 428   If String is NULL, then ASSERT().
 429   If String is not aligned on a 16-bit boundary, then ASSERT().
 430   If SearchString is NULL, then ASSERT().
 431   If SearchString is not aligned on a 16-bit boundary, then ASSERT().
 432
 433   If PcdMaximumUnicodeStringLength is not zero, and SearchString
 434   or String contains more than PcdMaximumUnicodeStringLength Unicode
 435   characters not including the Null-terminator, then ASSERT().
 436
 437   @param  String                                  Pointer to a Null-terminated Unicode string.
 438   @param  SearchString  Pointer to a Null-terminated Unicode string to search for.
 439
 440   @retval NULL            If the SearchString does not appear in String.
 441   @retval !NULL           If there is a match.
 442
 443 **/
 444 CHAR16 *
 445 EFIAPI
 446 StrStr (
 447   IN      CONST CHAR16                *String,
 448   IN      CONST CHAR16                *SearchString
 449   );
 450
 451 /**
 452   Convert a Null-terminated Unicode decimal string to a value of
 453   type UINTN.
 454
 455   This function returns a value of type UINTN by interpreting the contents
 456   of the Unicode string specified by String as a decimal number. The format
 457   of the input Unicode string String is:
 458
 459                   [spaces] [decimal digits].
 460
 461   The valid decimal digit character is in the range [0-9]. The
 462   function will ignore the pad space, which includes spaces or
 463   tab characters, before [decimal digits]. The running zero in the
 464   beginning of [decimal digits] will be ignored. Then, the function
 465   stops at the first character that is a not a valid decimal character
 466   or a Null-terminator, whichever one comes first.
 467
 468   If String is NULL, then ASSERT().
 469   If String is not aligned in a 16-bit boundary, then ASSERT().
 470   If String has only pad spaces, then 0 is returned.
 471   If String has no pad spaces or valid decimal digits,
 472   then 0 is returned.
 473   If the number represented by String overflows according
 474   to the range defined by UINTN, then ASSERT().
 475
 476   If PcdMaximumUnicodeStringLength is not zero, and String contains
 477   more than PcdMaximumUnicodeStringLength Unicode characters not including
 478   the Null-terminator, then ASSERT().
 479
 480   @param  String                            Pointer to a Null-terminated Unicode string.
 481
 482   @retval UINTN
 483
 484 **/
 485 UINTN
 486 EFIAPI
 487 StrDecimalToUintn (
 488   IN      CONST CHAR16                *String
 489   );
 490
 491 /**
 492   Convert a Null-terminated Unicode decimal string to a value of
 493   type UINT64.
 494
 495   This function returns a value of type UINT64 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 UINT64, 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 UINT64
 523
 524 **/
 525 UINT64
 526 EFIAPI
 527 StrDecimalToUint64 (
 528   IN      CONST CHAR16                *String
 529   );
 530
 531
 532 /**
 533   Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
 534
 535   This function returns a value of type UINTN by interpreting the contents
 536   of the Unicode string specified by String as a hexadecimal number.
 537   The format of the input Unicode string String is:
 538
 539                   [spaces][zeros][x][hexadecimal digits].
 540
 541   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
 542   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
 543   If "x" appears in the input string, it must be prefixed with at least one 0.
 544   The function will ignore the pad space, which includes spaces or tab characters,
 545   before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
 546   [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
 547   first valid hexadecimal digit. Then, the function stops at the first character that is
 548   a not a valid hexadecimal character or NULL, whichever one comes first.
 549
 550   If String is NULL, then ASSERT().
 551   If String is not aligned in a 16-bit boundary, then ASSERT().
 552   If String has only pad spaces, then zero is returned.
 553   If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
 554   then zero is returned.
 555   If the number represented by String overflows according to the range defined by
 556   UINTN, then ASSERT().
 557
 558   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
 559   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
 560   then ASSERT().
 561
 562   @param  String                            Pointer to a Null-terminated Unicode string.
 563
 564   @retval UINTN
 565
 566 **/
 567 UINTN
 568 EFIAPI
 569 StrHexToUintn (
 570   IN      CONST CHAR16                *String
 571   );
 572
 573
 574 /**
 575   Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
 576
 577   This function returns a value of type UINT64 by interpreting the contents
 578   of the Unicode string specified by String as a hexadecimal number.
 579   The format of the input Unicode string String is
 580
 581                   [spaces][zeros][x][hexadecimal digits].
 582
 583   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
 584   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
 585   If "x" appears in the input string, it must be prefixed with at least one 0.
 586   The function will ignore the pad space, which includes spaces or tab characters,
 587   before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
 588   [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
 589   first valid hexadecimal digit. Then, the function stops at the first character that is
 590   a not a valid hexadecimal character or NULL, whichever one comes first.
 591
 592   If String is NULL, then ASSERT().
 593   If String is not aligned in a 16-bit boundary, then ASSERT().
 594   If String has only pad spaces, then zero is returned.
 595   If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
 596   then zero is returned.
 597   If the number represented by String overflows according to the range defined by
 598   UINT64, then ASSERT().
 599
 600   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
 601   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
 602   then ASSERT().
 603
 604   @param  String                            Pointer to a Null-terminated Unicode string.
 605
 606   @retval UINT64
 607
 608 **/
 609 UINT64
 610 EFIAPI
 611 StrHexToUint64 (
 612   IN      CONST CHAR16                *String
 613   );
 614
 615
 616 /**
 617   Convert one Null-terminated Unicode string to a Null-terminated
 618   ASCII string and returns the ASCII string.
 619
 620   This function converts the content of the Unicode string Source
 621   to the ASCII string Destination by copying the lower 8 bits of
 622   each Unicode character. It returns Destination.
 623
 624   If any Unicode characters in Source contain non-zero value in
 625   the upper 8 bits, then ASSERT().
 626
 627   If Destination is NULL, then ASSERT().
 628   If Source is NULL, then ASSERT().
 629   If Source is not aligned on a 16-bit boundary, then ASSERT().
 630   If Source and Destination overlap, then ASSERT().
 631
 632   If PcdMaximumUnicodeStringLength is not zero, and Source contains
 633   more than PcdMaximumUnicodeStringLength Unicode characters not including
 634   the Null-terminator, then ASSERT().
 635
 636   If PcdMaximumAsciiStringLength is not zero, and Source contains more
 637   than PcdMaximumAsciiStringLength Unicode characters not including the
 638   Null-terminator, then ASSERT().
 639
 640   @param  Source        Pointer to a Null-terminated Unicode string.
 641   @param  Destination   Pointer to a Null-terminated ASCII string.
 642
 643   @reture Destination
 644
 645 **/
 646 CHAR8 *
 647 EFIAPI
 648 UnicodeStrToAsciiStr (
 649   IN      CONST CHAR16                *Source,
 650   OUT     CHAR8                           *Destination
 651   );
 652
 653
 654 /**
 655   Copies one Null-terminated ASCII string to another Null-terminated ASCII
 656   string and returns the new ASCII string.
 657
 658   This function copies the contents of the ASCII string Source to the ASCII
 659   string Destination, and returns Destination. If Source and Destination
 660   overlap, then the results are undefined.
 661
 662   If Destination is NULL, then ASSERT().
 663   If Source is NULL, then ASSERT().
 664   If Source and Destination overlap, then ASSERT().
 665   If PcdMaximumAsciiStringLength is not zero and Source contains more than
 666   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
 667   then ASSERT().
 668
 669   @param  Destination Pointer to a Null-terminated ASCII string.
 670   @param  Source      Pointer to a Null-terminated ASCII string.
 671
 672   @return Destination
 673
 674 **/
 675 CHAR8 *
 676 EFIAPI
 677 AsciiStrCpy (
 678   OUT     CHAR8                     *Destination,
 679   IN      CONST CHAR8               *Source
 680   );
 681
 682
 683 /**
 684   Copies one Null-terminated ASCII string with a maximum length to another
 685   Null-terminated ASCII string with a maximum length and returns the new ASCII
 686   string.
 687
 688   This function copies the contents of the ASCII string Source to the ASCII
 689   string Destination, and returns Destination. At most, Length ASCII characters
 690   are copied from Source to Destination. If Length is 0, then Destination is
 691   returned unmodified. If Length is greater that the number of ASCII characters
 692   in Source, then Destination is padded with Null ASCII characters. If Source
 693   and Destination overlap, then the results are undefined.
 694
 695   If Destination is NULL, then ASSERT().
 696   If Source is NULL, then ASSERT().
 697   If Source and Destination overlap, then ASSERT().
 698   If PcdMaximumAsciiStringLength is not zero, and Length is greater than
 699   PcdMaximumAsciiStringLength, then ASSERT().
 700   If PcdMaximumAsciiStringLength is not zero, and Source contains more than
 701   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
 702   then ASSERT().
 703
 704   @param  Destination Pointer to a Null-terminated ASCII string.
 705   @param  Source      Pointer to a Null-terminated ASCII string.
 706   @param  Length      Maximum number of ASCII characters to copy.
 707
 708   @return Destination
 709
 710 **/
 711 CHAR8 *
 712 EFIAPI
 713 AsciiStrnCpy (
 714   OUT     CHAR8                     *Destination,
 715   IN      CONST CHAR8               *Source,
 716   IN      UINTN                     Length
 717   );
 718
 719
 720 /**
 721   Returns the length of a Null-terminated ASCII string.
 722
 723   This function returns the number of ASCII characters in the Null-terminated
 724   ASCII string specified by String.
 725
 726   If Length > 0 and Destination is NULL, then ASSERT().
 727   If Length > 0 and Source is NULL, then ASSERT().
 728   If PcdMaximumAsciiStringLength is not zero and String contains more than
 729   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
 730   then ASSERT().
 731
 732   @param  String  Pointer to a Null-terminated ASCII string.
 733
 734   @return The length of String.
 735
 736 **/
 737 UINTN
 738 EFIAPI
 739 AsciiStrLen (
 740   IN      CONST CHAR8               *String
 741   );
 742
 743
 744 /**
 745   Returns the size of a Null-terminated ASCII string in bytes, including the
 746   Null terminator.
 747
 748   This function returns the size, in bytes, of the Null-terminated ASCII string
 749   specified by String.
 750
 751   If String is NULL, then ASSERT().
 752   If PcdMaximumAsciiStringLength is not zero and String contains more than
 753   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
 754   then ASSERT().
 755
 756   @param  String  Pointer to a Null-terminated ASCII string.
 757
 758   @return The size of String.
 759
 760 **/
 761 UINTN
 762 EFIAPI
 763 AsciiStrSize (
 764   IN      CONST CHAR8               *String
 765   );
 766
 767
 768 /**
 769   Compares two Null-terminated ASCII strings, and returns the difference
 770   between the first mismatched ASCII characters.
 771
 772   This function compares the Null-terminated ASCII string FirstString to the
 773   Null-terminated ASCII string SecondString. If FirstString is identical to
 774   SecondString, then 0 is returned. Otherwise, the value returned is the first
 775   mismatched ASCII character in SecondString subtracted from the first
 776   mismatched ASCII character in FirstString.
 777
 778   If FirstString is NULL, then ASSERT().
 779   If SecondString is NULL, then ASSERT().
 780   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
 781   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
 782   then ASSERT().
 783   If PcdMaximumAsciiStringLength is not zero and SecondString contains more
 784   than PcdMaximumAsciiStringLength ASCII characters not including the
 785   Null-terminator, then ASSERT().
 786
 787   @param  FirstString   Pointer to a Null-terminated ASCII string.
 788   @param  SecondString  Pointer to a Null-terminated ASCII string.
 789
 790   @retval 0   FirstString is identical to SecondString.
 791   @retval !=0 FirstString is not identical to SecondString.
 792
 793 **/
 794 INTN
 795 EFIAPI
 796 AsciiStrCmp (
 797   IN      CONST CHAR8               *FirstString,
 798   IN      CONST CHAR8               *SecondString
 799   );
 800
 801
 802 /**
 803   Performs a case insensitive comparison of two Null-terminated ASCII strings,
 804   and returns the difference between the first mismatched ASCII characters.
 805
 806   This function performs a case insensitive comparison of the Null-terminated
 807   ASCII string FirstString to the Null-terminated ASCII string SecondString. If
 808   FirstString is identical to SecondString, then 0 is returned. Otherwise, the
 809   value returned is the first mismatched lower case ASCII character in
 810   SecondString subtracted from the first mismatched lower case ASCII character
 811   in FirstString.
 812
 813   If FirstString is NULL, then ASSERT().
 814   If SecondString is NULL, then ASSERT().
 815   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
 816   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
 817   then ASSERT().
 818   If PcdMaximumAsciiStringLength is not zero and SecondString contains more
 819   than PcdMaximumAsciiStringLength ASCII characters not including the
 820   Null-terminator, then ASSERT().
 821
 822   @param  FirstString   Pointer to a Null-terminated ASCII string.
 823   @param  SecondString  Pointer to a Null-terminated ASCII string.
 824
 825   @retval 0   FirstString is identical to SecondString using case insensitive
 826               comparisons.
 827   @retval !=0 FirstString is not identical to SecondString using case
 828               insensitive comparisons.
 829
 830 **/
 831 INTN
 832 EFIAPI
 833 AsciiStriCmp (
 834   IN      CONST CHAR8               *FirstString,
 835   IN      CONST CHAR8               *SecondString
 836   );
 837
 838
 839 /**
 840   Compares two Null-terminated ASCII strings with maximum lengths, and returns
 841   the difference between the first mismatched ASCII characters.
 842
 843   This function compares the Null-terminated ASCII string FirstString to the
 844   Null-terminated ASCII  string SecondString. At most, Length ASCII characters
 845   will be compared. If Length is 0, then 0 is returned. If FirstString is
 846   identical to SecondString, then 0 is returned. Otherwise, the value returned
 847   is the first mismatched ASCII character in SecondString subtracted from the
 848   first mismatched ASCII character in FirstString.
 849
 850   If Length > 0 and FirstString is NULL, then ASSERT().
 851   If Length > 0 and SecondString is NULL, then ASSERT().
 852   If PcdMaximumAsciiStringLength is not zero, and Length is greater than
 853   PcdMaximumAsciiStringLength, then ASSERT().
 854   If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
 855   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
 856   then ASSERT().
 857   If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
 858   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
 859   then ASSERT().
 860
 861   @param  FirstString   Pointer to a Null-terminated ASCII string.
 862   @param  SecondString  Pointer to a Null-terminated ASCII string.
 863
 864   @retval 0   FirstString is identical to SecondString.
 865   @retval !=0 FirstString is not identical to SecondString.
 866
 867 **/
 868 INTN
 869 EFIAPI
 870 AsciiStrnCmp (
 871   IN      CONST CHAR8               *FirstString,
 872   IN      CONST CHAR8               *SecondString,
 873   IN      UINTN                     Length
 874   );
 875
 876
 877 /**
 878   Concatenates one Null-terminated ASCII string to another Null-terminated
 879   ASCII string, and returns the concatenated ASCII string.
 880
 881   This function concatenates two Null-terminated ASCII strings. The contents of
 882   Null-terminated ASCII string Source are concatenated to the end of Null-
 883   terminated ASCII string Destination. The Null-terminated concatenated ASCII
 884   String is returned.
 885
 886   If Destination is NULL, then ASSERT().
 887   If Source is NULL, then ASSERT().
 888   If PcdMaximumAsciiStringLength is not zero and Destination contains more than
 889   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
 890   then ASSERT().
 891   If PcdMaximumAsciiStringLength is not zero and Source contains more than
 892   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
 893   then ASSERT().
 894   If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
 895   Source results in a ASCII string with more than PcdMaximumAsciiStringLength
 896   ASCII characters, then ASSERT().
 897
 898   @param  Destination Pointer to a Null-terminated ASCII string.
 899   @param  Source      Pointer to a Null-terminated ASCII string.
 900
 901   @return Destination
 902
 903 **/
 904 CHAR8 *
 905 EFIAPI
 906 AsciiStrCat (
 907   IN OUT CHAR8    *Destination,
 908   IN CONST CHAR8  *Source
 909   );
 910
 911
 912 /**
 913   Concatenates one Null-terminated ASCII string with a maximum length to the
 914   end of another Null-terminated ASCII string, and returns the concatenated
 915   ASCII string.
 916
 917   This function concatenates two Null-terminated ASCII strings. The contents
 918   of Null-terminated ASCII string Source are concatenated to the end of Null-
 919   terminated ASCII string Destination, and Destination is returned. At most,
 920   Length ASCII characters are concatenated from Source to the end of
 921   Destination, and Destination is always Null-terminated. If Length is 0, then
 922   Destination is returned unmodified. If Source and Destination overlap, then
 923   the results are undefined.
 924
 925   If Length > 0 and Destination is NULL, then ASSERT().
 926   If Length > 0 and Source is NULL, then ASSERT().
 927   If Source and Destination overlap, then ASSERT().
 928   If PcdMaximumAsciiStringLength is not zero, and Length is greater than
 929   PcdMaximumAsciiStringLength, then ASSERT().
 930   If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
 931   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
 932   then ASSERT().
 933   If PcdMaximumAsciiStringLength is not zero, and Source contains more than
 934   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
 935   then ASSERT().
 936   If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
 937   Source results in a ASCII string with more than PcdMaximumAsciiStringLength
 938   ASCII characters, not including the Null-terminator, then ASSERT().
 939
 940   @param  Destination Pointer to a Null-terminated ASCII string.
 941   @param  Source      Pointer to a Null-terminated ASCII string.
 942   @param  Length      Maximum number of ASCII characters to concatenate from
 943                       Source.
 944
 945   @return Destination
 946
 947 **/
 948 CHAR8 *
 949 EFIAPI
 950 AsciiStrnCat (
 951   IN OUT  CHAR8                     *Destination,
 952   IN      CONST CHAR8               *Source,
 953   IN      UINTN                     Length
 954   );
 955
 956
 957 /**
 958   Returns the first occurance of a Null-terminated ASCII sub-string
 959   in a Null-terminated ASCII string.
 960
 961   This function scans the contents of the ASCII string specified by String
 962   and returns the first occurrence of SearchString. If SearchString is not
 963   found in String, then NULL is returned. If the length of SearchString is zero,
 964   then String is returned.
 965
 966   If String is NULL, then ASSERT().
 967   If SearchString is NULL, then ASSERT().
 968
 969   If PcdMaximumAsciiStringLength is not zero, and SearchString or
 970   String contains more than PcdMaximumAsciiStringLength Unicode characters
 971   not including the Null-terminator, then ASSERT().
 972
 973   @param  String                                  Pointer to a Null-terminated ASCII string.
 974   @param  SearchString    Pointer to a Null-terminated ASCII string to search for.
 975
 976   @retval NULL            If the SearchString does not appear in String.
 977   @retval !NULL           If there is a match.
 978
 979 **/
 980 CHAR8 *
 981 EFIAPI
 982 AsciiStrStr (
 983   IN      CONST CHAR8                   *String,
 984   IN      CONST CHAR8                   *SearchString
 985   );
 986
 987
 988 /**
 989   Convert a Null-terminated ASCII decimal string to a value of type
 990   UINTN.
 991
 992   This function returns a value of type UINTN by interpreting the contents
 993   of the ASCII string String as a decimal number. The format of the input
 994   ASCII string String is:
 995
 996                     [spaces] [decimal digits].
 997
 998   The valid decimal digit character is in the range [0-9]. The function will
 999   ignore the pad space, which includes spaces or tab characters, before the digits.
1000   The running zero in the beginning of [decimal digits] will be ignored. Then, the
1001   function stops at the first character that is a not a valid decimal character or
1002   Null-terminator, whichever on comes first.
1003
1004   If String has only pad spaces, then 0 is returned.
1005   If String has no pad spaces or valid decimal digits, then 0 is returned.
1006   If the number represented by String overflows according to the range defined by
1007   UINTN, then ASSERT().
1008   If String is NULL, then ASSERT().
1009   If PcdMaximumAsciiStringLength is not zero, and String contains more than
1010   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1011   then ASSERT().
1012
1013   @param  String                            Pointer to a Null-terminated ASCII string.
1014
1015   @retval UINTN
1016
1017 **/
1018 UINTN
1019 EFIAPI
1020 AsciiStrDecimalToUintn (
1021   IN      CONST CHAR8               *String
1022   );
1023
1024
1025 /**
1026   Convert a Null-terminated ASCII decimal string to a value of type
1027   UINT64.
1028
1029   This function returns a value of type UINT64 by interpreting the contents
1030   of the ASCII string String as a decimal number. The format of the input
1031   ASCII string String is:
1032
1033                     [spaces] [decimal digits].
1034
1035   The valid decimal digit character is in the range [0-9]. The function will
1036   ignore the pad space, which includes spaces or tab characters, before the digits.
1037   The running zero in the beginning of [decimal digits] will be ignored. Then, the
1038   function stops at the first character that is a not a valid decimal character or
1039   Null-terminator, whichever on comes first.
1040
1041   If String has only pad spaces, then 0 is returned.
1042   If String has no pad spaces or valid decimal digits, then 0 is returned.
1043   If the number represented by String overflows according to the range defined by
1044   UINT64, then ASSERT().
1045   If String is NULL, then ASSERT().
1046   If PcdMaximumAsciiStringLength is not zero, and String contains more than
1047   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1048   then ASSERT().
1049
1050   @param  String                            Pointer to a Null-terminated ASCII string.
1051
1052   @retval UINT64
1053
1054 **/
1055 UINT64
1056 EFIAPI
1057 AsciiStrDecimalToUint64 (
1058   IN      CONST CHAR8                 *String
1059   );
1060
1061
1062 /**
1063   Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1064
1065   This function returns a value of type UINTN by interpreting the contents of
1066   the ASCII string String as a hexadecimal number. The format of the input ASCII
1067   string String is:
1068
1069                   [spaces][zeros][x][hexadecimal digits].
1070
1071   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1072   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1073   appears in the input string, it must be prefixed with at least one 0. The function
1074   will ignore the pad space, which includes spaces or tab characters, before [zeros],
1075   [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1076   will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1077   digit. Then, the function stops at the first character that is a not a valid
1078   hexadecimal character or Null-terminator, whichever on comes first.
1079
1080   If String has only pad spaces, then 0 is returned.
1081   If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1082   0 is returned.
1083
1084   If the number represented by String overflows according to the range defined by UINTN,
1085   then ASSERT().
1086   If String is NULL, then ASSERT().
1087   If PcdMaximumAsciiStringLength is not zero,
1088   and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1089   the Null-terminator, then ASSERT().
1090
1091   @param  String                            Pointer to a Null-terminated ASCII string.
1092
1093   @retval UINTN
1094
1095 **/
1096 UINTN
1097 EFIAPI
1098 AsciiStrHexToUintn (
1099   IN      CONST CHAR8                 *String
1100   );
1101
1102
1103 /**
1104   Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1105
1106   This function returns a value of type UINT64 by interpreting the contents of
1107   the ASCII string String as a hexadecimal number. The format of the input ASCII
1108   string String is:
1109
1110                   [spaces][zeros][x][hexadecimal digits].
1111
1112   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1113   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1114   appears in the input string, it must be prefixed with at least one 0. The function
1115   will ignore the pad space, which includes spaces or tab characters, before [zeros],
1116   [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1117   will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1118   digit. Then, the function stops at the first character that is a not a valid
1119   hexadecimal character or Null-terminator, whichever on comes first.
1120
1121   If String has only pad spaces, then 0 is returned.
1122   If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1123   0 is returned.
1124
1125   If the number represented by String overflows according to the range defined by UINT64,
1126   then ASSERT().
1127   If String is NULL, then ASSERT().
1128   If PcdMaximumAsciiStringLength is not zero,
1129   and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1130   the Null-terminator, then ASSERT().
1131
1132   @param  String                            Pointer to a Null-terminated ASCII string.
1133
1134   @retval UINT64
1135
1136 **/
1137 UINT64
1138 EFIAPI
1139 AsciiStrHexToUint64 (
1140   IN      CONST CHAR8                   *String
1141   );
1142
1143
1144 /**
1145   Convert one Null-terminated ASCII string to a Null-terminated
1146   Unicode string and returns the Unicode string.
1147
1148   This function converts the contents of the ASCII string Source to the Unicode
1149   string Destination, and returns Destination.  The function terminates the
1150   Unicode string Destination by appending a Null-terminator character at the end.
1151   The caller is responsible to make sure Destination points to a buffer with size
1152   equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
1153
1154   If Destination is NULL, then ASSERT().
1155   If Destination is not aligned on a 16-bit boundary, then ASSERT().
1156   If Source is NULL, then ASSERT().
1157   If Source and Destination overlap, then ASSERT().
1158   If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1159   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1160   then ASSERT().
1161   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1162   PcdMaximumUnicodeStringLength ASCII characters not including the
1163   Null-terminator, then ASSERT().
1164
1165   @param  Source        Pointer to a Null-terminated ASCII string.
1166   @param  Destination   Pointer to a Null-terminated Unicode string.
1167
1168   @reture Destination
1169
1170 **/
1171 CHAR16 *
1172 EFIAPI
1173 AsciiStrToUnicodeStr (
1174   IN      CONST CHAR8                 *Source,
1175   OUT     CHAR16                        *Destination
1176   );
1177
1178
1179 /**
1180   Converts an 8-bit value to an 8-bit BCD value.
1181
1182   Converts the 8-bit value specified by Value to BCD. The BCD value is
1183   returned.
1184
1185   If Value >= 100, then ASSERT().
1186
1187   @param  Value The 8-bit value to convert to BCD. Range 0..99.
1188
1189   @return The BCD value
1190
1191 **/
1192 UINT8
1193 EFIAPI
1194 DecimalToBcd8 (
1195   IN      UINT8                     Value
1196   );
1197
1198
1199 /**
1200   Converts an 8-bit BCD value to an 8-bit value.
1201
1202   Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
1203   value is returned.
1204
1205   If Value >= 0xA0, then ASSERT().
1206   If (Value & 0x0F) >= 0x0A, then ASSERT().
1207
1208   @param  Value The 8-bit BCD value to convert to an 8-bit value.
1209
1210   @return The 8-bit value is returned.
1211
1212 **/
1213 UINT8
1214 EFIAPI
1215 BcdToDecimal8 (
1216   IN      UINT8                     Value
1217   );
1218
1219 //
1220 // LIST_ENTRY definition
1221 //
1222 typedef struct _LIST_ENTRY LIST_ENTRY;
1223
1224 struct _LIST_ENTRY {
1225   LIST_ENTRY  *ForwardLink;
1226   LIST_ENTRY  *BackLink;
1227 };
1228
1229 //
1230 // Linked List Functions and Macros
1231 //
1232
1233 /**
1234   Initializes the head node of a doubly linked list that is declared as a
1235   global variable in a module.
1236
1237   Initializes the forward and backward links of a new linked list. After
1238   initializing a linked list with this macro, the other linked list functions
1239   may be used to add and remove nodes from the linked list. This macro results
1240   in smaller executables by initializing the linked list in the data section,
1241   instead if calling the InitializeListHead() function to perform the
1242   equivalent operation.
1243
1244   @param  ListHead  The head note of a list to initiailize.
1245
1246 **/
1247 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead)  {&ListHead, &ListHead}
1248
1249
1250 /**
1251   Initializes the head node of a doubly linked list, and returns the pointer to
1252   the head node of the doubly linked list.
1253
1254   Initializes the forward and backward links of a new linked list. After
1255   initializing a linked list with this function, the other linked list
1256   functions may be used to add and remove nodes from the linked list. It is up
1257   to the caller of this function to allocate the memory for ListHead.
1258
1259   If ListHead is NULL, then ASSERT().
1260
1261   @param  ListHead  A pointer to the head node of a new doubly linked list.
1262
1263   @return ListHead
1264
1265 **/
1266 LIST_ENTRY *
1267 EFIAPI
1268 GlueInitializeListHead (
1269   IN      LIST_ENTRY                *ListHead
1270   );
1271
1272
1273 /**
1274   Adds a node to the beginning of a doubly linked list, and returns the pointer
1275   to the head node of the doubly linked list.
1276
1277   Adds the node Entry at the beginning of the doubly linked list denoted by
1278   ListHead, and returns ListHead.
1279
1280   If ListHead is NULL, then ASSERT().
1281   If Entry is NULL, then ASSERT().
1282   If ListHead was not initialized with InitializeListHead(), then ASSERT().
1283   If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number
1284   of nodes in ListHead, including the ListHead node, is greater than or
1285   equal to PcdMaximumLinkedListLength, then ASSERT().
1286
1287   @param  ListHead  A pointer to the head node of a doubly linked list.
1288   @param  Entry     A pointer to a node that is to be inserted at the beginning
1289                     of a doubly linked list.
1290
1291   @return ListHead
1292
1293 **/
1294 LIST_ENTRY *
1295 EFIAPI
1296 GlueInsertHeadList (
1297   IN      LIST_ENTRY                *ListHead,
1298   IN      LIST_ENTRY                *Entry
1299   );
1300
1301
1302 /**
1303   Adds a node to the end of a doubly linked list, and returns the pointer to
1304   the head node of the doubly linked list.
1305
1306   Adds the node Entry to the end of the doubly linked list denoted by ListHead,
1307   and returns ListHead.
1308
1309   If ListHead is NULL, then ASSERT().
1310   If Entry is NULL, then ASSERT().
1311   If ListHead was not initialized with InitializeListHead(), then ASSERT().
1312   If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number
1313   of nodes in ListHead, including the ListHead node, is greater than or
1314   equal to PcdMaximumLinkedListLength, then ASSERT().
1315
1316   @param  ListHead  A pointer to the head node of a doubly linked list.
1317   @param  Entry     A pointer to a node that is to be added at the end of the
1318                     doubly linked list.
1319
1320   @return ListHead
1321
1322 **/
1323 LIST_ENTRY *
1324 EFIAPI
1325 GlueInsertTailList (
1326   IN      LIST_ENTRY                *ListHead,
1327   IN      LIST_ENTRY                *Entry
1328   );
1329
1330
1331 /**
1332   Retrieves the first node of a doubly linked list.
1333
1334   Returns the first node of a doubly linked list. List must have been
1335   initialized with InitializeListHead(). If List is empty, then NULL is
1336   returned.
1337
1338   If List is NULL, then ASSERT().
1339   If List was not initialized with InitializeListHead(), then ASSERT().
1340   If PcdMaximumLinkedListLenth is not zero, and the number of nodes
1341   in List, including the List node, is greater than or equal to
1342   PcdMaximumLinkedListLength, then ASSERT().
1343
1344   @param  List  A pointer to the head node of a doubly linked list.
1345
1346   @return The first node of a doubly linked list.
1347   @retval NULL  The list is empty.
1348
1349 **/
1350 LIST_ENTRY *
1351 EFIAPI
1352 GlueGetFirstNode (
1353   IN      CONST LIST_ENTRY          *List
1354   );
1355
1356
1357 /**
1358   Retrieves the next node of a doubly linked list.
1359
1360   Returns the node of a doubly linked list that follows Node. List must have
1361   been initialized with InitializeListHead(). If List is empty, then List is
1362   returned.
1363
1364   If List is NULL, then ASSERT().
1365   If Node is NULL, then ASSERT().
1366   If List was not initialized with InitializeListHead(), then ASSERT().
1367   If PcdMaximumLinkedListLenth is not zero, and List contains more than
1368   PcdMaximumLinkedListLenth nodes, then ASSERT().
1369   If Node is not a node in List, then ASSERT().
1370
1371   @param  List  A pointer to the head node of a doubly linked list.
1372   @param  Node  A pointer to a node in the doubly linked list.
1373
1374   @return Pointer to the next node if one exists. Otherwise a null value which
1375           is actually List is returned.
1376
1377 **/
1378 LIST_ENTRY *
1379 EFIAPI
1380 GlueGetNextNode (
1381   IN      CONST LIST_ENTRY          *List,
1382   IN      CONST LIST_ENTRY          *Node
1383   );
1384
1385
1386 /**
1387   Checks to see if a doubly linked list is empty or not.
1388
1389   Checks to see if the doubly linked list is empty. If the linked list contains
1390   zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
1391
1392   If ListHead is NULL, then ASSERT().
1393   If ListHead was not initialized with InitializeListHead(), then ASSERT().
1394   If PcdMaximumLinkedListLenth is not zero, and the number of nodes
1395   in List, including the List node, is greater than or equal to
1396   PcdMaximumLinkedListLength, then ASSERT().
1397
1398   @param  ListHead  A pointer to the head node of a doubly linked list.
1399
1400   @retval TRUE  The linked list is empty.
1401   @retval FALSE The linked list is not empty.
1402
1403 **/
1404 BOOLEAN
1405 EFIAPI
1406 GlueIsListEmpty (
1407   IN      CONST LIST_ENTRY          *ListHead
1408   );
1409
1410
1411 /**
1412   Determines if a node in a doubly linked list is null.
1413
1414   Returns FALSE if Node is one of the nodes in the doubly linked list specified
1415   by List. Otherwise, TRUE is returned. List must have been initialized with
1416   InitializeListHead().
1417
1418   If List is NULL, then ASSERT().
1419   If Node is NULL, then ASSERT().
1420   If List was not initialized with InitializeListHead(), then ASSERT().
1421   If PcdMaximumLinkedListLenth is not zero, and the number of nodes
1422   in List, including the List node, is greater than or equal to
1423   PcdMaximumLinkedListLength, then ASSERT().
1424   If Node is not a node in List and Node is not equal to List, then ASSERT().
1425
1426   @param  List  A pointer to the head node of a doubly linked list.
1427   @param  Node  A pointer to a node in the doubly linked list.
1428
1429   @retval TRUE  Node is one of the nodes in the doubly linked list.
1430   @retval FALSE Node is not one of the nodes in the doubly linked list.
1431
1432 **/
1433 BOOLEAN
1434 EFIAPI
1435 GlueIsNull (
1436   IN      CONST LIST_ENTRY          *List,
1437   IN      CONST LIST_ENTRY          *Node
1438   );
1439
1440
1441 /**
1442   Determines if a node the last node in a doubly linked list.
1443
1444   Returns TRUE if Node is the last node in the doubly linked list specified by
1445   List. Otherwise, FALSE is returned. List must have been initialized with
1446   InitializeListHead().
1447
1448   If List is NULL, then ASSERT().
1449   If Node is NULL, then ASSERT().
1450   If List was not initialized with InitializeListHead(), then ASSERT().
1451   If PcdMaximumLinkedListLenth is not zero, and the number of nodes
1452   in List, including the List node, is greater than or equal to
1453   PcdMaximumLinkedListLength, then ASSERT().
1454   If Node is not a node in List, then ASSERT().
1455
1456   @param  List  A pointer to the head node of a doubly linked list.
1457   @param  Node  A pointer to a node in the doubly linked list.
1458
1459   @retval TRUE  Node is the last node in the linked list.
1460   @retval FALSE Node is not the last node in the linked list.
1461
1462 **/
1463 BOOLEAN
1464 EFIAPI
1465 GlueIsNodeAtEnd (
1466   IN      CONST LIST_ENTRY          *List,
1467   IN      CONST LIST_ENTRY          *Node
1468   );
1469
1470
1471 /**
1472   Swaps the location of two nodes in a doubly linked list, and returns the
1473   first node after the swap.
1474
1475   If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
1476   Otherwise, the location of the FirstEntry node is swapped with the location
1477   of the SecondEntry node in a doubly linked list. SecondEntry must be in the
1478   same double linked list as FirstEntry and that double linked list must have
1479   been initialized with InitializeListHead(). SecondEntry is returned after the
1480   nodes are swapped.
1481
1482   If FirstEntry is NULL, then ASSERT().
1483   If SecondEntry is NULL, then ASSERT().
1484   If SecondEntry and FirstEntry are not in the same linked list, then ASSERT().
1485   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
1486   linked list containing the FirstEntry and SecondEntry nodes, including
1487   the FirstEntry and SecondEntry nodes, is greater than or equal to
1488   PcdMaximumLinkedListLength, then ASSERT().
1489
1490   @param  FirstEntry  A pointer to a node in a linked list.
1491   @param  SecondEntry A pointer to another node in the same linked list.
1492
1493 **/
1494 LIST_ENTRY *
1495 EFIAPI
1496 GlueSwapListEntries (
1497   IN      LIST_ENTRY                *FirstEntry,
1498   IN      LIST_ENTRY                *SecondEntry
1499   );
1500
1501
1502 /**
1503   Removes a node from a doubly linked list, and returns the node that follows
1504   the removed node.
1505
1506   Removes the node Entry from a doubly linked list. It is up to the caller of
1507   this function to release the memory used by this node if that is required. On
1508   exit, the node following Entry in the doubly linked list is returned. If
1509   Entry is the only node in the linked list, then the head node of the linked
1510   list is returned.
1511
1512   If Entry is NULL, then ASSERT().
1513   If Entry is the head node of an empty list, then ASSERT().
1514   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
1515   linked list containing Entry, including the Entry node, is greater than
1516   or equal to PcdMaximumLinkedListLength, then ASSERT().
1517
1518   @param  Entry A pointer to a node in a linked list
1519
1520   @return Entry
1521
1522 **/
1523 LIST_ENTRY *
1524 EFIAPI
1525 GlueRemoveEntryList (
1526   IN      CONST LIST_ENTRY          *Entry
1527   );
1528
1529 //
1530 // Math Services
1531 //
1532
1533 /**
1534   Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
1535   with zeros. The shifted value is returned.
1536
1537   This function shifts the 64-bit value Operand to the left by Count bits. The
1538   low Count bits are set to zero. The shifted value is returned.
1539
1540   If Count is greater than 63, then ASSERT().
1541
1542   @param  Operand The 64-bit operand to shift left.
1543   @param  Count   The number of bits to shift left.
1544
1545   @return Operand << Count
1546
1547 **/
1548 UINT64
1549 EFIAPI
1550 GlueLShiftU64 (
1551   IN      UINT64                    Operand,
1552   IN      UINTN                     Count
1553   );
1554
1555
1556 /**
1557   Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
1558   filled with zeros. The shifted value is returned.
1559
1560   This function shifts the 64-bit value Operand to the right by Count bits. The
1561   high Count bits are set to zero. The shifted value is returned.
1562
1563   If Count is greater than 63, then ASSERT().
1564
1565   @param  Operand The 64-bit operand to shift right.
1566   @param  Count   The number of bits to shift right.
1567
1568   @return Operand >> Count
1569
1570 **/
1571 UINT64
1572 EFIAPI
1573 GlueRShiftU64 (
1574   IN      UINT64                    Operand,
1575   IN      UINTN                     Count
1576   );
1577
1578
1579 /**
1580   Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
1581   with original integer's bit 63. The shifted value is returned.
1582
1583   This function shifts the 64-bit value Operand to the right by Count bits. The
1584   high Count bits are set to bit 63 of Operand.  The shifted value is returned.
1585
1586   If Count is greater than 63, then ASSERT().
1587
1588   @param  Operand The 64-bit operand to shift right.
1589   @param  Count   The number of bits to shift right.
1590
1591   @return Operand >> Count
1592
1593 **/
1594 UINT64
1595 EFIAPI
1596 ARShiftU64 (
1597   IN      UINT64                    Operand,
1598   IN      UINTN                     Count
1599   );
1600
1601
1602 /**
1603   Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
1604   with the high bits that were rotated.
1605
1606   This function rotates the 32-bit value Operand to the left by Count bits. The
1607   low Count bits are fill with the high Count bits of Operand. The rotated
1608   value is returned.
1609
1610   If Count is greater than 31, then ASSERT().
1611
1612   @param  Operand The 32-bit operand to rotate left.
1613   @param  Count   The number of bits to rotate left.
1614
1615   @return Operand <<< Count
1616
1617 **/
1618 UINT32
1619 EFIAPI
1620 LRotU32 (
1621   IN      UINT32                    Operand,
1622   IN      UINTN                     Count
1623   );
1624
1625
1626 /**
1627   Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
1628   with the low bits that were rotated.
1629
1630   This function rotates the 32-bit value Operand to the right by Count bits.
1631   The high Count bits are fill with the low Count bits of Operand. The rotated
1632   value is returned.
1633
1634   If Count is greater than 31, then ASSERT().
1635
1636   @param  Operand The 32-bit operand to rotate right.
1637   @param  Count   The number of bits to rotate right.
1638
1639   @return Operand >>> Count
1640
1641 **/
1642 UINT32
1643 EFIAPI
1644 RRotU32 (
1645   IN      UINT32                    Operand,
1646   IN      UINTN                     Count
1647   );
1648
1649
1650 /**
1651   Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
1652   with the high bits that were rotated.
1653
1654   This function rotates the 64-bit value Operand to the left by Count bits. The
1655   low Count bits are fill with the high Count bits of Operand. The rotated
1656   value is returned.
1657
1658   If Count is greater than 63, then ASSERT().
1659
1660   @param  Operand The 64-bit operand to rotate left.
1661   @param  Count   The number of bits to rotate left.
1662
1663   @return Operand <<< Count
1664
1665 **/
1666 UINT64
1667 EFIAPI
1668 LRotU64 (
1669   IN      UINT64                    Operand,
1670   IN      UINTN                     Count
1671   );
1672
1673
1674 /**
1675   Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
1676   with the high low bits that were rotated.
1677
1678   This function rotates the 64-bit value Operand to the right by Count bits.
1679   The high Count bits are fill with the low Count bits of Operand. The rotated
1680   value is returned.
1681
1682   If Count is greater than 63, then ASSERT().
1683
1684   @param  Operand The 64-bit operand to rotate right.
1685   @param  Count   The number of bits to rotate right.
1686
1687   @return Operand >>> Count
1688
1689 **/
1690 UINT64
1691 EFIAPI
1692 RRotU64 (
1693   IN      UINT64                    Operand,
1694   IN      UINTN                     Count
1695   );
1696
1697
1698 /**
1699   Returns the bit position of the lowest bit set in a 32-bit value.
1700
1701   This function computes the bit position of the lowest bit set in the 32-bit
1702   value specified by Operand. If Operand is zero, then -1 is returned.
1703   Otherwise, a value between 0 and 31 is returned.
1704
1705   @param  Operand The 32-bit operand to evaluate.
1706
1707   @return Position of the lowest bit set in Operand if found.
1708   @retval -1 Operand is zero.
1709
1710 **/
1711 INTN
1712 EFIAPI
1713 LowBitSet32 (
1714   IN      UINT32                    Operand
1715   );
1716
1717
1718 /**
1719   Returns the bit position of the lowest bit set in a 64-bit value.
1720
1721   This function computes the bit position of the lowest bit set in the 64-bit
1722   value specified by Operand. If Operand is zero, then -1 is returned.
1723   Otherwise, a value between 0 and 63 is returned.
1724
1725   @param  Operand The 64-bit operand to evaluate.
1726
1727   @return Position of the lowest bit set in Operand if found.
1728   @retval -1  Operand is zero.
1729
1730 **/
1731 INTN
1732 EFIAPI
1733 LowBitSet64 (
1734   IN      UINT64                    Operand
1735   );
1736
1737
1738 /**
1739   Returns the bit position of the highest bit set in a 32-bit value. Equivalent
1740   to log2(x).
1741
1742   This function computes the bit position of the highest bit set in the 32-bit
1743   value specified by Operand. If Operand is zero, then -1 is returned.
1744   Otherwise, a value between 0 and 31 is returned.
1745
1746   @param  Operand The 32-bit operand to evaluate.
1747
1748   @return Position of the highest bit set in Operand if found.
1749   @retval -1  Operand is zero.
1750
1751 **/
1752 INTN
1753 EFIAPI
1754 HighBitSet32 (
1755   IN      UINT32                    Operand
1756   );
1757
1758
1759 /**
1760   Returns the bit position of the highest bit set in a 64-bit value. Equivalent
1761   to log2(x).
1762
1763   This function computes the bit position of the highest bit set in the 64-bit
1764   value specified by Operand. If Operand is zero, then -1 is returned.
1765   Otherwise, a value between 0 and 63 is returned.
1766
1767   @param  Operand The 64-bit operand to evaluate.
1768
1769   @return Position of the highest bit set in Operand if found.
1770   @retval -1  Operand is zero.
1771
1772 **/
1773 INTN
1774 EFIAPI
1775 HighBitSet64 (
1776   IN      UINT64                    Operand
1777   );
1778
1779
1780 /**
1781   Returns the value of the highest bit set in a 32-bit value. Equivalent to
1782   1 << HighBitSet32(x).
1783
1784   This function computes the value of the highest bit set in the 32-bit value
1785   specified by Operand. If Operand is zero, then zero is returned.
1786
1787   @param  Operand The 32-bit operand to evaluate.
1788
1789   @return 1 << HighBitSet32(Operand)
1790   @retval 0 Operand is zero.
1791
1792 **/
1793 UINT32
1794 EFIAPI
1795 GetPowerOfTwo32 (
1796   IN      UINT32                    Operand
1797   );
1798
1799
1800 /**
1801   Returns the value of the highest bit set in a 64-bit value. Equivalent to
1802   1 << HighBitSet64(x).
1803
1804   This function computes the value of the highest bit set in the 64-bit value
1805   specified by Operand. If Operand is zero, then zero is returned.
1806
1807   @param  Operand The 64-bit operand to evaluate.
1808
1809   @return 1 << HighBitSet64(Operand)
1810   @retval 0 Operand is zero.
1811
1812 **/
1813 UINT64
1814 EFIAPI
1815 GetPowerOfTwo64 (
1816   IN      UINT64                    Operand
1817   );
1818
1819
1820 /**
1821   Switches the endianess of a 16-bit integer.
1822
1823   This function swaps the bytes in a 16-bit unsigned value to switch the value
1824   from little endian to big endian or vice versa. The byte swapped value is
1825   returned.
1826
1827   @param  Operand A 16-bit unsigned value.
1828
1829   @return The byte swaped Operand.
1830
1831 **/
1832 UINT16
1833 EFIAPI
1834 SwapBytes16 (
1835   IN      UINT16                    Value
1836   );
1837
1838
1839 /**
1840   Switches the endianess of a 32-bit integer.
1841
1842   This function swaps the bytes in a 32-bit unsigned value to switch the value
1843   from little endian to big endian or vice versa. The byte swapped value is
1844   returned.
1845
1846   @param  Operand A 32-bit unsigned value.
1847
1848   @return The byte swaped Operand.
1849
1850 **/
1851 UINT32
1852 EFIAPI
1853 SwapBytes32 (
1854   IN      UINT32                    Value
1855   );
1856
1857
1858 /**
1859   Switches the endianess of a 64-bit integer.
1860
1861   This function swaps the bytes in a 64-bit unsigned value to switch the value
1862   from little endian to big endian or vice versa. The byte swapped value is
1863   returned.
1864
1865   @param  Operand A 64-bit unsigned value.
1866
1867   @return The byte swaped Operand.
1868
1869 **/
1870 UINT64
1871 EFIAPI
1872 SwapBytes64 (
1873   IN      UINT64                    Value
1874   );
1875
1876
1877 /**
1878   Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
1879   generates a 64-bit unsigned result.
1880
1881   This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
1882   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
1883   bit unsigned result is returned.
1884
1885   If the result overflows, then ASSERT().
1886
1887   @param  Multiplicand  A 64-bit unsigned value.
1888   @param  Multiplier    A 32-bit unsigned value.
1889
1890   @return Multiplicand * Multiplier
1891
1892 **/
1893 UINT64
1894 EFIAPI
1895 GlueMultU64x32 (
1896   IN      UINT64                    Multiplicand,
1897   IN      UINT32                    Multiplier
1898   );
1899
1900
1901 /**
1902   Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
1903   generates a 64-bit unsigned result.
1904
1905   This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
1906   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
1907   bit unsigned result is returned.
1908
1909   If the result overflows, then ASSERT().
1910
1911   @param  Multiplicand  A 64-bit unsigned value.
1912   @param  Multiplier    A 64-bit unsigned value.
1913
1914   @return Multiplicand * Multiplier
1915
1916 **/
1917 UINT64
1918 EFIAPI
1919 MultU64x64 (
1920   IN      UINT64                    Multiplicand,
1921   IN      UINT64                    Multiplier
1922   );
1923
1924
1925 /**
1926   Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
1927   64-bit signed result.
1928
1929   This function multiples the 64-bit signed value Multiplicand by the 64-bit
1930   signed value Multiplier and generates a 64-bit signed result. This 64-bit
1931   signed result is returned.
1932
1933   If the result overflows, then ASSERT().
1934
1935   @param  Multiplicand  A 64-bit signed value.
1936   @param  Multiplier    A 64-bit signed value.
1937
1938   @return Multiplicand * Multiplier
1939
1940 **/
1941 INT64
1942 EFIAPI
1943 MultS64x64 (
1944   IN      INT64                     Multiplicand,
1945   IN      INT64                     Multiplier
1946   );
1947
1948
1949 /**
1950   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
1951   a 64-bit unsigned result.
1952
1953   This function divides the 64-bit unsigned value Dividend by the 32-bit
1954   unsigned value Divisor and generates a 64-bit unsigned quotient. This
1955   function returns the 64-bit unsigned quotient.
1956
1957   If Divisor is 0, then ASSERT().
1958
1959   @param  Dividend  A 64-bit unsigned value.
1960   @param  Divisor   A 32-bit unsigned value.
1961
1962   @return Dividend / Divisor
1963
1964 **/
1965 UINT64
1966 EFIAPI
1967 GlueDivU64x32 (
1968   IN      UINT64                    Dividend,
1969   IN      UINT32                    Divisor
1970   );
1971
1972
1973 /**
1974   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
1975   a 32-bit unsigned remainder.
1976
1977   This function divides the 64-bit unsigned value Dividend by the 32-bit
1978   unsigned value Divisor and generates a 32-bit remainder. This function
1979   returns the 32-bit unsigned remainder.
1980
1981   If Divisor is 0, then ASSERT().
1982
1983   @param  Dividend  A 64-bit unsigned value.
1984   @param  Divisor   A 32-bit unsigned value.
1985
1986   @return Dividend % Divisor
1987
1988 **/
1989 UINT32
1990 EFIAPI
1991 ModU64x32 (
1992   IN      UINT64                    Dividend,
1993   IN      UINT32                    Divisor
1994   );
1995
1996
1997 /**
1998   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
1999   a 64-bit unsigned result and an optional 32-bit unsigned remainder.
2000
2001   This function divides the 64-bit unsigned value Dividend by the 32-bit
2002   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
2003   is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
2004   This function returns the 64-bit unsigned quotient.
2005
2006   If Divisor is 0, then ASSERT().
2007
2008   @param  Dividend  A 64-bit unsigned value.
2009   @param  Divisor   A 32-bit unsigned value.
2010   @param  Remainder A pointer to a 32-bit unsigned value. This parameter is
2011                     optional and may be NULL.
2012
2013   @return Dividend / Divisor
2014
2015 **/
2016 UINT64
2017 EFIAPI
2018 DivU64x32Remainder (
2019   IN      UINT64                    Dividend,
2020   IN      UINT32                    Divisor,
2021   OUT     UINT32                    *Remainder  OPTIONAL
2022   );
2023
2024
2025 /**
2026   Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
2027   a 64-bit unsigned result and an optional 64-bit unsigned remainder.
2028
2029   This function divides the 64-bit unsigned value Dividend by the 64-bit
2030   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
2031   is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
2032   This function returns the 64-bit unsigned quotient.
2033
2034   If Divisor is 0, then ASSERT().
2035
2036   @param  Dividend  A 64-bit unsigned value.
2037   @param  Divisor   A 64-bit unsigned value.
2038   @param  Remainder A pointer to a 64-bit unsigned value. This parameter is
2039                     optional and may be NULL.
2040
2041   @return Dividend / Divisor
2042
2043 **/
2044 UINT64
2045 EFIAPI
2046 DivU64x64Remainder (
2047   IN      UINT64                    Dividend,
2048   IN      UINT64                    Divisor,
2049   OUT     UINT64                    *Remainder  OPTIONAL
2050   );
2051
2052
2053 /**
2054   Divides a 64-bit signed integer by a 64-bit signed integer and generates a
2055   64-bit signed result and a optional 64-bit signed remainder.
2056
2057   This function divides the 64-bit signed value Dividend by the 64-bit signed
2058   value Divisor and generates a 64-bit signed quotient. If Remainder is not
2059   NULL, then the 64-bit signed remainder is returned in Remainder. This
2060   function returns the 64-bit signed quotient.
2061
2062   If Divisor is 0, then ASSERT().
2063
2064   @param  Dividend  A 64-bit signed value.
2065   @param  Divisor   A 64-bit signed value.
2066   @param  Remainder A pointer to a 64-bit signed value. This parameter is
2067                     optional and may be NULL.
2068
2069   @return Dividend / Divisor
2070
2071 **/
2072 INT64
2073 EFIAPI
2074 DivS64x64Remainder (
2075   IN      INT64                     Dividend,
2076   IN      INT64                     Divisor,
2077   OUT     INT64                     *Remainder  OPTIONAL
2078   );
2079
2080
2081 /**
2082   Reads a 16-bit value from memory that may be unaligned.
2083
2084   This function returns the 16-bit value pointed to by Buffer. The function
2085   guarantees that the read operation does not produce an alignment fault.
2086
2087   If the Buffer is NULL, then ASSERT().
2088
2089   @param  Buffer  Pointer to a 16-bit value that may be unaligned.
2090
2091   @return *Uint16
2092
2093 **/
2094 UINT16
2095 EFIAPI
2096 ReadUnaligned16 (
2097   IN      CONST UINT16              *Uint16
2098   );
2099
2100
2101 /**
2102   Writes a 16-bit value to memory that may be unaligned.
2103
2104   This function writes the 16-bit value specified by Value to Buffer. Value is
2105   returned. The function guarantees that the write operation does not produce
2106   an alignment fault.
2107
2108   If the Buffer is NULL, then ASSERT().
2109
2110   @param  Buffer  Pointer to a 16-bit value that may be unaligned.
2111   @param  Value   16-bit value to write to Buffer.
2112
2113   @return Value
2114
2115 **/
2116 UINT16
2117 EFIAPI
2118 WriteUnaligned16 (
2119   OUT     UINT16                    *Uint16,
2120   IN      UINT16                    Value
2121   );
2122
2123
2124 /**
2125   Reads a 24-bit value from memory that may be unaligned.
2126
2127   This function returns the 24-bit value pointed to by Buffer. The function
2128   guarantees that the read operation does not produce an alignment fault.
2129
2130   If the Buffer is NULL, then ASSERT().
2131
2132   @param  Buffer  Pointer to a 24-bit value that may be unaligned.
2133
2134   @return The value read.
2135
2136 **/
2137 UINT32
2138 EFIAPI
2139 ReadUnaligned24 (
2140   IN      CONST UINT32              *Buffer
2141   );
2142
2143
2144 /**
2145   Writes a 24-bit value to memory that may be unaligned.
2146
2147   This function writes the 24-bit value specified by Value to Buffer. Value is
2148   returned. The function guarantees that the write operation does not produce
2149   an alignment fault.
2150
2151   If the Buffer is NULL, then ASSERT().
2152
2153   @param  Buffer  Pointer to a 24-bit value that may be unaligned.
2154   @param  Value   24-bit value to write to Buffer.
2155
2156   @return The value written.
2157
2158 **/
2159 UINT32
2160 EFIAPI
2161 WriteUnaligned24 (
2162   OUT     UINT32                    *Buffer,
2163   IN      UINT32                    Value
2164   );
2165
2166
2167 /**
2168   Reads a 32-bit value from memory that may be unaligned.
2169
2170   This function returns the 32-bit value pointed to by Buffer. The function
2171   guarantees that the read operation does not produce an alignment fault.
2172
2173   If the Buffer is NULL, then ASSERT().
2174
2175   @param  Buffer  Pointer to a 32-bit value that may be unaligned.
2176
2177   @return *Uint32
2178
2179 **/
2180 UINT32
2181 EFIAPI
2182 ReadUnaligned32 (
2183   IN      CONST UINT32              *Uint32
2184   );
2185
2186
2187 /**
2188   Writes a 32-bit value to memory that may be unaligned.
2189
2190   This function writes the 32-bit value specified by Value to Buffer. Value is
2191   returned. The function guarantees that the write operation does not produce
2192   an alignment fault.
2193
2194   If the Buffer is NULL, then ASSERT().
2195
2196   @param  Buffer  Pointer to a 32-bit value that may be unaligned.
2197   @param  Value   32-bit value to write to Buffer.
2198
2199   @return Value
2200
2201 **/
2202 UINT32
2203 EFIAPI
2204 WriteUnaligned32 (
2205   OUT     UINT32                    *Uint32,
2206   IN      UINT32                    Value
2207   );
2208
2209
2210 /**
2211   Reads a 64-bit value from memory that may be unaligned.
2212
2213   This function returns the 64-bit value pointed to by Buffer. The function
2214   guarantees that the read operation does not produce an alignment fault.
2215
2216   If the Buffer is NULL, then ASSERT().
2217
2218   @param  Buffer  Pointer to a 64-bit value that may be unaligned.
2219
2220   @return *Uint64
2221
2222 **/
2223 UINT64
2224 EFIAPI
2225 ReadUnaligned64 (
2226   IN      CONST UINT64              *Uint64
2227   );
2228
2229
2230 /**
2231   Writes a 64-bit value to memory that may be unaligned.
2232
2233   This function writes the 64-bit value specified by Value to Buffer. Value is
2234   returned. The function guarantees that the write operation does not produce
2235   an alignment fault.
2236
2237   If the Buffer is NULL, then ASSERT().
2238
2239   @param  Buffer  Pointer to a 64-bit value that may be unaligned.
2240   @param  Value   64-bit value to write to Buffer.
2241
2242   @return Value
2243
2244 **/
2245 UINT64
2246 EFIAPI
2247 WriteUnaligned64 (
2248   OUT     UINT64                    *Uint64,
2249   IN      UINT64                    Value
2250   );
2251
2252
2253 //
2254 // Bit Field Functions
2255 //
2256
2257 /**
2258   Returns a bit field from an 8-bit value.
2259
2260   Returns the bitfield specified by the StartBit and the EndBit from Operand.
2261
2262   If 8-bit operations are not supported, then ASSERT().
2263   If StartBit is greater than 7, then ASSERT().
2264   If EndBit is greater than 7, then ASSERT().
2265   If EndBit is less than StartBit, then ASSERT().
2266
2267   @param  Operand   Operand on which to perform the bitfield operation.
2268   @param  StartBit  The ordinal of the least significant bit in the bit field.
2269                     Range 0..7.
2270   @param  EndBit    The ordinal of the most significant bit in the bit field.
2271                     Range 0..7.
2272
2273   @return The bit field read.
2274
2275 **/
2276 UINT8
2277 EFIAPI
2278 BitFieldRead8 (
2279   IN      UINT8                     Operand,
2280   IN      UINTN                     StartBit,
2281   IN      UINTN                     EndBit
2282   );
2283
2284
2285 /**
2286   Writes a bit field to an 8-bit value, and returns the result.
2287
2288   Writes Value to the bit field specified by the StartBit and the EndBit in
2289   Operand. All other bits in Operand are preserved. The new 8-bit value is
2290   returned.
2291
2292   If 8-bit operations are not supported, then ASSERT().
2293   If StartBit is greater than 7, then ASSERT().
2294   If EndBit is greater than 7, then ASSERT().
2295   If EndBit is less than StartBit, then ASSERT().
2296
2297   @param  Operand   Operand on which to perform the bitfield operation.
2298   @param  StartBit  The ordinal of the least significant bit in the bit field.
2299                     Range 0..7.
2300   @param  EndBit    The ordinal of the most significant bit in the bit field.
2301                     Range 0..7.
2302   @param  Value     New value of the bit field.
2303
2304   @return The new 8-bit value.
2305
2306 **/
2307 UINT8
2308 EFIAPI
2309 BitFieldWrite8 (
2310   IN      UINT8                     Operand,
2311   IN      UINTN                     StartBit,
2312   IN      UINTN                     EndBit,
2313   IN      UINT8                     Value
2314   );
2315
2316
2317 /**
2318   Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
2319   result.
2320
2321   Performs a bitwise inclusive OR between the bit field specified by StartBit
2322   and EndBit in Operand and the value specified by OrData. All other bits in
2323   Operand are preserved. The new 8-bit value is returned.
2324
2325   If 8-bit operations are not supported, then ASSERT().
2326   If StartBit is greater than 7, then ASSERT().
2327   If EndBit is greater than 7, then ASSERT().
2328   If EndBit is less than StartBit, then ASSERT().
2329
2330   @param  Operand   Operand on which to perform the bitfield operation.
2331   @param  StartBit  The ordinal of the least significant bit in the bit field.
2332                     Range 0..7.
2333   @param  EndBit    The ordinal of the most significant bit in the bit field.
2334                     Range 0..7.
2335   @param  OrData    The value to OR with the read value from the value
2336
2337   @return The new 8-bit value.
2338
2339 **/
2340 UINT8
2341 EFIAPI
2342 BitFieldOr8 (
2343   IN      UINT8                     Operand,
2344   IN      UINTN                     StartBit,
2345   IN      UINTN                     EndBit,
2346   IN      UINT8                     OrData
2347   );
2348
2349
2350 /**
2351   Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
2352   the result.
2353
2354   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2355   in Operand and the value specified by AndData. All other bits in Operand are
2356   preserved. The new 8-bit value is returned.
2357
2358   If 8-bit operations are not supported, then ASSERT().
2359   If StartBit is greater than 7, then ASSERT().
2360   If EndBit is greater than 7, then ASSERT().
2361   If EndBit is less than StartBit, then ASSERT().
2362
2363   @param  Operand   Operand on which to perform the bitfield operation.
2364   @param  StartBit  The ordinal of the least significant bit in the bit field.
2365                     Range 0..7.
2366   @param  EndBit    The ordinal of the most significant bit in the bit field.
2367                     Range 0..7.
2368   @param  AndData   The value to AND with the read value from the value.
2369
2370   @return The new 8-bit value.
2371
2372 **/
2373 UINT8
2374 EFIAPI
2375 BitFieldAnd8 (
2376   IN      UINT8                     Operand,
2377   IN      UINTN                     StartBit,
2378   IN      UINTN                     EndBit,
2379   IN      UINT8                     AndData
2380   );
2381
2382
2383 /**
2384   Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
2385   bitwise OR, and returns the result.
2386
2387   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2388   in Operand and the value specified by AndData, followed by a bitwise
2389   inclusive OR with value specified by OrData. 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   @param  OrData    The value to OR with the result of the AND operation.
2404
2405   @return The new 8-bit value.
2406
2407 **/
2408 UINT8
2409 EFIAPI
2410 BitFieldAndThenOr8 (
2411   IN      UINT8                     Operand,
2412   IN      UINTN                     StartBit,
2413   IN      UINTN                     EndBit,
2414   IN      UINT8                     AndData,
2415   IN      UINT8                     OrData
2416   );
2417
2418
2419 /**
2420   Returns a bit field from a 16-bit value.
2421
2422   Returns the bitfield specified by the StartBit and the EndBit from Operand.
2423
2424   If 16-bit operations are not supported, then ASSERT().
2425   If StartBit is greater than 15, then ASSERT().
2426   If EndBit is greater than 15, then ASSERT().
2427   If EndBit is less than StartBit, then ASSERT().
2428
2429   @param  Operand   Operand on which to perform the bitfield operation.
2430   @param  StartBit  The ordinal of the least significant bit in the bit field.
2431                     Range 0..15.
2432   @param  EndBit    The ordinal of the most significant bit in the bit field.
2433                     Range 0..15.
2434
2435   @return The bit field read.
2436
2437 **/
2438 UINT16
2439 EFIAPI
2440 BitFieldRead16 (
2441   IN      UINT16                    Operand,
2442   IN      UINTN                     StartBit,
2443   IN      UINTN                     EndBit
2444   );
2445
2446
2447 /**
2448   Writes a bit field to a 16-bit value, and returns the result.
2449
2450   Writes Value to the bit field specified by the StartBit and the EndBit in
2451   Operand. All other bits in Operand are preserved. The new 16-bit value is
2452   returned.
2453
2454   If 16-bit operations are not supported, then ASSERT().
2455   If StartBit is greater than 15, then ASSERT().
2456   If EndBit is greater than 15, then ASSERT().
2457   If EndBit is less than StartBit, then ASSERT().
2458
2459   @param  Operand   Operand on which to perform the bitfield operation.
2460   @param  StartBit  The ordinal of the least significant bit in the bit field.
2461                     Range 0..15.
2462   @param  EndBit    The ordinal of the most significant bit in the bit field.
2463                     Range 0..15.
2464   @param  Value     New value of the bit field.
2465
2466   @return The new 16-bit value.
2467
2468 **/
2469 UINT16
2470 EFIAPI
2471 BitFieldWrite16 (
2472   IN      UINT16                    Operand,
2473   IN      UINTN                     StartBit,
2474   IN      UINTN                     EndBit,
2475   IN      UINT16                    Value
2476   );
2477
2478
2479 /**
2480   Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
2481   result.
2482
2483   Performs a bitwise inclusive OR between the bit field specified by StartBit
2484   and EndBit in Operand and the value specified by OrData. All other bits in
2485   Operand are preserved. The new 16-bit value is returned.
2486
2487   If 16-bit operations are not supported, then ASSERT().
2488   If StartBit is greater than 15, then ASSERT().
2489   If EndBit is greater than 15, then ASSERT().
2490   If EndBit is less than StartBit, then ASSERT().
2491
2492   @param  Operand   Operand on which to perform the bitfield operation.
2493   @param  StartBit  The ordinal of the least significant bit in the bit field.
2494                     Range 0..15.
2495   @param  EndBit    The ordinal of the most significant bit in the bit field.
2496                     Range 0..15.
2497   @param  OrData    The value to OR with the read value from the value
2498
2499   @return The new 16-bit value.
2500
2501 **/
2502 UINT16
2503 EFIAPI
2504 BitFieldOr16 (
2505   IN      UINT16                    Operand,
2506   IN      UINTN                     StartBit,
2507   IN      UINTN                     EndBit,
2508   IN      UINT16                    OrData
2509   );
2510
2511
2512 /**
2513   Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
2514   the result.
2515
2516   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2517   in Operand and the value specified by AndData. All other bits in Operand are
2518   preserved. The new 16-bit value is returned.
2519
2520   If 16-bit operations are not supported, then ASSERT().
2521   If StartBit is greater than 15, then ASSERT().
2522   If EndBit is greater than 15, then ASSERT().
2523   If EndBit is less than StartBit, then ASSERT().
2524
2525   @param  Operand   Operand on which to perform the bitfield operation.
2526   @param  StartBit  The ordinal of the least significant bit in the bit field.
2527                     Range 0..15.
2528   @param  EndBit    The ordinal of the most significant bit in the bit field.
2529                     Range 0..15.
2530   @param  AndData   The value to AND with the read value from the value
2531
2532   @return The new 16-bit value.
2533
2534 **/
2535 UINT16
2536 EFIAPI
2537 BitFieldAnd16 (
2538   IN      UINT16                    Operand,
2539   IN      UINTN                     StartBit,
2540   IN      UINTN                     EndBit,
2541   IN      UINT16                    AndData
2542   );
2543
2544
2545 /**
2546   Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
2547   bitwise OR, and returns the result.
2548
2549   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2550   in Operand and the value specified by AndData, followed by a bitwise
2551   inclusive OR with value specified by OrData. 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   @param  OrData    The value to OR with the result of the AND operation.
2566
2567   @return The new 16-bit value.
2568
2569 **/
2570 UINT16
2571 EFIAPI
2572 BitFieldAndThenOr16 (
2573   IN      UINT16                    Operand,
2574   IN      UINTN                     StartBit,
2575   IN      UINTN                     EndBit,
2576   IN      UINT16                    AndData,
2577   IN      UINT16                    OrData
2578   );
2579
2580
2581 /**
2582   Returns a bit field from a 32-bit value.
2583
2584   Returns the bitfield specified by the StartBit and the EndBit from Operand.
2585
2586   If 32-bit operations are not supported, then ASSERT().
2587   If StartBit is greater than 31, then ASSERT().
2588   If EndBit is greater than 31, then ASSERT().
2589   If EndBit is less than StartBit, then ASSERT().
2590
2591   @param  Operand   Operand on which to perform the bitfield operation.
2592   @param  StartBit  The ordinal of the least significant bit in the bit field.
2593                     Range 0..31.
2594   @param  EndBit    The ordinal of the most significant bit in the bit field.
2595                     Range 0..31.
2596
2597   @return The bit field read.
2598
2599 **/
2600 UINT32
2601 EFIAPI
2602 BitFieldRead32 (
2603   IN      UINT32                    Operand,
2604   IN      UINTN                     StartBit,
2605   IN      UINTN                     EndBit
2606   );
2607
2608
2609 /**
2610   Writes a bit field to a 32-bit value, and returns the result.
2611
2612   Writes Value to the bit field specified by the StartBit and the EndBit in
2613   Operand. All other bits in Operand are preserved. The new 32-bit value is
2614   returned.
2615
2616   If 32-bit operations are not supported, then ASSERT().
2617   If StartBit is greater than 31, then ASSERT().
2618   If EndBit is greater than 31, then ASSERT().
2619   If EndBit is less than StartBit, then ASSERT().
2620
2621   @param  Operand   Operand on which to perform the bitfield operation.
2622   @param  StartBit  The ordinal of the least significant bit in the bit field.
2623                     Range 0..31.
2624   @param  EndBit    The ordinal of the most significant bit in the bit field.
2625                     Range 0..31.
2626   @param  Value     New value of the bit field.
2627
2628   @return The new 32-bit value.
2629
2630 **/
2631 UINT32
2632 EFIAPI
2633 BitFieldWrite32 (
2634   IN      UINT32                    Operand,
2635   IN      UINTN                     StartBit,
2636   IN      UINTN                     EndBit,
2637   IN      UINT32                    Value
2638   );
2639
2640
2641 /**
2642   Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
2643   result.
2644
2645   Performs a bitwise inclusive OR between the bit field specified by StartBit
2646   and EndBit in Operand and the value specified by OrData. All other bits in
2647   Operand are preserved. The new 32-bit value is returned.
2648
2649   If 32-bit operations are not supported, then ASSERT().
2650   If StartBit is greater than 31, then ASSERT().
2651   If EndBit is greater than 31, then ASSERT().
2652   If EndBit is less than StartBit, then ASSERT().
2653
2654   @param  Operand   Operand on which to perform the bitfield operation.
2655   @param  StartBit  The ordinal of the least significant bit in the bit field.
2656                     Range 0..31.
2657   @param  EndBit    The ordinal of the most significant bit in the bit field.
2658                     Range 0..31.
2659   @param  OrData    The value to OR with the read value from the value
2660
2661   @return The new 32-bit value.
2662
2663 **/
2664 UINT32
2665 EFIAPI
2666 BitFieldOr32 (
2667   IN      UINT32                    Operand,
2668   IN      UINTN                     StartBit,
2669   IN      UINTN                     EndBit,
2670   IN      UINT32                    OrData
2671   );
2672
2673
2674 /**
2675   Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
2676   the result.
2677
2678   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2679   in Operand and the value specified by AndData. All other bits in Operand are
2680   preserved. The new 32-bit value is returned.
2681
2682   If 32-bit operations are not supported, then ASSERT().
2683   If StartBit is greater than 31, then ASSERT().
2684   If EndBit is greater than 31, then ASSERT().
2685   If EndBit is less than StartBit, then ASSERT().
2686
2687   @param  Operand   Operand on which to perform the bitfield operation.
2688   @param  StartBit  The ordinal of the least significant bit in the bit field.
2689                     Range 0..31.
2690   @param  EndBit    The ordinal of the most significant bit in the bit field.
2691                     Range 0..31.
2692   @param  AndData   The value to AND with the read value from the value
2693
2694   @return The new 32-bit value.
2695
2696 **/
2697 UINT32
2698 EFIAPI
2699 BitFieldAnd32 (
2700   IN      UINT32                    Operand,
2701   IN      UINTN                     StartBit,
2702   IN      UINTN                     EndBit,
2703   IN      UINT32                    AndData
2704   );
2705
2706
2707 /**
2708   Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
2709   bitwise OR, and returns the result.
2710
2711   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2712   in Operand and the value specified by AndData, followed by a bitwise
2713   inclusive OR with value specified by OrData. 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   @param  OrData    The value to OR with the result of the AND operation.
2728
2729   @return The new 32-bit value.
2730
2731 **/
2732 UINT32
2733 EFIAPI
2734 BitFieldAndThenOr32 (
2735   IN      UINT32                    Operand,
2736   IN      UINTN                     StartBit,
2737   IN      UINTN                     EndBit,
2738   IN      UINT32                    AndData,
2739   IN      UINT32                    OrData
2740   );
2741
2742
2743 /**
2744   Returns a bit field from a 64-bit value.
2745
2746   Returns the bitfield specified by the StartBit and the EndBit from Operand.
2747
2748   If 64-bit operations are not supported, then ASSERT().
2749   If StartBit is greater than 63, then ASSERT().
2750   If EndBit is greater than 63, then ASSERT().
2751   If EndBit is less than StartBit, then ASSERT().
2752
2753   @param  Operand   Operand on which to perform the bitfield operation.
2754   @param  StartBit  The ordinal of the least significant bit in the bit field.
2755                     Range 0..63.
2756   @param  EndBit    The ordinal of the most significant bit in the bit field.
2757                     Range 0..63.
2758
2759   @return The bit field read.
2760
2761 **/
2762 UINT64
2763 EFIAPI
2764 BitFieldRead64 (
2765   IN      UINT64                    Operand,
2766   IN      UINTN                     StartBit,
2767   IN      UINTN                     EndBit
2768   );
2769
2770
2771 /**
2772   Writes a bit field to a 64-bit value, and returns the result.
2773
2774   Writes Value to the bit field specified by the StartBit and the EndBit in
2775   Operand. All other bits in Operand are preserved. The new 64-bit value is
2776   returned.
2777
2778   If 64-bit operations are not supported, then ASSERT().
2779   If StartBit is greater than 63, then ASSERT().
2780   If EndBit is greater than 63, then ASSERT().
2781   If EndBit is less than StartBit, then ASSERT().
2782
2783   @param  Operand   Operand on which to perform the bitfield operation.
2784   @param  StartBit  The ordinal of the least significant bit in the bit field.
2785                     Range 0..63.
2786   @param  EndBit    The ordinal of the most significant bit in the bit field.
2787                     Range 0..63.
2788   @param  Value     New value of the bit field.
2789
2790   @return The new 64-bit value.
2791
2792 **/
2793 UINT64
2794 EFIAPI
2795 BitFieldWrite64 (
2796   IN      UINT64                    Operand,
2797   IN      UINTN                     StartBit,
2798   IN      UINTN                     EndBit,
2799   IN      UINT64                    Value
2800   );
2801
2802
2803 /**
2804   Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
2805   result.
2806
2807   Performs a bitwise inclusive OR between the bit field specified by StartBit
2808   and EndBit in Operand and the value specified by OrData. All other bits in
2809   Operand are preserved. The new 64-bit value is returned.
2810
2811   If 64-bit operations are not supported, then ASSERT().
2812   If StartBit is greater than 63, then ASSERT().
2813   If EndBit is greater than 63, then ASSERT().
2814   If EndBit is less than StartBit, then ASSERT().
2815
2816   @param  Operand   Operand on which to perform the bitfield operation.
2817   @param  StartBit  The ordinal of the least significant bit in the bit field.
2818                     Range 0..63.
2819   @param  EndBit    The ordinal of the most significant bit in the bit field.
2820                     Range 0..63.
2821   @param  OrData    The value to OR with the read value from the value
2822
2823   @return The new 64-bit value.
2824
2825 **/
2826 UINT64
2827 EFIAPI
2828 BitFieldOr64 (
2829   IN      UINT64                    Operand,
2830   IN      UINTN                     StartBit,
2831   IN      UINTN                     EndBit,
2832   IN      UINT64                    OrData
2833   );
2834
2835
2836 /**
2837   Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
2838   the result.
2839
2840   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2841   in Operand and the value specified by AndData. All other bits in Operand are
2842   preserved. The new 64-bit value is returned.
2843
2844   If 64-bit operations are not supported, then ASSERT().
2845   If StartBit is greater than 63, then ASSERT().
2846   If EndBit is greater than 63, then ASSERT().
2847   If EndBit is less than StartBit, then ASSERT().
2848
2849   @param  Operand   Operand on which to perform the bitfield operation.
2850   @param  StartBit  The ordinal of the least significant bit in the bit field.
2851                     Range 0..63.
2852   @param  EndBit    The ordinal of the most significant bit in the bit field.
2853                     Range 0..63.
2854   @param  AndData   The value to AND with the read value from the value
2855
2856   @return The new 64-bit value.
2857
2858 **/
2859 UINT64
2860 EFIAPI
2861 BitFieldAnd64 (
2862   IN      UINT64                    Operand,
2863   IN      UINTN                     StartBit,
2864   IN      UINTN                     EndBit,
2865   IN      UINT64                    AndData
2866   );
2867
2868
2869 /**
2870   Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
2871   bitwise OR, and returns the result.
2872
2873   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2874   in Operand and the value specified by AndData, followed by a bitwise
2875   inclusive OR with value specified by OrData. 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   @param  OrData    The value to OR with the result of the AND operation.
2890
2891   @return The new 64-bit value.
2892
2893 **/
2894 UINT64
2895 EFIAPI
2896 BitFieldAndThenOr64 (
2897   IN      UINT64                    Operand,
2898   IN      UINTN                     StartBit,
2899   IN      UINTN                     EndBit,
2900   IN      UINT64                    AndData,
2901   IN      UINT64                    OrData
2902   );
2903
2904
2905 //
2906 // Base Library Synchronization Functions
2907 //
2908
2909 /**
2910   Retrieves the architecture specific spin lock alignment requirements for
2911   optimal spin lock performance.
2912
2913   This function retrieves the spin lock alignment requirements for optimal
2914   performance on a given CPU architecture. The spin lock alignment must be a
2915   power of two and is returned by this function. If there are no alignment
2916   requirements, then 1 must be returned. The spin lock synchronization
2917   functions must function correctly if the spin lock size and alignment values
2918   returned by this function are not used at all. These values are hints to the
2919   consumers of the spin lock synchronization functions to obtain optimal spin
2920   lock performance.
2921
2922   @return The architecture specific spin lock alignment.
2923
2924 **/
2925 UINTN
2926 EFIAPI
2927 GetSpinLockProperties (
2928   VOID
2929   );
2930
2931
2932 /**
2933   Initializes a spin lock to the released state and returns the spin lock.
2934
2935   This function initializes the spin lock specified by SpinLock to the released
2936   state, and returns SpinLock. Optimal performance can be achieved by calling
2937   GetSpinLockProperties() to determine the size and alignment requirements for
2938   SpinLock.
2939
2940   If SpinLock is NULL, then ASSERT().
2941
2942   @param  SpinLock  A pointer to the spin lock to initialize to the released
2943                     state.
2944
2945   @return SpinLock
2946
2947 **/
2948 SPIN_LOCK *
2949 EFIAPI
2950 InitializeSpinLock (
2951   IN      SPIN_LOCK                 *SpinLock
2952   );
2953
2954
2955 /**
2956   Waits until a spin lock can be placed in the acquired state.
2957
2958   This function checks the state of the spin lock specified by SpinLock. If
2959   SpinLock is in the released state, then this function places SpinLock in the
2960   acquired state and returns SpinLock. Otherwise, this function waits
2961   indefinitely for the spin lock to be released, and then places it in the
2962   acquired state and returns SpinLock. All state transitions of SpinLock must
2963   be performed using MP safe mechanisms.
2964
2965   If SpinLock is NULL, then ASSERT().
2966   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
2967   If PcdSpinLockTimeout is not zero, and SpinLock is can not be acquired in
2968   PcdSpinLockTimeout microseconds, then ASSERT().
2969
2970   @param  SpinLock  A pointer to the spin lock to place in the acquired state.
2971
2972   @return SpinLock
2973
2974 **/
2975 SPIN_LOCK *
2976 EFIAPI
2977 AcquireSpinLock (
2978   IN      SPIN_LOCK                 *SpinLock
2979   );
2980
2981
2982 /**
2983   Attempts to place a spin lock in the acquired state.
2984
2985   This function checks the state of the spin lock specified by SpinLock. If
2986   SpinLock is in the released state, then this function places SpinLock in the
2987   acquired state and returns TRUE. Otherwise, FALSE is returned. All state
2988   transitions of SpinLock must be performed using MP safe mechanisms.
2989
2990   If SpinLock is NULL, then ASSERT().
2991   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
2992
2993   @param  SpinLock  A pointer to the spin lock to place in the acquired state.
2994
2995   @retval TRUE  SpinLock was placed in the acquired state.
2996   @retval FALSE SpinLock could not be acquired.
2997
2998 **/
2999 BOOLEAN
3000 EFIAPI
3001 AcquireSpinLockOrFail (
3002   IN      SPIN_LOCK                 *SpinLock
3003   );
3004
3005
3006 /**
3007   Releases a spin lock.
3008
3009   This function places the spin lock specified by SpinLock in the release state
3010   and returns SpinLock.
3011
3012   If SpinLock is NULL, then ASSERT().
3013   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
3014
3015   @param  SpinLock  A pointer to the spin lock to release.
3016
3017   @return SpinLock
3018
3019 **/
3020 SPIN_LOCK *
3021 EFIAPI
3022 ReleaseSpinLock (
3023   IN      SPIN_LOCK                 *SpinLock
3024   );
3025
3026
3027 /**
3028   Performs an atomic increment of an 32-bit unsigned integer.
3029
3030   Performs an atomic increment of the 32-bit unsigned integer specified by
3031   Value and returns the incremented value. The increment operation must be
3032   performed using MP safe mechanisms. The state of the return value is not
3033   guaranteed to be MP safe.
3034
3035   If Value is NULL, then ASSERT().
3036
3037   @param  Value A pointer to the 32-bit value to increment.
3038
3039   @return The incremented value.
3040
3041 **/
3042 UINT32
3043 EFIAPI
3044 InterlockedIncrement (
3045   IN      UINT32                    *Value
3046   );
3047
3048
3049 /**
3050   Performs an atomic decrement of an 32-bit unsigned integer.
3051
3052   Performs an atomic decrement of the 32-bit unsigned integer specified by
3053   Value and returns the decremented value. The decrement operation must be
3054   performed using MP safe mechanisms. The state of the return value is not
3055   guaranteed to be MP safe.
3056
3057   If Value is NULL, then ASSERT().
3058
3059   @param  Value A pointer to the 32-bit value to decrement.
3060
3061   @return The decremented value.
3062
3063 **/
3064 UINT32
3065 EFIAPI
3066 InterlockedDecrement (
3067   IN      UINT32                    *Value
3068   );
3069
3070
3071 /**
3072   Performs an atomic compare exchange operation on a 32-bit unsigned integer.
3073
3074   Performs an atomic compare exchange operation on the 32-bit unsigned integer
3075   specified by Value.  If Value is equal to CompareValue, then Value is set to
3076   ExchangeValue and CompareValue is returned.  If Value is not equal to CompareValue,
3077   then Value is returned.  The compare exchange operation must be performed using
3078   MP safe mechanisms.
3079
3080   If Value is NULL, then ASSERT().
3081
3082   @param  Value         A pointer to the 32-bit value for the compare exchange
3083                         operation.
3084   @param  CompareValue  32-bit value used in compare operation.
3085   @param  ExchangeValue 32-bit value used in exchange operation.
3086
3087   @return The original *Value before exchange.
3088
3089 **/
3090 UINT32
3091 EFIAPI
3092 InterlockedCompareExchange32 (
3093   IN OUT  UINT32                    *Value,
3094   IN      UINT32                    CompareValue,
3095   IN      UINT32                    ExchangeValue
3096   );
3097
3098
3099 /**
3100   Performs an atomic compare exchange operation on a 64-bit unsigned integer.
3101
3102   Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
3103   by Value.  If Value is equal to CompareValue, then Value is set to ExchangeValue and
3104   CompareValue is returned.  If Value is not equal to CompareValue, then Value is returned.
3105   The compare exchange operation must be performed using MP safe mechanisms.
3106
3107   If Value is NULL, then ASSERT().
3108
3109   @param  Value         A pointer to the 64-bit value for the compare exchange
3110                         operation.
3111   @param  CompareValue  64-bit value used in compare operation.
3112   @param  ExchangeValue 64-bit value used in exchange operation.
3113
3114   @return The original *Value before exchange.
3115
3116 **/
3117 UINT64
3118 EFIAPI
3119 InterlockedCompareExchange64 (
3120   IN OUT  UINT64                    *Value,
3121   IN      UINT64                    CompareValue,
3122   IN      UINT64                    ExchangeValue
3123   );
3124
3125
3126 /**
3127   Performs an atomic compare exchange operation on a pointer value.
3128
3129   Performs an atomic compare exchange operation on the pointer value specified
3130   by Value. If Value is equal to CompareValue, then Value is set to
3131   ExchangeValue and CompareValue is returned. If Value is not equal to
3132   CompareValue, then Value is returned. The compare exchange operation must be
3133   performed using MP safe mechanisms.
3134
3135   If Value is NULL, then ASSERT().
3136
3137   @param  Value         A pointer to the pointer value for the compare exchange
3138                         operation.
3139   @param  CompareValue  Pointer value used in compare operation.
3140   @param  ExchangeValue Pointer value used in exchange operation.
3141
3142 **/
3143 VOID *
3144 EFIAPI
3145 InterlockedCompareExchangePointer (
3146   IN OUT  VOID                      **Value,
3147   IN      VOID                      *CompareValue,
3148   IN      VOID                      *ExchangeValue
3149   );
3150
3151
3152 //
3153 // Base Library Checksum Functions
3154 //
3155
3156 /**
3157   Calculate the sum of all elements in a buffer in unit of UINT8.
3158   During calculation, the carry bits are dropped.
3159
3160   This function calculates the sum of all elements in a buffer
3161   in unit of UINT8. The carry bits in result of addition are dropped.
3162   The result is returned as UINT8. If Length is Zero, then Zero is
3163   returned.
3164
3165   If Buffer is NULL, then ASSERT().
3166   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3167
3168   @param  Buffer                        Pointer to the buffer to carry out the sum operation.
3169   @param  Length            The size, in bytes, of Buffer .
3170
3171   @return Sum         The sum of Buffer with carry bits dropped during additions.
3172
3173 **/
3174 UINT8
3175 EFIAPI
3176 CalculateSum8 (
3177   IN      CONST UINT8                   *Buffer,
3178   IN      UINTN                               Length
3179   );
3180
3181
3182 /**
3183   Returns the two's complement checksum of all elements in a buffer
3184   of 8-bit values.
3185
3186   This function first calculates the sum of the 8-bit values in the
3187   buffer specified by Buffer and Length.  The carry bits in the result
3188   of addition are dropped. Then, the two's complement of the sum is
3189   returned.  If Length is 0, then 0 is returned.
3190
3191   If Buffer is NULL, then ASSERT().
3192   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3193
3194
3195   @param  Buffer                        Pointer to the buffer to carry out the checksum operation.
3196   @param  Length            The size, in bytes, of Buffer.
3197
3198   @return Checksum        The 2's complement checksum of Buffer.
3199
3200 **/
3201 UINT8
3202 EFIAPI
3203 CalculateCheckSum8 (
3204   IN      CONST UINT8                   *Buffer,
3205   IN      UINTN                               Length
3206   );
3207
3208
3209 /**
3210   Returns the sum of all elements in a buffer of 16-bit values.  During
3211   calculation, the carry bits are dropped.
3212
3213   This function calculates the sum of the 16-bit values in the buffer
3214   specified by Buffer and Length. The carry bits in result of addition are dropped.
3215   The 16-bit result is returned.  If Length is 0, then 0 is returned.
3216
3217   If Buffer is NULL, then ASSERT().
3218   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
3219   If Length is not aligned on a 16-bit boundary, then ASSERT().
3220   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3221
3222   @param  Buffer                        Pointer to the buffer to carry out the sum operation.
3223   @param  Length            The size, in bytes, of Buffer.
3224
3225   @return Sum         The sum of Buffer with carry bits dropped during additions.
3226
3227 **/
3228 UINT16
3229 EFIAPI
3230 CalculateSum16 (
3231   IN      CONST UINT16                  *Buffer,
3232   IN      UINTN                               Length
3233   );
3234
3235
3236 /**
3237   Returns the two's complement checksum of all elements in a buffer of
3238   16-bit values.
3239
3240   This function first calculates the sum of the 16-bit values in the buffer
3241   specified by Buffer and Length.  The carry bits in the result of addition
3242   are dropped. Then, the two's complement of the sum is returned.  If Length
3243   is 0, then 0 is returned.
3244
3245   If Buffer is NULL, then ASSERT().
3246   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
3247   If Length is not aligned on a 16-bit boundary, then ASSERT().
3248   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3249
3250   @param  Buffer                        Pointer to the buffer to carry out the checksum operation.
3251   @param  Length            The size, in bytes, of Buffer.
3252
3253   @return Checksum        The 2's complement checksum of Buffer.
3254
3255 **/
3256 UINT16
3257 EFIAPI
3258 CalculateCheckSum16 (
3259   IN      CONST UINT16                  *Buffer,
3260   IN      UINTN                               Length
3261   );
3262
3263
3264 /**
3265   Returns the sum of all elements in a buffer of 32-bit values.  During
3266   calculation, the carry bits are dropped.
3267
3268   This function calculates the sum of the 32-bit values in the buffer
3269   specified by Buffer and Length. The carry bits in result of addition are dropped.
3270   The 32-bit result is returned.  If Length is 0, then 0 is returned.
3271
3272   If Buffer is NULL, then ASSERT().
3273   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
3274   If Length is not aligned on a 32-bit boundary, then ASSERT().
3275   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3276
3277   @param  Buffer                        Pointer to the buffer to carry out the sum operation.
3278   @param  Length            The size, in bytes, of Buffer.
3279
3280   @return Sum         The sum of Buffer with carry bits dropped during additions.
3281
3282 **/
3283 UINT32
3284 EFIAPI
3285 CalculateSum32 (
3286   IN      CONST UINT32                  *Buffer,
3287   IN      UINTN                               Length
3288   );
3289
3290
3291 /**
3292   Returns the two's complement checksum of all elements in a buffer of
3293   32-bit values.
3294
3295   This function first calculates the sum of the 32-bit values in the buffer
3296   specified by Buffer and Length.  The carry bits in the result of addition
3297   are dropped. Then, the two's complement of the sum is returned.  If Length
3298   is 0, then 0 is returned.
3299
3300   If Buffer is NULL, then ASSERT().
3301   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
3302   If Length is not aligned on a 32-bit boundary, then ASSERT().
3303   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3304
3305   @param  Buffer                        Pointer to the buffer to carry out the checksum operation.
3306   @param  Length            The size, in bytes, of Buffer.
3307
3308   @return Checksum        The 2's complement checksum of Buffer.
3309
3310 **/
3311 UINT32
3312 EFIAPI
3313 CalculateCheckSum32 (
3314   IN      CONST UINT32                  *Buffer,
3315   IN      UINTN                               Length
3316   );
3317
3318
3319 /**
3320   Returns the sum of all elements in a buffer of 64-bit values.  During
3321   calculation, the carry bits are dropped.
3322
3323   This function calculates the sum of the 64-bit values in the buffer
3324   specified by Buffer and Length. The carry bits in result of addition are dropped.
3325   The 64-bit result is returned.  If Length is 0, then 0 is returned.
3326
3327   If Buffer is NULL, then ASSERT().
3328   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
3329   If Length is not aligned on a 64-bit boundary, then ASSERT().
3330   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3331
3332   @param  Buffer                        Pointer to the buffer to carry out the sum operation.
3333   @param  Length            The size, in bytes, of Buffer.
3334
3335   @return Sum         The sum of Buffer with carry bits dropped during additions.
3336
3337 **/
3338 UINT64
3339 EFIAPI
3340 CalculateSum64 (
3341   IN      CONST UINT64                  *Buffer,
3342   IN      UINTN                               Length
3343   );
3344
3345
3346 /**
3347   Returns the two's complement checksum of all elements in a buffer of
3348   64-bit values.
3349
3350   This function first calculates the sum of the 64-bit values in the buffer
3351   specified by Buffer and Length.  The carry bits in the result of addition
3352   are dropped. Then, the two's complement of the sum is returned.  If Length
3353   is 0, then 0 is returned.
3354
3355   If Buffer is NULL, then ASSERT().
3356   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
3357   If Length is not aligned on a 64-bit boundary, then ASSERT().
3358   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3359
3360   @param  Buffer                        Pointer to the buffer to carry out the checksum operation.
3361   @param  Length            The size, in bytes, of Buffer.
3362
3363   @return Checksum        The 2's complement checksum of Buffer.
3364
3365 **/
3366 UINT64
3367 EFIAPI
3368 CalculateCheckSum64 (
3369   IN      CONST UINT64                  *Buffer,
3370   IN      UINTN                               Length
3371   );
3372
3373
3374 //
3375 // Base Library CPU Functions
3376 //
3377 typedef
3378 VOID
3379 (EFIAPI *SWITCH_STACK_ENTRY_POINT) (
3380   IN      VOID                      *Context1,  OPTIONAL
3381   IN      VOID                      *Context2   OPTIONAL
3382   );
3383
3384
3385 /**
3386   Used to serialize load and store operations.
3387
3388   All loads and stores that proceed calls to this function are guaranteed to be
3389   globally visible when this function returns.
3390
3391 **/
3392 VOID
3393 EFIAPI
3394 MemoryFence (
3395   VOID
3396   );
3397
3398
3399 /**
3400   Saves the current CPU context that can be restored with a call to LongJump()
3401   and returns 0.
3402
3403   Saves the current CPU context in the buffer specified by JumpBuffer and
3404   returns 0. The initial call to SetJump() must always return 0. Subsequent
3405   calls to LongJump() cause a non-zero value to be returned by SetJump().
3406
3407   If JumpBuffer is NULL, then ASSERT().
3408   For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
3409
3410   @param  JumpBuffer  A pointer to CPU context buffer.
3411
3412   @retval 0 Indicates a return from SetJump().
3413
3414 **/
3415 UINTN
3416 EFIAPI
3417 SetJump (
3418   OUT     BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer
3419   );
3420
3421
3422 /**
3423   Restores the CPU context that was saved with SetJump().
3424
3425   Restores the CPU context from the buffer specified by JumpBuffer. This
3426   function never returns to the caller. Instead is resumes execution based on
3427   the state of JumpBuffer.
3428
3429   If JumpBuffer is NULL, then ASSERT().
3430   For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
3431   If Value is 0, then ASSERT().
3432
3433   @param  JumpBuffer  A pointer to CPU context buffer.
3434   @param  Value       The value to return when the SetJump() context is
3435                       restored and must be non-zero.
3436
3437 **/
3438 VOID
3439 EFIAPI
3440 LongJump (
3441   IN      BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer,
3442   IN      UINTN                     Value
3443   );
3444
3445
3446 /**
3447   Enables CPU interrupts.
3448
3449   Enables CPU interrupts.
3450
3451 **/
3452 VOID
3453 EFIAPI
3454 EnableInterrupts (
3455   VOID
3456   );
3457
3458
3459 /**
3460   Disables CPU interrupts.
3461
3462   Disables CPU interrupts.
3463
3464 **/
3465 VOID
3466 EFIAPI
3467 DisableInterrupts (
3468   VOID
3469   );
3470
3471
3472 /**
3473   Disables CPU interrupts and returns the interrupt state prior to the disable
3474   operation.
3475
3476   Disables CPU interrupts and returns the interrupt state prior to the disable
3477   operation.
3478
3479   @retval TRUE  CPU interrupts were enabled on entry to this call.
3480   @retval FALSE CPU interrupts were disabled on entry to this call.
3481
3482 **/
3483 BOOLEAN
3484 EFIAPI
3485 SaveAndDisableInterrupts (
3486   VOID
3487   );
3488
3489
3490 /**
3491   Enables CPU interrupts for the smallest window required to capture any
3492   pending interrupts.
3493
3494   Enables CPU interrupts for the smallest window required to capture any
3495   pending interrupts.
3496
3497 **/
3498 VOID
3499 EFIAPI
3500 EnableDisableInterrupts (
3501   VOID
3502   );
3503
3504
3505 /**
3506   Retrieves the current CPU interrupt state.
3507
3508   Retrieves the current CPU interrupt state. Returns TRUE is interrupts are
3509   currently enabled. Otherwise returns FALSE.
3510
3511   @retval TRUE  CPU interrupts are enabled.
3512   @retval FALSE CPU interrupts are disabled.
3513
3514 **/
3515 BOOLEAN
3516 EFIAPI
3517 GlueGetInterruptState (
3518   VOID
3519   );
3520
3521
3522 /**
3523   Set the current CPU interrupt state.
3524
3525   Sets the current CPU interrupt state to the state specified by
3526   InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
3527   InterruptState is FALSE, then interrupts are disabled. InterruptState is
3528   returned.
3529
3530   @param  InterruptState  TRUE if interrupts should enabled. FALSE if
3531                           interrupts should be disabled.
3532
3533   @return InterruptState
3534
3535 **/
3536 BOOLEAN
3537 EFIAPI
3538 SetInterruptState (
3539   IN      BOOLEAN                   InterruptState
3540   );
3541
3542
3543 /**
3544   Places the CPU in a sleep state until an interrupt is received.
3545
3546   Places the CPU in a sleep state until an interrupt is received. If interrupts
3547   are disabled prior to calling this function, then the CPU will be placed in a
3548   sleep state indefinitely.
3549
3550 **/
3551 VOID
3552 EFIAPI
3553 CpuSleep (
3554   VOID
3555   );
3556
3557
3558 /**
3559   Requests CPU to pause for a short period of time.
3560
3561   Requests CPU to pause for a short period of time. Typically used in MP
3562   systems to prevent memory starvation while waiting for a spin lock.
3563
3564 **/
3565 VOID
3566 EFIAPI
3567 CpuPause (
3568   VOID
3569   );
3570
3571
3572 /**
3573   Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU.
3574
3575   Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU.
3576
3577 **/
3578 VOID
3579 EFIAPI
3580 CpuFlushTlb (
3581   VOID
3582   );
3583
3584
3585 /**
3586   Transfers control to a function starting with a new stack.
3587
3588   Transfers control to the function specified by EntryPoint using the
3589   new stack specified by NewStack and passing in the parameters specified
3590   by Context1 and Context2.  Context1 and Context2 are optional and may
3591   be NULL.  The function EntryPoint must never return.  This function
3592   supports a variable number of arguments following the NewStack parameter.
3593   These additional arguments are ignored on IA-32, x64, and EBC.
3594   IPF CPUs expect one additional parameter of type VOID * that specifies
3595   the new backing store pointer.
3596
3597   If EntryPoint is NULL, then ASSERT().
3598   If NewStack is NULL, then ASSERT().
3599
3600   @param  EntryPoint  A pointer to function to call with the new stack.
3601   @param  Context1    A pointer to the context to pass into the EntryPoint
3602                       function.
3603   @param  Context2    A pointer to the context to pass into the EntryPoint
3604                       function.
3605   @param  NewStack    A pointer to the new stack to use for the EntryPoint
3606                       function.
3607
3608 **/
3609 VOID
3610 EFIAPI
3611 SwitchStack (
3612   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
3613   IN      VOID                      *Context1,  OPTIONAL
3614   IN      VOID                      *Context2,  OPTIONAL
3615   IN      VOID                      *NewStack,
3616   ...
3617   );
3618
3619
3620 /**
3621   Generates a breakpoint on the CPU.
3622
3623   Generates a breakpoint on the CPU. The breakpoint must be implemented such
3624   that code can resume normal execution after the breakpoint.
3625
3626 **/
3627 VOID
3628 EFIAPI
3629 CpuBreakpoint (
3630   VOID
3631   );
3632
3633
3634 /**
3635   Executes an infinite loop.
3636
3637   Forces the CPU to execute an infinite loop. A debugger may be used to skip
3638   past the loop and the code that follows the loop must execute properly. This
3639   implies that the infinite loop must not cause the code that follow it to be
3640   optimized away.
3641
3642 **/
3643 VOID
3644 EFIAPI
3645 CpuDeadLoop (
3646   VOID
3647   );
3648
3649 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
3650 //
3651 // IA32 and X64 Specific Functions
3652 //
3653 //
3654 // Byte packed structure for 16-bit Real Mode EFLAGS
3655 //
3656 typedef union {
3657   struct {
3658     UINT32  CF:1;           // Carry Flag
3659     UINT32  Reserved_0:1;   // Reserved
3660     UINT32  PF:1;           // Parity Flag
3661     UINT32  Reserved_1:1;   // Reserved
3662     UINT32  AF:1;           // Auxiliary Carry Flag
3663     UINT32  Reserved_2:1;   // Reserved
3664     UINT32  ZF:1;           // Zero Flag
3665     UINT32  SF:1;           // Sign Flag
3666     UINT32  TF:1;           // Trap Flag
3667     UINT32  IF:1;           // Interrupt Enable Flag
3668     UINT32  DF:1;           // Direction Flag
3669     UINT32  OF:1;           // Overflow Flag
3670     UINT32  IOPL:2;         // I/O Privilege Level
3671     UINT32  NT:1;           // Nested Task
3672     UINT32  Reserved_3:1;   // Reserved
3673   } Bits;
3674   UINT16    Uint16;
3675 } IA32_FLAGS16;
3676
3677 //
3678 // Byte packed structure for EFLAGS/RFLAGS
3679 // 32-bits on IA-32
3680 // 64-bits on X64.  The upper 32-bits on X64 are reserved
3681 //
3682 typedef union {
3683   struct {
3684     UINT32  CF:1;           // Carry Flag
3685     UINT32  Reserved_0:1;   // Reserved
3686     UINT32  PF:1;           // Parity Flag
3687     UINT32  Reserved_1:1;   // Reserved
3688     UINT32  AF:1;           // Auxiliary Carry Flag
3689     UINT32  Reserved_2:1;   // Reserved
3690     UINT32  ZF:1;           // Zero Flag
3691     UINT32  SF:1;           // Sign Flag
3692     UINT32  TF:1;           // Trap Flag
3693     UINT32  IF:1;           // Interrupt Enable Flag
3694     UINT32  DF:1;           // Direction Flag
3695     UINT32  OF:1;           // Overflow Flag
3696     UINT32  IOPL:2;         // I/O Privilege Level
3697     UINT32  NT:1;           // Nested Task
3698     UINT32  Reserved_3:1;   // Reserved
3699     UINT32  RF:1;           // Resume Flag
3700     UINT32  VM:1;           // Virtual 8086 Mode
3701     UINT32  AC:1;           // Alignment Check
3702     UINT32  VIF:1;          // Virtual Interrupt Flag
3703     UINT32  VIP:1;          // Virtual Interrupt Pending
3704     UINT32  ID:1;           // ID Flag
3705     UINT32  Reserved_4:10;  // Reserved
3706   } Bits;
3707   UINTN     UintN;
3708 } IA32_EFLAGS32;
3709
3710 //
3711 // Byte packed structure for Control Register 0 (CR0)
3712 // 32-bits on IA-32
3713 // 64-bits on X64.  The upper 32-bits on X64 are reserved
3714 //
3715 typedef union {
3716   struct {
3717     UINT32  PE:1;           // Protection Enable
3718     UINT32  MP:1;           // Monitor Coprocessor
3719     UINT32  EM:1;           // Emulation
3720     UINT32  TS:1;           // Task Switched
3721     UINT32  ET:1;           // Extension Type
3722     UINT32  NE:1;           // Numeric Error
3723     UINT32  Reserved_0:10;  // Reserved
3724     UINT32  WP:1;           // Write Protect
3725     UINT32  Reserved_1:1;   // Reserved
3726     UINT32  AM:1;           // Alignment Mask
3727     UINT32  Reserved_2:10;  // Reserved
3728     UINT32  NW:1;           // Mot Write-through
3729     UINT32  CD:1;           // Cache Disable
3730     UINT32  PG:1;           // Paging
3731   } Bits;
3732   UINTN     UintN;
3733 } IA32_CR0;
3734
3735 //
3736 // Byte packed structure for Control Register 4 (CR4)
3737 // 32-bits on IA-32
3738 // 64-bits on X64.  The upper 32-bits on X64 are reserved
3739 //
3740 typedef union {
3741   struct {
3742     UINT32  VME:1;          // Virtual-8086 Mode Extensions
3743     UINT32  PVI:1;          // Protected-Mode Virtual Interrupts
3744     UINT32  TSD:1;          // Time Stamp Disable
3745     UINT32  DE:1;           // Debugging Extensions
3746     UINT32  PSE:1;          // Page Size Extensions
3747     UINT32  PAE:1;          // Physical Address Extension
3748     UINT32  MCE:1;          // Machine Check Enable
3749     UINT32  PGE:1;          // Page Global Enable
3750     UINT32  PCE:1;          // Performance Monitoring Counter
3751                             // Enable
3752     UINT32  OSFXSR:1;       // Operating System Support for
3753                             // FXSAVE and FXRSTOR instructions
3754     UINT32  OSXMMEXCPT:1;   // Operating System Support for
3755                             // Unmasked SIMD Floating Point
3756                             // Exceptions
3757     UINT32  Reserved_0:2;   // Reserved
3758     UINT32  VMXE:1;         // VMX Enable
3759     UINT32  Reserved_1:18;  // Reseved
3760   } Bits;
3761   UINTN     UintN;
3762 } IA32_CR4;
3763
3764 //
3765 // Byte packed structure for an IDTR, GDTR, LDTR descriptor
3766 /// @bug  How to make this structure byte-packed in a compiler independent way?
3767 //
3768 #pragma pack (1)
3769 typedef struct {
3770   UINT16  Limit;
3771   UINTN   Base;
3772 } IA32_DESCRIPTOR;
3773 #pragma pack ()
3774
3775 #define IA32_IDT_GATE_TYPE_TASK          0x85
3776 #define IA32_IDT_GATE_TYPE_INTERRUPT_16  0x86
3777 #define IA32_IDT_GATE_TYPE_TRAP_16       0x87
3778 #define IA32_IDT_GATE_TYPE_INTERRUPT_32  0x8E
3779 #define IA32_IDT_GATE_TYPE_TRAP_32       0x8F
3780
3781 //
3782 // Byte packed structure for an Interrupt Gate Descriptor
3783 //
3784 typedef union {
3785   struct {
3786     UINT32  OffsetLow:16;   // Offset bits 15..0
3787     UINT32  Selector:16;    // Selector
3788     UINT32  Reserved_0:8;   // Reserved
3789     UINT32  GateType:8;     // Gate Type.  See #defines above
3790     UINT32  OffsetHigh:16;  // Offset bits 31..16
3791   } Bits;
3792   UINT64  Uint64;
3793 } IA32_IDT_GATE_DESCRIPTOR;
3794
3795 //
3796 // Byte packed structure for an FP/SSE/SSE2 context
3797 //
3798 typedef struct {
3799   UINT8  Buffer[512];
3800 } IA32_FX_BUFFER;
3801
3802 //
3803 // Structures for the 16-bit real mode thunks
3804 //
3805 typedef struct {
3806   UINT32                            Reserved1;
3807   UINT32                            Reserved2;
3808   UINT32                            Reserved3;
3809   UINT32                            Reserved4;
3810   UINT8                             BL;
3811   UINT8                             BH;
3812   UINT16                            Reserved5;
3813   UINT8                             DL;
3814   UINT8                             DH;
3815   UINT16                            Reserved6;
3816   UINT8                             CL;
3817   UINT8                             CH;
3818   UINT16                            Reserved7;
3819   UINT8                             AL;
3820   UINT8                             AH;
3821   UINT16                            Reserved8;
3822 } IA32_BYTE_REGS;
3823
3824 typedef struct {
3825   UINT16                            DI;
3826   UINT16                            Reserved1;
3827   UINT16                            SI;
3828   UINT16                            Reserved2;
3829   UINT16                            BP;
3830   UINT16                            Reserved3;
3831   UINT16                            SP;
3832   UINT16                            Reserved4;
3833   UINT16                            BX;
3834   UINT16                            Reserved5;
3835   UINT16                            DX;
3836   UINT16                            Reserved6;
3837   UINT16                            CX;
3838   UINT16                            Reserved7;
3839   UINT16                            AX;
3840   UINT16                            Reserved8;
3841 } IA32_WORD_REGS;
3842
3843 typedef struct {
3844   UINT32                            EDI;
3845   UINT32                            ESI;
3846   UINT32                            EBP;
3847   UINT32                            ESP;
3848   UINT32                            EBX;
3849   UINT32                            EDX;
3850   UINT32                            ECX;
3851   UINT32                            EAX;
3852   UINT16                            DS;
3853   UINT16                            ES;
3854   UINT16                            FS;
3855   UINT16                            GS;
3856   IA32_EFLAGS32                     EFLAGS;
3857   UINT32                            Eip;
3858   UINT16                            CS;
3859   UINT16                            SS;
3860 } IA32_DWORD_REGS;
3861
3862 typedef union {
3863   IA32_DWORD_REGS                   E;
3864   IA32_WORD_REGS                    X;
3865   IA32_BYTE_REGS                    H;
3866 } IA32_REGISTER_SET;
3867
3868 //
3869 // Byte packed structure for an 16-bit real mode thunks
3870 //
3871 typedef struct {
3872   IA32_REGISTER_SET                 *RealModeState;
3873   VOID                              *RealModeBuffer;
3874   UINT32                            RealModeBufferSize;
3875   UINT32                            ThunkAttributes;
3876 } THUNK_CONTEXT;
3877
3878 #define THUNK_ATTRIBUTE_BIG_REAL_MODE             0x00000001
3879 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15   0x00000002
3880 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
3881
3882 /**
3883   Retrieves CPUID information.
3884
3885   Executes the CPUID instruction with EAX set to the value specified by Index.
3886   This function always returns Index.
3887   If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
3888   If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
3889   If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
3890   If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
3891   This function is only available on IA-32 and X64.
3892
3893   @param  Index The 32-bit value to load into EAX prior to invoking the CPUID
3894                 instruction.
3895   @param  Eax   Pointer to the 32-bit EAX value returned by the CPUID
3896                 instruction. This is an optional parameter that may be NULL.
3897   @param  Ebx   Pointer to the 32-bit EBX value returned by the CPUID
3898                 instruction. This is an optional parameter that may be NULL.
3899   @param  Ecx   Pointer to the 32-bit ECX value returned by the CPUID
3900                 instruction. This is an optional parameter that may be NULL.
3901   @param  Edx   Pointer to the 32-bit EDX value returned by the CPUID
3902                 instruction. This is an optional parameter that may be NULL.
3903
3904   @return Index
3905
3906 **/
3907 UINT32
3908 EFIAPI
3909 AsmCpuid (
3910   IN      UINT32                    Index,
3911   OUT     UINT32                    *Eax,  OPTIONAL
3912   OUT     UINT32                    *Ebx,  OPTIONAL
3913   OUT     UINT32                    *Ecx,  OPTIONAL
3914   OUT     UINT32                    *Edx   OPTIONAL
3915   );
3916
3917
3918 /**
3919   Retrieves CPUID information using an extended leaf identifier.
3920
3921   Executes the CPUID instruction with EAX set to the value specified by Index
3922   and ECX set to the value specified by SubIndex. This function always returns
3923   Index. This function is only available on IA-32 and x64.
3924
3925   If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
3926   If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
3927   If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
3928   If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
3929
3930   @param  Index     The 32-bit value to load into EAX prior to invoking the
3931                     CPUID instruction.
3932   @param  SubIndex  The 32-bit value to load into ECX prior to invoking the
3933                     CPUID instruction.
3934   @param  Eax       Pointer to the 32-bit EAX value returned by the CPUID
3935                     instruction. This is an optional parameter that may be
3936                     NULL.
3937   @param  Ebx       Pointer to the 32-bit EBX value returned by the CPUID
3938                     instruction. This is an optional parameter that may be
3939                     NULL.
3940   @param  Ecx       Pointer to the 32-bit ECX value returned by the CPUID
3941                     instruction. This is an optional parameter that may be
3942                     NULL.
3943   @param  Edx       Pointer to the 32-bit EDX value returned by the CPUID
3944                     instruction. This is an optional parameter that may be
3945                     NULL.
3946
3947   @return Index
3948
3949 **/
3950 UINT32
3951 EFIAPI
3952 AsmCpuidEx (
3953   IN      UINT32                    Index,
3954   IN      UINT32                    SubIndex,
3955   OUT     UINT32                    *Eax,  OPTIONAL
3956   OUT     UINT32                    *Ebx,  OPTIONAL
3957   OUT     UINT32                    *Ecx,  OPTIONAL
3958   OUT     UINT32                    *Edx   OPTIONAL
3959   );
3960
3961
3962 /**
3963   Returns the lower 32-bits of a Machine Specific Register(MSR).
3964
3965   Reads and returns the lower 32-bits of the MSR specified by Index.
3966   No parameter checking is performed on Index, and some Index values may cause
3967   CPU exceptions. The caller must either guarantee that Index is valid, or the
3968   caller must set up exception handlers to catch the exceptions. This function
3969   is only available on IA-32 and X64.
3970
3971   @param  Index The 32-bit MSR index to read.
3972
3973   @return The lower 32 bits of the MSR identified by Index.
3974
3975 **/
3976 UINT32
3977 EFIAPI
3978 AsmReadMsr32 (
3979   IN      UINT32                    Index
3980   );
3981
3982
3983 /**
3984   Zero-extend a 32-bit value and writes it to a Machine Specific Register(MSR).
3985
3986   Writes the 32-bit value specified by Value to the MSR specified by Index. The
3987   upper 32-bits of the MSR write are set to zero. The 32-bit value written to
3988   the MSR is returned. No parameter checking is performed on Index or Value,
3989   and some of these may cause CPU exceptions. The caller must either guarantee
3990   that Index and Value are valid, or the caller must establish proper exception
3991   handlers. This function is only available on IA-32 and X64.
3992
3993   @param  Index The 32-bit MSR index to write.
3994   @param  Value The 32-bit value to write to the MSR.
3995
3996   @return Value
3997
3998 **/
3999 UINT32
4000 EFIAPI
4001 AsmWriteMsr32 (
4002   IN      UINT32                    Index,
4003   IN      UINT32                    Value
4004   );
4005
4006
4007 /**
4008   Reads a 64-bit MSR, performs a bitwise inclusive OR on the lower 32-bits, and
4009   writes the result back to the 64-bit MSR.
4010
4011   Reads the 64-bit MSR specified by Index, performs a bitwise inclusive OR
4012   between the lower 32-bits of the read result and the value specified by
4013   OrData, and writes the result to the 64-bit MSR specified by Index. The lower
4014   32-bits of the value written to the MSR is returned. No parameter checking is
4015   performed on Index or OrData, and some of these may cause CPU exceptions. The
4016   caller must either guarantee that Index and OrData are valid, or the caller
4017   must establish proper exception handlers. This function is only available on
4018   IA-32 and X64.
4019
4020   @param  Index   The 32-bit MSR index to write.
4021   @param  OrData  The value to OR with the read value from the MSR.
4022
4023   @return The lower 32-bit value written to the MSR.
4024
4025 **/
4026 UINT32
4027 EFIAPI
4028 AsmMsrOr32 (
4029   IN      UINT32                    Index,
4030   IN      UINT32                    OrData
4031   );
4032
4033
4034 /**
4035   Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
4036   the result back to the 64-bit MSR.
4037
4038   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
4039   lower 32-bits of the read result and the value specified by AndData, and
4040   writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
4041   the value written to the MSR is returned. No parameter checking is performed
4042   on Index or AndData, and some of these may cause CPU exceptions. The caller
4043   must either guarantee that Index and AndData are valid, or the caller must
4044   establish proper exception handlers. This function is only available on IA-32
4045   and X64.
4046
4047   @param  Index   The 32-bit MSR index to write.
4048   @param  AndData The value to AND with the read value from the MSR.
4049
4050   @return The lower 32-bit value written to the MSR.
4051
4052 **/
4053 UINT32
4054 EFIAPI
4055 AsmMsrAnd32 (
4056   IN      UINT32                    Index,
4057   IN      UINT32                    AndData
4058   );
4059
4060
4061 /**
4062   Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise inclusive OR
4063   on the lower 32-bits, and writes the result back to the 64-bit MSR.
4064
4065   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
4066   lower 32-bits of the read result and the value specified by AndData
4067   preserving the upper 32-bits, performs a bitwise inclusive OR between the
4068   result of the AND operation and the value specified by OrData, and writes the
4069   result to the 64-bit MSR specified by Address. The lower 32-bits of the value
4070   written to the MSR is returned. No parameter checking is performed on Index,
4071   AndData, or OrData, and some of these may cause CPU exceptions. The caller
4072   must either guarantee that Index, AndData, and OrData are valid, or the
4073   caller must establish proper exception handlers. This function is only
4074   available on IA-32 and X64.
4075
4076   @param  Index   The 32-bit MSR index to write.
4077   @param  AndData The value to AND with the read value from the MSR.
4078   @param  OrData  The value to OR with the result of the AND operation.
4079
4080   @return The lower 32-bit value written to the MSR.
4081
4082 **/
4083 UINT32
4084 EFIAPI
4085 AsmMsrAndThenOr32 (
4086   IN      UINT32                    Index,
4087   IN      UINT32                    AndData,
4088   IN      UINT32                    OrData
4089   );
4090
4091
4092 /**
4093   Reads a bit field of an MSR.
4094
4095   Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
4096   specified by the StartBit and the EndBit. The value of the bit field is
4097   returned. The caller must either guarantee that Index is valid, or the caller
4098   must set up exception handlers to catch the exceptions. This function is only
4099   available on IA-32 and X64.
4100
4101   If StartBit is greater than 31, then ASSERT().
4102   If EndBit is greater than 31, then ASSERT().
4103   If EndBit is less than StartBit, then ASSERT().
4104
4105   @param  Index     The 32-bit MSR index to read.
4106   @param  StartBit  The ordinal of the least significant bit in the bit field.
4107                     Range 0..31.
4108   @param  EndBit    The ordinal of the most significant bit in the bit field.
4109                     Range 0..31.
4110
4111   @return The bit field read from the MSR.
4112
4113 **/
4114 UINT32
4115 EFIAPI
4116 AsmMsrBitFieldRead32 (
4117   IN      UINT32                    Index,
4118   IN      UINTN                     StartBit,
4119   IN      UINTN                     EndBit
4120   );
4121
4122
4123 /**
4124   Writes a bit field to an MSR.
4125
4126   Writes Value to a bit field in the lower 32-bits of a  64-bit MSR. The bit
4127   field is specified by the StartBit and the EndBit. All other bits in the
4128   destination MSR are preserved. The lower 32-bits of the MSR written is
4129   returned. Extra left bits in Value are stripped. The caller must either
4130   guarantee that Index and the data written is valid, or the caller must set up
4131   exception handlers to catch the exceptions. This function is only available
4132   on IA-32 and X64.
4133
4134   If StartBit is greater than 31, then ASSERT().
4135   If EndBit is greater than 31, then ASSERT().
4136   If EndBit is less than StartBit, then ASSERT().
4137
4138   @param  Index     The 32-bit MSR index to write.
4139   @param  StartBit  The ordinal of the least significant bit in the bit field.
4140                     Range 0..31.
4141   @param  EndBit    The ordinal of the most significant bit in the bit field.
4142                     Range 0..31.
4143   @param  Value     New value of the bit field.
4144
4145   @return The lower 32-bit of the value written to the MSR.
4146
4147 **/
4148 UINT32
4149 EFIAPI
4150 AsmMsrBitFieldWrite32 (
4151   IN      UINT32                    Index,
4152   IN      UINTN                     StartBit,
4153   IN      UINTN                     EndBit,
4154   IN      UINT32                    Value
4155   );
4156
4157
4158 /**
4159   Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
4160   result back to the bit field in the 64-bit MSR.
4161
4162   Reads the 64-bit MSR specified by Index, performs a bitwise inclusive OR
4163   between the read result and the value specified by OrData, and writes the
4164   result to the 64-bit MSR specified by Index. The lower 32-bits of the value
4165   written to the MSR are returned. Extra left bits in OrData are stripped. The
4166   caller must either guarantee that Index and the data written is valid, or
4167   the caller must set up exception handlers to catch the exceptions. This
4168   function is only available on IA-32 and X64.
4169
4170   If StartBit is greater than 31, then ASSERT().
4171   If EndBit is greater than 31, then ASSERT().
4172   If EndBit is less than StartBit, then ASSERT().
4173
4174   @param  Index     The 32-bit MSR index to write.
4175   @param  StartBit  The ordinal of the least significant bit in the bit field.
4176                     Range 0..31.
4177   @param  EndBit    The ordinal of the most significant bit in the bit field.
4178                     Range 0..31.
4179   @param  OrData    The value to OR with the read value from the MSR.
4180
4181   @return The lower 32-bit of the value written to the MSR.
4182
4183 **/
4184 UINT32
4185 EFIAPI
4186 AsmMsrBitFieldOr32 (
4187   IN      UINT32                    Index,
4188   IN      UINTN                     StartBit,
4189   IN      UINTN                     EndBit,
4190   IN      UINT32                    OrData
4191   );
4192
4193
4194 /**
4195   Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
4196   result back to the bit field in the 64-bit MSR.
4197
4198   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
4199   read result and the value specified by AndData, and writes the result to the
4200   64-bit MSR specified by Index. The lower 32-bits of the value written to the
4201   MSR are returned. Extra left bits in AndData are stripped. The caller must
4202   either guarantee that Index and the data written is valid, or the caller must
4203   set up exception handlers to catch the exceptions. This function is only
4204   available on IA-32 and X64.
4205
4206   If StartBit is greater than 31, then ASSERT().
4207   If EndBit is greater than 31, then ASSERT().
4208   If EndBit is less than StartBit, then ASSERT().
4209
4210   @param  Index     The 32-bit MSR index to write.
4211   @param  StartBit  The ordinal of the least significant bit in the bit field.
4212                     Range 0..31.
4213   @param  EndBit    The ordinal of the most significant bit in the bit field.
4214                     Range 0..31.
4215   @param  AndData   The value to AND with the read value from the MSR.
4216
4217   @return The lower 32-bit of the value written to the MSR.
4218
4219 **/
4220 UINT32
4221 EFIAPI
4222 AsmMsrBitFieldAnd32 (
4223   IN      UINT32                    Index,
4224   IN      UINTN                     StartBit,
4225   IN      UINTN                     EndBit,
4226   IN      UINT32                    AndData
4227   );
4228
4229
4230 /**
4231   Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
4232   bitwise inclusive OR, and writes the result back to the bit field in the
4233   64-bit MSR.
4234
4235   Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
4236   bitwise inclusive OR between the read result and the value specified by
4237   AndData, and writes the result to the 64-bit MSR specified by Index. The
4238   lower 32-bits of the value written to the MSR are returned. Extra left bits
4239   in both AndData and OrData are stripped. The caller must either guarantee
4240   that Index and the data written is valid, or the caller must set up exception
4241   handlers to catch the exceptions. This function is only available on IA-32
4242   and X64.
4243
4244   If StartBit is greater than 31, then ASSERT().
4245   If EndBit is greater than 31, then ASSERT().
4246   If EndBit is less than StartBit, then ASSERT().
4247
4248   @param  Index     The 32-bit MSR index to write.
4249   @param  StartBit  The ordinal of the least significant bit in the bit field.
4250                     Range 0..31.
4251   @param  EndBit    The ordinal of the most significant bit in the bit field.
4252                     Range 0..31.
4253   @param  AndData   The value to AND with the read value from the MSR.
4254   @param  OrData    The value to OR with the result of the AND operation.
4255
4256   @return The lower 32-bit of the value written to the MSR.
4257
4258 **/
4259 UINT32
4260 EFIAPI
4261 AsmMsrBitFieldAndThenOr32 (
4262   IN      UINT32                    Index,
4263   IN      UINTN                     StartBit,
4264   IN      UINTN                     EndBit,
4265   IN      UINT32                    AndData,
4266   IN      UINT32                    OrData
4267   );
4268
4269
4270 /**
4271   Returns a 64-bit Machine Specific Register(MSR).
4272
4273   Reads and returns the 64-bit MSR specified by Index. No parameter checking is
4274   performed on Index, and some Index values may cause CPU exceptions. The
4275   caller must either guarantee that Index is valid, or the caller must set up
4276   exception handlers to catch the exceptions. This function is only available
4277   on IA-32 and X64.
4278
4279   @param  Index The 32-bit MSR index to read.
4280
4281   @return The value of the MSR identified by Index.
4282
4283 **/
4284 UINT64
4285 EFIAPI
4286 AsmReadMsr64 (
4287   IN      UINT32                    Index
4288   );
4289
4290
4291 /**
4292   Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
4293   value.
4294
4295   Writes the 64-bit value specified by Value to the MSR specified by Index. The
4296   64-bit value written to the MSR is returned. No parameter checking is
4297   performed on Index or Value, and some of these may cause CPU exceptions. The
4298   caller must either guarantee that Index and Value are valid, or the caller
4299   must establish proper exception handlers. This function is only available on
4300   IA-32 and X64.
4301
4302   @param  Index The 32-bit MSR index to write.
4303   @param  Value The 64-bit value to write to the MSR.
4304
4305   @return Value
4306
4307 **/
4308 UINT64
4309 EFIAPI
4310 AsmWriteMsr64 (
4311   IN      UINT32                    Index,
4312   IN      UINT64                    Value
4313   );
4314
4315
4316 /**
4317   Reads a 64-bit MSR, performs a bitwise inclusive OR, and writes the result
4318   back to the 64-bit MSR.
4319
4320   Reads the 64-bit MSR specified by Index, performs a bitwise inclusive OR
4321   between the read result and the value specified by OrData, and writes the
4322   result to the 64-bit MSR specified by Index. The value written to the MSR is
4323   returned. No parameter checking is performed on Index or OrData, and some of
4324   these may cause CPU exceptions. The caller must either guarantee that Index
4325   and OrData are valid, or the caller must establish proper exception handlers.
4326   This function is only available on IA-32 and X64.
4327
4328   @param  Index   The 32-bit MSR index to write.
4329   @param  OrData  The value to OR with the read value from the MSR.
4330
4331   @return The value written back to the MSR.
4332
4333 **/
4334 UINT64
4335 EFIAPI
4336 AsmMsrOr64 (
4337   IN      UINT32                    Index,
4338   IN      UINT64                    OrData
4339   );
4340
4341
4342 /**
4343   Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
4344   64-bit MSR.
4345
4346   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
4347   read result and the value specified by OrData, and writes the result to the
4348   64-bit MSR specified by Index. The value written to the MSR is returned. No
4349   parameter checking is performed on Index or OrData, and some of these may
4350   cause CPU exceptions. The caller must either guarantee that Index and OrData
4351   are valid, or the caller must establish proper exception handlers. This
4352   function is only available on IA-32 and X64.
4353
4354   @param  Index   The 32-bit MSR index to write.
4355   @param  AndData The value to AND with the read value from the MSR.
4356
4357   @return The value written back to the MSR.
4358
4359 **/
4360 UINT64
4361 EFIAPI
4362 AsmMsrAnd64 (
4363   IN      UINT32                    Index,
4364   IN      UINT64                    AndData
4365   );
4366
4367
4368 /**
4369   Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise inclusive
4370   OR, and writes the result back to the 64-bit MSR.
4371
4372   Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
4373   result and the value specified by AndData, performs a bitwise inclusive OR
4374   between the result of the AND operation and the value specified by OrData,
4375   and writes the result to the 64-bit MSR specified by Index. The value written
4376   to the MSR is returned. No parameter checking is performed on Index, AndData,
4377   or OrData, and some of these may cause CPU exceptions. The caller must either
4378   guarantee that Index, AndData, and OrData are valid, or the caller must
4379   establish proper exception handlers. This function is only available on IA-32
4380   and X64.
4381
4382   @param  Index   The 32-bit MSR index to write.
4383   @param  AndData The value to AND with the read value from the MSR.
4384   @param  OrData  The value to OR with the result of the AND operation.
4385
4386   @return The value written back to the MSR.
4387
4388 **/
4389 UINT64
4390 EFIAPI
4391 AsmMsrAndThenOr64 (
4392   IN      UINT32                    Index,
4393   IN      UINT64                    AndData,
4394   IN      UINT64                    OrData
4395   );
4396
4397
4398 /**
4399   Reads a bit field of an MSR.
4400
4401   Reads the bit field in the 64-bit MSR. The bit field is specified by the
4402   StartBit and the EndBit. The value of the bit field is returned. The caller
4403   must either guarantee that Index is valid, or the caller must set up
4404   exception handlers to catch the exceptions. This function is only available
4405   on IA-32 and X64.
4406
4407   If StartBit is greater than 63, then ASSERT().
4408   If EndBit is greater than 63, then ASSERT().
4409   If EndBit is less than StartBit, then ASSERT().
4410
4411   @param  Index     The 32-bit MSR index to read.
4412   @param  StartBit  The ordinal of the least significant bit in the bit field.
4413                     Range 0..63.
4414   @param  EndBit    The ordinal of the most significant bit in the bit field.
4415                     Range 0..63.
4416
4417   @return The value read from the MSR.
4418
4419 **/
4420 UINT64
4421 EFIAPI
4422 AsmMsrBitFieldRead64 (
4423   IN      UINT32                    Index,
4424   IN      UINTN                     StartBit,
4425   IN      UINTN                     EndBit
4426   );
4427
4428
4429 /**
4430   Writes a bit field to an MSR.
4431
4432   Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
4433   the StartBit and the EndBit. All other bits in the destination MSR are
4434   preserved. The MSR written is returned. Extra left bits in Value are
4435   stripped. The caller must either guarantee that Index and the data written is
4436   valid, or the caller must set up exception handlers to catch the exceptions.
4437   This function is only available on IA-32 and X64.
4438
4439   If StartBit is greater than 63, then ASSERT().
4440   If EndBit is greater than 63, then ASSERT().
4441   If EndBit is less than StartBit, then ASSERT().
4442
4443   @param  Index     The 32-bit MSR index to write.
4444   @param  StartBit  The ordinal of the least significant bit in the bit field.
4445                     Range 0..63.
4446   @param  EndBit    The ordinal of the most significant bit in the bit field.
4447                     Range 0..63.
4448   @param  Value     New value of the bit field.
4449
4450   @return The value written back to the MSR.
4451
4452 **/
4453 UINT64
4454 EFIAPI
4455 AsmMsrBitFieldWrite64 (
4456   IN      UINT32                    Index,
4457   IN      UINTN                     StartBit,
4458   IN      UINTN                     EndBit,
4459   IN      UINT64                    Value
4460   );
4461
4462
4463 /**
4464   Reads a bit field in a 64-bit MSR, performs a bitwise inclusive OR, and
4465   writes the result back to the bit field in the 64-bit MSR.
4466
4467   Reads the 64-bit MSR specified by Index, performs a bitwise inclusive OR
4468   between the read result and the value specified by OrData, and writes the
4469   result to the 64-bit MSR specified by Index. The value written to the MSR is
4470   returned. Extra left bits in OrData are stripped. The caller must either
4471   guarantee that Index and the data written is valid, or the caller must set up
4472   exception handlers to catch the exceptions. This function is only available
4473   on IA-32 and X64.
4474
4475   If StartBit is greater than 63, then ASSERT().
4476   If EndBit is greater than 63, then ASSERT().
4477   If EndBit is less than StartBit, then ASSERT().
4478
4479   @param  Index     The 32-bit MSR index to write.
4480   @param  StartBit  The ordinal of the least significant bit in the bit field.
4481                     Range 0..63.
4482   @param  EndBit    The ordinal of the most significant bit in the bit field.
4483                     Range 0..63.
4484   @param  OrData    The value to OR with the read value from the bit field.
4485
4486   @return The value written back to the MSR.
4487
4488 **/
4489 UINT64
4490 EFIAPI
4491 AsmMsrBitFieldOr64 (
4492   IN      UINT32                    Index,
4493   IN      UINTN                     StartBit,
4494   IN      UINTN                     EndBit,
4495   IN      UINT64                    OrData
4496   );
4497
4498
4499 /**
4500   Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
4501   result back to the bit field in the 64-bit MSR.
4502
4503   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
4504   read result and the value specified by AndData, and writes the result to the
4505   64-bit MSR specified by Index. The value written to the MSR is returned.
4506   Extra left bits in AndData are stripped. The caller must either guarantee
4507   that Index and the data written is valid, or the caller must set up exception
4508   handlers to catch the exceptions. This function is only available on IA-32
4509   and X64.
4510
4511   If StartBit is greater than 63, then ASSERT().
4512   If EndBit is greater than 63, then ASSERT().
4513   If EndBit is less than StartBit, then ASSERT().
4514
4515   @param  Index     The 32-bit MSR index to write.
4516   @param  StartBit  The ordinal of the least significant bit in the bit field.
4517                     Range 0..63.
4518   @param  EndBit    The ordinal of the most significant bit in the bit field.
4519                     Range 0..63.
4520   @param  AndData   The value to AND with the read value from the bit field.
4521
4522   @return The value written back to the MSR.
4523
4524 **/
4525 UINT64
4526 EFIAPI
4527 AsmMsrBitFieldAnd64 (
4528   IN      UINT32                    Index,
4529   IN      UINTN                     StartBit,
4530   IN      UINTN                     EndBit,
4531   IN      UINT64                    AndData
4532   );
4533
4534
4535 /**
4536   Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
4537   bitwise inclusive OR, and writes the result back to the bit field in the
4538   64-bit MSR.
4539
4540   Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
4541   a bitwise inclusive OR between the read result and the value specified by
4542   AndData, and writes the result to the 64-bit MSR specified by Index. The
4543   value written to the MSR is returned. Extra left bits in both AndData and
4544   OrData are stripped. The caller must either guarantee that Index and the data
4545   written is valid, or the caller must set up exception handlers to catch the
4546   exceptions. This function is only available on IA-32 and X64.
4547
4548   If StartBit is greater than 63, then ASSERT().
4549   If EndBit is greater than 63, then ASSERT().
4550   If EndBit is less than StartBit, then ASSERT().
4551
4552   @param  Index     The 32-bit MSR index to write.
4553   @param  StartBit  The ordinal of the least significant bit in the bit field.
4554                     Range 0..63.
4555   @param  EndBit    The ordinal of the most significant bit in the bit field.
4556                     Range 0..63.
4557   @param  AndData   The value to AND with the read value from the bit field.
4558   @param  OrData    The value to OR with the result of the AND operation.
4559
4560   @return The value written back to the MSR.
4561
4562 **/
4563 UINT64
4564 EFIAPI
4565 AsmMsrBitFieldAndThenOr64 (
4566   IN      UINT32                    Index,
4567   IN      UINTN                     StartBit,
4568   IN      UINTN                     EndBit,
4569   IN      UINT64                    AndData,
4570   IN      UINT64                    OrData
4571   );
4572
4573
4574 /**
4575   Reads the current value of the EFLAGS register.
4576
4577   Reads and returns the current value of the EFLAGS register. This function is
4578   only available on IA-32 and X64. This returns a 32-bit value on IA-32 and a
4579   64-bit value on X64.
4580
4581   @return EFLAGS on IA-32 or RFLAGS on X64.
4582
4583 **/
4584 UINTN
4585 EFIAPI
4586 AsmReadEflags (
4587   VOID
4588   );
4589
4590
4591 /**
4592   Reads the current value of the Control Register 0 (CR0).
4593
4594   Reads and returns the current value of CR0. This function is only available
4595   on IA-32 and X64. This returns a 32-bit value on IA-32 and a 64-bit value on
4596   X64.
4597
4598   @return The value of the Control Register 0 (CR0).
4599
4600 **/
4601 UINTN
4602 EFIAPI
4603 AsmReadCr0 (
4604   VOID
4605   );
4606
4607
4608 /**
4609   Reads the current value of the Control Register 2 (CR2).
4610
4611   Reads and returns the current value of CR2. This function is only available
4612   on IA-32 and X64. This returns a 32-bit value on IA-32 and a 64-bit value on
4613   X64.
4614
4615   @return The value of the Control Register 2 (CR2).
4616
4617 **/
4618 UINTN
4619 EFIAPI
4620 AsmReadCr2 (
4621   VOID
4622   );
4623
4624
4625 /**
4626   Reads the current value of the Control Register 3 (CR3).
4627
4628   Reads and returns the current value of CR3. This function is only available
4629   on IA-32 and X64. This returns a 32-bit value on IA-32 and a 64-bit value on
4630   X64.
4631
4632   @return The value of the Control Register 3 (CR3).
4633
4634 **/
4635 UINTN
4636 EFIAPI
4637 AsmReadCr3 (
4638   VOID
4639   );
4640
4641
4642 /**
4643   Reads the current value of the Control Register 4 (CR4).
4644
4645   Reads and returns the current value of CR4. This function is only available
4646   on IA-32 and X64. This returns a 32-bit value on IA-32 and a 64-bit value on
4647   X64.
4648
4649   @return The value of the Control Register 4 (CR4).
4650
4651 **/
4652 UINTN
4653 EFIAPI
4654 AsmReadCr4 (
4655   VOID
4656   );
4657
4658
4659 /**
4660   Writes a value to Control Register 0 (CR0).
4661
4662   Writes and returns a new value to CR0. This function is only available on
4663   IA-32 and X64. This writes a 32-bit value on IA-32 and a 64-bit value on X64.
4664
4665   @param  Cr0 The value to write to CR0.
4666
4667   @return The value written to CR0.
4668
4669 **/
4670 UINTN
4671 EFIAPI
4672 AsmWriteCr0 (
4673   UINTN  Cr0
4674   );
4675
4676
4677 /**
4678   Writes a value to Control Register 2 (CR2).
4679
4680   Writes and returns a new value to CR2. This function is only available on
4681   IA-32 and X64. This writes a 32-bit value on IA-32 and a 64-bit value on X64.
4682
4683   @param  Cr2 The value to write to CR2.
4684
4685   @return The value written to CR2.
4686
4687 **/
4688 UINTN
4689 EFIAPI
4690 AsmWriteCr2 (
4691   UINTN  Cr2
4692   );
4693
4694
4695 /**
4696   Writes a value to Control Register 3 (CR3).
4697
4698   Writes and returns a new value to CR3. This function is only available on
4699   IA-32 and X64. This writes a 32-bit value on IA-32 and a 64-bit value on X64.
4700
4701   @param  Cr3 The value to write to CR3.
4702
4703   @return The value written to CR3.
4704
4705 **/
4706 UINTN
4707 EFIAPI
4708 AsmWriteCr3 (
4709   UINTN  Cr3
4710   );
4711
4712
4713 /**
4714   Writes a value to Control Register 4 (CR4).
4715
4716   Writes and returns a new value to CR4. This function is only available on
4717   IA-32 and X64. This writes a 32-bit value on IA-32 and a 64-bit value on X64.
4718
4719   @param  Cr4 The value to write to CR4.
4720
4721   @return The value written to CR4.
4722
4723 **/
4724 UINTN
4725 EFIAPI
4726 AsmWriteCr4 (
4727   UINTN  Cr4
4728   );
4729
4730
4731 /**
4732   Reads the current value of Debug Register 0 (DR0).
4733
4734   Reads and returns the current value of DR0. This function is only available
4735   on IA-32 and X64. This returns a 32-bit value on IA-32 and a 64-bit value on
4736   X64.
4737
4738   @return The value of Debug Register 0 (DR0).
4739
4740 **/
4741 UINTN
4742 EFIAPI
4743 AsmReadDr0 (
4744   VOID
4745   );
4746
4747
4748 /**
4749   Reads the current value of Debug Register 1 (DR1).
4750
4751   Reads and returns the current value of DR1. This function is only available
4752   on IA-32 and X64. This returns a 32-bit value on IA-32 and a 64-bit value on
4753   X64.
4754
4755   @return The value of Debug Register 1 (DR1).
4756
4757 **/
4758 UINTN
4759 EFIAPI
4760 AsmReadDr1 (
4761   VOID
4762   );
4763
4764
4765 /**
4766   Reads the current value of Debug Register 2 (DR2).
4767
4768   Reads and returns the current value of DR2. This function is only available
4769   on IA-32 and X64. This returns a 32-bit value on IA-32 and a 64-bit value on
4770   X64.
4771
4772   @return The value of Debug Register 2 (DR2).
4773
4774 **/
4775 UINTN
4776 EFIAPI
4777 AsmReadDr2 (
4778   VOID
4779   );
4780
4781
4782 /**
4783   Reads the current value of Debug Register 3 (DR3).
4784
4785   Reads and returns the current value of DR3. This function is only available
4786   on IA-32 and X64. This returns a 32-bit value on IA-32 and a 64-bit value on
4787   X64.
4788
4789   @return The value of Debug Register 3 (DR3).
4790
4791 **/
4792 UINTN
4793 EFIAPI
4794 AsmReadDr3 (
4795   VOID
4796   );
4797
4798
4799 /**
4800   Reads the current value of Debug Register 4 (DR4).
4801
4802   Reads and returns the current value of DR4. This function is only available
4803   on IA-32 and X64. This returns a 32-bit value on IA-32 and a 64-bit value on
4804   X64.
4805
4806   @return The value of Debug Register 4 (DR4).
4807
4808 **/
4809 UINTN
4810 EFIAPI
4811 AsmReadDr4 (
4812   VOID
4813   );
4814
4815
4816 /**
4817   Reads the current value of Debug Register 5 (DR5).
4818
4819   Reads and returns the current value of DR5. This function is only available
4820   on IA-32 and X64. This returns a 32-bit value on IA-32 and a 64-bit value on
4821   X64.
4822
4823   @return The value of Debug Register 5 (DR5).
4824
4825 **/
4826 UINTN
4827 EFIAPI
4828 AsmReadDr5 (
4829   VOID
4830   );
4831
4832
4833 /**
4834   Reads the current value of Debug Register 6 (DR6).
4835
4836   Reads and returns the current value of DR6. This function is only available
4837   on IA-32 and X64. This returns a 32-bit value on IA-32 and a 64-bit value on
4838   X64.
4839
4840   @return The value of Debug Register 6 (DR6).
4841
4842 **/
4843 UINTN
4844 EFIAPI
4845 AsmReadDr6 (
4846   VOID
4847   );
4848
4849
4850 /**
4851   Reads the current value of Debug Register 7 (DR7).
4852
4853   Reads and returns the current value of DR7. This function is only available
4854   on IA-32 and X64. This returns a 32-bit value on IA-32 and a 64-bit value on
4855   X64.
4856
4857   @return The value of Debug Register 7 (DR7).
4858
4859 **/
4860 UINTN
4861 EFIAPI
4862 AsmReadDr7 (
4863   VOID
4864   );
4865
4866
4867 /**
4868   Writes a value to Debug Register 0 (DR0).
4869
4870   Writes and returns a new value to DR0. This function is only available on
4871   IA-32 and X64. This writes a 32-bit value on IA-32 and a 64-bit value on X64.
4872
4873   @param  Dr0 The value to write to Dr0.
4874
4875   @return The value written to Debug Register 0 (DR0).
4876
4877 **/
4878 UINTN
4879 EFIAPI
4880 AsmWriteDr0 (
4881   UINTN  Dr0
4882   );
4883
4884
4885 /**
4886   Writes a value to Debug Register 1 (DR1).
4887
4888   Writes and returns a new value to DR1. This function is only available on
4889   IA-32 and X64. This writes a 32-bit value on IA-32 and a 64-bit value on X64.
4890
4891   @param  Dr1 The value to write to Dr1.
4892
4893   @return The value written to Debug Register 1 (DR1).
4894
4895 **/
4896 UINTN
4897 EFIAPI
4898 AsmWriteDr1 (
4899   UINTN  Dr1
4900   );
4901
4902
4903 /**
4904   Writes a value to Debug Register 2 (DR2).
4905
4906   Writes and returns a new value to DR2. This function is only available on
4907   IA-32 and X64. This writes a 32-bit value on IA-32 and a 64-bit value on X64.
4908
4909   @param  Dr2 The value to write to Dr2.
4910
4911   @return The value written to Debug Register 2 (DR2).
4912
4913 **/
4914 UINTN
4915 EFIAPI
4916 AsmWriteDr2 (
4917   UINTN  Dr2
4918   );
4919
4920
4921 /**
4922   Writes a value to Debug Register 3 (DR3).
4923
4924   Writes and returns a new value to DR3. This function is only available on
4925   IA-32 and X64. This writes a 32-bit value on IA-32 and a 64-bit value on X64.
4926
4927   @param  Dr3 The value to write to Dr3.
4928
4929   @return The value written to Debug Register 3 (DR3).
4930
4931 **/
4932 UINTN
4933 EFIAPI
4934 AsmWriteDr3 (
4935   UINTN  Dr3
4936   );
4937
4938
4939 /**
4940   Writes a value to Debug Register 4 (DR4).
4941
4942   Writes and returns a new value to DR4. This function is only available on
4943   IA-32 and X64. This writes a 32-bit value on IA-32 and a 64-bit value on X64.
4944
4945   @param  Dr4 The value to write to Dr4.
4946
4947   @return The value written to Debug Register 4 (DR4).
4948
4949 **/
4950 UINTN
4951 EFIAPI
4952 AsmWriteDr4 (
4953   UINTN  Dr4
4954   );
4955
4956
4957 /**
4958   Writes a value to Debug Register 5 (DR5).
4959
4960   Writes and returns a new value to DR5. This function is only available on
4961   IA-32 and X64. This writes a 32-bit value on IA-32 and a 64-bit value on X64.
4962
4963   @param  Dr5 The value to write to Dr5.
4964
4965   @return The value written to Debug Register 5 (DR5).
4966
4967 **/
4968 UINTN
4969 EFIAPI
4970 AsmWriteDr5 (
4971   UINTN  Dr5
4972   );
4973
4974
4975 /**
4976   Writes a value to Debug Register 6 (DR6).
4977
4978   Writes and returns a new value to DR6. This function is only available on
4979   IA-32 and X64. This writes a 32-bit value on IA-32 and a 64-bit value on X64.
4980
4981   @param  Dr6 The value to write to Dr6.
4982
4983   @return The value written to Debug Register 6 (DR6).
4984
4985 **/
4986 UINTN
4987 EFIAPI
4988 AsmWriteDr6 (
4989   UINTN  Dr6
4990   );
4991
4992
4993 /**
4994   Writes a value to Debug Register 7 (DR7).
4995
4996   Writes and returns a new value to DR7. This function is only available on
4997   IA-32 and X64. This writes a 32-bit value on IA-32 and a 64-bit value on X64.
4998
4999   @param  Dr7 The value to write to Dr7.
5000
5001   @return The value written to Debug Register 7 (DR7).
5002
5003 **/
5004 UINTN
5005 EFIAPI
5006 AsmWriteDr7 (
5007   UINTN  Dr7
5008   );
5009
5010
5011 /**
5012   Reads the current value of Code Segment Register (CS).
5013
5014   Reads and returns the current value of CS. This function is only available on
5015   IA-32 and X64.
5016
5017   @return The current value of CS.
5018
5019 **/
5020 UINT16
5021 EFIAPI
5022 AsmReadCs (
5023   VOID
5024   );
5025
5026
5027 /**
5028   Reads the current value of Data Segment Register (DS).
5029
5030   Reads and returns the current value of DS. This function is only available on
5031   IA-32 and X64.
5032
5033   @return The current value of DS.
5034
5035 **/
5036 UINT16
5037 EFIAPI
5038 AsmReadDs (
5039   VOID
5040   );
5041
5042
5043 /**
5044   Reads the current value of Extra Segment Register (ES).
5045
5046   Reads and returns the current value of ES. This function is only available on
5047   IA-32 and X64.
5048
5049   @return The current value of ES.
5050
5051 **/
5052 UINT16
5053 EFIAPI
5054 AsmReadEs (
5055   VOID
5056   );
5057
5058
5059 /**
5060   Reads the current value of FS Data Segment Register (FS).
5061
5062   Reads and returns the current value of FS. This function is only available on
5063   IA-32 and X64.
5064
5065   @return The current value of FS.
5066
5067 **/
5068 UINT16
5069 EFIAPI
5070 AsmReadFs (
5071   VOID
5072   );
5073
5074
5075 /**
5076   Reads the current value of GS Data Segment Register (GS).
5077
5078   Reads and returns the current value of GS. This function is only available on
5079   IA-32 and X64.
5080
5081   @return The current value of GS.
5082
5083 **/
5084 UINT16
5085 EFIAPI
5086 AsmReadGs (
5087   VOID
5088   );
5089
5090
5091 /**
5092   Reads the current value of Stack Segment Register (SS).
5093
5094   Reads and returns the current value of SS. This function is only available on
5095   IA-32 and X64.
5096
5097   @return The current value of SS.
5098
5099 **/
5100 UINT16
5101 EFIAPI
5102 AsmReadSs (
5103   VOID
5104   );
5105
5106
5107 /**
5108   Reads the current value of Task Register (TR).
5109
5110   Reads and returns the current value of TR. This function is only available on
5111   IA-32 and X64.
5112
5113   @return The current value of TR.
5114
5115 **/
5116 UINT16
5117 EFIAPI
5118 AsmReadTr (
5119   VOID
5120   );
5121
5122
5123 /**
5124   Reads the current Global Descriptor Table Register(GDTR) descriptor.
5125
5126   Reads and returns the current GDTR descriptor and returns it in Gdtr. This
5127   function is only available on IA-32 and X64.
5128
5129   If Gdtr is NULL, then ASSERT().
5130
5131   @param  Gdtr  Pointer to a GDTR descriptor.
5132
5133 **/
5134 VOID
5135 EFIAPI
5136 AsmReadGdtr (
5137   OUT     IA32_DESCRIPTOR           *Gdtr
5138   );
5139
5140
5141 /**
5142   Writes the current Global Descriptor Table Register (GDTR) descriptor.
5143
5144   Writes and the current GDTR descriptor specified by Gdtr. This function is
5145   only available on IA-32 and X64.
5146
5147   If Gdtr is NULL, then ASSERT().
5148
5149   @param  Gdtr  Pointer to a GDTR descriptor.
5150
5151 **/
5152 VOID
5153 EFIAPI
5154 AsmWriteGdtr (
5155   IN      CONST IA32_DESCRIPTOR     *Gdtr
5156   );
5157
5158
5159 /**
5160   Reads the current Interrupt Descriptor Table Register(GDTR) descriptor.
5161
5162   Reads and returns the current IDTR descriptor and returns it in Idtr. This
5163   function is only available on IA-32 and X64.
5164
5165   If Idtr is NULL, then ASSERT().
5166
5167   @param  Idtr  Pointer to a IDTR descriptor.
5168
5169 **/
5170 VOID
5171 EFIAPI
5172 AsmReadIdtr (
5173   OUT     IA32_DESCRIPTOR           *Idtr
5174   );
5175
5176
5177 /**
5178   Writes the current Interrupt Descriptor Table Register(GDTR) descriptor.
5179
5180   Writes the current IDTR descriptor and returns it in Idtr. This function is
5181   only available on IA-32 and X64.
5182
5183   If Idtr is NULL, then ASSERT().
5184
5185   @param  Idtr  Pointer to a IDTR descriptor.
5186
5187 **/
5188 VOID
5189 EFIAPI
5190 AsmWriteIdtr (
5191   IN      CONST IA32_DESCRIPTOR     *Idtr
5192   );
5193
5194
5195 /**
5196   Reads the current Local Descriptor Table Register(LDTR) selector.
5197
5198   Reads and returns the current 16-bit LDTR descriptor value. This function is
5199   only available on IA-32 and X64.
5200
5201   @return The current selector of LDT.
5202
5203 **/
5204 UINT16
5205 EFIAPI
5206 AsmReadLdtr (
5207   VOID
5208   );
5209
5210
5211 /**
5212   Writes the current Local Descriptor Table Register (GDTR) selector.
5213
5214   Writes and the current LDTR descriptor specified by Ldtr. This function is
5215   only available on IA-32 and X64.
5216
5217   @param  Ldtr  16-bit LDTR selector value.
5218
5219 **/
5220 VOID
5221 EFIAPI
5222 AsmWriteLdtr (
5223   IN      UINT16                    Ldtr
5224   );
5225
5226
5227 /**
5228   Save the current floating point/SSE/SSE2 context to a buffer.
5229
5230   Saves the current floating point/SSE/SSE2 state to the buffer specified by
5231   Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
5232   available on IA-32 and X64.
5233
5234   If Buffer is NULL, then ASSERT().
5235   If Buffer is not aligned on a 16-byte boundary, then ASSERT().
5236
5237   @param  Buffer  Pointer to a buffer to save the floating point/SSE/SSE2 context.
5238
5239 **/
5240 VOID
5241 EFIAPI
5242 AsmFxSave (
5243   OUT     IA32_FX_BUFFER            *Buffer
5244   );
5245
5246
5247 /**
5248   Restores the current floating point/SSE/SSE2 context from a buffer.
5249
5250   Restores the current floating point/SSE/SSE2 state from the buffer specified
5251   by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
5252   only available on IA-32 and X64.
5253
5254   If Buffer is NULL, then ASSERT().
5255   If Buffer is not aligned on a 16-byte boundary, then ASSERT().
5256   If Buffer was not saved with AsmFxSave(), then ASSERT().
5257
5258   @param  Buffer  Pointer to a buffer to save the floating point/SSE/SSE2 context.
5259
5260 **/
5261 VOID
5262 EFIAPI
5263 AsmFxRestore (
5264   IN      CONST IA32_FX_BUFFER      *Buffer
5265   );
5266
5267
5268 /**
5269   Reads the current value of 64-bit MMX Register #0 (MM0).
5270
5271   Reads and returns the current value of MM0. This function is only available
5272   on IA-32 and X64.
5273
5274   @return The current value of MM0.
5275
5276 **/
5277 UINT64
5278 EFIAPI
5279 AsmReadMm0 (
5280   VOID
5281   );
5282
5283
5284 /**
5285   Reads the current value of 64-bit MMX Register #1 (MM1).
5286
5287   Reads and returns the current value of MM1. This function is only available
5288   on IA-32 and X64.
5289
5290   @return The current value of MM1.
5291
5292 **/
5293 UINT64
5294 EFIAPI
5295 AsmReadMm1 (
5296   VOID
5297   );
5298
5299
5300 /**
5301   Reads the current value of 64-bit MMX Register #2 (MM2).
5302
5303   Reads and returns the current value of MM2. This function is only available
5304   on IA-32 and X64.
5305
5306   @return The current value of MM2.
5307
5308 **/
5309 UINT64
5310 EFIAPI
5311 AsmReadMm2 (
5312   VOID
5313   );
5314
5315
5316 /**
5317   Reads the current value of 64-bit MMX Register #3 (MM3).
5318
5319   Reads and returns the current value of MM3. This function is only available
5320   on IA-32 and X64.
5321
5322   @return The current value of MM3.
5323
5324 **/
5325 UINT64
5326 EFIAPI
5327 AsmReadMm3 (
5328   VOID
5329   );
5330
5331
5332 /**
5333   Reads the current value of 64-bit MMX Register #4 (MM4).
5334
5335   Reads and returns the current value of MM4. This function is only available
5336   on IA-32 and X64.
5337
5338   @return The current value of MM4.
5339
5340 **/
5341 UINT64
5342 EFIAPI
5343 AsmReadMm4 (
5344   VOID
5345   );
5346
5347
5348 /**
5349   Reads the current value of 64-bit MMX Register #5 (MM5).
5350
5351   Reads and returns the current value of MM5. This function is only available
5352   on IA-32 and X64.
5353
5354   @return The current value of MM5.
5355
5356 **/
5357 UINT64
5358 EFIAPI
5359 AsmReadMm5 (
5360   VOID
5361   );
5362
5363
5364 /**
5365   Reads the current value of 64-bit MMX Register #6 (MM6).
5366
5367   Reads and returns the current value of MM6. This function is only available
5368   on IA-32 and X64.
5369
5370   @return The current value of MM6.
5371
5372 **/
5373 UINT64
5374 EFIAPI
5375 AsmReadMm6 (
5376   VOID
5377   );
5378
5379
5380 /**
5381   Reads the current value of 64-bit MMX Register #7 (MM7).
5382
5383   Reads and returns the current value of MM7. This function is only available
5384   on IA-32 and X64.
5385
5386   @return The current value of MM7.
5387
5388 **/
5389 UINT64
5390 EFIAPI
5391 AsmReadMm7 (
5392   VOID
5393   );
5394
5395
5396 /**
5397   Writes the current value of 64-bit MMX Register #0 (MM0).
5398
5399   Writes the current value of MM0. This function is only available on IA32 and
5400   X64.
5401
5402   @param  Value The 64-bit value to write to MM0.
5403
5404 **/
5405 VOID
5406 EFIAPI
5407 AsmWriteMm0 (
5408   IN      UINT64                    Value
5409   );
5410
5411
5412 /**
5413   Writes the current value of 64-bit MMX Register #1 (MM1).
5414
5415   Writes the current value of MM1. This function is only available on IA32 and
5416   X64.
5417
5418   @param  Value The 64-bit value to write to MM1.
5419
5420 **/
5421 VOID
5422 EFIAPI
5423 AsmWriteMm1 (
5424   IN      UINT64                    Value
5425   );
5426
5427
5428 /**
5429   Writes the current value of 64-bit MMX Register #2 (MM2).
5430
5431   Writes the current value of MM2. This function is only available on IA32 and
5432   X64.
5433
5434   @param  Value The 64-bit value to write to MM2.
5435
5436 **/
5437 VOID
5438 EFIAPI
5439 AsmWriteMm2 (
5440   IN      UINT64                    Value
5441   );
5442
5443
5444 /**
5445   Writes the current value of 64-bit MMX Register #3 (MM3).
5446
5447   Writes the current value of MM3. This function is only available on IA32 and
5448   X64.
5449
5450   @param  Value The 64-bit value to write to MM3.
5451
5452 **/
5453 VOID
5454 EFIAPI
5455 AsmWriteMm3 (
5456   IN      UINT64                    Value
5457   );
5458
5459
5460 /**
5461   Writes the current value of 64-bit MMX Register #4 (MM4).
5462
5463   Writes the current value of MM4. This function is only available on IA32 and
5464   X64.
5465
5466   @param  Value The 64-bit value to write to MM4.
5467
5468 **/
5469 VOID
5470 EFIAPI
5471 AsmWriteMm4 (
5472   IN      UINT64                    Value
5473   );
5474
5475
5476 /**
5477   Writes the current value of 64-bit MMX Register #5 (MM5).
5478
5479   Writes the current value of MM5. This function is only available on IA32 and
5480   X64.
5481
5482   @param  Value The 64-bit value to write to MM5.
5483
5484 **/
5485 VOID
5486 EFIAPI
5487 AsmWriteMm5 (
5488   IN      UINT64                    Value
5489   );
5490
5491
5492 /**
5493   Writes the current value of 64-bit MMX Register #6 (MM6).
5494
5495   Writes the current value of MM6. This function is only available on IA32 and
5496   X64.
5497
5498   @param  Value The 64-bit value to write to MM6.
5499
5500 **/
5501 VOID
5502 EFIAPI
5503 AsmWriteMm6 (
5504   IN      UINT64                    Value
5505   );
5506
5507
5508 /**
5509   Writes the current value of 64-bit MMX Register #7 (MM7).
5510
5511   Writes the current value of MM7. This function is only available on IA32 and
5512   X64.
5513
5514   @param  Value The 64-bit value to write to MM7.
5515
5516 **/
5517 VOID
5518 EFIAPI
5519 AsmWriteMm7 (
5520   IN      UINT64                    Value
5521   );
5522
5523
5524 /**
5525   Reads the current value of Time Stamp Counter (TSC).
5526
5527   Reads and returns the current value of TSC. This function is only available
5528   on IA-32 and X64.
5529
5530   @return The current value of TSC
5531
5532 **/
5533 UINT64
5534 EFIAPI
5535 AsmReadTsc (
5536   VOID
5537   );
5538
5539
5540 /**
5541   Reads the current value of a Performance Counter (PMC).
5542
5543   Reads and returns the current value of performance counter specified by
5544   Index. This function is only available on IA-32 and X64.
5545
5546   @param  Index The 32-bit Performance Counter index to read.
5547
5548   @return The value of the PMC specified by Index.
5549
5550 **/
5551 UINT64
5552 EFIAPI
5553 AsmReadPmc (
5554   IN      UINT32                    Index
5555   );
5556
5557
5558 /**
5559   Sets up a monitor buffer that is used by AsmMwait().
5560
5561   Executes a MONITOR instruction with the register state specified by Eax, Ecx
5562   and Edx. Returns Eax. This function is only available on IA-32 and X64.
5563
5564   @param  Eax The value to load into EAX or RAX before executing the MONITOR
5565               instruction.
5566   @param  Ecx The value to load into ECX or RCX before executing the MONITOR
5567               instruction.
5568   @param  Edx The value to load into EDX or RDX before executing the MONITOR
5569               instruction.
5570
5571   @return Eax
5572
5573 **/
5574 UINTN
5575 EFIAPI
5576 AsmMonitor (
5577   IN      UINTN                     Eax,
5578   IN      UINTN                     Ecx,
5579   IN      UINTN                     Edx
5580   );
5581
5582
5583 /**
5584   Executes an MWAIT instruction.
5585
5586   Executes an MWAIT instruction with the register state specified by Eax and
5587   Ecx. Returns Eax. This function is only available on IA-32 and X64.
5588
5589   @param  Eax The value to load into EAX or RAX before executing the MONITOR
5590               instruction.
5591   @param  Ecx The value to load into ECX or RCX before executing the MONITOR
5592               instruction.
5593
5594   @return Eax
5595
5596 **/
5597 UINTN
5598 EFIAPI
5599 AsmMwait (
5600   IN      UINTN                     Eax,
5601   IN      UINTN                     Ecx
5602   );
5603
5604
5605 /**
5606   Executes a WBINVD instruction.
5607
5608   Executes a WBINVD instruction. This function is only available on IA-32 and
5609   X64.
5610
5611 **/
5612 VOID
5613 EFIAPI
5614 AsmWbinvd (
5615   VOID
5616   );
5617
5618
5619 /**
5620   Executes a INVD instruction.
5621
5622   Executes a INVD instruction. This function is only available on IA-32 and
5623   X64.
5624
5625 **/
5626 VOID
5627 EFIAPI
5628 AsmInvd (
5629   VOID
5630   );
5631
5632
5633 /**
5634   Flushes a cache line from all the instruction and data caches within the
5635   coherency domain of the CPU.
5636
5637   Flushed the cache line specified by LinearAddress, and returns LinearAddress.
5638   This function is only available on IA-32 and X64.
5639
5640   @param  LinearAddress The address of the cache line to flush. If the CPU is
5641                         in a physical addressing mode, then LinearAddress is a
5642                         physical address. If the CPU is in a virtual
5643                         addressing mode, then LinearAddress is a virtual
5644                         address.
5645
5646   @return LinearAddress
5647 **/
5648 VOID *
5649 EFIAPI
5650 AsmFlushCacheLine (
5651   IN      VOID                      *LinearAddress
5652   );
5653
5654
5655 /**
5656   Enables the 32-bit paging mode on the CPU.
5657
5658   Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
5659   must be properly initialized prior to calling this service. This function
5660   assumes the current execution mode is 32-bit protected mode. This function is
5661   only available on IA-32. After the 32-bit paging mode is enabled, control is
5662   transferred to the function specified by EntryPoint using the new stack
5663   specified by NewStack and passing in the parameters specified by Context1 and
5664   Context2. Context1 and Context2 are optional and may be NULL. The function
5665   EntryPoint must never return.
5666
5667   If the current execution mode is not 32-bit protected mode, then ASSERT().
5668   If EntryPoint is NULL, then ASSERT().
5669   If NewStack is NULL, then ASSERT().
5670
5671   There are a number of constraints that must be followed before calling this
5672   function:
5673   1)  Interrupts must be disabled.
5674   2)  The caller must be in 32-bit protected mode with flat descriptors. This
5675       means all descriptors must have a base of 0 and a limit of 4GB.
5676   3)  CR0 and CR4 must be compatible with 32-bit protected mode with flat
5677       descriptors.
5678   4)  CR3 must point to valid page tables that will be used once the transition
5679       is complete, and those page tables must guarantee that the pages for this
5680       function and the stack are identity mapped.
5681
5682   @param  EntryPoint  A pointer to function to call with the new stack after
5683                       paging is enabled.
5684   @param  Context1    A pointer to the context to pass into the EntryPoint
5685                       function as the first parameter after paging is enabled.
5686   @param  Context2    A pointer to the context to pass into the EntryPoint
5687                       function as the second parameter after paging is enabled.
5688   @param  NewStack    A pointer to the new stack to use for the EntryPoint
5689                       function after paging is enabled.
5690
5691 **/
5692 VOID
5693 EFIAPI
5694 AsmEnablePaging32 (
5695   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
5696   IN      VOID                      *Context1,  OPTIONAL
5697   IN      VOID                      *Context2,  OPTIONAL
5698   IN      VOID                      *NewStack
5699   );
5700
5701
5702 /**
5703   Disables the 32-bit paging mode on the CPU.
5704
5705   Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
5706   mode. This function assumes the current execution mode is 32-paged protected
5707   mode. This function is only available on IA-32. After the 32-bit paging mode
5708   is disabled, control is transferred to the function specified by EntryPoint
5709   using the new stack specified by NewStack and passing in the parameters
5710   specified by Context1 and Context2. Context1 and Context2 are optional and
5711   may be NULL. The function EntryPoint must never return.
5712
5713   If the current execution mode is not 32-bit paged mode, then ASSERT().
5714   If EntryPoint is NULL, then ASSERT().
5715   If NewStack is NULL, then ASSERT().
5716
5717   There are a number of constraints that must be followed before calling this
5718   function:
5719   1)  Interrupts must be disabled.
5720   2)  The caller must be in 32-bit paged mode.
5721   3)  CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
5722   4)  CR3 must point to valid page tables that guarantee that the pages for
5723       this function and the stack are identity mapped.
5724
5725   @param  EntryPoint  A pointer to function to call with the new stack after
5726                       paging is disabled.
5727   @param  Context1    A pointer to the context to pass into the EntryPoint
5728                       function as the first parameter after paging is disabled.
5729   @param  Context2    A pointer to the context to pass into the EntryPoint
5730                       function as the second parameter after paging is
5731                       disabled.
5732   @param  NewStack    A pointer to the new stack to use for the EntryPoint
5733                       function after paging is disabled.
5734
5735 **/
5736 VOID
5737 EFIAPI
5738 AsmDisablePaging32 (
5739   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
5740   IN      VOID                      *Context1,  OPTIONAL
5741   IN      VOID                      *Context2,  OPTIONAL
5742   IN      VOID                      *NewStack
5743   );
5744
5745
5746 /**
5747   Enables the 64-bit paging mode on the CPU.
5748
5749   Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
5750   must be properly initialized prior to calling this service. This function
5751   assumes the current execution mode is 32-bit protected mode with flat
5752   descriptors. This function is only available on IA-32. After the 64-bit
5753   paging mode is enabled, control is transferred to the function specified by
5754   EntryPoint using the new stack specified by NewStack and passing in the
5755   parameters specified by Context1 and Context2. Context1 and Context2 are
5756   optional and may be 0. The function EntryPoint must never return.
5757
5758   If the current execution mode is not 32-bit protected mode with flat
5759   descriptors, then ASSERT().
5760   If EntryPoint is 0, then ASSERT().
5761   If NewStack is 0, then ASSERT().
5762
5763   @param  Cs          The 16-bit selector to load in the CS before EntryPoint
5764                       is called. The descriptor in the GDT that this selector
5765                       references must be setup for long mode.
5766   @param  EntryPoint  The 64-bit virtual address of the function to call with
5767                       the new stack after paging is enabled.
5768   @param  Context1    The 64-bit virtual address of the context to pass into
5769                       the EntryPoint function as the first parameter after
5770                       paging is enabled.
5771   @param  Context2    The 64-bit virtual address of the context to pass into
5772                       the EntryPoint function as the second parameter after
5773                       paging is enabled.
5774   @param  NewStack    The 64-bit virtual address of the new stack to use for
5775                       the EntryPoint function after paging is enabled.
5776
5777 **/
5778 VOID
5779 EFIAPI
5780 AsmEnablePaging64 (
5781   IN      UINT16                    CodeSelector,
5782   IN      UINT64                    EntryPoint,
5783   IN      UINT64                    Context1,  OPTIONAL
5784   IN      UINT64                    Context2,  OPTIONAL
5785   IN      UINT64                    NewStack
5786   );
5787
5788
5789 /**
5790   Disables the 64-bit paging mode on the CPU.
5791
5792   Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
5793   mode. This function assumes the current execution mode is 64-paging mode.
5794   This function is only available on X64. After the 64-bit paging mode is
5795   disabled, control is transferred to the function specified by EntryPoint
5796   using the new stack specified by NewStack and passing in the parameters
5797   specified by Context1 and Context2. Context1 and Context2 are optional and
5798   may be 0. The function EntryPoint must never return.
5799
5800   If the current execution mode is not 64-bit paged mode, then ASSERT().
5801   If EntryPoint is 0, then ASSERT().
5802   If NewStack is 0, then ASSERT().
5803
5804   @param  Cs          The 16-bit selector to load in the CS before EntryPoint
5805                       is called. The descriptor in the GDT that this selector
5806                       references must be setup for 32-bit protected mode.
5807   @param  EntryPoint  The 64-bit virtual address of the function to call with
5808                       the new stack after paging is disabled.
5809   @param  Context1    The 64-bit virtual address of the context to pass into
5810                       the EntryPoint function as the first parameter after
5811                       paging is disabled.
5812   @param  Context2    The 64-bit virtual address of the context to pass into
5813                       the EntryPoint function as the second parameter after
5814                       paging is disabled.
5815   @param  NewStack    The 64-bit virtual address of the new stack to use for
5816                       the EntryPoint function after paging is disabled.
5817
5818 **/
5819 VOID
5820 EFIAPI
5821 AsmDisablePaging64 (
5822   IN      UINT16                    CodeSelector,
5823   IN      UINT32                    EntryPoint,
5824   IN      UINT32                    Context1,  OPTIONAL
5825   IN      UINT32                    Context2,  OPTIONAL
5826   IN      UINT32                    NewStack
5827   );
5828
5829
5830 //
5831 // 16-bit thunking services
5832 //
5833
5834 /**
5835   Retrieves the properties for 16-bit thunk functions.
5836
5837   Computes the size of the buffer and stack below 1MB required to use the
5838   AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
5839   buffer size is returned in RealModeBufferSize, and the stack size is returned
5840   in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
5841   then the actual minimum stack size is ExtraStackSize plus the maximum number
5842   of bytes that need to be passed to the 16-bit real mode code.
5843
5844   If RealModeBufferSize is NULL, then ASSERT().
5845   If ExtraStackSize is NULL, then ASSERT().
5846
5847   @param  RealModeBufferSize  A pointer to the size of the buffer below 1MB
5848                               required to use the 16-bit thunk functions.
5849   @param  ExtraStackSize      A pointer to the extra size of stack below 1MB
5850                               that the 16-bit thunk functions require for
5851                               temporary storage in the transition to and from
5852                               16-bit real mode.
5853
5854 **/
5855 VOID
5856 EFIAPI
5857 AsmGetThunk16Properties (
5858   OUT     UINT32                    *RealModeBufferSize,
5859   OUT     UINT32                    *ExtraStackSize
5860   );
5861
5862
5863 /**
5864   Prepares all structures a code required to use AsmThunk16().
5865
5866   Prepares all structures and code required to use AsmThunk16().
5867
5868   If ThunkContext is NULL, then ASSERT().
5869
5870   @param  ThunkContext  A pointer to the context structure that describes the
5871                         16-bit real mode code to call.
5872
5873 **/
5874 VOID
5875 EFIAPI
5876 AsmPrepareThunk16 (
5877   OUT     THUNK_CONTEXT             *ThunkContext
5878   );
5879
5880
5881 /**
5882   Transfers control to a 16-bit real mode entry point and returns the results.
5883
5884   Transfers control to a 16-bit real mode entry point and returns the results.
5885   AsmPrepareThunk16() must be called with ThunkContext before this function is
5886   used.
5887
5888   If ThunkContext is NULL, then ASSERT().
5889   If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
5890
5891   @param  ThunkContext  A pointer to the context structure that describes the
5892                         16-bit real mode code to call.
5893
5894 **/
5895 VOID
5896 EFIAPI
5897 AsmThunk16 (
5898   IN OUT  THUNK_CONTEXT             *ThunkContext
5899   );
5900
5901
5902 /**
5903   Prepares all structures and code for a 16-bit real mode thunk, transfers
5904   control to a 16-bit real mode entry point, and returns the results.
5905
5906   Prepares all structures and code for a 16-bit real mode thunk, transfers
5907   control to a 16-bit real mode entry point, and returns the results. If the
5908   caller only need to perform a single 16-bit real mode thunk, then this
5909   service should be used. If the caller intends to make more than one 16-bit
5910   real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
5911   once and AsmThunk16() can be called for each 16-bit real mode thunk.
5912
5913   If ThunkContext is NULL, then ASSERT().
5914
5915   @param  ThunkContext  A pointer to the context structure that describes the
5916                         16-bit real mode code to call.
5917
5918 **/
5919 VOID
5920 EFIAPI
5921 AsmPrepareAndThunk16 (
5922   IN OUT  THUNK_CONTEXT             *ThunkContext
5923   );
5924
5925 #else
5926
5927 #endif
5928
5929 #endif