[mirror_edk2.git] / BaseTools / Source / C / FCE / Common.c

/** @file\r
\r
 Common library.\r
\r
 Copyright (c) 2011-2019, Intel Corporation. All rights reserved.<BR>\r
 SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
#include "Common.h"\r
\r
#define WARNING_STATUS_NUMBER         4\r
#define ERROR_STATUS_NUMBER           24\r
\r
CONST CHAR8 mHexStr[] = {'0','1','2','3','4','5','6','7','8','9','A','B','C','D','E','F'};\r
\r
CONST CHAR8 *mStatusString[] = {\r
  "Success",                      //  RETURN_SUCCESS                = 0\r
  "Warning Unknown Glyph",        //  RETURN_WARN_UNKNOWN_GLYPH     = 1\r
  "Warning Delete Failure",       //  RETURN_WARN_DELETE_FAILURE    = 2\r
  "Warning Write Failure",        //  RETURN_WARN_WRITE_FAILURE     = 3\r
  "Warning Buffer Too Small",     //  RETURN_WARN_BUFFER_TOO_SMALL  = 4\r
  "Load Error",                   //  RETURN_LOAD_ERROR             = 1  | MAX_BIT\r
  "Invalid Parameter",            //  RETURN_INVALID_PARAMETER      = 2  | MAX_BIT\r
  "Unsupported",                  //  RETURN_UNSUPPORTED            = 3  | MAX_BIT\r
  "Bad Buffer Size",              //  RETURN_BAD_BUFFER_SIZE        = 4  | MAX_BIT\r
  "Buffer Too Small",             //  RETURN_BUFFER_TOO_SMALL,      = 5  | MAX_BIT\r
  "Not Ready",                    //  RETURN_NOT_READY              = 6  | MAX_BIT\r
  "Device Error",                 //  RETURN_DEVICE_ERROR           = 7  | MAX_BIT\r
  "Write Protected",              //  RETURN_WRITE_PROTECTED        = 8  | MAX_BIT\r
  "Out of Resources",             //  RETURN_OUT_OF_RESOURCES       = 9  | MAX_BIT\r
  "Volume Corrupt",               //  RETURN_VOLUME_CORRUPTED       = 10 | MAX_BIT\r
  "Volume Full",                  //  RETURN_VOLUME_FULL            = 11 | MAX_BIT\r
  "No Media",                     //  RETURN_NO_MEDIA               = 12 | MAX_BIT\r
  "Media changed",                //  RETURN_MEDIA_CHANGED          = 13 | MAX_BIT\r
  "Not Found",                    //  RETURN_NOT_FOUND              = 14 | MAX_BIT\r
  "Access Denied",                //  RETURN_ACCESS_DENIED          = 15 | MAX_BIT\r
  "No Response",                  //  RETURN_NO_RESPONSE            = 16 | MAX_BIT\r
  "No mapping",                   //  RETURN_NO_MAPPING             = 17 | MAX_BIT\r
  "Time out",                     //  RETURN_TIMEOUT                = 18 | MAX_BIT\r
  "Not started",                  //  RETURN_NOT_STARTED            = 19 | MAX_BIT\r
  "Already started",              //  RETURN_ALREADY_STARTED        = 20 | MAX_BIT\r
  "Aborted",                      //  RETURN_ABORTED                = 21 | MAX_BIT\r
  "ICMP Error",                   //  RETURN_ICMP_ERROR             = 22 | MAX_BIT\r
  "TFTP Error",                   //  RETURN_TFTP_ERROR             = 23 | MAX_BIT\r
  "Protocol Error"                //  RETURN_PROTOCOL_ERROR         = 24 | MAX_BIT\r
};\r
\r
/**\r
  Copies one Null-terminated Unicode string to another Null-terminated Unicode\r
  string and returns the new Unicode string.\r
\r
  This function copies the contents of the Unicode string Source to the Unicode\r
  string Destination, and returns Destination. If Source and Destination\r
  overlap, then the results are undefined.\r
\r
  If Destination is NULL, then return NULL.\r
  If Destination is not aligned on a 16-bit boundary, then return NULL.\r
\r
  @param  Destination A pointer to a Null-terminated Unicode string.\r
  @param  Source      A pointer to a Null-terminated Unicode string.\r
\r
  @return Destination.\r
\r
**/\r
CHAR16 *\r
StrCpy (\r
  OUT     CHAR16                    *Destination,\r
  IN      CONST CHAR16              *Source\r
  )\r
{\r
  CHAR16                            *ReturnValue;\r
\r
  ReturnValue = NULL;\r
\r
  if ((Destination == NULL) || ((UINTN) Destination % 2 != 0)) {\r
    return NULL;\r
  }\r
\r
  ReturnValue = Destination;\r
  while (*Source != 0) {\r
    *(Destination++) = *(Source++);\r
  }\r
  *Destination = 0;\r
  return ReturnValue;\r
}\r
\r
/**\r
  Returns the length of a Null-terminated Unicode string.\r
\r
  This function returns the number of Unicode characters in the Null-terminated\r
  Unicode string specified by String.\r
\r
  If String is NULL, then return 0.\r
\r
  @param  String  A pointer to a Null-terminated Unicode string.\r
\r
  @return The length of String.\r
\r
**/\r
UINTN\r
FceStrLen (\r
  IN      CONST CHAR16              *String\r
  )\r
{\r
  UINTN           Length;\r
\r
  if (String == NULL) {\r
    return 0;\r
  }\r
  for (Length = 0; *String != L'\0'; String++, Length++) {\r
    ;\r
  }\r
  return Length;\r
}\r
\r
/**\r
  Returns the size of a Null-terminated Unicode string in bytes, including the\r
  Null terminator.\r
\r
  This function returns the size, in bytes, of the Null-terminated Unicode string\r
  specified by String.\r
\r
  If String is NULL, then ASSERT().\r
  If String is not aligned on a 16-bit boundary, then ASSERT().\r
  If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
  PcdMaximumUnicodeStringLength Unicode characters, not including the\r
  Null-terminator, then ASSERT().\r
\r
  @param  String  A pointer to a Null-terminated Unicode string.\r
\r
  @return The size of String.\r
\r
**/\r
UINTN\r
FceStrSize (\r
  IN      CONST CHAR16              *String\r
  )\r
{\r
  return (FceStrLen (String) + 1) * sizeof (*String);\r
}\r
\r
/**\r
  Compares two Null-terminated Unicode strings, and returns the difference\r
  between the first mismatched Unicode characters.\r
\r
  This function compares the Null-terminated Unicode string FirstString to the\r
  Null-terminated Unicode string SecondString. If FirstString is identical to\r
  SecondString, then 0 is returned. Otherwise, the value returned is the first\r
  mismatched Unicode character in SecondString subtracted from the first\r
  mismatched Unicode character in FirstString.\r
\r
  @param  FirstString   A pointer to a Null-terminated Unicode string.\r
  @param  SecondString  A pointer to a Null-terminated Unicode string.\r
\r
  @retval 0      FirstString is identical to SecondString.\r
  @return others FirstString is not identical to SecondString.\r
\r
**/\r
INTN\r
FceStrCmp (\r
  IN      CONST CHAR16              *FirstString,\r
  IN      CONST CHAR16              *SecondString\r
  )\r
{\r
  while ((*FirstString != L'\0') && (*FirstString == *SecondString)) {\r
    FirstString++;\r
    SecondString++;\r
  }\r
  return *FirstString - *SecondString;\r
}\r
\r
/**\r
  Concatenates one Null-terminated Unicode string to another Null-terminated\r
  Unicode string, and returns the concatenated Unicode string.\r
\r
  This function concatenates two Null-terminated Unicode strings. The contents\r
  of Null-terminated Unicode string Source are concatenated to the end of\r
  Null-terminated Unicode string Destination. The Null-terminated concatenated\r
  Unicode String is returned. If Source and Destination overlap, then the\r
  results are undefined.\r
\r
  If Destination is NULL, then ASSERT().\r
  If Destination is not aligned on a 16-bit boundary, then ASSERT().\r
  If Source is NULL, then ASSERT().\r
  If Source is not aligned on a 16-bit boundary, then ASSERT().\r
  If Source and Destination overlap, then ASSERT().\r
  If PcdMaximumUnicodeStringLength is not zero, and Destination contains more\r
  than PcdMaximumUnicodeStringLength Unicode characters, not including the\r
  Null-terminator, then ASSERT().\r
  If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
  PcdMaximumUnicodeStringLength Unicode characters, not including the\r
  Null-terminator, then ASSERT().\r
  If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination\r
  and Source results in a Unicode string with more than\r
  PcdMaximumUnicodeStringLength Unicode characters, not including the\r
  Null-terminator, then ASSERT().\r
\r
  @param  Destination A pointer to a Null-terminated Unicode string.\r
  @param  Source      A pointer to a Null-terminated Unicode string.\r
\r
  @return Destination.\r
\r
**/\r
CHAR16 *\r
StrCat (\r
  IN OUT  CHAR16                    *Destination,\r
  IN      CONST CHAR16              *Source\r
  )\r
{\r
  StrCpy (Destination + FceStrLen (Destination), Source);\r
\r
  //\r
  // Size of the resulting string should never be zero.\r
  // PcdMaximumUnicodeStringLength is tested inside FceStrLen().\r
  //\r
  ASSERT (FceStrSize (Destination) != 0);\r
  return Destination;\r
}\r
\r
/**\r
  Returns the first occurrence of a Null-terminated Unicode sub-string\r
  in a Null-terminated Unicode string.\r
\r
  This function scans the contents of the Null-terminated Unicode string\r
  specified by String and returns the first occurrence of SearchString.\r
  If SearchString is not found in String, then NULL is returned.  If\r
  the length of SearchString is zero, then String is\r
  returned.\r
\r
  If String is NULL, then ASSERT().\r
  If String is not aligned on a 16-bit boundary, then ASSERT().\r
  If SearchString is NULL, then ASSERT().\r
  If SearchString is not aligned on a 16-bit boundary, then ASSERT().\r
\r
  If PcdMaximumUnicodeStringLength is not zero, and SearchString\r
  or String contains more than PcdMaximumUnicodeStringLength Unicode\r
  characters, not including the Null-terminator, then ASSERT().\r
\r
  @param  String          A pointer to a Null-terminated Unicode string.\r
  @param  SearchString    A pointer to a Null-terminated Unicode string to search for.\r
\r
  @retval NULL            If the SearchString does not appear in String.\r
  @return others          If there is a match.\r
\r
**/\r
CHAR16 *\r
StrStr (\r
  IN      CONST CHAR16              *String,\r
  IN      CONST CHAR16              *SearchString\r
  )\r
{\r
  CONST CHAR16 *FirstMatch;\r
  CONST CHAR16 *SearchStringTmp;\r
\r
  //\r
  // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.\r
  // Length tests are performed inside FceStrLen().\r
  //\r
  ASSERT (FceStrSize (String) != 0);\r
  ASSERT (FceStrSize (SearchString) != 0);\r
\r
  if (*SearchString == L'\0') {\r
    return (CHAR16 *) String;\r
  }\r
\r
  while (*String != L'\0') {\r
    SearchStringTmp = SearchString;\r
    FirstMatch = String;\r
\r
    while ((*String == *SearchStringTmp)\r
            && (*String != L'\0')) {\r
      String++;\r
      SearchStringTmp++;\r
    }\r
\r
    if (*SearchStringTmp == L'\0') {\r
      return (CHAR16 *) FirstMatch;\r
    }\r
\r
    if (*String == L'\0') {\r
      return NULL;\r
    }\r
\r
    String = FirstMatch + 1;\r
  }\r
\r
  return NULL;\r
}\r
\r
/**\r
  Convert one Null-terminated ASCII string to a Null-terminated\r
  Unicode string and returns the Unicode string.\r
\r
  This function converts the contents of the ASCII string Source to the Unicode\r
  string Destination, and returns Destination.  The function terminates the\r
  Unicode string Destination by appending a Null-terminator character at the end.\r
  The caller is responsible to make sure Destination points to a buffer with size\r
  equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.\r
\r
  @param  Source        A pointer to a Null-terminated ASCII string.\r
  @param  Destination   A pointer to a Null-terminated Unicode string.\r
\r
  @return Destination.\r
  @return NULL          If Destination or Source is NULL, return NULL.\r
\r
**/\r
CHAR16 *\r
AsciiStrToUnicodeStr (\r
  IN      CONST CHAR8               *Source,\r
  OUT     CHAR16                    *Destination\r
  )\r
{\r
  CHAR16                            *ReturnValue;\r
\r
  ReturnValue = NULL;\r
\r
  if ((Destination == NULL) || (Source == NULL) || (strlen (Source) == 0)) {\r
    return NULL;\r
  }\r
  ReturnValue = Destination;\r
  while (*Source != '\0') {\r
    *(Destination++) = (CHAR16) *(Source++);\r
  }\r
  //\r
  // End the Destination with a NULL.\r
  //\r
  *Destination = '\0';\r
\r
  return ReturnValue;\r
}\r
\r
/**\r
  Internal function that convert a number to a string in Buffer.\r
\r
  Print worker function that converts a decimal or hexadecimal number to an ASCII string in Buffer.\r
\r
  @param  Buffer    Location to place the ASCII string of Value.\r
  @param  Value     The value to convert to a Decimal or Hexadecimal string in Buffer.\r
  @param  Radix     Radix of the value\r
\r
  @return A pointer to the end of buffer filled with ASCII string.\r
\r
**/\r
CHAR8 *\r
BasePrintLibValueToString (\r
  IN OUT CHAR8  *Buffer,\r
  IN INT64      Value,\r
  IN UINTN      Radix\r
  )\r
{\r
  UINT32  Remainder;\r
\r
  //\r
  // Loop to convert one digit at a time in reverse order\r
  //\r
  *Buffer = 0;\r
  do {\r
    Value = (INT64)DivU64x32Remainder ((UINT64)Value, (UINT32)Radix, &Remainder);\r
    *(++Buffer) = mHexStr[Remainder];\r
  } while (Value != 0);\r
\r
  //\r
  // Return pointer of the end of filled buffer.\r
  //\r
  return Buffer;\r
}\r
\r
/**\r
  Reads a 16-bit value from memory that may be unaligned.\r
\r
  This function returns the 16-bit value pointed to by Buffer. The function\r
  guarantees that the read operation does not produce an alignment fault.\r
\r
  If the Buffer is NULL, then ASSERT().\r
\r
  @param  Buffer  A pointer to a 16-bit value that may be unaligned.\r
\r
  @return The 16-bit value read from Buffer.\r
\r
**/\r
UINT16\r
FceReadUnaligned16 (\r
  IN CONST UINT16              *Buffer\r
  )\r
{\r
  ASSERT (Buffer != NULL);\r
\r
  return *Buffer;\r
}\r
\r
/**\r
  Reads a 32-bit value from memory that may be unaligned.\r
\r
  This function returns the 32-bit value pointed to by Buffer. The function\r
  guarantees that the read operation does not produce an alignment fault.\r
\r
  If the Buffer is NULL, then ASSERT().\r
\r
  @param  Buffer  A pointer to a 32-bit value that may be unaligned.\r
\r
  @return The 32-bit value read from Buffer.\r
\r
**/\r
UINT32\r
ReadUnaligned32 (\r
  IN CONST UINT32              *Buffer\r
  )\r
{\r
  ASSERT (Buffer != NULL);\r
\r
  return *Buffer;\r
}\r
\r
/**\r
  Internal function that places the character into the Buffer.\r
\r
  Internal function that places ASCII or Unicode character into the Buffer.\r
\r
  @param  Buffer      The buffer to place the Unicode or ASCII string.\r
  @param  EndBuffer   The end of the input Buffer. No characters will be\r
                      placed after that.\r
  @param  Length      The count of character to be placed into Buffer.\r
                      (Negative value indicates no buffer fill.)\r
  @param  Character   The character to be placed into Buffer.\r
  @param  Increment   The character increment in Buffer.\r
\r
  @return Buffer.\r
\r
**/\r
CHAR8 *\r
BasePrintLibFillBuffer (\r
  OUT CHAR8   *Buffer,\r
  IN  CHAR8   *EndBuffer,\r
  IN  INTN    Length,\r
  IN  UINTN   Character,\r
  IN  INTN    Increment\r
  )\r
{\r
  INTN  Index;\r
\r
  for (Index = 0; Index < Length && Buffer < EndBuffer; Index++) {\r
    *Buffer = (CHAR8) Character;\r
    if (Increment != 1) {\r
      *(Buffer + 1) = (CHAR8)(Character >> 8);\r
    }\r
    Buffer += Increment;\r
  }\r
\r
  return Buffer;\r
}\r
\r
/**\r
  Worker function that produces a Null-terminated string in an output buffer\r
  based on a Null-terminated format string and a VA_LIST argument list.\r
\r
  VSPrint function to process format and place the results in Buffer. Since a\r
  VA_LIST is used this routine allows the nesting of Vararg routines. Thus\r
  this is the main print working routine.\r
\r
  If COUNT_ONLY_NO_PRINT is set in Flags, Buffer will not be modified at all.\r
\r
  @param[out] Buffer          The character buffer to print the results of the\r
                              parsing of Format into.\r
  @param[in]  BufferSize      The maximum number of characters to put into\r
                              buffer.\r
  @param[in]  Flags           Initial flags value.\r
                              Can only have FORMAT_UNICODE, OUTPUT_UNICODE,\r
                              and COUNT_ONLY_NO_PRINT set.\r
  @param[in]  Format          A Null-terminated format string.\r
  @param[in]  VaListMarker    VA_LIST style variable argument list consumed by\r
                              processing Format.\r
  @param[in]  BaseListMarker  BASE_LIST style variable argument list consumed\r
                              by processing Format.\r
\r
  @return The number of characters printed not including the Null-terminator.\r
          If COUNT_ONLY_NO_PRINT was set returns the same, but without any\r
          modification to Buffer.\r
\r
**/\r
UINTN\r
BasePrintLibSPrintMarker (\r
  OUT CHAR8        *Buffer,\r
  IN  UINTN        BufferSize,\r
  IN  UINTN        Flags,\r
  IN  CONST CHAR8  *Format,\r
  IN  VA_LIST      VaListMarker,   OPTIONAL\r
  IN  BASE_LIST    BaseListMarker  OPTIONAL\r
  )\r
{\r
  CHAR8             *OriginalBuffer;\r
  CHAR8             *EndBuffer;\r
  CHAR8             ValueBuffer[MAXIMUM_VALUE_CHARACTERS];\r
  UINT32            BytesPerOutputCharacter;\r
  UINTN             BytesPerFormatCharacter;\r
  UINTN             FormatMask;\r
  UINTN             FormatCharacter;\r
  UINTN             Width;\r
  UINTN             Precision;\r
  INT64             Value;\r
  CONST CHAR8       *ArgumentString;\r
  UINTN             Character;\r
  EFI_GUID          *TmpGuid;\r
  TIME              *TmpTime;\r
  UINTN             Count;\r
  UINTN             ArgumentMask;\r
  INTN              BytesPerArgumentCharacter;\r
  UINTN             ArgumentCharacter;\r
  BOOLEAN           Done;\r
  UINTN             Index;\r
  CHAR8             Prefix;\r
  BOOLEAN           ZeroPad;\r
  BOOLEAN           Comma;\r
  UINTN             Digits;\r
  UINTN             Radix;\r
  RETURN_STATUS     Status;\r
  UINT32            GuidData1;\r
  UINT16            GuidData2;\r
  UINT16            GuidData3;\r
  UINTN             LengthToReturn;\r
\r
  //\r
  // If you change this code be sure to match the 2 versions of this function.\r
  // Nearly identical logic is found in the BasePrintLib and\r
  // DxePrintLibPrint2Protocol (both PrintLib instances).\r
  //\r
\r
  if ((Flags & COUNT_ONLY_NO_PRINT) != 0) {\r
    if (BufferSize == 0) {\r
      Buffer = NULL;\r
    }\r
  } else {\r
    //\r
    // We can run without a Buffer for counting only.\r
    //\r
    if (BufferSize == 0) {\r
      return 0;\r
    }\r
    ASSERT (Buffer != NULL);\r
  }\r
\r
  if ((Flags & OUTPUT_UNICODE) != 0) {\r
    BytesPerOutputCharacter = 2;\r
  } else {\r
    BytesPerOutputCharacter = 1;\r
  }\r
\r
  LengthToReturn = 0;\r
\r
  //\r
  // Reserve space for the Null terminator.\r
  //\r
  BufferSize--;\r
  OriginalBuffer = Buffer;\r
\r
  //\r
  // Set the tag for the end of the input Buffer.\r
  //\r
  EndBuffer      = Buffer + BufferSize * BytesPerOutputCharacter;\r
\r
  if ((Flags & FORMAT_UNICODE) != 0) {\r
    //\r
    // Make sure format string cannot contain more than PcdMaximumUnicodeStringLength\r
    // Unicode characters if PcdMaximumUnicodeStringLength is not zero.\r
    //\r
    ASSERT (FceStrSize ((CHAR16 *) Format) != 0);\r
    BytesPerFormatCharacter = 2;\r
    FormatMask = 0xffff;\r
  } else {\r
    //\r
    // Make sure format string cannot contain more than PcdMaximumAsciiStringLength\r
    // Ascii characters if PcdMaximumAsciiStringLength is not zero.\r
    //\r
    ASSERT (strlen (Format) + 1 != 0);\r
    BytesPerFormatCharacter = 1;\r
    FormatMask = 0xff;\r
  }\r
\r
  //\r
  // Get the first character from the format string\r
  //\r
  FormatCharacter = ((*Format & 0xff) | (*(Format + 1) << 8)) & FormatMask;\r
\r
  //\r
  // Loop until the end of the format string is reached or the output buffer is full\r
  //\r
  while (FormatCharacter != 0 && Buffer < EndBuffer) {\r
    //\r
    // Clear all the flag bits except those that may have been passed in\r
    //\r
    Flags &= (OUTPUT_UNICODE | FORMAT_UNICODE | COUNT_ONLY_NO_PRINT);\r
\r
    //\r
    // Set the default width to zero, and the default precision to 1\r
    //\r
    Width     = 0;\r
    Precision = 1;\r
    Prefix    = 0;\r
    Comma     = FALSE;\r
    ZeroPad   = FALSE;\r
    Count     = 0;\r
    Digits    = 0;\r
\r
    switch (FormatCharacter) {\r
    case '%':\r
      //\r
      // Parse Flags and Width\r
      //\r
      for (Done = FALSE; !Done; ) {\r
        Format += BytesPerFormatCharacter;\r
        FormatCharacter = ((*Format & 0xff) | (*(Format + 1) << 8)) & FormatMask;\r
        switch (FormatCharacter) {\r
        case '.':\r
          Flags |= PRECISION;\r
          break;\r
        case '-':\r
          Flags |= LEFT_JUSTIFY;\r
          break;\r
        case '+':\r
          Flags |= PREFIX_SIGN;\r
          break;\r
        case ' ':\r
          Flags |= PREFIX_BLANK;\r
          break;\r
        case ',':\r
          Flags |= COMMA_TYPE;\r
          break;\r
        case 'L':\r
        case 'l':\r
          Flags |= LONG_TYPE;\r
          break;\r
        case '*':\r
          if ((Flags & PRECISION) == 0) {\r
            Flags |= PAD_TO_WIDTH;\r
            if (BaseListMarker == NULL) {\r
              Width = VA_ARG (VaListMarker, UINTN);\r
            } else {\r
              Width = BASE_ARG (BaseListMarker, UINTN);\r
            }\r
          } else {\r
            if (BaseListMarker == NULL) {\r
              Precision = VA_ARG (VaListMarker, UINTN);\r
            } else {\r
              Precision = BASE_ARG (BaseListMarker, UINTN);\r
            }\r
          }\r
          break;\r
        case '0':\r
          if ((Flags & PRECISION) == 0) {\r
            Flags |= PREFIX_ZERO;\r
          }\r
        case '1':\r
        case '2':\r
        case '3':\r
        case '4':\r
        case '5':\r
        case '6':\r
        case '7':\r
        case '8':\r
        case '9':\r
          for (Count = 0; ((FormatCharacter >= '0') &&  (FormatCharacter <= '9')); ){\r
            Count = (Count * 10) + FormatCharacter - '0';\r
            Format += BytesPerFormatCharacter;\r
            FormatCharacter = ((*Format & 0xff) | (*(Format + 1) << 8)) & FormatMask;\r
          }\r
          Format -= BytesPerFormatCharacter;\r
          if ((Flags & PRECISION) == 0) {\r
            Flags |= PAD_TO_WIDTH;\r
            Width = Count;\r
          } else {\r
            Precision = Count;\r
          }\r
          break;\r
\r
        case '\0':\r
          //\r
          // Make no output if Format string terminates unexpectedly when\r
          // looking up for flag, width, precision and type.\r
          //\r
          Format   -= BytesPerFormatCharacter;\r
          Precision = 0;\r
          //\r
          // break skipped on purpose.\r
          //\r
        default:\r
          Done = TRUE;\r
          break;\r
        }\r
      }\r
\r
      //\r
      // Handle each argument type\r
      //\r
      switch (FormatCharacter) {\r
      case 'p':\r
        //\r
        // Flag space, +, 0, L & l are invalid for type p.\r
        //\r
        Flags &= ~(PREFIX_BLANK | PREFIX_SIGN | PREFIX_ZERO | LONG_TYPE);\r
        if (sizeof (VOID *) > 4) {\r
          Flags |= LONG_TYPE;\r
        }\r
      case 'X':\r
        Flags |= PREFIX_ZERO;\r
        //\r
        // break skipped on purpose\r
        //\r
      case 'x':\r
        Flags |= RADIX_HEX;\r
        //\r
        // break skipped on purpose\r
        //\r
      case 'd':\r
        if ((Flags & LONG_TYPE) == 0) {\r
          //\r
          // 'd','x', and 'X' that are not preceded by 'l' or 'L' are assumed to be type "int".\r
          // This assumption is made so the format string definition is compatible with the ANSI C\r
          // Specification for formatted strings.  It is recommended that the Base Types be used\r
          // everywhere, but in this one case, compliance with ANSI C is more important, and\r
          // provides an implementation that is compatible with that largest possible set of CPU\r
          // architectures.  This is why the type "int" is used in this one case.\r
          //\r
          if (BaseListMarker == NULL) {\r
            Value = VA_ARG (VaListMarker, int);\r
          } else {\r
            Value = BASE_ARG (BaseListMarker, int);\r
          }\r
        } else {\r
          if (BaseListMarker == NULL) {\r
            Value = VA_ARG (VaListMarker, INT64);\r
          } else {\r
            Value = BASE_ARG (BaseListMarker, INT64);\r
          }\r
        }\r
        if ((Flags & PREFIX_BLANK) != 0) {\r
          Prefix = ' ';\r
        }\r
        if ((Flags & PREFIX_SIGN) != 0) {\r
          Prefix = '+';\r
        }\r
        if ((Flags & COMMA_TYPE) != 0) {\r
          Comma = TRUE;\r
        }\r
        if ((Flags & RADIX_HEX) == 0) {\r
          Radix = 10;\r
          if (Comma) {\r
            Flags &= (~PREFIX_ZERO);\r
            Precision = 1;\r
          }\r
          if (Value < 0) {\r
            Flags |= PREFIX_SIGN;\r
            Prefix = '-';\r
            Value = -Value;\r
          }\r
        } else {\r
          Radix = 16;\r
          Comma = FALSE;\r
          if ((Flags & LONG_TYPE) == 0 && Value < 0) {\r
            //\r
            // 'd','x', and 'X' that are not preceded by 'l' or 'L' are assumed to be type "int".\r
            // This assumption is made so the format string definition is compatible with the ANSI C\r
            // Specification for formatted strings.  It is recommended that the Base Types be used\r
            // everywhere, but in this one case, compliance with ANSI C is more important, and\r
            // provides an implementation that is compatible with that largest possible set of CPU\r
            // architectures.  This is why the type "unsigned int" is used in this one case.\r
            //\r
            Value = (unsigned int)Value;\r
          }\r
        }\r
        //\r
        // Convert Value to a reversed string\r
        //\r
        Count = BasePrintLibValueToString (ValueBuffer, Value, Radix) - ValueBuffer;\r
        if (Value == 0 && Precision == 0) {\r
          Count = 0;\r
        }\r
        ArgumentString = (CHAR8 *)ValueBuffer + Count;\r
\r
        Digits = Count % 3;\r
        if (Digits != 0) {\r
          Digits = 3 - Digits;\r
        }\r
        if (Comma && Count != 0) {\r
          Count += ((Count - 1) / 3);\r
        }\r
        if (Prefix != 0) {\r
          Count++;\r
          Precision++;\r
        }\r
        Flags |= ARGUMENT_REVERSED;\r
        ZeroPad = TRUE;\r
        if ((Flags & PREFIX_ZERO) != 0) {\r
          if ((Flags & LEFT_JUSTIFY) == 0) {\r
            if ((Flags & PAD_TO_WIDTH) != 0) {\r
              if ((Flags & PRECISION) == 0) {\r
                Precision = Width;\r
              }\r
            }\r
          }\r
        }\r
        break;\r
\r
      case 's':\r
      case 'S':\r
        Flags |= ARGUMENT_UNICODE;\r
        //\r
        // break skipped on purpose\r
        //\r
      case 'a':\r
        if (BaseListMarker == NULL) {\r
          ArgumentString = VA_ARG (VaListMarker, CHAR8 *);\r
        } else {\r
          ArgumentString = BASE_ARG (BaseListMarker, CHAR8 *);\r
        }\r
        if (ArgumentString == NULL) {\r
          Flags &= (~ARGUMENT_UNICODE);\r
          ArgumentString = "<null string>";\r
        }\r
        //\r
        // Set the default precision for string to be zero if not specified.\r
        //\r
        if ((Flags & PRECISION) == 0) {\r
          Precision = 0;\r
        }\r
        break;\r
\r
      case 'c':\r
        if (BaseListMarker == NULL) {\r
          Character = VA_ARG (VaListMarker, UINTN) & 0xffff;\r
        } else {\r
          Character = BASE_ARG (BaseListMarker, UINTN) & 0xffff;\r
        }\r
        ArgumentString = (CHAR8 *)&Character;\r
        Flags |= ARGUMENT_UNICODE;\r
        break;\r
\r
      case 'g':\r
        if (BaseListMarker == NULL) {\r
          TmpGuid = VA_ARG (VaListMarker, EFI_GUID *);\r
        } else {\r
          TmpGuid = BASE_ARG (BaseListMarker, EFI_GUID *);\r
        }\r
        if (TmpGuid == NULL) {\r
          ArgumentString = "<null guid>";\r
        } else {\r
          GuidData1 = ReadUnaligned32 (&(TmpGuid->Data1));\r
          GuidData2 = FceReadUnaligned16 (&(TmpGuid->Data2));\r
          GuidData3 = FceReadUnaligned16 (&(TmpGuid->Data3));\r
          BasePrintLibSPrint (\r
            ValueBuffer,\r
            MAXIMUM_VALUE_CHARACTERS,\r
            0,\r
            "%08x-%04x-%04x-%02x%02x-%02x%02x%02x%02x%02x%02x",\r
            GuidData1,\r
            GuidData2,\r
            GuidData3,\r
            TmpGuid->Data4[0],\r
            TmpGuid->Data4[1],\r
            TmpGuid->Data4[2],\r
            TmpGuid->Data4[3],\r
            TmpGuid->Data4[4],\r
            TmpGuid->Data4[5],\r
            TmpGuid->Data4[6],\r
            TmpGuid->Data4[7]\r
            );\r
          ArgumentString = ValueBuffer;\r
        }\r
        break;\r
\r
      case 't':\r
        if (BaseListMarker == NULL) {\r
          TmpTime = VA_ARG (VaListMarker, TIME *);\r
        } else {\r
          TmpTime = BASE_ARG (BaseListMarker, TIME *);\r
        }\r
        if (TmpTime == NULL) {\r
          ArgumentString = "<null time>";\r
        } else {\r
          BasePrintLibSPrint (\r
            ValueBuffer,\r
            MAXIMUM_VALUE_CHARACTERS,\r
            0,\r
            "%02d/%02d/%04d  %02d:%02d",\r
            TmpTime->Month,\r
            TmpTime->Day,\r
            TmpTime->Year,\r
            TmpTime->Hour,\r
            TmpTime->Minute\r
            );\r
          ArgumentString = ValueBuffer;\r
        }\r
        break;\r
\r
      case 'r':\r
        if (BaseListMarker == NULL) {\r
          Status = VA_ARG (VaListMarker, RETURN_STATUS);\r
        } else {\r
          Status = BASE_ARG (BaseListMarker, RETURN_STATUS);\r
        }\r
        ArgumentString = ValueBuffer;\r
        if (RETURN_ERROR (Status)) {\r
          //\r
          // Clear error bit\r
          //\r
          Index = Status & ~MAX_BIT;\r
          if (Index > 0 && Index <= ERROR_STATUS_NUMBER) {\r
            ArgumentString = mStatusString [Index + WARNING_STATUS_NUMBER];\r
          }\r
        } else {\r
          Index = Status;\r
          if (Index <= WARNING_STATUS_NUMBER) {\r
            ArgumentString = mStatusString [Index];\r
          }\r
        }\r
        if (ArgumentString == ValueBuffer) {\r
          BasePrintLibSPrint ((CHAR8 *) ValueBuffer, MAXIMUM_VALUE_CHARACTERS, 0, "%08X", Status);\r
        }\r
        break;\r
\r
      case '\r':\r
        Format += BytesPerFormatCharacter;\r
        FormatCharacter = ((*Format & 0xff) | (*(Format + 1) << 8)) & FormatMask;\r
        if (FormatCharacter == '\n') {\r
          //\r
          // Translate '\r\n' to '\r\n'\r
          //\r
          ArgumentString = "\r\n";\r
        } else {\r
          //\r
          // Translate '\r' to '\r'\r
          //\r
          ArgumentString = "\r";\r
          Format   -= BytesPerFormatCharacter;\r
        }\r
        break;\r
\r
      case '\n':\r
        //\r
        // Translate '\n' to '\r\n' and '\n\r' to '\r\n'\r
        //\r
        ArgumentString = "\r\n";\r
        Format += BytesPerFormatCharacter;\r
        FormatCharacter = ((*Format & 0xff) | (*(Format + 1) << 8)) & FormatMask;\r
        if (FormatCharacter != '\r') {\r
          Format   -= BytesPerFormatCharacter;\r
        }\r
        break;\r
\r
      case '%':\r
      default:\r
        //\r
        // if the type is '%' or unknown, then print it to the screen\r
        //\r
        ArgumentString = (CHAR8 *)&FormatCharacter;\r
        Flags |= ARGUMENT_UNICODE;\r
        break;\r
      }\r
      break;\r
\r
    case '\r':\r
      Format += BytesPerFormatCharacter;\r
      FormatCharacter = ((*Format & 0xff) | (*(Format + 1) << 8)) & FormatMask;\r
      if (FormatCharacter == '\n') {\r
        //\r
        // Translate '\r\n' to '\r\n'\r
        //\r
        ArgumentString = "\r\n";\r
      } else {\r
        //\r
        // Translate '\r' to '\r'\r
        //\r
        ArgumentString = "\r";\r
        Format   -= BytesPerFormatCharacter;\r
      }\r
      break;\r
\r
    case '\n':\r
      //\r
      // Translate '\n' to '\r\n' and '\n\r' to '\r\n'\r
      //\r
      ArgumentString = "\r\n";\r
      Format += BytesPerFormatCharacter;\r
      FormatCharacter = ((*Format & 0xff) | (*(Format + 1) << 8)) & FormatMask;\r
      if (FormatCharacter != '\r') {\r
        Format   -= BytesPerFormatCharacter;\r
      }\r
      break;\r
\r
    default:\r
      ArgumentString = (CHAR8 *)&FormatCharacter;\r
      Flags |= ARGUMENT_UNICODE;\r
      break;\r
    }\r
\r
    //\r
    // Retrieve the ArgumentString attriubutes\r
    //\r
    if ((Flags & ARGUMENT_UNICODE) != 0) {\r
      ArgumentMask = 0xffff;\r
      BytesPerArgumentCharacter = 2;\r
    } else {\r
      ArgumentMask = 0xff;\r
      BytesPerArgumentCharacter = 1;\r
    }\r
    if ((Flags & ARGUMENT_REVERSED) != 0) {\r
      BytesPerArgumentCharacter = -BytesPerArgumentCharacter;\r
    } else {\r
      //\r
      // Compute the number of characters in ArgumentString and store it in Count\r
      // ArgumentString is either null-terminated, or it contains Precision characters\r
      //\r
      for (Count = 0; Count < Precision || ((Flags & PRECISION) == 0); Count++) {\r
        ArgumentCharacter = ((ArgumentString[Count * BytesPerArgumentCharacter] & 0xff) | ((ArgumentString[Count * BytesPerArgumentCharacter + 1]) << 8)) & ArgumentMask;\r
        if (ArgumentCharacter == 0) {\r
          break;\r
        }\r
      }\r
    }\r
\r
    if (Precision < Count) {\r
      Precision = Count;\r
    }\r
\r
    //\r
    // Pad before the string\r
    //\r
    if ((Flags & (PAD_TO_WIDTH | LEFT_JUSTIFY)) == (PAD_TO_WIDTH)) {\r
      LengthToReturn += ((Width - Precision) * BytesPerOutputCharacter);\r
      if ((Flags & COUNT_ONLY_NO_PRINT) == 0 && Buffer != NULL) {\r
        Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, Width - Precision, ' ', BytesPerOutputCharacter);\r
      }\r
    }\r
\r
    if (ZeroPad) {\r
      if (Prefix != 0) {\r
        LengthToReturn += (1 * BytesPerOutputCharacter);\r
        if ((Flags & COUNT_ONLY_NO_PRINT) == 0 && Buffer != NULL) {\r
          Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, 1, Prefix, BytesPerOutputCharacter);\r
        }\r
      }\r
      LengthToReturn += ((Precision - Count) * BytesPerOutputCharacter);\r
      if ((Flags & COUNT_ONLY_NO_PRINT) == 0 && Buffer != NULL) {\r
        Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, Precision - Count, '0', BytesPerOutputCharacter);\r
      }\r
    } else {\r
      LengthToReturn += ((Precision - Count) * BytesPerOutputCharacter);\r
      if ((Flags & COUNT_ONLY_NO_PRINT) == 0 && Buffer != NULL) {\r
        Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, Precision - Count, ' ', BytesPerOutputCharacter);\r
      }\r
      if (Prefix != 0) {\r
        LengthToReturn += (1 * BytesPerOutputCharacter);\r
        if ((Flags & COUNT_ONLY_NO_PRINT) == 0 && Buffer != NULL) {\r
          Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, 1, Prefix, BytesPerOutputCharacter);\r
        }\r
      }\r
    }\r
