2 Obsolete library interfaces.
4 This file contains part of obsolete library interfaces in EDK.
5 User is recommended to follow the porting Guide in R8Lib.c to elimante them.
7 Copyright (c) 2006, Intel Corporation
8 All rights reserved. This program and the accompanying materials
9 are licensed and made available under the terms and conditions of the BSD License
10 which accompanies this distribution. The full text of the license may be found at
11 http://opensource.org/licenses/bsd-license.php
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18 ////#UefiBootServicesTableLib
20 R8_EfiLibInstallDriverBinding (
21 IN EFI_HANDLE ImageHandle
,
22 IN EFI_SYSTEM_TABLE
*SystemTable
,
23 IN EFI_DRIVER_BINDING_PROTOCOL
*DriverBinding
,
24 IN EFI_HANDLE DriverBindingHandle
30 Intialize a driver by installing the Driver Binding Protocol onto the
31 driver's DriverBindingHandle. This is typically the same as the driver's
32 ImageHandle, but it can be different if the driver produces multiple
33 DriverBinding Protocols. This function also initializes the EFI Driver
34 Library that initializes the global variables gST, gBS, gRT.
38 ImageHandle - The image handle of the driver.
39 SystemTable - The EFI System Table that was passed to the driver's entry point
40 DriverBinding - A Driver Binding Protocol instance that this driver is producing
41 DriverBindingHandle - The handle that DriverBinding is to be installe onto. If this
42 parameter is NULL, then a new handle is created.
46 EFI_SUCCESS - DriverBinding is installed onto DriverBindingHandle
47 Others - Some error occurs when executing gBS->InstallProtocolInterface()
53 // This obsolete Edk library interface installs driver binding protocol.
54 // If the entry point of that module ONLY invokes this function, it can
55 // use UefiDriverModuleLib in MdePkg and expose "DriverBinding" protocol interface
56 // at the <Externs> tag, build tool will auto generate code to handle it.
60 // <DriverBinding>gFatDriverBinding</DriverBinding>
64 DriverBinding
->ImageHandle
= ImageHandle
;
65 DriverBinding
->DriverBindingHandle
= DriverBindingHandle
;
67 return gBS
->InstallProtocolInterface (
68 &DriverBinding
->DriverBindingHandle
,
69 &gEfiDriverBindingProtocolGuid
,
76 ////#UefiBootServicesTableLib
78 R8_EfiLibInstallAllDriverProtocols (
79 IN EFI_HANDLE ImageHandle
,
80 IN EFI_SYSTEM_TABLE
*SystemTable
,
81 IN EFI_DRIVER_BINDING_PROTOCOL
*DriverBinding
,
82 IN EFI_HANDLE DriverBindingHandle
,
83 IN EFI_COMPONENT_NAME_PROTOCOL
*ComponentName
, OPTIONAL
84 IN EFI_DRIVER_CONFIGURATION_PROTOCOL
*DriverConfiguration
, OPTIONAL
85 IN EFI_DRIVER_DIAGNOSTICS_PROTOCOL
*DriverDiagnostics OPTIONAL
91 Intialize a driver by installing the Driver Binding Protocol onto the
92 driver's DriverBindingHandle. This is typically the same as the driver's
93 ImageHandle, but it can be different if the driver produces multiple
94 DriverBinding Protocols. This function also initializes the EFI Driver
95 Library that initializes the global variables gST, gBS, gRT.
99 ImageHandle - The image handle of the driver
100 SystemTable - The EFI System Table that was passed to the driver's entry point
101 DriverBinding - A Driver Binding Protocol instance that this driver is producing
102 DriverBindingHandle - The handle that DriverBinding is to be installe onto. If this
103 parameter is NULL, then a new handle is created.
104 ComponentName - A Component Name Protocol instance that this driver is producing
105 DriverConfiguration - A Driver Configuration Protocol instance that this driver is producing
106 DriverDiagnostics - A Driver Diagnostics Protocol instance that this driver is producing
110 EFI_SUCCESS - DriverBinding is installed onto DriverBindingHandle
111 Others - Some error occurs when executing gBS->InstallProtocolInterface()
117 // This obsolete Edk library interface installs driver binding protocol
118 // with optional component name, driver configuration & driver diagnotics protocols.
119 // If the entry point of that module ONLY invokes this function, it can
120 // use UefiDriverModuleLib in MdePkg and expose "DriverBinding", "ComponentName",
121 // "DriverConfiguration" and "DriverDiagnostics" protocol interfaces.
122 // at the <Externs> tag, build tool will auto generate code to handle it.
126 // <DriverBinding>gFatDriverBinding</DriverBinding>
129 // <ComponentName>gFatComponentName</ComponentName>
135 DriverBinding
->ImageHandle
= ImageHandle
;
136 DriverBinding
->DriverBindingHandle
= DriverBindingHandle
;
138 Status
= gBS
->InstallProtocolInterface (
139 &DriverBinding
->DriverBindingHandle
,
140 &gEfiDriverBindingProtocolGuid
,
141 EFI_NATIVE_INTERFACE
,
144 if (EFI_ERROR (Status
)) {
148 if (ComponentName
!= NULL
) {
149 Status
= gBS
->InstallProtocolInterface (
150 &DriverBinding
->DriverBindingHandle
,
151 &gEfiComponentNameProtocolGuid
,
152 EFI_NATIVE_INTERFACE
,
155 if (EFI_ERROR (Status
)) {
160 if (DriverConfiguration
!= NULL
) {
161 Status
= gBS
->InstallProtocolInterface (
162 &DriverBinding
->DriverBindingHandle
,
163 &gEfiDriverConfigurationProtocolGuid
,
164 EFI_NATIVE_INTERFACE
,
167 if (EFI_ERROR (Status
)) {
172 if (DriverDiagnostics
!= NULL
) {
173 Status
= gBS
->InstallProtocolInterface (
174 &DriverBinding
->DriverBindingHandle
,
175 &gEfiDriverDiagnosticsProtocolGuid
,
176 EFI_NATIVE_INTERFACE
,
179 if (EFI_ERROR (Status
)) {
190 R8_EfiLibCompareLanguage (
198 Compare whether two names of languages are identical.
202 Language1 - Name of language 1
203 Language2 - Name of language 2
214 // This library interface is simply obsolete.
215 // Include the source code to user code.
219 for (Index
= 0; Index
< 3; Index
++) {
220 if (Language1
[Index
] != Language2
[Index
]) {
233 IN OUT UINTN
*HexStringBufferLength
,
240 Converts binary buffer to Unicode string.
241 At a minimum, any blob of data could be represented as a hex string.
244 Str - Pointer to the string.
245 HexStringBufferLength - Length in bytes of buffer to hold the hex string. Includes tailing '\0' character.
246 If routine return with EFI_SUCCESS, containing length of hex string buffer.
247 If routine return with EFI_BUFFER_TOO_SMALL, containg length of hex string buffer desired.
248 Buf - Buffer to be converted from.
249 Len - Length in bytes of the buffer to be converted.
252 EFI_SUCCESS - Routine success.
253 EFI_BUFFER_TOO_SMALL - The hex string buffer is too small.
259 // This library interface is simply obsolete.
260 // Include the source code to user code.
267 // Make sure string is either passed or allocate enough.
268 // It takes 2 Unicode characters (4 bytes) to represent 1 byte of the binary buffer.
269 // Plus the Unicode termination character.
272 if (StrLen
> ((*HexStringBufferLength
) - 1)) {
273 *HexStringBufferLength
= StrLen
+ 1;
274 return EFI_BUFFER_TOO_SMALL
;
277 *HexStringBufferLength
= StrLen
+ 1;
283 for (Idx
= 0; Idx
< Len
; Idx
++) {
286 Str
[StrLen
- 1 - Idx
* 2] = NibbleToHexChar (Byte
);
287 Str
[StrLen
- 2 - Idx
* 2] = NibbleToHexChar ((UINT8
)(Byte
>> 4));
304 Removes (trims) specified leading and trailing characters from a string.
308 str - Pointer to the null-terminated string to be trimmed. On return,
309 str will hold the trimmed string.
310 CharC - Character will be trimmed from str.
316 // This library interface is simply obsolete.
317 // Include the source code to user code.
327 // Trim off the leading and trailing characters c
329 for (p1
= str
; *p1
&& *p1
== CharC
; p1
++) {
349 for (p1
= str
+ StrLen(str
) - 1; p1
>= str
&& *p1
== CharC
; p1
--) {
352 if (p1
!= str
+ StrLen(str
) - 1) {
360 R8_EfiValueToHexStr (
361 IN OUT CHAR16
*Buffer
,
370 VSPrint worker function that prints a Value as a hex number in Buffer
374 Buffer - Location to place ascii hex string of Value.
375 Value - Hex value to convert to a string in Buffer.
376 Flags - Flags to use in printing Hex string, see file header for details.
377 Width - Width of hex value.
381 Number of characters printed.
387 // Edk II BasePrintLib function UnicodeValueToString does not support
388 // to convert Value to Hex String.
389 // Include the source code to user code or use the full PrintLib funtion
390 // UnicodeVSPrintAsciiFormat (Buffer, MAXIMUM_VALUE_CHARACTERS, "%x", Value) instead.
393 CHAR16 TempBuffer
[MAXIMUM_VALUE_CHARACTERS
];
400 TempStr
= TempBuffer
;
404 // Count starts at one since we will null terminate. Each iteration of the
405 // loop picks off one nibble. Oh yea TempStr ends up backwards
409 if (Width
> MAXIMUM_VALUE_CHARACTERS
- 1) {
410 Width
= MAXIMUM_VALUE_CHARACTERS
- 1;
415 // If Width == 0, it means no limit.
417 if ((Width
!= 0) && (Count
>= Width
)) {
421 Index
= ((UINTN
)Value
& 0xf);
422 *(TempStr
++) = mHexStr
[Index
];
423 Value
= RShiftU64 (Value
, 4);
425 } while (Value
!= 0);
427 if (Flags
& PREFIX_ZERO
) {
434 if (!(Flags
& LEFT_JUSTIFY
)) {
435 for (; Index
< Width
; Index
++) {
436 *(TempStr
++) = Prefix
;
441 // Reverse temp string into Buffer.
443 while (TempStr
!= TempBuffer
) {
444 *(BufferPtr
++) = *(--TempStr
);
460 OUT UINTN
*ConvertedStrLen OPTIONAL
465 Converts Unicode string to binary buffer.
466 The conversion may be partial.
467 The first character in the string that is not hex digit stops the conversion.
468 At a minimum, any blob of data could be represented as a hex string.
471 Buf - Pointer to buffer that receives the data.
472 Len - Length in bytes of the buffer to hold converted data.
473 If routine return with EFI_SUCCESS, containing length of converted data.
474 If routine return with EFI_BUFFER_TOO_SMALL, containg length of buffer desired.
475 Str - String to be converted from.
476 ConvertedStrLen - Length of the Hex String consumed.
479 EFI_SUCCESS - Routine Success.
480 EFI_BUFFER_TOO_SMALL - The buffer is too small to hold converted data.
486 // This library interface is simply obsolete.
487 // Include the source code to user code.
497 // Find out how many hex characters the string has.
499 for (Idx
= 0, HexCnt
= 0; IsHexDigit (&Digit
, Str
[Idx
]); Idx
++, HexCnt
++);
506 // Two Unicode characters make up 1 buffer byte. Round up.
508 BufferLength
= (HexCnt
+ 1) / 2;
511 // Test if buffer is passed enough.
513 if (BufferLength
> (*Len
)) {
515 return EFI_BUFFER_TOO_SMALL
;
520 for (Idx
= 0; Idx
< HexCnt
; Idx
++) {
522 IsHexDigit (&Digit
, Str
[HexCnt
- 1 - Idx
]);
525 // For odd charaters, write the lower nibble for each buffer byte,
526 // and for even characters, the upper nibble.
528 if ((Idx
& 1) == 0) {
539 if (ConvertedStrLen
!= NULL
) {
540 *ConvertedStrLen
= HexCnt
;
556 Determines if a Unicode character is a hexadecimal digit.
557 The test is case insensitive.
560 Digit - Pointer to byte that receives the value of the hex character.
561 Char - Unicode character to test.
564 TRUE - If the character is a hexadecimal digit.
571 // This library interface is simply obsolete.
572 // Include the source code to user code.
575 if ((Char
>= L
'0') && (Char
<= L
'9')) {
576 *Digit
= (UINT8
) (Char
- L
'0');
580 if ((Char
>= L
'A') && (Char
<= L
'F')) {
581 *Digit
= (UINT8
) (Char
- L
'A' + 0x0A);
585 if ((Char
>= L
'a') && (Char
<= L
'f')) {
586 *Digit
= (UINT8
) (Char
- L
'a' + 0x0A);
602 Converts the low nibble of a byte to hex unicode character.
605 Nibble - lower nibble of a byte.
608 Hex unicode character.
614 // This library interface is simply obsolete.
615 // Include the source code to user code.
620 return (CHAR16
)(Nibble
+ L
'0');
623 return (CHAR16
)(Nibble
- 0xA + L
'A');
637 This function returns the first instance of a HOB type in a HOB list.
641 Type - The HOB type to return.
642 HobStart - The first HOB in the HOB list.
646 HobStart - There were no HOBs found with the requested type.
647 Other - The first HOB with the matching type.
653 // Edk II HobLib GetNextHob () is an equivelent function with the following exceptions:
654 // 1. GetNextHob () does not allow NULL value as the argument of HobStart by ASSERT ()
655 // 2. GetNextHob () will return NULL instead of returning HobStart when such kind of
656 // HOB can be retrieved, so caller does not need to re-check the return HOB type any longer.
661 // Return input if not found
663 if (HobStart
== NULL
) {
666 Hob
= GetNextHob (Type
, HobStart
);
684 Get size of hob list.
688 HobStart - Start pointer of hob list
698 // This library interface is simply obsolete.
699 // Include the source code to user code.
701 EFI_PEI_HOB_POINTERS Hob
;
707 while (Hob
.Header
->HobType
!= EFI_HOB_TYPE_END_OF_HOB_LIST
) {
708 Size
+= Hob
.Header
->HobLength
;
709 Hob
.Raw
+= Hob
.Header
->HobLength
;
712 Size
+= Hob
.Header
->HobLength
;
731 HobStart - Start pointer of hob list
741 // This library interface is simply obsolete.
742 // Include the source code to user code.
745 EFI_PEI_HOB_POINTERS Hob
;
748 return Hob
.HandoffInformationTable
->Version
;
756 OUT EFI_BOOT_MODE
*BootMode
762 Get current boot mode.
766 HobStart - Start pointer of hob list
767 BootMode - Current boot mode recorded in PHIT hob
771 EFI_NOT_FOUND - Invalid hob header
772 EFI_SUCCESS - Boot mode found
778 // This library interface is simply obsolete.
779 // Include the source code to user code.
780 // In fact, since EFI_HANDOFF_HOB must be the first Hob,
781 // the following code can retrieve boot mode.
783 // EFI_HOB_HANDOFF_INFO_TABLE *HandOffHob;
785 // HandOffHob = GetHobList ();
786 // ASSERT (HandOffHob->Header.HobType == EFI_HOB_TYPE_HANDOFF);
788 // BootMode = HandOffHob->BootMode;
790 EFI_PEI_HOB_POINTERS Hob
;
793 if (Hob
.Header
->HobType
!= EFI_HOB_TYPE_HANDOFF
) {
794 return EFI_NOT_FOUND
;
797 *BootMode
= Hob
.HandoffInformationTable
->BootMode
;
807 OUT UINT8
*SizeOfMemorySpace
,
808 OUT UINT8
*SizeOfIoSpace
814 Get information recorded in CPU hob (Memory space size, Io space size)
818 HobStart - Start pointer of hob list
819 SizeOfMemorySpace - Size of memory size
820 SizeOfIoSpace - Size of IO size
824 EFI_NOT_FOUND - CPU hob not found
825 EFI_SUCCESS - CPU hob found and information got.
831 // This library interface is simply obsolete.
832 // Include the source code to user code.
833 // If Cpu HOB info is indispensable, user is able to ASSERT ()
834 // first to save error handling code
837 // EFI_HOB_CPU *CpuHob;
839 // CpuHob = GetHob (EFI_HOB_TYPE_CPU, HobStart);
840 // ASSERT (CpuHob != NULL);
846 CpuHob
= GetHob (EFI_HOB_TYPE_CPU
, HobStart
);
847 if (CpuHob
== NULL
) {
848 return EFI_NOT_FOUND
;
851 *SizeOfMemorySpace
= CpuHob
->SizeOfMemorySpace
;
852 *SizeOfIoSpace
= CpuHob
->SizeOfIoSpace
;
859 R8_GetDxeCoreHobInfo (
861 OUT EFI_PHYSICAL_ADDRESS
*BaseAddress
,
863 OUT VOID
**EntryPoint
,
864 OUT EFI_GUID
**FileName
870 Get memory allocation hob created for DXE core and extract its information
874 HobStart - Start pointer of the hob list
875 BaseAddress - Start address of memory allocated for DXE core
876 Length - Length of memory allocated for DXE core
877 EntryPoint - DXE core file name
882 EFI_NOT_FOUND - DxeCoreHob not found
883 EFI_SUCCESS - DxeCoreHob found and information got
889 // This library interface is simply obsolete.
890 // Include the source code to user code.
892 EFI_PEI_HOB_POINTERS DxeCoreHob
;
894 for (DxeCoreHob
.Raw
= HobStart
;
895 (DxeCoreHob
.Raw
= GetNextHob (EFI_HOB_TYPE_MEMORY_ALLOCATION
, DxeCoreHob
.Raw
)) != NULL
;
896 DxeCoreHob
.Raw
= GET_NEXT_HOB (DxeCoreHob
)) {
897 if (CompareGuid (&DxeCoreHob
.MemoryAllocationModule
->MemoryAllocationHeader
.Name
,
898 &gEfiHobMemeryAllocModuleGuid
)) {
899 *BaseAddress
= DxeCoreHob
.MemoryAllocationModule
->MemoryAllocationHeader
.MemoryBaseAddress
;
900 *Length
= DxeCoreHob
.MemoryAllocationModule
->MemoryAllocationHeader
.MemoryLength
;
901 *EntryPoint
= (VOID
*) (UINTN
) DxeCoreHob
.MemoryAllocationModule
->EntryPoint
;
902 *FileName
= &DxeCoreHob
.MemoryAllocationModule
->ModuleName
;
907 return EFI_NOT_FOUND
;
913 R8_GetNextFirmwareVolumeHob (
914 IN OUT VOID
**HobStart
,
915 OUT EFI_PHYSICAL_ADDRESS
*BaseAddress
,
922 Get next firmware volume hob from HobStart
926 HobStart - Start pointer of hob list
927 BaseAddress - Start address of next firmware volume
928 Length - Length of next firmware volume
932 EFI_NOT_FOUND - Next firmware volume not found
933 EFI_SUCCESS - Next firmware volume found with address information
939 // This library interface is simply obsolete.
940 // Include the source code to user code.
941 // Pay attention that caller is REQUIRED to update HobStart with:
942 // *HobStart = GET_NEXT_HOB (FirmwareVolumeHob)
944 // If FV HOB info is indispensable, user is able to ASSERT ()
945 // first to save error handling code
948 // EFI_HOB_FIRMWARE_VOLUME *FirmwareVolumeHob;
950 // FirmwareVolumeHob = GetHob (EFI_HOB_TYPE_FV, HobStart);
951 // ASSERT (FirmwareVolumeHob != NULL);
956 EFI_PEI_HOB_POINTERS FirmwareVolumeHob
;
958 FirmwareVolumeHob
.Raw
= GetNextHob (EFI_HOB_TYPE_FV
, *HobStart
);
959 if (FirmwareVolumeHob
.Raw
!= NULL
) {
960 return EFI_NOT_FOUND
;
963 *BaseAddress
= FirmwareVolumeHob
.FirmwareVolume
->BaseAddress
;
964 *Length
= FirmwareVolumeHob
.FirmwareVolume
->Length
;
966 *HobStart
= GET_NEXT_HOB (FirmwareVolumeHob
);
975 IN OUT VOID
**HobStart
,
978 OUT UINTN
*BufferSize OPTIONAL
983 Get the next guid hob.
986 HobStart - A pointer to the start hob.
987 Guid - A pointer to a guid.
988 Buffer - A pointer to the buffer.
989 BufferSize - Buffer size.
992 EFI_NOT_FOUND - Next Guid hob not found
993 EFI_SUCCESS - Next Guid hob found and data for this Guid got
994 EFI_INVALID_PARAMETER - invalid parameter
1000 // This library interface is changed substantially with R9 counerpart GetNextGuidHob ().
1001 // 1. R9 GetNextGuidHob has two parameters and returns the matched GUID HOB from the StartHob.
1002 // 2. R9 GetNextGuidHob does not strip the HOB header, so caller is required to apply
1003 // GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () to extract the data section and its
1004 // size info respectively.
1005 // 3. this function does not skip the starting HOB pointer unconditionally:
1006 // it returns HobStart back if HobStart itself meets the requirement;
1007 // caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
1009 EFI_PEI_HOB_POINTERS GuidHob
;
1011 if (Buffer
== NULL
) {
1012 return EFI_INVALID_PARAMETER
;
1015 GuidHob
.Raw
= GetNextGuidHob (Guid
, *HobStart
);
1016 if (GuidHob
.Raw
== NULL
) {
1017 return EFI_NOT_FOUND
;
1020 *Buffer
= GET_GUID_HOB_DATA (GuidHob
.Guid
);
1021 if (BufferSize
!= NULL
) {
1022 *BufferSize
= GET_GUID_HOB_DATA_SIZE (GuidHob
.Guid
);
1025 *HobStart
= GET_NEXT_HOB (GuidHob
);
1033 R8_GetPalEntryHobInfo (
1035 OUT EFI_PHYSICAL_ADDRESS
*PalEntry
1039 Routine Description:
1041 Get PAL entry from PalEntryHob
1045 HobStart - Start pointer of hob list
1046 PalEntry - Pointer to PAL entry
1054 EFI_HOB_GUID_TYPE
*GuidHob
;
1056 GuidHob
= GetNextGuidHob (&gPalEntryHob
, HobStart
);
1058 if (GuidHob
== NULL
) {
1059 return EFI_NOT_FOUND
;
1062 *PalEntry
= *((EFI_PHYSICAL_ADDRESS
*) GET_GUID_HOB_DATA (GuidHob
));
1069 R8_GetIoPortSpaceAddressHobInfo (
1071 OUT EFI_PHYSICAL_ADDRESS
*IoPortSpaceAddress
1075 Routine Description:
1077 Get IO port space address from IoBaseHob.
1081 HobStart - Start pointer of hob list
1082 IoPortSpaceAddress - IO port space address
1092 // This library interface is simply obsolete.
1093 // Include the source code to user code.
1095 EFI_HOB_GUID_TYPE
*GuidHob
;
1097 GuidHob
= GetNextGuidHob (&gEfiIoBaseHobGuid
, HobStart
);
1099 if (GuidHob
== NULL
) {
1100 return EFI_NOT_FOUND
;
1103 *IoPortSpaceAddress
= *((EFI_PHYSICAL_ADDRESS
*) GET_GUID_HOB_DATA (GuidHob
));
1110 R8_PeiBuildHobGuid (
1112 IN UINTN DataLength
,
1117 Routine Description:
1119 Builds a custom HOB that is tagged with a GUID for identification
1123 Guid - The GUID of the custome HOB type
1124 DataLength - The size of the data payload for the GUIDed HOB
1125 Hob - Pointer to pointer to the created Hob
1129 EFI_SUCCESS - Hob is successfully built.
1130 Others - Errors occur while creating new Hob
1135 // Porting Guide: Apply the new interface of BuildGuidHob in R9 HobLib.
1136 // Pay attention that the return value has been changed to the start address of
1137 // GUID HOB data so that caller can fill the customized data.
1138 // For BuildGuidHob (), the HOB Header and Name field is already stripped..
1142 HobData
= BuildGuidHob (Guid
, DataLength
);
1144 // This step is necessary to be compatible with R8 interface!
1146 *Hob
= (VOID
*) ((UINT8
*) HobData
- sizeof (EFI_HOB_GUID_TYPE
));