BaseTools/Source/C/FCE/Common.h

   1 /** @file
   2
   3  Common library.
   4
   5  Copyright (c) 2011-2019, Intel Corporation. All rights reserved.<BR>
   6  SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9 #ifndef _COMMON_LIB_H_
  10 #define _COMMON_LIB_H_
  11
  12 #include <stdio.h>
  13 #include <stdlib.h>
  14 #include <string.h>
  15 #ifdef __GNUC__
  16 #include <unistd.h>
  17 #else
  18 #include <io.h>
  19 #include <direct.h>
  20 #endif
  21 #include <ctype.h>
  22 #include <assert.h>
  23 #include <math.h>
  24 #include "CommonLib.h"
  25 #include <Common/UefiBaseTypes.h>
  26
  27 #define MAX_QUI_PARAM_LEN              2000
  28 #define ERROR_INFO_LENGTH              400
  29 #define MAX_STR_LEN_FOR_PICK_UQI       200
  30 #define MAX_PLATFORM_DEFAULT_ID_NUM    1000
  31 #define _MAX_BUILD_VERSION             100
  32 #define _MAXIMUM_SECTION_FILE_NUM      1000
  33
  34 #ifndef _MAX_PATH
  35 #define _MAX_PATH 500
  36 #endif
  37
  38 ///
  39 /// Variable attributes.
  40 ///
  41 #define EFI_VARIABLE_NON_VOLATILE       0x00000001
  42 #define EFI_VARIABLE_BOOTSERVICE_ACCESS 0x00000002
  43 #define EFI_VARIABLE_RUNTIME_ACCESS     0x00000004
  44
  45 ///
  46 /// This attribute is identified by the mnemonic 'HR'
  47 /// elsewhere in this specification.
  48 ///
  49 #define EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS   0x00000010
  50
  51 #define VARSTORE_LIST_TYPE         0x0000000000000001ULL
  52 #define EFI_VARSTORE_LIST_TYPE     0x0000000000000002ULL
  53 #define PLATFORM_DEFAULT_ID_TYPE   0x0000000000000004ULL
  54 #define UQI_LIST_TYPE              0x0000000000000008ULL
  55 #define HII_OBJ_LIST_TYPE          0x0000000000000010ULL
  56
  57 ///
  58 /// LIST_ENTRY structure definition.
  59 ///
  60 typedef struct _LIST_ENTRY {
  61   struct _LIST_ENTRY  *ForwardLink;
  62   struct _LIST_ENTRY  *BackLink;
  63 } LIST_ENTRY;
  64
  65 #define CR(Record, TYPE, Field, TestSignature)  ((TYPE *) ((CHAR8 *) (Record) - (CHAR8 *) &(((TYPE *) 0)->Field)))
  66 #define AllocateZeroPool(a)  calloc(a, sizeof (CHAR8))
  67 #define FreePool(a) free(a)
  68 #define CopyMem(a, b, c)  memcpy(a, b, c)
  69 #define ZeroMem(a, b) memset(a, 0, b)
  70 #define CompareMem(a, b, c)  memcmp(a, b, c)
  71 #define AllocatePool(a)  malloc(a)
  72
  73 /**
  74   Returns a 16-bit signature built from 2 ASCII characters.
  75
  76   This macro returns a 16-bit value built from the two ASCII characters specified
  77   by A and B.
  78
  79   @param  A    The first ASCII character.
  80   @param  B    The second ASCII character.
  81
  82   @return A 16-bit value built from the two ASCII characters specified by A and B.
  83
  84 **/
  85 #define SIGNATURE_16(A, B)        ((A) | (B << 8))
  86
  87 /**
  88   Returns a 32-bit signature built from 4 ASCII characters.
  89
  90   This macro returns a 32-bit value built from the four ASCII characters specified
  91   by A, B, C, and D.
  92
  93   @param  A    The first ASCII character.
  94   @param  B    The second ASCII character.
  95   @param  C    The third ASCII character.
  96   @param  D    The fourth ASCII character.
  97
  98   @return A 32-bit value built from the two ASCII characters specified by A, B,
  99           C and D.
 100
 101 **/
 102 #define SIGNATURE_32(A, B, C, D)  (SIGNATURE_16 (A, B) | (SIGNATURE_16 (C, D) << 16))
 103
 104 #define ASSERT_UNICODE_BUFFER(Buffer) ASSERT ((((UINTN) (Buffer)) & 0x01) == 0)
 105
 106 /**
 107   Returns an argument of a specified type from a variable argument list and updates
 108   the pointer to the variable argument list to point to the next argument.
 109
 110   This function returns an argument of the type specified by TYPE from the beginning
 111   of the variable argument list specified by Marker.  Marker is then updated to point
 112   to the next argument in the variable argument list.  The method for computing the
 113   pointer to the next argument in the argument list is CPU specific following the EFIAPI ABI.
 114
 115   @param   Marker   The pointer to the beginning of a variable argument list.
 116   @param   TYPE     The type of argument to retrieve from the beginning
 117                     of the variable argument list.
 118
 119   @return  An argument of the type specified by TYPE.
 120
 121 **/
 122 #define BASE_ARG(Marker, TYPE)   (*(TYPE *) ((Marker += _BASE_INT_SIZE_OF (TYPE)) - _BASE_INT_SIZE_OF (TYPE)))
 123
 124 ///
 125 /// Define the maximum number of characters that are required to
 126 /// encode with a NULL terminator a decimal, hexadecimal, GUID,
 127 /// or TIME value.
 128 ///
 129 ///  Maximum Length Decimal String     = 28
 130 ///    "-9,223,372,036,854,775,808"
 131 ///  Maximum Length Hexadecimal String = 17
 132 ///    "FFFFFFFFFFFFFFFF"
 133 ///  Maximum Length GUID               = 37
 134 ///    "00000000-0000-0000-0000-000000000000"
 135 ///  Maximum Length TIME               = 18
 136 ///    "12/12/2006  12:12"
 137 ///
 138 #define MAXIMUM_VALUE_CHARACTERS  38
 139
 140 ///
 141 /// Pointer to the start of a variable argument list stored in a memory buffer. Same as UINT8 *.
 142 ///
 143 typedef UINTN  *BASE_LIST;
 144
 145 /**
 146   Returns the size of a data type in sizeof(UINTN) units rounded up to the nearest UINTN boundary.
 147
 148   @param  TYPE  The date type to determine the size of.
 149
 150   @return The size of TYPE in sizeof (UINTN) units rounded up to the nearest UINTN boundary.
 151 **/
 152 #define _BASE_INT_SIZE_OF(TYPE) ((sizeof (TYPE) + sizeof (UINTN) - 1) / sizeof (UINTN))
 153
 154 //
 155 // Print primitives
 156 //
 157 #define PREFIX_SIGN           BIT1
 158 #define PREFIX_BLANK          BIT2
 159 #define LONG_TYPE             BIT4
 160 #define OUTPUT_UNICODE        BIT6
 161 #define FORMAT_UNICODE        BIT8
 162 #define PAD_TO_WIDTH          BIT9
 163 #define ARGUMENT_UNICODE      BIT10
 164 #define PRECISION             BIT11
 165 #define ARGUMENT_REVERSED     BIT12
 166 #define COUNT_ONLY_NO_PRINT   BIT13
 167
 168 ///
 169 /// Flags bitmask values use in UnicodeValueToString() and
 170 /// AsciiValueToString()
 171 ///
 172 #define LEFT_JUSTIFY      0x01
 173 #define COMMA_TYPE        0x08
 174 #define PREFIX_ZERO       0x20
 175 #define RADIX_HEX         0x80
 176
 177 //
 178 // Record date and time information
 179 //
 180 typedef struct {
 181   UINT16  Year;
 182   UINT8   Month;
 183   UINT8   Day;
 184   UINT8   Hour;
 185   UINT8   Minute;
 186   UINT8   Second;
 187   UINT8   Pad1;
 188   UINT32  Nanosecond;
 189   INT16   TimeZone;
 190   UINT8   Daylight;
 191   UINT8   Pad2;
 192 } TIME;
 193
 194
 195 /**
 196   Copies one Null-terminated Unicode string to another Null-terminated Unicode
 197   string and returns the new Unicode string.
 198
 199   This function copies the contents of the Unicode string Source to the Unicode
 200   string Destination, and returns Destination. If Source and Destination
 201   overlap, then the results are undefined.
 202
 203   If Destination is NULL, then return NULL.
 204   If Destination is not aligned on a 16-bit boundary, then return NULL.
 205
 206   @param  Destination A pointer to a Null-terminated Unicode string.
 207   @param  Source      A pointer to a Null-terminated Unicode string.
 208
 209   @return Destination.
 210
 211 **/
 212 CHAR16 *
 213 StrCpy (
 214   OUT     CHAR16                    *Destination,
 215   IN      CONST CHAR16              *Source
 216   );
 217
 218 /**
 219   Returns the length of a Null-terminated Unicode string.
 220
 221   This function returns the number of Unicode characters in the Null-terminated
 222   Unicode string specified by String.
 223
 224   If String is NULL, then return 0.
 225
 226   @param  String  A pointer to a Null-terminated Unicode string.
 227
 228   @return The length of String.
 229
 230 **/
 231 UINTN
 232 FceStrLen (
 233   IN      CONST CHAR16              *String
 234   );
 235
 236 /**
 237   Returns the size of a Null-terminated Unicode string in bytes, including the
 238   Null terminator.
 239
 240   This function returns the size, in bytes, of the Null-terminated Unicode string
 241   specified by String.
 242
 243   If String is NULL, then ASSERT().
 244   If String is not aligned on a 16-bit boundary, then ASSERT().
 245   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
 246   PcdMaximumUnicodeStringLength Unicode characters, not including the
 247   Null-terminator, then ASSERT().
 248
 249   @param  String  A pointer to a Null-terminated Unicode string.
 250
 251   @return The size of String.
 252
 253 **/
 254 UINTN
 255 FceStrSize (
 256   IN      CONST CHAR16              *String
 257   );
 258
 259 /**
 260   Compares two Null-terminated Unicode strings, and returns the difference
 261   between the first mismatched Unicode characters.
 262
 263   This function compares the Null-terminated Unicode string FirstString to the
 264   Null-terminated Unicode string SecondString. If FirstString is identical to
 265   SecondString, then 0 is returned. Otherwise, the value returned is the first
 266   mismatched Unicode character in SecondString subtracted from the first
 267   mismatched Unicode character in FirstString.
 268
 269   @param  FirstString   A pointer to a Null-terminated Unicode string.
 270   @param  SecondString  A pointer to a Null-terminated Unicode string.
 271
 272   @retval 0      FirstString is identical to SecondString.
 273   @return others FirstString is not identical to SecondString.
 274
 275 **/
 276 INTN
 277 FceStrCmp (
 278   IN      CONST CHAR16              *FirstString,
 279   IN      CONST CHAR16              *SecondString
 280   );
 281
 282 /**
 283   Concatenates one Null-terminated Unicode string to another Null-terminated
 284   Unicode string, and returns the concatenated Unicode string.
 285
 286   This function concatenates two Null-terminated Unicode strings. The contents
 287   of Null-terminated Unicode string Source are concatenated to the end of
 288   Null-terminated Unicode string Destination. The Null-terminated concatenated
 289   Unicode String is returned. If Source and Destination overlap, then the
 290   results are undefined.
 291
 292   If Destination is NULL, then ASSERT().
 293   If Destination is not aligned on a 16-bit boundary, then ASSERT().
 294   If Source is NULL, then ASSERT().
 295   If Source is not aligned on a 16-bit boundary, then ASSERT().
 296   If Source and Destination overlap, then ASSERT().
 297   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
 298   than PcdMaximumUnicodeStringLength Unicode characters, not including the
 299   Null-terminator, then ASSERT().
 300   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
 301   PcdMaximumUnicodeStringLength Unicode characters, not including the
 302   Null-terminator, then ASSERT().
 303   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
 304   and Source results in a Unicode string with more than
 305   PcdMaximumUnicodeStringLength Unicode characters, not including the
 306   Null-terminator, then ASSERT().
 307
 308   @param  Destination A pointer to a Null-terminated Unicode string.
 309   @param  Source      A pointer to a Null-terminated Unicode string.
 310
 311   @return Destination.
 312
 313 **/
 314 CHAR16 *
 315 StrCat (
 316   IN OUT  CHAR16                    *Destination,
 317   IN      CONST CHAR16              *Source
 318   );
 319
 320 /**
 321   Returns the first occurrence of a Null-terminated Unicode sub-string
 322   in a Null-terminated Unicode string.
 323
 324   This function scans the contents of the Null-terminated Unicode string
 325   specified by String and returns the first occurrence of SearchString.
 326   If SearchString is not found in String, then NULL is returned.  If
 327   the length of SearchString is zero, then String is
 328   returned.
 329
 330   If String is NULL, then ASSERT().
 331   If String is not aligned on a 16-bit boundary, then ASSERT().
 332   If SearchString is NULL, then ASSERT().
 333   If SearchString is not aligned on a 16-bit boundary, then ASSERT().
 334
 335   If PcdMaximumUnicodeStringLength is not zero, and SearchString
 336   or String contains more than PcdMaximumUnicodeStringLength Unicode
 337   characters, not including the Null-terminator, then ASSERT().
 338
 339   @param  String          A pointer to a Null-terminated Unicode string.
 340   @param  SearchString    A pointer to a Null-terminated Unicode string to search for.
 341
 342   @retval NULL            If the SearchString does not appear in String.
 343   @return others          If there is a match.
 344
 345 **/
 346 CHAR16 *
 347 StrStr (
 348   IN      CONST CHAR16              *String,
 349   IN      CONST CHAR16              *SearchString
 350   );
 351
 352 /**
 353   Convert a Null-terminated Unicode decimal string to a value of
 354   type UINT64.
 355
 356   This function returns a value of type UINT64 by interpreting the contents
 357   of the Unicode string specified by String as a decimal number. The format
 358   of the input Unicode string String is:
 359
 360                   [spaces] [decimal digits].
 361
 362   The valid decimal digit character is in the range [0-9]. The
 363   function will ignore the pad space, which includes spaces or
 364   tab characters, before [decimal digits]. The running zero in the
 365   beginning of [decimal digits] will be ignored. Then, the function
 366   stops at the first character that is a not a valid decimal character
 367   or a Null-terminator, whichever one comes first.
 368
 369   If String is NULL, then ASSERT().
 370   If String is not aligned in a 16-bit boundary, then ASSERT().
 371   If String has only pad spaces, then 0 is returned.
 372   If String has no pad spaces or valid decimal digits,
 373   then 0 is returned.
 374   If the number represented by String overflows according
 375   to the range defined by UINT64, then ASSERT().
 376
 377   If PcdMaximumUnicodeStringLength is not zero, and String contains
 378   more than PcdMaximumUnicodeStringLength Unicode characters, not including
 379   the Null-terminator, then ASSERT().
 380
 381   @param  String          A pointer to a Null-terminated Unicode string.
 382
 383   @retval Value translated from String.
 384
 385 **/
 386 UINT64
 387 FceStrDecimalToUint64 (
 388   IN      CONST CHAR16              *String
 389   );
 390
 391
 392 /**
 393   Convert one Null-terminated ASCII string to a Null-terminated
 394   Unicode string and returns the Unicode string.
 395
 396   This function converts the contents of the ASCII string Source to the Unicode
 397   string Destination, and returns Destination.  The function terminates the
 398   Unicode string Destination by appending a Null-terminator character at the end.
 399   The caller is responsible to make sure Destination points to a buffer with size
 400   equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
 401
 402   @param  Source        A pointer to a Null-terminated ASCII string.
 403   @param  Destination   A pointer to a Null-terminated Unicode string.
 404
 405   @return Destination.
 406   @return NULL          If Destination or Source is NULL, return NULL.
 407
 408 **/
 409 CHAR16 *
 410 AsciiStrToUnicodeStr (
 411   IN      CONST CHAR8               *Source,
 412   OUT     CHAR16                    *Destination
 413   );
 414
 415 /**
 416   Worker function that produces a Null-terminated string in an output buffer
 417   based on a Null-terminated format string and variable argument list.
 418
 419   VSPrint function to process format and place the results in Buffer. Since a
 420   VA_LIST is used this routine allows the nesting of Vararg routines. Thus
 421   this is the main print working routine
 422
 423   @param  StartOfBuffer The character buffer to print the results of the parsing
 424                         of Format into.
 425   @param  BufferSize    The maximum number of characters to put into buffer.
 426                         Zero means no limit.
 427   @param  Flags         Initial flags value.
 428                         Can only have FORMAT_UNICODE and OUTPUT_UNICODE set
 429   @param  FormatString  A Null-terminated format string.
 430   @param  ...           The variable argument list.
 431
 432   @return The number of characters printed.
 433
 434 **/
 435 UINTN
 436 BasePrintLibSPrint (
 437   OUT CHAR8        *StartOfBuffer,
 438   IN  UINTN        BufferSize,
 439   IN  UINTN        Flags,
 440   IN  CONST CHAR8  *FormatString,
 441   ...
 442   );
 443
 444 /**
 445   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 446   Unicode format string and variable argument list.
 447
 448   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 449   and BufferSize.
 450   The Unicode string is produced by parsing the format string specified by FormatString.
 451   Arguments are pulled from the variable argument list based on the contents of the format string.
 452   The number of Unicode characters in the produced output buffer is returned not including
 453   the Null-terminator.
 454   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 455
 456   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 457   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 458   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 459   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 460   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 461   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 462   ASSERT().
 463   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 464   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 465   Null-terminator, then ASSERT().
 466
 467   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 468                           Unicode string.
 469   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 470   @param  FormatString    A Null-terminated Unicode format string.
 471   @param  ...             Variable argument list whose contents are accessed based on the
 472                           format string specified by FormatString.
 473
 474   @return The number of Unicode characters in the produced output buffer not including the
 475           Null-terminator.
 476
 477 **/
 478 UINTN
 479 UnicodeSPrint (
 480   OUT CHAR16        *StartOfBuffer,
 481   IN  UINTN         BufferSize,
 482   IN  CONST CHAR16  *FormatString,
 483   ...
 484   );
 485
 486 /**
 487   Convert a Null-terminated Unicode string to a Null-terminated
 488   ASCII string and returns the ASCII string.
 489
 490   This function converts the content of the Unicode string Source
 491   to the ASCII string Destination by copying the lower 8 bits of
 492   each Unicode character. It returns Destination. The function terminates
 493   the ASCII string Destination  by appending a Null-terminator character
 494   at the end. The caller is responsible to make sure Destination points
 495   to a buffer with size equal or greater than (FceStrLen (Source) + 1) in bytes.
 496
 497   If Destination is NULL, then ASSERT().
 498   If Source is NULL, then ASSERT().
 499   If Source is not aligned on a 16-bit boundary, then ASSERT().
 500   If Source and Destination overlap, then ASSERT().
 501
 502   If any Unicode characters in Source contain non-zero value in
 503   the upper 8 bits, then ASSERT().
 504
 505   @param  Source        Pointer to a Null-terminated Unicode string.
 506   @param  Destination   Pointer to a Null-terminated ASCII string.
 507
 508   @reture Destination
 509
 510 **/
 511 CHAR8 *
 512 UnicodeStrToAsciiStr (
 513   IN      CONST CHAR16             *Source,
 514   OUT           CHAR8              *Destination
 515   );
 516
 517 /**
 518   Allocate new memory and then copy the Unicode string Source to Destination.
 519
 520   @param  Dest                   Location to copy string
 521   @param  Src                    String to copy
 522
 523 **/
 524 VOID
 525 NewStringCpy (
 526   IN OUT CHAR16       **Dest,
 527   IN CHAR16           *Src
 528   );
 529
 530 /**
 531   Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
 532
 533   This function returns a value of type UINT64 by interpreting the contents
 534   of the Unicode string specified by String as a hexadecimal number.
 535   The format of the input Unicode string String is
 536
 537                   [spaces][zeros][x][hexadecimal digits].
 538
 539   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
 540   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
 541   If "x" appears in the input string, it must be prefixed with at least one 0.
 542   The function will ignore the pad space, which includes spaces or tab characters,
 543   before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
 544   [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
 545   first valid hexadecimal digit. Then, the function stops at the first character that is
 546   a not a valid hexadecimal character or NULL, whichever one comes first.
 547
 548   If String is NULL, then ASSERT().
 549   If String is not aligned in a 16-bit boundary, then ASSERT().
 550   If String has only pad spaces, then zero is returned.
 551   If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
 552   then zero is returned.
 553   If the number represented by String overflows according to the range defined by
 554   UINT64, then ASSERT().
 555
 556   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
 557   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
 558   then ASSERT().
 559
 560   @param  String          A pointer to a Null-terminated Unicode string.
 561
 562   @retval Value translated from String.
 563
 564 **/
 565 UINT64
 566 FceStrHexToUint64 (
 567   IN      CONST CHAR16             *String
 568   );
 569
 570
 571 CHAR16
 572 ToUpper (
 573   CHAR16  a
 574   );
 575
 576 CHAR16
 577 ToLower (
 578   CHAR16  a
 579   );
 580
 581 /**
 582   Performs a case-insensitive comparison between a Null-terminated
 583   Unicode pattern string and a Null-terminated Unicode string.
 584
 585   @param  String   - A pointer to a Null-terminated Unicode string.
 586   @param  Pattern  - A pointer to a Null-terminated Unicode pattern string.
 587
 588
 589   @retval TRUE     - Pattern was found in String.
 590   @retval FALSE    - Pattern was not found in String.
 591
 592 **/
 593 BOOLEAN
 594 MetaiMatch (
 595   IN CHAR16                           *String,
 596   IN CHAR16                           *Pattern
 597   );
 598
 599 /**
 600   Multiplies a 64-bit unsigned integer by a 32-bit unsigned integer and
 601   generates a 64-bit unsigned result.
 602
 603   This function multiplies the 64-bit unsigned value Multiplicand by the 32-bit
 604   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
 605   bit unsigned result is returned.
 606
 607   @param  Multiplicand  A 64-bit unsigned value.
 608   @param  Multiplier    A 32-bit unsigned value.
 609
 610   @return Multiplicand * Multiplier.
 611
 612 **/
 613 UINT64
 614 MultU64x32 (
 615   IN      UINT64                    Multiplicand,
 616   IN      UINT32                    Multiplier
 617   );
 618
 619 /**
 620   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
 621   a 64-bit unsigned result.
 622
 623   This function divides the 64-bit unsigned value Dividend by the 32-bit
 624   unsigned value Divisor and generates a 64-bit unsigned quotient. This
 625   function returns the 64-bit unsigned quotient.
 626
 627   If Divisor is 0, then ASSERT().
 628
 629   @param  Dividend  A 64-bit unsigned value.
 630   @param  Divisor   A 32-bit unsigned value.
 631
 632   @return Dividend / Divisor
 633
 634 **/
 635 UINT64
 636 DivU64x32 (
 637   IN      UINT64                    Dividend,
 638   IN      UINT32                    Divisor
 639   );
 640
 641 /**
 642   Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
 643   with zeros. The shifted value is returned.
 644
 645   This function shifts the 64-bit value Operand to the left by Count bits. The
 646   low Count bits are set to zero. The shifted value is returned.
 647
 648   If Count is greater than 63, then ASSERT().
 649
 650   @param  Operand The 64-bit operand to shift left.
 651   @param  Count   The number of bits to shift left.
 652
 653   @return Operand << Count.
 654
 655 **/
 656 UINT64
 657 LShiftU64 (
 658   IN      UINT64                    Operand,
 659   IN      UINTN                     Count
 660   );
 661
 662 /**
 663   Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
 664   filled with zeros. The shifted value is returned.
 665
 666   This function shifts the 64-bit value Operand to the right by Count bits. The
 667   high Count bits are set to zero. The shifted value is returned.
 668
 669   If Count is greater than 63, then ASSERT().
 670
 671   @param  Operand The 64-bit operand to shift right.
 672   @param  Count   The number of bits to shift right.
 673
 674   @return Operand >> Count.
 675
 676 **/
 677 UINT64
 678 RShiftU64 (
 679   IN      UINT64                    Operand,
 680   IN      UINTN                     Count
 681   );
 682
 683
 684 /**
 685   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
 686   a 64-bit unsigned result and an optional 32-bit unsigned remainder.
 687
 688   This function divides the 64-bit unsigned value Dividend by the 32-bit
 689   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
 690   is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
 691   This function returns the 64-bit unsigned quotient.
 692
 693   If Divisor is 0, then ASSERT().
 694
 695   @param  Dividend  A 64-bit unsigned value.
 696   @param  Divisor   A 32-bit unsigned value.
 697   @param  Remainder A pointer to a 32-bit unsigned value. This parameter is
 698                     optional and may be NULL.
 699
 700   @return Dividend / Divisor
 701
 702 **/
 703 UINT64
 704 DivU64x32Remainder (
 705   IN      UINT64                    Dividend,
 706   IN      UINT32                    Divisor,
 707   OUT     UINT32                    *Remainder
 708   );
 709
 710 /**
 711   Copies a buffer to an allocated buffer.
 712
 713   Allocates the number bytes specified by AllocationSize, copies allocationSize bytes
 714   from Buffer to the newly allocated buffer, and returns a pointer to the allocated
 715   buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 716   is not enough memory remaining to satisfy the request, then NULL is returned.
 717
 718   If Buffer is NULL, then ASSERT().
 719
 720   @param  AllocationSize        The number of bytes to allocate and zero.
 721   @param  Buffer                The buffer to copy to the allocated buffer.
 722
 723   @return A pointer to the allocated buffer or NULL if allocation fails.
 724
 725 **/
 726 VOID *
 727 FceAllocateCopyPool (
 728   IN UINTN       AllocationSize,
 729   IN CONST VOID  *Buffer
 730   );
 731
 732 /**
 733   Initializes the head node of a doubly-linked list, and returns the pointer to
 734   the head node of the doubly-linked list.
 735
 736   Initializes the forward and backward links of a new linked list. After
 737   initializing a linked list with this function, the other linked list
 738   functions may be used to add and remove nodes from the linked list. It is up
 739   to the caller of this function to allocate the memory for ListHead.
 740
 741   If ListHead is NULL, then ASSERT().
 742
 743   @param  ListHead  A pointer to the head node of a new doubly-linked list.
 744
 745   @return ListHead
 746
 747 **/
 748 LIST_ENTRY *
 749 InitializeListHead (
 750   IN OUT  LIST_ENTRY                *ListHead
 751   );
 752
 753 /**
 754   Adds a node to the beginning of a doubly-linked list, and returns the pointer
 755   to the head node of the doubly-linked list.
 756
 757   Adds the node Entry at the beginning of the doubly-linked list denoted by
 758   ListHead, and returns ListHead.
 759
 760   If ListHead is NULL, then ASSERT().
 761   If Entry is NULL, then ASSERT().
 762   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
 763   InitializeListHead(), then ASSERT().
 764   If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number
 765   of nodes in ListHead, including the ListHead node, is greater than or
 766   equal to PcdMaximumLinkedListLength, then ASSERT().
 767
 768   @param  ListHead  A pointer to the head node of a doubly-linked list.
 769   @param  Entry     A pointer to a node that is to be inserted at the beginning
 770                     of a doubly-linked list.
 771
 772   @return ListHead
 773
 774 **/
 775 LIST_ENTRY *
 776 InsertHeadList (
 777   IN OUT  LIST_ENTRY                *ListHead,
 778   IN OUT  LIST_ENTRY                *Entry
 779   );
 780
 781 /**
 782   Adds a node to the end of a doubly-linked list, and returns the pointer to
 783   the head node of the doubly-linked list.
 784
 785   Adds the node Entry to the end of the doubly-linked list denoted by ListHead,
 786   and returns ListHead.
 787
 788   If ListHead is NULL, then ASSERT().
 789   If Entry is NULL, then ASSERT().
 790   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
 791   InitializeListHead(), then ASSERT().
 792   If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number
 793   of nodes in ListHead, including the ListHead node, is greater than or
 794   equal to PcdMaximumLinkedListLength, then ASSERT().
 795
 796   @param  ListHead  A pointer to the head node of a doubly-linked list.
 797   @param  Entry     A pointer to a node that is to be added at the end of the
 798                     doubly-linked list.
 799
 800   @return ListHead
 801
 802 **/
 803 LIST_ENTRY *
 804 InsertTailList (
 805   IN OUT  LIST_ENTRY                *ListHead,
 806   IN OUT  LIST_ENTRY                *Entry
 807   );
 808
 809 /**
 810   Retrieves the first node of a doubly-linked list.
 811
 812   Returns the first node of a doubly-linked list.  List must have been
 813   initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
 814   If List is empty, then List is returned.
 815
 816   If List is NULL, then ASSERT().
 817   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
 818   InitializeListHead(), then ASSERT().
 819   If PcdMaximumLinkedListLenth is not zero, and the number of nodes
 820   in List, including the List node, is greater than or equal to
 821   PcdMaximumLinkedListLength, then ASSERT().
 822
 823   @param  List  A pointer to the head node of a doubly-linked list.
 824
 825   @return The first node of a doubly-linked list.
 826   @retval NULL  The list is empty.
 827
 828 **/
 829 LIST_ENTRY *
 830 GetFirstNode (
 831   IN      CONST LIST_ENTRY          *List
 832   );
 833
 834 /**
 835   Retrieves the next node of a doubly-linked list.
 836
 837   Returns the node of a doubly-linked list that follows Node.
 838   List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
 839   or InitializeListHead().  If List is empty, then List is returned.
 840
 841   If List is NULL, then ASSERT().
 842   If Node is NULL, then ASSERT().
 843   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
 844   InitializeListHead(), then ASSERT().
 845   If PcdMaximumLinkedListLenth is not zero, and List contains more than
 846   PcdMaximumLinkedListLenth nodes, then ASSERT().
 847   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
 848
 849   @param  List  A pointer to the head node of a doubly-linked list.
 850   @param  Node  A pointer to a node in the doubly-linked list.
 851
 852   @return A pointer to the next node if one exists. Otherwise List is returned.
 853
 854 **/
 855 LIST_ENTRY *
 856 GetNextNode (
 857   IN      CONST LIST_ENTRY          *List,
 858   IN      CONST LIST_ENTRY          *Node
 859   );
 860
 861 /**
 862   Retrieves the previous node of a doubly-linked list.
 863
 864   Returns the node of a doubly-linked list that precedes Node.
 865   List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
 866   or InitializeListHead().  If List is empty, then List is returned.
 867
 868   If List is NULL, then ASSERT().
 869   If Node is NULL, then ASSERT().
 870   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
 871   InitializeListHead(), then ASSERT().
 872   If PcdMaximumLinkedListLenth is not zero, and List contains more than
 873   PcdMaximumLinkedListLenth nodes, then ASSERT().
 874   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
 875
 876   @param  List  A pointer to the head node of a doubly-linked list.
 877   @param  Node  A pointer to a node in the doubly-linked list.
 878
 879   @return A pointer to the previous node if one exists. Otherwise List is returned.
 880
 881 **/
 882 LIST_ENTRY *
 883 GetPreviousNode (
 884   IN      CONST LIST_ENTRY          *List,
 885   IN      CONST LIST_ENTRY          *Node
 886   );
 887
 888 /**
 889   Checks to see if a doubly-linked list is empty or not.
 890
 891   Checks to see if the doubly-linked list is empty. If the linked list contains
 892   zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
 893
 894   If ListHead is NULL, then ASSERT().
 895   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
 896   InitializeListHead(), then ASSERT().
 897   If PcdMaximumLinkedListLenth is not zero, and the number of nodes
 898   in List, including the List node, is greater than or equal to
 899   PcdMaximumLinkedListLength, then ASSERT().
 900
 901   @param  ListHead  A pointer to the head node of a doubly-linked list.
 902
 903   @retval TRUE  The linked list is empty.
 904   @retval FALSE The linked list is not empty.
 905
 906 **/
 907 BOOLEAN
 908 IsListEmpty (
 909   IN      CONST LIST_ENTRY          *ListHead
 910   );
 911
 912 /**
 913   Determines if a node in a doubly-linked list is the head node of a the same
 914   doubly-linked list.  This function is typically used to terminate a loop that
 915   traverses all the nodes in a doubly-linked list starting with the head node.
 916
 917   Returns TRUE if Node is equal to List.  Returns FALSE if Node is one of the
 918   nodes in the doubly-linked list specified by List.  List must have been
 919   initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
 920
 921   If List is NULL, then ASSERT().
 922   If Node is NULL, then ASSERT().
 923   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
 924   then ASSERT().
 925   If PcdMaximumLinkedListLenth is not zero, and the number of nodes
 926   in List, including the List node, is greater than or equal to
 927   PcdMaximumLinkedListLength, then ASSERT().
 928   If PcdVerifyNodeInList is TRUE and Node is not a node in List and Node is not
 929   equal to List, then ASSERT().
 930
 931   @param  List  A pointer to the head node of a doubly-linked list.
 932   @param  Node  A pointer to a node in the doubly-linked list.
 933
 934   @retval TRUE  Node is the head of the doubly-linked list pointed by List.
 935   @retval FALSE Node is not the head of the doubly-linked list pointed by List.
 936
 937 **/
 938 BOOLEAN
 939 IsNull (
 940   IN      CONST LIST_ENTRY          *List,
 941   IN      CONST LIST_ENTRY          *Node
 942   );
 943
 944 /**
 945   Determines if a node the last node in a doubly-linked list.
 946
 947   Returns TRUE if Node is the last node in the doubly-linked list specified by
 948   List. Otherwise, FALSE is returned. List must have been initialized with
 949   INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
 950
 951   If List is NULL, then ASSERT().
 952   If Node is NULL, then ASSERT().
 953   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
 954   InitializeListHead(), then ASSERT().
 955   If PcdMaximumLinkedListLenth is not zero, and the number of nodes
 956   in List, including the List node, is greater than or equal to
 957   PcdMaximumLinkedListLength, then ASSERT().
 958   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
 959
 960   @param  List  A pointer to the head node of a doubly-linked list.
 961   @param  Node  A pointer to a node in the doubly-linked list.
 962
 963   @retval TRUE  Node is the last node in the linked list.
 964   @retval FALSE Node is not the last node in the linked list.
 965
 966 **/
 967 BOOLEAN
 968 IsNodeAtEnd (
 969   IN      CONST LIST_ENTRY          *List,
 970   IN      CONST LIST_ENTRY          *Node
 971   );
 972
 973 /**
 974   Removes a node from a doubly-linked list, and returns the node that follows
 975   the removed node.
 976
 977   Removes the node Entry from a doubly-linked list. It is up to the caller of
 978   this function to release the memory used by this node if that is required. On
 979   exit, the node following Entry in the doubly-linked list is returned. If
 980   Entry is the only node in the linked list, then the head node of the linked
 981   list is returned.
 982
 983   If Entry is NULL, then ASSERT().
 984   If Entry is the head node of an empty list, then ASSERT().
 985   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
 986   linked list containing Entry, including the Entry node, is greater than
 987   or equal to PcdMaximumLinkedListLength, then ASSERT().
 988
 989   @param  Entry A pointer to a node in a linked list.
 990
 991   @return Entry.
 992
 993 **/
 994 LIST_ENTRY *
 995 RemoveEntryList (
 996   IN      CONST LIST_ENTRY          *Entry
 997   );
 998
 999 #endif