\r
    //\r
    // Output the Prefix character if it is present\r
    //\r
    Index = 0;\r
    if (Prefix != 0) {\r
      Index++;\r
    }\r
\r
    //\r
    // Copy the string into the output buffer performing the required type conversions\r
    //\r
    while (Index < Count) {\r
      ArgumentCharacter = ((*ArgumentString & 0xff) | (*(ArgumentString + 1) << 8)) & ArgumentMask;\r
\r
      LengthToReturn += (1 * BytesPerOutputCharacter);\r
      if ((Flags & COUNT_ONLY_NO_PRINT) == 0 && Buffer != NULL) {\r
        Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, 1, ArgumentCharacter, BytesPerOutputCharacter);\r
      }\r
      ArgumentString    += BytesPerArgumentCharacter;\r
      Index++;\r
      if (Comma) {\r
        Digits++;\r
        if (Digits == 3) {\r
          Digits = 0;\r
          Index++;\r
          if (Index < Count) {\r
            LengthToReturn += (1 * BytesPerOutputCharacter);\r
            if ((Flags & COUNT_ONLY_NO_PRINT) == 0 && Buffer != NULL) {\r
              Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, 1, ',', BytesPerOutputCharacter);\r
            }\r
          }\r
        }\r
      }\r
    }\r
\r
    //\r
    // Pad after the string\r
    //\r
    if ((Flags & (PAD_TO_WIDTH | LEFT_JUSTIFY)) == (PAD_TO_WIDTH | LEFT_JUSTIFY)) {\r
      LengthToReturn += ((Width - Precision) * BytesPerOutputCharacter);\r
      if ((Flags & COUNT_ONLY_NO_PRINT) == 0 && Buffer != NULL) {\r
        Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, Width - Precision, ' ', BytesPerOutputCharacter);\r
      }\r
    }\r
