VirtualBox

Ignore:
Timestamp:
Mar 12, 2019 12:40:12 PM (6 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
129295
Message:

EFI: First step in UDK2018 merge. Does not build yet.

Location:
trunk/src/VBox/Devices/EFI/FirmwareNew
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Devices/EFI/FirmwareNew

  • trunk/src/VBox/Devices/EFI/FirmwareNew/MdePkg/Include/Library/BaseLib.h

    r58466 r77662  
    11/** @file
    22  Provides string functions, linked list functions, math functions, synchronization
    3   functions, and CPU architecture-specific functions.
    4 
    5 Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR>
     3  functions, file path functions, and CPU architecture-specific functions.
     4
     5Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
    66Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
    77This program and the accompanying materials
    … …  
    188188  Returns the length of a Null-terminated Unicode string.
    189189
     190  This function is similar as strlen_s defined in C11.
     191
    190192  If String is not aligned on a 16-bit boundary, then ASSERT().
    191193
    … …  
    207209
    208210/**
     211  Returns the size of a Null-terminated Unicode string in bytes, including the
     212  Null terminator.
     213
     214  This function returns the size of the Null-terminated Unicode string
     215  specified by String in bytes, including the Null terminator.
     216
     217  If String is not aligned on a 16-bit boundary, then ASSERT().
     218
     219  @param  String   A pointer to a Null-terminated Unicode string.
     220  @param  MaxSize  The maximum number of Destination Unicode
     221                   char, including the Null terminator.
     222
     223  @retval 0  If String is NULL.
     224  @retval (sizeof (CHAR16) * (MaxSize + 1))
     225             If there is no Null terminator in the first MaxSize characters of
     226             String.
     227  @return The size of the Null-terminated Unicode string in bytes, including
     228          the Null terminator.
     229
     230**/
     231UINTN
     232EFIAPI
     233StrnSizeS (
     234  IN CONST CHAR16              *String,
     235  IN UINTN                     MaxSize
     236  );
     237
     238/**
    209239  Copies the string pointed to by Source (including the terminating null char)
    210240  to the array pointed to by Destination.
    211241
     242  This function is similar as strcpy_s defined in C11.
     243
    212244  If Destination is not aligned on a 16-bit boundary, then ASSERT().
    213245  If Source is not aligned on a 16-bit boundary, then ASSERT().
     246  If an error would be returned, then the function will also ASSERT().
     247
     248  If an error is returned, then the Destination is unmodified.
    214249
    215250  @param  Destination              A pointer to a Null-terminated Unicode string.
    … …  
    241276  Source, then Destination[Length] is always set to null.
    242277
     278  This function is similar as strncpy_s defined in C11.
     279
    243280  If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
    244281  If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
     282  If an error would be returned, then the function will also ASSERT().
     283
     284  If an error is returned, then the Destination is unmodified.
    245285
    246286  @param  Destination              A pointer to a Null-terminated Unicode string.
    … …  
    274314  null char) to the end of the string pointed to by Destination.
    275315
     316  This function is similar as strcat_s defined in C11.
     317
    276318  If Destination is not aligned on a 16-bit boundary, then ASSERT().
    277319  If Source is not aligned on a 16-bit boundary, then ASSERT().
     320  If an error would be returned, then the function will also ASSERT().
     321
     322  If an error is returned, then the Destination is unmodified.
    278323
    279324  @param  Destination              A pointer to a Null-terminated Unicode string.
    … …  
    309354  set to null.
    310355
     356  This function is similar as strncat_s defined in C11.
     357
    311358  If Destination is not aligned on a 16-bit boundary, then ASSERT().
    312   If and Source is not aligned on a 16-bit boundary, then ASSERT().
     359  If Source is not aligned on a 16-bit boundary, then ASSERT().
     360  If an error would be returned, then the function will also ASSERT().
     361
     362  If an error is returned, then the Destination is unmodified.
    313363
    314364  @param  Destination              A pointer to a Null-terminated Unicode string.
    … …  
    341391
    342392/**
     393  Convert a Null-terminated Unicode decimal string to a value of type UINTN.
     394
     395  This function outputs a value of type UINTN by interpreting the contents of
     396  the Unicode string specified by String as a decimal number. The format of the
     397  input Unicode string String is:
     398
     399                  [spaces] [decimal digits].
     400
     401  The valid decimal digit character is in the range [0-9]. The function will
     402  ignore the pad space, which includes spaces or tab characters, before
     403  [decimal digits]. The running zero in the beginning of [decimal digits] will
     404  be ignored. Then, the function stops at the first character that is a not a
     405  valid decimal character or a Null-terminator, whichever one comes first.
     406
     407  If String is NULL, then ASSERT().
     408  If Data is NULL, then ASSERT().
     409  If String is not aligned in a 16-bit boundary, then ASSERT().
     410  If PcdMaximumUnicodeStringLength is not zero, and String contains more than
     411  PcdMaximumUnicodeStringLength Unicode characters, not including the
     412  Null-terminator, then ASSERT().
     413
     414  If String has no valid decimal digits in the above format, then 0 is stored
     415  at the location pointed to by Data.
     416  If the number represented by String exceeds the range defined by UINTN, then
     417  MAX_UINTN is stored at the location pointed to by Data.
     418
     419  If EndPointer is not NULL, a pointer to the character that stopped the scan
     420  is stored at the location pointed to by EndPointer. If String has no valid
     421  decimal digits right after the optional pad spaces, the value of String is
     422  stored at the location pointed to by EndPointer.
     423
     424  @param  String                   Pointer to a Null-terminated Unicode string.
     425  @param  EndPointer               Pointer to character that stops scan.
     426  @param  Data                     Pointer to the converted value.
     427
     428  @retval RETURN_SUCCESS           Value is translated from String.
     429  @retval RETURN_INVALID_PARAMETER If String is NULL.
     430                                   If Data is NULL.
     431                                   If PcdMaximumUnicodeStringLength is not
     432                                   zero, and String contains more than
     433                                   PcdMaximumUnicodeStringLength Unicode
     434                                   characters, not including the
     435                                   Null-terminator.
     436  @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
     437                                   the range defined by UINTN.
     438
     439**/
     440RETURN_STATUS
     441EFIAPI
     442StrDecimalToUintnS (
     443  IN  CONST CHAR16             *String,
     444  OUT       CHAR16             **EndPointer,  OPTIONAL
     445  OUT       UINTN              *Data
     446  );
     447
     448/**
     449  Convert a Null-terminated Unicode decimal string to a value of type UINT64.
     450
     451  This function outputs a value of type UINT64 by interpreting the contents of
     452  the Unicode string specified by String as a decimal number. The format of the
     453  input Unicode string String is:
     454
     455                  [spaces] [decimal digits].
     456
     457  The valid decimal digit character is in the range [0-9]. The function will
     458  ignore the pad space, which includes spaces or tab characters, before
     459  [decimal digits]. The running zero in the beginning of [decimal digits] will
     460  be ignored. Then, the function stops at the first character that is a not a
     461  valid decimal character or a Null-terminator, whichever one comes first.
     462
     463  If String is NULL, then ASSERT().
     464  If Data is NULL, then ASSERT().
     465  If String is not aligned in a 16-bit boundary, then ASSERT().
     466  If PcdMaximumUnicodeStringLength is not zero, and String contains more than
     467  PcdMaximumUnicodeStringLength Unicode characters, not including the
     468  Null-terminator, then ASSERT().
     469
     470  If String has no valid decimal digits in the above format, then 0 is stored
     471  at the location pointed to by Data.
     472  If the number represented by String exceeds the range defined by UINT64, then
     473  MAX_UINT64 is stored at the location pointed to by Data.
     474
     475  If EndPointer is not NULL, a pointer to the character that stopped the scan
     476  is stored at the location pointed to by EndPointer. If String has no valid
     477  decimal digits right after the optional pad spaces, the value of String is
     478  stored at the location pointed to by EndPointer.
     479
     480  @param  String                   Pointer to a Null-terminated Unicode string.
     481  @param  EndPointer               Pointer to character that stops scan.
     482  @param  Data                     Pointer to the converted value.
     483
     484  @retval RETURN_SUCCESS           Value is translated from String.
     485  @retval RETURN_INVALID_PARAMETER If String is NULL.
     486                                   If Data is NULL.
     487                                   If PcdMaximumUnicodeStringLength is not
     488                                   zero, and String contains more than
     489                                   PcdMaximumUnicodeStringLength Unicode
     490                                   characters, not including the
     491                                   Null-terminator.
     492  @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
     493                                   the range defined by UINT64.
     494
     495**/
     496RETURN_STATUS
     497EFIAPI
     498StrDecimalToUint64S (
     499  IN  CONST CHAR16             *String,
     500  OUT       CHAR16             **EndPointer,  OPTIONAL
     501  OUT       UINT64             *Data
     502  );
     503
     504/**
     505  Convert a Null-terminated Unicode hexadecimal string to a value of type
     506  UINTN.
     507
     508  This function outputs a value of type UINTN by interpreting the contents of
     509  the Unicode string specified by String as a hexadecimal number. The format of
     510  the input Unicode string String is:
     511
     512                  [spaces][zeros][x][hexadecimal digits].
     513
     514  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
     515  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
     516  If "x" appears in the input string, it must be prefixed with at least one 0.
     517  The function will ignore the pad space, which includes spaces or tab
     518  characters, before [zeros], [x] or [hexadecimal digit]. The running zero
     519  before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
     520  after [x] or the first valid hexadecimal digit. Then, the function stops at
     521  the first character that is a not a valid hexadecimal character or NULL,
     522  whichever one comes first.
     523
     524  If String is NULL, then ASSERT().
     525  If Data is NULL, then ASSERT().
     526  If String is not aligned in a 16-bit boundary, then ASSERT().
     527  If PcdMaximumUnicodeStringLength is not zero, and String contains more than
     528  PcdMaximumUnicodeStringLength Unicode characters, not including the
     529  Null-terminator, then ASSERT().
     530
     531  If String has no valid hexadecimal digits in the above format, then 0 is
     532  stored at the location pointed to by Data.
     533  If the number represented by String exceeds the range defined by UINTN, then
     534  MAX_UINTN is stored at the location pointed to by Data.
     535
     536  If EndPointer is not NULL, a pointer to the character that stopped the scan
     537  is stored at the location pointed to by EndPointer. If String has no valid
     538  hexadecimal digits right after the optional pad spaces, the value of String
     539  is stored at the location pointed to by EndPointer.
     540
     541  @param  String                   Pointer to a Null-terminated Unicode string.
     542  @param  EndPointer               Pointer to character that stops scan.
     543  @param  Data                     Pointer to the converted value.
     544
     545  @retval RETURN_SUCCESS           Value is translated from String.
     546  @retval RETURN_INVALID_PARAMETER If String is NULL.
     547                                   If Data is NULL.
     548                                   If PcdMaximumUnicodeStringLength is not
     549                                   zero, and String contains more than
     550                                   PcdMaximumUnicodeStringLength Unicode
     551                                   characters, not including the
     552                                   Null-terminator.
     553  @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
     554                                   the range defined by UINTN.
     555
     556**/
     557RETURN_STATUS
     558EFIAPI
     559StrHexToUintnS (
     560  IN  CONST CHAR16             *String,
     561  OUT       CHAR16             **EndPointer,  OPTIONAL
     562  OUT       UINTN              *Data
     563  );
     564
     565/**
     566  Convert a Null-terminated Unicode hexadecimal string to a value of type
     567  UINT64.
     568
     569  This function outputs a value of type UINT64 by interpreting the contents of
     570  the Unicode string specified by String as a hexadecimal number. The format of
     571  the input Unicode string String is:
     572
     573                  [spaces][zeros][x][hexadecimal digits].
     574
     575  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
     576  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
     577  If "x" appears in the input string, it must be prefixed with at least one 0.
     578  The function will ignore the pad space, which includes spaces or tab
     579  characters, before [zeros], [x] or [hexadecimal digit]. The running zero
     580  before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
     581  after [x] or the first valid hexadecimal digit. Then, the function stops at
     582  the first character that is a not a valid hexadecimal character or NULL,
     583  whichever one comes first.
     584
     585  If String is NULL, then ASSERT().
     586  If Data is NULL, then ASSERT().
     587  If String is not aligned in a 16-bit boundary, then ASSERT().
     588  If PcdMaximumUnicodeStringLength is not zero, and String contains more than
     589  PcdMaximumUnicodeStringLength Unicode characters, not including the
     590  Null-terminator, then ASSERT().
     591
     592  If String has no valid hexadecimal digits in the above format, then 0 is
     593  stored at the location pointed to by Data.
     594  If the number represented by String exceeds the range defined by UINT64, then
     595  MAX_UINT64 is stored at the location pointed to by Data.
     596
     597  If EndPointer is not NULL, a pointer to the character that stopped the scan
     598  is stored at the location pointed to by EndPointer. If String has no valid
     599  hexadecimal digits right after the optional pad spaces, the value of String
     600  is stored at the location pointed to by EndPointer.
     601
     602  @param  String                   Pointer to a Null-terminated Unicode string.
     603  @param  EndPointer               Pointer to character that stops scan.
     604  @param  Data                     Pointer to the converted value.
     605
     606  @retval RETURN_SUCCESS           Value is translated from String.
     607  @retval RETURN_INVALID_PARAMETER If String is NULL.
     608                                   If Data is NULL.
     609                                   If PcdMaximumUnicodeStringLength is not
     610                                   zero, and String contains more than
     611                                   PcdMaximumUnicodeStringLength Unicode
     612                                   characters, not including the
     613                                   Null-terminator.
     614  @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
     615                                   the range defined by UINT64.
     616
     617**/
     618RETURN_STATUS
     619EFIAPI
     620StrHexToUint64S (
     621  IN  CONST CHAR16             *String,
     622  OUT       CHAR16             **EndPointer,  OPTIONAL
     623  OUT       UINT64             *Data
     624  );
     625
     626/**
    343627  Returns the length of a Null-terminated Ascii string.
     628
     629  This function is similar as strlen_s defined in C11.
    344630
    345631  @param  String   A pointer to a Null-terminated Ascii string.
    … …  
    360646
    361647/**
     648  Returns the size of a Null-terminated Ascii string in bytes, including the
     649  Null terminator.
     650
     651  This function returns the size of the Null-terminated Ascii string specified
     652  by String in bytes, including the Null terminator.
     653
     654  @param  String   A pointer to a Null-terminated Ascii string.
     655  @param  MaxSize  The maximum number of Destination Ascii
     656                   char, including the Null terminator.
     657
     658  @retval 0  If String is NULL.
     659  @retval (sizeof (CHAR8) * (MaxSize + 1))
     660             If there is no Null terminator in the first MaxSize characters of
     661             String.
     662  @return The size of the Null-terminated Ascii string in bytes, including the
     663          Null terminator.
     664
     665**/
     666UINTN
     667EFIAPI
     668AsciiStrnSizeS (
     669  IN CONST CHAR8               *String,
     670  IN UINTN                     MaxSize
     671  );
     672
     673/**
    362674  Copies the string pointed to by Source (including the terminating null char)
    363675  to the array pointed to by Destination.
     676
     677  This function is similar as strcpy_s defined in C11.
     678
     679  If an error would be returned, then the function will also ASSERT().
     680
     681  If an error is returned, then the Destination is unmodified.
    364682
    365683  @param  Destination              A pointer to a Null-terminated Ascii string.
    … …  
    390708  Source to the array pointed to by Destination. If no null char is copied from
    391709  Source, then Destination[Length] is always set to null.
     710
     711  This function is similar as strncpy_s defined in C11.
     712
     713  If an error would be returned, then the function will also ASSERT().
     714
     715  If an error is returned, then the Destination is unmodified.
    392716
    393717  @param  Destination              A pointer to a Null-terminated Ascii string.
    … …  
    420744  Appends a copy of the string pointed to by Source (including the terminating
    421745  null char) to the end of the string pointed to by Destination.
     746
     747  This function is similar as strcat_s defined in C11.
     748
     749  If an error would be returned, then the function will also ASSERT().
     750
     751  If an error is returned, then the Destination is unmodified.
    422752
    423753  @param  Destination              A pointer to a Null-terminated Ascii string.
    … …  
    453783  set to null.
    454784
     785  This function is similar as strncat_s defined in C11.
     786
     787  If an error would be returned, then the function will also ASSERT().
     788
     789  If an error is returned, then the Destination is unmodified.
     790
    455791  @param  Destination              A pointer to a Null-terminated Ascii string.
    456792  @param  DestMax                  The maximum number of Destination Ascii
    … …  
    481817  );
    482818
     819/**
     820  Convert a Null-terminated Ascii decimal string to a value of type UINTN.
     821
     822  This function outputs a value of type UINTN by interpreting the contents of
     823  the Ascii string specified by String as a decimal number. The format of the
     824  input Ascii string String is:
     825
     826                  [spaces] [decimal digits].
     827
     828  The valid decimal digit character is in the range [0-9]. The function will
     829  ignore the pad space, which includes spaces or tab characters, before
     830  [decimal digits]. The running zero in the beginning of [decimal digits] will
     831  be ignored. Then, the function stops at the first character that is a not a
     832  valid decimal character or a Null-terminator, whichever one comes first.
     833
     834  If String is NULL, then ASSERT().
     835  If Data is NULL, then ASSERT().
     836  If PcdMaximumAsciiStringLength is not zero, and String contains more than
     837  PcdMaximumAsciiStringLength Ascii characters, not including the
     838  Null-terminator, then ASSERT().
     839
     840  If String has no valid decimal digits in the above format, then 0 is stored
     841  at the location pointed to by Data.
     842  If the number represented by String exceeds the range defined by UINTN, then
     843  MAX_UINTN is stored at the location pointed to by Data.
     844
     845  If EndPointer is not NULL, a pointer to the character that stopped the scan
     846  is stored at the location pointed to by EndPointer. If String has no valid
     847  decimal digits right after the optional pad spaces, the value of String is
     848  stored at the location pointed to by EndPointer.
     849
     850  @param  String                   Pointer to a Null-terminated Ascii string.
     851  @param  EndPointer               Pointer to character that stops scan.
     852  @param  Data                     Pointer to the converted value.
     853
     854  @retval RETURN_SUCCESS           Value is translated from String.
     855  @retval RETURN_INVALID_PARAMETER If String is NULL.
     856                                   If Data is NULL.
     857                                   If PcdMaximumAsciiStringLength is not zero,
     858                                   and String contains more than
     859                                   PcdMaximumAsciiStringLength Ascii
     860                                   characters, not including the
     861                                   Null-terminator.
     862  @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
     863                                   the range defined by UINTN.
     864
     865**/
     866RETURN_STATUS
     867EFIAPI
     868AsciiStrDecimalToUintnS (
     869  IN  CONST CHAR8              *String,
     870  OUT       CHAR8              **EndPointer,  OPTIONAL
     871  OUT       UINTN              *Data
     872  );
     873
     874/**
     875  Convert a Null-terminated Ascii decimal string to a value of type UINT64.
     876
     877  This function outputs a value of type UINT64 by interpreting the contents of
     878  the Ascii string specified by String as a decimal number. The format of the
     879  input Ascii string String is:
     880
     881                  [spaces] [decimal digits].
     882
     883  The valid decimal digit character is in the range [0-9]. The function will
     884  ignore the pad space, which includes spaces or tab characters, before
     885  [decimal digits]. The running zero in the beginning of [decimal digits] will
     886  be ignored. Then, the function stops at the first character that is a not a
     887  valid decimal character or a Null-terminator, whichever one comes first.
     888
     889  If String is NULL, then ASSERT().
     890  If Data is NULL, then ASSERT().
     891  If PcdMaximumAsciiStringLength is not zero, and String contains more than
     892  PcdMaximumAsciiStringLength Ascii characters, not including the
     893  Null-terminator, then ASSERT().
     894
     895  If String has no valid decimal digits in the above format, then 0 is stored
     896  at the location pointed to by Data.
     897  If the number represented by String exceeds the range defined by UINT64, then
     898  MAX_UINT64 is stored at the location pointed to by Data.
     899
     900  If EndPointer is not NULL, a pointer to the character that stopped the scan
     901  is stored at the location pointed to by EndPointer. If String has no valid
     902  decimal digits right after the optional pad spaces, the value of String is
     903  stored at the location pointed to by EndPointer.
     904
     905  @param  String                   Pointer to a Null-terminated Ascii string.
     906  @param  EndPointer               Pointer to character that stops scan.
     907  @param  Data                     Pointer to the converted value.
     908
     909  @retval RETURN_SUCCESS           Value is translated from String.
     910  @retval RETURN_INVALID_PARAMETER If String is NULL.
     911                                   If Data is NULL.
     912                                   If PcdMaximumAsciiStringLength is not zero,
     913                                   and String contains more than
     914                                   PcdMaximumAsciiStringLength Ascii
     915                                   characters, not including the
     916                                   Null-terminator.
     917  @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
     918                                   the range defined by UINT64.
     919
     920**/
     921RETURN_STATUS
     922EFIAPI
     923AsciiStrDecimalToUint64S (
     924  IN  CONST CHAR8              *String,
     925  OUT       CHAR8              **EndPointer,  OPTIONAL
     926  OUT       UINT64             *Data
     927  );
     928
     929/**
     930  Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
     931
     932  This function outputs a value of type UINTN by interpreting the contents of
     933  the Ascii string specified by String as a hexadecimal number. The format of
     934  the input Ascii string String is:
     935
     936                  [spaces][zeros][x][hexadecimal digits].
     937
     938  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
     939  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
     940  "x" appears in the input string, it must be prefixed with at least one 0. The
     941  function will ignore the pad space, which includes spaces or tab characters,
     942  before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
     943  [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
     944  the first valid hexadecimal digit. Then, the function stops at the first
     945  character that is a not a valid hexadecimal character or Null-terminator,
     946  whichever on comes first.
     947
     948  If String is NULL, then ASSERT().
     949  If Data is NULL, then ASSERT().
     950  If PcdMaximumAsciiStringLength is not zero, and String contains more than
     951  PcdMaximumAsciiStringLength Ascii characters, not including the
     952  Null-terminator, then ASSERT().
     953
     954  If String has no valid hexadecimal digits in the above format, then 0 is
     955  stored at the location pointed to by Data.
     956  If the number represented by String exceeds the range defined by UINTN, then
     957  MAX_UINTN is stored at the location pointed to by Data.
     958
     959  If EndPointer is not NULL, a pointer to the character that stopped the scan
     960  is stored at the location pointed to by EndPointer. If String has no valid
     961  hexadecimal digits right after the optional pad spaces, the value of String
     962  is stored at the location pointed to by EndPointer.
     963
     964  @param  String                   Pointer to a Null-terminated Ascii string.
     965  @param  EndPointer               Pointer to character that stops scan.
     966  @param  Data                     Pointer to the converted value.
     967
     968  @retval RETURN_SUCCESS           Value is translated from String.
     969  @retval RETURN_INVALID_PARAMETER If String is NULL.
     970                                   If Data is NULL.
     971                                   If PcdMaximumAsciiStringLength is not zero,
     972                                   and String contains more than
     973                                   PcdMaximumAsciiStringLength Ascii
     974                                   characters, not including the
     975                                   Null-terminator.
     976  @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
     977                                   the range defined by UINTN.
     978
     979**/
     980RETURN_STATUS
     981EFIAPI
     982AsciiStrHexToUintnS (
     983  IN  CONST CHAR8              *String,
     984  OUT       CHAR8              **EndPointer,  OPTIONAL
     985  OUT       UINTN              *Data
     986  );
     987
     988/**
     989  Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
     990
     991  This function outputs a value of type UINT64 by interpreting the contents of
     992  the Ascii string specified by String as a hexadecimal number. The format of
     993  the input Ascii string String is:
     994
     995                  [spaces][zeros][x][hexadecimal digits].
     996
     997  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
     998  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
     999  "x" appears in the input string, it must be prefixed with at least one 0. The
     1000  function will ignore the pad space, which includes spaces or tab characters,
     1001  before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
     1002  [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
     1003  the first valid hexadecimal digit. Then, the function stops at the first
     1004  character that is a not a valid hexadecimal character or Null-terminator,
     1005  whichever on comes first.
     1006
     1007  If String is NULL, then ASSERT().
     1008  If Data is NULL, then ASSERT().
     1009  If PcdMaximumAsciiStringLength is not zero, and String contains more than
     1010  PcdMaximumAsciiStringLength Ascii characters, not including the
     1011  Null-terminator, then ASSERT().
     1012
     1013  If String has no valid hexadecimal digits in the above format, then 0 is
     1014  stored at the location pointed to by Data.
     1015  If the number represented by String exceeds the range defined by UINT64, then
     1016  MAX_UINT64 is stored at the location pointed to by Data.
     1017
     1018  If EndPointer is not NULL, a pointer to the character that stopped the scan
     1019  is stored at the location pointed to by EndPointer. If String has no valid
     1020  hexadecimal digits right after the optional pad spaces, the value of String
     1021  is stored at the location pointed to by EndPointer.
     1022
     1023  @param  String                   Pointer to a Null-terminated Ascii string.
     1024  @param  EndPointer               Pointer to character that stops scan.
     1025  @param  Data                     Pointer to the converted value.
     1026
     1027  @retval RETURN_SUCCESS           Value is translated from String.
     1028  @retval RETURN_INVALID_PARAMETER If String is NULL.
     1029                                   If Data is NULL.
     1030                                   If PcdMaximumAsciiStringLength is not zero,
     1031                                   and String contains more than
     1032                                   PcdMaximumAsciiStringLength Ascii
     1033                                   characters, not including the
     1034                                   Null-terminator.
     1035  @retval RETURN_UNSUPPORTED       If the number represented by String exceeds
     1036                                   the range defined by UINT64.
     1037
     1038**/
     1039RETURN_STATUS
     1040EFIAPI
     1041AsciiStrHexToUint64S (
     1042  IN  CONST CHAR8              *String,
     1043  OUT       CHAR8              **EndPointer,  OPTIONAL
     1044  OUT       UINT64             *Data
     1045  );
     1046
    4831047
    4841048#ifndef DISABLE_NEW_DEPRECATED_INTERFACES
    4851049
    4861050/**
    487   [ATTENTION] This function will be deprecated for security reason.
     1051  [ATTENTION] This function is deprecated for security reason.
    4881052
    4891053  Copies one Null-terminated Unicode string to another Null-terminated Unicode
    … …  
    5181082
    5191083/**
    520   [ATTENTION] This function will be deprecated for security reason.
     1084  [ATTENTION] This function is deprecated for security reason.
    5211085
    5221086  Copies up to a specified length from one Null-terminated Unicode string to
    … …  
    6871251
    6881252/**
    689   [ATTENTION] This function will be deprecated for security reason.
     1253  [ATTENTION] This function is deprecated for security reason.
    6901254
    6911255  Concatenates one Null-terminated Unicode string to another Null-terminated
    … …  
    7291293
    7301294/**
    731   [ATTENTION] This function will be deprecated for security reason.
     1295  [ATTENTION] This function is deprecated for security reason.
    7321296
    7331297  Concatenates up to a specified length one Null-terminated Unicode to the end
    … …  
    8321396  then 0 is returned.
    8331397  If the number represented by String overflows according
    834   to the range defined by UINTN, then ASSERT().
     1398  to the range defined by UINTN, then MAX_UINTN is returned.
    8351399
    8361400  If PcdMaximumUnicodeStringLength is not zero, and String contains
    … …  
    8721436  then 0 is returned.
    8731437  If the number represented by String overflows according
    874   to the range defined by UINT64, then ASSERT().
     1438  to the range defined by UINT64, then MAX_UINT64 is returned.
    8751439
    8761440  If PcdMaximumUnicodeStringLength is not zero, and String contains
    … …  
    9141478  then zero is returned.
    9151479  If the number represented by String overflows according to the range defined by
    916   UINTN, then ASSERT().
     1480  UINTN, then MAX_UINTN is returned.
    9171481
    9181482  If PcdMaximumUnicodeStringLength is not zero, and String contains more than
    … …  
    9561520  then zero is returned.
    9571521  If the number represented by String overflows according to the range defined by
    958   UINT64, then ASSERT().
     1522  UINT64, then MAX_UINT64 is returned.
    9591523
    9601524  If PcdMaximumUnicodeStringLength is not zero, and String contains more than
    … …  
    9741538
    9751539/**
     1540  Convert a Null-terminated Unicode string to IPv6 address and prefix length.
     1541
     1542  This function outputs a value of type IPv6_ADDRESS and may output a value
     1543  of type UINT8 by interpreting the contents of the Unicode string specified
     1544  by String. The format of the input Unicode string String is as follows:
     1545
     1546                  X:X:X:X:X:X:X:X[/P]
     1547
     1548  X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
     1549  [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
     1550  memory address and high byte is stored in high memory address. P contains decimal
     1551  digit characters in the range [0-9]. The running zero in the beginning of P will
     1552  be ignored. /P is optional.
     1553
     1554  When /P is not in the String, the function stops at the first character that is
     1555  not a valid hexadecimal digit character after eight X's are converted.
     1556
     1557  When /P is in the String, the function stops at the first character that is not
     1558  a valid decimal digit character after P is converted.
     1559
     1560  "::" can be used to compress one or more groups of X when X contains only 0.
     1561  The "::" can only appear once in the String.
     1562
     1563  If String is NULL, then ASSERT().
     1564
     1565  If Address is NULL, then ASSERT().
     1566
     1567  If String is not aligned in a 16-bit boundary, then ASSERT().
     1568
     1569  If PcdMaximumUnicodeStringLength is not zero, and String contains more than
     1570  PcdMaximumUnicodeStringLength Unicode characters, not including the
     1571  Null-terminator, then ASSERT().
     1572
     1573  If EndPointer is not NULL and Address is translated from String, a pointer
     1574  to the character that stopped the scan is stored at the location pointed to
     1575  by EndPointer.
     1576
     1577  @param  String                   Pointer to a Null-terminated Unicode string.
     1578  @param  EndPointer               Pointer to character that stops scan.
     1579  @param  Address                  Pointer to the converted IPv6 address.
     1580  @param  PrefixLength             Pointer to the converted IPv6 address prefix
     1581                                   length. MAX_UINT8 is returned when /P is
     1582                                   not in the String.
     1583
     1584  @retval RETURN_SUCCESS           Address is translated from String.
     1585  @retval RETURN_INVALID_PARAMETER If String is NULL.
     1586                                   If Data is NULL.
     1587  @retval RETURN_UNSUPPORTED       If X contains more than four hexadecimal
     1588                                    digit characters.
     1589                                   If String contains "::" and number of X
     1590                                    is not less than 8.
     1591                                   If P starts with character that is not a
     1592                                    valid decimal digit character.
     1593                                   If the decimal number converted from P
     1594                                    exceeds 128.
     1595
     1596**/
     1597RETURN_STATUS
     1598EFIAPI
     1599StrToIpv6Address (
     1600  IN  CONST CHAR16       *String,
     1601  OUT CHAR16             **EndPointer, OPTIONAL
     1602  OUT IPv6_ADDRESS       *Address,
     1603  OUT UINT8              *PrefixLength OPTIONAL
     1604  );
     1605
     1606/**
     1607  Convert a Null-terminated Unicode string to IPv4 address and prefix length.
     1608
     1609  This function outputs a value of type IPv4_ADDRESS and may output a value
     1610  of type UINT8 by interpreting the contents of the Unicode string specified
     1611  by String. The format of the input Unicode string String is as follows:
     1612
     1613                  D.D.D.D[/P]
     1614
     1615  D and P are decimal digit characters in the range [0-9]. The running zero in
     1616  the beginning of D and P will be ignored. /P is optional.
     1617
     1618  When /P is not in the String, the function stops at the first character that is
     1619  not a valid decimal digit character after four D's are converted.
     1620
     1621  When /P is in the String, the function stops at the first character that is not
     1622  a valid decimal digit character after P is converted.
     1623
     1624  If String is NULL, then ASSERT().
     1625
     1626  If Address is NULL, then ASSERT().
     1627
     1628  If String is not aligned in a 16-bit boundary, then ASSERT().
     1629
     1630  If PcdMaximumUnicodeStringLength is not zero, and String contains more than
     1631  PcdMaximumUnicodeStringLength Unicode characters, not including the
     1632  Null-terminator, then ASSERT().
     1633
     1634  If EndPointer is not NULL and Address is translated from String, a pointer
     1635  to the character that stopped the scan is stored at the location pointed to
     1636  by EndPointer.
     1637
     1638  @param  String                   Pointer to a Null-terminated Unicode string.
     1639  @param  EndPointer               Pointer to character that stops scan.
     1640  @param  Address                  Pointer to the converted IPv4 address.
     1641  @param  PrefixLength             Pointer to the converted IPv4 address prefix
     1642                                   length. MAX_UINT8 is returned when /P is
     1643                                   not in the String.
     1644
     1645  @retval RETURN_SUCCESS           Address is translated from String.
     1646  @retval RETURN_INVALID_PARAMETER If String is NULL.
     1647                                   If Data is NULL.
     1648  @retval RETURN_UNSUPPORTED       If String is not in the correct format.
     1649                                   If any decimal number converted from D
     1650                                    exceeds 255.
     1651                                   If the decimal number converted from P
     1652                                    exceeds 32.
     1653
     1654**/
     1655RETURN_STATUS
     1656EFIAPI
     1657StrToIpv4Address (
     1658  IN  CONST CHAR16       *String,
     1659  OUT CHAR16             **EndPointer, OPTIONAL
     1660  OUT IPv4_ADDRESS       *Address,
     1661  OUT UINT8              *PrefixLength OPTIONAL
     1662  );
     1663
     1664#define GUID_STRING_LENGTH  36
     1665
     1666/**
     1667  Convert a Null-terminated Unicode GUID string to a value of type
     1668  EFI_GUID.
     1669
     1670  This function outputs a GUID value by interpreting the contents of
     1671  the Unicode string specified by String. The format of the input
     1672  Unicode string String consists of 36 characters, as follows:
     1673
     1674                  aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
     1675
     1676  The pairs aa - pp are two characters in the range [0-9], [a-f] and
     1677  [A-F], with each pair representing a single byte hexadecimal value.
     1678
     1679  The mapping between String and the EFI_GUID structure is as follows:
     1680                  aa          Data1[24:31]
     1681                  bb          Data1[16:23]
     1682                  cc          Data1[8:15]
     1683                  dd          Data1[0:7]
     1684                  ee          Data2[8:15]
     1685                  ff          Data2[0:7]
     1686                  gg          Data3[8:15]
     1687                  hh          Data3[0:7]
     1688                  ii          Data4[0:7]
     1689                  jj          Data4[8:15]
     1690                  kk          Data4[16:23]
     1691                  ll          Data4[24:31]
     1692                  mm          Data4[32:39]
     1693                  nn          Data4[40:47]
     1694                  oo          Data4[48:55]
     1695                  pp          Data4[56:63]
     1696
     1697  If String is NULL, then ASSERT().
     1698  If Guid is NULL, then ASSERT().
     1699  If String is not aligned in a 16-bit boundary, then ASSERT().
     1700
     1701  @param  String                   Pointer to a Null-terminated Unicode string.
     1702  @param  Guid                     Pointer to the converted GUID.
     1703
     1704  @retval RETURN_SUCCESS           Guid is translated from String.
     1705  @retval RETURN_INVALID_PARAMETER If String is NULL.
     1706                                   If Data is NULL.
     1707  @retval RETURN_UNSUPPORTED       If String is not as the above format.
     1708
     1709**/
     1710RETURN_STATUS
     1711EFIAPI
     1712StrToGuid (
     1713  IN  CONST CHAR16       *String,
     1714  OUT GUID               *Guid
     1715  );
     1716
     1717/**
     1718  Convert a Null-terminated Unicode hexadecimal string to a byte array.
     1719
     1720  This function outputs a byte array by interpreting the contents of
     1721  the Unicode string specified by String in hexadecimal format. The format of
     1722  the input Unicode string String is:
     1723
     1724                  [XX]*
     1725
     1726  X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
     1727  The function decodes every two hexadecimal digit characters as one byte. The
     1728  decoding stops after Length of characters and outputs Buffer containing
     1729  (Length / 2) bytes.
     1730
     1731  If String is not aligned in a 16-bit boundary, then ASSERT().
     1732
     1733  If String is NULL, then ASSERT().
     1734
     1735  If Buffer is NULL, then ASSERT().
     1736
     1737  If Length is not multiple of 2, then ASSERT().
     1738
     1739  If PcdMaximumUnicodeStringLength is not zero and Length is greater than
     1740  PcdMaximumUnicodeStringLength, then ASSERT().
     1741
     1742  If MaxBufferSize is less than (Length / 2), then ASSERT().
     1743
     1744  @param  String                   Pointer to a Null-terminated Unicode string.
     1745  @param  Length                   The number of Unicode characters to decode.
     1746  @param  Buffer                   Pointer to the converted bytes array.
     1747  @param  MaxBufferSize            The maximum size of Buffer.
     1748
     1749  @retval RETURN_SUCCESS           Buffer is translated from String.
     1750  @retval RETURN_INVALID_PARAMETER If String is NULL.
     1751                                   If Data is NULL.
     1752                                   If Length is not multiple of 2.
     1753                                   If PcdMaximumUnicodeStringLength is not zero,
     1754                                    and Length is greater than
     1755                                    PcdMaximumUnicodeStringLength.
     1756  @retval RETURN_UNSUPPORTED       If Length of characters from String contain
     1757                                    a character that is not valid hexadecimal
     1758                                    digit characters, or a Null-terminator.
     1759  @retval RETURN_BUFFER_TOO_SMALL  If MaxBufferSize is less than (Length / 2).
     1760**/
     1761RETURN_STATUS
     1762EFIAPI
     1763StrHexToBytes (
     1764  IN  CONST CHAR16       *String,
     1765  IN  UINTN              Length,
     1766  OUT UINT8              *Buffer,
     1767  IN  UINTN              MaxBufferSize
     1768  );
     1769
     1770#ifndef DISABLE_NEW_DEPRECATED_INTERFACES
     1771
     1772/**
     1773  [ATTENTION] This function is deprecated for security reason.
     1774
    9761775  Convert a Null-terminated Unicode string to a Null-terminated
    9771776  ASCII string and returns the ASCII string.
    … …  
    10131812  );
    10141813
     1814#endif
     1815
     1816/**
     1817  Convert a Null-terminated Unicode string to a Null-terminated
     1818  ASCII string.
     1819
     1820  This function is similar to AsciiStrCpyS.
     1821
     1822  This function converts the content of the Unicode string Source
     1823  to the ASCII string Destination by copying the lower 8 bits of
     1824  each Unicode character. The function terminates the ASCII string
     1825  Destination by appending a Null-terminator character at the end.
     1826
     1827  The caller is responsible to make sure Destination points to a buffer with size
     1828  equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
     1829
     1830  If any Unicode characters in Source contain non-zero value in
     1831  the upper 8 bits, then ASSERT().
     1832
     1833  If Source is not aligned on a 16-bit boundary, then ASSERT().
     1834  If an error would be returned, then the function will also ASSERT().
     1835
     1836  If an error is returned, then the Destination is unmodified.
     1837
     1838  @param  Source        The pointer to a Null-terminated Unicode string.
     1839  @param  Destination   The pointer to a Null-terminated ASCII string.
     1840  @param  DestMax       The maximum number of Destination Ascii
     1841                        char, including terminating null char.
     1842
     1843  @retval RETURN_SUCCESS           String is converted.
     1844  @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than StrLen(Source).
     1845  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
     1846                                   If Source is NULL.
     1847                                   If PcdMaximumAsciiStringLength is not zero,
     1848                                    and DestMax is greater than
     1849                                    PcdMaximumAsciiStringLength.
     1850                                   If PcdMaximumUnicodeStringLength is not zero,
     1851                                    and DestMax is greater than
     1852                                    PcdMaximumUnicodeStringLength.
     1853                                   If DestMax is 0.
     1854  @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
     1855
     1856**/
     1857RETURN_STATUS
     1858EFIAPI
     1859UnicodeStrToAsciiStrS (
     1860  IN      CONST CHAR16              *Source,
     1861  OUT     CHAR8                     *Destination,
     1862  IN      UINTN                     DestMax
     1863  );
     1864
     1865/**
     1866  Convert not more than Length successive characters from a Null-terminated
     1867  Unicode string to a Null-terminated Ascii string. If no null char is copied
     1868  from Source, then Destination[Length] is always set to null.
     1869
     1870  This function converts not more than Length successive characters from the
     1871  Unicode string Source to the Ascii string Destination by copying the lower 8
     1872  bits of each Unicode character. The function terminates the Ascii string
     1873  Destination by appending a Null-terminator character at the end.
     1874
     1875  The caller is responsible to make sure Destination points to a buffer with size
     1876  equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
     1877
     1878  If any Unicode characters in Source contain non-zero value in the upper 8
     1879  bits, then ASSERT().
     1880  If Source is not aligned on a 16-bit boundary, then ASSERT().
     1881  If an error would be returned, then the function will also ASSERT().
     1882
     1883  If an error is returned, then the Destination is unmodified.
     1884
     1885  @param  Source             The pointer to a Null-terminated Unicode string.
     1886  @param  Length             The maximum number of Unicode characters to
     1887                             convert.
     1888  @param  Destination        The pointer to a Null-terminated Ascii string.
     1889  @param  DestMax            The maximum number of Destination Ascii
     1890                             char, including terminating null char.
     1891  @param  DestinationLength  The number of Unicode characters converted.
     1892
     1893  @retval RETURN_SUCCESS            String is converted.
     1894  @retval RETURN_INVALID_PARAMETER  If Destination is NULL.
     1895                                    If Source is NULL.
     1896                                    If DestinationLength is NULL.
     1897                                    If PcdMaximumAsciiStringLength is not zero,
     1898                                    and Length or DestMax is greater than
     1899                                    PcdMaximumAsciiStringLength.
     1900                                    If PcdMaximumUnicodeStringLength is not
     1901                                    zero, and Length or DestMax is greater than
     1902                                    PcdMaximumUnicodeStringLength.
     1903                                    If DestMax is 0.
     1904  @retval RETURN_BUFFER_TOO_SMALL   If DestMax is NOT greater than
     1905                                    MIN(StrLen(Source), Length).
     1906  @retval RETURN_ACCESS_DENIED      If Source and Destination overlap.
     1907
     1908**/
     1909RETURN_STATUS
     1910EFIAPI
     1911UnicodeStrnToAsciiStrS (
     1912  IN      CONST CHAR16              *Source,
     1913  IN      UINTN                     Length,
     1914  OUT     CHAR8                     *Destination,
     1915  IN      UINTN                     DestMax,
     1916  OUT     UINTN                     *DestinationLength
     1917  );
    10151918
    10161919#ifndef DISABLE_NEW_DEPRECATED_INTERFACES
    10171920
    10181921/**
    1019   [ATTENTION] This function will be deprecated for security reason.
     1922  [ATTENTION] This function is deprecated for security reason.
    10201923
    10211924  Copies one Null-terminated ASCII string to another Null-terminated ASCII
    … …  
    10481951
    10491952/**
    1050   [ATTENTION] This function will be deprecated for security reason.
     1953  [ATTENTION] This function is deprecated for security reason.
    10511954
    10521955  Copies up to a specified length one Null-terminated ASCII string to another
    … …  
    12462149
    12472150/**
    1248   [ATTENTION] This function will be deprecated for security reason.
     2151  [ATTENTION] This function is deprecated for security reason.
    12492152
    12502153  Concatenates one Null-terminated ASCII string to another Null-terminated
    … …  
    12832186
    12842187/**
    1285   [ATTENTION] This function will be deprecated for security reason.
     2188  [ATTENTION] This function is deprecated for security reason.
    12862189
    12872190  Concatenates up to a specified length one Null-terminated ASCII string to
    … …  
    13802283  If String has no pad spaces or valid decimal digits, then 0 is returned.
    13812284  If the number represented by String overflows according to the range defined by
    1382   UINTN, then ASSERT().
     2285  UINTN, then MAX_UINTN is returned.
    13832286  If String is NULL, then ASSERT().
    13842287  If PcdMaximumAsciiStringLength is not zero, and String contains more than
    … …  
    14172320  If String has no pad spaces or valid decimal digits, then 0 is returned.
    14182321  If the number represented by String overflows according to the range defined by
    1419   UINT64, then ASSERT().
     2322  UINT64, then MAX_UINT64 is returned.
    14202323  If String is NULL, then ASSERT().
    14212324  If PcdMaximumAsciiStringLength is not zero, and String contains more than
    … …  
    14582361
    14592362  If the number represented by String overflows according to the range defined by UINTN,
    1460   then ASSERT().
     2363  then MAX_UINTN is returned.
    14612364  If String is NULL, then ASSERT().
    14622365  If PcdMaximumAsciiStringLength is not zero,
    … …  
    14992402
    15002403  If the number represented by String overflows according to the range defined by UINT64,
    1501   then ASSERT().
     2404  then MAX_UINT64 is returned.
    15022405  If String is NULL, then ASSERT().
    15032406  If PcdMaximumAsciiStringLength is not zero,
    … …  
    15162419  );
    15172420
    1518 
    1519 /**
     2421/**
     2422  Convert a Null-terminated ASCII string to IPv6 address and prefix length.
     2423
     2424  This function outputs a value of type IPv6_ADDRESS and may output a value
     2425  of type UINT8 by interpreting the contents of the ASCII string specified
     2426  by String. The format of the input ASCII string String is as follows:
     2427
     2428                  X:X:X:X:X:X:X:X[/P]
     2429
     2430  X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
     2431  [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
     2432  memory address and high byte is stored in high memory address. P contains decimal
     2433  digit characters in the range [0-9]. The running zero in the beginning of P will
     2434  be ignored. /P is optional.
     2435
     2436  When /P is not in the String, the function stops at the first character that is
     2437  not a valid hexadecimal digit character after eight X's are converted.
     2438
     2439  When /P is in the String, the function stops at the first character that is not
     2440  a valid decimal digit character after P is converted.
     2441
     2442  "::" can be used to compress one or more groups of X when X contains only 0.
     2443  The "::" can only appear once in the String.
     2444
     2445  If String is NULL, then ASSERT().
     2446
     2447  If Address is NULL, then ASSERT().
     2448
     2449  If EndPointer is not NULL and Address is translated from String, a pointer
     2450  to the character that stopped the scan is stored at the location pointed to
     2451  by EndPointer.
     2452
     2453  @param  String                   Pointer to a Null-terminated ASCII string.
     2454  @param  EndPointer               Pointer to character that stops scan.
     2455  @param  Address                  Pointer to the converted IPv6 address.
     2456  @param  PrefixLength             Pointer to the converted IPv6 address prefix
     2457                                   length. MAX_UINT8 is returned when /P is
     2458                                   not in the String.
     2459
     2460  @retval RETURN_SUCCESS           Address is translated from String.
     2461  @retval RETURN_INVALID_PARAMETER If String is NULL.
     2462                                   If Data is NULL.
     2463  @retval RETURN_UNSUPPORTED       If X contains more than four hexadecimal
     2464                                    digit characters.
     2465                                   If String contains "::" and number of X
     2466                                    is not less than 8.
     2467                                   If P starts with character that is not a
     2468                                    valid decimal digit character.
     2469                                   If the decimal number converted from P
     2470                                    exceeds 128.
     2471
     2472**/
     2473RETURN_STATUS
     2474EFIAPI
     2475AsciiStrToIpv6Address (
     2476  IN  CONST CHAR8        *String,
     2477  OUT CHAR8              **EndPointer, OPTIONAL
     2478  OUT IPv6_ADDRESS       *Address,
     2479  OUT UINT8              *PrefixLength OPTIONAL
     2480  );
     2481
     2482/**
     2483  Convert a Null-terminated ASCII string to IPv4 address and prefix length.
     2484
     2485  This function outputs a value of type IPv4_ADDRESS and may output a value
     2486  of type UINT8 by interpreting the contents of the ASCII string specified
     2487  by String. The format of the input ASCII string String is as follows:
     2488
     2489                  D.D.D.D[/P]
     2490
     2491  D and P are decimal digit characters in the range [0-9]. The running zero in
     2492  the beginning of D and P will be ignored. /P is optional.
     2493
     2494  When /P is not in the String, the function stops at the first character that is
     2495  not a valid decimal digit character after four D's are converted.
     2496
     2497  When /P is in the String, the function stops at the first character that is not
     2498  a valid decimal digit character after P is converted.
     2499
     2500  If String is NULL, then ASSERT().
     2501
     2502  If Address is NULL, then ASSERT().
     2503
     2504  If EndPointer is not NULL and Address is translated from String, a pointer
     2505  to the character that stopped the scan is stored at the location pointed to
     2506  by EndPointer.
     2507
     2508  @param  String                   Pointer to a Null-terminated ASCII string.
     2509  @param  EndPointer               Pointer to character that stops scan.
     2510  @param  Address                  Pointer to the converted IPv4 address.
     2511  @param  PrefixLength             Pointer to the converted IPv4 address prefix
     2512                                   length. MAX_UINT8 is returned when /P is
     2513                                   not in the String.
     2514
     2515  @retval RETURN_SUCCESS           Address is translated from String.
     2516  @retval RETURN_INVALID_PARAMETER If String is NULL.
     2517                                   If Data is NULL.
     2518  @retval RETURN_UNSUPPORTED       If String is not in the correct format.
     2519                                   If any decimal number converted from D
     2520                                    exceeds 255.
     2521                                   If the decimal number converted from P
     2522                                    exceeds 32.
     2523
     2524**/
     2525RETURN_STATUS
     2526EFIAPI
     2527AsciiStrToIpv4Address (
     2528  IN  CONST CHAR8        *String,
     2529  OUT CHAR8              **EndPointer, OPTIONAL
     2530  OUT IPv4_ADDRESS       *Address,
     2531  OUT UINT8              *PrefixLength OPTIONAL
     2532  );
     2533
     2534/**
     2535  Convert a Null-terminated ASCII GUID string to a value of type
     2536  EFI_GUID.
     2537
     2538  This function outputs a GUID value by interpreting the contents of
     2539  the ASCII string specified by String. The format of the input
     2540  ASCII string String consists of 36 characters, as follows:
     2541
     2542                  aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
     2543
     2544  The pairs aa - pp are two characters in the range [0-9], [a-f] and
     2545  [A-F], with each pair representing a single byte hexadecimal value.
     2546
     2547  The mapping between String and the EFI_GUID structure is as follows:
     2548                  aa          Data1[24:31]
     2549                  bb          Data1[16:23]
     2550                  cc          Data1[8:15]
     2551                  dd          Data1[0:7]
     2552                  ee          Data2[8:15]
     2553                  ff          Data2[0:7]
     2554                  gg          Data3[8:15]
     2555                  hh          Data3[0:7]
     2556                  ii          Data4[0:7]
     2557                  jj          Data4[8:15]
     2558                  kk          Data4[16:23]
     2559                  ll          Data4[24:31]
     2560                  mm          Data4[32:39]
     2561                  nn          Data4[40:47]
     2562                  oo          Data4[48:55]
     2563                  pp          Data4[56:63]
     2564
     2565  If String is NULL, then ASSERT().
     2566  If Guid is NULL, then ASSERT().
     2567
     2568  @param  String                   Pointer to a Null-terminated ASCII string.
     2569  @param  Guid                     Pointer to the converted GUID.
     2570
     2571  @retval RETURN_SUCCESS           Guid is translated from String.
     2572  @retval RETURN_INVALID_PARAMETER If String is NULL.
     2573                                   If Data is NULL.
     2574  @retval RETURN_UNSUPPORTED       If String is not as the above format.
     2575
     2576**/
     2577RETURN_STATUS
     2578EFIAPI
     2579AsciiStrToGuid (
     2580  IN  CONST CHAR8        *String,
     2581  OUT GUID               *Guid
     2582  );
     2583
     2584/**
     2585  Convert a Null-terminated ASCII hexadecimal string to a byte array.
     2586
     2587  This function outputs a byte array by interpreting the contents of
     2588  the ASCII string specified by String in hexadecimal format. The format of
     2589  the input ASCII string String is:
     2590
     2591                  [XX]*
     2592
     2593  X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
     2594  The function decodes every two hexadecimal digit characters as one byte. The
     2595  decoding stops after Length of characters and outputs Buffer containing
     2596  (Length / 2) bytes.
     2597
     2598  If String is NULL, then ASSERT().
     2599
     2600  If Buffer is NULL, then ASSERT().
     2601
     2602  If Length is not multiple of 2, then ASSERT().
     2603
     2604  If PcdMaximumAsciiStringLength is not zero and Length is greater than
     2605  PcdMaximumAsciiStringLength, then ASSERT().
     2606
     2607  If MaxBufferSize is less than (Length / 2), then ASSERT().
     2608
     2609  @param  String                   Pointer to a Null-terminated ASCII string.
     2610  @param  Length                   The number of ASCII characters to decode.
     2611  @param  Buffer                   Pointer to the converted bytes array.
     2612  @param  MaxBufferSize            The maximum size of Buffer.
     2613
     2614  @retval RETURN_SUCCESS           Buffer is translated from String.
     2615  @retval RETURN_INVALID_PARAMETER If String is NULL.
     2616                                   If Data is NULL.
     2617                                   If Length is not multiple of 2.
     2618                                   If PcdMaximumAsciiStringLength is not zero,
     2619                                    and Length is greater than
     2620                                    PcdMaximumAsciiStringLength.
     2621  @retval RETURN_UNSUPPORTED       If Length of characters from String contain
     2622                                    a character that is not valid hexadecimal
     2623                                    digit characters, or a Null-terminator.
     2624  @retval RETURN_BUFFER_TOO_SMALL  If MaxBufferSize is less than (Length / 2).
     2625**/
     2626RETURN_STATUS
     2627EFIAPI
     2628AsciiStrHexToBytes (
     2629  IN  CONST CHAR8        *String,
     2630  IN  UINTN              Length,
     2631  OUT UINT8              *Buffer,
     2632  IN  UINTN              MaxBufferSize
     2633  );
     2634
     2635#ifndef DISABLE_NEW_DEPRECATED_INTERFACES
     2636
     2637/**
     2638  [ATTENTION] This function is deprecated for security reason.
     2639
    15202640  Convert one Null-terminated ASCII string to a Null-terminated
    15212641  Unicode string and returns the Unicode string.
    … …  
    15512671  );
    15522672
     2673#endif
     2674
     2675/**
     2676  Convert one Null-terminated ASCII string to a Null-terminated
     2677  Unicode string.
     2678
     2679  This function is similar to StrCpyS.
     2680
     2681  This function converts the contents of the ASCII string Source to the Unicode
     2682  string Destination. The function terminates the Unicode string Destination by
     2683  appending a Null-terminator character at the end.
     2684
     2685  The caller is responsible to make sure Destination points to a buffer with size
     2686  equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
     2687
     2688  If Destination is not aligned on a 16-bit boundary, then ASSERT().
     2689  If an error would be returned, then the function will also ASSERT().
     2690
     2691  If an error is returned, then the Destination is unmodified.
     2692
     2693  @param  Source        The pointer to a Null-terminated ASCII string.
     2694  @param  Destination   The pointer to a Null-terminated Unicode string.
     2695  @param  DestMax       The maximum number of Destination Unicode
     2696                        char, including terminating null char.
     2697
     2698  @retval RETURN_SUCCESS           String is converted.
     2699  @retval RETURN_BUFFER_TOO_SMALL  If DestMax is NOT greater than StrLen(Source).
     2700  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
     2701                                   If Source is NULL.
     2702                                   If PcdMaximumUnicodeStringLength is not zero,
     2703                                    and DestMax is greater than
     2704                                    PcdMaximumUnicodeStringLength.
     2705                                   If PcdMaximumAsciiStringLength is not zero,
     2706                                    and DestMax is greater than
     2707                                    PcdMaximumAsciiStringLength.
     2708                                   If DestMax is 0.
     2709  @retval RETURN_ACCESS_DENIED     If Source and Destination overlap.
     2710
     2711**/
     2712RETURN_STATUS
     2713EFIAPI
     2714AsciiStrToUnicodeStrS (
     2715  IN      CONST CHAR8               *Source,
     2716  OUT     CHAR16                    *Destination,
     2717  IN      UINTN                     DestMax
     2718  );
     2719
     2720/**
     2721  Convert not more than Length successive characters from a Null-terminated
     2722  Ascii string to a Null-terminated Unicode string. If no null char is copied
     2723  from Source, then Destination[Length] is always set to null.
     2724
     2725  This function converts not more than Length successive characters from the
     2726  Ascii string Source to the Unicode string Destination. The function
     2727  terminates the Unicode string Destination by appending a Null-terminator
     2728  character at the end.
     2729
     2730  The caller is responsible to make sure Destination points to a buffer with
     2731  size not smaller than
     2732  ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
     2733
     2734  If Destination is not aligned on a 16-bit boundary, then ASSERT().
     2735  If an error would be returned, then the function will also ASSERT().
     2736
     2737  If an error is returned, then Destination and DestinationLength are
     2738  unmodified.
     2739
     2740  @param  Source             The pointer to a Null-terminated Ascii string.
     2741  @param  Length             The maximum number of Ascii characters to convert.
     2742  @param  Destination        The pointer to a Null-terminated Unicode string.
     2743  @param  DestMax            The maximum number of Destination Unicode char,
     2744                             including terminating null char.
     2745  @param  DestinationLength  The number of Ascii characters converted.
     2746
     2747  @retval RETURN_SUCCESS            String is converted.
     2748  @retval RETURN_INVALID_PARAMETER  If Destination is NULL.
     2749                                    If Source is NULL.
     2750                                    If DestinationLength is NULL.
     2751                                    If PcdMaximumUnicodeStringLength is not
     2752                                    zero, and Length or DestMax is greater than
     2753                                    PcdMaximumUnicodeStringLength.
     2754                                    If PcdMaximumAsciiStringLength is not zero,
     2755                                    and Length or DestMax is greater than
     2756                                    PcdMaximumAsciiStringLength.
     2757                                    If DestMax is 0.
     2758  @retval RETURN_BUFFER_TOO_SMALL   If DestMax is NOT greater than
     2759                                    MIN(AsciiStrLen(Source), Length).
     2760  @retval RETURN_ACCESS_DENIED      If Source and Destination overlap.
     2761
     2762**/
     2763RETURN_STATUS
     2764EFIAPI
     2765AsciiStrnToUnicodeStrS (
     2766  IN      CONST CHAR8               *Source,
     2767  IN      UINTN                     Length,
     2768  OUT     CHAR16                    *Destination,
     2769  IN      UINTN                     DestMax,
     2770  OUT     UINTN                     *DestinationLength
     2771  );
    15532772
    15542773/**
    … …  
    15922811  );
    15932812
     2813//
     2814//  File Path Manipulation Functions
     2815//
     2816
     2817/**
     2818  Removes the last directory or file entry in a path.
     2819
     2820  @param[in, out] Path    The pointer to the path to modify.
     2821
     2822  @retval FALSE     Nothing was found to remove.
     2823  @retval TRUE      A directory or file was removed.
     2824**/
     2825BOOLEAN
     2826EFIAPI
     2827PathRemoveLastItem(
     2828  IN OUT CHAR16 *Path
     2829  );
     2830
     2831/**
     2832  Function to clean up paths.
     2833    - Single periods in the path are removed.
     2834    - Double periods in the path are removed along with a single parent directory.
     2835    - Forward slashes L'/' are converted to backward slashes L'\'.
     2836
     2837  This will be done inline and the existing buffer may be larger than required
     2838  upon completion.
     2839
     2840  @param[in] Path       The pointer to the string containing the path.
     2841
     2842  @return       Returns Path, otherwise returns NULL to indicate that an error has occurred.
     2843**/
     2844CHAR16*
     2845EFIAPI
     2846PathCleanUpDirectories(
     2847  IN CHAR16 *Path
     2848  );
    15942849
    15952850//
    … …  
    16122867**/
    16132868#define INITIALIZE_LIST_HEAD_VARIABLE(ListHead)  {&(ListHead), &(ListHead)}
     2869
     2870
     2871/**
     2872  Checks whether FirstEntry and SecondEntry are part of the same doubly-linked
     2873  list.
     2874
     2875  If FirstEntry is NULL, then ASSERT().
     2876  If FirstEntry->ForwardLink is NULL, then ASSERT().
     2877  If FirstEntry->BackLink is NULL, then ASSERT().
     2878  If SecondEntry is NULL, then ASSERT();
     2879  If PcdMaximumLinkedListLength is not zero, and List contains more than
     2880  PcdMaximumLinkedListLength nodes, then ASSERT().
     2881
     2882  @param  FirstEntry   A pointer to a node in a linked list.
     2883  @param  SecondEntry  A pointer to the node to locate.
     2884
     2885  @retval TRUE   SecondEntry is in the same doubly-linked list as FirstEntry.
     2886  @retval FALSE  SecondEntry isn't in the same doubly-linked list as FirstEntry,
     2887                 or FirstEntry is invalid.
     2888
     2889**/
     2890BOOLEAN
     2891EFIAPI
     2892IsNodeInList (
     2893  IN      CONST LIST_ENTRY      *FirstEntry,
     2894  IN      CONST LIST_ENTRY      *SecondEntry
     2895  );
    16142896
    16152897
    … …  
    35484830  );
    35494831
     4832/**
     4833  Computes and returns a 32-bit CRC for a data buffer.
     4834  CRC32 value bases on ITU-T V.42.
     4835
     4836  If Buffer is NULL, then ASSERT().
     4837  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
     4838
     4839  @param[in]  Buffer       A pointer to the buffer on which the 32-bit CRC is to be computed.
     4840  @param[in]  Length       The number of bytes in the buffer Data.
     4841
     4842  @retval Crc32            The 32-bit CRC was computed for the data buffer.
     4843
     4844**/
     4845UINT32
     4846EFIAPI
     4847CalculateCrc32(
     4848  IN  VOID                         *Buffer,
     4849  IN  UINTN                        Length
     4850  );
    35504851
    35514852//
    … …  
    53476648#define IA32_IDT_GATE_TYPE_TRAP_32       0x8F
    53486649
     6650#define IA32_GDT_TYPE_TSS               0x9
     6651#define IA32_GDT_ALIGNMENT              8
    53496652
    53506653#if defined (MDE_CPU_IA32)
    … …  
    53626665  UINT64  Uint64;
    53636666} IA32_IDT_GATE_DESCRIPTOR;
     6667
     6668#pragma pack (1)
     6669//
     6670// IA32 Task-State Segment Definition
     6671//
     6672typedef struct {
     6673  UINT16    PreviousTaskLink;
     6674  UINT16    Reserved_2;
     6675  UINT32    ESP0;
     6676  UINT16    SS0;
     6677  UINT16    Reserved_10;
     6678  UINT32    ESP1;
     6679  UINT16    SS1;
     6680  UINT16    Reserved_18;
     6681  UINT32    ESP2;
     6682  UINT16    SS2;
     6683  UINT16    Reserved_26;
     6684  UINT32    CR3;
     6685  UINT32    EIP;
     6686  UINT32    EFLAGS;
     6687  UINT32    EAX;
     6688  UINT32    ECX;
     6689  UINT32    EDX;
     6690  UINT32    EBX;
     6691  UINT32    ESP;
     6692  UINT32    EBP;
     6693  UINT32    ESI;
     6694  UINT32    EDI;
     6695  UINT16    ES;
     6696  UINT16    Reserved_74;
     6697  UINT16    CS;
     6698  UINT16    Reserved_78;
     6699  UINT16    SS;
     6700  UINT16    Reserved_82;
     6701  UINT16    DS;
     6702  UINT16    Reserved_86;
     6703  UINT16    FS;
     6704  UINT16    Reserved_90;
     6705  UINT16    GS;
     6706  UINT16    Reserved_94;
     6707  UINT16    LDTSegmentSelector;
     6708  UINT16    Reserved_98;
     6709  UINT16    T;
     6710  UINT16    IOMapBaseAddress;
     6711} IA32_TASK_STATE_SEGMENT;
     6712
     6713typedef union {
     6714  struct {
     6715    UINT32  LimitLow:16;    ///< Segment Limit 15..00
     6716    UINT32  BaseLow:16;     ///< Base Address  15..00
     6717    UINT32  BaseMid:8;      ///< Base Address  23..16
     6718    UINT32  Type:4;         ///< Type (1 0 B 1)
     6719    UINT32  Reserved_43:1;  ///< 0
     6720    UINT32  DPL:2;          ///< Descriptor Privilege Level
     6721    UINT32  P:1;            ///< Segment Present
     6722    UINT32  LimitHigh:4;    ///< Segment Limit 19..16
     6723    UINT32  AVL:1;          ///< Available for use by system software
     6724    UINT32  Reserved_52:2;  ///< 0 0
     6725    UINT32  G:1;            ///< Granularity
     6726    UINT32  BaseHigh:8;     ///< Base Address 31..24
     6727  } Bits;
     6728  UINT64  Uint64;
     6729} IA32_TSS_DESCRIPTOR;
     6730#pragma pack ()
    53646731
    53656732#endif
    … …  
    53846751  } Uint128;
    53856752} IA32_IDT_GATE_DESCRIPTOR;
     6753
     6754#pragma pack (1)
     6755//
     6756// IA32 Task-State Segment Definition
     6757//
     6758typedef struct {
     6759  UINT32    Reserved_0;
     6760  UINT64    RSP0;
     6761  UINT64    RSP1;
     6762  UINT64    RSP2;
     6763  UINT64    Reserved_28;
     6764  UINT64    IST[7];
     6765  UINT64    Reserved_92;
     6766  UINT16    Reserved_100;
     6767  UINT16    IOMapBaseAddress;
     6768} IA32_TASK_STATE_SEGMENT;
     6769
     6770typedef union {
     6771  struct {
     6772    UINT32  LimitLow:16;    ///< Segment Limit 15..00
     6773    UINT32  BaseLow:16;     ///< Base Address  15..00
     6774    UINT32  BaseMidl:8;     ///< Base Address  23..16
     6775    UINT32  Type:4;         ///< Type (1 0 B 1)
     6776    UINT32  Reserved_43:1;  ///< 0
     6777    UINT32  DPL:2;          ///< Descriptor Privilege Level
     6778    UINT32  P:1;            ///< Segment Present
     6779    UINT32  LimitHigh:4;    ///< Segment Limit 19..16
     6780    UINT32  AVL:1;          ///< Available for use by system software
     6781    UINT32  Reserved_52:2;  ///< 0 0
     6782    UINT32  G:1;            ///< Granularity
     6783    UINT32  BaseMidh:8;     ///< Base Address  31..24
     6784    UINT32  BaseHigh:32;    ///< Base Address  63..32
     6785    UINT32  Reserved_96:32; ///< Reserved
     6786  } Bits;
     6787  struct {
     6788    UINT64  Uint64;
     6789    UINT64  Uint64_1;
     6790  } Uint128;
     6791} IA32_TSS_DESCRIPTOR;
     6792#pragma pack ()
    53866793
    53876794#endif
    … …  
    75999006  );
    76009007
     9008/**
     9009  Generates a 16-bit random number through RDRAND instruction.
     9010
     9011  if Rand is NULL, then ASSERT().
     9012
     9013  @param[out]  Rand     Buffer pointer to store the random result.
     9014
     9015  @retval TRUE          RDRAND call was successful.
     9016  @retval FALSE         Failed attempts to call RDRAND.
     9017
     9018 **/
     9019BOOLEAN
     9020EFIAPI
     9021AsmRdRand16 (
     9022  OUT     UINT16                    *Rand
     9023  );
     9024
     9025/**
     9026  Generates a 32-bit random number through RDRAND instruction.
     9027
     9028  if Rand is NULL, then ASSERT().
     9029
     9030  @param[out]  Rand     Buffer pointer to store the random result.
     9031
     9032  @retval TRUE          RDRAND call was successful.
     9033  @retval FALSE         Failed attempts to call RDRAND.
     9034
     9035**/
     9036BOOLEAN
     9037EFIAPI
     9038AsmRdRand32 (
     9039  OUT     UINT32                    *Rand
     9040  );
     9041
     9042/**
     9043  Generates a 64-bit random number through RDRAND instruction.
     9044
     9045  if Rand is NULL, then ASSERT().
     9046
     9047  @param[out]  Rand     Buffer pointer to store the random result.
     9048
     9049  @retval TRUE          RDRAND call was successful.
     9050  @retval FALSE         Failed attempts to call RDRAND.
     9051
     9052**/
     9053BOOLEAN
     9054EFIAPI
     9055AsmRdRand64  (
     9056  OUT     UINT64                    *Rand
     9057  );
     9058
     9059/**
     9060  Load given selector into TR register.
     9061
     9062  @param[in] Selector     Task segment selector
     9063**/
     9064VOID
     9065EFIAPI
     9066AsmWriteTr (
     9067  IN UINT16 Selector
     9068  );
     9069
     9070/**
     9071  Performs a serializing operation on all load-from-memory instructions that
     9072  were issued prior the AsmLfence function.
     9073
     9074  Executes a LFENCE instruction. This function is only available on IA-32 and x64.
     9075
     9076**/
     9077VOID
     9078EFIAPI
     9079AsmLfence (
     9080  VOID
     9081  );
     9082
    76019083#endif
    76029084#endif
Note: See TracChangeset for help on using the changeset viewer.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette