3 Copyright (c) 2004 - 2007, Intel Corporation. All rights reserved.<BR>
4 This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18 Light weight lib to support EFI drivers.
22 #ifndef _EFI_COMMON_LIB_H_
23 #define _EFI_COMMON_LIB_H_
26 EfiLibGetSystemConfigurationTable (
27 IN EFI_GUID
*TableGuid
,
34 Return the EFI 1.0 System Tabl entry with TableGuid
38 TableGuid - Name of entry to return in the system table
39 Table - Pointer in EFI system table associated with TableGuid
43 EFI_SUCCESS - Table returned;
44 EFI_NOT_FOUND - TableGuid not in EFI system table
50 // ASPrint and AvSPrint definitions you must include the specific library
51 // to get the expected behavior from the two functions
53 // Graphics: Dxe\Graphics\Unicode Dxe\Graphics\ASCII
54 // ASCII: Dxe\Print\ASCII
55 // Unicode: Dxe\Print\Unicode
61 IN CONST CHAR8
*Format
,
68 Process format and place the results in Buffer for narrow chars.
72 Buffer - Narrow char buffer to print the results of the parsing of Format into.
73 BufferSize - Maximum number of characters to put into buffer.
74 Format - Format string
75 ... - Vararg list consumed by processing Format.
79 Number of characters printed.
86 OUT CHAR8
*StartOfBuffer
,
88 IN CONST CHAR8
*Format
,
95 Internal implementation of ASPrint.
96 Process format and place the results in Buffer for narrow chars.
100 StartOfBuffer - Narrow char buffer to print the results of the parsing of Format into.
101 StrSize - Maximum number of characters to put into buffer.
102 FormatString - Format string
103 Marker - Vararg list consumed by processing Format.
107 Number of characters printed.
113 // Lib functions which can be used in both PEI and DXE pahse
116 EfiInitializeCommonDriverLib (
117 IN EFI_HANDLE ImageHandle
,
124 Initialize lib function calling phase: PEI or DXE
128 ImageHandle - The firmware allocated handle for the EFI image.
130 SystemTable - A pointer to the EFI System Table.
134 EFI_STATUS always returns EFI_SUCCESS
154 Width - Width of read operation
155 Address - Start IO address to read
157 Buffer - Buffer to store result
181 Width - Width of write operation
182 Address - Start IO address to write
184 Buffer - Buffer to write to the address
208 Width - Width of PCI read
209 Address - PCI address to read
211 Buffer - Output buffer for the read
235 Width - Width of PCI write
236 Address - PCI address to write
238 Buffer - Buffer to write to the address
260 Guid1 - guid to compare
262 Guid2 - guid to compare
265 TRUE if Guid1 == Guid2
266 FALSE if Guid1 != Guid2
281 Set Buffer to Value for Size bytes.
285 Buffer - Memory to set.
287 Size - Number of bytes to set
289 Value - Value of the set operation.
299 EfiCommonLibCopyMem (
300 IN VOID
*Destination
,
308 Copy Length bytes from Source to Destination.
312 Destination - Target of copy
314 Source - Place to copy from
316 Length - Number of bytes to copy
335 Compares two memory buffers of a given length.
339 MemOne - First memory buffer
341 MemTwo - Second memory buffer
343 Len - Length of Mem1 and Mem2 memory regions to compare
347 = 0 if MemOne == MemTwo
349 > 0 if MemOne > MemTwo
351 < 0 if MemOne < MemTwo
357 EfiCommonLibZeroMem (
365 Set Buffer to 0 for Size bytes.
369 Buffer - Memory to set.
371 Size - Number of bytes to set
383 #define EFI_MIN(a, b) (((a) < (b)) ? (a) : (b))
384 #define EFI_MAX(a, b) (((a) > (b)) ? (a) : (b))
387 // Align a pointer. The pointer represented by ptr is aligned to the bound.
388 // The resulting pointer is always equal or greater (by no more than bound-1)
389 // than the ptr. I.e., if the ptr is already aligned, the result will be equal to ptr.
390 // Valid values for bound are powers of two: 2, 4, 8, 16, 32 etc.
391 // The returned pointer is VOID* this assignment-compatible with all pointer types.
393 #define EFI_ALIGN(ptr, bound) ((VOID *) (((UINTN) (ptr) + ((UINTN) (bound) - 1)) &~((UINTN) (bound) - 1)))
398 #define EFI_UINTN_ALIGN_MASK (sizeof (UINTN) - 1)
399 #define EFI_UINTN_ALIGNED(ptr) (((UINTN) (ptr)) & EFI_UINTN_ALIGN_MASK)
402 // Integer division with rounding to the nearest rather than truncating.
403 // For example 8/3=2 but EFI_IDIV_ROUND(8,3)=3. 1/3=0 and EFI_IDIV_ROUND(1,3)=0.
404 // A half is rounded up e.g., EFI_IDIV_ROUND(1,2)=1 but 1/2=0.
406 #define EFI_IDIV_ROUND(r, s) ((r) / (s) + (((2 * ((r) % (s))) < (s)) ? 0 : 1))
409 // ReportStatusCode.c init
412 EfiConstructStatusCodeData (
414 IN EFI_GUID
*TypeGuid
,
415 IN OUT EFI_STATUS_CODE_DATA
*Data
421 Construct stanader header for optional data passed into ReportStatusCode
425 DataSize - Size of optional data. Does not include EFI_STATUS_CODE_DATA header
426 TypeGuid - GUID to place in EFI_STATUS_CODE_DATA
427 Data - Buffer to use.
431 Return pointer to Data buffer pointing past the end of EFI_STATUS_CODE_DATA
437 EfiDebugVPrintWorker (
448 Worker function for DEBUG(). If Error Logging hub is loaded log ASSERT
449 information. If Error Logging hub is not loaded do nothing.
451 We use UINT64 buffers due to IPF alignment concerns.
455 ErrorLevel - If error level is set do the debug print.
457 Format - String to use for the print, followed by Print arguments.
461 BufferSize - Size of Buffer.
463 Buffer - Caller allocated buffer, contains ReportStatusCode extended data
473 EfiDebugAssertWorker (
476 IN CHAR8
*Description
,
484 Worker function for ASSERT (). If Error Logging hub is loaded log ASSERT
485 information. If Error Logging hub is not loaded DEADLOOP ().
487 We use UINT64 buffers due to IPF alignment concerns.
491 FileName - File name of failing routine.
493 LineNumber - Line number of failing ASSERT().
495 Description - Description, usually the assertion,
497 BufferSize - Size of Buffer.
499 Buffer - Caller allocated buffer, contains ReportStatusCode extendecd data
509 ReportStatusCodeExtractAssertInfo (
510 IN EFI_STATUS_CODE_TYPE CodeType
,
511 IN EFI_STATUS_CODE_VALUE Value
,
512 IN EFI_STATUS_CODE_DATA
*Data
,
513 OUT CHAR8
**Filename
,
514 OUT CHAR8
**Description
,
515 OUT UINT32
*LineNumber
521 Extract assert information from status code data.
527 Data - Optional data associated with this status code.
528 Filename - Filename extracted from Data
529 Description - Description extracted from Data
530 LineNumber - Line number extracted from Data
534 TRUE - Successfully extracted
536 FALSE - Extraction failed
542 ReportStatusCodeExtractDebugInfo (
543 IN EFI_STATUS_CODE_DATA
*Data
,
544 OUT UINT32
*ErrorLevel
,
552 Extract debug information from status code data.
556 Data - Optional data associated with status code.
557 ErrorLevel - Error level extracted from Data
558 Marker - VA_LIST extracted from Data
559 Format - Format string extracted from Data
563 TRUE - Successfully extracted
565 FALSE - Extraction failed
572 IN EFI_STATUS_CODE_TYPE CodeType
,
573 IN EFI_STATUS_CODE_VALUE Value
,
580 Convert code value to an 8 bit post code
586 PostCode - Post code as output
590 TRUE - Successfully converted
592 FALSE - Convertion failed
602 IN UINT64 Multiplicand
,
609 This routine allows a 64 bit value to be multiplied with a 32 bit
610 value returns 64bit result.
611 No checking if the result is greater than 64bits
615 Multiplicand - multiplicand
616 Multiplier - multiplier
620 Multiplicand * Multiplier
629 OUT UINTN
*Remainder OPTIONAL
635 This routine allows a 64 bit value to be divided with a 32 bit value returns
636 64bit result and the Remainder.
642 Remainder - buffer for remainder
647 Remainder = Dividend mod Divisor
661 This routine allows a 64 bit value to be right shifted by 32 bits and returns the
663 Count is valid up 63. (Only Bits 0-5 is valid for Count)
667 Operand - Value to be shifted
668 Count - Number of times to shift right.
672 Value shifted right identified by the Count.
686 This routine allows a 64 bit value to be left shifted by 32 bits and
687 returns the shifted value.
688 Count is valid up 63. (Only Bits 0-5 is valid for Count)
692 Operand - Value to be shifted
693 Count - Number of times to shift left.
697 Value shifted left identified by the Count.
711 Raise 10 to the power of Power, and multiply the result with Operand
715 Operand - multiplicand
733 Calculates and floors logarithms based on 2
737 Operand - value to calculate logarithm
741 The largest integer that is less than or equal
742 to the logarithm of Operand based on 2
755 Calculates the largest integer that is both
756 a power of two and less than Input
760 Input - value to calculate power of two
764 the largest integer that is both a power of
765 two and less than Input
771 // Unicode String primatives
775 IN CHAR16
*Destination
,
781 Copy the Unicode string Source to Destination.
784 Destination - Location to copy string
785 Source - String to copy
802 Copy a string from source to destination
805 Dst Destination string
807 Length Length of destination string
821 Return the number of Unicode characters in String. This is not the same as
822 the length of the string in bytes.
825 String - String to process
828 Number of Unicode characters in String
840 Return the number bytes in the Unicode String. This is not the same as
841 the length of the string in characters. The string size includes the NULL
844 String - String to process
847 Number of bytes in String
860 Return the alphabetic relationship between two stirngs.
863 String - Compare to String2
865 String2 - Compare to String
870 > 0 - String is alphabeticly greater than String2
872 < 0 - String is alphabeticly less than String2
886 This function compares the Unicode string String to the Unicode
887 string String2 for len characters. If the first len characters
888 of String is identical to the first len characters of String2,
889 then 0 is returned. If substring of String sorts lexicographically
890 after String2, the function returns a number greater than 0. If
891 substring of String sorts lexicographically before String2, the
892 function returns a number less than 0.
895 String - Compare to String2
896 String2 - Compare to String
897 Length - Number of Unicode characters to compare
900 0 - The substring of String and String2 is identical.
901 > 0 - The substring of String sorts lexicographically after String2
902 < 0 - The substring of String sorts lexicographically before String2
909 IN CHAR16
*Destination
,
915 Concatinate Source on the end of Destination
918 Destination - String to added to the end of.
919 Source - String to concatinate.
936 Concatinate Source on the end of Destination
939 Dst Destination string
941 Length Length of destination string
955 Return the number of Ascii characters in String. This is not the same as
956 the length of the string in bytes.
959 String - String to process
962 Number of Unicode characters in String
969 IN CHAR8
*Destination
,
975 Copy the Ascii string Source to Destination.
978 Destination - Location to copy string
979 Source - String to copy
982 Pointer just pass the end of Destination
996 Copy the Ascii string from source to destination
999 Dst Destination string
1001 Length Length of destination string
1014 Routine Description:
1015 Return the number bytes in the Ascii String. This is not the same as
1016 the length of the string in characters. The string size includes the NULL
1019 String - String to process
1022 Number of bytes in String
1035 Routine Description:
1036 Compare the Ascii string pointed by String to the string pointed by String2.
1039 String - String to process
1041 String2 - The other string to process
1044 Return a positive integer if String is lexicall greater than String2; Zero if
1045 the two strings are identical; and a negative interger if String is lexically
1058 Routine Description:
1059 This function compares the ASCII string String to the ASCII
1060 string String2 for len characters. If the first len characters
1061 of String is identical to the first len characters of String2,
1062 then 0 is returned. If substring of String sorts lexicographically
1063 after String2, the function returns a number greater than 0. If
1064 substring of String sorts lexicographically before String2, the
1065 function returns a number less than 0.
1068 String - Compare to String2
1069 String2 - Compare to String
1070 Length - Number of ASCII characters to compare
1073 0 - The substring of String and String2 is identical.
1074 > 0 - The substring of String sorts lexicographically after String2
1075 < 0 - The substring of String sorts lexicographically before String2
1082 IN CHAR8
*Destination
,
1087 Routine Description:
1088 Concatinate Source on the end of Destination
1091 Destination - String to added to the end of.
1092 Source - String to concatinate.
1102 IN CHAR8
*Destination
,
1108 Routine Description:
1109 Concatinate Source on the end of Destination
1112 Destination - String to added to the end of.
1113 Source - String to concatinate.
1124 #define LEFT_JUSTIFY 0x01
1125 #define PREFIX_SIGN 0x02
1126 #define PREFIX_BLANK 0x04
1127 #define COMMA_TYPE 0x08
1128 #define LONG_TYPE 0x10
1129 #define PREFIX_ZERO 0x20
1132 // Length of temp string buffer to store value string.
1134 #define CHARACTER_NUMBER_FOR_VALUE 30
1138 IN OUT CHAR16
*Buffer
,
1145 Routine Description:
1147 VSPrint worker function that prints a Value as a hex number in Buffer
1151 Buffer - Location to place ascii hex string of Value.
1153 Value - Hex value to convert to a string in Buffer.
1155 Flags - Flags to use in printing Hex string, see file header for details.
1157 Width - Width of hex value.
1161 Number of characters printed.
1168 IN OUT CHAR16
*Buffer
,
1175 Routine Description:
1177 VSPrint worker function that prints a Value as a decimal number in Buffer
1181 Buffer - Location to place ascii decimal number string of Value.
1183 Value - Decimal value to convert to a string in Buffer.
1185 Flags - Flags to use in printing decimal string, see file header for details.
1187 Width - Width of hex value.
1191 Number of characters printed.
1203 Routine Description:
1204 Determines if a Unicode character is a hexadecimal digit.
1205 The test is case insensitive.
1208 Digit - Pointer to byte that receives the value of the hex character.
1209 Char - Unicode character to test.
1212 TRUE - If the character is a hexadecimal digit.
1224 Routine Description:
1225 Converts the low nibble of a byte to hex unicode character.
1228 Nibble - lower nibble of a byte.
1231 Hex unicode character.
1241 OUT UINTN
*ConvertedStrLen OPTIONAL
1245 Routine Description:
1246 Converts Unicode string to binary buffer.
1247 The conversion may be partial.
1248 The first character in the string that is not hex digit stops the conversion.
1249 At a minimum, any blob of data could be represented as a hex string.
1252 Buf - Pointer to buffer that receives the data.
1253 Len - Length in bytes of the buffer to hold converted data.
1254 If routine return with EFI_SUCCESS, containing length of converted data.
1255 If routine return with EFI_BUFFER_TOO_SMALL, containg length of buffer desired.
1256 Str - String to be converted from.
1257 ConvertedStrLen - Length of the Hex String consumed.
1260 EFI_SUCCESS: Routine Success.
1261 EFI_BUFFER_TOO_SMALL: The buffer is too small to hold converted data.
1270 IN OUT UINTN
*HexStringBufferLength
,
1276 Routine Description:
1277 Converts binary buffer to Unicode string.
1278 At a minimum, any blob of data could be represented as a hex string.
1281 Str - Pointer to the string.
1282 HexStringBufferLength - Length in bytes of buffer to hold the hex string. Includes tailing '\0' character.
1283 If routine return with EFI_SUCCESS, containing length of hex string buffer.
1284 If routine return with EFI_BUFFER_TOO_SMALL, containg length of hex string buffer desired.
1285 Buf - Buffer to be converted from.
1286 Len - Length in bytes of the buffer to be converted.
1289 EFI_SUCCESS: Routine success.
1290 EFI_BUFFER_TOO_SMALL: The hex string buffer is too small.
1302 Routine Description:
1304 Removes (trims) specified leading and trailing characters from a string.
1308 str - Pointer to the null-terminated string to be trimmed. On return,
1309 str will hold the trimmed string.
1310 CharC - Character will be trimmed from str.
1321 IN CHAR16
*StrCharSet
1325 Routine Description:
1331 String - Null-terminated string to search.
1332 StrCharSet - Null-terminated string to search for.
1335 The address of the first occurrence of the matching substring if successful, or NULL otherwise.
1342 IN CHAR8
*StrCharSet
1346 Routine Description:
1348 Find a Ascii substring.
1352 String - Null-terminated Ascii string to search.
1353 StrCharSet - Null-terminated Ascii string to search for.
1356 The address of the first occurrence of the matching Ascii substring if successful, or NULL otherwise.