\r
    //\r
    // Get the next character from the format string\r
    //\r
    Format += BytesPerFormatCharacter;\r
\r
    //\r
    // Get the next character from the format string\r
    //\r
    FormatCharacter = ((*Format & 0xff) | (*(Format + 1) << 8)) & FormatMask;\r
  }\r
\r
  if ((Flags & COUNT_ONLY_NO_PRINT) != 0) {\r
    return (LengthToReturn / BytesPerOutputCharacter);\r
  }\r
\r
  ASSERT (Buffer != NULL);\r
  //\r
  // Null terminate the Unicode or ASCII string\r
  //\r
  BasePrintLibFillBuffer (Buffer, EndBuffer + BytesPerOutputCharacter, 1, 0, BytesPerOutputCharacter);\r
  //\r
  // Make sure output buffer cannot contain more than PcdMaximumUnicodeStringLength\r
  // Unicode characters if PcdMaximumUnicodeStringLength is not zero.\r
  //\r
  ASSERT ((((Flags & OUTPUT_UNICODE) == 0)) || (FceStrSize ((CHAR16 *) OriginalBuffer) != 0));\r
  //\r
  // Make sure output buffer cannot contain more than PcdMaximumAsciiStringLength\r
  // ASCII characters if PcdMaximumAsciiStringLength is not zero.\r
  //\r
  ASSERT ((((Flags & OUTPUT_UNICODE) != 0)) || ((strlen (OriginalBuffer) + 1) != 0));\r
