iPXE
BaseLib.h
Go to the documentation of this file.
00001 /** @file
00002   Provides string functions, linked list functions, math functions, synchronization
00003   functions, file path functions, and CPU architecture-specific functions.
00004 
00005 Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>
00006 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
00007 This program and the accompanying materials
00008 are licensed and made available under the terms and conditions of the BSD License
00009 which accompanies this distribution.  The full text of the license may be found at
00010 http://opensource.org/licenses/bsd-license.php.
00011 
00012 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00013 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00014 
00015 **/
00016 
00017 #ifndef __BASE_LIB__
00018 #define __BASE_LIB__
00019 
00020 FILE_LICENCE ( BSD3 );
00021 
00022 //
00023 // Definitions for architecture-specific types
00024 //
00025 #if   defined (MDE_CPU_IA32)
00026 ///
00027 /// The IA-32 architecture context buffer used by SetJump() and LongJump().
00028 ///
00029 typedef struct {
00030   UINT32                            Ebx;
00031   UINT32                            Esi;
00032   UINT32                            Edi;
00033   UINT32                            Ebp;
00034   UINT32                            Esp;
00035   UINT32                            Eip;
00036 } BASE_LIBRARY_JUMP_BUFFER;
00037 
00038 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
00039 
00040 #endif // defined (MDE_CPU_IA32)
00041 
00042 #if defined (MDE_CPU_IPF)
00043 
00044 ///
00045 /// The Itanium architecture context buffer used by SetJump() and LongJump().
00046 ///
00047 typedef struct {
00048   UINT64                            F2[2];
00049   UINT64                            F3[2];
00050   UINT64                            F4[2];
00051   UINT64                            F5[2];
00052   UINT64                            F16[2];
00053   UINT64                            F17[2];
00054   UINT64                            F18[2];
00055   UINT64                            F19[2];
00056   UINT64                            F20[2];
00057   UINT64                            F21[2];
00058   UINT64                            F22[2];
00059   UINT64                            F23[2];
00060   UINT64                            F24[2];
00061   UINT64                            F25[2];
00062   UINT64                            F26[2];
00063   UINT64                            F27[2];
00064   UINT64                            F28[2];
00065   UINT64                            F29[2];
00066   UINT64                            F30[2];
00067   UINT64                            F31[2];
00068   UINT64                            R4;
00069   UINT64                            R5;
00070   UINT64                            R6;
00071   UINT64                            R7;
00072   UINT64                            SP;
00073   UINT64                            BR0;
00074   UINT64                            BR1;
00075   UINT64                            BR2;
00076   UINT64                            BR3;
00077   UINT64                            BR4;
00078   UINT64                            BR5;
00079   UINT64                            InitialUNAT;
00080   UINT64                            AfterSpillUNAT;
00081   UINT64                            PFS;
00082   UINT64                            BSP;
00083   UINT64                            Predicates;
00084   UINT64                            LoopCount;
00085   UINT64                            FPSR;
00086 } BASE_LIBRARY_JUMP_BUFFER;
00087 
00088 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 0x10
00089 
00090 #endif // defined (MDE_CPU_IPF)
00091 
00092 #if defined (MDE_CPU_X64)
00093 ///
00094 /// The x64 architecture context buffer used by SetJump() and LongJump().
00095 ///
00096 typedef struct {
00097   UINT64                            Rbx;
00098   UINT64                            Rsp;
00099   UINT64                            Rbp;
00100   UINT64                            Rdi;
00101   UINT64                            Rsi;
00102   UINT64                            R12;
00103   UINT64                            R13;
00104   UINT64                            R14;
00105   UINT64                            R15;
00106   UINT64                            Rip;
00107   UINT64                            MxCsr;
00108   UINT8                             XmmBuffer[160]; ///< XMM6-XMM15.
00109 } BASE_LIBRARY_JUMP_BUFFER;
00110 
00111 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
00112 
00113 #endif // defined (MDE_CPU_X64)
00114 
00115 #if defined (MDE_CPU_EBC)
00116 ///
00117 /// The EBC context buffer used by SetJump() and LongJump().
00118 ///
00119 typedef struct {
00120   UINT64                            R0;
00121   UINT64                            R1;
00122   UINT64                            R2;
00123   UINT64                            R3;
00124   UINT64                            IP;
00125 } BASE_LIBRARY_JUMP_BUFFER;
00126 
00127 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
00128 
00129 #endif // defined (MDE_CPU_EBC)
00130 
00131 #if defined (MDE_CPU_ARM)
00132 
00133 typedef struct {
00134   UINT32    R3;  ///< A copy of R13.
00135   UINT32    R4;
00136   UINT32    R5;
00137   UINT32    R6;
00138   UINT32    R7;
00139   UINT32    R8;
00140   UINT32    R9;
00141   UINT32    R10;
00142   UINT32    R11;
00143   UINT32    R12;
00144   UINT32    R14;
00145 } BASE_LIBRARY_JUMP_BUFFER;
00146 
00147 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
00148 
00149 #endif  // defined (MDE_CPU_ARM)
00150 
00151 #if defined (MDE_CPU_AARCH64)
00152 typedef struct {
00153   // GP regs
00154   UINT64    X19;
00155   UINT64    X20;
00156   UINT64    X21;
00157   UINT64    X22;
00158   UINT64    X23;
00159   UINT64    X24;
00160   UINT64    X25;
00161   UINT64    X26;
00162   UINT64    X27;
00163   UINT64    X28;
00164   UINT64    FP;
00165   UINT64    LR;
00166   UINT64    IP0;
00167 
00168   // FP regs
00169   UINT64    D8;
00170   UINT64    D9;
00171   UINT64    D10;
00172   UINT64    D11;
00173   UINT64    D12;
00174   UINT64    D13;
00175   UINT64    D14;
00176   UINT64    D15;
00177 } BASE_LIBRARY_JUMP_BUFFER;
00178 
00179 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
00180 
00181 #endif  // defined (MDE_CPU_AARCH64)
00182 
00183 
00184 //
00185 // String Services
00186 //
00187 
00188 
00189 /**
00190   Returns the length of a Null-terminated Unicode string.
00191 
00192   This function is similar as strlen_s defined in C11.
00193 
00194   If String is not aligned on a 16-bit boundary, then ASSERT().
00195 
00196   @param  String   A pointer to a Null-terminated Unicode string.
00197   @param  MaxSize  The maximum number of Destination Unicode
00198                    char, including terminating null char.
00199 
00200   @retval 0        If String is NULL.
00201   @retval MaxSize  If there is no null character in the first MaxSize characters of String.
00202   @return The number of characters that percede the terminating null character.
00203 
00204 **/
00205 UINTN
00206 EFIAPI
00207 StrnLenS (
00208   IN CONST CHAR16              *String,
00209   IN UINTN                     MaxSize
00210   );
00211 
00212 /**
00213   Returns the size of a Null-terminated Unicode string in bytes, including the
00214   Null terminator.
00215 
00216   This function returns the size of the Null-terminated Unicode string
00217   specified by String in bytes, including the Null terminator.
00218 
00219   If String is not aligned on a 16-bit boundary, then ASSERT().
00220 
00221   @param  String   A pointer to a Null-terminated Unicode string.
00222   @param  MaxSize  The maximum number of Destination Unicode
00223                    char, including the Null terminator.
00224 
00225   @retval 0  If String is NULL.
00226   @retval (sizeof (CHAR16) * (MaxSize + 1))
00227              If there is no Null terminator in the first MaxSize characters of
00228              String.
00229   @return The size of the Null-terminated Unicode string in bytes, including
00230           the Null terminator.
00231 
00232 **/
00233 UINTN
00234 EFIAPI
00235 StrnSizeS (
00236   IN CONST CHAR16              *String,
00237   IN UINTN                     MaxSize
00238   );
00239 
00240 /**
00241   Copies the string pointed to by Source (including the terminating null char)
00242   to the array pointed to by Destination.
00243 
00244   This function is similar as strcpy_s defined in C11.
00245 
00246   If Destination is not aligned on a 16-bit boundary, then ASSERT().
00247   If Source is not aligned on a 16-bit boundary, then ASSERT().
00248   If an error would be returned, then the function will also ASSERT().
00249 
00250   If an error is returned, then the Destination is unmodified.
00251 
00252   @param  Destination              A pointer to a Null-terminated Unicode string.
00253   @param  DestMax                  The maximum number of Destination Unicode
00254                                    char, including terminating null char.
00255   @param  Source                   A pointer to a Null-terminated Unicode string.
00256 
00257   @retval RETURN_SUCCESS           String is copied.
00258   @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than StrLen(Source).
00259   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
00260                                    If Source is NULL.
00261                                    If PcdMaximumUnicodeStringLength is not zero,
00262                                     and DestMax is greater than
00263                                     PcdMaximumUnicodeStringLength.
00264                                    If DestMax is 0.
00265   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
00266 **/
00267 RETURN_STATUS
00268 EFIAPI
00269 StrCpyS (
00270   OUT CHAR16       *Destination,
00271   IN  UINTN        DestMax,
00272   IN  CONST CHAR16 *Source
00273   );
00274 
00275 /**
00276   Copies not more than Length successive char from the string pointed to by
00277   Source to the array pointed to by Destination. If no null char is copied from
00278   Source, then Destination[Length] is always set to null.
00279 
00280   This function is similar as strncpy_s defined in C11.
00281 
00282   If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
00283   If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
00284   If an error would be returned, then the function will also ASSERT().
00285 
00286   If an error is returned, then the Destination is unmodified.
00287 
00288   @param  Destination              A pointer to a Null-terminated Unicode string.
00289   @param  DestMax                  The maximum number of Destination Unicode
00290                                    char, including terminating null char.
00291   @param  Source                   A pointer to a Null-terminated Unicode string.
00292   @param  Length                   The maximum number of Unicode characters to copy.
00293 
00294   @retval RETURN_SUCCESS           String is copied.
00295   @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than
00296                                    MIN(StrLen(Source), Length).
00297   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
00298                                    If Source is NULL.
00299                                    If PcdMaximumUnicodeStringLength is not zero,
00300                                     and DestMax is greater than
00301                                     PcdMaximumUnicodeStringLength.
00302                                    If DestMax is 0.
00303   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
00304 **/
00305 RETURN_STATUS
00306 EFIAPI
00307 StrnCpyS (
00308   OUT CHAR16       *Destination,
00309   IN  UINTN        DestMax,
00310   IN  CONST CHAR16 *Source,
00311   IN  UINTN        Length
00312   );
00313 
00314 /**
00315   Appends a copy of the string pointed to by Source (including the terminating
00316   null char) to the end of the string pointed to by Destination.
00317 
00318   This function is similar as strcat_s defined in C11.
00319 
00320   If Destination is not aligned on a 16-bit boundary, then ASSERT().
00321   If Source is not aligned on a 16-bit boundary, then ASSERT().
00322   If an error would be returned, then the function will also ASSERT().
00323 
00324   If an error is returned, then the Destination is unmodified.
00325 
00326   @param  Destination              A pointer to a Null-terminated Unicode string.
00327   @param  DestMax                  The maximum number of Destination Unicode
00328                                    char, including terminating null char.
00329   @param  Source                   A pointer to a Null-terminated Unicode string.
00330 
00331   @retval RETURN_SUCCESS           String is appended.
00332   @retval RETURN_BAD_BUFFER_SIZE   If DestMax is NOT greater than
00333                                    StrLen(Destination).
00334   @retval RETURN_BUFFER_TOO_SMALL  If (DestMax - StrLen(Destination)) is NOT
00335                                    greater than StrLen(Source).
00336   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
00337                                    If Source is NULL.
00338                                    If PcdMaximumUnicodeStringLength is not zero,
00339                                     and DestMax is greater than
00340                                     PcdMaximumUnicodeStringLength.
00341                                    If DestMax is 0.
00342   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
00343 **/
00344 RETURN_STATUS
00345 EFIAPI
00346 StrCatS (
00347   IN OUT CHAR16       *Destination,
00348   IN     UINTN        DestMax,
00349   IN     CONST CHAR16 *Source
00350   );
00351 
00352 /**
00353   Appends not more than Length successive char from the string pointed to by
00354   Source to the end of the string pointed to by Destination. If no null char is
00355   copied from Source, then Destination[StrLen(Destination) + Length] is always
00356   set to null.
00357 
00358   This function is similar as strncat_s defined in C11.
00359 
00360   If Destination is not aligned on a 16-bit boundary, then ASSERT().
00361   If Source is not aligned on a 16-bit boundary, then ASSERT().
00362   If an error would be returned, then the function will also ASSERT().
00363 
00364   If an error is returned, then the Destination is unmodified.
00365 
00366   @param  Destination              A pointer to a Null-terminated Unicode string.
00367   @param  DestMax                  The maximum number of Destination Unicode
00368                                    char, including terminating null char.
00369   @param  Source                   A pointer to a Null-terminated Unicode string.
00370   @param  Length                   The maximum number of Unicode characters to copy.
00371 
00372   @retval RETURN_SUCCESS           String is appended.
00373   @retval RETURN_BAD_BUFFER_SIZE   If DestMax is NOT greater than
00374                                    StrLen(Destination).
00375   @retval RETURN_BUFFER_TOO_SMALL  If (DestMax - StrLen(Destination)) is NOT
00376                                    greater than MIN(StrLen(Source), Length).
00377   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
00378                                    If Source is NULL.
00379                                    If PcdMaximumUnicodeStringLength is not zero,
00380                                     and DestMax is greater than
00381                                     PcdMaximumUnicodeStringLength.
00382                                    If DestMax is 0.
00383   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
00384 **/
00385 RETURN_STATUS
00386 EFIAPI
00387 StrnCatS (
00388   IN OUT CHAR16       *Destination,
00389   IN     UINTN        DestMax,
00390   IN     CONST CHAR16 *Source,
00391   IN     UINTN        Length
00392   );
00393 
00394 /**
00395   Convert a Null-terminated Unicode decimal string to a value of type UINTN.
00396 
00397   This function outputs a value of type UINTN by interpreting the contents of
00398   the Unicode string specified by String as a decimal number. The format of the
00399   input Unicode string String is:
00400 
00401                   [spaces] [decimal digits].
00402 
00403   The valid decimal digit character is in the range [0-9]. The function will
00404   ignore the pad space, which includes spaces or tab characters, before
00405   [decimal digits]. The running zero in the beginning of [decimal digits] will
00406   be ignored. Then, the function stops at the first character that is a not a
00407   valid decimal character or a Null-terminator, whichever one comes first.
00408 
00409   If String is NULL, then ASSERT().
00410   If Data is NULL, then ASSERT().
00411   If String is not aligned in a 16-bit boundary, then ASSERT().
00412   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
00413   PcdMaximumUnicodeStringLength Unicode characters, not including the
00414   Null-terminator, then ASSERT().
00415 
00416   If String has no valid decimal digits in the above format, then 0 is stored
00417   at the location pointed to by Data.
00418   If the number represented by String exceeds the range defined by UINTN, then
00419   MAX_UINTN is stored at the location pointed to by Data.
00420 
00421   If EndPointer is not NULL, a pointer to the character that stopped the scan
00422   is stored at the location pointed to by EndPointer. If String has no valid
00423   decimal digits right after the optional pad spaces, the value of String is
00424   stored at the location pointed to by EndPointer.
00425 
00426   @param  String                   Pointer to a Null-terminated Unicode string.
00427   @param  EndPointer               Pointer to character that stops scan.
00428   @param  Data                     Pointer to the converted value.
00429 
00430   @retval RETURN_SUCCESS           Value is translated from String.
00431   @retval RETURN_INVALID_PARAMETER If String is NULL.
00432                                    If Data is NULL.
00433                                    If PcdMaximumUnicodeStringLength is not
00434                                    zero, and String contains more than
00435                                    PcdMaximumUnicodeStringLength Unicode
00436                                    characters, not including the
00437                                    Null-terminator.
00438   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
00439                                    the range defined by UINTN.
00440 
00441 **/
00442 RETURN_STATUS
00443 EFIAPI
00444 StrDecimalToUintnS (
00445   IN  CONST CHAR16             *String,
00446   OUT       CHAR16             **EndPointer,  OPTIONAL
00447   OUT       UINTN              *Data
00448   );
00449 
00450 /**
00451   Convert a Null-terminated Unicode decimal string to a value of type UINT64.
00452 
00453   This function outputs a value of type UINT64 by interpreting the contents of
00454   the Unicode string specified by String as a decimal number. The format of the
00455   input Unicode string String is:
00456 
00457                   [spaces] [decimal digits].
00458 
00459   The valid decimal digit character is in the range [0-9]. The function will
00460   ignore the pad space, which includes spaces or tab characters, before
00461   [decimal digits]. The running zero in the beginning of [decimal digits] will
00462   be ignored. Then, the function stops at the first character that is a not a
00463   valid decimal character or a Null-terminator, whichever one comes first.
00464 
00465   If String is NULL, then ASSERT().
00466   If Data is NULL, then ASSERT().
00467   If String is not aligned in a 16-bit boundary, then ASSERT().
00468   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
00469   PcdMaximumUnicodeStringLength Unicode characters, not including the
00470   Null-terminator, then ASSERT().
00471 
00472   If String has no valid decimal digits in the above format, then 0 is stored
00473   at the location pointed to by Data.
00474   If the number represented by String exceeds the range defined by UINT64, then
00475   MAX_UINT64 is stored at the location pointed to by Data.
00476 
00477   If EndPointer is not NULL, a pointer to the character that stopped the scan
00478   is stored at the location pointed to by EndPointer. If String has no valid
00479   decimal digits right after the optional pad spaces, the value of String is
00480   stored at the location pointed to by EndPointer.
00481 
00482   @param  String                   Pointer to a Null-terminated Unicode string.
00483   @param  EndPointer               Pointer to character that stops scan.
00484   @param  Data                     Pointer to the converted value.
00485 
00486   @retval RETURN_SUCCESS           Value is translated from String.
00487   @retval RETURN_INVALID_PARAMETER If String is NULL.
00488                                    If Data is NULL.
00489                                    If PcdMaximumUnicodeStringLength is not
00490                                    zero, and String contains more than
00491                                    PcdMaximumUnicodeStringLength Unicode
00492                                    characters, not including the
00493                                    Null-terminator.
00494   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
00495                                    the range defined by UINT64.
00496 
00497 **/
00498 RETURN_STATUS
00499 EFIAPI
00500 StrDecimalToUint64S (
00501   IN  CONST CHAR16             *String,
00502   OUT       CHAR16             **EndPointer,  OPTIONAL
00503   OUT       UINT64             *Data
00504   );
00505 
00506 /**
00507   Convert a Null-terminated Unicode hexadecimal string to a value of type
00508   UINTN.
00509 
00510   This function outputs a value of type UINTN by interpreting the contents of
00511   the Unicode string specified by String as a hexadecimal number. The format of
00512   the input Unicode string String is:
00513 
00514                   [spaces][zeros][x][hexadecimal digits].
00515 
00516   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
00517   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
00518   If "x" appears in the input string, it must be prefixed with at least one 0.
00519   The function will ignore the pad space, which includes spaces or tab
00520   characters, before [zeros], [x] or [hexadecimal digit]. The running zero
00521   before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
00522   after [x] or the first valid hexadecimal digit. Then, the function stops at
00523   the first character that is a not a valid hexadecimal character or NULL,
00524   whichever one comes first.
00525 
00526   If String is NULL, then ASSERT().
00527   If Data is NULL, then ASSERT().
00528   If String is not aligned in a 16-bit boundary, then ASSERT().
00529   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
00530   PcdMaximumUnicodeStringLength Unicode characters, not including the
00531   Null-terminator, then ASSERT().
00532 
00533   If String has no valid hexadecimal digits in the above format, then 0 is
00534   stored at the location pointed to by Data.
00535   If the number represented by String exceeds the range defined by UINTN, then
00536   MAX_UINTN is stored at the location pointed to by Data.
00537 
00538   If EndPointer is not NULL, a pointer to the character that stopped the scan
00539   is stored at the location pointed to by EndPointer. If String has no valid
00540   hexadecimal digits right after the optional pad spaces, the value of String
00541   is stored at the location pointed to by EndPointer.
00542 
00543   @param  String                   Pointer to a Null-terminated Unicode string.
00544   @param  EndPointer               Pointer to character that stops scan.
00545   @param  Data                     Pointer to the converted value.
00546 
00547   @retval RETURN_SUCCESS           Value is translated from String.
00548   @retval RETURN_INVALID_PARAMETER If String is NULL.
00549                                    If Data is NULL.
00550                                    If PcdMaximumUnicodeStringLength is not
00551                                    zero, and String contains more than
00552                                    PcdMaximumUnicodeStringLength Unicode
00553                                    characters, not including the
00554                                    Null-terminator.
00555   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
00556                                    the range defined by UINTN.
00557 
00558 **/
00559 RETURN_STATUS
00560 EFIAPI
00561 StrHexToUintnS (
00562   IN  CONST CHAR16             *String,
00563   OUT       CHAR16             **EndPointer,  OPTIONAL
00564   OUT       UINTN              *Data
00565   );
00566 
00567 /**
00568   Convert a Null-terminated Unicode hexadecimal string to a value of type
00569   UINT64.
00570 
00571   This function outputs a value of type UINT64 by interpreting the contents of
00572   the Unicode string specified by String as a hexadecimal number. The format of
00573   the input Unicode string String is:
00574 
00575                   [spaces][zeros][x][hexadecimal digits].
00576 
00577   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
00578   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
00579   If "x" appears in the input string, it must be prefixed with at least one 0.
00580   The function will ignore the pad space, which includes spaces or tab
00581   characters, before [zeros], [x] or [hexadecimal digit]. The running zero
00582   before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
00583   after [x] or the first valid hexadecimal digit. Then, the function stops at
00584   the first character that is a not a valid hexadecimal character or NULL,
00585   whichever one comes first.
00586 
00587   If String is NULL, then ASSERT().
00588   If Data is NULL, then ASSERT().
00589   If String is not aligned in a 16-bit boundary, then ASSERT().
00590   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
00591   PcdMaximumUnicodeStringLength Unicode characters, not including the
00592   Null-terminator, then ASSERT().
00593 
00594   If String has no valid hexadecimal digits in the above format, then 0 is
00595   stored at the location pointed to by Data.
00596   If the number represented by String exceeds the range defined by UINT64, then
00597   MAX_UINT64 is stored at the location pointed to by Data.
00598 
00599   If EndPointer is not NULL, a pointer to the character that stopped the scan
00600   is stored at the location pointed to by EndPointer. If String has no valid
00601   hexadecimal digits right after the optional pad spaces, the value of String
00602   is stored at the location pointed to by EndPointer.
00603 
00604   @param  String                   Pointer to a Null-terminated Unicode string.
00605   @param  EndPointer               Pointer to character that stops scan.
00606   @param  Data                     Pointer to the converted value.
00607 
00608   @retval RETURN_SUCCESS           Value is translated from String.
00609   @retval RETURN_INVALID_PARAMETER If String is NULL.
00610                                    If Data is NULL.
00611                                    If PcdMaximumUnicodeStringLength is not
00612                                    zero, and String contains more than
00613                                    PcdMaximumUnicodeStringLength Unicode
00614                                    characters, not including the
00615                                    Null-terminator.
00616   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
00617                                    the range defined by UINT64.
00618 
00619 **/
00620 RETURN_STATUS
00621 EFIAPI
00622 StrHexToUint64S (
00623   IN  CONST CHAR16             *String,
00624   OUT       CHAR16             **EndPointer,  OPTIONAL
00625   OUT       UINT64             *Data
00626   );
00627 
00628 /**
00629   Returns the length of a Null-terminated Ascii string.
00630 
00631   This function is similar as strlen_s defined in C11.
00632 
00633   @param  String   A pointer to a Null-terminated Ascii string.
00634   @param  MaxSize  The maximum number of Destination Ascii
00635                    char, including terminating null char.
00636 
00637   @retval 0        If String is NULL.
00638   @retval MaxSize  If there is no null character in the first MaxSize characters of String.
00639   @return The number of characters that percede the terminating null character.
00640 
00641 **/
00642 UINTN
00643 EFIAPI
00644 AsciiStrnLenS (
00645   IN CONST CHAR8               *String,
00646   IN UINTN                     MaxSize
00647   );
00648 
00649 /**
00650   Returns the size of a Null-terminated Ascii string in bytes, including the
00651   Null terminator.
00652 
00653   This function returns the size of the Null-terminated Ascii string specified
00654   by String in bytes, including the Null terminator.
00655 
00656   @param  String   A pointer to a Null-terminated Ascii string.
00657   @param  MaxSize  The maximum number of Destination Ascii
00658                    char, including the Null terminator.
00659 
00660   @retval 0  If String is NULL.
00661   @retval (sizeof (CHAR8) * (MaxSize + 1))
00662              If there is no Null terminator in the first MaxSize characters of
00663              String.
00664   @return The size of the Null-terminated Ascii string in bytes, including the
00665           Null terminator.
00666 
00667 **/
00668 UINTN
00669 EFIAPI
00670 AsciiStrnSizeS (
00671   IN CONST CHAR8               *String,
00672   IN UINTN                     MaxSize
00673   );
00674 
00675 /**
00676   Copies the string pointed to by Source (including the terminating null char)
00677   to the array pointed to by Destination.
00678 
00679   This function is similar as strcpy_s defined in C11.
00680 
00681   If an error would be returned, then the function will also ASSERT().
00682 
00683   If an error is returned, then the Destination is unmodified.
00684 
00685   @param  Destination              A pointer to a Null-terminated Ascii string.
00686   @param  DestMax                  The maximum number of Destination Ascii
00687                                    char, including terminating null char.
00688   @param  Source                   A pointer to a Null-terminated Ascii string.
00689 
00690   @retval RETURN_SUCCESS           String is copied.
00691   @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than StrLen(Source).
00692   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
00693                                    If Source is NULL.
00694                                    If PcdMaximumAsciiStringLength is not zero,
00695                                     and DestMax is greater than
00696                                     PcdMaximumAsciiStringLength.
00697                                    If DestMax is 0.
00698   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
00699 **/
00700 RETURN_STATUS
00701 EFIAPI
00702 AsciiStrCpyS (
00703   OUT CHAR8        *Destination,
00704   IN  UINTN        DestMax,
00705   IN  CONST CHAR8  *Source
00706   );
00707 
00708 /**
00709   Copies not more than Length successive char from the string pointed to by
00710   Source to the array pointed to by Destination. If no null char is copied from
00711   Source, then Destination[Length] is always set to null.
00712 
00713   This function is similar as strncpy_s defined in C11.
00714 
00715   If an error would be returned, then the function will also ASSERT().
00716 
00717   If an error is returned, then the Destination is unmodified.
00718 
00719   @param  Destination              A pointer to a Null-terminated Ascii string.
00720   @param  DestMax                  The maximum number of Destination Ascii
00721                                    char, including terminating null char.
00722   @param  Source                   A pointer to a Null-terminated Ascii string.
00723   @param  Length                   The maximum number of Ascii characters to copy.
00724 
00725   @retval RETURN_SUCCESS           String is copied.
00726   @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than
00727                                    MIN(StrLen(Source), Length).
00728   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
00729                                    If Source is NULL.
00730                                    If PcdMaximumAsciiStringLength is not zero,
00731                                     and DestMax is greater than
00732                                     PcdMaximumAsciiStringLength.
00733                                    If DestMax is 0.
00734   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
00735 **/
00736 RETURN_STATUS
00737 EFIAPI
00738 AsciiStrnCpyS (
00739   OUT CHAR8        *Destination,
00740   IN  UINTN        DestMax,
00741   IN  CONST CHAR8  *Source,
00742   IN  UINTN        Length
00743   );
00744 
00745 /**
00746   Appends a copy of the string pointed to by Source (including the terminating
00747   null char) to the end of the string pointed to by Destination.
00748 
00749   This function is similar as strcat_s defined in C11.
00750 
00751   If an error would be returned, then the function will also ASSERT().
00752 
00753   If an error is returned, then the Destination is unmodified.
00754 
00755   @param  Destination              A pointer to a Null-terminated Ascii string.
00756   @param  DestMax                  The maximum number of Destination Ascii
00757                                    char, including terminating null char.
00758   @param  Source                   A pointer to a Null-terminated Ascii string.
00759 
00760   @retval RETURN_SUCCESS           String is appended.
00761   @retval RETURN_BAD_BUFFER_SIZE   If DestMax is NOT greater than
00762                                    StrLen(Destination).
00763   @retval RETURN_BUFFER_TOO_SMALL  If (DestMax - StrLen(Destination)) is NOT
00764                                    greater than StrLen(Source).
00765   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
00766                                    If Source is NULL.
00767                                    If PcdMaximumAsciiStringLength is not zero,
00768                                     and DestMax is greater than
00769                                     PcdMaximumAsciiStringLength.
00770                                    If DestMax is 0.
00771   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
00772 **/
00773 RETURN_STATUS
00774 EFIAPI
00775 AsciiStrCatS (
00776   IN OUT CHAR8        *Destination,
00777   IN     UINTN        DestMax,
00778   IN     CONST CHAR8  *Source
00779   );
00780 
00781 /**
00782   Appends not more than Length successive char from the string pointed to by
00783   Source to the end of the string pointed to by Destination. If no null char is
00784   copied from Source, then Destination[StrLen(Destination) + Length] is always
00785   set to null.
00786 
00787   This function is similar as strncat_s defined in C11.
00788 
00789   If an error would be returned, then the function will also ASSERT().
00790 
00791   If an error is returned, then the Destination is unmodified.
00792 
00793   @param  Destination              A pointer to a Null-terminated Ascii string.
00794   @param  DestMax                  The maximum number of Destination Ascii
00795                                    char, including terminating null char.
00796   @param  Source                   A pointer to a Null-terminated Ascii string.
00797   @param  Length                   The maximum number of Ascii characters to copy.
00798 
00799   @retval RETURN_SUCCESS           String is appended.
00800   @retval RETURN_BAD_BUFFER_SIZE   If DestMax is NOT greater than
00801                                    StrLen(Destination).
00802   @retval RETURN_BUFFER_TOO_SMALL  If (DestMax - StrLen(Destination)) is NOT
00803                                    greater than MIN(StrLen(Source), Length).
00804   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
00805                                    If Source is NULL.
00806                                    If PcdMaximumAsciiStringLength is not zero,
00807                                     and DestMax is greater than
00808                                     PcdMaximumAsciiStringLength.
00809                                    If DestMax is 0.
00810   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
00811 **/
00812 RETURN_STATUS
00813 EFIAPI
00814 AsciiStrnCatS (
00815   IN OUT CHAR8        *Destination,
00816   IN     UINTN        DestMax,
00817   IN     CONST CHAR8  *Source,
00818   IN     UINTN        Length
00819   );
00820 
00821 /**
00822   Convert a Null-terminated Ascii decimal string to a value of type UINTN.
00823 
00824   This function outputs a value of type UINTN by interpreting the contents of
00825   the Ascii string specified by String as a decimal number. The format of the
00826   input Ascii string String is:
00827 
00828                   [spaces] [decimal digits].
00829 
00830   The valid decimal digit character is in the range [0-9]. The function will
00831   ignore the pad space, which includes spaces or tab characters, before
00832   [decimal digits]. The running zero in the beginning of [decimal digits] will
00833   be ignored. Then, the function stops at the first character that is a not a
00834   valid decimal character or a Null-terminator, whichever one comes first.
00835 
00836   If String is NULL, then ASSERT().
00837   If Data is NULL, then ASSERT().
00838   If PcdMaximumAsciiStringLength is not zero, and String contains more than
00839   PcdMaximumAsciiStringLength Ascii characters, not including the
00840   Null-terminator, then ASSERT().
00841 
00842   If String has no valid decimal digits in the above format, then 0 is stored
00843   at the location pointed to by Data.
00844   If the number represented by String exceeds the range defined by UINTN, then
00845   MAX_UINTN is stored at the location pointed to by Data.
00846 
00847   If EndPointer is not NULL, a pointer to the character that stopped the scan
00848   is stored at the location pointed to by EndPointer. If String has no valid
00849   decimal digits right after the optional pad spaces, the value of String is
00850   stored at the location pointed to by EndPointer.
00851 
00852   @param  String                   Pointer to a Null-terminated Ascii string.
00853   @param  EndPointer               Pointer to character that stops scan.
00854   @param  Data                     Pointer to the converted value.
00855 
00856   @retval RETURN_SUCCESS           Value is translated from String.
00857   @retval RETURN_INVALID_PARAMETER If String is NULL.
00858                                    If Data is NULL.
00859                                    If PcdMaximumAsciiStringLength is not zero,
00860                                    and String contains more than
00861                                    PcdMaximumAsciiStringLength Ascii
00862                                    characters, not including the
00863                                    Null-terminator.
00864   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
00865                                    the range defined by UINTN.
00866 
00867 **/
00868 RETURN_STATUS
00869 EFIAPI
00870 AsciiStrDecimalToUintnS (
00871   IN  CONST CHAR8              *String,
00872   OUT       CHAR8              **EndPointer,  OPTIONAL
00873   OUT       UINTN              *Data
00874   );
00875 
00876 /**
00877   Convert a Null-terminated Ascii decimal string to a value of type UINT64.
00878 
00879   This function outputs a value of type UINT64 by interpreting the contents of
00880   the Ascii string specified by String as a decimal number. The format of the
00881   input Ascii string String is:
00882 
00883                   [spaces] [decimal digits].
00884 
00885   The valid decimal digit character is in the range [0-9]. The function will
00886   ignore the pad space, which includes spaces or tab characters, before
00887   [decimal digits]. The running zero in the beginning of [decimal digits] will
00888   be ignored. Then, the function stops at the first character that is a not a
00889   valid decimal character or a Null-terminator, whichever one comes first.
00890 
00891   If String is NULL, then ASSERT().
00892   If Data is NULL, then ASSERT().
00893   If PcdMaximumAsciiStringLength is not zero, and String contains more than
00894   PcdMaximumAsciiStringLength Ascii characters, not including the
00895   Null-terminator, then ASSERT().
00896 
00897   If String has no valid decimal digits in the above format, then 0 is stored
00898   at the location pointed to by Data.
00899   If the number represented by String exceeds the range defined by UINT64, then
00900   MAX_UINT64 is stored at the location pointed to by Data.
00901 
00902   If EndPointer is not NULL, a pointer to the character that stopped the scan
00903   is stored at the location pointed to by EndPointer. If String has no valid
00904   decimal digits right after the optional pad spaces, the value of String is
00905   stored at the location pointed to by EndPointer.
00906 
00907   @param  String                   Pointer to a Null-terminated Ascii string.
00908   @param  EndPointer               Pointer to character that stops scan.
00909   @param  Data                     Pointer to the converted value.
00910 
00911   @retval RETURN_SUCCESS           Value is translated from String.
00912   @retval RETURN_INVALID_PARAMETER If String is NULL.
00913                                    If Data is NULL.
00914                                    If PcdMaximumAsciiStringLength is not zero,
00915                                    and String contains more than
00916                                    PcdMaximumAsciiStringLength Ascii
00917                                    characters, not including the
00918                                    Null-terminator.
00919   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
00920                                    the range defined by UINT64.
00921 
00922 **/
00923 RETURN_STATUS
00924 EFIAPI
00925 AsciiStrDecimalToUint64S (
00926   IN  CONST CHAR8              *String,
00927   OUT       CHAR8              **EndPointer,  OPTIONAL
00928   OUT       UINT64             *Data
00929   );
00930 
00931 /**
00932   Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
00933 
00934   This function outputs a value of type UINTN by interpreting the contents of
00935   the Ascii string specified by String as a hexadecimal number. The format of
00936   the input Ascii string String is:
00937 
00938                   [spaces][zeros][x][hexadecimal digits].
00939 
00940   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
00941   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
00942   "x" appears in the input string, it must be prefixed with at least one 0. The
00943   function will ignore the pad space, which includes spaces or tab characters,
00944   before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
00945   [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
00946   the first valid hexadecimal digit. Then, the function stops at the first
00947   character that is a not a valid hexadecimal character or Null-terminator,
00948   whichever on comes first.
00949 
00950   If String is NULL, then ASSERT().
00951   If Data is NULL, then ASSERT().
00952   If PcdMaximumAsciiStringLength is not zero, and String contains more than
00953   PcdMaximumAsciiStringLength Ascii characters, not including the
00954   Null-terminator, then ASSERT().
00955 
00956   If String has no valid hexadecimal digits in the above format, then 0 is
00957   stored at the location pointed to by Data.
00958   If the number represented by String exceeds the range defined by UINTN, then
00959   MAX_UINTN is stored at the location pointed to by Data.
00960 
00961   If EndPointer is not NULL, a pointer to the character that stopped the scan
00962   is stored at the location pointed to by EndPointer. If String has no valid
00963   hexadecimal digits right after the optional pad spaces, the value of String
00964   is stored at the location pointed to by EndPointer.
00965 
00966   @param  String                   Pointer to a Null-terminated Ascii string.
00967   @param  EndPointer               Pointer to character that stops scan.
00968   @param  Data                     Pointer to the converted value.
00969 
00970   @retval RETURN_SUCCESS           Value is translated from String.
00971   @retval RETURN_INVALID_PARAMETER If String is NULL.
00972                                    If Data is NULL.
00973                                    If PcdMaximumAsciiStringLength is not zero,
00974                                    and String contains more than
00975                                    PcdMaximumAsciiStringLength Ascii
00976                                    characters, not including the
00977                                    Null-terminator.
00978   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
00979                                    the range defined by UINTN.
00980 
00981 **/
00982 RETURN_STATUS
00983 EFIAPI
00984 AsciiStrHexToUintnS (
00985   IN  CONST CHAR8              *String,
00986   OUT       CHAR8              **EndPointer,  OPTIONAL
00987   OUT       UINTN              *Data
00988   );
00989 
00990 /**
00991   Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
00992 
00993   This function outputs a value of type UINT64 by interpreting the contents of
00994   the Ascii string specified by String as a hexadecimal number. The format of
00995   the input Ascii string String is:
00996 
00997                   [spaces][zeros][x][hexadecimal digits].
00998 
00999   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
01000   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
01001   "x" appears in the input string, it must be prefixed with at least one 0. The
01002   function will ignore the pad space, which includes spaces or tab characters,
01003   before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
01004   [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
01005   the first valid hexadecimal digit. Then, the function stops at the first
01006   character that is a not a valid hexadecimal character or Null-terminator,
01007   whichever on comes first.
01008 
01009   If String is NULL, then ASSERT().
01010   If Data is NULL, then ASSERT().
01011   If PcdMaximumAsciiStringLength is not zero, and String contains more than
01012   PcdMaximumAsciiStringLength Ascii characters, not including the
01013   Null-terminator, then ASSERT().
01014 
01015   If String has no valid hexadecimal digits in the above format, then 0 is
01016   stored at the location pointed to by Data.
01017   If the number represented by String exceeds the range defined by UINT64, then
01018   MAX_UINT64 is stored at the location pointed to by Data.
01019 
01020   If EndPointer is not NULL, a pointer to the character that stopped the scan
01021   is stored at the location pointed to by EndPointer. If String has no valid
01022   hexadecimal digits right after the optional pad spaces, the value of String
01023   is stored at the location pointed to by EndPointer.
01024 
01025   @param  String                   Pointer to a Null-terminated Ascii string.
01026   @param  EndPointer               Pointer to character that stops scan.
01027   @param  Data                     Pointer to the converted value.
01028 
01029   @retval RETURN_SUCCESS           Value is translated from String.
01030   @retval RETURN_INVALID_PARAMETER If String is NULL.
01031                                    If Data is NULL.
01032                                    If PcdMaximumAsciiStringLength is not zero,
01033                                    and String contains more than
01034                                    PcdMaximumAsciiStringLength Ascii
01035                                    characters, not including the
01036                                    Null-terminator.
01037   @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
01038                                    the range defined by UINT64.
01039 
01040 **/
01041 RETURN_STATUS
01042 EFIAPI
01043 AsciiStrHexToUint64S (
01044   IN  CONST CHAR8              *String,
01045   OUT       CHAR8              **EndPointer,  OPTIONAL
01046   OUT       UINT64             *Data
01047   );
01048 
01049 
01050 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
01051 
01052 /**
01053   [ATTENTION] This function is deprecated for security reason.
01054 
01055   Copies one Null-terminated Unicode string to another Null-terminated Unicode
01056   string and returns the new Unicode string.
01057 
01058   This function copies the contents of the Unicode string Source to the Unicode
01059   string Destination, and returns Destination. If Source and Destination
01060   overlap, then the results are undefined.
01061 
01062   If Destination is NULL, then ASSERT().
01063   If Destination is not aligned on a 16-bit boundary, then ASSERT().
01064   If Source is NULL, then ASSERT().
01065   If Source is not aligned on a 16-bit boundary, then ASSERT().
01066   If Source and Destination overlap, then ASSERT().
01067   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
01068   PcdMaximumUnicodeStringLength Unicode characters not including the
01069   Null-terminator, then ASSERT().
01070 
01071   @param  Destination The pointer to a Null-terminated Unicode string.
01072   @param  Source      The pointer to a Null-terminated Unicode string.
01073 
01074   @return Destination.
01075 
01076 **/
01077 CHAR16 *
01078 EFIAPI
01079 StrCpy (
01080   OUT     CHAR16                    *Destination,
01081   IN      CONST CHAR16              *Source
01082   );
01083 
01084 
01085 /**
01086   [ATTENTION] This function is deprecated for security reason.
01087 
01088   Copies up to a specified length from one Null-terminated Unicode string to
01089   another Null-terminated Unicode string and returns the new Unicode string.
01090 
01091   This function copies the contents of the Unicode string Source to the Unicode
01092   string Destination, and returns Destination. At most, Length Unicode
01093   characters are copied from Source to Destination. If Length is 0, then
01094   Destination is returned unmodified. If Length is greater that the number of
01095   Unicode characters in Source, then Destination is padded with Null Unicode
01096   characters. If Source and Destination overlap, then the results are
01097   undefined.
01098 
01099   If Length > 0 and Destination is NULL, then ASSERT().
01100   If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
01101   If Length > 0 and Source is NULL, then ASSERT().
01102   If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
01103   If Source and Destination overlap, then ASSERT().
01104   If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
01105   PcdMaximumUnicodeStringLength, then ASSERT().
01106   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
01107   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
01108   then ASSERT().
01109 
01110   @param  Destination The pointer to a Null-terminated Unicode string.
01111   @param  Source      The pointer to a Null-terminated Unicode string.
01112   @param  Length      The maximum number of Unicode characters to copy.
01113 
01114   @return Destination.
01115 
01116 **/
01117 CHAR16 *
01118 EFIAPI
01119 StrnCpy (
01120   OUT     CHAR16                    *Destination,
01121   IN      CONST CHAR16              *Source,
01122   IN      UINTN                     Length
01123   );
01124 #endif
01125 
01126 /**
01127   Returns the length of a Null-terminated Unicode string.
01128 
01129   This function returns the number of Unicode characters in the Null-terminated
01130   Unicode string specified by String.
01131 
01132   If String is NULL, then ASSERT().
01133   If String is not aligned on a 16-bit boundary, then ASSERT().
01134   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
01135   PcdMaximumUnicodeStringLength Unicode characters not including the
01136   Null-terminator, then ASSERT().
01137 
01138   @param  String  Pointer to a Null-terminated Unicode string.
01139 
01140   @return The length of String.
01141 
01142 **/
01143 UINTN
01144 EFIAPI
01145 StrLen (
01146   IN      CONST CHAR16              *String
01147   );
01148 
01149 
01150 /**
01151   Returns the size of a Null-terminated Unicode string in bytes, including the
01152   Null terminator.
01153 
01154   This function returns the size, in bytes, of the Null-terminated Unicode string
01155   specified by String.
01156 
01157   If String is NULL, then ASSERT().
01158   If String is not aligned on a 16-bit boundary, then ASSERT().
01159   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
01160   PcdMaximumUnicodeStringLength Unicode characters not including the
01161   Null-terminator, then ASSERT().
01162 
01163   @param  String  The pointer to a Null-terminated Unicode string.
01164 
01165   @return The size of String.
01166 
01167 **/
01168 UINTN
01169 EFIAPI
01170 StrSize (
01171   IN      CONST CHAR16              *String
01172   );
01173 
01174 
01175 /**
01176   Compares two Null-terminated Unicode strings, and returns the difference
01177   between the first mismatched Unicode characters.
01178 
01179   This function compares the Null-terminated Unicode string FirstString to the
01180   Null-terminated Unicode string SecondString. If FirstString is identical to
01181   SecondString, then 0 is returned. Otherwise, the value returned is the first
01182   mismatched Unicode character in SecondString subtracted from the first
01183   mismatched Unicode character in FirstString.
01184 
01185   If FirstString is NULL, then ASSERT().
01186   If FirstString is not aligned on a 16-bit boundary, then ASSERT().
01187   If SecondString is NULL, then ASSERT().
01188   If SecondString is not aligned on a 16-bit boundary, then ASSERT().
01189   If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
01190   than PcdMaximumUnicodeStringLength Unicode characters not including the
01191   Null-terminator, then ASSERT().
01192   If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
01193   than PcdMaximumUnicodeStringLength Unicode characters, not including the
01194   Null-terminator, then ASSERT().
01195 
01196   @param  FirstString   The pointer to a Null-terminated Unicode string.
01197   @param  SecondString  The pointer to a Null-terminated Unicode string.
01198 
01199   @retval 0      FirstString is identical to SecondString.
01200   @return others FirstString is not identical to SecondString.
01201 
01202 **/
01203 INTN
01204 EFIAPI
01205 StrCmp (
01206   IN      CONST CHAR16              *FirstString,
01207   IN      CONST CHAR16              *SecondString
01208   );
01209 
01210 
01211 /**
01212   Compares up to a specified length the contents of two Null-terminated Unicode strings,
01213   and returns the difference between the first mismatched Unicode characters.
01214 
01215   This function compares the Null-terminated Unicode string FirstString to the
01216   Null-terminated Unicode string SecondString. At most, Length Unicode
01217   characters will be compared. If Length is 0, then 0 is returned. If
01218   FirstString is identical to SecondString, then 0 is returned. Otherwise, the
01219   value returned is the first mismatched Unicode character in SecondString
01220   subtracted from the first mismatched Unicode character in FirstString.
01221 
01222   If Length > 0 and FirstString is NULL, then ASSERT().
01223   If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
01224   If Length > 0 and SecondString is NULL, then ASSERT().
01225   If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
01226   If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
01227   PcdMaximumUnicodeStringLength, then ASSERT().
01228   If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
01229   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
01230   then ASSERT().
01231   If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
01232   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
01233   then ASSERT().
01234 
01235   @param  FirstString   The pointer to a Null-terminated Unicode string.
01236   @param  SecondString  The pointer to a Null-terminated Unicode string.
01237   @param  Length        The maximum number of Unicode characters to compare.
01238 
01239   @retval 0      FirstString is identical to SecondString.
01240   @return others FirstString is not identical to SecondString.
01241 
01242 **/
01243 INTN
01244 EFIAPI
01245 StrnCmp (
01246   IN      CONST CHAR16              *FirstString,
01247   IN      CONST CHAR16              *SecondString,
01248   IN      UINTN                     Length
01249   );
01250 
01251 
01252 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
01253 
01254 /**
01255   [ATTENTION] This function is deprecated for security reason.
01256 
01257   Concatenates one Null-terminated Unicode string to another Null-terminated
01258   Unicode string, and returns the concatenated Unicode string.
01259 
01260   This function concatenates two Null-terminated Unicode strings. The contents
01261   of Null-terminated Unicode string Source are concatenated to the end of
01262   Null-terminated Unicode string Destination. The Null-terminated concatenated
01263   Unicode String is returned. If Source and Destination overlap, then the
01264   results are undefined.
01265 
01266   If Destination is NULL, then ASSERT().
01267   If Destination is not aligned on a 16-bit boundary, then ASSERT().
01268   If Source is NULL, then ASSERT().
01269   If Source is not aligned on a 16-bit boundary, then ASSERT().
01270   If Source and Destination overlap, then ASSERT().
01271   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
01272   than PcdMaximumUnicodeStringLength Unicode characters, not including the
01273   Null-terminator, then ASSERT().
01274   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
01275   PcdMaximumUnicodeStringLength Unicode characters, not including the
01276   Null-terminator, then ASSERT().
01277   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
01278   and Source results in a Unicode string with more than
01279   PcdMaximumUnicodeStringLength Unicode characters, not including the
01280   Null-terminator, then ASSERT().
01281 
01282   @param  Destination The pointer to a Null-terminated Unicode string.
01283   @param  Source      The pointer to a Null-terminated Unicode string.
01284 
01285   @return Destination.
01286 
01287 **/
01288 CHAR16 *
01289 EFIAPI
01290 StrCat (
01291   IN OUT  CHAR16                    *Destination,
01292   IN      CONST CHAR16              *Source
01293   );
01294 
01295 
01296 /**
01297   [ATTENTION] This function is deprecated for security reason.
01298 
01299   Concatenates up to a specified length one Null-terminated Unicode to the end
01300   of another Null-terminated Unicode string, and returns the concatenated
01301   Unicode string.
01302 
01303   This function concatenates two Null-terminated Unicode strings. The contents
01304   of Null-terminated Unicode string Source are concatenated to the end of
01305   Null-terminated Unicode string Destination, and Destination is returned. At
01306   most, Length Unicode characters are concatenated from Source to the end of
01307   Destination, and Destination is always Null-terminated. If Length is 0, then
01308   Destination is returned unmodified. If Source and Destination overlap, then
01309   the results are undefined.
01310 
01311   If Destination is NULL, then ASSERT().
01312   If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
01313   If Length > 0 and Source is NULL, then ASSERT().
01314   If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
01315   If Source and Destination overlap, then ASSERT().
01316   If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
01317   PcdMaximumUnicodeStringLength, then ASSERT().
01318   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
01319   than PcdMaximumUnicodeStringLength Unicode characters, not including the
01320   Null-terminator, then ASSERT().
01321   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
01322   PcdMaximumUnicodeStringLength Unicode characters, not including the
01323   Null-terminator, then ASSERT().
01324   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
01325   and Source results in a Unicode string with more than PcdMaximumUnicodeStringLength
01326   Unicode characters, not including the Null-terminator, then ASSERT().
01327 
01328   @param  Destination The pointer to a Null-terminated Unicode string.
01329   @param  Source      The pointer to a Null-terminated Unicode string.
01330   @param  Length      The maximum number of Unicode characters to concatenate from
01331                       Source.
01332 
01333   @return Destination.
01334 
01335 **/
01336 CHAR16 *
01337 EFIAPI
01338 StrnCat (
01339   IN OUT  CHAR16                    *Destination,
01340   IN      CONST CHAR16              *Source,
01341   IN      UINTN                     Length
01342   );
01343 #endif
01344 
01345 /**
01346   Returns the first occurrence of a Null-terminated Unicode sub-string
01347   in a Null-terminated Unicode string.
01348 
01349   This function scans the contents of the Null-terminated Unicode string
01350   specified by String and returns the first occurrence of SearchString.
01351   If SearchString is not found in String, then NULL is returned.  If
01352   the length of SearchString is zero, then String is returned.
01353 
01354   If String is NULL, then ASSERT().
01355   If String is not aligned on a 16-bit boundary, then ASSERT().
01356   If SearchString is NULL, then ASSERT().
01357   If SearchString is not aligned on a 16-bit boundary, then ASSERT().
01358 
01359   If PcdMaximumUnicodeStringLength is not zero, and SearchString
01360   or String contains more than PcdMaximumUnicodeStringLength Unicode
01361   characters, not including the Null-terminator, then ASSERT().
01362 
01363   @param  String          The pointer to a Null-terminated Unicode string.
01364   @param  SearchString    The pointer to a Null-terminated Unicode string to search for.
01365 
01366   @retval NULL            If the SearchString does not appear in String.
01367   @return others          If there is a match.
01368 
01369 **/
01370 CHAR16 *
01371 EFIAPI
01372 StrStr (
01373   IN      CONST CHAR16              *String,
01374   IN      CONST CHAR16              *SearchString
01375   );
01376 
01377 /**
01378   Convert a Null-terminated Unicode decimal string to a value of
01379   type UINTN.
01380 
01381   This function returns a value of type UINTN by interpreting the contents
01382   of the Unicode string specified by String as a decimal number. The format
01383   of the input Unicode string String is:
01384 
01385                   [spaces] [decimal digits].
01386 
01387   The valid decimal digit character is in the range [0-9]. The
01388   function will ignore the pad space, which includes spaces or
01389   tab characters, before [decimal digits]. The running zero in the
01390   beginning of [decimal digits] will be ignored. Then, the function
01391   stops at the first character that is a not a valid decimal character
01392   or a Null-terminator, whichever one comes first.
01393 
01394   If String is NULL, then ASSERT().
01395   If String is not aligned in a 16-bit boundary, then ASSERT().
01396   If String has only pad spaces, then 0 is returned.
01397   If String has no pad spaces or valid decimal digits,
01398   then 0 is returned.
01399   If the number represented by String overflows according
01400   to the range defined by UINTN, then MAX_UINTN is returned.
01401 
01402   If PcdMaximumUnicodeStringLength is not zero, and String contains
01403   more than PcdMaximumUnicodeStringLength Unicode characters not including
01404   the Null-terminator, then ASSERT().
01405 
01406   @param  String      The pointer to a Null-terminated Unicode string.
01407 
01408   @retval Value translated from String.
01409 
01410 **/
01411 UINTN
01412 EFIAPI
01413 StrDecimalToUintn (
01414   IN      CONST CHAR16              *String
01415   );
01416 
01417 /**
01418   Convert a Null-terminated Unicode decimal string to a value of
01419   type UINT64.
01420 
01421   This function returns a value of type UINT64 by interpreting the contents
01422   of the Unicode string specified by String as a decimal number. The format
01423   of the input Unicode string String is:
01424 
01425                   [spaces] [decimal digits].
01426 
01427   The valid decimal digit character is in the range [0-9]. The
01428   function will ignore the pad space, which includes spaces or
01429   tab characters, before [decimal digits]. The running zero in the
01430   beginning of [decimal digits] will be ignored. Then, the function
01431   stops at the first character that is a not a valid decimal character
01432   or a Null-terminator, whichever one comes first.
01433 
01434   If String is NULL, then ASSERT().
01435   If String is not aligned in a 16-bit boundary, then ASSERT().
01436   If String has only pad spaces, then 0 is returned.
01437   If String has no pad spaces or valid decimal digits,
01438   then 0 is returned.
01439   If the number represented by String overflows according
01440   to the range defined by UINT64, then MAX_UINT64 is returned.
01441 
01442   If PcdMaximumUnicodeStringLength is not zero, and String contains
01443   more than PcdMaximumUnicodeStringLength Unicode characters not including
01444   the Null-terminator, then ASSERT().
01445 
01446   @param  String          The pointer to a Null-terminated Unicode string.
01447 
01448   @retval Value translated from String.
01449 
01450 **/
01451 UINT64
01452 EFIAPI
01453 StrDecimalToUint64 (
01454   IN      CONST CHAR16              *String
01455   );
01456 
01457 
01458 /**
01459   Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
01460 
01461   This function returns a value of type UINTN by interpreting the contents
01462   of the Unicode string specified by String as a hexadecimal number.
01463   The format of the input Unicode string String is:
01464 
01465                   [spaces][zeros][x][hexadecimal digits].
01466 
01467   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
01468   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
01469   If "x" appears in the input string, it must be prefixed with at least one 0.
01470   The function will ignore the pad space, which includes spaces or tab characters,
01471   before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
01472   [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
01473   first valid hexadecimal digit. Then, the function stops at the first character
01474   that is a not a valid hexadecimal character or NULL, whichever one comes first.
01475 
01476   If String is NULL, then ASSERT().
01477   If String is not aligned in a 16-bit boundary, then ASSERT().
01478   If String has only pad spaces, then zero is returned.
01479   If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
01480   then zero is returned.
01481   If the number represented by String overflows according to the range defined by
01482   UINTN, then MAX_UINTN is returned.
01483 
01484   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
01485   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
01486   then ASSERT().
01487 
01488   @param  String          The pointer to a Null-terminated Unicode string.
01489 
01490   @retval Value translated from String.
01491 
01492 **/
01493 UINTN
01494 EFIAPI
01495 StrHexToUintn (
01496   IN      CONST CHAR16              *String
01497   );
01498 
01499 
01500 /**
01501   Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
01502 
01503   This function returns a value of type UINT64 by interpreting the contents
01504   of the Unicode string specified by String as a hexadecimal number.
01505   The format of the input Unicode string String is
01506 
01507                   [spaces][zeros][x][hexadecimal digits].
01508 
01509   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
01510   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
01511   If "x" appears in the input string, it must be prefixed with at least one 0.
01512   The function will ignore the pad space, which includes spaces or tab characters,
01513   before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
01514   [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
01515   first valid hexadecimal digit. Then, the function stops at the first character that is
01516   a not a valid hexadecimal character or NULL, whichever one comes first.
01517 
01518   If String is NULL, then ASSERT().
01519   If String is not aligned in a 16-bit boundary, then ASSERT().
01520   If String has only pad spaces, then zero is returned.
01521   If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
01522   then zero is returned.
01523   If the number represented by String overflows according to the range defined by
01524   UINT64, then MAX_UINT64 is returned.
01525 
01526   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
01527   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
01528   then ASSERT().
01529 
01530   @param  String          The pointer to a Null-terminated Unicode string.
01531 
01532   @retval Value translated from String.
01533 
01534 **/
01535 UINT64
01536 EFIAPI
01537 StrHexToUint64 (
01538   IN      CONST CHAR16             *String
01539   );
01540 
01541 /**
01542   Convert a Null-terminated Unicode string to IPv6 address and prefix length.
01543 
01544   This function outputs a value of type IPv6_ADDRESS and may output a value
01545   of type UINT8 by interpreting the contents of the Unicode string specified
01546   by String. The format of the input Unicode string String is as follows:
01547 
01548                   X:X:X:X:X:X:X:X[/P]
01549 
01550   X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
01551   [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
01552   memory address and high byte is stored in high memory address. P contains decimal
01553   digit characters in the range [0-9]. The running zero in the beginning of P will
01554   be ignored. /P is optional.
01555 
01556   When /P is not in the String, the function stops at the first character that is
01557   not a valid hexadecimal digit character after eight X's are converted.
01558 
01559   When /P is in the String, the function stops at the first character that is not
01560   a valid decimal digit character after P is converted.
01561 
01562   "::" can be used to compress one or more groups of X when X contains only 0.
01563   The "::" can only appear once in the String.
01564 
01565   If String is NULL, then ASSERT().
01566 
01567   If Address is NULL, then ASSERT().
01568 
01569   If String is not aligned in a 16-bit boundary, then ASSERT().
01570 
01571   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
01572   PcdMaximumUnicodeStringLength Unicode characters, not including the
01573   Null-terminator, then ASSERT().
01574 
01575   If EndPointer is not NULL and Address is translated from String, a pointer
01576   to the character that stopped the scan is stored at the location pointed to
01577   by EndPointer.
01578 
01579   @param  String                   Pointer to a Null-terminated Unicode string.
01580   @param  EndPointer               Pointer to character that stops scan.
01581   @param  Address                  Pointer to the converted IPv6 address.
01582   @param  PrefixLength             Pointer to the converted IPv6 address prefix
01583                                    length. MAX_UINT8 is returned when /P is
01584                                    not in the String.
01585 
01586   @retval RETURN_SUCCESS           Address is translated from String.
01587   @retval RETURN_INVALID_PARAMETER If String is NULL.
01588                                    If Data is NULL.
01589   @retval RETURN_UNSUPPORTED       If X contains more than four hexadecimal
01590                                     digit characters.
01591                                    If String contains "::" and number of X
01592                                     is not less than 8.
01593                                    If P starts with character that is not a
01594                                     valid decimal digit character.
01595                                    If the decimal number converted from P
01596                                     exceeds 128.
01597 
01598 **/
01599 RETURN_STATUS
01600 EFIAPI
01601 StrToIpv6Address (
01602   IN  CONST CHAR16       *String,
01603   OUT CHAR16             **EndPointer, OPTIONAL
01604   OUT IPv6_ADDRESS       *Address,
01605   OUT UINT8              *PrefixLength OPTIONAL
01606   );
01607 
01608 /**
01609   Convert a Null-terminated Unicode string to IPv4 address and prefix length.
01610 
01611   This function outputs a value of type IPv4_ADDRESS and may output a value
01612   of type UINT8 by interpreting the contents of the Unicode string specified
01613   by String. The format of the input Unicode string String is as follows:
01614 
01615                   D.D.D.D[/P]
01616 
01617   D and P are decimal digit characters in the range [0-9]. The running zero in
01618   the beginning of D and P will be ignored. /P is optional.
01619 
01620   When /P is not in the String, the function stops at the first character that is
01621   not a valid decimal digit character after four D's are converted.
01622 
01623   When /P is in the String, the function stops at the first character that is not
01624   a valid decimal digit character after P is converted.
01625 
01626   If String is NULL, then ASSERT().
01627 
01628   If Address is NULL, then ASSERT().
01629 
01630   If String is not aligned in a 16-bit boundary, then ASSERT().
01631 
01632   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
01633   PcdMaximumUnicodeStringLength Unicode characters, not including the
01634   Null-terminator, then ASSERT().
01635 
01636   If EndPointer is not NULL and Address is translated from String, a pointer
01637   to the character that stopped the scan is stored at the location pointed to
01638   by EndPointer.
01639 
01640   @param  String                   Pointer to a Null-terminated Unicode string.
01641   @param  EndPointer               Pointer to character that stops scan.
01642   @param  Address                  Pointer to the converted IPv4 address.
01643   @param  PrefixLength             Pointer to the converted IPv4 address prefix
01644                                    length. MAX_UINT8 is returned when /P is
01645                                    not in the String.
01646 
01647   @retval RETURN_SUCCESS           Address is translated from String.
01648   @retval RETURN_INVALID_PARAMETER If String is NULL.
01649                                    If Data is NULL.
01650   @retval RETURN_UNSUPPORTED       If String is not in the correct format.
01651                                    If any decimal number converted from D
01652                                     exceeds 255.
01653                                    If the decimal number converted from P
01654                                     exceeds 32.
01655 
01656 **/
01657 RETURN_STATUS
01658 EFIAPI
01659 StrToIpv4Address (
01660   IN  CONST CHAR16       *String,
01661   OUT CHAR16             **EndPointer, OPTIONAL
01662   OUT IPv4_ADDRESS       *Address,
01663   OUT UINT8              *PrefixLength OPTIONAL
01664   );
01665 
01666 #define GUID_STRING_LENGTH  36
01667 
01668 /**
01669   Convert a Null-terminated Unicode GUID string to a value of type
01670   EFI_GUID.
01671 
01672   This function outputs a GUID value by interpreting the contents of
01673   the Unicode string specified by String. The format of the input
01674   Unicode string String consists of 36 characters, as follows:
01675 
01676                   aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
01677 
01678   The pairs aa - pp are two characters in the range [0-9], [a-f] and
01679   [A-F], with each pair representing a single byte hexadecimal value.
01680 
01681   The mapping between String and the EFI_GUID structure is as follows:
01682                   aa          Data1[24:31]
01683                   bb          Data1[16:23]
01684                   cc          Data1[8:15]
01685                   dd          Data1[0:7]
01686                   ee          Data2[8:15]
01687                   ff          Data2[0:7]
01688                   gg          Data3[8:15]
01689                   hh          Data3[0:7]
01690                   ii          Data4[0:7]
01691                   jj          Data4[8:15]
01692                   kk          Data4[16:23]
01693                   ll          Data4[24:31]
01694                   mm          Data4[32:39]
01695                   nn          Data4[40:47]
01696                   oo          Data4[48:55]
01697                   pp          Data4[56:63]
01698 
01699   If String is NULL, then ASSERT().
01700   If Guid is NULL, then ASSERT().
01701   If String is not aligned in a 16-bit boundary, then ASSERT().
01702 
01703   @param  String                   Pointer to a Null-terminated Unicode string.
01704   @param  Guid                     Pointer to the converted GUID.
01705 
01706   @retval RETURN_SUCCESS           Guid is translated from String.
01707   @retval RETURN_INVALID_PARAMETER If String is NULL.
01708                                    If Data is NULL.
01709   @retval RETURN_UNSUPPORTED       If String is not as the above format.
01710 
01711 **/
01712 RETURN_STATUS
01713 EFIAPI
01714 StrToGuid (
01715   IN  CONST CHAR16       *String,
01716   OUT GUID               *Guid
01717   );
01718 
01719 /**
01720   Convert a Null-terminated Unicode hexadecimal string to a byte array.
01721 
01722   This function outputs a byte array by interpreting the contents of
01723   the Unicode string specified by String in hexadecimal format. The format of
01724   the input Unicode string String is:
01725 
01726                   [XX]*
01727 
01728   X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
01729   The function decodes every two hexadecimal digit characters as one byte. The
01730   decoding stops after Length of characters and outputs Buffer containing
01731   (Length / 2) bytes.
01732 
01733   If String is not aligned in a 16-bit boundary, then ASSERT().
01734 
01735   If String is NULL, then ASSERT().
01736 
01737   If Buffer is NULL, then ASSERT().
01738 
01739   If Length is not multiple of 2, then ASSERT().
01740 
01741   If PcdMaximumUnicodeStringLength is not zero and Length is greater than
01742   PcdMaximumUnicodeStringLength, then ASSERT().
01743 
01744   If MaxBufferSize is less than (Length / 2), then ASSERT().
01745 
01746   @param  String                   Pointer to a Null-terminated Unicode string.
01747   @param  Length                   The number of Unicode characters to decode.
01748   @param  Buffer                   Pointer to the converted bytes array.
01749   @param  MaxBufferSize            The maximum size of Buffer.
01750 
01751   @retval RETURN_SUCCESS           Buffer is translated from String.
01752   @retval RETURN_INVALID_PARAMETER If String is NULL.
01753                                    If Data is NULL.
01754                                    If Length is not multiple of 2.
01755                                    If PcdMaximumUnicodeStringLength is not zero,
01756                                     and Length is greater than
01757                                     PcdMaximumUnicodeStringLength.
01758   @retval RETURN_UNSUPPORTED       If Length of characters from String contain
01759                                     a character that is not valid hexadecimal
01760                                     digit characters, or a Null-terminator.
01761   @retval RETURN_BUFFER_TOO_SMALL  If MaxBufferSize is less than (Length / 2).
01762 **/
01763 RETURN_STATUS
01764 EFIAPI
01765 StrHexToBytes (
01766   IN  CONST CHAR16       *String,
01767   IN  UINTN              Length,
01768   OUT UINT8              *Buffer,
01769   IN  UINTN              MaxBufferSize
01770   );
01771 
01772 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
01773 
01774 /**
01775   [ATTENTION] This function is deprecated for security reason.
01776 
01777   Convert a Null-terminated Unicode string to a Null-terminated
01778   ASCII string and returns the ASCII string.
01779 
01780   This function converts the content of the Unicode string Source
01781   to the ASCII string Destination by copying the lower 8 bits of
01782   each Unicode character. It returns Destination.
01783 
01784   The caller is responsible to make sure Destination points to a buffer with size
01785   equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
01786 
01787   If any Unicode characters in Source contain non-zero value in
01788   the upper 8 bits, then ASSERT().
01789 
01790   If Destination is NULL, then ASSERT().
01791   If Source is NULL, then ASSERT().
01792   If Source is not aligned on a 16-bit boundary, then ASSERT().
01793   If Source and Destination overlap, then ASSERT().
01794 
01795   If PcdMaximumUnicodeStringLength is not zero, and Source contains
01796   more than PcdMaximumUnicodeStringLength Unicode characters not including
01797   the Null-terminator, then ASSERT().
01798 
01799   If PcdMaximumAsciiStringLength is not zero, and Source contains more
01800   than PcdMaximumAsciiStringLength Unicode characters not including the
01801   Null-terminator, then ASSERT().
01802 
01803   @param  Source        The pointer to a Null-terminated Unicode string.
01804   @param  Destination   The pointer to a Null-terminated ASCII string.
01805 
01806   @return Destination.
01807 
01808 **/
01809 CHAR8 *
01810 EFIAPI
01811 UnicodeStrToAsciiStr (
01812   IN      CONST CHAR16              *Source,
01813   OUT     CHAR8                     *Destination
01814   );
01815 
01816 #endif
01817 
01818 /**
01819   Convert a Null-terminated Unicode string to a Null-terminated
01820   ASCII string.
01821 
01822   This function is similar to AsciiStrCpyS.
01823 
01824   This function converts the content of the Unicode string Source
01825   to the ASCII string Destination by copying the lower 8 bits of
01826   each Unicode character. The function terminates the ASCII string
01827   Destination by appending a Null-terminator character at the end.
01828 
01829   The caller is responsible to make sure Destination points to a buffer with size
01830   equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
01831 
01832   If any Unicode characters in Source contain non-zero value in
01833   the upper 8 bits, then ASSERT().
01834 
01835   If Source is not aligned on a 16-bit boundary, then ASSERT().
01836   If an error would be returned, then the function will also ASSERT().
01837 
01838   If an error is returned, then the Destination is unmodified.
01839 
01840   @param  Source        The pointer to a Null-terminated Unicode string.
01841   @param  Destination   The pointer to a Null-terminated ASCII string.
01842   @param  DestMax       The maximum number of Destination Ascii
01843                         char, including terminating null char.
01844 
01845   @retval RETURN_SUCCESS           String is converted.
01846   @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than StrLen(Source).
01847   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
01848                                    If Source is NULL.
01849                                    If PcdMaximumAsciiStringLength is not zero,
01850                                     and DestMax is greater than
01851                                     PcdMaximumAsciiStringLength.
01852                                    If PcdMaximumUnicodeStringLength is not zero,
01853                                     and DestMax is greater than
01854                                     PcdMaximumUnicodeStringLength.
01855                                    If DestMax is 0.
01856   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
01857 
01858 **/
01859 RETURN_STATUS
01860 EFIAPI
01861 UnicodeStrToAsciiStrS (
01862   IN      CONST CHAR16              *Source,
01863   OUT     CHAR8                     *Destination,
01864   IN      UINTN                     DestMax
01865   );
01866 
01867 /**
01868   Convert not more than Length successive characters from a Null-terminated
01869   Unicode string to a Null-terminated Ascii string. If no null char is copied
01870   from Source, then Destination[Length] is always set to null.
01871 
01872   This function converts not more than Length successive characters from the
01873   Unicode string Source to the Ascii string Destination by copying the lower 8
01874   bits of each Unicode character. The function terminates the Ascii string
01875   Destination by appending a Null-terminator character at the end.
01876 
01877   The caller is responsible to make sure Destination points to a buffer with size
01878   equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
01879 
01880   If any Unicode characters in Source contain non-zero value in the upper 8
01881   bits, then ASSERT().
01882   If Source is not aligned on a 16-bit boundary, then ASSERT().
01883   If an error would be returned, then the function will also ASSERT().
01884 
01885   If an error is returned, then the Destination is unmodified.
01886 
01887   @param  Source             The pointer to a Null-terminated Unicode string.
01888   @param  Length             The maximum number of Unicode characters to
01889                              convert.
01890   @param  Destination        The pointer to a Null-terminated Ascii string.
01891   @param  DestMax            The maximum number of Destination Ascii
01892                              char, including terminating null char.
01893   @param  DestinationLength  The number of Unicode characters converted.
01894 
01895   @retval RETURN_SUCCESS            String is converted.
01896   @retval RETURN_INVALID_PARAMETER  If Destination is NULL.
01897                                     If Source is NULL.
01898                                     If DestinationLength is NULL.
01899                                     If PcdMaximumAsciiStringLength is not zero,
01900                                     and Length or DestMax is greater than
01901                                     PcdMaximumAsciiStringLength.
01902                                     If PcdMaximumUnicodeStringLength is not
01903                                     zero, and Length or DestMax is greater than
01904                                     PcdMaximumUnicodeStringLength.
01905                                     If DestMax is 0.
01906   @retval RETURN_BUFFER_TOO_SMALL   If DestMax is NOT greater than
01907                                     MIN(StrLen(Source), Length).
01908   @retval RETURN_ACCESS_DENIED      If Source and Destination overlap.
01909 
01910 **/
01911 RETURN_STATUS
01912 EFIAPI
01913 UnicodeStrnToAsciiStrS (
01914   IN      CONST CHAR16              *Source,
01915   IN      UINTN                     Length,
01916   OUT     CHAR8                     *Destination,
01917   IN      UINTN                     DestMax,
01918   OUT     UINTN                     *DestinationLength
01919   );
01920 
01921 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
01922 
01923 /**
01924   [ATTENTION] This function is deprecated for security reason.
01925 
01926   Copies one Null-terminated ASCII string to another Null-terminated ASCII
01927   string and returns the new ASCII string.
01928 
01929   This function copies the contents of the ASCII string Source to the ASCII
01930   string Destination, and returns Destination. If Source and Destination
01931   overlap, then the results are undefined.
01932 
01933   If Destination is NULL, then ASSERT().
01934   If Source is NULL, then ASSERT().
01935   If Source and Destination overlap, then ASSERT().
01936   If PcdMaximumAsciiStringLength is not zero and Source contains more than
01937   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
01938   then ASSERT().
01939 
01940   @param  Destination The pointer to a Null-terminated ASCII string.
01941   @param  Source      The pointer to a Null-terminated ASCII string.
01942 
01943   @return Destination
01944 
01945 **/
01946 CHAR8 *
01947 EFIAPI
01948 AsciiStrCpy (
01949   OUT     CHAR8                     *Destination,
01950   IN      CONST CHAR8               *Source
01951   );
01952 
01953 
01954 /**
01955   [ATTENTION] This function is deprecated for security reason.
01956 
01957   Copies up to a specified length one Null-terminated ASCII string to another
01958   Null-terminated ASCII string and returns the new ASCII string.
01959 
01960   This function copies the contents of the ASCII string Source to the ASCII
01961   string Destination, and returns Destination. At most, Length ASCII characters
01962   are copied from Source to Destination. If Length is 0, then Destination is
01963   returned unmodified. If Length is greater that the number of ASCII characters
01964   in Source, then Destination is padded with Null ASCII characters. If Source
01965   and Destination overlap, then the results are undefined.
01966 
01967   If Destination is NULL, then ASSERT().
01968   If Source is NULL, then ASSERT().
01969   If Source and Destination overlap, then ASSERT().
01970   If PcdMaximumAsciiStringLength is not zero, and Length is greater than
01971   PcdMaximumAsciiStringLength, then ASSERT().
01972   If PcdMaximumAsciiStringLength is not zero, and Source contains more than
01973   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
01974   then ASSERT().
01975 
01976   @param  Destination The pointer to a Null-terminated ASCII string.
01977   @param  Source      The pointer to a Null-terminated ASCII string.
01978   @param  Length      The maximum number of ASCII characters to copy.
01979 
01980   @return Destination
01981 
01982 **/
01983 CHAR8 *
01984 EFIAPI
01985 AsciiStrnCpy (
01986   OUT     CHAR8                     *Destination,
01987   IN      CONST CHAR8               *Source,
01988   IN      UINTN                     Length
01989   );
01990 #endif
01991 
01992 /**
01993   Returns the length of a Null-terminated ASCII string.
01994 
01995   This function returns the number of ASCII characters in the Null-terminated
01996   ASCII string specified by String.
01997 
01998   If Length > 0 and Destination is NULL, then ASSERT().
01999   If Length > 0 and Source is NULL, then ASSERT().
02000   If PcdMaximumAsciiStringLength is not zero and String contains more than
02001   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
02002   then ASSERT().
02003 
02004   @param  String  The pointer to a Null-terminated ASCII string.
02005 
02006   @return The length of String.
02007 
02008 **/
02009 UINTN
02010 EFIAPI
02011 AsciiStrLen (
02012   IN      CONST CHAR8               *String
02013   );
02014 
02015 
02016 /**
02017   Returns the size of a Null-terminated ASCII string in bytes, including the
02018   Null terminator.
02019 
02020   This function returns the size, in bytes, of the Null-terminated ASCII string
02021   specified by String.
02022 
02023   If String is NULL, then ASSERT().
02024   If PcdMaximumAsciiStringLength is not zero and String contains more than
02025   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
02026   then ASSERT().
02027 
02028   @param  String  The pointer to a Null-terminated ASCII string.
02029 
02030   @return The size of String.
02031 
02032 **/
02033 UINTN
02034 EFIAPI
02035 AsciiStrSize (
02036   IN      CONST CHAR8               *String
02037   );
02038 
02039 
02040 /**
02041   Compares two Null-terminated ASCII strings, and returns the difference
02042   between the first mismatched ASCII characters.
02043 
02044   This function compares the Null-terminated ASCII string FirstString to the
02045   Null-terminated ASCII string SecondString. If FirstString is identical to
02046   SecondString, then 0 is returned. Otherwise, the value returned is the first
02047   mismatched ASCII character in SecondString subtracted from the first
02048   mismatched ASCII character in FirstString.
02049 
02050   If FirstString is NULL, then ASSERT().
02051   If SecondString is NULL, then ASSERT().
02052   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
02053   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
02054   then ASSERT().
02055   If PcdMaximumAsciiStringLength is not zero and SecondString contains more
02056   than PcdMaximumAsciiStringLength ASCII characters not including the
02057   Null-terminator, then ASSERT().
02058 
02059   @param  FirstString   The pointer to a Null-terminated ASCII string.
02060   @param  SecondString  The pointer to a Null-terminated ASCII string.
02061 
02062   @retval ==0      FirstString is identical to SecondString.
02063   @retval !=0      FirstString is not identical to SecondString.
02064 
02065 **/
02066 INTN
02067 EFIAPI
02068 AsciiStrCmp (
02069   IN      CONST CHAR8               *FirstString,
02070   IN      CONST CHAR8               *SecondString
02071   );
02072 
02073 
02074 /**
02075   Performs a case insensitive comparison of two Null-terminated ASCII strings,
02076   and returns the difference between the first mismatched ASCII characters.
02077 
02078   This function performs a case insensitive comparison of the Null-terminated
02079   ASCII string FirstString to the Null-terminated ASCII string SecondString. If
02080   FirstString is identical to SecondString, then 0 is returned. Otherwise, the
02081   value returned is the first mismatched lower case ASCII character in
02082   SecondString subtracted from the first mismatched lower case ASCII character
02083   in FirstString.
02084 
02085   If FirstString is NULL, then ASSERT().
02086   If SecondString is NULL, then ASSERT().
02087   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
02088   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
02089   then ASSERT().
02090   If PcdMaximumAsciiStringLength is not zero and SecondString contains more
02091   than PcdMaximumAsciiStringLength ASCII characters not including the
02092   Null-terminator, then ASSERT().
02093 
02094   @param  FirstString   The pointer to a Null-terminated ASCII string.
02095   @param  SecondString  The pointer to a Null-terminated ASCII string.
02096 
02097   @retval ==0    FirstString is identical to SecondString using case insensitive
02098                  comparisons.
02099   @retval !=0    FirstString is not identical to SecondString using case
02100                  insensitive comparisons.
02101 
02102 **/
02103 INTN
02104 EFIAPI
02105 AsciiStriCmp (
02106   IN      CONST CHAR8               *FirstString,
02107   IN      CONST CHAR8               *SecondString
02108   );
02109 
02110 
02111 /**
02112   Compares two Null-terminated ASCII strings with maximum lengths, and returns
02113   the difference between the first mismatched ASCII characters.
02114 
02115   This function compares the Null-terminated ASCII string FirstString to the
02116   Null-terminated ASCII  string SecondString. At most, Length ASCII characters
02117   will be compared. If Length is 0, then 0 is returned. If FirstString is
02118   identical to SecondString, then 0 is returned. Otherwise, the value returned
02119   is the first mismatched ASCII character in SecondString subtracted from the
02120   first mismatched ASCII character in FirstString.
02121 
02122   If Length > 0 and FirstString is NULL, then ASSERT().
02123   If Length > 0 and SecondString is NULL, then ASSERT().
02124   If PcdMaximumAsciiStringLength is not zero, and Length is greater than
02125   PcdMaximumAsciiStringLength, then ASSERT().
02126   If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
02127   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
02128   then ASSERT().
02129   If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
02130   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
02131   then ASSERT().
02132 
02133   @param  FirstString   The pointer to a Null-terminated ASCII string.
02134   @param  SecondString  The pointer to a Null-terminated ASCII string.
02135   @param  Length        The maximum number of ASCII characters for compare.
02136 
02137   @retval ==0       FirstString is identical to SecondString.
02138   @retval !=0       FirstString is not identical to SecondString.
02139 
02140 **/
02141 INTN
02142 EFIAPI
02143 AsciiStrnCmp (
02144   IN      CONST CHAR8               *FirstString,
02145   IN      CONST CHAR8               *SecondString,
02146   IN      UINTN                     Length
02147   );
02148 
02149 
02150 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
02151 
02152 /**
02153   [ATTENTION] This function is deprecated for security reason.
02154 
02155   Concatenates one Null-terminated ASCII string to another Null-terminated
02156   ASCII string, and returns the concatenated ASCII string.
02157 
02158   This function concatenates two Null-terminated ASCII strings. The contents of
02159   Null-terminated ASCII string Source are concatenated to the end of Null-
02160   terminated ASCII string Destination. The Null-terminated concatenated ASCII
02161   String is returned.
02162 
02163   If Destination is NULL, then ASSERT().
02164   If Source is NULL, then ASSERT().
02165   If PcdMaximumAsciiStringLength is not zero and Destination contains more than
02166   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
02167   then ASSERT().
02168   If PcdMaximumAsciiStringLength is not zero and Source contains more than
02169   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
02170   then ASSERT().
02171   If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
02172   Source results in a ASCII string with more than PcdMaximumAsciiStringLength
02173   ASCII characters, then ASSERT().
02174 
02175   @param  Destination The pointer to a Null-terminated ASCII string.
02176   @param  Source      The pointer to a Null-terminated ASCII string.
02177 
02178   @return Destination
02179 
02180 **/
02181 CHAR8 *
02182 EFIAPI
02183 AsciiStrCat (
02184   IN OUT CHAR8    *Destination,
02185   IN CONST CHAR8  *Source
02186   );
02187 
02188 
02189 /**
02190   [ATTENTION] This function is deprecated for security reason.
02191 
02192   Concatenates up to a specified length one Null-terminated ASCII string to
02193   the end of another Null-terminated ASCII string, and returns the
02194   concatenated ASCII string.
02195 
02196   This function concatenates two Null-terminated ASCII strings. The contents
02197   of Null-terminated ASCII string Source are concatenated to the end of Null-
02198   terminated ASCII string Destination, and Destination is returned. At most,
02199   Length ASCII characters are concatenated from Source to the end of
02200   Destination, and Destination is always Null-terminated. If Length is 0, then
02201   Destination is returned unmodified. If Source and Destination overlap, then
02202   the results are undefined.
02203 
02204   If Length > 0 and Destination is NULL, then ASSERT().
02205   If Length > 0 and Source is NULL, then ASSERT().
02206   If Source and Destination overlap, then ASSERT().
02207   If PcdMaximumAsciiStringLength is not zero, and Length is greater than
02208   PcdMaximumAsciiStringLength, then ASSERT().
02209   If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
02210   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
02211   then ASSERT().
02212   If PcdMaximumAsciiStringLength is not zero, and Source contains more than
02213   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
02214   then ASSERT().
02215   If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
02216   Source results in a ASCII string with more than PcdMaximumAsciiStringLength
02217   ASCII characters, not including the Null-terminator, then ASSERT().
02218 
02219   @param  Destination The pointer to a Null-terminated ASCII string.
02220   @param  Source      The pointer to a Null-terminated ASCII string.
02221   @param  Length      The maximum number of ASCII characters to concatenate from
02222                       Source.
02223 
02224   @return Destination
02225 
02226 **/
02227 CHAR8 *
02228 EFIAPI
02229 AsciiStrnCat (
02230   IN OUT  CHAR8                     *Destination,
02231   IN      CONST CHAR8               *Source,
02232   IN      UINTN                     Length
02233   );
02234 #endif
02235 
02236 /**
02237   Returns the first occurrence of a Null-terminated ASCII sub-string
02238   in a Null-terminated ASCII string.
02239 
02240   This function scans the contents of the ASCII string specified by String
02241   and returns the first occurrence of SearchString. If SearchString is not
02242   found in String, then NULL is returned. If the length of SearchString is zero,
02243   then String is returned.
02244 
02245   If String is NULL, then ASSERT().
02246   If SearchString is NULL, then ASSERT().
02247 
02248   If PcdMaximumAsciiStringLength is not zero, and SearchString or
02249   String contains more than PcdMaximumAsciiStringLength Unicode characters
02250   not including the Null-terminator, then ASSERT().
02251 
02252   @param  String          The pointer to a Null-terminated ASCII string.
02253   @param  SearchString    The pointer to a Null-terminated ASCII string to search for.
02254 
02255   @retval NULL            If the SearchString does not appear in String.
02256   @retval others          If there is a match return the first occurrence of SearchingString.
02257                           If the length of SearchString is zero,return String.
02258 
02259 **/
02260 CHAR8 *
02261 EFIAPI
02262 AsciiStrStr (
02263   IN      CONST CHAR8               *String,
02264   IN      CONST CHAR8               *SearchString
02265   );
02266 
02267 
02268 /**
02269   Convert a Null-terminated ASCII decimal string to a value of type
02270   UINTN.
02271 
02272   This function returns a value of type UINTN by interpreting the contents
02273   of the ASCII string String as a decimal number. The format of the input
02274   ASCII string String is:
02275 
02276                     [spaces] [decimal digits].
02277 
02278   The valid decimal digit character is in the range [0-9]. The function will
02279   ignore the pad space, which includes spaces or tab characters, before the digits.
02280   The running zero in the beginning of [decimal digits] will be ignored. Then, the
02281   function stops at the first character that is a not a valid decimal character or
02282   Null-terminator, whichever on comes first.
02283 
02284   If String has only pad spaces, then 0 is returned.
02285   If String has no pad spaces or valid decimal digits, then 0 is returned.
02286   If the number represented by String overflows according to the range defined by
02287   UINTN, then MAX_UINTN is returned.
02288   If String is NULL, then ASSERT().
02289   If PcdMaximumAsciiStringLength is not zero, and String contains more than
02290   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
02291   then ASSERT().
02292 
02293   @param  String          The pointer to a Null-terminated ASCII string.
02294 
02295   @retval The value translated from String.
02296 
02297 **/
02298 UINTN
02299 EFIAPI
02300 AsciiStrDecimalToUintn (
02301   IN      CONST CHAR8               *String
02302   );
02303 
02304 
02305 /**
02306   Convert a Null-terminated ASCII decimal string to a value of type
02307   UINT64.
02308 
02309   This function returns a value of type UINT64 by interpreting the contents
02310   of the ASCII string String as a decimal number. The format of the input
02311   ASCII string String is:
02312 
02313                     [spaces] [decimal digits].
02314 
02315   The valid decimal digit character is in the range [0-9]. The function will
02316   ignore the pad space, which includes spaces or tab characters, before the digits.
02317   The running zero in the beginning of [decimal digits] will be ignored. Then, the
02318   function stops at the first character that is a not a valid decimal character or
02319   Null-terminator, whichever on comes first.
02320 
02321   If String has only pad spaces, then 0 is returned.
02322   If String has no pad spaces or valid decimal digits, then 0 is returned.
02323   If the number represented by String overflows according to the range defined by
02324   UINT64, then MAX_UINT64 is returned.
02325   If String is NULL, then ASSERT().
02326   If PcdMaximumAsciiStringLength is not zero, and String contains more than
02327   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
02328   then ASSERT().
02329 
02330   @param  String          The pointer to a Null-terminated ASCII string.
02331 
02332   @retval Value translated from String.
02333 
02334 **/
02335 UINT64
02336 EFIAPI
02337 AsciiStrDecimalToUint64 (
02338   IN      CONST CHAR8               *String
02339   );
02340 
02341 
02342 /**
02343   Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
02344 
02345   This function returns a value of type UINTN by interpreting the contents of
02346   the ASCII string String as a hexadecimal number. The format of the input ASCII
02347   string String is:
02348 
02349                   [spaces][zeros][x][hexadecimal digits].
02350 
02351   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
02352   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
02353   appears in the input string, it must be prefixed with at least one 0. The function
02354   will ignore the pad space, which includes spaces or tab characters, before [zeros],
02355   [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
02356   will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
02357   digit. Then, the function stops at the first character that is a not a valid
02358   hexadecimal character or Null-terminator, whichever on comes first.
02359 
02360   If String has only pad spaces, then 0 is returned.
02361   If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
02362   0 is returned.
02363 
02364   If the number represented by String overflows according to the range defined by UINTN,
02365   then MAX_UINTN is returned.
02366   If String is NULL, then ASSERT().
02367   If PcdMaximumAsciiStringLength is not zero,
02368   and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
02369   the Null-terminator, then ASSERT().
02370 
02371   @param  String          The pointer to a Null-terminated ASCII string.
02372 
02373   @retval Value translated from String.
02374 
02375 **/
02376 UINTN
02377 EFIAPI
02378 AsciiStrHexToUintn (
02379   IN      CONST CHAR8               *String
02380   );
02381 
02382 
02383 /**
02384   Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
02385 
02386   This function returns a value of type UINT64 by interpreting the contents of
02387   the ASCII string String as a hexadecimal number. The format of the input ASCII
02388   string String is:
02389 
02390                   [spaces][zeros][x][hexadecimal digits].
02391 
02392   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
02393   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
02394   appears in the input string, it must be prefixed with at least one 0. The function
02395   will ignore the pad space, which includes spaces or tab characters, before [zeros],
02396   [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
02397   will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
02398   digit. Then, the function stops at the first character that is a not a valid
02399   hexadecimal character or Null-terminator, whichever on comes first.
02400 
02401   If String has only pad spaces, then 0 is returned.
02402   If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
02403   0 is returned.
02404 
02405   If the number represented by String overflows according to the range defined by UINT64,
02406   then MAX_UINT64 is returned.
02407   If String is NULL, then ASSERT().
02408   If PcdMaximumAsciiStringLength is not zero,
02409   and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
02410   the Null-terminator, then ASSERT().
02411 
02412   @param  String          The pointer to a Null-terminated ASCII string.
02413 
02414   @retval Value translated from String.
02415 
02416 **/
02417 UINT64
02418 EFIAPI
02419 AsciiStrHexToUint64 (
02420   IN      CONST CHAR8                *String
02421   );
02422 
02423 /**
02424   Convert a Null-terminated ASCII string to IPv6 address and prefix length.
02425 
02426   This function outputs a value of type IPv6_ADDRESS and may output a value
02427   of type UINT8 by interpreting the contents of the ASCII string specified
02428   by String. The format of the input ASCII string String is as follows:
02429 
02430                   X:X:X:X:X:X:X:X[/P]
02431 
02432   X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
02433   [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
02434   memory address and high byte is stored in high memory address. P contains decimal
02435   digit characters in the range [0-9]. The running zero in the beginning of P will
02436   be ignored. /P is optional.
02437 
02438   When /P is not in the String, the function stops at the first character that is
02439   not a valid hexadecimal digit character after eight X's are converted.
02440 
02441   When /P is in the String, the function stops at the first character that is not
02442   a valid decimal digit character after P is converted.
02443 
02444   "::" can be used to compress one or more groups of X when X contains only 0.
02445   The "::" can only appear once in the String.
02446 
02447   If String is NULL, then ASSERT().
02448 
02449   If Address is NULL, then ASSERT().
02450 
02451   If EndPointer is not NULL and Address is translated from String, a pointer
02452   to the character that stopped the scan is stored at the location pointed to
02453   by EndPointer.
02454 
02455   @param  String                   Pointer to a Null-terminated ASCII string.
02456   @param  EndPointer               Pointer to character that stops scan.
02457   @param  Address                  Pointer to the converted IPv6 address.
02458   @param  PrefixLength             Pointer to the converted IPv6 address prefix
02459                                    length. MAX_UINT8 is returned when /P is
02460                                    not in the String.
02461 
02462   @retval RETURN_SUCCESS           Address is translated from String.
02463   @retval RETURN_INVALID_PARAMETER If String is NULL.
02464                                    If Data is NULL.
02465   @retval RETURN_UNSUPPORTED       If X contains more than four hexadecimal
02466                                     digit characters.
02467                                    If String contains "::" and number of X
02468                                     is not less than 8.
02469                                    If P starts with character that is not a
02470                                     valid decimal digit character.
02471                                    If the decimal number converted from P
02472                                     exceeds 128.
02473 
02474 **/
02475 RETURN_STATUS
02476 EFIAPI
02477 AsciiStrToIpv6Address (
02478   IN  CONST CHAR8        *String,
02479   OUT CHAR8              **EndPointer, OPTIONAL
02480   OUT IPv6_ADDRESS       *Address,
02481   OUT UINT8              *PrefixLength OPTIONAL
02482   );
02483 
02484 /**
02485   Convert a Null-terminated ASCII string to IPv4 address and prefix length.
02486 
02487   This function outputs a value of type IPv4_ADDRESS and may output a value
02488   of type UINT8 by interpreting the contents of the ASCII string specified
02489   by String. The format of the input ASCII string String is as follows:
02490 
02491                   D.D.D.D[/P]
02492 
02493   D and P are decimal digit characters in the range [0-9]. The running zero in
02494   the beginning of D and P will be ignored. /P is optional.
02495 
02496   When /P is not in the String, the function stops at the first character that is
02497   not a valid decimal digit character after four D's are converted.
02498 
02499   When /P is in the String, the function stops at the first character that is not
02500   a valid decimal digit character after P is converted.
02501 
02502   If String is NULL, then ASSERT().
02503 
02504   If Address is NULL, then ASSERT().
02505 
02506   If EndPointer is not NULL and Address is translated from String, a pointer
02507   to the character that stopped the scan is stored at the location pointed to
02508   by EndPointer.
02509 
02510   @param  String                   Pointer to a Null-terminated ASCII string.
02511   @param  EndPointer               Pointer to character that stops scan.
02512   @param  Address                  Pointer to the converted IPv4 address.
02513   @param  PrefixLength             Pointer to the converted IPv4 address prefix
02514                                    length. MAX_UINT8 is returned when /P is
02515                                    not in the String.
02516 
02517   @retval RETURN_SUCCESS           Address is translated from String.
02518   @retval RETURN_INVALID_PARAMETER If String is NULL.
02519                                    If Data is NULL.
02520   @retval RETURN_UNSUPPORTED       If String is not in the correct format.
02521                                    If any decimal number converted from D
02522                                     exceeds 255.
02523                                    If the decimal number converted from P
02524                                     exceeds 32.
02525 
02526 **/
02527 RETURN_STATUS
02528 EFIAPI
02529 AsciiStrToIpv4Address (
02530   IN  CONST CHAR8        *String,
02531   OUT CHAR8              **EndPointer, OPTIONAL
02532   OUT IPv4_ADDRESS       *Address,
02533   OUT UINT8              *PrefixLength OPTIONAL
02534   );
02535 
02536 /**
02537   Convert a Null-terminated ASCII GUID string to a value of type
02538   EFI_GUID.
02539 
02540   This function outputs a GUID value by interpreting the contents of
02541   the ASCII string specified by String. The format of the input
02542   ASCII string String consists of 36 characters, as follows:
02543 
02544                   aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
02545 
02546   The pairs aa - pp are two characters in the range [0-9], [a-f] and
02547   [A-F], with each pair representing a single byte hexadecimal value.
02548 
02549   The mapping between String and the EFI_GUID structure is as follows:
02550                   aa          Data1[24:31]
02551                   bb          Data1[16:23]
02552                   cc          Data1[8:15]
02553                   dd          Data1[0:7]
02554                   ee          Data2[8:15]
02555                   ff          Data2[0:7]
02556                   gg          Data3[8:15]
02557                   hh          Data3[0:7]
02558                   ii          Data4[0:7]
02559                   jj          Data4[8:15]
02560                   kk          Data4[16:23]
02561                   ll          Data4[24:31]
02562                   mm          Data4[32:39]
02563                   nn          Data4[40:47]
02564                   oo          Data4[48:55]
02565                   pp          Data4[56:63]
02566 
02567   If String is NULL, then ASSERT().
02568   If Guid is NULL, then ASSERT().
02569 
02570   @param  String                   Pointer to a Null-terminated ASCII string.
02571   @param  Guid                     Pointer to the converted GUID.
02572 
02573   @retval RETURN_SUCCESS           Guid is translated from String.
02574   @retval RETURN_INVALID_PARAMETER If String is NULL.
02575                                    If Data is NULL.
02576   @retval RETURN_UNSUPPORTED       If String is not as the above format.
02577 
02578 **/
02579 RETURN_STATUS
02580 EFIAPI
02581 AsciiStrToGuid (
02582   IN  CONST CHAR8        *String,
02583   OUT GUID               *Guid
02584   );
02585 
02586 /**
02587   Convert a Null-terminated ASCII hexadecimal string to a byte array.
02588 
02589   This function outputs a byte array by interpreting the contents of
02590   the ASCII string specified by String in hexadecimal format. The format of
02591   the input ASCII string String is:
02592 
02593                   [XX]*
02594 
02595   X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
02596   The function decodes every two hexadecimal digit characters as one byte. The
02597   decoding stops after Length of characters and outputs Buffer containing
02598   (Length / 2) bytes.
02599 
02600   If String is NULL, then ASSERT().
02601 
02602   If Buffer is NULL, then ASSERT().
02603 
02604   If Length is not multiple of 2, then ASSERT().
02605 
02606   If PcdMaximumAsciiStringLength is not zero and Length is greater than
02607   PcdMaximumAsciiStringLength, then ASSERT().
02608 
02609   If MaxBufferSize is less than (Length / 2), then ASSERT().
02610 
02611   @param  String                   Pointer to a Null-terminated ASCII string.
02612   @param  Length                   The number of ASCII characters to decode.
02613   @param  Buffer                   Pointer to the converted bytes array.
02614   @param  MaxBufferSize            The maximum size of Buffer.
02615 
02616   @retval RETURN_SUCCESS           Buffer is translated from String.
02617   @retval RETURN_INVALID_PARAMETER If String is NULL.
02618                                    If Data is NULL.
02619                                    If Length is not multiple of 2.
02620                                    If PcdMaximumAsciiStringLength is not zero,
02621                                     and Length is greater than
02622                                     PcdMaximumAsciiStringLength.
02623   @retval RETURN_UNSUPPORTED       If Length of characters from String contain
02624                                     a character that is not valid hexadecimal
02625                                     digit characters, or a Null-terminator.
02626   @retval RETURN_BUFFER_TOO_SMALL  If MaxBufferSize is less than (Length / 2).
02627 **/
02628 RETURN_STATUS
02629 EFIAPI
02630 AsciiStrHexToBytes (
02631   IN  CONST CHAR8        *String,
02632   IN  UINTN              Length,
02633   OUT UINT8              *Buffer,
02634   IN  UINTN              MaxBufferSize
02635   );
02636 
02637 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
02638 
02639 /**
02640   [ATTENTION] This function is deprecated for security reason.
02641 
02642   Convert one Null-terminated ASCII string to a Null-terminated
02643   Unicode string and returns the Unicode string.
02644 
02645   This function converts the contents of the ASCII string Source to the Unicode
02646   string Destination, and returns Destination.  The function terminates the
02647   Unicode string Destination by appending a Null-terminator character at the end.
02648   The caller is responsible to make sure Destination points to a buffer with size
02649   equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
02650 
02651   If Destination is NULL, then ASSERT().
02652   If Destination is not aligned on a 16-bit boundary, then ASSERT().
02653   If Source is NULL, then ASSERT().
02654   If Source and Destination overlap, then ASSERT().
02655   If PcdMaximumAsciiStringLength is not zero, and Source contains more than
02656   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
02657   then ASSERT().
02658   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
02659   PcdMaximumUnicodeStringLength ASCII characters not including the
02660   Null-terminator, then ASSERT().
02661 
02662   @param  Source        The pointer to a Null-terminated ASCII string.
02663   @param  Destination   The pointer to a Null-terminated Unicode string.
02664 
02665   @return Destination.
02666 
02667 **/
02668 CHAR16 *
02669 EFIAPI
02670 AsciiStrToUnicodeStr (
02671   IN      CONST CHAR8               *Source,
02672   OUT     CHAR16                    *Destination
02673   );
02674 
02675 #endif
02676 
02677 /**
02678   Convert one Null-terminated ASCII string to a Null-terminated
02679   Unicode string.
02680 
02681   This function is similar to StrCpyS.
02682 
02683   This function converts the contents of the ASCII string Source to the Unicode
02684   string Destination. The function terminates the Unicode string Destination by
02685   appending a Null-terminator character at the end.
02686 
02687   The caller is responsible to make sure Destination points to a buffer with size
02688   equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
02689 
02690   If Destination is not aligned on a 16-bit boundary, then ASSERT().
02691   If an error would be returned, then the function will also ASSERT().
02692 
02693   If an error is returned, then the Destination is unmodified.
02694 
02695   @param  Source        The pointer to a Null-terminated ASCII string.
02696   @param  Destination   The pointer to a Null-terminated Unicode string.
02697   @param  DestMax       The maximum number of Destination Unicode
02698                         char, including terminating null char.
02699 
02700   @retval RETURN_SUCCESS           String is converted.
02701   @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than StrLen(Source).
02702   @retval RETURN_INVALID_PARAMETER If Destination is NULL.
02703                                    If Source is NULL.
02704                                    If PcdMaximumUnicodeStringLength is not zero,
02705                                     and DestMax is greater than
02706                                     PcdMaximumUnicodeStringLength.
02707                                    If PcdMaximumAsciiStringLength is not zero,
02708                                     and DestMax is greater than
02709                                     PcdMaximumAsciiStringLength.
02710                                    If DestMax is 0.
02711   @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
02712 
02713 **/
02714 RETURN_STATUS
02715 EFIAPI
02716 AsciiStrToUnicodeStrS (
02717   IN      CONST CHAR8               *Source,
02718   OUT     CHAR16                    *Destination,
02719   IN      UINTN                     DestMax
02720   );
02721 
02722 /**
02723   Convert not more than Length successive characters from a Null-terminated
02724   Ascii string to a Null-terminated Unicode string. If no null char is copied
02725   from Source, then Destination[Length] is always set to null.
02726 
02727   This function converts not more than Length successive characters from the
02728   Ascii string Source to the Unicode string Destination. The function
02729   terminates the Unicode string Destination by appending a Null-terminator
02730   character at the end.
02731 
02732   The caller is responsible to make sure Destination points to a buffer with
02733   size not smaller than
02734   ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
02735 
02736   If Destination is not aligned on a 16-bit boundary, then ASSERT().
02737   If an error would be returned, then the function will also ASSERT().
02738 
02739   If an error is returned, then Destination and DestinationLength are
02740   unmodified.
02741 
02742   @param  Source             The pointer to a Null-terminated Ascii string.
02743   @param  Length             The maximum number of Ascii characters to convert.
02744   @param  Destination        The pointer to a Null-terminated Unicode string.
02745   @param  DestMax            The maximum number of Destination Unicode char,
02746                              including terminating null char.
02747   @param  DestinationLength  The number of Ascii characters converted.
02748 
02749   @retval RETURN_SUCCESS            String is converted.
02750   @retval RETURN_INVALID_PARAMETER  If Destination is NULL.
02751                                     If Source is NULL.
02752                                     If DestinationLength is NULL.
02753                                     If PcdMaximumUnicodeStringLength is not
02754                                     zero, and Length or DestMax is greater than
02755                                     PcdMaximumUnicodeStringLength.
02756                                     If PcdMaximumAsciiStringLength is not zero,
02757                                     and Length or DestMax is greater than
02758                                     PcdMaximumAsciiStringLength.
02759                                     If DestMax is 0.
02760   @retval RETURN_BUFFER_TOO_SMALL   If DestMax is NOT greater than
02761                                     MIN(AsciiStrLen(Source), Length).
02762   @retval RETURN_ACCESS_DENIED      If Source and Destination overlap.
02763 
02764 **/
02765 RETURN_STATUS
02766 EFIAPI
02767 AsciiStrnToUnicodeStrS (
02768   IN      CONST CHAR8               *Source,
02769   IN      UINTN                     Length,
02770   OUT     CHAR16                    *Destination,
02771   IN      UINTN                     DestMax,
02772   OUT     UINTN                     *DestinationLength
02773   );
02774 
02775 /**
02776   Converts an 8-bit value to an 8-bit BCD value.
02777 
02778   Converts the 8-bit value specified by Value to BCD. The BCD value is
02779   returned.
02780 
02781   If Value >= 100, then ASSERT().
02782 
02783   @param  Value The 8-bit value to convert to BCD. Range 0..99.
02784 
02785   @return The BCD value.
02786 
02787 **/
02788 UINT8
02789 EFIAPI
02790 DecimalToBcd8 (
02791   IN      UINT8                     Value
02792   );
02793 
02794 
02795 /**
02796   Converts an 8-bit BCD value to an 8-bit value.
02797 
02798   Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
02799   value is returned.
02800 
02801   If Value >= 0xA0, then ASSERT().
02802   If (Value & 0x0F) >= 0x0A, then ASSERT().
02803 
02804   @param  Value The 8-bit BCD value to convert to an 8-bit value.
02805 
02806   @return The 8-bit value is returned.
02807 
02808 **/
02809 UINT8
02810 EFIAPI
02811 BcdToDecimal8 (
02812   IN      UINT8                     Value
02813   );
02814 
02815 //
02816 //  File Path Manipulation Functions
02817 //
02818 
02819 /**
02820   Removes the last directory or file entry in a path.
02821 
02822   @param[in, out] Path    The pointer to the path to modify.
02823 
02824   @retval FALSE     Nothing was found to remove.
02825   @retval TRUE      A directory or file was removed.
02826 **/
02827 BOOLEAN
02828 EFIAPI
02829 PathRemoveLastItem(
02830   IN OUT CHAR16 *Path
02831   );
02832 
02833 /**
02834   Function to clean up paths.
02835     - Single periods in the path are removed.
02836     - Double periods in the path are removed along with a single parent directory.
02837     - Forward slashes L'/' are converted to backward slashes L'\'.
02838 
02839   This will be done inline and the existing buffer may be larger than required
02840   upon completion.
02841 
02842   @param[in] Path       The pointer to the string containing the path.
02843 
02844   @return       Returns Path, otherwise returns NULL to indicate that an error has occurred.
02845 **/
02846 CHAR16*
02847 EFIAPI
02848 PathCleanUpDirectories(
02849   IN CHAR16 *Path
02850   );
02851 
02852 //
02853 // Linked List Functions and Macros
02854 //
02855 
02856 /**
02857   Initializes the head node of a doubly linked list that is declared as a
02858   global variable in a module.
02859 
02860   Initializes the forward and backward links of a new linked list. After
02861   initializing a linked list with this macro, the other linked list functions
02862   may be used to add and remove nodes from the linked list. This macro results
02863   in smaller executables by initializing the linked list in the data section,
02864   instead if calling the InitializeListHead() function to perform the
02865   equivalent operation.
02866 
02867   @param  ListHead  The head note of a list to initialize.
02868 
02869 **/
02870 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead)  {&(ListHead), &(ListHead)}
02871 
02872 
02873 /**
02874   Initializes the head node of a doubly linked list, and returns the pointer to
02875   the head node of the doubly linked list.
02876 
02877   Initializes the forward and backward links of a new linked list. After
02878   initializing a linked list with this function, the other linked list
02879   functions may be used to add and remove nodes from the linked list. It is up
02880   to the caller of this function to allocate the memory for ListHead.
02881 
02882   If ListHead is NULL, then ASSERT().
02883 
02884   @param  ListHead  A pointer to the head node of a new doubly linked list.
02885 
02886   @return ListHead
02887 
02888 **/
02889 LIST_ENTRY *
02890 EFIAPI
02891 InitializeListHead (
02892   IN OUT  LIST_ENTRY                *ListHead
02893   );
02894 
02895 
02896 /**
02897   Adds a node to the beginning of a doubly linked list, and returns the pointer
02898   to the head node of the doubly linked list.
02899 
02900   Adds the node Entry at the beginning of the doubly linked list denoted by
02901   ListHead, and returns ListHead.
02902 
02903   If ListHead is NULL, then ASSERT().
02904   If Entry is NULL, then ASSERT().
02905   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
02906   InitializeListHead(), then ASSERT().
02907   If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
02908   of nodes in ListHead, including the ListHead node, is greater than or
02909   equal to PcdMaximumLinkedListLength, then ASSERT().
02910 
02911   @param  ListHead  A pointer to the head node of a doubly linked list.
02912   @param  Entry     A pointer to a node that is to be inserted at the beginning
02913                     of a doubly linked list.
02914 
02915   @return ListHead
02916 
02917 **/
02918 LIST_ENTRY *
02919 EFIAPI
02920 InsertHeadList (
02921   IN OUT  LIST_ENTRY                *ListHead,
02922   IN OUT  LIST_ENTRY                *Entry
02923   );
02924 
02925 
02926 /**
02927   Adds a node to the end of a doubly linked list, and returns the pointer to
02928   the head node of the doubly linked list.
02929 
02930   Adds the node Entry to the end of the doubly linked list denoted by ListHead,
02931   and returns ListHead.
02932 
02933   If ListHead is NULL, then ASSERT().
02934   If Entry is NULL, then ASSERT().
02935   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
02936   InitializeListHead(), then ASSERT().
02937   If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
02938   of nodes in ListHead, including the ListHead node, is greater than or
02939   equal to PcdMaximumLinkedListLength, then ASSERT().
02940 
02941   @param  ListHead  A pointer to the head node of a doubly linked list.
02942   @param  Entry     A pointer to a node that is to be added at the end of the
02943                     doubly linked list.
02944 
02945   @return ListHead
02946 
02947 **/
02948 LIST_ENTRY *
02949 EFIAPI
02950 InsertTailList (
02951   IN OUT  LIST_ENTRY                *ListHead,
02952   IN OUT  LIST_ENTRY                *Entry
02953   );
02954 
02955 
02956 /**
02957   Retrieves the first node of a doubly linked list.
02958 
02959   Returns the first node of a doubly linked list.  List must have been
02960   initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
02961   If List is empty, then List is returned.
02962 
02963   If List is NULL, then ASSERT().
02964   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
02965   InitializeListHead(), then ASSERT().
02966   If PcdMaximumLinkedListLength is not zero, and the number of nodes
02967   in List, including the List node, is greater than or equal to
02968   PcdMaximumLinkedListLength, then ASSERT().
02969 
02970   @param  List  A pointer to the head node of a doubly linked list.
02971 
02972   @return The first node of a doubly linked list.
02973   @retval List  The list is empty.
02974 
02975 **/
02976 LIST_ENTRY *
02977 EFIAPI
02978 GetFirstNode (
02979   IN      CONST LIST_ENTRY          *List
02980   );
02981 
02982 
02983 /**
02984   Retrieves the next node of a doubly linked list.
02985 
02986   Returns the node of a doubly linked list that follows Node.
02987   List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
02988   or InitializeListHead().  If List is empty, then List is returned.
02989 
02990   If List is NULL, then ASSERT().
02991   If Node is NULL, then ASSERT().
02992   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
02993   InitializeListHead(), then ASSERT().
02994   If PcdMaximumLinkedListLength is not zero, and List contains more than
02995   PcdMaximumLinkedListLength nodes, then ASSERT().
02996   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
02997 
02998   @param  List  A pointer to the head node of a doubly linked list.
02999   @param  Node  A pointer to a node in the doubly linked list.
03000 
03001   @return The pointer to the next node if one exists. Otherwise List is returned.
03002 
03003 **/
03004 LIST_ENTRY *
03005 EFIAPI
03006 GetNextNode (
03007   IN      CONST LIST_ENTRY          *List,
03008   IN      CONST LIST_ENTRY          *Node
03009   );
03010 
03011 
03012 /**
03013   Retrieves the previous node of a doubly linked list.
03014 
03015   Returns the node of a doubly linked list that precedes Node.
03016   List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
03017   or InitializeListHead().  If List is empty, then List is returned.
03018 
03019   If List is NULL, then ASSERT().
03020   If Node is NULL, then ASSERT().
03021   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
03022   InitializeListHead(), then ASSERT().
03023   If PcdMaximumLinkedListLength is not zero, and List contains more than
03024   PcdMaximumLinkedListLength nodes, then ASSERT().
03025   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
03026 
03027   @param  List  A pointer to the head node of a doubly linked list.
03028   @param  Node  A pointer to a node in the doubly linked list.
03029 
03030   @return The pointer to the previous node if one exists. Otherwise List is returned.
03031 
03032 **/
03033 LIST_ENTRY *
03034 EFIAPI
03035 GetPreviousNode (
03036   IN      CONST LIST_ENTRY          *List,
03037   IN      CONST LIST_ENTRY          *Node
03038   );
03039 
03040 
03041 /**
03042   Checks to see if a doubly linked list is empty or not.
03043 
03044   Checks to see if the doubly linked list is empty. If the linked list contains
03045   zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
03046 
03047   If ListHead is NULL, then ASSERT().
03048   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
03049   InitializeListHead(), then ASSERT().
03050   If PcdMaximumLinkedListLength is not zero, and the number of nodes
03051   in List, including the List node, is greater than or equal to
03052   PcdMaximumLinkedListLength, then ASSERT().
03053 
03054   @param  ListHead  A pointer to the head node of a doubly linked list.
03055 
03056   @retval TRUE  The linked list is empty.
03057   @retval FALSE The linked list is not empty.
03058 
03059 **/
03060 BOOLEAN
03061 EFIAPI
03062 IsListEmpty (
03063   IN      CONST LIST_ENTRY          *ListHead
03064   );
03065 
03066 
03067 /**
03068   Determines if a node in a doubly linked list is the head node of a the same
03069   doubly linked list.  This function is typically used to terminate a loop that
03070   traverses all the nodes in a doubly linked list starting with the head node.
03071 
03072   Returns TRUE if Node is equal to List.  Returns FALSE if Node is one of the
03073   nodes in the doubly linked list specified by List.  List must have been
03074   initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
03075 
03076   If List is NULL, then ASSERT().
03077   If Node is NULL, then ASSERT().
03078   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
03079   then ASSERT().
03080   If PcdMaximumLinkedListLength is not zero, and the number of nodes
03081   in List, including the List node, is greater than or equal to
03082   PcdMaximumLinkedListLength, then ASSERT().
03083   If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
03084   to List, then ASSERT().
03085 
03086   @param  List  A pointer to the head node of a doubly linked list.
03087   @param  Node  A pointer to a node in the doubly linked list.
03088 
03089   @retval TRUE  Node is the head of the doubly-linked list pointed by List.
03090   @retval FALSE Node is not the head of the doubly-linked list pointed by List.
03091 
03092 **/
03093 BOOLEAN
03094 EFIAPI
03095 IsNull (
03096   IN      CONST LIST_ENTRY          *List,
03097   IN      CONST LIST_ENTRY          *Node
03098   );
03099 
03100 
03101 /**
03102   Determines if a node the last node in a doubly linked list.
03103 
03104   Returns TRUE if Node is the last node in the doubly linked list specified by
03105   List. Otherwise, FALSE is returned. List must have been initialized with
03106   INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
03107 
03108   If List is NULL, then ASSERT().
03109   If Node is NULL, then ASSERT().
03110   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
03111   InitializeListHead(), then ASSERT().
03112   If PcdMaximumLinkedListLength is not zero, and the number of nodes
03113   in List, including the List node, is greater than or equal to
03114   PcdMaximumLinkedListLength, then ASSERT().
03115   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
03116 
03117   @param  List  A pointer to the head node of a doubly linked list.
03118   @param  Node  A pointer to a node in the doubly linked list.
03119 
03120   @retval TRUE  Node is the last node in the linked list.
03121   @retval FALSE Node is not the last node in the linked list.
03122 
03123 **/
03124 BOOLEAN
03125 EFIAPI
03126 IsNodeAtEnd (
03127   IN      CONST LIST_ENTRY          *List,
03128   IN      CONST LIST_ENTRY          *Node
03129   );
03130 
03131 
03132 /**
03133   Swaps the location of two nodes in a doubly linked list, and returns the
03134   first node after the swap.
03135 
03136   If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
03137   Otherwise, the location of the FirstEntry node is swapped with the location
03138   of the SecondEntry node in a doubly linked list. SecondEntry must be in the
03139   same double linked list as FirstEntry and that double linked list must have
03140   been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
03141   SecondEntry is returned after the nodes are swapped.
03142 
03143   If FirstEntry is NULL, then ASSERT().
03144   If SecondEntry is NULL, then ASSERT().
03145   If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
03146   same linked list, then ASSERT().
03147   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
03148   linked list containing the FirstEntry and SecondEntry nodes, including
03149   the FirstEntry and SecondEntry nodes, is greater than or equal to
03150   PcdMaximumLinkedListLength, then ASSERT().
03151 
03152   @param  FirstEntry  A pointer to a node in a linked list.
03153   @param  SecondEntry A pointer to another node in the same linked list.
03154 
03155   @return SecondEntry.
03156 
03157 **/
03158 LIST_ENTRY *
03159 EFIAPI
03160 SwapListEntries (
03161   IN OUT  LIST_ENTRY                *FirstEntry,
03162   IN OUT  LIST_ENTRY                *SecondEntry
03163   );
03164 
03165 
03166 /**
03167   Removes a node from a doubly linked list, and returns the node that follows
03168   the removed node.
03169 
03170   Removes the node Entry from a doubly linked list. It is up to the caller of
03171   this function to release the memory used by this node if that is required. On
03172   exit, the node following Entry in the doubly linked list is returned. If
03173   Entry is the only node in the linked list, then the head node of the linked
03174   list is returned.
03175 
03176   If Entry is NULL, then ASSERT().
03177   If Entry is the head node of an empty list, then ASSERT().
03178   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
03179   linked list containing Entry, including the Entry node, is greater than
03180   or equal to PcdMaximumLinkedListLength, then ASSERT().
03181 
03182   @param  Entry A pointer to a node in a linked list.
03183 
03184   @return Entry.
03185 
03186 **/
03187 LIST_ENTRY *
03188 EFIAPI
03189 RemoveEntryList (
03190   IN      CONST LIST_ENTRY          *Entry
03191   );
03192 
03193 //
03194 // Math Services
03195 //
03196 
03197 /**
03198   Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
03199   with zeros. The shifted value is returned.
03200 
03201   This function shifts the 64-bit value Operand to the left by Count bits. The
03202   low Count bits are set to zero. The shifted value is returned.
03203 
03204   If Count is greater than 63, then ASSERT().
03205 
03206   @param  Operand The 64-bit operand to shift left.
03207   @param  Count   The number of bits to shift left.
03208 
03209   @return Operand << Count.
03210 
03211 **/
03212 UINT64
03213 EFIAPI
03214 LShiftU64 (
03215   IN      UINT64                    Operand,
03216   IN      UINTN                     Count
03217   );
03218 
03219 
03220 /**
03221   Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
03222   filled with zeros. The shifted value is returned.
03223 
03224   This function shifts the 64-bit value Operand to the right by Count bits. The
03225   high Count bits are set to zero. The shifted value is returned.
03226 
03227   If Count is greater than 63, then ASSERT().
03228 
03229   @param  Operand The 64-bit operand to shift right.
03230   @param  Count   The number of bits to shift right.
03231 
03232   @return Operand >> Count
03233 
03234 **/
03235 UINT64
03236 EFIAPI
03237 RShiftU64 (
03238   IN      UINT64                    Operand,
03239   IN      UINTN                     Count
03240   );
03241 
03242 
03243 /**
03244   Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
03245   with original integer's bit 63. The shifted value is returned.
03246 
03247   This function shifts the 64-bit value Operand to the right by Count bits. The
03248   high Count bits are set to bit 63 of Operand.  The shifted value is returned.
03249 
03250   If Count is greater than 63, then ASSERT().
03251 
03252   @param  Operand The 64-bit operand to shift right.
03253   @param  Count   The number of bits to shift right.
03254 
03255   @return Operand >> Count
03256 
03257 **/
03258 UINT64
03259 EFIAPI
03260 ARShiftU64 (
03261   IN      UINT64                    Operand,
03262   IN      UINTN                     Count
03263   );
03264 
03265 
03266 /**
03267   Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
03268   with the high bits that were rotated.
03269 
03270   This function rotates the 32-bit value Operand to the left by Count bits. The
03271   low Count bits are fill with the high Count bits of Operand. The rotated
03272   value is returned.
03273 
03274   If Count is greater than 31, then ASSERT().
03275 
03276   @param  Operand The 32-bit operand to rotate left.
03277   @param  Count   The number of bits to rotate left.
03278 
03279   @return Operand << Count
03280 
03281 **/
03282 UINT32
03283 EFIAPI
03284 LRotU32 (
03285   IN      UINT32                    Operand,
03286   IN      UINTN                     Count
03287   );
03288 
03289 
03290 /**
03291   Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
03292   with the low bits that were rotated.
03293 
03294   This function rotates the 32-bit value Operand to the right by Count bits.
03295   The high Count bits are fill with the low Count bits of Operand. The rotated
03296   value is returned.
03297 
03298   If Count is greater than 31, then ASSERT().
03299 
03300   @param  Operand The 32-bit operand to rotate right.
03301   @param  Count   The number of bits to rotate right.
03302 
03303   @return Operand >> Count
03304 
03305 **/
03306 UINT32
03307 EFIAPI
03308 RRotU32 (
03309   IN      UINT32                    Operand,
03310   IN      UINTN                     Count
03311   );
03312 
03313 
03314 /**
03315   Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
03316   with the high bits that were rotated.
03317 
03318   This function rotates the 64-bit value Operand to the left by Count bits. The
03319   low Count bits are fill with the high Count bits of Operand. The rotated
03320   value is returned.
03321 
03322   If Count is greater than 63, then ASSERT().
03323 
03324   @param  Operand The 64-bit operand to rotate left.
03325   @param  Count   The number of bits to rotate left.
03326 
03327   @return Operand << Count
03328 
03329 **/
03330 UINT64
03331 EFIAPI
03332 LRotU64 (
03333   IN      UINT64                    Operand,
03334   IN      UINTN                     Count
03335   );
03336 
03337 
03338 /**
03339   Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
03340   with the high low bits that were rotated.
03341 
03342   This function rotates the 64-bit value Operand to the right by Count bits.
03343   The high Count bits are fill with the low Count bits of Operand. The rotated
03344   value is returned.
03345 
03346   If Count is greater than 63, then ASSERT().
03347 
03348   @param  Operand The 64-bit operand to rotate right.
03349   @param  Count   The number of bits to rotate right.
03350 
03351   @return Operand >> Count
03352 
03353 **/
03354 UINT64
03355 EFIAPI
03356 RRotU64 (
03357   IN      UINT64                    Operand,
03358   IN      UINTN                     Count
03359   );
03360 
03361 
03362 /**
03363   Returns the bit position of the lowest bit set in a 32-bit value.
03364 
03365   This function computes the bit position of the lowest bit set in the 32-bit
03366   value specified by Operand. If Operand is zero, then -1 is returned.
03367   Otherwise, a value between 0 and 31 is returned.
03368 
03369   @param  Operand The 32-bit operand to evaluate.
03370 
03371   @retval 0..31  The lowest bit set in Operand was found.
03372   @retval -1    Operand is zero.
03373 
03374 **/
03375 INTN
03376 EFIAPI
03377 LowBitSet32 (
03378   IN      UINT32                    Operand
03379   );
03380 
03381 
03382 /**
03383   Returns the bit position of the lowest bit set in a 64-bit value.
03384 
03385   This function computes the bit position of the lowest bit set in the 64-bit
03386   value specified by Operand. If Operand is zero, then -1 is returned.
03387   Otherwise, a value between 0 and 63 is returned.
03388 
03389   @param  Operand The 64-bit operand to evaluate.
03390 
03391   @retval 0..63  The lowest bit set in Operand was found.
03392   @retval -1    Operand is zero.
03393 
03394 
03395 **/
03396 INTN
03397 EFIAPI
03398 LowBitSet64 (
03399   IN      UINT64                    Operand
03400   );
03401 
03402 
03403 /**
03404   Returns the bit position of the highest bit set in a 32-bit value. Equivalent
03405   to log2(x).
03406 
03407   This function computes the bit position of the highest bit set in the 32-bit
03408   value specified by Operand. If Operand is zero, then -1 is returned.
03409   Otherwise, a value between 0 and 31 is returned.
03410 
03411   @param  Operand The 32-bit operand to evaluate.
03412 
03413   @retval 0..31  Position of the highest bit set in Operand if found.
03414   @retval -1    Operand is zero.
03415 
03416 **/
03417 INTN
03418 EFIAPI
03419 HighBitSet32 (
03420   IN      UINT32                    Operand
03421   );
03422 
03423 
03424 /**
03425   Returns the bit position of the highest bit set in a 64-bit value. Equivalent
03426   to log2(x).
03427 
03428   This function computes the bit position of the highest bit set in the 64-bit
03429   value specified by Operand. If Operand is zero, then -1 is returned.
03430   Otherwise, a value between 0 and 63 is returned.
03431 
03432   @param  Operand The 64-bit operand to evaluate.
03433 
03434   @retval 0..63   Position of the highest bit set in Operand if found.
03435   @retval -1     Operand is zero.
03436 
03437 **/
03438 INTN
03439 EFIAPI
03440 HighBitSet64 (
03441   IN      UINT64                    Operand
03442   );
03443 
03444 
03445 /**
03446   Returns the value of the highest bit set in a 32-bit value. Equivalent to
03447   1 << log2(x).
03448 
03449   This function computes the value of the highest bit set in the 32-bit value
03450   specified by Operand. If Operand is zero, then zero is returned.
03451 
03452   @param  Operand The 32-bit operand to evaluate.
03453 
03454   @return 1 << HighBitSet32(Operand)
03455   @retval 0 Operand is zero.
03456 
03457 **/
03458 UINT32
03459 EFIAPI
03460 GetPowerOfTwo32 (
03461   IN      UINT32                    Operand
03462   );
03463 
03464 
03465 /**
03466   Returns the value of the highest bit set in a 64-bit value. Equivalent to
03467   1 << log2(x).
03468 
03469   This function computes the value of the highest bit set in the 64-bit value
03470   specified by Operand. If Operand is zero, then zero is returned.
03471 
03472   @param  Operand The 64-bit operand to evaluate.
03473 
03474   @return 1 << HighBitSet64(Operand)
03475   @retval 0 Operand is zero.
03476 
03477 **/
03478 UINT64
03479 EFIAPI
03480 GetPowerOfTwo64 (
03481   IN      UINT64                    Operand
03482   );
03483 
03484 
03485 /**
03486   Switches the endianness of a 16-bit integer.
03487 
03488   This function swaps the bytes in a 16-bit unsigned value to switch the value
03489   from little endian to big endian or vice versa. The byte swapped value is
03490   returned.
03491 
03492   @param  Value A 16-bit unsigned value.
03493 
03494   @return The byte swapped Value.
03495 
03496 **/
03497 UINT16
03498 EFIAPI
03499 SwapBytes16 (
03500   IN      UINT16                    Value
03501   );
03502 
03503 
03504 /**
03505   Switches the endianness of a 32-bit integer.
03506 
03507   This function swaps the bytes in a 32-bit unsigned value to switch the value
03508   from little endian to big endian or vice versa. The byte swapped value is
03509   returned.
03510 
03511   @param  Value A 32-bit unsigned value.
03512 
03513   @return The byte swapped Value.
03514 
03515 **/
03516 UINT32
03517 EFIAPI
03518 SwapBytes32 (
03519   IN      UINT32                    Value
03520   );
03521 
03522 
03523 /**
03524   Switches the endianness of a 64-bit integer.
03525 
03526   This function swaps the bytes in a 64-bit unsigned value to switch the value
03527   from little endian to big endian or vice versa. The byte swapped value is
03528   returned.
03529 
03530   @param  Value A 64-bit unsigned value.
03531 
03532   @return The byte swapped Value.
03533 
03534 **/
03535 UINT64
03536 EFIAPI
03537 SwapBytes64 (
03538   IN      UINT64                    Value
03539   );
03540 
03541 
03542 /**
03543   Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
03544   generates a 64-bit unsigned result.
03545 
03546   This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
03547   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
03548   bit unsigned result is returned.
03549 
03550   @param  Multiplicand  A 64-bit unsigned value.
03551   @param  Multiplier    A 32-bit unsigned value.
03552 
03553   @return Multiplicand * Multiplier
03554 
03555 **/
03556 UINT64
03557 EFIAPI
03558 MultU64x32 (
03559   IN      UINT64                    Multiplicand,
03560   IN      UINT32                    Multiplier
03561   );
03562 
03563 
03564 /**
03565   Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
03566   generates a 64-bit unsigned result.
03567 
03568   This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
03569   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
03570   bit unsigned result is returned.
03571 
03572   @param  Multiplicand  A 64-bit unsigned value.
03573   @param  Multiplier    A 64-bit unsigned value.
03574 
03575   @return Multiplicand * Multiplier.
03576 
03577 **/
03578 UINT64
03579 EFIAPI
03580 MultU64x64 (
03581   IN      UINT64                    Multiplicand,
03582   IN      UINT64                    Multiplier
03583   );
03584 
03585 
03586 /**
03587   Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
03588   64-bit signed result.
03589 
03590   This function multiples the 64-bit signed value Multiplicand by the 64-bit
03591   signed value Multiplier and generates a 64-bit signed result. This 64-bit
03592   signed result is returned.
03593 
03594   @param  Multiplicand  A 64-bit signed value.
03595   @param  Multiplier    A 64-bit signed value.
03596 
03597   @return Multiplicand * Multiplier
03598 
03599 **/
03600 INT64
03601 EFIAPI
03602 MultS64x64 (
03603   IN      INT64                     Multiplicand,
03604   IN      INT64                     Multiplier
03605   );
03606 
03607 
03608 /**
03609   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
03610   a 64-bit unsigned result.
03611 
03612   This function divides the 64-bit unsigned value Dividend by the 32-bit
03613   unsigned value Divisor and generates a 64-bit unsigned quotient. This
03614   function returns the 64-bit unsigned quotient.
03615 
03616   If Divisor is 0, then ASSERT().
03617 
03618   @param  Dividend  A 64-bit unsigned value.
03619   @param  Divisor   A 32-bit unsigned value.
03620 
03621   @return Dividend / Divisor.
03622 
03623 **/
03624 UINT64
03625 EFIAPI
03626 DivU64x32 (
03627   IN      UINT64                    Dividend,
03628   IN      UINT32                    Divisor
03629   );
03630 
03631 
03632 /**
03633   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
03634   a 32-bit unsigned remainder.
03635 
03636   This function divides the 64-bit unsigned value Dividend by the 32-bit
03637   unsigned value Divisor and generates a 32-bit remainder. This function
03638   returns the 32-bit unsigned remainder.
03639 
03640   If Divisor is 0, then ASSERT().
03641 
03642   @param  Dividend  A 64-bit unsigned value.
03643   @param  Divisor   A 32-bit unsigned value.
03644 
03645   @return Dividend % Divisor.
03646 
03647 **/
03648 UINT32
03649 EFIAPI
03650 ModU64x32 (
03651   IN      UINT64                    Dividend,
03652   IN      UINT32                    Divisor
03653   );
03654 
03655 
03656 /**
03657   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
03658   a 64-bit unsigned result and an optional 32-bit unsigned remainder.
03659 
03660   This function divides the 64-bit unsigned value Dividend by the 32-bit
03661   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
03662   is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
03663   This function returns the 64-bit unsigned quotient.
03664 
03665   If Divisor is 0, then ASSERT().
03666 
03667   @param  Dividend  A 64-bit unsigned value.
03668   @param  Divisor   A 32-bit unsigned value.
03669   @param  Remainder A pointer to a 32-bit unsigned value. This parameter is
03670                     optional and may be NULL.
03671 
03672   @return Dividend / Divisor.
03673 
03674 **/
03675 UINT64
03676 EFIAPI
03677 DivU64x32Remainder (
03678   IN      UINT64                    Dividend,
03679   IN      UINT32                    Divisor,
03680   OUT     UINT32                    *Remainder  OPTIONAL
03681   );
03682 
03683 
03684 /**
03685   Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
03686   a 64-bit unsigned result and an optional 64-bit unsigned remainder.
03687 
03688   This function divides the 64-bit unsigned value Dividend by the 64-bit
03689   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
03690   is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
03691   This function returns the 64-bit unsigned quotient.
03692 
03693   If Divisor is 0, then ASSERT().
03694 
03695   @param  Dividend  A 64-bit unsigned value.
03696   @param  Divisor   A 64-bit unsigned value.
03697   @param  Remainder A pointer to a 64-bit unsigned value. This parameter is
03698                     optional and may be NULL.
03699 
03700   @return Dividend / Divisor.
03701 
03702 **/
03703 UINT64
03704 EFIAPI
03705 DivU64x64Remainder (
03706   IN      UINT64                    Dividend,
03707   IN      UINT64                    Divisor,
03708   OUT     UINT64                    *Remainder  OPTIONAL
03709   );
03710 
03711 
03712 /**
03713   Divides a 64-bit signed integer by a 64-bit signed integer and generates a
03714   64-bit signed result and a optional 64-bit signed remainder.
03715 
03716   This function divides the 64-bit signed value Dividend by the 64-bit signed
03717   value Divisor and generates a 64-bit signed quotient. If Remainder is not
03718   NULL, then the 64-bit signed remainder is returned in Remainder. This
03719   function returns the 64-bit signed quotient.
03720 
03721   It is the caller's responsibility to not call this function with a Divisor of 0.
03722   If Divisor is 0, then the quotient and remainder should be assumed to be
03723   the largest negative integer.
03724 
03725   If Divisor is 0, then ASSERT().
03726 
03727   @param  Dividend  A 64-bit signed value.
03728   @param  Divisor   A 64-bit signed value.
03729   @param  Remainder A pointer to a 64-bit signed value. This parameter is
03730                     optional and may be NULL.
03731 
03732   @return Dividend / Divisor.
03733 
03734 **/
03735 INT64
03736 EFIAPI
03737 DivS64x64Remainder (
03738   IN      INT64                     Dividend,
03739   IN      INT64                     Divisor,
03740   OUT     INT64                     *Remainder  OPTIONAL
03741   );
03742 
03743 
03744 /**
03745   Reads a 16-bit value from memory that may be unaligned.
03746 
03747   This function returns the 16-bit value pointed to by Buffer. The function
03748   guarantees that the read operation does not produce an alignment fault.
03749 
03750   If the Buffer is NULL, then ASSERT().
03751 
03752   @param  Buffer  The pointer to a 16-bit value that may be unaligned.
03753 
03754   @return The 16-bit value read from Buffer.
03755 
03756 **/
03757 UINT16
03758 EFIAPI
03759 ReadUnaligned16 (
03760   IN CONST UINT16              *Buffer
03761   );
03762 
03763 
03764 /**
03765   Writes a 16-bit value to memory that may be unaligned.
03766 
03767   This function writes the 16-bit value specified by Value to Buffer. Value is
03768   returned. The function guarantees that the write operation does not produce
03769   an alignment fault.
03770 
03771   If the Buffer is NULL, then ASSERT().
03772 
03773   @param  Buffer  The pointer to a 16-bit value that may be unaligned.
03774   @param  Value   16-bit value to write to Buffer.
03775 
03776   @return The 16-bit value to write to Buffer.
03777 
03778 **/
03779 UINT16
03780 EFIAPI
03781 WriteUnaligned16 (
03782   OUT UINT16                    *Buffer,
03783   IN  UINT16                    Value
03784   );
03785 
03786 
03787 /**
03788   Reads a 24-bit value from memory that may be unaligned.
03789 
03790   This function returns the 24-bit value pointed to by Buffer. The function
03791   guarantees that the read operation does not produce an alignment fault.
03792 
03793   If the Buffer is NULL, then ASSERT().
03794 
03795   @param  Buffer  The pointer to a 24-bit value that may be unaligned.
03796 
03797   @return The 24-bit value read from Buffer.
03798 
03799 **/
03800 UINT32
03801 EFIAPI
03802 ReadUnaligned24 (
03803   IN CONST UINT32              *Buffer
03804   );
03805 
03806 
03807 /**
03808   Writes a 24-bit value to memory that may be unaligned.
03809 
03810   This function writes the 24-bit value specified by Value to Buffer. Value is
03811   returned. The function guarantees that the write operation does not produce
03812   an alignment fault.
03813 
03814   If the Buffer is NULL, then ASSERT().
03815 
03816   @param  Buffer  The pointer to a 24-bit value that may be unaligned.
03817   @param  Value   24-bit value to write to Buffer.
03818 
03819   @return The 24-bit value to write to Buffer.
03820 
03821 **/
03822 UINT32
03823 EFIAPI
03824 WriteUnaligned24 (
03825   OUT UINT32                    *Buffer,
03826   IN  UINT32                    Value
03827   );
03828 
03829 
03830 /**
03831   Reads a 32-bit value from memory that may be unaligned.
03832 
03833   This function returns the 32-bit value pointed to by Buffer. The function
03834   guarantees that the read operation does not produce an alignment fault.
03835 
03836   If the Buffer is NULL, then ASSERT().
03837 
03838   @param  Buffer  The pointer to a 32-bit value that may be unaligned.
03839 
03840   @return The 32-bit value read from Buffer.
03841 
03842 **/
03843 UINT32
03844 EFIAPI
03845 ReadUnaligned32 (
03846   IN CONST UINT32              *Buffer
03847   );
03848 
03849 
03850 /**
03851   Writes a 32-bit value to memory that may be unaligned.
03852 
03853   This function writes the 32-bit value specified by Value to Buffer. Value is
03854   returned. The function guarantees that the write operation does not produce
03855   an alignment fault.
03856 
03857   If the Buffer is NULL, then ASSERT().
03858 
03859   @param  Buffer  The pointer to a 32-bit value that may be unaligned.
03860   @param  Value   32-bit value to write to Buffer.
03861 
03862   @return The 32-bit value to write to Buffer.
03863 
03864 **/
03865 UINT32
03866 EFIAPI
03867 WriteUnaligned32 (
03868   OUT UINT32                    *Buffer,
03869   IN  UINT32                    Value
03870   );
03871 
03872 
03873 /**
03874   Reads a 64-bit value from memory that may be unaligned.
03875 
03876   This function returns the 64-bit value pointed to by Buffer. The function
03877   guarantees that the read operation does not produce an alignment fault.
03878 
03879   If the Buffer is NULL, then ASSERT().
03880 
03881   @param  Buffer  The pointer to a 64-bit value that may be unaligned.
03882 
03883   @return The 64-bit value read from Buffer.
03884 
03885 **/
03886 UINT64
03887 EFIAPI
03888 ReadUnaligned64 (
03889   IN CONST UINT64              *Buffer
03890   );
03891 
03892 
03893 /**
03894   Writes a 64-bit value to memory that may be unaligned.
03895 
03896   This function writes the 64-bit value specified by Value to Buffer. Value is
03897   returned. The function guarantees that the write operation does not produce
03898   an alignment fault.
03899 
03900   If the Buffer is NULL, then ASSERT().
03901 
03902   @param  Buffer  The pointer to a 64-bit value that may be unaligned.
03903   @param  Value   64-bit value to write to Buffer.
03904 
03905   @return The 64-bit value to write to Buffer.
03906 
03907 **/
03908 UINT64
03909 EFIAPI
03910 WriteUnaligned64 (
03911   OUT UINT64                    *Buffer,
03912   IN  UINT64                    Value
03913   );
03914 
03915 
03916 //
03917 // Bit Field Functions
03918 //
03919 
03920 /**
03921   Returns a bit field from an 8-bit value.
03922 
03923   Returns the bitfield specified by the StartBit and the EndBit from Operand.
03924 
03925   If 8-bit operations are not supported, then ASSERT().
03926   If StartBit is greater than 7, then ASSERT().
03927   If EndBit is greater than 7, then ASSERT().
03928   If EndBit is less than StartBit, then ASSERT().
03929 
03930   @param  Operand   Operand on which to perform the bitfield operation.
03931   @param  StartBit  The ordinal of the least significant bit in the bit field.
03932                     Range 0..7.
03933   @param  EndBit    The ordinal of the most significant bit in the bit field.
03934                     Range 0..7.
03935 
03936   @return The bit field read.
03937 
03938 **/
03939 UINT8
03940 EFIAPI
03941 BitFieldRead8 (
03942   IN      UINT8                     Operand,
03943   IN      UINTN                     StartBit,
03944   IN      UINTN                     EndBit
03945   );
03946 
03947 
03948 /**
03949   Writes a bit field to an 8-bit value, and returns the result.
03950 
03951   Writes Value to the bit field specified by the StartBit and the EndBit in
03952   Operand. All other bits in Operand are preserved. The new 8-bit value is
03953   returned.
03954 
03955   If 8-bit operations are not supported, then ASSERT().
03956   If StartBit is greater than 7, then ASSERT().
03957   If EndBit is greater than 7, then ASSERT().
03958   If EndBit is less than StartBit, then ASSERT().
03959   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
03960 
03961   @param  Operand   Operand on which to perform the bitfield operation.
03962   @param  StartBit  The ordinal of the least significant bit in the bit field.
03963                     Range 0..7.
03964   @param  EndBit    The ordinal of the most significant bit in the bit field.
03965                     Range 0..7.
03966   @param  Value     New value of the bit field.
03967 
03968   @return The new 8-bit value.
03969 
03970 **/
03971 UINT8
03972 EFIAPI
03973 BitFieldWrite8 (
03974   IN      UINT8                     Operand,
03975   IN      UINTN                     StartBit,
03976   IN      UINTN                     EndBit,
03977   IN      UINT8                     Value
03978   );
03979 
03980 
03981 /**
03982   Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
03983   result.
03984 
03985   Performs a bitwise OR between the bit field specified by StartBit
03986   and EndBit in Operand and the value specified by OrData. All other bits in
03987   Operand are preserved. The new 8-bit value is returned.
03988 
03989   If 8-bit operations are not supported, then ASSERT().
03990   If StartBit is greater than 7, then ASSERT().
03991   If EndBit is greater than 7, then ASSERT().
03992   If EndBit is less than StartBit, then ASSERT().
03993   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
03994 
03995   @param  Operand   Operand on which to perform the bitfield operation.
03996   @param  StartBit  The ordinal of the least significant bit in the bit field.
03997                     Range 0..7.
03998   @param  EndBit    The ordinal of the most significant bit in the bit field.
03999                     Range 0..7.
04000   @param  OrData    The value to OR with the read value from the value
04001 
04002   @return The new 8-bit value.
04003 
04004 **/
04005 UINT8
04006 EFIAPI
04007 BitFieldOr8 (
04008   IN      UINT8                     Operand,
04009   IN      UINTN                     StartBit,
04010   IN      UINTN                     EndBit,
04011   IN      UINT8                     OrData
04012   );
04013 
04014 
04015 /**
04016   Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
04017   the result.
04018 
04019   Performs a bitwise AND between the bit field specified by StartBit and EndBit
04020   in Operand and the value specified by AndData. All other bits in Operand are
04021   preserved. The new 8-bit value is returned.
04022 
04023   If 8-bit operations are not supported, then ASSERT().
04024   If StartBit is greater than 7, then ASSERT().
04025   If EndBit is greater than 7, then ASSERT().
04026   If EndBit is less than StartBit, then ASSERT().
04027   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04028 
04029   @param  Operand   Operand on which to perform the bitfield operation.
04030   @param  StartBit  The ordinal of the least significant bit in the bit field.
04031                     Range 0..7.
04032   @param  EndBit    The ordinal of the most significant bit in the bit field.
04033                     Range 0..7.
04034   @param  AndData   The value to AND with the read value from the value.
04035 
04036   @return The new 8-bit value.
04037 
04038 **/
04039 UINT8
04040 EFIAPI
04041 BitFieldAnd8 (
04042   IN      UINT8                     Operand,
04043   IN      UINTN                     StartBit,
04044   IN      UINTN                     EndBit,
04045   IN      UINT8                     AndData
04046   );
04047 
04048 
04049 /**
04050   Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
04051   bitwise OR, and returns the result.
04052 
04053   Performs a bitwise AND between the bit field specified by StartBit and EndBit
04054   in Operand and the value specified by AndData, followed by a bitwise
04055   OR with value specified by OrData. All other bits in Operand are
04056   preserved. The new 8-bit value is returned.
04057 
04058   If 8-bit operations are not supported, then ASSERT().
04059   If StartBit is greater than 7, then ASSERT().
04060   If EndBit is greater than 7, then ASSERT().
04061   If EndBit is less than StartBit, then ASSERT().
04062   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04063   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04064 
04065   @param  Operand   Operand on which to perform the bitfield operation.
04066   @param  StartBit  The ordinal of the least significant bit in the bit field.
04067                     Range 0..7.
04068   @param  EndBit    The ordinal of the most significant bit in the bit field.
04069                     Range 0..7.
04070   @param  AndData   The value to AND with the read value from the value.
04071   @param  OrData    The value to OR with the result of the AND operation.
04072 
04073   @return The new 8-bit value.
04074 
04075 **/
04076 UINT8
04077 EFIAPI
04078 BitFieldAndThenOr8 (
04079   IN      UINT8                     Operand,
04080   IN      UINTN                     StartBit,
04081   IN      UINTN                     EndBit,
04082   IN      UINT8                     AndData,
04083   IN      UINT8                     OrData
04084   );
04085 
04086 
04087 /**
04088   Returns a bit field from a 16-bit value.
04089 
04090   Returns the bitfield specified by the StartBit and the EndBit from Operand.
04091 
04092   If 16-bit operations are not supported, then ASSERT().
04093   If StartBit is greater than 15, then ASSERT().
04094   If EndBit is greater than 15, then ASSERT().
04095   If EndBit is less than StartBit, then ASSERT().
04096 
04097   @param  Operand   Operand on which to perform the bitfield operation.
04098   @param  StartBit  The ordinal of the least significant bit in the bit field.
04099                     Range 0..15.
04100   @param  EndBit    The ordinal of the most significant bit in the bit field.
04101                     Range 0..15.
04102 
04103   @return The bit field read.
04104 
04105 **/
04106 UINT16
04107 EFIAPI
04108 BitFieldRead16 (
04109   IN      UINT16                    Operand,
04110   IN      UINTN                     StartBit,
04111   IN      UINTN                     EndBit
04112   );
04113 
04114 
04115 /**
04116   Writes a bit field to a 16-bit value, and returns the result.
04117 
04118   Writes Value to the bit field specified by the StartBit and the EndBit in
04119   Operand. All other bits in Operand are preserved. The new 16-bit value is
04120   returned.
04121 
04122   If 16-bit operations are not supported, then ASSERT().
04123   If StartBit is greater than 15, then ASSERT().
04124   If EndBit is greater than 15, then ASSERT().
04125   If EndBit is less than StartBit, then ASSERT().
04126   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04127 
04128   @param  Operand   Operand on which to perform the bitfield operation.
04129   @param  StartBit  The ordinal of the least significant bit in the bit field.
04130                     Range 0..15.
04131   @param  EndBit    The ordinal of the most significant bit in the bit field.
04132                     Range 0..15.
04133   @param  Value     New value of the bit field.
04134 
04135   @return The new 16-bit value.
04136 
04137 **/
04138 UINT16
04139 EFIAPI
04140 BitFieldWrite16 (
04141   IN      UINT16                    Operand,
04142   IN      UINTN                     StartBit,
04143   IN      UINTN                     EndBit,
04144   IN      UINT16                    Value
04145   );
04146 
04147 
04148 /**
04149   Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
04150   result.
04151 
04152   Performs a bitwise OR between the bit field specified by StartBit
04153   and EndBit in Operand and the value specified by OrData. All other bits in
04154   Operand are preserved. The new 16-bit value is returned.
04155 
04156   If 16-bit operations are not supported, then ASSERT().
04157   If StartBit is greater than 15, then ASSERT().
04158   If EndBit is greater than 15, then ASSERT().
04159   If EndBit is less than StartBit, then ASSERT().
04160   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04161 
04162   @param  Operand   Operand on which to perform the bitfield operation.
04163   @param  StartBit  The ordinal of the least significant bit in the bit field.
04164                     Range 0..15.
04165   @param  EndBit    The ordinal of the most significant bit in the bit field.
04166                     Range 0..15.
04167   @param  OrData    The value to OR with the read value from the value
04168 
04169   @return The new 16-bit value.
04170 
04171 **/
04172 UINT16
04173 EFIAPI
04174 BitFieldOr16 (
04175   IN      UINT16                    Operand,
04176   IN      UINTN                     StartBit,
04177   IN      UINTN                     EndBit,
04178   IN      UINT16                    OrData
04179   );
04180 
04181 
04182 /**
04183   Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
04184   the result.
04185 
04186   Performs a bitwise AND between the bit field specified by StartBit and EndBit
04187   in Operand and the value specified by AndData. All other bits in Operand are
04188   preserved. The new 16-bit value is returned.
04189 
04190   If 16-bit operations are not supported, then ASSERT().
04191   If StartBit is greater than 15, then ASSERT().
04192   If EndBit is greater than 15, then ASSERT().
04193   If EndBit is less than StartBit, then ASSERT().
04194   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04195 
04196   @param  Operand   Operand on which to perform the bitfield operation.
04197   @param  StartBit  The ordinal of the least significant bit in the bit field.
04198                     Range 0..15.
04199   @param  EndBit    The ordinal of the most significant bit in the bit field.
04200                     Range 0..15.
04201   @param  AndData   The value to AND with the read value from the value
04202 
04203   @return The new 16-bit value.
04204 
04205 **/
04206 UINT16
04207 EFIAPI
04208 BitFieldAnd16 (
04209   IN      UINT16                    Operand,
04210   IN      UINTN                     StartBit,
04211   IN      UINTN                     EndBit,
04212   IN      UINT16                    AndData
04213   );
04214 
04215 
04216 /**
04217   Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
04218   bitwise OR, and returns the result.
04219 
04220   Performs a bitwise AND between the bit field specified by StartBit and EndBit
04221   in Operand and the value specified by AndData, followed by a bitwise
04222   OR with value specified by OrData. All other bits in Operand are
04223   preserved. The new 16-bit value is returned.
04224 
04225   If 16-bit operations are not supported, then ASSERT().
04226   If StartBit is greater than 15, then ASSERT().
04227   If EndBit is greater than 15, then ASSERT().
04228   If EndBit is less than StartBit, then ASSERT().
04229   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04230   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04231 
04232   @param  Operand   Operand on which to perform the bitfield operation.
04233   @param  StartBit  The ordinal of the least significant bit in the bit field.
04234                     Range 0..15.
04235   @param  EndBit    The ordinal of the most significant bit in the bit field.
04236                     Range 0..15.
04237   @param  AndData   The value to AND with the read value from the value.
04238   @param  OrData    The value to OR with the result of the AND operation.
04239 
04240   @return The new 16-bit value.
04241 
04242 **/
04243 UINT16
04244 EFIAPI
04245 BitFieldAndThenOr16 (
04246   IN      UINT16                    Operand,
04247   IN      UINTN                     StartBit,
04248   IN      UINTN                     EndBit,
04249   IN      UINT16                    AndData,
04250   IN      UINT16                    OrData
04251   );
04252 
04253 
04254 /**
04255   Returns a bit field from a 32-bit value.
04256 
04257   Returns the bitfield specified by the StartBit and the EndBit from Operand.
04258 
04259   If 32-bit operations are not supported, then ASSERT().
04260   If StartBit is greater than 31, then ASSERT().
04261   If EndBit is greater than 31, then ASSERT().
04262   If EndBit is less than StartBit, then ASSERT().
04263 
04264   @param  Operand   Operand on which to perform the bitfield operation.
04265   @param  StartBit  The ordinal of the least significant bit in the bit field.
04266                     Range 0..31.
04267   @param  EndBit    The ordinal of the most significant bit in the bit field.
04268                     Range 0..31.
04269 
04270   @return The bit field read.
04271 
04272 **/
04273 UINT32
04274 EFIAPI
04275 BitFieldRead32 (
04276   IN      UINT32                    Operand,
04277   IN      UINTN                     StartBit,
04278   IN      UINTN                     EndBit
04279   );
04280 
04281 
04282 /**
04283   Writes a bit field to a 32-bit value, and returns the result.
04284 
04285   Writes Value to the bit field specified by the StartBit and the EndBit in
04286   Operand. All other bits in Operand are preserved. The new 32-bit value is
04287   returned.
04288 
04289   If 32-bit operations are not supported, then ASSERT().
04290   If StartBit is greater than 31, then ASSERT().
04291   If EndBit is greater than 31, then ASSERT().
04292   If EndBit is less than StartBit, then ASSERT().
04293   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04294 
04295   @param  Operand   Operand on which to perform the bitfield operation.
04296   @param  StartBit  The ordinal of the least significant bit in the bit field.
04297                     Range 0..31.
04298   @param  EndBit    The ordinal of the most significant bit in the bit field.
04299                     Range 0..31.
04300   @param  Value     New value of the bit field.
04301 
04302   @return The new 32-bit value.
04303 
04304 **/
04305 UINT32
04306 EFIAPI
04307 BitFieldWrite32 (
04308   IN      UINT32                    Operand,
04309   IN      UINTN                     StartBit,
04310   IN      UINTN                     EndBit,
04311   IN      UINT32                    Value
04312   );
04313 
04314 
04315 /**
04316   Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
04317   result.
04318 
04319   Performs a bitwise OR between the bit field specified by StartBit
04320   and EndBit in Operand and the value specified by OrData. All other bits in
04321   Operand are preserved. The new 32-bit value is returned.
04322 
04323   If 32-bit operations are not supported, then ASSERT().
04324   If StartBit is greater than 31, then ASSERT().
04325   If EndBit is greater than 31, then ASSERT().
04326   If EndBit is less than StartBit, then ASSERT().
04327   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04328 
04329   @param  Operand   Operand on which to perform the bitfield operation.
04330   @param  StartBit  The ordinal of the least significant bit in the bit field.
04331                     Range 0..31.
04332   @param  EndBit    The ordinal of the most significant bit in the bit field.
04333                     Range 0..31.
04334   @param  OrData    The value to OR with the read value from the value.
04335 
04336   @return The new 32-bit value.
04337 
04338 **/
04339 UINT32
04340 EFIAPI
04341 BitFieldOr32 (
04342   IN      UINT32                    Operand,
04343   IN      UINTN                     StartBit,
04344   IN      UINTN                     EndBit,
04345   IN      UINT32                    OrData
04346   );
04347 
04348 
04349 /**
04350   Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
04351   the result.
04352 
04353   Performs a bitwise AND between the bit field specified by StartBit and EndBit
04354   in Operand and the value specified by AndData. All other bits in Operand are
04355   preserved. The new 32-bit value is returned.
04356 
04357   If 32-bit operations are not supported, then ASSERT().
04358   If StartBit is greater than 31, then ASSERT().
04359   If EndBit is greater than 31, then ASSERT().
04360   If EndBit is less than StartBit, then ASSERT().
04361   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04362 
04363   @param  Operand   Operand on which to perform the bitfield operation.
04364   @param  StartBit  The ordinal of the least significant bit in the bit field.
04365                     Range 0..31.
04366   @param  EndBit    The ordinal of the most significant bit in the bit field.
04367                     Range 0..31.
04368   @param  AndData   The value to AND with the read value from the value
04369 
04370   @return The new 32-bit value.
04371 
04372 **/
04373 UINT32
04374 EFIAPI
04375 BitFieldAnd32 (
04376   IN      UINT32                    Operand,
04377   IN      UINTN                     StartBit,
04378   IN      UINTN                     EndBit,
04379   IN      UINT32                    AndData
04380   );
04381 
04382 
04383 /**
04384   Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
04385   bitwise OR, and returns the result.
04386 
04387   Performs a bitwise AND between the bit field specified by StartBit and EndBit
04388   in Operand and the value specified by AndData, followed by a bitwise
04389   OR with value specified by OrData. All other bits in Operand are
04390   preserved. The new 32-bit value is returned.
04391 
04392   If 32-bit operations are not supported, then ASSERT().
04393   If StartBit is greater than 31, then ASSERT().
04394   If EndBit is greater than 31, then ASSERT().
04395   If EndBit is less than StartBit, then ASSERT().
04396   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04397   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04398 
04399   @param  Operand   Operand on which to perform the bitfield operation.
04400   @param  StartBit  The ordinal of the least significant bit in the bit field.
04401                     Range 0..31.
04402   @param  EndBit    The ordinal of the most significant bit in the bit field.
04403                     Range 0..31.
04404   @param  AndData   The value to AND with the read value from the value.
04405   @param  OrData    The value to OR with the result of the AND operation.
04406 
04407   @return The new 32-bit value.
04408 
04409 **/
04410 UINT32
04411 EFIAPI
04412 BitFieldAndThenOr32 (
04413   IN      UINT32                    Operand,
04414   IN      UINTN                     StartBit,
04415   IN      UINTN                     EndBit,
04416   IN      UINT32                    AndData,
04417   IN      UINT32                    OrData
04418   );
04419 
04420 
04421 /**
04422   Returns a bit field from a 64-bit value.
04423 
04424   Returns the bitfield specified by the StartBit and the EndBit from Operand.
04425 
04426   If 64-bit operations are not supported, then ASSERT().
04427   If StartBit is greater than 63, then ASSERT().
04428   If EndBit is greater than 63, then ASSERT().
04429   If EndBit is less than StartBit, then ASSERT().
04430 
04431   @param  Operand   Operand on which to perform the bitfield operation.
04432   @param  StartBit  The ordinal of the least significant bit in the bit field.
04433                     Range 0..63.
04434   @param  EndBit    The ordinal of the most significant bit in the bit field.
04435                     Range 0..63.
04436 
04437   @return The bit field read.
04438 
04439 **/
04440 UINT64
04441 EFIAPI
04442 BitFieldRead64 (
04443   IN      UINT64                    Operand,
04444   IN      UINTN                     StartBit,
04445   IN      UINTN                     EndBit
04446   );
04447 
04448 
04449 /**
04450   Writes a bit field to a 64-bit value, and returns the result.
04451 
04452   Writes Value to the bit field specified by the StartBit and the EndBit in
04453   Operand. All other bits in Operand are preserved. The new 64-bit value is
04454   returned.
04455 
04456   If 64-bit operations are not supported, then ASSERT().
04457   If StartBit is greater than 63, then ASSERT().
04458   If EndBit is greater than 63, then ASSERT().
04459   If EndBit is less than StartBit, then ASSERT().
04460   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04461 
04462   @param  Operand   Operand on which to perform the bitfield operation.
04463   @param  StartBit  The ordinal of the least significant bit in the bit field.
04464                     Range 0..63.
04465   @param  EndBit    The ordinal of the most significant bit in the bit field.
04466                     Range 0..63.
04467   @param  Value     New value of the bit field.
04468 
04469   @return The new 64-bit value.
04470 
04471 **/
04472 UINT64
04473 EFIAPI
04474 BitFieldWrite64 (
04475   IN      UINT64                    Operand,
04476   IN      UINTN                     StartBit,
04477   IN      UINTN                     EndBit,
04478   IN      UINT64                    Value
04479   );
04480 
04481 
04482 /**
04483   Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
04484   result.
04485 
04486   Performs a bitwise OR between the bit field specified by StartBit
04487   and EndBit in Operand and the value specified by OrData. All other bits in
04488   Operand are preserved. The new 64-bit value is returned.
04489 
04490   If 64-bit operations are not supported, then ASSERT().
04491   If StartBit is greater than 63, then ASSERT().
04492   If EndBit is greater than 63, then ASSERT().
04493   If EndBit is less than StartBit, then ASSERT().
04494   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04495 
04496   @param  Operand   Operand on which to perform the bitfield operation.
04497   @param  StartBit  The ordinal of the least significant bit in the bit field.
04498                     Range 0..63.
04499   @param  EndBit    The ordinal of the most significant bit in the bit field.
04500                     Range 0..63.
04501   @param  OrData    The value to OR with the read value from the value
04502 
04503   @return The new 64-bit value.
04504 
04505 **/
04506 UINT64
04507 EFIAPI
04508 BitFieldOr64 (
04509   IN      UINT64                    Operand,
04510   IN      UINTN                     StartBit,
04511   IN      UINTN                     EndBit,
04512   IN      UINT64                    OrData
04513   );
04514 
04515 
04516 /**
04517   Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
04518   the result.
04519 
04520   Performs a bitwise AND between the bit field specified by StartBit and EndBit
04521   in Operand and the value specified by AndData. All other bits in Operand are
04522   preserved. The new 64-bit value is returned.
04523 
04524   If 64-bit operations are not supported, then ASSERT().
04525   If StartBit is greater than 63, then ASSERT().
04526   If EndBit is greater than 63, then ASSERT().
04527   If EndBit is less than StartBit, then ASSERT().
04528   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04529 
04530   @param  Operand   Operand on which to perform the bitfield operation.
04531   @param  StartBit  The ordinal of the least significant bit in the bit field.
04532                     Range 0..63.
04533   @param  EndBit    The ordinal of the most significant bit in the bit field.
04534                     Range 0..63.
04535   @param  AndData   The value to AND with the read value from the value
04536 
04537   @return The new 64-bit value.
04538 
04539 **/
04540 UINT64
04541 EFIAPI
04542 BitFieldAnd64 (
04543   IN      UINT64                    Operand,
04544   IN      UINTN                     StartBit,
04545   IN      UINTN                     EndBit,
04546   IN      UINT64                    AndData
04547   );
04548 
04549 
04550 /**
04551   Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
04552   bitwise OR, and returns the result.
04553 
04554   Performs a bitwise AND between the bit field specified by StartBit and EndBit
04555   in Operand and the value specified by AndData, followed by a bitwise
04556   OR with value specified by OrData. All other bits in Operand are
04557   preserved. The new 64-bit value is returned.
04558 
04559   If 64-bit operations are not supported, then ASSERT().
04560   If StartBit is greater than 63, then ASSERT().
04561   If EndBit is greater than 63, then ASSERT().
04562   If EndBit is less than StartBit, then ASSERT().
04563   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04564   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
04565 
04566   @param  Operand   Operand on which to perform the bitfield operation.
04567   @param  StartBit  The ordinal of the least significant bit in the bit field.
04568                     Range 0..63.
04569   @param  EndBit    The ordinal of the most significant bit in the bit field.
04570                     Range 0..63.
04571   @param  AndData   The value to AND with the read value from the value.
04572   @param  OrData    The value to OR with the result of the AND operation.
04573 
04574   @return The new 64-bit value.
04575 
04576 **/
04577 UINT64
04578 EFIAPI
04579 BitFieldAndThenOr64 (
04580   IN      UINT64                    Operand,
04581   IN      UINTN                     StartBit,
04582   IN      UINTN                     EndBit,
04583   IN      UINT64                    AndData,
04584   IN      UINT64                    OrData
04585   );
04586 
04587 //
04588 // Base Library Checksum Functions
04589 //
04590 
04591 /**
04592   Returns the sum of all elements in a buffer in unit of UINT8.
04593   During calculation, the carry bits are dropped.
04594 
04595   This function calculates the sum of all elements in a buffer
04596   in unit of UINT8. The carry bits in result of addition are dropped.
04597   The result is returned as UINT8. If Length is Zero, then Zero is
04598   returned.
04599 
04600   If Buffer is NULL, then ASSERT().
04601   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
04602 
04603   @param  Buffer      The pointer to the buffer to carry out the sum operation.
04604   @param  Length      The size, in bytes, of Buffer.
04605 
04606   @return Sum         The sum of Buffer with carry bits dropped during additions.
04607 
04608 **/
04609 UINT8
04610 EFIAPI
04611 CalculateSum8 (
04612   IN      CONST UINT8              *Buffer,
04613   IN      UINTN                     Length
04614   );
04615 
04616 
04617 /**
04618   Returns the two's complement checksum of all elements in a buffer
04619   of 8-bit values.
04620 
04621   This function first calculates the sum of the 8-bit values in the
04622   buffer specified by Buffer and Length.  The carry bits in the result
04623   of addition are dropped. Then, the two's complement of the sum is
04624   returned.  If Length is 0, then 0 is returned.
04625 
04626   If Buffer is NULL, then ASSERT().
04627   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
04628 
04629   @param  Buffer      The pointer to the buffer to carry out the checksum operation.
04630   @param  Length      The size, in bytes, of Buffer.
04631 
04632   @return Checksum    The two's complement checksum of Buffer.
04633 
04634 **/
04635 UINT8
04636 EFIAPI
04637 CalculateCheckSum8 (
04638   IN      CONST UINT8              *Buffer,
04639   IN      UINTN                     Length
04640   );
04641 
04642 
04643 /**
04644   Returns the sum of all elements in a buffer of 16-bit values.  During
04645   calculation, the carry bits are dropped.
04646 
04647   This function calculates the sum of the 16-bit values in the buffer
04648   specified by Buffer and Length. The carry bits in result of addition are dropped.
04649   The 16-bit result is returned.  If Length is 0, then 0 is returned.
04650 
04651   If Buffer is NULL, then ASSERT().
04652   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
04653   If Length is not aligned on a 16-bit boundary, then ASSERT().
04654   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
04655 
04656   @param  Buffer      The pointer to the buffer to carry out the sum operation.
04657   @param  Length      The size, in bytes, of Buffer.
04658 
04659   @return Sum         The sum of Buffer with carry bits dropped during additions.
04660 
04661 **/
04662 UINT16
04663 EFIAPI
04664 CalculateSum16 (
04665   IN      CONST UINT16             *Buffer,
04666   IN      UINTN                     Length
04667   );
04668 
04669 
04670 /**
04671   Returns the two's complement checksum of all elements in a buffer of
04672   16-bit values.
04673 
04674   This function first calculates the sum of the 16-bit values in the buffer
04675   specified by Buffer and Length.  The carry bits in the result of addition
04676   are dropped. Then, the two's complement of the sum is returned.  If Length
04677   is 0, then 0 is returned.
04678 
04679   If Buffer is NULL, then ASSERT().
04680   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
04681   If Length is not aligned on a 16-bit boundary, then ASSERT().
04682   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
04683 
04684   @param  Buffer      The pointer to the buffer to carry out the checksum operation.
04685   @param  Length      The size, in bytes, of Buffer.
04686 
04687   @return Checksum    The two's complement checksum of Buffer.
04688 
04689 **/
04690 UINT16
04691 EFIAPI
04692 CalculateCheckSum16 (
04693   IN      CONST UINT16             *Buffer,
04694   IN      UINTN                     Length
04695   );
04696 
04697 
04698 /**
04699   Returns the sum of all elements in a buffer of 32-bit values. During
04700   calculation, the carry bits are dropped.
04701 
04702   This function calculates the sum of the 32-bit values in the buffer
04703   specified by Buffer and Length. The carry bits in result of addition are dropped.
04704   The 32-bit result is returned. If Length is 0, then 0 is returned.
04705 
04706   If Buffer is NULL, then ASSERT().
04707   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
04708   If Length is not aligned on a 32-bit boundary, then ASSERT().
04709   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
04710 
04711   @param  Buffer      The pointer to the buffer to carry out the sum operation.
04712   @param  Length      The size, in bytes, of Buffer.
04713 
04714   @return Sum         The sum of Buffer with carry bits dropped during additions.
04715 
04716 **/
04717 UINT32
04718 EFIAPI
04719 CalculateSum32 (
04720   IN      CONST UINT32             *Buffer,
04721   IN      UINTN                     Length
04722   );
04723 
04724 
04725 /**
04726   Returns the two's complement checksum of all elements in a buffer of
04727   32-bit values.
04728 
04729   This function first calculates the sum of the 32-bit values in the buffer
04730   specified by Buffer and Length.  The carry bits in the result of addition
04731   are dropped. Then, the two's complement of the sum is returned.  If Length
04732   is 0, then 0 is returned.
04733 
04734   If Buffer is NULL, then ASSERT().
04735   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
04736   If Length is not aligned on a 32-bit boundary, then ASSERT().
04737   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
04738 
04739   @param  Buffer      The pointer to the buffer to carry out the checksum operation.
04740   @param  Length      The size, in bytes, of Buffer.
04741 
04742   @return Checksum    The two's complement checksum of Buffer.
04743 
04744 **/
04745 UINT32
04746 EFIAPI
04747 CalculateCheckSum32 (
04748   IN      CONST UINT32             *Buffer,
04749   IN      UINTN                     Length
04750   );
04751 
04752 
04753 /**
04754   Returns the sum of all elements in a buffer of 64-bit values.  During
04755   calculation, the carry bits are dropped.
04756 
04757   This function calculates the sum of the 64-bit values in the buffer
04758   specified by Buffer and Length. The carry bits in result of addition are dropped.
04759   The 64-bit result is returned.  If Length is 0, then 0 is returned.
04760 
04761   If Buffer is NULL, then ASSERT().
04762   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
04763   If Length is not aligned on a 64-bit boundary, then ASSERT().
04764   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
04765 
04766   @param  Buffer      The pointer to the buffer to carry out the sum operation.
04767   @param  Length      The size, in bytes, of Buffer.
04768 
04769   @return Sum         The sum of Buffer with carry bits dropped during additions.
04770 
04771 **/
04772 UINT64
04773 EFIAPI
04774 CalculateSum64 (
04775   IN      CONST UINT64             *Buffer,
04776   IN      UINTN                     Length
04777   );
04778 
04779 
04780 /**
04781   Returns the two's complement checksum of all elements in a buffer of
04782   64-bit values.
04783 
04784   This function first calculates the sum of the 64-bit values in the buffer
04785   specified by Buffer and Length.  The carry bits in the result of addition
04786   are dropped. Then, the two's complement of the sum is returned.  If Length
04787   is 0, then 0 is returned.
04788 
04789   If Buffer is NULL, then ASSERT().
04790   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
04791   If Length is not aligned on a 64-bit boundary, then ASSERT().
04792   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
04793 
04794   @param  Buffer      The pointer to the buffer to carry out the checksum operation.
04795   @param  Length      The size, in bytes, of Buffer.
04796 
04797   @return Checksum    The two's complement checksum of Buffer.
04798 
04799 **/
04800 UINT64
04801 EFIAPI
04802 CalculateCheckSum64 (
04803   IN      CONST UINT64             *Buffer,
04804   IN      UINTN                     Length
04805   );
04806 
04807 
04808 //
04809 // Base Library CPU Functions
04810 //
04811 
04812 /**
04813   Function entry point used when a stack switch is requested with SwitchStack()
04814 
04815   @param  Context1        Context1 parameter passed into SwitchStack().
04816   @param  Context2        Context2 parameter passed into SwitchStack().
04817 
04818 **/
04819 typedef
04820 VOID
04821 (EFIAPI *SWITCH_STACK_ENTRY_POINT)(
04822   IN      VOID                      *Context1,  OPTIONAL
04823   IN      VOID                      *Context2   OPTIONAL
04824   );
04825 
04826 
04827 /**
04828   Used to serialize load and store operations.
04829 
04830   All loads and stores that proceed calls to this function are guaranteed to be
04831   globally visible when this function returns.
04832 
04833 **/
04834 VOID
04835 EFIAPI
04836 MemoryFence (
04837   VOID
04838   );
04839 
04840 
04841 /**
04842   Saves the current CPU context that can be restored with a call to LongJump()
04843   and returns 0.
04844 
04845   Saves the current CPU context in the buffer specified by JumpBuffer and
04846   returns 0. The initial call to SetJump() must always return 0. Subsequent
04847   calls to LongJump() cause a non-zero value to be returned by SetJump().
04848 
04849   If JumpBuffer is NULL, then ASSERT().
04850   For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
04851 
04852   NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
04853   The same structure must never be used for more than one CPU architecture context.
04854   For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
04855   SetJump()/LongJump() is not currently supported for the EBC processor type.
04856 
04857   @param  JumpBuffer  A pointer to CPU context buffer.
04858 
04859   @retval 0 Indicates a return from SetJump().
04860 
04861 **/
04862 UINTN
04863 EFIAPI
04864 SetJump (
04865   OUT     BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer
04866   );
04867 
04868 
04869 /**
04870   Restores the CPU context that was saved with SetJump().
04871 
04872   Restores the CPU context from the buffer specified by JumpBuffer. This
04873   function never returns to the caller. Instead is resumes execution based on
04874   the state of JumpBuffer.
04875 
04876   If JumpBuffer is NULL, then ASSERT().
04877   For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
04878   If Value is 0, then ASSERT().
04879 
04880   @param  JumpBuffer  A pointer to CPU context buffer.
04881   @param  Value       The value to return when the SetJump() context is
04882                       restored and must be non-zero.
04883 
04884 **/
04885 VOID
04886 EFIAPI
04887 LongJump (
04888   IN      BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer,
04889   IN      UINTN                     Value
04890   );
04891 
04892 
04893 /**
04894   Enables CPU interrupts.
04895 
04896 **/
04897 VOID
04898 EFIAPI
04899 EnableInterrupts (
04900   VOID
04901   );
04902 
04903 
04904 /**
04905   Disables CPU interrupts.
04906 
04907 **/
04908 VOID
04909 EFIAPI
04910 DisableInterrupts (
04911   VOID
04912   );
04913 
04914 
04915 /**
04916   Disables CPU interrupts and returns the interrupt state prior to the disable
04917   operation.
04918 
04919   @retval TRUE  CPU interrupts were enabled on entry to this call.
04920   @retval FALSE CPU interrupts were disabled on entry to this call.
04921 
04922 **/
04923 BOOLEAN
04924 EFIAPI
04925 SaveAndDisableInterrupts (
04926   VOID
04927   );
04928 
04929 
04930 /**
04931   Enables CPU interrupts for the smallest window required to capture any
04932   pending interrupts.
04933 
04934 **/
04935 VOID
04936 EFIAPI
04937 EnableDisableInterrupts (
04938   VOID
04939   );
04940 
04941 
04942 /**
04943   Retrieves the current CPU interrupt state.
04944 
04945   Returns TRUE if interrupts are currently enabled. Otherwise
04946   returns FALSE.
04947 
04948   @retval TRUE  CPU interrupts are enabled.
04949   @retval FALSE CPU interrupts are disabled.
04950 
04951 **/
04952 BOOLEAN
04953 EFIAPI
04954 GetInterruptState (
04955   VOID
04956   );
04957 
04958 
04959 /**
04960   Set the current CPU interrupt state.
04961 
04962   Sets the current CPU interrupt state to the state specified by
04963   InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
04964   InterruptState is FALSE, then interrupts are disabled. InterruptState is
04965   returned.
04966 
04967   @param  InterruptState  TRUE if interrupts should enabled. FALSE if
04968                           interrupts should be disabled.
04969 
04970   @return InterruptState
04971 
04972 **/
04973 BOOLEAN
04974 EFIAPI
04975 SetInterruptState (
04976   IN      BOOLEAN                   InterruptState
04977   );
04978 
04979 
04980 /**
04981   Requests CPU to pause for a short period of time.
04982 
04983   Requests CPU to pause for a short period of time. Typically used in MP
04984   systems to prevent memory starvation while waiting for a spin lock.
04985 
04986 **/
04987 VOID
04988 EFIAPI
04989 CpuPause (
04990   VOID
04991   );
04992 
04993 
04994 /**
04995   Transfers control to a function starting with a new stack.
04996 
04997   Transfers control to the function specified by EntryPoint using the
04998   new stack specified by NewStack and passing in the parameters specified
04999   by Context1 and Context2.  Context1 and Context2 are optional and may
05000   be NULL.  The function EntryPoint must never return.  This function
05001   supports a variable number of arguments following the NewStack parameter.
05002   These additional arguments are ignored on IA-32, x64, and EBC architectures.
05003   Itanium processors expect one additional parameter of type VOID * that specifies
05004   the new backing store pointer.
05005 
05006   If EntryPoint is NULL, then ASSERT().
05007   If NewStack is NULL, then ASSERT().
05008 
05009   @param  EntryPoint  A pointer to function to call with the new stack.
05010   @param  Context1    A pointer to the context to pass into the EntryPoint
05011                       function.
05012   @param  Context2    A pointer to the context to pass into the EntryPoint
05013                       function.
05014   @param  NewStack    A pointer to the new stack to use for the EntryPoint
05015                       function.
05016   @param  ...         This variable argument list is ignored for IA-32, x64, and
05017                       EBC architectures.  For Itanium processors, this variable
05018                       argument list is expected to contain a single parameter of
05019                       type VOID * that specifies the new backing store pointer.
05020 
05021 
05022 **/
05023 VOID
05024 EFIAPI
05025 SwitchStack (
05026   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
05027   IN      VOID                      *Context1,  OPTIONAL
05028   IN      VOID                      *Context2,  OPTIONAL
05029   IN      VOID                      *NewStack,
05030   ...
05031   );
05032 
05033 
05034 /**
05035   Generates a breakpoint on the CPU.
05036 
05037   Generates a breakpoint on the CPU. The breakpoint must be implemented such
05038   that code can resume normal execution after the breakpoint.
05039 
05040 **/
05041 VOID
05042 EFIAPI
05043 CpuBreakpoint (
05044   VOID
05045   );
05046 
05047 
05048 /**
05049   Executes an infinite loop.
05050 
05051   Forces the CPU to execute an infinite loop. A debugger may be used to skip
05052   past the loop and the code that follows the loop must execute properly. This
05053   implies that the infinite loop must not cause the code that follow it to be
05054   optimized away.
05055 
05056 **/
05057 VOID
05058 EFIAPI
05059 CpuDeadLoop (
05060   VOID
05061   );
05062 
05063 #if defined (MDE_CPU_IPF)
05064 
05065 /**
05066   Flush a range of  cache lines in the cache coherency domain of the calling
05067   CPU.
05068 
05069   Flushes the cache lines specified by Address and Length.  If Address is not aligned
05070   on a cache line boundary, then entire cache line containing Address is flushed.
05071   If Address + Length is not aligned on a cache line boundary, then the entire cache
05072   line containing Address + Length - 1 is flushed.  This function may choose to flush
05073   the entire cache if that is more efficient than flushing the specified range.  If
05074   Length is 0, the no cache lines are flushed.  Address is returned.
05075   This function is only available on Itanium processors.
05076 
05077   If Length is greater than (MAX_ADDRESS - Address + 1), then ASSERT().
05078 
05079   @param  Address The base address of the instruction lines to invalidate. If
05080                   the CPU is in a physical addressing mode, then Address is a
05081                   physical address. If the CPU is in a virtual addressing mode,
05082                   then Address is a virtual address.
05083 
05084   @param  Length  The number of bytes to invalidate from the instruction cache.
05085 
05086   @return Address.
05087 
05088 **/
05089 VOID *
05090 EFIAPI
05091 AsmFlushCacheRange (
05092   IN      VOID                      *Address,
05093   IN      UINTN                     Length
05094   );
05095 
05096 
05097 /**
05098   Executes an FC instruction.
05099   Executes an FC instruction on the cache line specified by Address.
05100   The cache line size affected is at least 32-bytes (aligned on a 32-byte boundary).
05101   An implementation may flush a larger region.  This function is only available on Itanium processors.
05102 
05103   @param Address    The Address of cache line to be flushed.
05104 
05105   @return The address of FC instruction executed.
05106 
05107 **/
05108 UINT64
05109 EFIAPI
05110 AsmFc (
05111   IN  UINT64  Address
05112   );
05113 
05114 
05115 /**
05116   Executes an FC.I instruction.
05117   Executes an FC.I instruction on the cache line specified by Address.
05118   The cache line size affected is at least 32-bytes (aligned on a 32-byte boundary).
05119   An implementation may flush a larger region.  This function is only available on Itanium processors.
05120 
05121   @param Address    The Address of cache line to be flushed.
05122 
05123   @return The address of the FC.I instruction executed.
05124 
05125 **/
05126 UINT64
05127 EFIAPI
05128 AsmFci (
05129   IN  UINT64  Address
05130   );
05131 
05132 
05133 /**
05134   Reads the current value of a Processor Identifier Register (CPUID).
05135 
05136   Reads and returns the current value of Processor Identifier Register specified by Index.
05137   The Index of largest implemented CPUID (One less than the number of implemented CPUID
05138   registers) is determined by CPUID [3] bits {7:0}.
05139   No parameter checking is performed on Index.  If the Index value is beyond the
05140   implemented CPUID register range, a Reserved Register/Field fault may occur.  The caller
05141   must either guarantee that Index is valid, or the caller must set up fault handlers to
05142   catch the faults.  This function is only available on Itanium processors.
05143 
05144   @param Index    The 8-bit Processor Identifier Register index to read.
05145 
05146   @return The current value of Processor Identifier Register specified by Index.
05147 
05148 **/
05149 UINT64
05150 EFIAPI
05151 AsmReadCpuid (
05152   IN  UINT8   Index
05153   );
05154 
05155 
05156 /**
05157   Reads the current value of 64-bit Processor Status Register (PSR).
05158   This function is only available on Itanium processors.
05159 
05160   @return The current value of PSR.
05161 
05162 **/
05163 UINT64
05164 EFIAPI
05165 AsmReadPsr (
05166   VOID
05167   );
05168 
05169 
05170 /**
05171   Writes the current value of 64-bit Processor Status Register (PSR).
05172 
05173   No parameter checking is performed on Value.  All bits of Value corresponding to
05174   reserved fields of PSR must be 0 or a Reserved Register/Field fault may occur.
05175   The caller must either guarantee that Value is valid, or the caller must set up
05176   fault handlers to catch the faults. This function is only available on Itanium processors.
05177 
05178   @param Value    The 64-bit value to write to PSR.
05179 
05180   @return The 64-bit value written to the PSR.
05181 
05182 **/
05183 UINT64
05184 EFIAPI
05185 AsmWritePsr (
05186   IN UINT64  Value
05187   );
05188 
05189 
05190 /**
05191   Reads the current value of 64-bit Kernel Register #0 (KR0).
05192 
05193   Reads and returns the current value of KR0.
05194   This function is only available on Itanium processors.
05195 
05196   @return The current value of KR0.
05197 
05198 **/
05199 UINT64
05200 EFIAPI
05201 AsmReadKr0 (
05202   VOID
05203   );
05204 
05205 
05206 /**
05207   Reads the current value of 64-bit Kernel Register #1 (KR1).
05208 
05209   Reads and returns the current value of KR1.
05210   This function is only available on Itanium processors.
05211 
05212   @return The current value of KR1.
05213 
05214 **/
05215 UINT64
05216 EFIAPI
05217 AsmReadKr1 (
05218   VOID
05219   );
05220 
05221 
05222 /**
05223   Reads the current value of 64-bit Kernel Register #2 (KR2).
05224 
05225   Reads and returns the current value of KR2.
05226   This function is only available on Itanium processors.
05227 
05228   @return The current value of KR2.
05229 
05230 **/
05231 UINT64
05232 EFIAPI
05233 AsmReadKr2 (
05234   VOID
05235   );
05236 
05237 
05238 /**
05239   Reads the current value of 64-bit Kernel Register #3 (KR3).
05240 
05241   Reads and returns the current value of KR3.
05242   This function is only available on Itanium processors.
05243 
05244   @return The current value of KR3.
05245 
05246 **/
05247 UINT64
05248 EFIAPI
05249 AsmReadKr3 (
05250   VOID
05251   );
05252 
05253 
05254 /**
05255   Reads the current value of 64-bit Kernel Register #4 (KR4).
05256 
05257   Reads and returns the current value of KR4.
05258   This function is only available on Itanium processors.
05259 
05260   @return The current value of KR4.
05261 
05262 **/
05263 UINT64
05264 EFIAPI
05265 AsmReadKr4 (
05266   VOID
05267   );
05268 
05269 
05270 /**
05271   Reads the current value of 64-bit Kernel Register #5 (KR5).
05272 
05273   Reads and returns the current value of KR5.
05274   This function is only available on Itanium processors.
05275 
05276   @return The current value of KR5.
05277 
05278 **/
05279 UINT64
05280 EFIAPI
05281 AsmReadKr5 (
05282   VOID
05283   );
05284 
05285 
05286 /**
05287   Reads the current value of 64-bit Kernel Register #6 (KR6).
05288 
05289   Reads and returns the current value of KR6.
05290   This function is only available on Itanium processors.
05291 
05292   @return The current value of KR6.
05293 
05294 **/
05295 UINT64
05296 EFIAPI
05297 AsmReadKr6 (
05298   VOID
05299   );
05300 
05301 
05302 /**
05303   Reads the current value of 64-bit Kernel Register #7 (KR7).
05304 
05305   Reads and returns the current value of KR7.
05306   This function is only available on Itanium processors.
05307 
05308   @return The current value of KR7.
05309 
05310 **/
05311 UINT64
05312 EFIAPI
05313 AsmReadKr7 (
05314   VOID
05315   );
05316 
05317 
05318 /**
05319   Write the current value of 64-bit Kernel Register #0 (KR0).
05320 
05321   Writes the current value of KR0.  The 64-bit value written to
05322   the KR0 is returned. This function is only available on Itanium processors.
05323 
05324   @param  Value   The 64-bit value to write to KR0.
05325 
05326   @return The 64-bit value written to the KR0.
05327 
05328 **/
05329 UINT64
05330 EFIAPI
05331 AsmWriteKr0 (
05332   IN UINT64  Value
05333   );
05334 
05335 
05336 /**
05337   Write the current value of 64-bit Kernel Register #1 (KR1).
05338 
05339   Writes the current value of KR1.  The 64-bit value written to
05340   the KR1 is returned. This function is only available on Itanium processors.
05341 
05342   @param  Value   The 64-bit value to write to KR1.
05343 
05344   @return The 64-bit value written to the KR1.
05345 
05346 **/
05347 UINT64
05348 EFIAPI
05349 AsmWriteKr1 (
05350   IN UINT64  Value
05351   );
05352 
05353 
05354 /**
05355   Write the current value of 64-bit Kernel Register #2 (KR2).
05356 
05357   Writes the current value of KR2.  The 64-bit value written to
05358   the KR2 is returned. This function is only available on Itanium processors.
05359 
05360   @param  Value   The 64-bit value to write to KR2.
05361 
05362   @return The 64-bit value written to the KR2.
05363 
05364 **/
05365 UINT64
05366 EFIAPI
05367 AsmWriteKr2 (
05368   IN UINT64  Value
05369   );
05370 
05371 
05372 /**
05373   Write the current value of 64-bit Kernel Register #3 (KR3).
05374 
05375   Writes the current value of KR3.  The 64-bit value written to
05376   the KR3 is returned. This function is only available on Itanium processors.
05377 
05378   @param  Value   The 64-bit value to write to KR3.
05379 
05380   @return The 64-bit value written to the KR3.
05381 
05382 **/
05383 UINT64
05384 EFIAPI
05385 AsmWriteKr3 (
05386   IN UINT64  Value
05387   );
05388 
05389 
05390 /**
05391   Write the current value of 64-bit Kernel Register #4 (KR4).
05392 
05393   Writes the current value of KR4.  The 64-bit value written to
05394   the KR4 is returned. This function is only available on Itanium processors.
05395 
05396   @param  Value   The 64-bit value to write to KR4.
05397 
05398   @return The 64-bit value written to the KR4.
05399 
05400 **/
05401 UINT64
05402 EFIAPI
05403 AsmWriteKr4 (
05404   IN UINT64  Value
05405   );
05406 
05407 
05408 /**
05409   Write the current value of 64-bit Kernel Register #5 (KR5).
05410 
05411   Writes the current value of KR5.  The 64-bit value written to
05412   the KR5 is returned. This function is only available on Itanium processors.
05413 
05414   @param  Value   The 64-bit value to write to KR5.
05415 
05416   @return The 64-bit value written to the KR5.
05417 
05418 **/
05419 UINT64
05420 EFIAPI
05421 AsmWriteKr5 (
05422   IN UINT64  Value
05423   );
05424 
05425 
05426 /**
05427   Write the current value of 64-bit Kernel Register #6 (KR6).
05428 
05429   Writes the current value of KR6.  The 64-bit value written to
05430   the KR6 is returned. This function is only available on Itanium processors.
05431 
05432   @param  Value   The 64-bit value to write to KR6.
05433 
05434   @return The 64-bit value written to the KR6.
05435 
05436 **/
05437 UINT64
05438 EFIAPI
05439 AsmWriteKr6 (
05440   IN UINT64  Value
05441   );
05442 
05443 
05444 /**
05445   Write the current value of 64-bit Kernel Register #7 (KR7).
05446 
05447   Writes the current value of KR7.  The 64-bit value written to
05448   the KR7 is returned. This function is only available on Itanium processors.
05449 
05450   @param  Value   The 64-bit value to write to KR7.
05451 
05452   @return The 64-bit value written to the KR7.
05453 
05454 **/
05455 UINT64
05456 EFIAPI
05457 AsmWriteKr7 (
05458   IN UINT64  Value
05459   );
05460 
05461 
05462 /**
05463   Reads the current value of Interval Timer Counter Register (ITC).
05464 
05465   Reads and returns the current value of ITC.
05466   This function is only available on Itanium processors.
05467 
05468   @return The current value of ITC.
05469 
05470 **/
05471 UINT64
05472 EFIAPI
05473 AsmReadItc (
05474   VOID
05475   );
05476 
05477 
05478 /**
05479   Reads the current value of Interval Timer Vector Register (ITV).
05480 
05481   Reads and returns the current value of ITV.
05482   This function is only available on Itanium processors.
05483 
05484   @return The current value of ITV.
05485 
05486 **/
05487 UINT64
05488 EFIAPI
05489 AsmReadItv (
05490   VOID
05491   );
05492 
05493 
05494 /**
05495   Reads the current value of Interval Timer Match Register (ITM).
05496 
05497   Reads and returns the current value of ITM.
05498   This function is only available on Itanium processors.
05499 
05500   @return The current value of ITM.
05501 **/
05502 UINT64
05503 EFIAPI
05504 AsmReadItm (
05505   VOID
05506   );
05507 
05508 
05509 /**
05510   Writes the current value of 64-bit Interval Timer Counter Register (ITC).
05511 
05512   Writes the current value of ITC.  The 64-bit value written to the ITC is returned.
05513   This function is only available on Itanium processors.
05514 
05515   @param Value    The 64-bit value to write to ITC.
05516 
05517   @return The 64-bit value written to the ITC.
05518 
05519 **/
05520 UINT64
05521 EFIAPI
05522 AsmWriteItc (
05523   IN UINT64  Value
05524   );
05525 
05526 
05527 /**
05528   Writes the current value of 64-bit Interval Timer Match Register (ITM).
05529 
05530   Writes the current value of ITM.  The 64-bit value written to the ITM is returned.
05531   This function is only available on Itanium processors.
05532 
05533   @param Value    The 64-bit value to write to ITM.
05534 
05535   @return The 64-bit value written to the ITM.
05536 
05537 **/
05538 UINT64
05539 EFIAPI
05540 AsmWriteItm (
05541   IN UINT64  Value
05542   );
05543 
05544 
05545 /**
05546   Writes the current value of 64-bit Interval Timer Vector Register (ITV).
05547 
05548   Writes the current value of ITV.  The 64-bit value written to the ITV is returned.
05549   No parameter checking is performed on Value.  All bits of Value corresponding to
05550   reserved fields of ITV must be 0 or a Reserved Register/Field fault may occur.
05551   The caller must either guarantee that Value is valid, or the caller must set up
05552   fault handlers to catch the faults.
05553   This function is only available on Itanium processors.
05554 
05555   @param Value    The 64-bit value to write to ITV.
05556 
05557   @return The 64-bit value written to the ITV.
05558 
05559 **/
05560 UINT64
05561 EFIAPI
05562 AsmWriteItv (
05563   IN UINT64  Value
05564   );
05565 
05566 
05567 /**
05568   Reads the current value of Default Control Register (DCR).
05569 
05570   Reads and returns the current value of DCR.  This function is only available on Itanium processors.
05571 
05572   @return The current value of DCR.
05573 
05574 **/
05575 UINT64
05576 EFIAPI
05577 AsmReadDcr (
05578   VOID
05579   );
05580 
05581 
05582 /**
05583   Reads the current value of Interruption Vector Address Register (IVA).
05584 
05585   Reads and returns the current value of IVA.  This function is only available on Itanium processors.
05586 
05587   @return The current value of IVA.
05588 **/
05589 UINT64
05590 EFIAPI
05591 AsmReadIva (
05592   VOID
05593   );
05594 
05595 
05596 /**
05597   Reads the current value of Page Table Address Register (PTA).
05598 
05599   Reads and returns the current value of PTA.  This function is only available on Itanium processors.
05600 
05601   @return The current value of PTA.
05602 
05603 **/
05604 UINT64
05605 EFIAPI
05606 AsmReadPta (
05607   VOID
05608   );
05609 
05610 
05611 /**
05612   Writes the current value of 64-bit Default Control Register (DCR).
05613 
05614   Writes the current value of DCR.  The 64-bit value written to the DCR is returned.
05615   No parameter checking is performed on Value.  All bits of Value corresponding to
05616   reserved fields of DCR must be 0 or a Reserved Register/Field fault may occur.
05617   The caller must either guarantee that Value is valid, or the caller must set up
05618   fault handlers to catch the faults.
05619   This function is only available on Itanium processors.
05620 
05621   @param Value    The 64-bit value to write to DCR.
05622 
05623   @return The 64-bit value written to the DCR.
05624 
05625 **/
05626 UINT64
05627 EFIAPI
05628 AsmWriteDcr (
05629   IN UINT64  Value
05630   );
05631 
05632 
05633 /**
05634   Writes the current value of 64-bit Interruption Vector Address Register (IVA).
05635 
05636   Writes the current value of IVA.  The 64-bit value written to the IVA is returned.
05637   The size of vector table is 32 K bytes and is 32 K bytes aligned
05638   the low 15 bits of Value is ignored when written.
05639   This function is only available on Itanium processors.
05640 
05641   @param Value    The 64-bit value to write to IVA.
05642 
05643   @return The 64-bit value written to the IVA.
05644 
05645 **/
05646 UINT64
05647 EFIAPI
05648 AsmWriteIva (
05649   IN UINT64  Value
05650   );
05651 
05652 
05653 /**
05654   Writes the current value of 64-bit Page Table Address Register (PTA).
05655 
05656   Writes the current value of PTA.  The 64-bit value written to the PTA is returned.
05657   No parameter checking is performed on Value.  All bits of Value corresponding to
05658   reserved fields of DCR must be 0 or a Reserved Register/Field fault may occur.
05659   The caller must either guarantee that Value is valid, or the caller must set up
05660   fault handlers to catch the faults.
05661   This function is only available on Itanium processors.
05662 
05663   @param Value    The 64-bit value to write to PTA.
05664 
05665   @return The 64-bit value written to the PTA.
05666 **/
05667 UINT64
05668 EFIAPI
05669 AsmWritePta (
05670   IN UINT64  Value
05671   );
05672 
05673 
05674 /**
05675   Reads the current value of Local Interrupt ID Register (LID).
05676 
05677   Reads and returns the current value of LID.  This function is only available on Itanium processors.
05678 
05679   @return The current value of LID.
05680 
05681 **/
05682 UINT64
05683 EFIAPI
05684 AsmReadLid (
05685   VOID
05686   );
05687 
05688 
05689 /**
05690   Reads the current value of External Interrupt Vector Register (IVR).
05691 
05692   Reads and returns the current value of IVR.  This function is only available on Itanium processors.
05693 
05694   @return The current value of IVR.
05695 
05696 **/
05697 UINT64
05698 EFIAPI
05699 AsmReadIvr (
05700   VOID
05701   );
05702 
05703 
05704 /**
05705   Reads the current value of Task Priority Register (TPR).
05706 
05707   Reads and returns the current value of TPR.  This function is only available on Itanium processors.
05708 
05709   @return The current value of TPR.
05710 
05711 **/
05712 UINT64
05713 EFIAPI
05714 AsmReadTpr (
05715   VOID
05716   );
05717 
05718 
05719 /**
05720   Reads the current value of External Interrupt Request Register #0 (IRR0).
05721 
05722   Reads and returns the current value of IRR0.  This function is only available on Itanium processors.
05723 
05724   @return The current value of IRR0.
05725 
05726 **/
05727 UINT64
05728 EFIAPI
05729 AsmReadIrr0 (
05730   VOID
05731   );
05732 
05733 
05734 /**
05735   Reads the current value of External Interrupt Request Register #1 (IRR1).
05736 
05737   Reads and returns the current value of IRR1.  This function is only available on Itanium processors.
05738 
05739   @return The current value of IRR1.
05740 
05741 **/
05742 UINT64
05743 EFIAPI
05744 AsmReadIrr1 (
05745   VOID
05746   );
05747 
05748 
05749 /**
05750   Reads the current value of External Interrupt Request Register #2 (IRR2).
05751 
05752   Reads and returns the current value of IRR2.  This function is only available on Itanium processors.
05753 
05754   @return The current value of IRR2.
05755 
05756 **/
05757 UINT64
05758 EFIAPI
05759 AsmReadIrr2 (
05760   VOID
05761   );
05762 
05763 
05764 /**
05765   Reads the current value of External Interrupt Request Register #3 (IRR3).
05766 
05767   Reads and returns the current value of IRR3.  This function is only available on Itanium processors.
05768 
05769   @return The current value of IRR3.
05770 
05771 **/
05772 UINT64
05773 EFIAPI
05774 AsmReadIrr3 (
05775   VOID
05776   );
05777 
05778 
05779 /**
05780   Reads the current value of Performance Monitor Vector Register (PMV).
05781 
05782   Reads and returns the current value of PMV.  This function is only available on Itanium processors.
05783 
05784   @return The current value of PMV.
05785 
05786 **/
05787 UINT64
05788 EFIAPI
05789 AsmReadPmv (
05790   VOID
05791   );
05792 
05793 
05794 /**
05795   Reads the current value of Corrected Machine Check Vector Register (CMCV).
05796 
05797   Reads and returns the current value of CMCV.  This function is only available on Itanium processors.
05798 
05799   @return The current value of CMCV.
05800 
05801 **/
05802 UINT64
05803 EFIAPI
05804 AsmReadCmcv (
05805   VOID
05806   );
05807 
05808 
05809 /**
05810   Reads the current value of Local Redirection Register #0 (LRR0).
05811 
05812   Reads and returns the current value of LRR0.  This function is only available on Itanium processors.
05813 
05814   @return The current value of LRR0.
05815 
05816 **/
05817 UINT64
05818 EFIAPI
05819 AsmReadLrr0 (
05820   VOID
05821   );
05822 
05823 
05824 /**
05825   Reads the current value of Local Redirection Register #1 (LRR1).
05826 
05827   Reads and returns the current value of LRR1.  This function is only available on Itanium processors.
05828 
05829   @return The current value of LRR1.
05830 
05831 **/
05832 UINT64
05833 EFIAPI
05834 AsmReadLrr1 (
05835   VOID
05836   );
05837 
05838 
05839 /**
05840   Writes the current value of 64-bit Page Local Interrupt ID Register (LID).
05841 
05842   Writes the current value of LID.  The 64-bit value written to the LID is returned.
05843   No parameter checking is performed on Value.  All bits of Value corresponding to
05844   reserved fields of LID must be 0 or a Reserved Register/Field fault may occur.
05845   The caller must either guarantee that Value is valid, or the caller must set up
05846   fault handlers to catch the faults.
05847   This function is only available on Itanium processors.
05848 
05849   @param Value    The 64-bit value to write to LID.
05850 
05851   @return The 64-bit value written to the LID.
05852 
05853 **/
05854 UINT64
05855 EFIAPI
05856 AsmWriteLid (
05857   IN UINT64  Value
05858   );
05859 
05860 
05861 /**
05862   Writes the current value of 64-bit Task Priority Register (TPR).
05863 
05864   Writes the current value of TPR.  The 64-bit value written to the TPR is returned.
05865   No parameter checking is performed on Value.  All bits of Value corresponding to
05866   reserved fields of TPR must be 0 or a Reserved Register/Field fault may occur.
05867   The caller must either guarantee that Value is valid, or the caller must set up
05868   fault handlers to catch the faults.
05869   This function is only available on Itanium processors.
05870 
05871   @param Value    The 64-bit value to write to TPR.
05872 
05873   @return The 64-bit value written to the TPR.
05874 
05875 **/
05876 UINT64
05877 EFIAPI
05878 AsmWriteTpr (
05879   IN UINT64  Value
05880   );
05881 
05882 
05883 /**
05884   Performs a write operation on End OF External Interrupt Register (EOI).
05885 
05886   Writes a value of 0 to the EOI Register.  This function is only available on Itanium processors.
05887 
05888 **/
05889 VOID
05890 EFIAPI
05891 AsmWriteEoi (
05892   VOID
05893   );
05894 
05895 
05896 /**
05897   Writes the current value of 64-bit Performance Monitor Vector Register (PMV).
05898 
05899   Writes the current value of PMV.  The 64-bit value written to the PMV is returned.
05900   No parameter checking is performed on Value.  All bits of Value corresponding
05901   to reserved fields of PMV must be 0 or a Reserved Register/Field fault may occur.
05902   The caller must either guarantee that Value is valid, or the caller must set up
05903   fault handlers to catch the faults.
05904   This function is only available on Itanium processors.
05905 
05906   @param Value    The 64-bit value to write to PMV.
05907 
05908   @return The 64-bit value written to the PMV.
05909 
05910 **/
05911 UINT64
05912 EFIAPI
05913 AsmWritePmv (
05914   IN UINT64  Value
05915   );
05916 
05917 
05918 /**
05919   Writes the current value of 64-bit Corrected Machine Check Vector Register (CMCV).
05920 
05921   Writes the current value of CMCV.  The 64-bit value written to the CMCV is returned.
05922   No parameter checking is performed on Value.  All bits of Value corresponding
05923   to reserved fields of CMCV must be 0 or a Reserved Register/Field fault may occur.
05924   The caller must either guarantee that Value is valid, or the caller must set up
05925   fault handlers to catch the faults.
05926   This function is only available on Itanium processors.
05927 
05928   @param Value    The 64-bit value to write to CMCV.
05929 
05930   @return The 64-bit value written to the CMCV.
05931 
05932 **/
05933 UINT64
05934 EFIAPI
05935 AsmWriteCmcv (
05936   IN UINT64  Value
05937   );
05938 
05939 
05940 /**
05941   Writes the current value of 64-bit Local Redirection Register #0 (LRR0).
05942 
05943   Writes the current value of LRR0.  The 64-bit value written to the LRR0 is returned.
05944   No parameter checking is performed on Value.  All bits of Value corresponding
05945   to reserved fields of LRR0 must be 0 or a Reserved Register/Field fault may occur.
05946   The caller must either guarantee that Value is valid, or the caller must set up
05947   fault handlers to catch the faults.
05948   This function is only available on Itanium processors.
05949 
05950   @param Value    The 64-bit value to write to LRR0.
05951 
05952   @return The 64-bit value written to the LRR0.
05953 
05954 **/
05955 UINT64
05956 EFIAPI
05957 AsmWriteLrr0 (
05958   IN UINT64  Value
05959   );
05960 
05961 
05962 /**
05963   Writes the current value of 64-bit Local Redirection Register #1 (LRR1).
05964 
05965   Writes the current value of LRR1.  The 64-bit value written to the LRR1 is returned.
05966   No parameter checking is performed on Value.  All bits of Value corresponding
05967   to reserved fields of LRR1 must be 0 or a Reserved Register/Field fault may occur.
05968   The caller must either guarantee that Value is valid, or the caller must
05969   set up fault handlers to catch the faults.
05970   This function is only available on Itanium processors.
05971 
05972   @param Value    The 64-bit value to write to LRR1.
05973 
05974   @return The 64-bit value written to the LRR1.
05975 
05976 **/
05977 UINT64
05978 EFIAPI
05979 AsmWriteLrr1 (
05980   IN UINT64  Value
05981   );
05982 
05983 
05984 /**
05985   Reads the current value of Instruction Breakpoint Register (IBR).
05986 
05987   The Instruction Breakpoint Registers are used in pairs.  The even numbered
05988   registers contain breakpoint addresses, and the odd numbered registers contain
05989   breakpoint mask conditions.  At least four instruction registers pairs are implemented
05990   on all processor models.   Implemented registers are contiguous starting with
05991   register 0.  No parameter checking is performed on Index, and if the Index value
05992   is beyond the implemented IBR register range, a Reserved Register/Field fault may
05993   occur.  The caller must either guarantee that Index is valid, or the caller must
05994   set up fault handlers to catch the faults.
05995   This function is only available on Itanium processors.
05996 
05997   @param Index    The 8-bit Instruction Breakpoint Register index to read.
05998 
05999   @return The current value of Instruction Breakpoint Register specified by Index.
06000 
06001 **/
06002 UINT64
06003 EFIAPI
06004 AsmReadIbr (
06005   IN  UINT8   Index
06006   );
06007 
06008 
06009 /**
06010   Reads the current value of Data Breakpoint Register (DBR).
06011 
06012   The Data Breakpoint Registers are used in pairs.  The even numbered registers
06013   contain breakpoint addresses, and odd numbered registers contain breakpoint
06014   mask conditions.  At least four data registers pairs are implemented on all processor
06015   models.  Implemented registers are contiguous starting with register 0.
06016   No parameter checking is performed on Index.  If the Index value is beyond
06017   the implemented DBR register range, a Reserved Register/Field fault may occur.
06018   The caller must either guarantee that Index is valid, or the caller must set up
06019   fault handlers to catch the faults.
06020   This function is only available on Itanium processors.
06021 
06022   @param Index    The 8-bit Data Breakpoint Register index to read.
06023 
06024   @return The current value of Data Breakpoint Register specified by Index.
06025 
06026 **/
06027 UINT64
06028 EFIAPI
06029 AsmReadDbr (
06030   IN  UINT8   Index
06031   );
06032 
06033 
06034 /**
06035   Reads the current value of Performance Monitor Configuration Register (PMC).
06036 
06037   All processor implementations provide at least four performance counters
06038   (PMC/PMD [4]...PMC/PMD [7] pairs), and four performance monitor counter overflow
06039   status registers (PMC [0]... PMC [3]).  Processor implementations may provide
06040   additional implementation-dependent PMC and PMD to increase the number of
06041   'generic' performance counters (PMC/PMD pairs).  The remainder of PMC and PMD
06042   register set is implementation dependent.  No parameter checking is performed
06043   on Index.  If the Index value is beyond the implemented PMC register range,
06044   zero value will be returned.
06045   This function is only available on Itanium processors.
06046 
06047   @param Index    The 8-bit Performance Monitor Configuration Register index to read.
06048 
06049   @return   The current value of Performance Monitor Configuration Register
06050             specified by Index.
06051 
06052 **/
06053 UINT64
06054 EFIAPI
06055 AsmReadPmc (
06056   IN  UINT8   Index
06057   );
06058 
06059 
06060 /**
06061   Reads the current value of Performance Monitor Data Register (PMD).
06062 
06063   All processor implementations provide at least 4 performance counters
06064   (PMC/PMD [4]...PMC/PMD [7] pairs), and 4 performance monitor counter
06065   overflow status registers (PMC [0]... PMC [3]).  Processor implementations may
06066   provide additional implementation-dependent PMC and PMD to increase the number
06067   of 'generic' performance counters (PMC/PMD pairs).  The remainder of PMC and PMD
06068   register set is implementation dependent.  No parameter checking is performed
06069   on Index.  If the Index value is beyond the implemented PMD register range,
06070   zero value will be returned.
06071   This function is only available on Itanium processors.
06072 
06073   @param Index    The 8-bit Performance Monitor Data Register index to read.
06074 
06075   @return The current value of Performance Monitor Data Register specified by Index.
06076 
06077 **/
06078 UINT64
06079 EFIAPI
06080 AsmReadPmd (
06081   IN  UINT8   Index
06082   );
06083 
06084 
06085 /**
06086   Writes the current value of 64-bit Instruction Breakpoint Register (IBR).
06087 
06088   Writes current value of Instruction Breakpoint Register specified by Index.
06089   The Instruction Breakpoint Registers are used in pairs.  The even numbered
06090   registers contain breakpoint addresses, and odd numbered registers contain
06091   breakpoint mask conditions.  At least four instruction registers pairs are implemented
06092   on all processor models.  Implemented registers are contiguous starting with
06093   register 0.  No parameter checking is performed on Index.  If the Index value
06094   is beyond the implemented IBR register range, a Reserved Register/Field fault may
06095   occur.  The caller must either guarantee that Index is valid, or the caller must
06096   set up fault handlers to catch the faults.
06097   This function is only available on Itanium processors.
06098 
06099   @param Index    The 8-bit Instruction Breakpoint Register index to write.
06100   @param Value    The 64-bit value to write to IBR.
06101 
06102   @return The 64-bit value written to the IBR.
06103 
06104 **/
06105 UINT64
06106 EFIAPI
06107 AsmWriteIbr (
06108   IN UINT8   Index,
06109   IN UINT64  Value
06110   );
06111 
06112 
06113 /**
06114   Writes the current value of 64-bit Data Breakpoint Register (DBR).
06115 
06116   Writes current value of Data Breakpoint Register specified by Index.
06117   The Data Breakpoint Registers are used in pairs.  The even numbered registers
06118   contain breakpoint addresses, and odd numbered registers contain breakpoint
06119   mask conditions.  At least four data registers pairs are implemented on all processor
06120   models.  Implemented registers are contiguous starting with register 0.  No parameter
06121   checking is performed on Index.  If the Index value is beyond the implemented
06122   DBR register range, a Reserved Register/Field fault may occur.  The caller must
06123   either guarantee that Index is valid, or the caller must set up fault handlers to
06124   catch the faults.
06125   This function is only available on Itanium processors.
06126 
06127   @param Index    The 8-bit Data Breakpoint Register index to write.
06128   @param Value    The 64-bit value to write to DBR.
06129 
06130   @return The 64-bit value written to the DBR.
06131 
06132 **/
06133 UINT64
06134 EFIAPI
06135 AsmWriteDbr (
06136   IN UINT8   Index,
06137   IN UINT64  Value
06138   );
06139 
06140 
06141 /**
06142   Writes the current value of 64-bit Performance Monitor Configuration Register (PMC).
06143 
06144   Writes current value of Performance Monitor Configuration Register specified by Index.
06145   All processor implementations provide at least four performance counters
06146   (PMC/PMD [4]...PMC/PMD [7] pairs), and four performance monitor counter overflow status
06147   registers (PMC [0]... PMC [3]).  Processor implementations may provide additional
06148   implementation-dependent PMC and PMD to increase the number of 'generic' performance
06149   counters (PMC/PMD pairs).  The remainder of PMC and PMD register set is implementation
06150   dependent.  No parameter checking is performed on Index.  If the Index value is
06151   beyond the implemented PMC register range, the write is ignored.
06152   This function is only available on Itanium processors.
06153 
06154   @param Index    The 8-bit Performance Monitor Configuration Register index to write.
06155   @param Value    The 64-bit value to write to PMC.
06156 
06157   @return The 64-bit value written to the PMC.
06158 
06159 **/
06160 UINT64
06161 EFIAPI
06162 AsmWritePmc (
06163   IN UINT8   Index,
06164   IN UINT64  Value
06165   );
06166 
06167 
06168 /**
06169   Writes the current value of 64-bit Performance Monitor Data Register (PMD).
06170 
06171   Writes current value of Performance Monitor Data Register specified by Index.
06172   All processor implementations provide at least four performance counters
06173   (PMC/PMD [4]...PMC/PMD [7] pairs), and four performance monitor counter overflow
06174   status registers (PMC [0]... PMC [3]).  Processor implementations may provide
06175   additional implementation-dependent PMC and PMD to increase the number of 'generic'
06176   performance counters (PMC/PMD pairs).  The remainder of PMC and PMD register set
06177   is implementation dependent.  No parameter checking is performed on Index.  If the
06178   Index value is beyond the implemented PMD register range, the write is ignored.
06179   This function is only available on Itanium processors.
06180 
06181   @param Index    The 8-bit Performance Monitor Data Register index to write.
06182   @param Value    The 64-bit value to write to PMD.
06183 
06184   @return The 64-bit value written to the PMD.
06185 
06186 **/
06187 UINT64
06188 EFIAPI
06189 AsmWritePmd (
06190   IN UINT8   Index,
06191   IN UINT64  Value
06192   );
06193 
06194 
06195 /**
06196   Reads the current value of 64-bit Global Pointer (GP).
06197 
06198   Reads and returns the current value of GP.
06199   This function is only available on Itanium processors.
06200 
06201   @return The current value of GP.
06202 
06203 **/
06204 UINT64
06205 EFIAPI
06206 AsmReadGp (
06207   VOID
06208   );
06209 
06210 
06211 /**
06212   Write the current value of 64-bit Global Pointer (GP).
06213 
06214   Writes the current value of GP. The 64-bit value written to the GP is returned.
06215   No parameter checking is performed on Value.
06216   This function is only available on Itanium processors.
06217 
06218   @param Value  The 64-bit value to write to GP.
06219 
06220   @return The 64-bit value written to the GP.
06221 
06222 **/
06223 UINT64
06224 EFIAPI
06225 AsmWriteGp (
06226   IN UINT64  Value
06227   );
06228 
06229 
06230 /**
06231   Reads the current value of 64-bit Stack Pointer (SP).
06232 
06233   Reads and returns the current value of SP.
06234   This function is only available on Itanium processors.
06235 
06236   @return The current value of SP.
06237 
06238 **/
06239 UINT64
06240 EFIAPI
06241 AsmReadSp (
06242   VOID
06243   );
06244 
06245 
06246 ///
06247 /// Valid Index value for AsmReadControlRegister().
06248 ///
06249 #define IPF_CONTROL_REGISTER_DCR   0
06250 #define IPF_CONTROL_REGISTER_ITM   1
06251 #define IPF_CONTROL_REGISTER_IVA   2
06252 #define IPF_CONTROL_REGISTER_PTA   8
06253 #define IPF_CONTROL_REGISTER_IPSR  16
06254 #define IPF_CONTROL_REGISTER_ISR   17
06255 #define IPF_CONTROL_REGISTER_IIP   19
06256 #define IPF_CONTROL_REGISTER_IFA   20
06257 #define IPF_CONTROL_REGISTER_ITIR  21
06258 #define IPF_CONTROL_REGISTER_IIPA  22
06259 #define IPF_CONTROL_REGISTER_IFS   23
06260 #define IPF_CONTROL_REGISTER_IIM   24
06261 #define IPF_CONTROL_REGISTER_IHA   25
06262 #define IPF_CONTROL_REGISTER_LID   64
06263 #define IPF_CONTROL_REGISTER_IVR   65
06264 #define IPF_CONTROL_REGISTER_TPR   66
06265 #define IPF_CONTROL_REGISTER_EOI   67
06266 #define IPF_CONTROL_REGISTER_IRR0  68
06267 #define IPF_CONTROL_REGISTER_IRR1  69
06268 #define IPF_CONTROL_REGISTER_IRR2  70
06269 #define IPF_CONTROL_REGISTER_IRR3  71
06270 #define IPF_CONTROL_REGISTER_ITV   72
06271 #define IPF_CONTROL_REGISTER_PMV   73
06272 #define IPF_CONTROL_REGISTER_CMCV  74
06273 #define IPF_CONTROL_REGISTER_LRR0  80
06274 #define IPF_CONTROL_REGISTER_LRR1  81
06275 
06276 /**
06277   Reads a 64-bit control register.
06278 
06279   Reads and returns the control register specified by Index. The valid Index valued
06280   are defined above in "Related Definitions".
06281   If Index is invalid then 0xFFFFFFFFFFFFFFFF is returned.  This function is only
06282   available on Itanium processors.
06283 
06284   @param  Index                     The index of the control register to read.
06285 
06286   @return The control register specified by Index.
06287 
06288 **/
06289 UINT64
06290 EFIAPI
06291 AsmReadControlRegister (
06292   IN UINT64  Index
06293   );
06294 
06295 
06296 ///
06297 /// Valid Index value for AsmReadApplicationRegister().
06298 ///
06299 #define IPF_APPLICATION_REGISTER_K0        0
06300 #define IPF_APPLICATION_REGISTER_K1        1
06301 #define IPF_APPLICATION_REGISTER_K2        2
06302 #define IPF_APPLICATION_REGISTER_K3        3
06303 #define IPF_APPLICATION_REGISTER_K4        4
06304 #define IPF_APPLICATION_REGISTER_K5        5
06305 #define IPF_APPLICATION_REGISTER_K6        6
06306 #define IPF_APPLICATION_REGISTER_K7        7
06307 #define IPF_APPLICATION_REGISTER_RSC       16
06308 #define IPF_APPLICATION_REGISTER_BSP       17
06309 #define IPF_APPLICATION_REGISTER_BSPSTORE  18
06310 #define IPF_APPLICATION_REGISTER_RNAT      19
06311 #define IPF_APPLICATION_REGISTER_FCR       21
06312 #define IPF_APPLICATION_REGISTER_EFLAG     24
06313 #define IPF_APPLICATION_REGISTER_CSD       25
06314 #define IPF_APPLICATION_REGISTER_SSD       26
06315 #define IPF_APPLICATION_REGISTER_CFLG      27
06316 #define IPF_APPLICATION_REGISTER_FSR       28
06317 #define IPF_APPLICATION_REGISTER_FIR       29
06318 #define IPF_APPLICATION_REGISTER_FDR       30
06319 #define IPF_APPLICATION_REGISTER_CCV       32
06320 #define IPF_APPLICATION_REGISTER_UNAT      36
06321 #define IPF_APPLICATION_REGISTER_FPSR      40
06322 #define IPF_APPLICATION_REGISTER_ITC       44
06323 #define IPF_APPLICATION_REGISTER_PFS       64
06324 #define IPF_APPLICATION_REGISTER_LC        65
06325 #define IPF_APPLICATION_REGISTER_EC        66
06326 
06327 /**
06328   Reads a 64-bit application register.
06329 
06330   Reads and returns the application register specified by Index. The valid Index
06331   valued are defined above in "Related Definitions".
06332   If Index is invalid then 0xFFFFFFFFFFFFFFFF is returned.  This function is only
06333   available on Itanium processors.
06334 
06335   @param  Index                     The index of the application register to read.
06336 
06337   @return The application register specified by Index.
06338 
06339 **/
06340 UINT64
06341 EFIAPI
06342 AsmReadApplicationRegister (
06343   IN UINT64  Index
06344   );
06345 
06346 
06347 /**
06348   Reads the current value of a Machine Specific Register (MSR).
06349 
06350   Reads and returns the current value of the Machine Specific Register specified by Index.  No
06351   parameter checking is performed on Index, and if the Index value is beyond the implemented MSR
06352   register range, a Reserved Register/Field fault may occur.  The caller must either guarantee that
06353   Index is valid, or the caller must set up fault handlers to catch the faults.  This function is
06354   only available on Itanium processors.
06355 
06356   @param  Index                     The 8-bit Machine Specific Register index to read.
06357 
06358   @return The current value of the Machine Specific Register specified by Index.
06359 
06360 **/
06361 UINT64
06362 EFIAPI
06363 AsmReadMsr (
06364   IN UINT8   Index
06365   );
06366 
06367 
06368 /**
06369   Writes the current value of a Machine Specific Register (MSR).
06370 
06371   Writes Value to the Machine Specific Register specified by Index.  Value is returned.  No
06372   parameter checking is performed on Index, and if the Index value is beyond the implemented MSR
06373   register range, a Reserved Register/Field fault may occur.  The caller must either guarantee that
06374   Index is valid, or the caller must set up fault handlers to catch the faults.  This function is
06375   only available on Itanium processors.
06376 
06377   @param  Index                     The 8-bit Machine Specific Register index to write.
06378   @param  Value                     The 64-bit value to write to the Machine Specific Register.
06379 
06380   @return The 64-bit value to write to the Machine Specific Register.
06381 
06382 **/
06383 UINT64
06384 EFIAPI
06385 AsmWriteMsr (
06386   IN UINT8   Index,
06387   IN UINT64  Value
06388   );
06389 
06390 
06391 /**
06392   Determines if the CPU is currently executing in virtual, physical, or mixed mode.
06393 
06394   Determines the current execution mode of the CPU.
06395   If the CPU is in virtual mode(PSR.RT=1, PSR.DT=1, PSR.IT=1), then 1 is returned.
06396   If the CPU is in physical mode(PSR.RT=0, PSR.DT=0, PSR.IT=0), then 0 is returned.
06397   If the CPU is not in physical mode or virtual mode, then it is in mixed mode,
06398   and -1 is returned.
06399   This function is only available on Itanium processors.
06400 
06401   @retval  1  The CPU is in virtual mode.
06402   @retval  0  The CPU is in physical mode.
06403   @retval -1  The CPU is in mixed mode.
06404 
06405 **/
06406 INT64
06407 EFIAPI
06408 AsmCpuVirtual (
06409   VOID
06410   );
06411 
06412 
06413 /**
06414   Makes a PAL procedure call.
06415 
06416   This is a wrapper function to make a PAL procedure call.  Based on the Index
06417   value this API will make static or stacked PAL call.  The following table
06418   describes the usage of PAL Procedure Index Assignment. Architected procedures
06419   may be designated as required or optional.  If a PAL procedure is specified
06420   as optional, a unique return code of 0xFFFFFFFFFFFFFFFF is returned in the
06421   Status field of the PAL_CALL_RETURN structure.
06422   This indicates that the procedure is not present in this PAL implementation.
06423   It is the caller's responsibility to check for this return code after calling
06424   any optional PAL procedure.
06425   No parameter checking is performed on the 5 input parameters, but there are
06426   some common rules that the caller should follow when making a PAL call.  Any
06427   address passed to PAL as buffers for return parameters must be 8-byte aligned.
06428   Unaligned addresses may cause undefined results.  For those parameters defined
06429   as reserved or some fields defined as reserved must be zero filled or the invalid
06430   argument return value may be returned or undefined result may occur during the
06431   execution of the procedure.  If the PalEntryPoint  does not point to a valid
06432   PAL entry point then the system behavior is undefined.  This function is only
06433   available on Itanium processors.
06434 
06435   @param PalEntryPoint  The PAL procedure calls entry point.
06436   @param Index          The PAL procedure Index number.
06437   @param Arg2           The 2nd parameter for PAL procedure calls.
06438   @param Arg3           The 3rd parameter for PAL procedure calls.
06439   @param Arg4           The 4th parameter for PAL procedure calls.
06440 
06441   @return structure returned from the PAL Call procedure, including the status and return value.
06442 
06443 **/
06444 PAL_CALL_RETURN
06445 EFIAPI
06446 AsmPalCall (
06447   IN UINT64  PalEntryPoint,
06448   IN UINT64  Index,
06449   IN UINT64  Arg2,
06450   IN UINT64  Arg3,
06451   IN UINT64  Arg4
06452   );
06453 #endif
06454 
06455 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
06456 ///
06457 /// IA32 and x64 Specific Functions.
06458 /// Byte packed structure for 16-bit Real Mode EFLAGS.
06459 ///
06460 typedef union {
06461   struct {
06462     UINT32  CF:1;           ///< Carry Flag.
06463     UINT32  Reserved_0:1;   ///< Reserved.
06464     UINT32  PF:1;           ///< Parity Flag.
06465     UINT32  Reserved_1:1;   ///< Reserved.
06466     UINT32  AF:1;           ///< Auxiliary Carry Flag.
06467     UINT32  Reserved_2:1;   ///< Reserved.
06468     UINT32  ZF:1;           ///< Zero Flag.
06469     UINT32  SF:1;           ///< Sign Flag.
06470     UINT32  TF:1;           ///< Trap Flag.
06471     UINT32  IF:1;           ///< Interrupt Enable Flag.
06472     UINT32  DF:1;           ///< Direction Flag.
06473     UINT32  OF:1;           ///< Overflow Flag.
06474     UINT32  IOPL:2;         ///< I/O Privilege Level.
06475     UINT32  NT:1;           ///< Nested Task.
06476     UINT32  Reserved_3:1;   ///< Reserved.
06477   } Bits;
06478   UINT16    Uint16;
06479 } IA32_FLAGS16;
06480 
06481 ///
06482 /// Byte packed structure for EFLAGS/RFLAGS.
06483 /// 32-bits on IA-32.
06484 /// 64-bits on x64.  The upper 32-bits on x64 are reserved.
06485 ///
06486 typedef union {
06487   struct {
06488     UINT32  CF:1;           ///< Carry Flag.
06489     UINT32  Reserved_0:1;   ///< Reserved.
06490     UINT32  PF:1;           ///< Parity Flag.
06491     UINT32  Reserved_1:1;   ///< Reserved.
06492     UINT32  AF:1;           ///< Auxiliary Carry Flag.
06493     UINT32  Reserved_2:1;   ///< Reserved.
06494     UINT32  ZF:1;           ///< Zero Flag.
06495     UINT32  SF:1;           ///< Sign Flag.
06496     UINT32  TF:1;           ///< Trap Flag.
06497     UINT32  IF:1;           ///< Interrupt Enable Flag.
06498     UINT32  DF:1;           ///< Direction Flag.
06499     UINT32  OF:1;           ///< Overflow Flag.
06500     UINT32  IOPL:2;         ///< I/O Privilege Level.
06501     UINT32  NT:1;           ///< Nested Task.
06502     UINT32  Reserved_3:1;   ///< Reserved.
06503     UINT32  RF:1;           ///< Resume Flag.
06504     UINT32  VM:1;           ///< Virtual 8086 Mode.
06505     UINT32  AC:1;           ///< Alignment Check.
06506     UINT32  VIF:1;          ///< Virtual Interrupt Flag.
06507     UINT32  VIP:1;          ///< Virtual Interrupt Pending.
06508     UINT32  ID:1;           ///< ID Flag.
06509     UINT32  Reserved_4:10;  ///< Reserved.
06510   } Bits;
06511   UINTN     UintN;
06512 } IA32_EFLAGS32;
06513 
06514 ///
06515 /// Byte packed structure for Control Register 0 (CR0).
06516 /// 32-bits on IA-32.
06517 /// 64-bits on x64.  The upper 32-bits on x64 are reserved.
06518 ///
06519 typedef union {
06520   struct {
06521     UINT32  PE:1;           ///< Protection Enable.
06522     UINT32  MP:1;           ///< Monitor Coprocessor.
06523     UINT32  EM:1;           ///< Emulation.
06524     UINT32  TS:1;           ///< Task Switched.
06525     UINT32  ET:1;           ///< Extension Type.
06526     UINT32  NE:1;           ///< Numeric Error.
06527     UINT32  Reserved_0:10;  ///< Reserved.
06528     UINT32  WP:1;           ///< Write Protect.
06529     UINT32  Reserved_1:1;   ///< Reserved.
06530     UINT32  AM:1;           ///< Alignment Mask.
06531     UINT32  Reserved_2:10;  ///< Reserved.
06532     UINT32  NW:1;           ///< Mot Write-through.
06533     UINT32  CD:1;           ///< Cache Disable.
06534     UINT32  PG:1;           ///< Paging.
06535   } Bits;
06536   UINTN     UintN;
06537 } IA32_CR0;
06538 
06539 ///
06540 /// Byte packed structure for Control Register 4 (CR4).
06541 /// 32-bits on IA-32.
06542 /// 64-bits on x64.  The upper 32-bits on x64 are reserved.
06543 ///
06544 typedef union {
06545   struct {
06546     UINT32  VME:1;          ///< Virtual-8086 Mode Extensions.
06547     UINT32  PVI:1;          ///< Protected-Mode Virtual Interrupts.
06548     UINT32  TSD:1;          ///< Time Stamp Disable.
06549     UINT32  DE:1;           ///< Debugging Extensions.
06550     UINT32  PSE:1;          ///< Page Size Extensions.
06551     UINT32  PAE:1;          ///< Physical Address Extension.
06552     UINT32  MCE:1;          ///< Machine Check Enable.
06553     UINT32  PGE:1;          ///< Page Global Enable.
06554     UINT32  PCE:1;          ///< Performance Monitoring Counter
06555                             ///< Enable.
06556     UINT32  OSFXSR:1;       ///< Operating System Support for
06557                             ///< FXSAVE and FXRSTOR instructions
06558     UINT32  OSXMMEXCPT:1;   ///< Operating System Support for
06559                             ///< Unmasked SIMD Floating Point
06560                             ///< Exceptions.
06561     UINT32  Reserved_0:2;   ///< Reserved.
06562     UINT32  VMXE:1;         ///< VMX Enable
06563     UINT32  Reserved_1:18;  ///< Reserved.
06564   } Bits;
06565   UINTN     UintN;
06566 } IA32_CR4;
06567 
06568 ///
06569 /// Byte packed structure for a segment descriptor in a GDT/LDT.
06570 ///
06571 typedef union {
06572   struct {
06573     UINT32  LimitLow:16;
06574     UINT32  BaseLow:16;
06575     UINT32  BaseMid:8;
06576     UINT32  Type:4;
06577     UINT32  S:1;
06578     UINT32  DPL:2;
06579     UINT32  P:1;
06580     UINT32  LimitHigh:4;
06581     UINT32  AVL:1;
06582     UINT32  L:1;
06583     UINT32  DB:1;
06584     UINT32  G:1;
06585     UINT32  BaseHigh:8;
06586   } Bits;
06587   UINT64  Uint64;
06588 } IA32_SEGMENT_DESCRIPTOR;
06589 
06590 ///
06591 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
06592 ///
06593 #pragma pack (1)
06594 typedef struct {
06595   UINT16  Limit;
06596   UINTN   Base;
06597 } IA32_DESCRIPTOR;
06598 #pragma pack ()
06599 
06600 #define IA32_IDT_GATE_TYPE_TASK          0x85
06601 #define IA32_IDT_GATE_TYPE_INTERRUPT_16  0x86
06602 #define IA32_IDT_GATE_TYPE_TRAP_16       0x87
06603 #define IA32_IDT_GATE_TYPE_INTERRUPT_32  0x8E
06604 #define IA32_IDT_GATE_TYPE_TRAP_32       0x8F
06605 
06606 
06607 #if defined (MDE_CPU_IA32)
06608 ///
06609 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
06610 ///
06611 typedef union {
06612   struct {
06613     UINT32  OffsetLow:16;   ///< Offset bits 15..0.
06614     UINT32  Selector:16;    ///< Selector.
06615     UINT32  Reserved_0:8;   ///< Reserved.
06616     UINT32  GateType:8;     ///< Gate Type.  See #defines above.
06617     UINT32  OffsetHigh:16;  ///< Offset bits 31..16.
06618   } Bits;
06619   UINT64  Uint64;
06620 } IA32_IDT_GATE_DESCRIPTOR;
06621 
06622 #endif
06623 
06624 #if defined (MDE_CPU_X64)
06625 ///
06626 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
06627 ///
06628 typedef union {
06629   struct {
06630     UINT32  OffsetLow:16;   ///< Offset bits 15..0.
06631     UINT32  Selector:16;    ///< Selector.
06632     UINT32  Reserved_0:8;   ///< Reserved.
06633     UINT32  GateType:8;     ///< Gate Type.  See #defines above.
06634     UINT32  OffsetHigh:16;  ///< Offset bits 31..16.
06635     UINT32  OffsetUpper:32; ///< Offset bits 63..32.
06636     UINT32  Reserved_1:32;  ///< Reserved.
06637   } Bits;
06638   struct {
06639     UINT64  Uint64;
06640     UINT64  Uint64_1;
06641   } Uint128;
06642 } IA32_IDT_GATE_DESCRIPTOR;
06643 
06644 #endif
06645 
06646 ///
06647 /// Byte packed structure for an FP/SSE/SSE2 context.
06648 ///
06649 typedef struct {
06650   UINT8  Buffer[512];
06651 } IA32_FX_BUFFER;
06652 
06653 ///
06654 /// Structures for the 16-bit real mode thunks.
06655 ///
06656 typedef struct {
06657   UINT32                            Reserved1;
06658   UINT32                            Reserved2;
06659   UINT32                            Reserved3;
06660   UINT32                            Reserved4;
06661   UINT8                             BL;
06662   UINT8                             BH;
06663   UINT16                            Reserved5;
06664   UINT8                             DL;
06665   UINT8                             DH;
06666   UINT16                            Reserved6;
06667   UINT8                             CL;
06668   UINT8                             CH;
06669   UINT16                            Reserved7;
06670   UINT8                             AL;
06671   UINT8                             AH;
06672   UINT16                            Reserved8;
06673 } IA32_BYTE_REGS;
06674 
06675 typedef struct {
06676   UINT16                            DI;
06677   UINT16                            Reserved1;
06678   UINT16                            SI;
06679   UINT16                            Reserved2;
06680   UINT16                            BP;
06681   UINT16                            Reserved3;
06682   UINT16                            SP;
06683   UINT16                            Reserved4;
06684   UINT16                            BX;
06685   UINT16                            Reserved5;
06686   UINT16                            DX;
06687   UINT16                            Reserved6;
06688   UINT16                            CX;
06689   UINT16                            Reserved7;
06690   UINT16                            AX;
06691   UINT16                            Reserved8;
06692 } IA32_WORD_REGS;
06693 
06694 typedef struct {
06695   UINT32                            EDI;
06696   UINT32                            ESI;
06697   UINT32                            EBP;
06698   UINT32                            ESP;
06699   UINT32                            EBX;
06700   UINT32                            EDX;
06701   UINT32                            ECX;
06702   UINT32                            EAX;
06703   UINT16                            DS;
06704   UINT16                            ES;
06705   UINT16                            FS;
06706   UINT16                            GS;
06707   IA32_EFLAGS32                     EFLAGS;
06708   UINT32                            Eip;
06709   UINT16                            CS;
06710   UINT16                            SS;
06711 } IA32_DWORD_REGS;
06712 
06713 typedef union {
06714   IA32_DWORD_REGS                   E;
06715   IA32_WORD_REGS                    X;
06716   IA32_BYTE_REGS                    H;
06717 } IA32_REGISTER_SET;
06718 
06719 ///
06720 /// Byte packed structure for an 16-bit real mode thunks.
06721 ///
06722 typedef struct {
06723   IA32_REGISTER_SET                 *RealModeState;
06724   VOID                              *RealModeBuffer;
06725   UINT32                            RealModeBufferSize;
06726   UINT32                            ThunkAttributes;
06727 } THUNK_CONTEXT;
06728 
06729 #define THUNK_ATTRIBUTE_BIG_REAL_MODE             0x00000001
06730 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15   0x00000002
06731 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
06732 
06733 /**
06734   Retrieves CPUID information.
06735 
06736   Executes the CPUID instruction with EAX set to the value specified by Index.
06737   This function always returns Index.
06738   If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
06739   If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
06740   If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
06741   If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
06742   This function is only available on IA-32 and x64.
06743 
06744   @param  Index The 32-bit value to load into EAX prior to invoking the CPUID
06745                 instruction.
06746   @param  Eax   The pointer to the 32-bit EAX value returned by the CPUID
06747                 instruction. This is an optional parameter that may be NULL.
06748   @param  Ebx   The pointer to the 32-bit EBX value returned by the CPUID
06749                 instruction. This is an optional parameter that may be NULL.
06750   @param  Ecx   The pointer to the 32-bit ECX value returned by the CPUID
06751                 instruction. This is an optional parameter that may be NULL.
06752   @param  Edx   The pointer to the 32-bit EDX value returned by the CPUID
06753                 instruction. This is an optional parameter that may be NULL.
06754 
06755   @return Index.
06756 
06757 **/
06758 UINT32
06759 EFIAPI
06760 AsmCpuid (
06761   IN      UINT32                    Index,
06762   OUT     UINT32                    *Eax,  OPTIONAL
06763   OUT     UINT32                    *Ebx,  OPTIONAL
06764   OUT     UINT32                    *Ecx,  OPTIONAL
06765   OUT     UINT32                    *Edx   OPTIONAL
06766   );
06767 
06768 
06769 /**
06770   Retrieves CPUID information using an extended leaf identifier.
06771 
06772   Executes the CPUID instruction with EAX set to the value specified by Index
06773   and ECX set to the value specified by SubIndex. This function always returns
06774   Index. This function is only available on IA-32 and x64.
06775 
06776   If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
06777   If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
06778   If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
06779   If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
06780 
06781   @param  Index     The 32-bit value to load into EAX prior to invoking the
06782                     CPUID instruction.
06783   @param  SubIndex  The 32-bit value to load into ECX prior to invoking the
06784                     CPUID instruction.
06785   @param  Eax       The pointer to the 32-bit EAX value returned by the CPUID
06786                     instruction. This is an optional parameter that may be
06787                     NULL.
06788   @param  Ebx       The pointer to the 32-bit EBX value returned by the CPUID
06789                     instruction. This is an optional parameter that may be
06790                     NULL.
06791   @param  Ecx       The pointer to the 32-bit ECX value returned by the CPUID
06792                     instruction. This is an optional parameter that may be
06793                     NULL.
06794   @param  Edx       The pointer to the 32-bit EDX value returned by the CPUID
06795                     instruction. This is an optional parameter that may be
06796                     NULL.
06797 
06798   @return Index.
06799 
06800 **/
06801 UINT32
06802 EFIAPI
06803 AsmCpuidEx (
06804   IN      UINT32                    Index,
06805   IN      UINT32                    SubIndex,
06806   OUT     UINT32                    *Eax,  OPTIONAL
06807   OUT     UINT32                    *Ebx,  OPTIONAL
06808   OUT     UINT32                    *Ecx,  OPTIONAL
06809   OUT     UINT32                    *Edx   OPTIONAL
06810   );
06811 
06812 
06813 /**
06814   Set CD bit and clear NW bit of CR0 followed by a WBINVD.
06815 
06816   Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
06817   and executing a WBINVD instruction.  This function is only available on IA-32 and x64.
06818 
06819 **/
06820 VOID
06821 EFIAPI
06822 AsmDisableCache (
06823   VOID
06824   );
06825 
06826 
06827 /**
06828   Perform a WBINVD and clear both the CD and NW bits of CR0.
06829 
06830   Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
06831   bits of CR0 to 0.  This function is only available on IA-32 and x64.
06832 
06833 **/
06834 VOID
06835 EFIAPI
06836 AsmEnableCache (
06837   VOID
06838   );
06839 
06840 
06841 /**
06842   Returns the lower 32-bits of a Machine Specific Register(MSR).
06843 
06844   Reads and returns the lower 32-bits of the MSR specified by Index.
06845   No parameter checking is performed on Index, and some Index values may cause
06846   CPU exceptions. The caller must either guarantee that Index is valid, or the
06847   caller must set up exception handlers to catch the exceptions. This function
06848   is only available on IA-32 and x64.
06849 
06850   @param  Index The 32-bit MSR index to read.
06851 
06852   @return The lower 32 bits of the MSR identified by Index.
06853 
06854 **/
06855 UINT32
06856 EFIAPI
06857 AsmReadMsr32 (
06858   IN      UINT32                    Index
06859   );
06860 
06861 
06862 /**
06863   Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
06864   The upper 32-bits of the MSR are set to zero.
06865 
06866   Writes the 32-bit value specified by Value to the MSR specified by Index. The
06867   upper 32-bits of the MSR write are set to zero. The 32-bit value written to
06868   the MSR is returned. No parameter checking is performed on Index or Value,
06869   and some of these may cause CPU exceptions. The caller must either guarantee
06870   that Index and Value are valid, or the caller must establish proper exception
06871   handlers. This function is only available on IA-32 and x64.
06872 
06873   @param  Index The 32-bit MSR index to write.
06874   @param  Value The 32-bit value to write to the MSR.
06875 
06876   @return Value
06877 
06878 **/
06879 UINT32
06880 EFIAPI
06881 AsmWriteMsr32 (
06882   IN      UINT32                    Index,
06883   IN      UINT32                    Value
06884   );
06885 
06886 
06887 /**
06888   Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
06889   writes the result back to the 64-bit MSR.
06890 
06891   Reads the 64-bit MSR specified by Index, performs a bitwise OR
06892   between the lower 32-bits of the read result and the value specified by
06893   OrData, and writes the result to the 64-bit MSR specified by Index. The lower
06894   32-bits of the value written to the MSR is returned. No parameter checking is
06895   performed on Index or OrData, and some of these may cause CPU exceptions. The
06896   caller must either guarantee that Index and OrData are valid, or the caller
06897   must establish proper exception handlers. This function is only available on
06898   IA-32 and x64.
06899 
06900   @param  Index   The 32-bit MSR index to write.
06901   @param  OrData  The value to OR with the read value from the MSR.
06902 
06903   @return The lower 32-bit value written to the MSR.
06904 
06905 **/
06906 UINT32
06907 EFIAPI
06908 AsmMsrOr32 (
06909   IN      UINT32                    Index,
06910   IN      UINT32                    OrData
06911   );
06912 
06913 
06914 /**
06915   Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
06916   the result back to the 64-bit MSR.
06917 
06918   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
06919   lower 32-bits of the read result and the value specified by AndData, and
06920   writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
06921   the value written to the MSR is returned. No parameter checking is performed
06922   on Index or AndData, and some of these may cause CPU exceptions. The caller
06923   must either guarantee that Index and AndData are valid, or the caller must
06924   establish proper exception handlers. This function is only available on IA-32
06925   and x64.
06926 
06927   @param  Index   The 32-bit MSR index to write.
06928   @param  AndData The value to AND with the read value from the MSR.
06929 
06930   @return The lower 32-bit value written to the MSR.
06931 
06932 **/
06933 UINT32
06934 EFIAPI
06935 AsmMsrAnd32 (
06936   IN      UINT32                    Index,
06937   IN      UINT32                    AndData
06938   );
06939 
06940 
06941 /**
06942   Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
06943   on the lower 32-bits, and writes the result back to the 64-bit MSR.
06944 
06945   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
06946   lower 32-bits of the read result and the value specified by AndData
06947   preserving the upper 32-bits, performs a bitwise OR between the
06948   result of the AND operation and the value specified by OrData, and writes the
06949   result to the 64-bit MSR specified by Address. The lower 32-bits of the value
06950   written to the MSR is returned. No parameter checking is performed on Index,
06951   AndData, or OrData, and some of these may cause CPU exceptions. The caller
06952   must either guarantee that Index, AndData, and OrData are valid, or the
06953   caller must establish proper exception handlers. This function is only
06954   available on IA-32 and x64.
06955 
06956   @param  Index   The 32-bit MSR index to write.
06957   @param  AndData The value to AND with the read value from the MSR.
06958   @param  OrData  The value to OR with the result of the AND operation.
06959 
06960   @return The lower 32-bit value written to the MSR.
06961 
06962 **/
06963 UINT32
06964 EFIAPI
06965 AsmMsrAndThenOr32 (
06966   IN      UINT32                    Index,
06967   IN      UINT32                    AndData,
06968   IN      UINT32                    OrData
06969   );
06970 
06971 
06972 /**
06973   Reads a bit field of an MSR.
06974 
06975   Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
06976   specified by the StartBit and the EndBit. The value of the bit field is
06977   returned. The caller must either guarantee that Index is valid, or the caller
06978   must set up exception handlers to catch the exceptions. This function is only
06979   available on IA-32 and x64.
06980 
06981   If StartBit is greater than 31, then ASSERT().
06982   If EndBit is greater than 31, then ASSERT().
06983   If EndBit is less than StartBit, then ASSERT().
06984 
06985   @param  Index     The 32-bit MSR index to read.
06986   @param  StartBit  The ordinal of the least significant bit in the bit field.
06987                     Range 0..31.
06988   @param  EndBit    The ordinal of the most significant bit in the bit field.
06989                     Range 0..31.
06990 
06991   @return The bit field read from the MSR.
06992 
06993 **/
06994 UINT32
06995 EFIAPI
06996 AsmMsrBitFieldRead32 (
06997   IN      UINT32                    Index,
06998   IN      UINTN                     StartBit,
06999   IN      UINTN                     EndBit
07000   );
07001 
07002 
07003 /**
07004   Writes a bit field to an MSR.
07005 
07006   Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
07007   field is specified by the StartBit and the EndBit. All other bits in the
07008   destination MSR are preserved. The lower 32-bits of the MSR written is
07009   returned. The caller must either guarantee that Index and the data written
07010   is valid, or the caller must set up exception handlers to catch the exceptions.
07011   This function is only available on IA-32 and x64.
07012 
07013   If StartBit is greater than 31, then ASSERT().
07014   If EndBit is greater than 31, then ASSERT().
07015   If EndBit is less than StartBit, then ASSERT().
07016   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
07017 
07018   @param  Index     The 32-bit MSR index to write.
07019   @param  StartBit  The ordinal of the least significant bit in the bit field.
07020                     Range 0..31.
07021   @param  EndBit    The ordinal of the most significant bit in the bit field.
07022                     Range 0..31.
07023   @param  Value     New value of the bit field.
07024 
07025   @return The lower 32-bit of the value written to the MSR.
07026 
07027 **/
07028 UINT32
07029 EFIAPI
07030 AsmMsrBitFieldWrite32 (
07031   IN      UINT32                    Index,
07032   IN      UINTN                     StartBit,
07033   IN      UINTN                     EndBit,
07034   IN      UINT32                    Value
07035   );
07036 
07037 
07038 /**
07039   Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
07040   result back to the bit field in the 64-bit MSR.
07041 
07042   Reads the 64-bit MSR specified by Index, performs a bitwise OR
07043   between the read result and the value specified by OrData, and writes the
07044   result to the 64-bit MSR specified by Index. The lower 32-bits of the value
07045   written to the MSR are returned. Extra left bits in OrData are stripped. The
07046   caller must either guarantee that Index and the data written is valid, or
07047   the caller must set up exception handlers to catch the exceptions. This
07048   function is only available on IA-32 and x64.
07049 
07050   If StartBit is greater than 31, then ASSERT().
07051   If EndBit is greater than 31, then ASSERT().
07052   If EndBit is less than StartBit, then ASSERT().
07053   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
07054 
07055   @param  Index     The 32-bit MSR index to write.
07056   @param  StartBit  The ordinal of the least significant bit in the bit field.
07057                     Range 0..31.
07058   @param  EndBit    The ordinal of the most significant bit in the bit field.
07059                     Range 0..31.
07060   @param  OrData    The value to OR with the read value from the MSR.
07061 
07062   @return The lower 32-bit of the value written to the MSR.
07063 
07064 **/
07065 UINT32
07066 EFIAPI
07067 AsmMsrBitFieldOr32 (
07068   IN      UINT32                    Index,
07069   IN      UINTN                     StartBit,
07070   IN      UINTN                     EndBit,
07071   IN      UINT32                    OrData
07072   );
07073 
07074 
07075 /**
07076   Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
07077   result back to the bit field in the 64-bit MSR.
07078 
07079   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
07080   read result and the value specified by AndData, and writes the result to the
07081   64-bit MSR specified by Index. The lower 32-bits of the value written to the
07082   MSR are returned. Extra left bits in AndData are stripped. The caller must
07083   either guarantee that Index and the data written is valid, or the caller must
07084   set up exception handlers to catch the exceptions. This function is only
07085   available on IA-32 and x64.
07086 
07087   If StartBit is greater than 31, then ASSERT().
07088   If EndBit is greater than 31, then ASSERT().
07089   If EndBit is less than StartBit, then ASSERT().
07090   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
07091 
07092   @param  Index     The 32-bit MSR index to write.
07093   @param  StartBit  The ordinal of the least significant bit in the bit field.
07094                     Range 0..31.
07095   @param  EndBit    The ordinal of the most significant bit in the bit field.
07096                     Range 0..31.
07097   @param  AndData   The value to AND with the read value from the MSR.
07098 
07099   @return The lower 32-bit of the value written to the MSR.
07100 
07101 **/
07102 UINT32
07103 EFIAPI
07104 AsmMsrBitFieldAnd32 (
07105   IN      UINT32                    Index,
07106   IN      UINTN                     StartBit,
07107   IN      UINTN                     EndBit,
07108   IN      UINT32                    AndData
07109   );
07110 
07111 
07112 /**
07113   Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
07114   bitwise OR, and writes the result back to the bit field in the
07115   64-bit MSR.
07116 
07117   Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
07118   bitwise OR between the read result and the value specified by
07119   AndData, and writes the result to the 64-bit MSR specified by Index. The
07120   lower 32-bits of the value written to the MSR are returned. Extra left bits
07121   in both AndData and OrData are stripped. The caller must either guarantee
07122   that Index and the data written is valid, or the caller must set up exception
07123   handlers to catch the exceptions. This function is only available on IA-32
07124   and x64.
07125 
07126   If StartBit is greater than 31, then ASSERT().
07127   If EndBit is greater than 31, then ASSERT().
07128   If EndBit is less than StartBit, then ASSERT().
07129   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
07130   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
07131 
07132   @param  Index     The 32-bit MSR index to write.
07133   @param  StartBit  The ordinal of the least significant bit in the bit field.
07134                     Range 0..31.
07135   @param  EndBit    The ordinal of the most significant bit in the bit field.
07136                     Range 0..31.
07137   @param  AndData   The value to AND with the read value from the MSR.
07138   @param  OrData    The value to OR with the result of the AND operation.
07139 
07140   @return The lower 32-bit of the value written to the MSR.
07141 
07142 **/
07143 UINT32
07144 EFIAPI
07145 AsmMsrBitFieldAndThenOr32 (
07146   IN      UINT32                    Index,
07147   IN      UINTN                     StartBit,
07148   IN      UINTN                     EndBit,
07149   IN      UINT32                    AndData,
07150   IN      UINT32                    OrData
07151   );
07152 
07153 
07154 /**
07155   Returns a 64-bit Machine Specific Register(MSR).
07156 
07157   Reads and returns the 64-bit MSR specified by Index. No parameter checking is
07158   performed on Index, and some Index values may cause CPU exceptions. The
07159   caller must either guarantee that Index is valid, or the caller must set up
07160   exception handlers to catch the exceptions. This function is only available
07161   on IA-32 and x64.
07162 
07163   @param  Index The 32-bit MSR index to read.
07164 
07165   @return The value of the MSR identified by Index.
07166 
07167 **/
07168 UINT64
07169 EFIAPI
07170 AsmReadMsr64 (
07171   IN      UINT32                    Index
07172   );
07173 
07174 
07175 /**
07176   Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
07177   value.
07178 
07179   Writes the 64-bit value specified by Value to the MSR specified by Index. The
07180   64-bit value written to the MSR is returned. No parameter checking is
07181   performed on Index or Value, and some of these may cause CPU exceptions. The
07182   caller must either guarantee that Index and Value are valid, or the caller
07183   must establish proper exception handlers. This function is only available on
07184   IA-32 and x64.
07185 
07186   @param  Index The 32-bit MSR index to write.
07187   @param  Value The 64-bit value to write to the MSR.
07188 
07189   @return Value
07190 
07191 **/
07192 UINT64
07193 EFIAPI
07194 AsmWriteMsr64 (
07195   IN      UINT32                    Index,
07196   IN      UINT64                    Value
07197   );
07198 
07199 
07200 /**
07201   Reads a 64-bit MSR, performs a bitwise OR, and writes the result
07202   back to the 64-bit MSR.
07203 
07204   Reads the 64-bit MSR specified by Index, performs a bitwise OR
07205   between the read result and the value specified by OrData, and writes the
07206   result to the 64-bit MSR specified by Index. The value written to the MSR is
07207   returned. No parameter checking is performed on Index or OrData, and some of
07208   these may cause CPU exceptions. The caller must either guarantee that Index
07209   and OrData are valid, or the caller must establish proper exception handlers.
07210   This function is only available on IA-32 and x64.
07211 
07212   @param  Index   The 32-bit MSR index to write.
07213   @param  OrData  The value to OR with the read value from the MSR.
07214 
07215   @return The value written back to the MSR.
07216 
07217 **/
07218 UINT64
07219 EFIAPI
07220 AsmMsrOr64 (
07221   IN      UINT32                    Index,
07222   IN      UINT64                    OrData
07223   );
07224 
07225 
07226 /**
07227   Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
07228   64-bit MSR.
07229 
07230   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
07231   read result and the value specified by OrData, and writes the result to the
07232   64-bit MSR specified by Index. The value written to the MSR is returned. No
07233   parameter checking is performed on Index or OrData, and some of these may
07234   cause CPU exceptions. The caller must either guarantee that Index and OrData
07235   are valid, or the caller must establish proper exception handlers. This
07236   function is only available on IA-32 and x64.
07237 
07238   @param  Index   The 32-bit MSR index to write.
07239   @param  AndData The value to AND with the read value from the MSR.
07240 
07241   @return The value written back to the MSR.
07242 
07243 **/
07244 UINT64
07245 EFIAPI
07246 AsmMsrAnd64 (
07247   IN      UINT32                    Index,
07248   IN      UINT64                    AndData
07249   );
07250 
07251 
07252 /**
07253   Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
07254   OR, and writes the result back to the 64-bit MSR.
07255 
07256   Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
07257   result and the value specified by AndData, performs a bitwise OR
07258   between the result of the AND operation and the value specified by OrData,
07259   and writes the result to the 64-bit MSR specified by Index. The value written
07260   to the MSR is returned. No parameter checking is performed on Index, AndData,
07261   or OrData, and some of these may cause CPU exceptions. The caller must either
07262   guarantee that Index, AndData, and OrData are valid, or the caller must
07263   establish proper exception handlers. This function is only available on IA-32
07264   and x64.
07265 
07266   @param  Index   The 32-bit MSR index to write.
07267   @param  AndData The value to AND with the read value from the MSR.
07268   @param  OrData  The value to OR with the result of the AND operation.
07269 
07270   @return The value written back to the MSR.
07271 
07272 **/
07273 UINT64
07274 EFIAPI
07275 AsmMsrAndThenOr64 (
07276   IN      UINT32                    Index,
07277   IN      UINT64                    AndData,
07278   IN      UINT64                    OrData
07279   );
07280 
07281 
07282 /**
07283   Reads a bit field of an MSR.
07284 
07285   Reads the bit field in the 64-bit MSR. The bit field is specified by the
07286   StartBit and the EndBit. The value of the bit field is returned. The caller
07287   must either guarantee that Index is valid, or the caller must set up
07288   exception handlers to catch the exceptions. This function is only available
07289   on IA-32 and x64.
07290 
07291   If StartBit is greater than 63, then ASSERT().
07292   If EndBit is greater than 63, then ASSERT().
07293   If EndBit is less than StartBit, then ASSERT().
07294 
07295   @param  Index     The 32-bit MSR index to read.
07296   @param  StartBit  The ordinal of the least significant bit in the bit field.
07297                     Range 0..63.
07298   @param  EndBit    The ordinal of the most significant bit in the bit field.
07299                     Range 0..63.
07300 
07301   @return The value read from the MSR.
07302 
07303 **/
07304 UINT64
07305 EFIAPI
07306 AsmMsrBitFieldRead64 (
07307   IN      UINT32                    Index,
07308   IN      UINTN                     StartBit,
07309   IN      UINTN                     EndBit
07310   );
07311 
07312 
07313 /**
07314   Writes a bit field to an MSR.
07315 
07316   Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
07317   the StartBit and the EndBit. All other bits in the destination MSR are
07318   preserved. The MSR written is returned. The caller must either guarantee
07319   that Index and the data written is valid, or the caller must set up exception
07320   handlers to catch the exceptions. This function is only available on IA-32 and x64.
07321 
07322   If StartBit is greater than 63, then ASSERT().
07323   If EndBit is greater than 63, then ASSERT().
07324   If EndBit is less than StartBit, then ASSERT().
07325   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
07326 
07327   @param  Index     The 32-bit MSR index to write.
07328   @param  StartBit  The ordinal of the least significant bit in the bit field.
07329                     Range 0..63.
07330   @param  EndBit    The ordinal of the most significant bit in the bit field.
07331                     Range 0..63.
07332   @param  Value     New value of the bit field.
07333 
07334   @return The value written back to the MSR.
07335 
07336 **/
07337 UINT64
07338 EFIAPI
07339 AsmMsrBitFieldWrite64 (
07340   IN      UINT32                    Index,
07341   IN      UINTN                     StartBit,
07342   IN      UINTN                     EndBit,
07343   IN      UINT64                    Value
07344   );
07345 
07346 
07347 /**
07348   Reads a bit field in a 64-bit MSR, performs a bitwise OR, and
07349   writes the result back to the bit field in the 64-bit MSR.
07350 
07351   Reads the 64-bit MSR specified by Index, performs a bitwise OR
07352   between the read result and the value specified by OrData, and writes the
07353   result to the 64-bit MSR specified by Index. The value written to the MSR is
07354   returned. Extra left bits in OrData are stripped. The caller must either
07355   guarantee that Index and the data written is valid, or the caller must set up
07356   exception handlers to catch the exceptions. This function is only available
07357   on IA-32 and x64.
07358 
07359   If StartBit is greater than 63, then ASSERT().
07360   If EndBit is greater than 63, then ASSERT().
07361   If EndBit is less than StartBit, then ASSERT().
07362   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
07363 
07364   @param  Index     The 32-bit MSR index to write.
07365   @param  StartBit  The ordinal of the least significant bit in the bit field.
07366                     Range 0..63.
07367   @param  EndBit    The ordinal of the most significant bit in the bit field.
07368                     Range 0..63.
07369   @param  OrData    The value to OR with the read value from the bit field.
07370 
07371   @return The value written back to the MSR.
07372 
07373 **/
07374 UINT64
07375 EFIAPI
07376 AsmMsrBitFieldOr64 (
07377   IN      UINT32                    Index,
07378   IN      UINTN                     StartBit,
07379   IN      UINTN                     EndBit,
07380   IN      UINT64                    OrData
07381   );
07382 
07383 
07384 /**
07385   Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
07386   result back to the bit field in the 64-bit MSR.
07387 
07388   Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
07389   read result and the value specified by AndData, and writes the result to the
07390   64-bit MSR specified by Index. The value written to the MSR is returned.
07391   Extra left bits in AndData are stripped. The caller must either guarantee
07392   that Index and the data written is valid, or the caller must set up exception
07393   handlers to catch the exceptions. This function is only available on IA-32
07394   and x64.
07395 
07396   If StartBit is greater than 63, then ASSERT().
07397   If EndBit is greater than 63, then ASSERT().
07398   If EndBit is less than StartBit, then ASSERT().
07399   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
07400 
07401   @param  Index     The 32-bit MSR index to write.
07402   @param  StartBit  The ordinal of the least significant bit in the bit field.
07403                     Range 0..63.
07404   @param  EndBit    The ordinal of the most significant bit in the bit field.
07405                     Range 0..63.
07406   @param  AndData   The value to AND with the read value from the bit field.
07407 
07408   @return The value written back to the MSR.
07409 
07410 **/
07411 UINT64
07412 EFIAPI
07413 AsmMsrBitFieldAnd64 (
07414   IN      UINT32                    Index,
07415   IN      UINTN                     StartBit,
07416   IN      UINTN                     EndBit,
07417   IN      UINT64                    AndData
07418   );
07419 
07420 
07421 /**
07422   Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
07423   bitwise OR, and writes the result back to the bit field in the
07424   64-bit MSR.
07425 
07426   Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
07427   a bitwise OR between the read result and the value specified by
07428   AndData, and writes the result to the 64-bit MSR specified by Index. The
07429   value written to the MSR is returned. Extra left bits in both AndData and
07430   OrData are stripped. The caller must either guarantee that Index and the data
07431   written is valid, or the caller must set up exception handlers to catch the
07432   exceptions. This function is only available on IA-32 and x64.
07433 
07434   If StartBit is greater than 63, then ASSERT().
07435   If EndBit is greater than 63, then ASSERT().
07436   If EndBit is less than StartBit, then ASSERT().
07437   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
07438   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
07439 
07440   @param  Index     The 32-bit MSR index to write.
07441   @param  StartBit  The ordinal of the least significant bit in the bit field.
07442                     Range 0..63.
07443   @param  EndBit    The ordinal of the most significant bit in the bit field.
07444                     Range 0..63.
07445   @param  AndData   The value to AND with the read value from the bit field.
07446   @param  OrData    The value to OR with the result of the AND operation.
07447 
07448   @return The value written back to the MSR.
07449 
07450 **/
07451 UINT64
07452 EFIAPI
07453 AsmMsrBitFieldAndThenOr64 (
07454   IN      UINT32                    Index,
07455   IN      UINTN                     StartBit,
07456   IN      UINTN                     EndBit,
07457   IN      UINT64                    AndData,
07458   IN      UINT64                    OrData
07459   );
07460 
07461 
07462 /**
07463   Reads the current value of the EFLAGS register.
07464 
07465   Reads and returns the current value of the EFLAGS register. This function is
07466   only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a
07467   64-bit value on x64.
07468 
07469   @return EFLAGS on IA-32 or RFLAGS on x64.
07470 
07471 **/
07472 UINTN
07473 EFIAPI
07474 AsmReadEflags (
07475   VOID
07476   );
07477 
07478 
07479 /**
07480   Reads the current value of the Control Register 0 (CR0).
07481 
07482   Reads and returns the current value of CR0. This function is only available
07483   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
07484   x64.
07485 
07486   @return The value of the Control Register 0 (CR0).
07487 
07488 **/
07489 UINTN
07490 EFIAPI
07491 AsmReadCr0 (
07492   VOID
07493   );
07494 
07495 
07496 /**
07497   Reads the current value of the Control Register 2 (CR2).
07498 
07499   Reads and returns the current value of CR2. This function is only available
07500   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
07501   x64.
07502 
07503   @return The value of the Control Register 2 (CR2).
07504 
07505 **/
07506 UINTN
07507 EFIAPI
07508 AsmReadCr2 (
07509   VOID
07510   );
07511 
07512 
07513 /**
07514   Reads the current value of the Control Register 3 (CR3).
07515 
07516   Reads and returns the current value of CR3. This function is only available
07517   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
07518   x64.
07519 
07520   @return The value of the Control Register 3 (CR3).
07521 
07522 **/
07523 UINTN
07524 EFIAPI
07525 AsmReadCr3 (
07526   VOID
07527   );
07528 
07529 
07530 /**
07531   Reads the current value of the Control Register 4 (CR4).
07532 
07533   Reads and returns the current value of CR4. This function is only available
07534   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
07535   x64.
07536 
07537   @return The value of the Control Register 4 (CR4).
07538 
07539 **/
07540 UINTN
07541 EFIAPI
07542 AsmReadCr4 (
07543   VOID
07544   );
07545 
07546 
07547 /**
07548   Writes a value to Control Register 0 (CR0).
07549 
07550   Writes and returns a new value to CR0. This function is only available on
07551   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
07552 
07553   @param  Cr0 The value to write to CR0.
07554 
07555   @return The value written to CR0.
07556 
07557 **/
07558 UINTN
07559 EFIAPI
07560 AsmWriteCr0 (
07561   UINTN  Cr0
07562   );
07563 
07564 
07565 /**
07566   Writes a value to Control Register 2 (CR2).
07567 
07568   Writes and returns a new value to CR2. This function is only available on
07569   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
07570 
07571   @param  Cr2 The value to write to CR2.
07572 
07573   @return The value written to CR2.
07574 
07575 **/
07576 UINTN
07577 EFIAPI
07578 AsmWriteCr2 (
07579   UINTN  Cr2
07580   );
07581 
07582 
07583 /**
07584   Writes a value to Control Register 3 (CR3).
07585 
07586   Writes and returns a new value to CR3. This function is only available on
07587   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
07588 
07589   @param  Cr3 The value to write to CR3.
07590 
07591   @return The value written to CR3.
07592 
07593 **/
07594 UINTN
07595 EFIAPI
07596 AsmWriteCr3 (
07597   UINTN  Cr3
07598   );
07599 
07600 
07601 /**
07602   Writes a value to Control Register 4 (CR4).
07603 
07604   Writes and returns a new value to CR4. This function is only available on
07605   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
07606 
07607   @param  Cr4 The value to write to CR4.
07608 
07609   @return The value written to CR4.
07610 
07611 **/
07612 UINTN
07613 EFIAPI
07614 AsmWriteCr4 (
07615   UINTN  Cr4
07616   );
07617 
07618 
07619 /**
07620   Reads the current value of Debug Register 0 (DR0).
07621 
07622   Reads and returns the current value of DR0. This function is only available
07623   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
07624   x64.
07625 
07626   @return The value of Debug Register 0 (DR0).
07627 
07628 **/
07629 UINTN
07630 EFIAPI
07631 AsmReadDr0 (
07632   VOID
07633   );
07634 
07635 
07636 /**
07637   Reads the current value of Debug Register 1 (DR1).
07638 
07639   Reads and returns the current value of DR1. This function is only available
07640   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
07641   x64.
07642 
07643   @return The value of Debug Register 1 (DR1).
07644 
07645 **/
07646 UINTN
07647 EFIAPI
07648 AsmReadDr1 (
07649   VOID
07650   );
07651 
07652 
07653 /**
07654   Reads the current value of Debug Register 2 (DR2).
07655 
07656   Reads and returns the current value of DR2. This function is only available
07657   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
07658   x64.
07659 
07660   @return The value of Debug Register 2 (DR2).
07661 
07662 **/
07663 UINTN
07664 EFIAPI
07665 AsmReadDr2 (
07666   VOID
07667   );
07668 
07669 
07670 /**
07671   Reads the current value of Debug Register 3 (DR3).
07672 
07673   Reads and returns the current value of DR3. This function is only available
07674   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
07675   x64.
07676 
07677   @return The value of Debug Register 3 (DR3).
07678 
07679 **/
07680 UINTN
07681 EFIAPI
07682 AsmReadDr3 (
07683   VOID
07684   );
07685 
07686 
07687 /**
07688   Reads the current value of Debug Register 4 (DR4).
07689 
07690   Reads and returns the current value of DR4. This function is only available
07691   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
07692   x64.
07693 
07694   @return The value of Debug Register 4 (DR4).
07695 
07696 **/
07697 UINTN
07698 EFIAPI
07699 AsmReadDr4 (
07700   VOID
07701   );
07702 
07703 
07704 /**
07705   Reads the current value of Debug Register 5 (DR5).
07706 
07707   Reads and returns the current value of DR5. This function is only available
07708   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
07709   x64.
07710 
07711   @return The value of Debug Register 5 (DR5).
07712 
07713 **/
07714 UINTN
07715 EFIAPI
07716 AsmReadDr5 (
07717   VOID
07718   );
07719 
07720 
07721 /**
07722   Reads the current value of Debug Register 6 (DR6).
07723 
07724   Reads and returns the current value of DR6. This function is only available
07725   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
07726   x64.
07727 
07728   @return The value of Debug Register 6 (DR6).
07729 
07730 **/
07731 UINTN
07732 EFIAPI
07733 AsmReadDr6 (
07734   VOID
07735   );
07736 
07737 
07738 /**
07739   Reads the current value of Debug Register 7 (DR7).
07740 
07741   Reads and returns the current value of DR7. This function is only available
07742   on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
07743   x64.
07744 
07745   @return The value of Debug Register 7 (DR7).
07746 
07747 **/
07748 UINTN
07749 EFIAPI
07750 AsmReadDr7 (
07751   VOID
07752   );
07753 
07754 
07755 /**
07756   Writes a value to Debug Register 0 (DR0).
07757 
07758   Writes and returns a new value to DR0. This function is only available on
07759   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
07760 
07761   @param  Dr0 The value to write to Dr0.
07762 
07763   @return The value written to Debug Register 0 (DR0).
07764 
07765 **/
07766 UINTN
07767 EFIAPI
07768 AsmWriteDr0 (
07769   UINTN  Dr0
07770   );
07771 
07772 
07773 /**
07774   Writes a value to Debug Register 1 (DR1).
07775 
07776   Writes and returns a new value to DR1. This function is only available on
07777   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
07778 
07779   @param  Dr1 The value to write to Dr1.
07780 
07781   @return The value written to Debug Register 1 (DR1).
07782 
07783 **/
07784 UINTN
07785 EFIAPI
07786 AsmWriteDr1 (
07787   UINTN  Dr1
07788   );
07789 
07790 
07791 /**
07792   Writes a value to Debug Register 2 (DR2).
07793 
07794   Writes and returns a new value to DR2. This function is only available on
07795   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
07796 
07797   @param  Dr2 The value to write to Dr2.
07798 
07799   @return The value written to Debug Register 2 (DR2).
07800 
07801 **/
07802 UINTN
07803 EFIAPI
07804 AsmWriteDr2 (
07805   UINTN  Dr2
07806   );
07807 
07808 
07809 /**
07810   Writes a value to Debug Register 3 (DR3).
07811 
07812   Writes and returns a new value to DR3. This function is only available on
07813   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
07814 
07815   @param  Dr3 The value to write to Dr3.
07816 
07817   @return The value written to Debug Register 3 (DR3).
07818 
07819 **/
07820 UINTN
07821 EFIAPI
07822 AsmWriteDr3 (
07823   UINTN  Dr3
07824   );
07825 
07826 
07827 /**
07828   Writes a value to Debug Register 4 (DR4).
07829 
07830   Writes and returns a new value to DR4. This function is only available on
07831   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
07832 
07833   @param  Dr4 The value to write to Dr4.
07834 
07835   @return The value written to Debug Register 4 (DR4).
07836 
07837 **/
07838 UINTN
07839 EFIAPI
07840 AsmWriteDr4 (
07841   UINTN  Dr4
07842   );
07843 
07844 
07845 /**
07846   Writes a value to Debug Register 5 (DR5).
07847 
07848   Writes and returns a new value to DR5. This function is only available on
07849   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
07850 
07851   @param  Dr5 The value to write to Dr5.
07852 
07853   @return The value written to Debug Register 5 (DR5).
07854 
07855 **/
07856 UINTN
07857 EFIAPI
07858 AsmWriteDr5 (
07859   UINTN  Dr5
07860   );
07861 
07862 
07863 /**
07864   Writes a value to Debug Register 6 (DR6).
07865 
07866   Writes and returns a new value to DR6. This function is only available on
07867   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
07868 
07869   @param  Dr6 The value to write to Dr6.
07870 
07871   @return The value written to Debug Register 6 (DR6).
07872 
07873 **/
07874 UINTN
07875 EFIAPI
07876 AsmWriteDr6 (
07877   UINTN  Dr6
07878   );
07879 
07880 
07881 /**
07882   Writes a value to Debug Register 7 (DR7).
07883 
07884   Writes and returns a new value to DR7. This function is only available on
07885   IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
07886 
07887   @param  Dr7 The value to write to Dr7.
07888 
07889   @return The value written to Debug Register 7 (DR7).
07890 
07891 **/
07892 UINTN
07893 EFIAPI
07894 AsmWriteDr7 (
07895   UINTN  Dr7
07896   );
07897 
07898 
07899 /**
07900   Reads the current value of Code Segment Register (CS).
07901 
07902   Reads and returns the current value of CS. This function is only available on
07903   IA-32 and x64.
07904 
07905   @return The current value of CS.
07906 
07907 **/
07908 UINT16
07909 EFIAPI
07910 AsmReadCs (
07911   VOID
07912   );
07913 
07914 
07915 /**
07916   Reads the current value of Data Segment Register (DS).
07917 
07918   Reads and returns the current value of DS. This function is only available on
07919   IA-32 and x64.
07920 
07921   @return The current value of DS.
07922 
07923 **/
07924 UINT16
07925 EFIAPI
07926 AsmReadDs (
07927   VOID
07928   );
07929 
07930 
07931 /**
07932   Reads the current value of Extra Segment Register (ES).
07933 
07934   Reads and returns the current value of ES. This function is only available on
07935   IA-32 and x64.
07936 
07937   @return The current value of ES.
07938 
07939 **/
07940 UINT16
07941 EFIAPI
07942 AsmReadEs (
07943   VOID
07944   );
07945 
07946 
07947 /**
07948   Reads the current value of FS Data Segment Register (FS).
07949 
07950   Reads and returns the current value of FS. This function is only available on
07951   IA-32 and x64.
07952 
07953   @return The current value of FS.
07954 
07955 **/
07956 UINT16
07957 EFIAPI
07958 AsmReadFs (
07959   VOID
07960   );
07961 
07962 
07963 /**
07964   Reads the current value of GS Data Segment Register (GS).
07965 
07966   Reads and returns the current value of GS. This function is only available on
07967   IA-32 and x64.
07968 
07969   @return The current value of GS.
07970 
07971 **/
07972 UINT16
07973 EFIAPI
07974 AsmReadGs (
07975   VOID
07976   );
07977 
07978 
07979 /**
07980   Reads the current value of Stack Segment Register (SS).
07981 
07982   Reads and returns the current value of SS. This function is only available on
07983   IA-32 and x64.
07984 
07985   @return The current value of SS.
07986 
07987 **/
07988 UINT16
07989 EFIAPI
07990 AsmReadSs (
07991   VOID
07992   );
07993 
07994 
07995 /**
07996   Reads the current value of Task Register (TR).
07997 
07998   Reads and returns the current value of TR. This function is only available on
07999   IA-32 and x64.
08000 
08001   @return The current value of TR.
08002 
08003 **/
08004 UINT16
08005 EFIAPI
08006 AsmReadTr (
08007   VOID
08008   );
08009 
08010 
08011 /**
08012   Reads the current Global Descriptor Table Register(GDTR) descriptor.
08013 
08014   Reads and returns the current GDTR descriptor and returns it in Gdtr. This
08015   function is only available on IA-32 and x64.
08016 
08017   If Gdtr is NULL, then ASSERT().
08018 
08019   @param  Gdtr  The pointer to a GDTR descriptor.
08020 
08021 **/
08022 VOID
08023 EFIAPI
08024 AsmReadGdtr (
08025   OUT     IA32_DESCRIPTOR           *Gdtr
08026   );
08027 
08028 
08029 /**
08030   Writes the current Global Descriptor Table Register (GDTR) descriptor.
08031 
08032   Writes and the current GDTR descriptor specified by Gdtr. This function is
08033   only available on IA-32 and x64.
08034 
08035   If Gdtr is NULL, then ASSERT().
08036 
08037   @param  Gdtr  The pointer to a GDTR descriptor.
08038 
08039 **/
08040 VOID
08041 EFIAPI
08042 AsmWriteGdtr (
08043   IN      CONST IA32_DESCRIPTOR     *Gdtr
08044   );
08045 
08046 
08047 /**
08048   Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.
08049 
08050   Reads and returns the current IDTR descriptor and returns it in Idtr. This
08051   function is only available on IA-32 and x64.
08052 
08053   If Idtr is NULL, then ASSERT().
08054 
08055   @param  Idtr  The pointer to a IDTR descriptor.
08056 
08057 **/
08058 VOID
08059 EFIAPI
08060 AsmReadIdtr (
08061   OUT     IA32_DESCRIPTOR           *Idtr
08062   );
08063 
08064 
08065 /**
08066   Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.
08067 
08068   Writes the current IDTR descriptor and returns it in Idtr. This function is
08069   only available on IA-32 and x64.
08070 
08071   If Idtr is NULL, then ASSERT().
08072 
08073   @param  Idtr  The pointer to a IDTR descriptor.
08074 
08075 **/
08076 VOID
08077 EFIAPI
08078 AsmWriteIdtr (
08079   IN      CONST IA32_DESCRIPTOR     *Idtr
08080   );
08081 
08082 
08083 /**
08084   Reads the current Local Descriptor Table Register(LDTR) selector.
08085 
08086   Reads and returns the current 16-bit LDTR descriptor value. This function is
08087   only available on IA-32 and x64.
08088 
08089   @return The current selector of LDT.
08090 
08091 **/
08092 UINT16
08093 EFIAPI
08094 AsmReadLdtr (
08095   VOID
08096   );
08097 
08098 
08099 /**
08100   Writes the current Local Descriptor Table Register (LDTR) selector.
08101 
08102   Writes and the current LDTR descriptor specified by Ldtr. This function is
08103   only available on IA-32 and x64.
08104 
08105   @param  Ldtr  16-bit LDTR selector value.
08106 
08107 **/
08108 VOID
08109 EFIAPI
08110 AsmWriteLdtr (
08111   IN      UINT16                    Ldtr
08112   );
08113 
08114 
08115 /**
08116   Save the current floating point/SSE/SSE2 context to a buffer.
08117 
08118   Saves the current floating point/SSE/SSE2 state to the buffer specified by
08119   Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
08120   available on IA-32 and x64.
08121 
08122   If Buffer is NULL, then ASSERT().
08123   If Buffer is not aligned on a 16-byte boundary, then ASSERT().
08124 
08125   @param  Buffer  The pointer to a buffer to save the floating point/SSE/SSE2 context.
08126 
08127 **/
08128 VOID
08129 EFIAPI
08130 AsmFxSave (
08131   OUT     IA32_FX_BUFFER            *Buffer
08132   );
08133 
08134 
08135 /**
08136   Restores the current floating point/SSE/SSE2 context from a buffer.
08137 
08138   Restores the current floating point/SSE/SSE2 state from the buffer specified
08139   by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
08140   only available on IA-32 and x64.
08141 
08142   If Buffer is NULL, then ASSERT().
08143   If Buffer is not aligned on a 16-byte boundary, then ASSERT().
08144   If Buffer was not saved with AsmFxSave(), then ASSERT().
08145 
08146   @param  Buffer  The pointer to a buffer to save the floating point/SSE/SSE2 context.
08147 
08148 **/
08149 VOID
08150 EFIAPI
08151 AsmFxRestore (
08152   IN      CONST IA32_FX_BUFFER      *Buffer
08153   );
08154 
08155 
08156 /**
08157   Reads the current value of 64-bit MMX Register #0 (MM0).
08158 
08159   Reads and returns the current value of MM0. This function is only available
08160   on IA-32 and x64.
08161 
08162   @return The current value of MM0.
08163 
08164 **/
08165 UINT64
08166 EFIAPI
08167 AsmReadMm0 (
08168   VOID
08169   );
08170 
08171 
08172 /**
08173   Reads the current value of 64-bit MMX Register #1 (MM1).
08174 
08175   Reads and returns the current value of MM1. This function is only available
08176   on IA-32 and x64.
08177 
08178   @return The current value of MM1.
08179 
08180 **/
08181 UINT64
08182 EFIAPI
08183 AsmReadMm1 (
08184   VOID
08185   );
08186 
08187 
08188 /**
08189   Reads the current value of 64-bit MMX Register #2 (MM2).
08190 
08191   Reads and returns the current value of MM2. This function is only available
08192   on IA-32 and x64.
08193 
08194   @return The current value of MM2.
08195 
08196 **/
08197 UINT64
08198 EFIAPI
08199 AsmReadMm2 (
08200   VOID
08201   );
08202 
08203 
08204 /**
08205   Reads the current value of 64-bit MMX Register #3 (MM3).
08206 
08207   Reads and returns the current value of MM3. This function is only available
08208   on IA-32 and x64.
08209 
08210   @return The current value of MM3.
08211 
08212 **/
08213 UINT64
08214 EFIAPI
08215 AsmReadMm3 (
08216   VOID
08217   );
08218 
08219 
08220 /**
08221   Reads the current value of 64-bit MMX Register #4 (MM4).
08222 
08223   Reads and returns the current value of MM4. This function is only available
08224   on IA-32 and x64.
08225 
08226   @return The current value of MM4.
08227 
08228 **/
08229 UINT64
08230 EFIAPI
08231 AsmReadMm4 (
08232   VOID
08233   );
08234 
08235 
08236 /**
08237   Reads the current value of 64-bit MMX Register #5 (MM5).
08238 
08239   Reads and returns the current value of MM5. This function is only available
08240   on IA-32 and x64.
08241 
08242   @return The current value of MM5.
08243 
08244 **/
08245 UINT64
08246 EFIAPI
08247 AsmReadMm5 (
08248   VOID
08249   );
08250 
08251 
08252 /**
08253   Reads the current value of 64-bit MMX Register #6 (MM6).
08254 
08255   Reads and returns the current value of MM6. This function is only available
08256   on IA-32 and x64.
08257 
08258   @return The current value of MM6.
08259 
08260 **/
08261 UINT64
08262 EFIAPI
08263 AsmReadMm6 (
08264   VOID
08265   );
08266 
08267 
08268 /**
08269   Reads the current value of 64-bit MMX Register #7 (MM7).
08270 
08271   Reads and returns the current value of MM7. This function is only available
08272   on IA-32 and x64.
08273 
08274   @return The current value of MM7.
08275 
08276 **/
08277 UINT64
08278 EFIAPI
08279 AsmReadMm7 (
08280   VOID
08281   );
08282 
08283 
08284 /**
08285   Writes the current value of 64-bit MMX Register #0 (MM0).
08286 
08287   Writes the current value of MM0. This function is only available on IA32 and
08288   x64.
08289 
08290   @param  Value The 64-bit value to write to MM0.
08291 
08292 **/
08293 VOID
08294 EFIAPI
08295 AsmWriteMm0 (
08296   IN      UINT64                    Value
08297   );
08298 
08299 
08300 /**
08301   Writes the current value of 64-bit MMX Register #1 (MM1).
08302 
08303   Writes the current value of MM1. This function is only available on IA32 and
08304   x64.
08305 
08306   @param  Value The 64-bit value to write to MM1.
08307 
08308 **/
08309 VOID
08310 EFIAPI
08311 AsmWriteMm1 (
08312   IN      UINT64                    Value
08313   );
08314 
08315 
08316 /**
08317   Writes the current value of 64-bit MMX Register #2 (MM2).
08318 
08319   Writes the current value of MM2. This function is only available on IA32 and
08320   x64.
08321 
08322   @param  Value The 64-bit value to write to MM2.
08323 
08324 **/
08325 VOID
08326 EFIAPI
08327 AsmWriteMm2 (
08328   IN      UINT64                    Value
08329   );
08330 
08331 
08332 /**
08333   Writes the current value of 64-bit MMX Register #3 (MM3).
08334 
08335   Writes the current value of MM3. This function is only available on IA32 and
08336   x64.
08337 
08338   @param  Value The 64-bit value to write to MM3.
08339 
08340 **/
08341 VOID
08342 EFIAPI
08343 AsmWriteMm3 (
08344   IN      UINT64                    Value
08345   );
08346 
08347 
08348 /**
08349   Writes the current value of 64-bit MMX Register #4 (MM4).
08350 
08351   Writes the current value of MM4. This function is only available on IA32 and
08352   x64.
08353 
08354   @param  Value The 64-bit value to write to MM4.
08355 
08356 **/
08357 VOID
08358 EFIAPI
08359 AsmWriteMm4 (
08360   IN      UINT64                    Value
08361   );
08362 
08363 
08364 /**
08365   Writes the current value of 64-bit MMX Register #5 (MM5).
08366 
08367   Writes the current value of MM5. This function is only available on IA32 and
08368   x64.
08369 
08370   @param  Value The 64-bit value to write to MM5.
08371 
08372 **/
08373 VOID
08374 EFIAPI
08375 AsmWriteMm5 (
08376   IN      UINT64                    Value
08377   );
08378 
08379 
08380 /**
08381   Writes the current value of 64-bit MMX Register #6 (MM6).
08382 
08383   Writes the current value of MM6. This function is only available on IA32 and
08384   x64.
08385 
08386   @param  Value The 64-bit value to write to MM6.
08387 
08388 **/
08389 VOID
08390 EFIAPI
08391 AsmWriteMm6 (
08392   IN      UINT64                    Value
08393   );
08394 
08395 
08396 /**
08397   Writes the current value of 64-bit MMX Register #7 (MM7).
08398 
08399   Writes the current value of MM7. This function is only available on IA32 and
08400   x64.
08401 
08402   @param  Value The 64-bit value to write to MM7.
08403 
08404 **/
08405 VOID
08406 EFIAPI
08407 AsmWriteMm7 (
08408   IN      UINT64                    Value
08409   );
08410 
08411 
08412 /**
08413   Reads the current value of Time Stamp Counter (TSC).
08414 
08415   Reads and returns the current value of TSC. This function is only available
08416   on IA-32 and x64.
08417 
08418   @return The current value of TSC
08419 
08420 **/
08421 UINT64
08422 EFIAPI
08423 AsmReadTsc (
08424   VOID
08425   );
08426 
08427 
08428 /**
08429   Reads the current value of a Performance Counter (PMC).
08430 
08431   Reads and returns the current value of performance counter specified by
08432   Index. This function is only available on IA-32 and x64.
08433 
08434   @param  Index The 32-bit Performance Counter index to read.
08435 
08436   @return The value of the PMC specified by Index.
08437 
08438 **/
08439 UINT64
08440 EFIAPI
08441 AsmReadPmc (
08442   IN      UINT32                    Index
08443   );
08444 
08445 
08446 /**
08447   Sets up a monitor buffer that is used by AsmMwait().
08448 
08449   Executes a MONITOR instruction with the register state specified by Eax, Ecx
08450   and Edx. Returns Eax. This function is only available on IA-32 and x64.
08451 
08452   @param  Eax The value to load into EAX or RAX before executing the MONITOR
08453               instruction.
08454   @param  Ecx The value to load into ECX or RCX before executing the MONITOR
08455               instruction.
08456   @param  Edx The value to load into EDX or RDX before executing the MONITOR
08457               instruction.
08458 
08459   @return Eax
08460 
08461 **/
08462 UINTN
08463 EFIAPI
08464 AsmMonitor (
08465   IN      UINTN                     Eax,
08466   IN      UINTN                     Ecx,
08467   IN      UINTN                     Edx
08468   );
08469 
08470 
08471 /**
08472   Executes an MWAIT instruction.
08473 
08474   Executes an MWAIT instruction with the register state specified by Eax and
08475   Ecx. Returns Eax. This function is only available on IA-32 and x64.
08476 
08477   @param  Eax The value to load into EAX or RAX before executing the MONITOR
08478               instruction.
08479   @param  Ecx The value to load into ECX or RCX before executing the MONITOR
08480               instruction.
08481 
08482   @return Eax
08483 
08484 **/
08485 UINTN
08486 EFIAPI
08487 AsmMwait (
08488   IN      UINTN                     Eax,
08489   IN      UINTN                     Ecx
08490   );
08491 
08492 
08493 /**
08494   Executes a WBINVD instruction.
08495 
08496   Executes a WBINVD instruction. This function is only available on IA-32 and
08497   x64.
08498 
08499 **/
08500 VOID
08501 EFIAPI
08502 AsmWbinvd (
08503   VOID
08504   );
08505 
08506 
08507 /**
08508   Executes a INVD instruction.
08509 
08510   Executes a INVD instruction. This function is only available on IA-32 and
08511   x64.
08512 
08513 **/
08514 VOID
08515 EFIAPI
08516 AsmInvd (
08517   VOID
08518   );
08519 
08520 
08521 /**
08522   Flushes a cache line from all the instruction and data caches within the
08523   coherency domain of the CPU.
08524 
08525   Flushed the cache line specified by LinearAddress, and returns LinearAddress.
08526   This function is only available on IA-32 and x64.
08527 
08528   @param  LinearAddress The address of the cache line to flush. If the CPU is
08529                         in a physical addressing mode, then LinearAddress is a
08530                         physical address. If the CPU is in a virtual
08531                         addressing mode, then LinearAddress is a virtual
08532                         address.
08533 
08534   @return LinearAddress.
08535 **/
08536 VOID *
08537 EFIAPI
08538 AsmFlushCacheLine (
08539   IN      VOID                      *LinearAddress
08540   );
08541 
08542 
08543 /**
08544   Enables the 32-bit paging mode on the CPU.
08545 
08546   Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
08547   must be properly initialized prior to calling this service. This function
08548   assumes the current execution mode is 32-bit protected mode. This function is
08549   only available on IA-32. After the 32-bit paging mode is enabled, control is
08550   transferred to the function specified by EntryPoint using the new stack
08551   specified by NewStack and passing in the parameters specified by Context1 and
08552   Context2. Context1 and Context2 are optional and may be NULL. The function
08553   EntryPoint must never return.
08554 
08555   If the current execution mode is not 32-bit protected mode, then ASSERT().
08556   If EntryPoint is NULL, then ASSERT().
08557   If NewStack is NULL, then ASSERT().
08558 
08559   There are a number of constraints that must be followed before calling this
08560   function:
08561   1)  Interrupts must be disabled.
08562   2)  The caller must be in 32-bit protected mode with flat descriptors. This
08563       means all descriptors must have a base of 0 and a limit of 4GB.
08564   3)  CR0 and CR4 must be compatible with 32-bit protected mode with flat
08565       descriptors.
08566   4)  CR3 must point to valid page tables that will be used once the transition
08567       is complete, and those page tables must guarantee that the pages for this
08568       function and the stack are identity mapped.
08569 
08570   @param  EntryPoint  A pointer to function to call with the new stack after
08571                       paging is enabled.
08572   @param  Context1    A pointer to the context to pass into the EntryPoint
08573                       function as the first parameter after paging is enabled.
08574   @param  Context2    A pointer to the context to pass into the EntryPoint
08575                       function as the second parameter after paging is enabled.
08576   @param  NewStack    A pointer to the new stack to use for the EntryPoint
08577                       function after paging is enabled.
08578 
08579 **/
08580 VOID
08581 EFIAPI
08582 AsmEnablePaging32 (
08583   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
08584   IN      VOID                      *Context1,  OPTIONAL
08585   IN      VOID                      *Context2,  OPTIONAL
08586   IN      VOID                      *NewStack
08587   );
08588 
08589 
08590 /**
08591   Disables the 32-bit paging mode on the CPU.
08592 
08593   Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
08594   mode. This function assumes the current execution mode is 32-paged protected
08595   mode. This function is only available on IA-32. After the 32-bit paging mode
08596   is disabled, control is transferred to the function specified by EntryPoint
08597   using the new stack specified by NewStack and passing in the parameters
08598   specified by Context1 and Context2. Context1 and Context2 are optional and
08599   may be NULL. The function EntryPoint must never return.
08600 
08601   If the current execution mode is not 32-bit paged mode, then ASSERT().
08602   If EntryPoint is NULL, then ASSERT().
08603   If NewStack is NULL, then ASSERT().
08604 
08605   There are a number of constraints that must be followed before calling this
08606   function:
08607   1)  Interrupts must be disabled.
08608   2)  The caller must be in 32-bit paged mode.
08609   3)  CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
08610   4)  CR3 must point to valid page tables that guarantee that the pages for
08611       this function and the stack are identity mapped.
08612 
08613   @param  EntryPoint  A pointer to function to call with the new stack after
08614                       paging is disabled.
08615   @param  Context1    A pointer to the context to pass into the EntryPoint
08616                       function as the first parameter after paging is disabled.
08617   @param  Context2    A pointer to the context to pass into the EntryPoint
08618                       function as the second parameter after paging is
08619                       disabled.
08620   @param  NewStack    A pointer to the new stack to use for the EntryPoint
08621                       function after paging is disabled.
08622 
08623 **/
08624 VOID
08625 EFIAPI
08626 AsmDisablePaging32 (
08627   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
08628   IN      VOID                      *Context1,  OPTIONAL
08629   IN      VOID                      *Context2,  OPTIONAL
08630   IN      VOID                      *NewStack
08631   );
08632 
08633 
08634 /**
08635   Enables the 64-bit paging mode on the CPU.
08636 
08637   Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
08638   must be properly initialized prior to calling this service. This function
08639   assumes the current execution mode is 32-bit protected mode with flat
08640   descriptors. This function is only available on IA-32. After the 64-bit
08641   paging mode is enabled, control is transferred to the function specified by
08642   EntryPoint using the new stack specified by NewStack and passing in the
08643   parameters specified by Context1 and Context2. Context1 and Context2 are
08644   optional and may be 0. The function EntryPoint must never return.
08645 
08646   If the current execution mode is not 32-bit protected mode with flat
08647   descriptors, then ASSERT().
08648   If EntryPoint is 0, then ASSERT().
08649   If NewStack is 0, then ASSERT().
08650 
08651   @param  Cs          The 16-bit selector to load in the CS before EntryPoint
08652                       is called. The descriptor in the GDT that this selector
08653                       references must be setup for long mode.
08654   @param  EntryPoint  The 64-bit virtual address of the function to call with
08655                       the new stack after paging is enabled.
08656   @param  Context1    The 64-bit virtual address of the context to pass into
08657                       the EntryPoint function as the first parameter after
08658                       paging is enabled.
08659   @param  Context2    The 64-bit virtual address of the context to pass into
08660                       the EntryPoint function as the second parameter after
08661                       paging is enabled.
08662   @param  NewStack    The 64-bit virtual address of the new stack to use for
08663                       the EntryPoint function after paging is enabled.
08664 
08665 **/
08666 VOID
08667 EFIAPI
08668 AsmEnablePaging64 (
08669   IN      UINT16                    Cs,
08670   IN      UINT64                    EntryPoint,
08671   IN      UINT64                    Context1,  OPTIONAL
08672   IN      UINT64                    Context2,  OPTIONAL
08673   IN      UINT64                    NewStack
08674   );
08675 
08676 
08677 /**
08678   Disables the 64-bit paging mode on the CPU.
08679 
08680   Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
08681   mode. This function assumes the current execution mode is 64-paging mode.
08682   This function is only available on x64. After the 64-bit paging mode is
08683   disabled, control is transferred to the function specified by EntryPoint
08684   using the new stack specified by NewStack and passing in the parameters
08685   specified by Context1 and Context2. Context1 and Context2 are optional and
08686   may be 0. The function EntryPoint must never return.
08687 
08688   If the current execution mode is not 64-bit paged mode, then ASSERT().
08689   If EntryPoint is 0, then ASSERT().
08690   If NewStack is 0, then ASSERT().
08691 
08692   @param  Cs          The 16-bit selector to load in the CS before EntryPoint
08693                       is called. The descriptor in the GDT that this selector
08694                       references must be setup for 32-bit protected mode.
08695   @param  EntryPoint  The 64-bit virtual address of the function to call with
08696                       the new stack after paging is disabled.
08697   @param  Context1    The 64-bit virtual address of the context to pass into
08698                       the EntryPoint function as the first parameter after
08699                       paging is disabled.
08700   @param  Context2    The 64-bit virtual address of the context to pass into
08701                       the EntryPoint function as the second parameter after
08702                       paging is disabled.
08703   @param  NewStack    The 64-bit virtual address of the new stack to use for
08704                       the EntryPoint function after paging is disabled.
08705 
08706 **/
08707 VOID
08708 EFIAPI
08709 AsmDisablePaging64 (
08710   IN      UINT16                    Cs,
08711   IN      UINT32                    EntryPoint,
08712   IN      UINT32                    Context1,  OPTIONAL
08713   IN      UINT32                    Context2,  OPTIONAL
08714   IN      UINT32                    NewStack
08715   );
08716 
08717 
08718 //
08719 // 16-bit thunking services
08720 //
08721 
08722 /**
08723   Retrieves the properties for 16-bit thunk functions.
08724 
08725   Computes the size of the buffer and stack below 1MB required to use the
08726   AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
08727   buffer size is returned in RealModeBufferSize, and the stack size is returned
08728   in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
08729   then the actual minimum stack size is ExtraStackSize plus the maximum number
08730   of bytes that need to be passed to the 16-bit real mode code.
08731 
08732   If RealModeBufferSize is NULL, then ASSERT().
08733   If ExtraStackSize is NULL, then ASSERT().
08734 
08735   @param  RealModeBufferSize  A pointer to the size of the buffer below 1MB
08736                               required to use the 16-bit thunk functions.
08737   @param  ExtraStackSize      A pointer to the extra size of stack below 1MB
08738                               that the 16-bit thunk functions require for
08739                               temporary storage in the transition to and from
08740                               16-bit real mode.
08741 
08742 **/
08743 VOID
08744 EFIAPI
08745 AsmGetThunk16Properties (
08746   OUT     UINT32                    *RealModeBufferSize,
08747   OUT     UINT32                    *ExtraStackSize
08748   );
08749 
08750 
08751 /**
08752   Prepares all structures a code required to use AsmThunk16().
08753 
08754   Prepares all structures and code required to use AsmThunk16().
08755 
08756   This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
08757   virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
08758 
08759   If ThunkContext is NULL, then ASSERT().
08760 
08761   @param  ThunkContext  A pointer to the context structure that describes the
08762                         16-bit real mode code to call.
08763 
08764 **/
08765 VOID
08766 EFIAPI
08767 AsmPrepareThunk16 (
08768   IN OUT  THUNK_CONTEXT             *ThunkContext
08769   );
08770 
08771 
08772 /**
08773   Transfers control to a 16-bit real mode entry point and returns the results.
08774 
08775   Transfers control to a 16-bit real mode entry point and returns the results.
08776   AsmPrepareThunk16() must be called with ThunkContext before this function is used.
08777   This function must be called with interrupts disabled.
08778 
08779   The register state from the RealModeState field of ThunkContext is restored just prior
08780   to calling the 16-bit real mode entry point.  This includes the EFLAGS field of RealModeState,
08781   which is used to set the interrupt state when a 16-bit real mode entry point is called.
08782   Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
08783   The stack is initialized to the SS and ESP fields of RealModeState.  Any parameters passed to
08784   the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
08785   The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
08786   so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
08787   and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
08788   point must exit with a RETF instruction. The register state is captured into RealModeState immediately
08789   after the RETF instruction is executed.
08790 
08791   If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
08792   or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
08793   the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
08794 
08795   If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
08796   then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
08797   This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
08798 
08799   If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
08800   is invoked in big real mode.  Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
08801 
08802   If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
08803   ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
08804   disable the A20 mask.
08805 
08806   If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
08807   ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask.  If this INT 15 call fails,
08808   then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
08809 
08810   If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
08811   ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
08812 
08813   If ThunkContext is NULL, then ASSERT().
08814   If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
08815   If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
08816   ThunkAttributes, then ASSERT().
08817 
08818   This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
08819   virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1.
08820 
08821   @param  ThunkContext  A pointer to the context structure that describes the
08822                         16-bit real mode code to call.
08823 
08824 **/
08825 VOID
08826 EFIAPI
08827 AsmThunk16 (
08828   IN OUT  THUNK_CONTEXT             *ThunkContext
08829   );
08830 
08831 
08832 /**
08833   Prepares all structures and code for a 16-bit real mode thunk, transfers
08834   control to a 16-bit real mode entry point, and returns the results.
08835 
08836   Prepares all structures and code for a 16-bit real mode thunk, transfers
08837   control to a 16-bit real mode entry point, and returns the results. If the
08838   caller only need to perform a single 16-bit real mode thunk, then this
08839   service should be used. If the caller intends to make more than one 16-bit
08840   real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
08841   once and AsmThunk16() can be called for each 16-bit real mode thunk.
08842 
08843   This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
08844   virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
08845 
08846   See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
08847 
08848   @param  ThunkContext  A pointer to the context structure that describes the
08849                         16-bit real mode code to call.
08850 
08851 **/
08852 VOID
08853 EFIAPI
08854 AsmPrepareAndThunk16 (
08855   IN OUT  THUNK_CONTEXT             *ThunkContext
08856   );
08857 
08858 /**
08859   Generates a 16-bit random number through RDRAND instruction.
08860 
08861   if Rand is NULL, then ASSERT().
08862 
08863   @param[out]  Rand     Buffer pointer to store the random result.
08864 
08865   @retval TRUE          RDRAND call was successful.
08866   @retval FALSE         Failed attempts to call RDRAND.
08867 
08868  **/
08869 BOOLEAN
08870 EFIAPI
08871 AsmRdRand16 (
08872   OUT     UINT16                    *Rand
08873   );
08874 
08875 /**
08876   Generates a 32-bit random number through RDRAND instruction.
08877 
08878   if Rand is NULL, then ASSERT().
08879 
08880   @param[out]  Rand     Buffer pointer to store the random result.
08881 
08882   @retval TRUE          RDRAND call was successful.
08883   @retval FALSE         Failed attempts to call RDRAND.
08884 
08885 **/
08886 BOOLEAN
08887 EFIAPI
08888 AsmRdRand32 (
08889   OUT     UINT32                    *Rand
08890   );
08891 
08892 /**
08893   Generates a 64-bit random number through RDRAND instruction.
08894 
08895   if Rand is NULL, then ASSERT().
08896 
08897   @param[out]  Rand     Buffer pointer to store the random result.
08898 
08899   @retval TRUE          RDRAND call was successful.
08900   @retval FALSE         Failed attempts to call RDRAND.
08901 
08902 **/
08903 BOOLEAN
08904 EFIAPI
08905 AsmRdRand64  (
08906   OUT     UINT64                    *Rand
08907   );
08908 
08909 #endif
08910 #endif
08911 
08912