\r
  return ((Buffer - OriginalBuffer) / BytesPerOutputCharacter);\r
}\r
\r
/**\r
  Worker function that produces a Null-terminated string in an output buffer\r
  based on a Null-terminated format string and variable argument list.\r
\r
  VSPrint function to process format and place the results in Buffer. Since a\r
  VA_LIST is used this routine allows the nesting of Vararg routines. Thus\r
  this is the main print working routine\r
\r
  @param  StartOfBuffer The character buffer to print the results of the parsing\r
                        of Format into.\r
  @param  BufferSize    The maximum number of characters to put into buffer.\r
                        Zero means no limit.\r
  @param  Flags         Initial flags value.\r
                        Can only have FORMAT_UNICODE and OUTPUT_UNICODE set\r
  @param  FormatString  A Null-terminated format string.\r
  @param  ...           The variable argument list.\r
\r
  @return The number of characters printed.\r
\r
**/\r
UINTN\r
BasePrintLibSPrint (\r
  OUT CHAR8        *StartOfBuffer,\r
  IN  UINTN        BufferSize,\r
  IN  UINTN        Flags,\r
  IN  CONST CHAR8  *FormatString,\r
  ...\r
  )\r
{\r
  VA_LIST  Marker;\r
\r
  VA_START (Marker, FormatString);\r
  return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, Flags, FormatString, Marker, NULL);\r
}\r
\r
/**\r
  Produces a Null-terminated Unicode string in an output buffer based on\r
  a Null-terminated Unicode format string and a VA_LIST argument list\r
\r
  Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer\r
  and BufferSize.\r
  The Unicode string is produced by parsing the format string specified by FormatString.\r
  Arguments are pulled from the variable argument list specified by Marker based on the\r
  contents of the format string.\r
  The number of Unicode characters in the produced output buffer is returned not including\r
  the Null-terminator.\r
  If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.\r
\r
  If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().\r
  If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().\r
  If BufferSize > 1 and FormatString is NULL, then ASSERT().\r
  If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().\r
  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than\r
  PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then\r
  ASSERT().\r
  If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string\r
  contains more than PcdMaximumUnicodeStringLength Unicode characters not including the\r
  Null-terminator, then ASSERT().\r
\r
  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated\r
                          Unicode string.\r
  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
  @param  FormatString    A Null-terminated Unicode format string.\r
  @param  Marker          VA_LIST marker for the variable argument list.\r
\r
  @return The number of Unicode characters in the produced output buffer not including the\r
          Null-terminator.\r
\r
**/\r
UINTN\r
UnicodeVSPrint (\r
  OUT CHAR16        *StartOfBuffer,\r
  IN  UINTN         BufferSize,\r
  IN  CONST CHAR16  *FormatString,\r
  IN  VA_LIST       Marker\r
  )\r
{\r
  ASSERT_UNICODE_BUFFER (StartOfBuffer);\r
  ASSERT_UNICODE_BUFFER (FormatString);\r
  return BasePrintLibSPrintMarker ((CHAR8 *)StartOfBuffer, BufferSize >> 1, FORMAT_UNICODE | OUTPUT_UNICODE, (CHAR8 *)FormatString, Marker, NULL);\r
}\r
\r
/**\r
  Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated\r
  Unicode format string and variable argument list.\r
\r
  Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer\r
  and BufferSize.\r
  The Unicode string is produced by parsing the format string specified by FormatString.\r
  Arguments are pulled from the variable argument list based on the contents of the format string.\r
  The number of Unicode characters in the produced output buffer is returned not including\r
  the Null-terminator.\r
  If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.\r
\r
  If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().\r
  If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().\r
  If BufferSize > 1 and FormatString is NULL, then ASSERT().\r
  If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().\r
  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than\r
  PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then\r
  ASSERT().\r
  If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string\r
  contains more than PcdMaximumUnicodeStringLength Unicode characters not including the\r
  Null-terminator, then ASSERT().\r
\r
  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated\r
                          Unicode string.\r
  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
  @param  FormatString    A Null-terminated Unicode format string.\r
  @param  ...             Variable argument list whose contents are accessed based on the\r
                          format string specified by FormatString.\r
\r
  @return The number of Unicode characters in the produced output buffer not including the\r
          Null-terminator.\r
\r
**/\r
UINTN\r
UnicodeSPrint (\r
  OUT CHAR16        *StartOfBuffer,\r
  IN  UINTN         BufferSize,\r
  IN  CONST CHAR16  *FormatString,\r
  ...\r
  )\r
{\r
  VA_LIST Marker;\r
\r
  VA_START (Marker, FormatString);\r
  return UnicodeVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);\r
}\r
\r
/**\r
  Convert a Null-terminated Unicode string to a Null-terminated\r
  ASCII string and returns the ASCII string.\r
\r
  This function converts the content of the Unicode string Source\r
  to the ASCII string Destination by copying the lower 8 bits of\r
  each Unicode character. It returns Destination. The function terminates\r
  the ASCII string Destination  by appending a Null-terminator character\r
  at the end. The caller is responsible to make sure Destination points\r
  to a buffer with size equal or greater than (FceStrLen (Source) + 1) in bytes.\r
\r
  If Destination is NULL, then ASSERT().\r
  If Source is NULL, then ASSERT().\r
  If Source is not aligned on a 16-bit boundary, then ASSERT().\r
  If Source and Destination overlap, then ASSERT().\r
\r
  If any Unicode characters in Source contain non-zero value in\r
  the upper 8 bits, then ASSERT().\r
\r
  @param  Source        Pointer to a Null-terminated Unicode string.\r
  @param  Destination   Pointer to a Null-terminated ASCII string.\r
\r
  @reture Destination\r
\r
**/\r
CHAR8 *\r
UnicodeStrToAsciiStr (\r
  IN      CONST CHAR16             *Source,\r
  OUT           CHAR8              *Destination\r
  )\r
{\r
  CHAR8          *ReturnValue;\r
\r
  ReturnValue = Destination;\r
  assert (Destination != NULL);\r
  assert (Source != NULL);\r
  assert (((UINTN) Source & 0x01) == 0);\r
\r
  while (*Source != L'\0') {\r
    //\r
    // If any Unicode characters in Source contain\r
    // non-zero value in the upper 8 bits, then ASSERT().\r
    //\r
    assert (*Source < 0x100);\r
    *(ReturnValue++) = (CHAR8) *(Source++);\r
  }\r
\r
  *ReturnValue = '\0';\r
\r
  return Destination;\r
}\r
\r
/**\r
  Allocate new memory and then copy the Unicode string Source to Destination.\r
\r
  @param  Dest                   Location to copy string\r
  @param  Src                    String to copy\r
\r
**/\r
VOID\r
NewStringCpy (\r
  IN OUT CHAR16       **Dest,\r
  IN CHAR16           *Src\r
  )\r
{\r
  if (*Dest != NULL) {\r
    FreePool (*Dest);\r
  }\r
  *Dest = FceAllocateCopyPool (FceStrSize (Src), Src);\r
  ASSERT (*Dest != NULL);\r
}\r
\r
/**\r
  Check if a Unicode character is a decimal character.\r
\r
  This internal function checks if a Unicode character is a\r
  decimal character. The valid decimal character is from\r
  L'0' to L'9'.\r
\r
  @param  Char  The character to check against.\r
\r
  @retval TRUE  If the Char is a decmial character.\r
  @retval FALSE If the Char is not a decmial character.\r
\r
**/\r
BOOLEAN\r
FceInternalIsDecimalDigitCharacter (\r
  IN      CHAR16                    Char\r
  )\r
{\r
  return (BOOLEAN) ((Char >= L'0') && (Char <= L'9'));\r
}\r
\r
/**\r
  Convert a Unicode character to upper case only if\r
  it maps to a valid small-case ASCII character.\r
\r
  This internal function only deal with Unicode character\r
  which maps to a valid small-case ASCII character, i.e.\r
  L'a' to L'z'. For other Unicode character, the input character\r
  is returned directly.\r
\r
  @param  Char  The character to convert.\r
\r
  @retval LowerCharacter   If the Char is with range L'a' to L'z'.\r
  @retval Unchanged        Otherwise.\r
\r
**/\r
CHAR16\r
FceInternalCharToUpper (\r
  IN      CHAR16                    Char\r
  )\r
{\r
  if ((Char >= L'a') && (Char <= L'z')) {\r
    return (CHAR16) (Char - (L'a' - L'A'));\r
  }\r
\r
  return Char;\r
}\r
\r
/**\r
  Convert a Unicode character to numerical value.\r
\r
  This internal function only deal with Unicode character\r
  which maps to a valid hexadecimal ASII character, i.e.\r
  L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other\r
  Unicode character, the value returned does not make sense.\r
\r
  @param  Char  The character to convert.\r
\r
  @return The numerical value converted.\r
\r
**/\r
UINTN\r
FceInternalHexCharToUintn (\r
  IN      CHAR16                    Char\r
  )\r
{\r
  if (FceInternalIsDecimalDigitCharacter (Char)) {\r
    return Char - L'0';\r
  }\r
\r
  return (UINTN) (10 + FceInternalCharToUpper (Char) - L'A');\r
}\r
\r
/**\r
  Check if a Unicode character is a hexadecimal character.\r
\r
  This internal function checks if a Unicode character is a\r
  decimal character.  The valid hexadecimal character is\r
  L'0' to L'9', L'a' to L'f', or L'A' to L'F'.\r
\r
\r
  @param  Char  The character to check against.\r
\r
  @retval TRUE  If the Char is a hexadecmial character.\r
  @retval FALSE If the Char is not a hexadecmial character.\r
\r
**/\r
BOOLEAN\r
FceInternalIsHexaDecimalDigitCharacter (\r
  IN      CHAR16                    Char\r
  )\r
{\r
\r
  return (BOOLEAN) (FceInternalIsDecimalDigitCharacter (Char) ||\r
    ((Char >= L'A') && (Char <= L'F')) ||\r
    ((Char >= L'a') && (Char <= L'f')));\r
}\r
\r
\r
/**\r
  Convert a Null-terminated Unicode decimal string to a value of\r
  type UINT64.\r
\r
  This function returns a value of type UINT64 by interpreting the contents\r
  of the Unicode string specified by String as a decimal number. The format\r
  of the input Unicode string String is:\r
\r
                  [spaces] [decimal digits].\r
\r
  The valid decimal digit character is in the range [0-9]. The\r
  function will ignore the pad space, which includes spaces or\r
  tab characters, before [decimal digits]. The running zero in the\r
  beginning of [decimal digits] will be ignored. Then, the function\r
  stops at the first character that is a not a valid decimal character\r
  or a Null-terminator, whichever one comes first.\r
\r
  If String is NULL, then ASSERT().\r
  If String is not aligned in a 16-bit boundary, then ASSERT().\r
  If String has only pad spaces, then 0 is returned.\r
  If String has no pad spaces or valid decimal digits,\r
  then 0 is returned.\r
  If the number represented by String overflows according\r
  to the range defined by UINT64, then ASSERT().\r
\r
  If PcdMaximumUnicodeStringLength is not zero, and String contains\r
  more than PcdMaximumUnicodeStringLength Unicode characters, not including\r
  the Null-terminator, then ASSERT().\r
\r
  @param  String          A pointer to a Null-terminated Unicode string.\r
\r
  @retval Value translated from String.\r
\r
**/\r
UINT64\r
FceStrDecimalToUint64 (\r
  IN      CONST CHAR16              *String\r
  )\r
{\r
  UINT64     Result;\r
\r
  //\r
  // ASSERT String is less long than PcdMaximumUnicodeStringLength.\r
  // Length tests are performed inside FceStrLen().\r
  //\r
  ASSERT (FceStrSize (String) != 0);\r
\r
  //\r
  // Ignore the pad spaces (space or tab)\r
  //\r
  while ((*String == L' ') || (*String == L'\t')) {\r
    String++;\r
  }\r
\r
  //\r
  // Ignore leading Zeros after the spaces\r
  //\r
  while (*String == L'0') {\r
    String++;\r
  }\r
\r
  Result = 0;\r
\r
  while (FceInternalIsDecimalDigitCharacter (*String)) {\r
    //\r
    // If the number represented by String overflows according\r
    // to the range defined by UINTN, then ASSERT().\r
    //\r
    ASSERT (Result <= DivU64x32 (((UINT64) ~0) - (*String - L'0') , 10));\r
\r
    Result = MultU64x32 (Result, 10) + (*String - L'0');\r
    String++;\r
  }\r
\r
  return Result;\r
}\r
\r
\r
/**\r
  Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.\r
\r
  This function returns a value of type UINT64 by interpreting the contents\r
  of the Unicode string specified by String as a hexadecimal number.\r
  The format of the input Unicode string String is\r
\r
                  [spaces][zeros][x][hexadecimal digits].\r
\r
  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].\r
  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.\r
  If "x" appears in the input string, it must be prefixed with at least one 0.\r
  The function will ignore the pad space, which includes spaces or tab characters,\r
  before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or\r
  [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the\r
  first valid hexadecimal digit. Then, the function stops at the first character that is\r
  a not a valid hexadecimal character or NULL, whichever one comes first.\r
\r
  If String is NULL, then ASSERT().\r
  If String is not aligned in a 16-bit boundary, then ASSERT().\r
  If String has only pad spaces, then zero is returned.\r
  If String has no leading pad spaces, leading zeros or valid hexadecimal digits,\r
  then zero is returned.\r
  If the number represented by String overflows according to the range defined by\r
  UINT64, then ASSERT().\r
\r
  If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
  PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,\r
  then ASSERT().\r
\r
  @param  String          A pointer to a Null-terminated Unicode string.\r
\r
  @retval Value translated from String.\r
\r
**/\r
UINT64\r
FceStrHexToUint64 (\r
  IN      CONST CHAR16             *String\r
  )\r
{\r
  UINT64    Result;\r
\r
  //\r
  // ASSERT String is less long than PcdMaximumUnicodeStringLength.\r
  // Length tests are performed inside FceStrLen().\r
  //\r
  ASSERT (FceStrSize (String) != 0);\r
\r
  //\r
  // Ignore the pad spaces (space or tab)\r
  //\r
  while ((*String == L' ') || (*String == L'\t')) {\r
    String++;\r
  }\r
\r
  //\r
  // Ignore leading Zeros after the spaces\r
  //\r
  while (*String == L'0') {\r
    String++;\r
  }\r
\r
  if (FceInternalCharToUpper (*String) == L'X') {\r
    ASSERT (*(String - 1) == L'0');\r
    if (*(String - 1) != L'0') {\r
      return 0;\r
    }\r
    //\r
    // Skip the 'X'\r
    //\r
    String++;\r
  }\r
\r
  Result = 0;\r
\r
  while (FceInternalIsHexaDecimalDigitCharacter (*String)) {\r
    //\r
    // If the Hex Number represented by String overflows according\r
    // to the range defined by UINTN, then ASSERT().\r
    //\r
    ASSERT (Result <= RShiftU64 (((UINT64) ~0) - FceInternalHexCharToUintn (*String) , 4));\r
\r
    Result = LShiftU64 (Result, 4);\r
    Result = Result + FceInternalHexCharToUintn (*String);\r
    String++;\r
  }\r
\r
  return Result;\r
}\r
\r
\r
CHAR16\r
ToUpper (\r
  CHAR16  a\r
  )\r
{\r
  if (('a' <= a) && (a <= 'z')) {\r
    return (CHAR16) (a - 0x20);\r
  } else {\r
    return a;\r
  }\r
}\r
\r
CHAR16\r
ToLower (\r
  CHAR16  a\r
  )\r
{\r
  if (('A' <= a) && (a <= 'Z')) {\r
    return (CHAR16) (a + 0x20);\r
  } else {\r
    return a;\r
  }\r
}\r
\r
/**\r
  Performs a case-insensitive comparison between a Null-terminated\r
  Unicode pattern string and a Null-terminated Unicode string.\r
\r
  @param  String   - A pointer to a Null-terminated Unicode string.\r
  @param  Pattern  - A pointer to a Null-terminated Unicode pattern string.\r
\r
\r
  @retval TRUE     - Pattern was found in String.\r
  @retval FALSE    - Pattern was not found in String.\r
\r
**/\r
BOOLEAN\r
MetaiMatch (\r
  IN CHAR16                           *String,\r
  IN CHAR16                           *Pattern\r
  )\r
{\r
  CHAR16  c;\r
  CHAR16  p;\r
\r
  assert (String != NULL);\r
  assert (Pattern != NULL);\r
\r
  for (;;) {\r
    p     = *Pattern;\r
    Pattern += 1;\r
\r
    if (p == 0) {\r
      //\r
      // End of pattern.  If end of string, TRUE match\r
      //\r
      if (*String) {\r
        return FALSE;\r
      } else {\r
        return TRUE;\r
      }\r
\r
    } else {\r
\r
      c = *String;\r
      if (ToUpper (c) != ToUpper (p)) {\r
        return FALSE;\r
      }\r
\r
      String += 1;\r
\r
    }\r
\r
  }\r
\r
}\r
/**\r
  Multiplies a 64-bit unsigned integer by a 32-bit unsigned integer and\r
  generates a 64-bit unsigned result.\r
\r
  This function multiplies the 64-bit unsigned value Multiplicand by the 32-bit\r
  unsigned value Multiplier and generates a 64-bit unsigned result. This 64-\r
  bit unsigned result is returned.\r
\r
  @param  Multiplicand  A 64-bit unsigned value.\r
  @param  Multiplier    A 32-bit unsigned value.\r
\r
  @return Multiplicand * Multiplier.\r
\r
**/\r
UINT64\r
MultU64x32 (\r
  IN      UINT64                    Multiplicand,\r
  IN      UINT32                    Multiplier\r
  )\r
{\r
  return Multiplicand * Multiplier;\r
}\r
\r
/**\r
  Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates\r
  a 64-bit unsigned result.\r
\r
  This function divides the 64-bit unsigned value Dividend by the 32-bit\r
  unsigned value Divisor and generates a 64-bit unsigned quotient. This\r
  function returns the 64-bit unsigned quotient.\r
\r
  If Divisor is 0, then ASSERT().\r
\r
  @param  Dividend  A 64-bit unsigned value.\r
  @param  Divisor   A 32-bit unsigned value.\r
\r
  @return Dividend / Divisor\r
\r
**/\r
UINT64\r
DivU64x32 (\r
  IN      UINT64                    Dividend,\r
  IN      UINT32                    Divisor\r
  )\r
{\r
  ASSERT (Divisor != 0);\r
  return Dividend / Divisor;\r
}\r
\r
/**\r
  Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled\r
  with zeros. The shifted value is returned.\r
\r
  This function shifts the 64-bit value Operand to the left by Count bits. The\r
  low Count bits are set to zero. The shifted value is returned.\r
\r
  If Count is greater than 63, then ASSERT().\r
\r
  @param  Operand The 64-bit operand to shift left.\r
  @param  Count   The number of bits to shift left.\r
\r
  @return Operand << Count.\r
\r
**/\r
UINT64\r
LShiftU64 (\r
  IN      UINT64                    Operand,\r
  IN      UINTN                     Count\r
  )\r
{\r
  ASSERT (Count < 64);\r
  return Operand << Count;\r
}\r
\r
/**\r
  Shifts a 64-bit integer right between 0 and 63 bits. This high bits are\r
  filled with zeros. The shifted value is returned.\r
\r
  This function shifts the 64-bit value Operand to the right by Count bits. The\r
  high Count bits are set to zero. The shifted value is returned.\r
\r
  If Count is greater than 63, then ASSERT().\r
\r
  @param  Operand The 64-bit operand to shift right.\r
  @param  Count   The number of bits to shift right.\r
\r
  @return Operand >> Count.\r
\r
**/\r
UINT64\r
RShiftU64 (\r
  IN      UINT64                    Operand,\r
  IN      UINTN                     Count\r
  )\r
\r
{\r
  ASSERT (Count < 64);\r
  return Operand >> Count;\r
}\r
\r
\r
/**\r
  Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates\r
  a 64-bit unsigned result and an optional 32-bit unsigned remainder.\r
\r
  This function divides the 64-bit unsigned value Dividend by the 32-bit\r
  unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder\r
  is not NULL, then the 32-bit unsigned remainder is returned in Remainder.\r
  This function returns the 64-bit unsigned quotient.\r
\r
  If Divisor is 0, then ASSERT().\r
\r
  @param  Dividend  A 64-bit unsigned value.\r
  @param  Divisor   A 32-bit unsigned value.\r
  @param  Remainder A pointer to a 32-bit unsigned value. This parameter is\r
                    optional and may be NULL.\r
\r
  @return Dividend / Divisor\r
\r
**/\r
UINT64\r
DivU64x32Remainder (\r
  IN      UINT64                    Dividend,\r
  IN      UINT32                    Divisor,\r
  OUT     UINT32                    *Remainder\r
  )\r
{\r
  ASSERT (Divisor != 0);\r
\r
  if (Remainder != NULL) {\r
    *Remainder = (UINT32)(Dividend % Divisor);\r
  }\r
  return Dividend / Divisor;\r
}\r
\r
/**\r
  Copies a buffer to an allocated buffer.\r
\r
  Allocates the number bytes specified by AllocationSize, copies allocationSize bytes\r
  from Buffer to the newly allocated buffer, and returns a pointer to the allocated\r
  buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there\r
  is not enough memory remaining to satisfy the request, then NULL is returned.\r
\r
  If Buffer is NULL, then ASSERT().\r
\r
  @param  AllocationSize        The number of bytes to allocate and zero.\r
  @param  Buffer                The buffer to copy to the allocated buffer.\r
\r
  @return A pointer to the allocated buffer or NULL if allocation fails.\r
\r
**/\r
VOID *\r
FceAllocateCopyPool (\r
  IN UINTN       AllocationSize,\r
  IN CONST VOID  *Buffer\r
  )\r
{\r
  VOID  *Memory;\r
\r
  Memory = NULL;\r
\r
  if ((Buffer == NULL) || (AllocationSize == 0)) {\r
    return Memory;\r
  }\r
\r
  Memory = calloc (AllocationSize, sizeof (CHAR8));\r
  if (Memory != NULL) {\r
     Memory = memcpy (Memory, Buffer, AllocationSize);\r
  }\r
  return Memory;\r
}\r
\r
/**\r
  Initializes the head node of a doubly-linked list, and returns the pointer to\r
  the head node of the doubly-linked list.\r
\r
  Initializes the forward and backward links of a new linked list. After\r
  initializing a linked list with this function, the other linked list\r
  functions may be used to add and remove nodes from the linked list. It is up\r
  to the caller of this function to allocate the memory for ListHead.\r
\r
  If ListHead is NULL, then ASSERT().\r
\r
  @param  ListHead  A pointer to the head node of a new doubly-linked list.\r
\r
  @return ListHead\r
\r
**/\r
LIST_ENTRY *\r
InitializeListHead (\r
  IN OUT  LIST_ENTRY                *ListHead\r
  )\r
\r
{\r
  assert (ListHead != NULL);\r
\r
  ListHead->ForwardLink = ListHead;\r
  ListHead->BackLink = ListHead;\r
  return ListHead;\r
}\r
\r
/**\r
  Adds a node to the beginning of a doubly-linked list, and returns the pointer\r
  to the head node of the doubly-linked list.\r
\r
  Adds the node Entry at the beginning of the doubly-linked list denoted by\r
  ListHead, and returns ListHead.\r
\r
  If ListHead is NULL, then ASSERT().\r
  If Entry is NULL, then ASSERT().\r
  If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
  InitializeListHead(), then ASSERT().\r
  If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number\r
  of nodes in ListHead, including the ListHead node, is greater than or\r
  equal to PcdMaximumLinkedListLength, then ASSERT().\r
\r
  @param  ListHead  A pointer to the head node of a doubly-linked list.\r
  @param  Entry     A pointer to a node that is to be inserted at the beginning\r
                    of a doubly-linked list.\r
\r
  @return ListHead\r
\r
**/\r
LIST_ENTRY *\r
InsertHeadList (\r
  IN OUT  LIST_ENTRY                *ListHead,\r
  IN OUT  LIST_ENTRY                *Entry\r
  )\r
{\r
  assert ((ListHead != NULL) && (Entry != NULL));\r
\r
  Entry->ForwardLink = ListHead->ForwardLink;\r
  Entry->BackLink = ListHead;\r
  Entry->ForwardLink->BackLink = Entry;\r
  ListHead->ForwardLink = Entry;\r
  return ListHead;\r
}\r
\r
/**\r
  Adds a node to the end of a doubly-linked list, and returns the pointer to\r
  the head node of the doubly-linked list.\r
\r
  Adds the node Entry to the end of the doubly-linked list denoted by ListHead,\r
  and returns ListHead.\r
\r
  If ListHead is NULL, then ASSERT().\r
  If Entry is NULL, then ASSERT().\r
  If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
  InitializeListHead(), then ASSERT().\r
  If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number\r
  of nodes in ListHead, including the ListHead node, is greater than or\r
  equal to PcdMaximumLinkedListLength, then ASSERT().\r
\r
  @param  ListHead  A pointer to the head node of a doubly-linked list.\r
  @param  Entry     A pointer to a node that is to be added at the end of the\r
                    doubly-linked list.\r
\r
  @return ListHead\r
\r
**/\r
LIST_ENTRY *\r
InsertTailList (\r
  IN OUT  LIST_ENTRY                *ListHead,\r
  IN OUT  LIST_ENTRY                *Entry\r
  )\r
{\r
  assert ((ListHead != NULL) && (Entry != NULL));\r
\r
  Entry->ForwardLink = ListHead;\r
  Entry->BackLink = ListHead->BackLink;\r
  Entry->BackLink->ForwardLink = Entry;\r
  ListHead->BackLink = Entry;\r
  return ListHead;\r
}\r
\r
/**\r
  Retrieves the first node of a doubly-linked list.\r
\r
  Returns the first node of a doubly-linked list.  List must have been\r
  initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().\r
  If List is empty, then List is returned.\r
\r
  If List is NULL, then ASSERT().\r
  If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
  InitializeListHead(), then ASSERT().\r
  If PcdMaximumLinkedListLenth is not zero, and the number of nodes\r
  in List, including the List node, is greater than or equal to\r
  PcdMaximumLinkedListLength, then ASSERT().\r
\r
  @param  List  A pointer to the head node of a doubly-linked list.\r
\r
  @return The first node of a doubly-linked list.\r
  @retval NULL  The list is empty.\r
\r
**/\r
LIST_ENTRY *\r
GetFirstNode (\r
  IN      CONST LIST_ENTRY          *List\r
  )\r
{\r
  assert (List != NULL);\r
\r
  return List->ForwardLink;\r
}\r
\r
/**\r
  Retrieves the next node of a doubly-linked list.\r
\r
  Returns the node of a doubly-linked list that follows Node.\r
  List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()\r
  or InitializeListHead().  If List is empty, then List is returned.\r
\r
  If List is NULL, then ASSERT().\r
  If Node is NULL, then ASSERT().\r
  If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
  InitializeListHead(), then ASSERT().\r
  If PcdMaximumLinkedListLenth is not zero, and List contains more than\r
  PcdMaximumLinkedListLenth nodes, then ASSERT().\r
  If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().\r
\r
  @param  List  A pointer to the head node of a doubly-linked list.\r
  @param  Node  A pointer to a node in the doubly-linked list.\r
\r
  @return A pointer to the next node if one exists. Otherwise List is returned.\r
\r
**/\r
LIST_ENTRY *\r
GetNextNode (\r
  IN      CONST LIST_ENTRY          *List,\r
  IN      CONST LIST_ENTRY          *Node\r
  )\r
{\r
  assert ((List != NULL) && (Node != NULL));\r
\r
  return Node->ForwardLink;\r
}\r
\r
/**\r
  Retrieves the previous node of a doubly-linked list.\r
\r
  Returns the node of a doubly-linked list that precedes Node.\r
  List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()\r
  or InitializeListHead().  If List is empty, then List is returned.\r
\r
  If List is NULL, then ASSERT().\r
  If Node is NULL, then ASSERT().\r
  If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
  InitializeListHead(), then ASSERT().\r
  If PcdMaximumLinkedListLenth is not zero, and List contains more than\r
  PcdMaximumLinkedListLenth nodes, then ASSERT().\r
  If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().\r
\r
  @param  List  A pointer to the head node of a doubly-linked list.\r
  @param  Node  A pointer to a node in the doubly-linked list.\r
\r
  @return A pointer to the previous node if one exists. Otherwise List is returned.\r
\r
**/\r
LIST_ENTRY *\r
GetPreviousNode (\r
  IN      CONST LIST_ENTRY          *List,\r
  IN      CONST LIST_ENTRY          *Node\r
  )\r
{\r
  assert ((List != NULL) && (Node != NULL));\r
\r
  return Node->BackLink;\r
}\r
\r
/**\r
  Checks to see if a doubly-linked list is empty or not.\r
\r
  Checks to see if the doubly-linked list is empty. If the linked list contains\r
  zero nodes, this function returns TRUE. Otherwise, it returns FALSE.\r
\r
  If ListHead is NULL, then ASSERT().\r
  If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
  InitializeListHead(), then ASSERT().\r
  If PcdMaximumLinkedListLenth is not zero, and the number of nodes\r
  in List, including the List node, is greater than or equal to\r
  PcdMaximumLinkedListLength, then ASSERT().\r
\r
  @param  ListHead  A pointer to the head node of a doubly-linked list.\r
\r
  @retval TRUE  The linked list is empty.\r
  @retval FALSE The linked list is not empty.\r
\r
**/\r
BOOLEAN\r
IsListEmpty (\r
  IN      CONST LIST_ENTRY          *ListHead\r
  )\r
{\r
  assert (ListHead != NULL);\r
\r
  return (BOOLEAN)(ListHead->ForwardLink == ListHead);\r
}\r
\r
/**\r
  Determines if a node in a doubly-linked list is the head node of a the same\r
  doubly-linked list.  This function is typically used to terminate a loop that\r
  traverses all the nodes in a doubly-linked list starting with the head node.\r
\r
  Returns TRUE if Node is equal to List.  Returns FALSE if Node is one of the\r
  nodes in the doubly-linked list specified by List.  List must have been\r
  initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().\r
\r
  If List is NULL, then ASSERT().\r
  If Node is NULL, then ASSERT().\r
  If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),\r
  then ASSERT().\r
  If PcdMaximumLinkedListLenth is not zero, and the number of nodes\r
  in List, including the List node, is greater than or equal to\r
  PcdMaximumLinkedListLength, then ASSERT().\r
  If PcdVerifyNodeInList is TRUE and Node is not a node in List and Node is not\r
  equal to List, then ASSERT().\r
\r
  @param  List  A pointer to the head node of a doubly-linked list.\r
  @param  Node  A pointer to a node in the doubly-linked list.\r
\r
  @retval TRUE  Node is the head of the doubly-linked list pointed by List.\r
  @retval FALSE Node is not the head of the doubly-linked list pointed by List.\r
\r
**/\r
BOOLEAN\r
IsNull (\r
  IN      CONST LIST_ENTRY          *List,\r
  IN      CONST LIST_ENTRY          *Node\r
  )\r
{\r
  assert ((List != NULL) && (Node != NULL));\r
\r
  return (BOOLEAN)(Node == List);\r
}\r
\r
/**\r
  Determines if a node the last node in a doubly-linked list.\r
\r
  Returns TRUE if Node is the last node in the doubly-linked list specified by\r
  List. Otherwise, FALSE is returned. List must have been initialized with\r
  INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().\r
\r
  If List is NULL, then ASSERT().\r
  If Node is NULL, then ASSERT().\r
  If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
  InitializeListHead(), then ASSERT().\r
  If PcdMaximumLinkedListLenth is not zero, and the number of nodes\r
  in List, including the List node, is greater than or equal to\r
  PcdMaximumLinkedListLength, then ASSERT().\r
  If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().\r
\r
  @param  List  A pointer to the head node of a doubly-linked list.\r
  @param  Node  A pointer to a node in the doubly-linked list.\r
\r
  @retval TRUE  Node is the last node in the linked list.\r
  @retval FALSE Node is not the last node in the linked list.\r
\r
**/\r
BOOLEAN\r
IsNodeAtEnd (\r
  IN      CONST LIST_ENTRY          *List,\r
  IN      CONST LIST_ENTRY          *Node\r
  )\r
{\r
  assert ((List != NULL) && (Node != NULL));\r
\r
  return (BOOLEAN)(!IsNull (List, Node) && (List->BackLink == Node));\r
}\r
\r
/**\r
  Removes a node from a doubly-linked list, and returns the node that follows\r
  the removed node.\r
\r
  Removes the node Entry from a doubly-linked list. It is up to the caller of\r
  this function to release the memory used by this node if that is required. On\r
  exit, the node following Entry in the doubly-linked list is returned. If\r
  Entry is the only node in the linked list, then the head node of the linked\r
  list is returned.\r
\r
  If Entry is NULL, then ASSERT().\r
  If Entry is the head node of an empty list, then ASSERT().\r
  If PcdMaximumLinkedListLength is not zero, and the number of nodes in the\r
  linked list containing Entry, including the Entry node, is greater than\r
  or equal to PcdMaximumLinkedListLength, then ASSERT().\r
\r
  @param  Entry A pointer to a node in a linked list.\r
\r
  @return Entry.\r
\r
**/\r
LIST_ENTRY *\r
RemoveEntryList (\r
  IN      CONST LIST_ENTRY          *Entry\r
  )\r
{\r
  assert (!IsListEmpty (Entry));\r
\r
  Entry->ForwardLink->BackLink = Entry->BackLink;\r
  Entry->BackLink->ForwardLink = Entry->ForwardLink;\r
  return Entry->ForwardLink;\r
}\r
\r