2 The UEFI Library provides functions and macros that simplify the development of
3 UEFI Drivers and UEFI Applications. These functions and macros help manage EFI
4 events, build simple locks utilizing EFI Task Priority Levels (TPLs), install
5 EFI Driver Model related protocols, manage Unicode string tables for UEFI Drivers,
6 and print messages on the console output and standard error devices.
8 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
9 SPDX-License-Identifier: BSD-2-Clause-Patent
14 #include "UefiLibInternal.h"
17 Empty constructor function that is required to resolve dependencies between
22 @param ImageHandle The firmware allocated handle for the EFI image.
23 @param SystemTable A pointer to the EFI System Table.
25 @retval EFI_SUCCESS The constructor executed correctly.
31 IN EFI_HANDLE ImageHandle
,
32 IN EFI_SYSTEM_TABLE
*SystemTable
39 Compare whether two names of languages are identical.
41 @param Language1 Name of language 1.
42 @param Language2 Name of language 2.
44 @retval TRUE Language 1 and language 2 are the same.
45 @retval FALSE Language 1 and language 2 are not the same.
49 CompareIso639LanguageCode (
50 IN CONST CHAR8
*Language1
,
51 IN CONST CHAR8
*Language2
57 Name1
= ReadUnaligned24 ((CONST UINT32
*) Language1
);
58 Name2
= ReadUnaligned24 ((CONST UINT32
*) Language2
);
60 return (BOOLEAN
) (Name1
== Name2
);
64 Retrieves a pointer to the system configuration table from the EFI System Table
65 based on a specified GUID.
67 This function searches the list of configuration tables stored in the EFI System Table
68 for a table with a GUID that matches TableGuid. If a match is found, then a pointer to
69 the configuration table is returned in Table., and EFI_SUCCESS is returned. If a matching GUID
70 is not found, then EFI_NOT_FOUND is returned.
71 If TableGuid is NULL, then ASSERT().
72 If Table is NULL, then ASSERT().
74 @param TableGuid The pointer to table's GUID type.
75 @param Table The pointer to the table associated with TableGuid in the EFI System Table.
77 @retval EFI_SUCCESS A configuration table matching TableGuid was found.
78 @retval EFI_NOT_FOUND A configuration table matching TableGuid could not be found.
83 EfiGetSystemConfigurationTable (
84 IN EFI_GUID
*TableGuid
,
88 EFI_SYSTEM_TABLE
*SystemTable
;
91 ASSERT (TableGuid
!= NULL
);
92 ASSERT (Table
!= NULL
);
96 for (Index
= 0; Index
< SystemTable
->NumberOfTableEntries
; Index
++) {
97 if (CompareGuid (TableGuid
, &(SystemTable
->ConfigurationTable
[Index
].VendorGuid
))) {
98 *Table
= SystemTable
->ConfigurationTable
[Index
].VendorTable
;
103 return EFI_NOT_FOUND
;
107 Creates and returns a notification event and registers that event with all the protocol
108 instances specified by ProtocolGuid.
110 This function causes the notification function to be executed for every protocol of type
111 ProtocolGuid instance that exists in the system when this function is invoked. If there are
112 no instances of ProtocolGuid in the handle database at the time this function is invoked,
113 then the notification function is still executed one time. In addition, every time a protocol
114 of type ProtocolGuid instance is installed or reinstalled, the notification function is also
115 executed. This function returns the notification event that was created.
116 If ProtocolGuid is NULL, then ASSERT().
117 If NotifyTpl is not a legal TPL value, then ASSERT().
118 If NotifyFunction is NULL, then ASSERT().
119 If Registration is NULL, then ASSERT().
122 @param ProtocolGuid Supplies GUID of the protocol upon whose installation the event is fired.
123 @param NotifyTpl Supplies the task priority level of the event notifications.
124 @param NotifyFunction Supplies the function to notify when the event is signaled.
125 @param NotifyContext The context parameter to pass to NotifyFunction.
126 @param Registration A pointer to a memory location to receive the registration value.
127 This value is passed to LocateHandle() to obtain new handles that
128 have been added that support the ProtocolGuid-specified protocol.
130 @return The notification event that was created.
135 EfiCreateProtocolNotifyEvent(
136 IN EFI_GUID
*ProtocolGuid
,
137 IN EFI_TPL NotifyTpl
,
138 IN EFI_EVENT_NOTIFY NotifyFunction
,
139 IN VOID
*NotifyContext
, OPTIONAL
140 OUT VOID
**Registration
146 ASSERT (ProtocolGuid
!= NULL
);
147 ASSERT (NotifyFunction
!= NULL
);
148 ASSERT (Registration
!= NULL
);
154 Status
= gBS
->CreateEvent (
161 ASSERT_EFI_ERROR (Status
);
164 // Register for protocol notifications on this event
167 Status
= gBS
->RegisterProtocolNotify (
173 ASSERT_EFI_ERROR (Status
);
176 // Kick the event so we will perform an initial pass of
177 // current installed drivers
180 gBS
->SignalEvent (Event
);
185 Creates a named event that can be signaled with EfiNamedEventSignal().
187 This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.
188 This event is signaled with EfiNamedEventSignal(). This provides the ability for one or more
189 listeners on the same event named by the GUID specified by Name.
190 If Name is NULL, then ASSERT().
191 If NotifyTpl is not a legal TPL value, then ASSERT().
192 If NotifyFunction is NULL, then ASSERT().
194 @param Name Supplies the GUID name of the event.
195 @param NotifyTpl Supplies the task priority level of the event notifications.
196 @param NotifyFunction Supplies the function to notify when the event is signaled.
197 @param NotifyContext The context parameter to pass to NotifyFunction.
198 @param Registration A pointer to a memory location to receive the registration value.
200 @retval EFI_SUCCESS A named event was created.
201 @retval EFI_OUT_OF_RESOURCES There are not enough resource to create the named event.
206 EfiNamedEventListen (
207 IN CONST EFI_GUID
*Name
,
208 IN EFI_TPL NotifyTpl
,
209 IN EFI_EVENT_NOTIFY NotifyFunction
,
210 IN CONST VOID
*NotifyContext
, OPTIONAL
211 OUT VOID
*Registration OPTIONAL
216 VOID
*RegistrationLocal
;
218 ASSERT (Name
!= NULL
);
219 ASSERT (NotifyFunction
!= NULL
);
220 ASSERT (NotifyTpl
<= TPL_HIGH_LEVEL
);
225 Status
= gBS
->CreateEvent (
229 (VOID
*) NotifyContext
,
232 ASSERT_EFI_ERROR (Status
);
235 // The Registration is not optional to RegisterProtocolNotify().
236 // To make it optional to EfiNamedEventListen(), may need to substitute with a local.
238 if (Registration
!= NULL
) {
239 RegistrationLocal
= Registration
;
241 RegistrationLocal
= &RegistrationLocal
;
245 // Register for an installation of protocol interface
248 Status
= gBS
->RegisterProtocolNotify (
253 ASSERT_EFI_ERROR (Status
);
259 Signals a named event created with EfiNamedEventListen().
261 This function signals the named event specified by Name. The named event must have been
262 created with EfiNamedEventListen().
263 If Name is NULL, then ASSERT().
265 @param Name Supplies the GUID name of the event.
267 @retval EFI_SUCCESS A named event was signaled.
268 @retval EFI_OUT_OF_RESOURCES There are not enough resource to signal the named event.
273 EfiNamedEventSignal (
274 IN CONST EFI_GUID
*Name
280 ASSERT(Name
!= NULL
);
283 Status
= gBS
->InstallProtocolInterface (
286 EFI_NATIVE_INTERFACE
,
289 ASSERT_EFI_ERROR (Status
);
291 Status
= gBS
->UninstallProtocolInterface (
296 ASSERT_EFI_ERROR (Status
);
302 Signals an event group by placing a new event in the group temporarily and
305 @param[in] EventGroup Supplies the unique identifier of the event
308 @retval EFI_SUCCESS The event group was signaled successfully.
309 @retval EFI_INVALID_PARAMETER EventGroup is NULL.
310 @return Error codes that report problems about event
311 creation or signaling.
315 EfiEventGroupSignal (
316 IN CONST EFI_GUID
*EventGroup
322 if (EventGroup
== NULL
) {
323 return EFI_INVALID_PARAMETER
;
326 Status
= gBS
->CreateEventEx (
329 EfiEventEmptyFunction
,
334 if (EFI_ERROR (Status
)) {
338 Status
= gBS
->SignalEvent (Event
);
339 gBS
->CloseEvent (Event
);
345 An empty function that can be used as NotifyFunction parameter of
346 CreateEvent() or CreateEventEx().
348 @param Event Event whose notification function is being invoked.
349 @param Context The pointer to the notification function's context,
350 which is implementation-dependent.
355 EfiEventEmptyFunction (
363 Returns the current TPL.
365 This function returns the current TPL. There is no EFI service to directly
366 retrieve the current TPL. Instead, the RaiseTPL() function is used to raise
367 the TPL to TPL_HIGH_LEVEL. This will return the current TPL. The TPL level
368 can then immediately be restored back to the current TPL level with a call
371 @return The current TPL.
382 Tpl
= gBS
->RaiseTPL (TPL_HIGH_LEVEL
);
383 gBS
->RestoreTPL (Tpl
);
390 Initializes a basic mutual exclusion lock.
392 This function initializes a basic mutual exclusion lock to the released state
393 and returns the lock. Each lock provides mutual exclusion access at its task
394 priority level. Since there is no preemption or multiprocessor support in EFI,
395 acquiring the lock only consists of raising to the locks TPL.
396 If Lock is NULL, then ASSERT().
397 If Priority is not a valid TPL value, then ASSERT().
399 @param Lock A pointer to the lock data structure to initialize.
400 @param Priority EFI TPL is associated with the lock.
408 IN OUT EFI_LOCK
*Lock
,
412 ASSERT (Lock
!= NULL
);
413 ASSERT (Priority
<= TPL_HIGH_LEVEL
);
415 Lock
->Tpl
= Priority
;
416 Lock
->OwnerTpl
= TPL_APPLICATION
;
417 Lock
->Lock
= EfiLockReleased
;
422 Acquires ownership of a lock.
424 This function raises the system's current task priority level to the task
425 priority level of the mutual exclusion lock. Then, it places the lock in the
427 If Lock is NULL, then ASSERT().
428 If Lock is not initialized, then ASSERT().
429 If Lock is already in the acquired state, then ASSERT().
431 @param Lock A pointer to the lock to acquire.
440 ASSERT (Lock
!= NULL
);
441 ASSERT (Lock
->Lock
== EfiLockReleased
);
443 Lock
->OwnerTpl
= gBS
->RaiseTPL (Lock
->Tpl
);
444 Lock
->Lock
= EfiLockAcquired
;
448 Acquires ownership of a lock.
450 This function raises the system's current task priority level to the task priority
451 level of the mutual exclusion lock. Then, it attempts to place the lock in the acquired state.
452 If the lock is already in the acquired state, then EFI_ACCESS_DENIED is returned.
453 Otherwise, EFI_SUCCESS is returned.
454 If Lock is NULL, then ASSERT().
455 If Lock is not initialized, then ASSERT().
457 @param Lock A pointer to the lock to acquire.
459 @retval EFI_SUCCESS The lock was acquired.
460 @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
465 EfiAcquireLockOrFail (
470 ASSERT (Lock
!= NULL
);
471 ASSERT (Lock
->Lock
!= EfiLockUninitialized
);
473 if (Lock
->Lock
== EfiLockAcquired
) {
475 // Lock is already owned, so bail out
477 return EFI_ACCESS_DENIED
;
480 Lock
->OwnerTpl
= gBS
->RaiseTPL (Lock
->Tpl
);
482 Lock
->Lock
= EfiLockAcquired
;
488 Releases ownership of a lock.
490 This function transitions a mutual exclusion lock from the acquired state to
491 the released state, and restores the system's task priority level to its
493 If Lock is NULL, then ASSERT().
494 If Lock is not initialized, then ASSERT().
495 If Lock is already in the released state, then ASSERT().
497 @param Lock A pointer to the lock to release.
508 ASSERT (Lock
!= NULL
);
509 ASSERT (Lock
->Lock
== EfiLockAcquired
);
511 Tpl
= Lock
->OwnerTpl
;
513 Lock
->Lock
= EfiLockReleased
;
515 gBS
->RestoreTPL (Tpl
);
519 Tests whether a controller handle is being managed by a specific driver.
521 This function tests whether the driver specified by DriverBindingHandle is
522 currently managing the controller specified by ControllerHandle. This test
523 is performed by evaluating if the the protocol specified by ProtocolGuid is
524 present on ControllerHandle and is was opened by DriverBindingHandle with an
525 attribute of EFI_OPEN_PROTOCOL_BY_DRIVER.
526 If ProtocolGuid is NULL, then ASSERT().
528 @param ControllerHandle A handle for a controller to test.
529 @param DriverBindingHandle Specifies the driver binding handle for the
531 @param ProtocolGuid Specifies the protocol that the driver specified
532 by DriverBindingHandle opens in its Start()
535 @retval EFI_SUCCESS ControllerHandle is managed by the driver
536 specified by DriverBindingHandle.
537 @retval EFI_UNSUPPORTED ControllerHandle is not managed by the driver
538 specified by DriverBindingHandle.
543 EfiTestManagedDevice (
544 IN CONST EFI_HANDLE ControllerHandle
,
545 IN CONST EFI_HANDLE DriverBindingHandle
,
546 IN CONST EFI_GUID
*ProtocolGuid
550 VOID
*ManagedInterface
;
552 ASSERT (ProtocolGuid
!= NULL
);
554 Status
= gBS
->OpenProtocol (
556 (EFI_GUID
*) ProtocolGuid
,
560 EFI_OPEN_PROTOCOL_BY_DRIVER
562 if (!EFI_ERROR (Status
)) {
565 (EFI_GUID
*) ProtocolGuid
,
569 return EFI_UNSUPPORTED
;
572 if (Status
!= EFI_ALREADY_STARTED
) {
573 return EFI_UNSUPPORTED
;
580 Tests whether a child handle is a child device of the controller.
582 This function tests whether ChildHandle is one of the children of
583 ControllerHandle. This test is performed by checking to see if the protocol
584 specified by ProtocolGuid is present on ControllerHandle and opened by
585 ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
586 If ProtocolGuid is NULL, then ASSERT().
588 @param ControllerHandle A handle for a (parent) controller to test.
589 @param ChildHandle A child handle to test.
590 @param ProtocolGuid Supplies the protocol that the child controller
591 opens on its parent controller.
593 @retval EFI_SUCCESS ChildHandle is a child of the ControllerHandle.
594 @retval EFI_UNSUPPORTED ChildHandle is not a child of the
601 IN CONST EFI_HANDLE ControllerHandle
,
602 IN CONST EFI_HANDLE ChildHandle
,
603 IN CONST EFI_GUID
*ProtocolGuid
607 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
*OpenInfoBuffer
;
611 ASSERT (ProtocolGuid
!= NULL
);
614 // Retrieve the list of agents that are consuming the specific protocol
615 // on ControllerHandle.
617 Status
= gBS
->OpenProtocolInformation (
619 (EFI_GUID
*) ProtocolGuid
,
623 if (EFI_ERROR (Status
)) {
624 return EFI_UNSUPPORTED
;
628 // Inspect if ChildHandle is one of the agents.
630 Status
= EFI_UNSUPPORTED
;
631 for (Index
= 0; Index
< EntryCount
; Index
++) {
632 if ((OpenInfoBuffer
[Index
].ControllerHandle
== ChildHandle
) &&
633 (OpenInfoBuffer
[Index
].Attributes
& EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
) != 0) {
634 Status
= EFI_SUCCESS
;
639 FreePool (OpenInfoBuffer
);
644 This function checks the supported languages list for a target language,
645 This only supports RFC 4646 Languages.
647 @param SupportedLanguages The supported languages
648 @param TargetLanguage The target language
650 @retval Returns EFI_SUCCESS if the language is supported,
651 EFI_UNSUPPORTED otherwise
655 IsLanguageSupported (
656 IN CONST CHAR8
*SupportedLanguages
,
657 IN CONST CHAR8
*TargetLanguage
661 while (*SupportedLanguages
!= 0) {
662 for (Index
= 0; SupportedLanguages
[Index
] != 0 && SupportedLanguages
[Index
] != ';'; Index
++);
663 if ((AsciiStrnCmp(SupportedLanguages
, TargetLanguage
, Index
) == 0) && (TargetLanguage
[Index
] == 0)) {
666 SupportedLanguages
+= Index
;
667 for (; *SupportedLanguages
!= 0 && *SupportedLanguages
== ';'; SupportedLanguages
++);
670 return EFI_UNSUPPORTED
;
674 This function looks up a Unicode string in UnicodeStringTable.
676 If Language is a member of SupportedLanguages and a Unicode string is found in
677 UnicodeStringTable that matches the language code specified by Language, then it
678 is returned in UnicodeString.
680 @param Language A pointer to the ISO 639-2 language code for the
681 Unicode string to look up and return.
682 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
683 that the Unicode string table supports. Language
684 must be a member of this set.
685 @param UnicodeStringTable A pointer to the table of Unicode strings.
686 @param UnicodeString A pointer to the Unicode string from UnicodeStringTable
687 that matches the language specified by Language.
689 @retval EFI_SUCCESS The Unicode string that matches the language
690 specified by Language was found
691 in the table of Unicode strings UnicodeStringTable,
692 and it was returned in UnicodeString.
693 @retval EFI_INVALID_PARAMETER Language is NULL.
694 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
695 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
696 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
697 @retval EFI_UNSUPPORTED The language specified by Language is not a
698 member of SupportedLanguages.
699 @retval EFI_UNSUPPORTED The language specified by Language is not
700 supported by UnicodeStringTable.
705 LookupUnicodeString (
706 IN CONST CHAR8
*Language
,
707 IN CONST CHAR8
*SupportedLanguages
,
708 IN CONST EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
,
709 OUT CHAR16
**UnicodeString
713 // Make sure the parameters are valid
715 if (Language
== NULL
|| UnicodeString
== NULL
) {
716 return EFI_INVALID_PARAMETER
;
720 // If there are no supported languages, or the Unicode String Table is empty, then the
721 // Unicode String specified by Language is not supported by this Unicode String Table
723 if (SupportedLanguages
== NULL
|| UnicodeStringTable
== NULL
) {
724 return EFI_UNSUPPORTED
;
728 // Make sure Language is in the set of Supported Languages
730 while (*SupportedLanguages
!= 0) {
731 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
734 // Search the Unicode String Table for the matching Language specifier
736 while (UnicodeStringTable
->Language
!= NULL
) {
737 if (CompareIso639LanguageCode (Language
, UnicodeStringTable
->Language
)) {
740 // A matching string was found, so return it
742 *UnicodeString
= UnicodeStringTable
->UnicodeString
;
746 UnicodeStringTable
++;
749 return EFI_UNSUPPORTED
;
752 SupportedLanguages
+= 3;
755 return EFI_UNSUPPORTED
;
761 This function looks up a Unicode string in UnicodeStringTable.
763 If Language is a member of SupportedLanguages and a Unicode string is found in
764 UnicodeStringTable that matches the language code specified by Language, then
765 it is returned in UnicodeString.
767 @param Language A pointer to an ASCII string containing the ISO 639-2 or the
768 RFC 4646 language code for the Unicode string to look up and
769 return. If Iso639Language is TRUE, then this ASCII string is
770 not assumed to be Null-terminated, and only the first three
771 characters are used. If Iso639Language is FALSE, then this ASCII
772 string must be Null-terminated.
773 @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains a
774 set of ISO 639-2 or RFC 4646 language codes that the Unicode
775 string table supports. Language must be a member of this set.
776 If Iso639Language is TRUE, then this string contains one or more
777 ISO 639-2 language codes with no separator characters. If Iso639Language
778 is FALSE, then is string contains one or more RFC 4646 language
779 codes separated by ';'.
780 @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
781 is defined in "Related Definitions".
782 @param UnicodeString A pointer to the Null-terminated Unicode string from UnicodeStringTable
783 that matches the language specified by Language.
784 @param Iso639Language Specifies the supported language code format. If it is TRUE, then
785 Language and SupportedLanguages follow ISO 639-2 language code format.
786 Otherwise, they follow RFC 4646 language code format.
789 @retval EFI_SUCCESS The Unicode string that matches the language specified by Language
790 was found in the table of Unicode strings UnicodeStringTable, and
791 it was returned in UnicodeString.
792 @retval EFI_INVALID_PARAMETER Language is NULL.
793 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
794 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
795 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
796 @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages.
797 @retval EFI_UNSUPPORTED The language specified by Language is not supported by UnicodeStringTable.
802 LookupUnicodeString2 (
803 IN CONST CHAR8
*Language
,
804 IN CONST CHAR8
*SupportedLanguages
,
805 IN CONST EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
,
806 OUT CHAR16
**UnicodeString
,
807 IN BOOLEAN Iso639Language
812 CHAR8
*LanguageString
;
815 // Make sure the parameters are valid
817 if (Language
== NULL
|| UnicodeString
== NULL
) {
818 return EFI_INVALID_PARAMETER
;
822 // If there are no supported languages, or the Unicode String Table is empty, then the
823 // Unicode String specified by Language is not supported by this Unicode String Table
825 if (SupportedLanguages
== NULL
|| UnicodeStringTable
== NULL
) {
826 return EFI_UNSUPPORTED
;
830 // Make sure Language is in the set of Supported Languages
833 if (Iso639Language
) {
834 while (*SupportedLanguages
!= 0) {
835 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
839 SupportedLanguages
+= 3;
842 Found
= !IsLanguageSupported(SupportedLanguages
, Language
);
847 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
850 return EFI_UNSUPPORTED
;
854 // Search the Unicode String Table for the matching Language specifier
856 while (UnicodeStringTable
->Language
!= NULL
) {
857 LanguageString
= UnicodeStringTable
->Language
;
858 while (0 != *LanguageString
) {
859 for (Index
= 0 ;LanguageString
[Index
] != 0 && LanguageString
[Index
] != ';'; Index
++);
860 if (AsciiStrnCmp(LanguageString
, Language
, Index
) == 0) {
861 *UnicodeString
= UnicodeStringTable
->UnicodeString
;
864 LanguageString
+= Index
;
865 for (Index
= 0 ;LanguageString
[Index
] != 0 && LanguageString
[Index
] == ';'; Index
++);
867 UnicodeStringTable
++;
870 return EFI_UNSUPPORTED
;
875 This function adds a Unicode string to UnicodeStringTable.
877 If Language is a member of SupportedLanguages then UnicodeString is added to
878 UnicodeStringTable. New buffers are allocated for both Language and
879 UnicodeString. The contents of Language and UnicodeString are copied into
880 these new buffers. These buffers are automatically freed when
881 FreeUnicodeStringTable() is called.
883 @param Language A pointer to the ISO 639-2 language code for the Unicode
885 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
886 that the Unicode string table supports.
887 Language must be a member of this set.
888 @param UnicodeStringTable A pointer to the table of Unicode strings.
889 @param UnicodeString A pointer to the Unicode string to add.
891 @retval EFI_SUCCESS The Unicode string that matches the language
892 specified by Language was found in the table of
893 Unicode strings UnicodeStringTable, and it was
894 returned in UnicodeString.
895 @retval EFI_INVALID_PARAMETER Language is NULL.
896 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
897 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
898 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
899 @retval EFI_ALREADY_STARTED A Unicode string with language Language is
900 already present in UnicodeStringTable.
901 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another
902 Unicode string to UnicodeStringTable.
903 @retval EFI_UNSUPPORTED The language specified by Language is not a
904 member of SupportedLanguages.
910 IN CONST CHAR8
*Language
,
911 IN CONST CHAR8
*SupportedLanguages
,
912 IN OUT EFI_UNICODE_STRING_TABLE
**UnicodeStringTable
,
913 IN CONST CHAR16
*UnicodeString
916 UINTN NumberOfEntries
;
917 EFI_UNICODE_STRING_TABLE
*OldUnicodeStringTable
;
918 EFI_UNICODE_STRING_TABLE
*NewUnicodeStringTable
;
919 UINTN UnicodeStringLength
;
922 // Make sure the parameter are valid
924 if (Language
== NULL
|| UnicodeString
== NULL
|| UnicodeStringTable
== NULL
) {
925 return EFI_INVALID_PARAMETER
;
929 // If there are no supported languages, then a Unicode String can not be added
931 if (SupportedLanguages
== NULL
) {
932 return EFI_UNSUPPORTED
;
936 // If the Unicode String is empty, then a Unicode String can not be added
938 if (UnicodeString
[0] == 0) {
939 return EFI_INVALID_PARAMETER
;
943 // Make sure Language is a member of SupportedLanguages
945 while (*SupportedLanguages
!= 0) {
946 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
949 // Determine the size of the Unicode String Table by looking for a NULL Language entry
952 if (*UnicodeStringTable
!= NULL
) {
953 OldUnicodeStringTable
= *UnicodeStringTable
;
954 while (OldUnicodeStringTable
->Language
!= NULL
) {
955 if (CompareIso639LanguageCode (Language
, OldUnicodeStringTable
->Language
)) {
956 return EFI_ALREADY_STARTED
;
959 OldUnicodeStringTable
++;
965 // Allocate space for a new Unicode String Table. It must hold the current number of
966 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
969 NewUnicodeStringTable
= AllocatePool ((NumberOfEntries
+ 2) * sizeof (EFI_UNICODE_STRING_TABLE
));
970 if (NewUnicodeStringTable
== NULL
) {
971 return EFI_OUT_OF_RESOURCES
;
975 // If the current Unicode String Table contains any entries, then copy them to the
976 // newly allocated Unicode String Table.
978 if (*UnicodeStringTable
!= NULL
) {
980 NewUnicodeStringTable
,
982 NumberOfEntries
* sizeof (EFI_UNICODE_STRING_TABLE
)
987 // Allocate space for a copy of the Language specifier
989 NewUnicodeStringTable
[NumberOfEntries
].Language
= AllocateCopyPool (3, Language
);
990 if (NewUnicodeStringTable
[NumberOfEntries
].Language
== NULL
) {
991 FreePool (NewUnicodeStringTable
);
992 return EFI_OUT_OF_RESOURCES
;
996 // Compute the length of the Unicode String
998 for (UnicodeStringLength
= 0; UnicodeString
[UnicodeStringLength
] != 0; UnicodeStringLength
++)
1002 // Allocate space for a copy of the Unicode String
1004 NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
= AllocateCopyPool (
1005 (UnicodeStringLength
+ 1) * sizeof (CHAR16
),
1008 if (NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
== NULL
) {
1009 FreePool (NewUnicodeStringTable
[NumberOfEntries
].Language
);
1010 FreePool (NewUnicodeStringTable
);
1011 return EFI_OUT_OF_RESOURCES
;
1015 // Mark the end of the Unicode String Table
1017 NewUnicodeStringTable
[NumberOfEntries
+ 1].Language
= NULL
;
1018 NewUnicodeStringTable
[NumberOfEntries
+ 1].UnicodeString
= NULL
;
1021 // Free the old Unicode String Table
1023 if (*UnicodeStringTable
!= NULL
) {
1024 FreePool (*UnicodeStringTable
);
1028 // Point UnicodeStringTable at the newly allocated Unicode String Table
1030 *UnicodeStringTable
= NewUnicodeStringTable
;
1035 SupportedLanguages
+= 3;
1038 return EFI_UNSUPPORTED
;
1043 This function adds the Null-terminated Unicode string specified by UnicodeString
1044 to UnicodeStringTable.
1046 If Language is a member of SupportedLanguages then UnicodeString is added to
1047 UnicodeStringTable. New buffers are allocated for both Language and UnicodeString.
1048 The contents of Language and UnicodeString are copied into these new buffers.
1049 These buffers are automatically freed when EfiLibFreeUnicodeStringTable() is called.
1051 @param Language A pointer to an ASCII string containing the ISO 639-2 or
1052 the RFC 4646 language code for the Unicode string to add.
1053 If Iso639Language is TRUE, then this ASCII string is not
1054 assumed to be Null-terminated, and only the first three
1055 chacters are used. If Iso639Language is FALSE, then this
1056 ASCII string must be Null-terminated.
1057 @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains
1058 a set of ISO 639-2 or RFC 4646 language codes that the Unicode
1059 string table supports. Language must be a member of this set.
1060 If Iso639Language is TRUE, then this string contains one or more
1061 ISO 639-2 language codes with no separator characters.
1062 If Iso639Language is FALSE, then is string contains one or more
1063 RFC 4646 language codes separated by ';'.
1064 @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
1065 is defined in "Related Definitions".
1066 @param UnicodeString A pointer to the Unicode string to add.
1067 @param Iso639Language Specifies the supported language code format. If it is TRUE,
1068 then Language and SupportedLanguages follow ISO 639-2 language code format.
1069 Otherwise, they follow RFC 4646 language code format.
1071 @retval EFI_SUCCESS The Unicode string that matches the language specified by
1072 Language was found in the table of Unicode strings UnicodeStringTable,
1073 and it was returned in UnicodeString.
1074 @retval EFI_INVALID_PARAMETER Language is NULL.
1075 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
1076 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
1077 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
1078 @retval EFI_ALREADY_STARTED A Unicode string with language Language is already present in
1080 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another Unicode string UnicodeStringTable.
1081 @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages.
1087 IN CONST CHAR8
*Language
,
1088 IN CONST CHAR8
*SupportedLanguages
,
1089 IN OUT EFI_UNICODE_STRING_TABLE
**UnicodeStringTable
,
1090 IN CONST CHAR16
*UnicodeString
,
1091 IN BOOLEAN Iso639Language
1094 UINTN NumberOfEntries
;
1095 EFI_UNICODE_STRING_TABLE
*OldUnicodeStringTable
;
1096 EFI_UNICODE_STRING_TABLE
*NewUnicodeStringTable
;
1097 UINTN UnicodeStringLength
;
1100 CHAR8
*LanguageString
;
1103 // Make sure the parameter are valid
1105 if (Language
== NULL
|| UnicodeString
== NULL
|| UnicodeStringTable
== NULL
) {
1106 return EFI_INVALID_PARAMETER
;
1110 // If there are no supported languages, then a Unicode String can not be added
1112 if (SupportedLanguages
== NULL
) {
1113 return EFI_UNSUPPORTED
;
1117 // If the Unicode String is empty, then a Unicode String can not be added
1119 if (UnicodeString
[0] == 0) {
1120 return EFI_INVALID_PARAMETER
;
1124 // Make sure Language is a member of SupportedLanguages
1127 if (Iso639Language
) {
1128 while (*SupportedLanguages
!= 0) {
1129 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
1133 SupportedLanguages
+= 3;
1136 Found
= !IsLanguageSupported(SupportedLanguages
, Language
);
1139 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
1142 return EFI_UNSUPPORTED
;
1146 // Determine the size of the Unicode String Table by looking for a NULL Language entry
1148 NumberOfEntries
= 0;
1149 if (*UnicodeStringTable
!= NULL
) {
1150 OldUnicodeStringTable
= *UnicodeStringTable
;
1151 while (OldUnicodeStringTable
->Language
!= NULL
) {
1152 LanguageString
= OldUnicodeStringTable
->Language
;
1154 while (*LanguageString
!= 0) {
1155 for (Index
= 0; LanguageString
[Index
] != 0 && LanguageString
[Index
] != ';'; Index
++);
1157 if (AsciiStrnCmp (Language
, LanguageString
, Index
) == 0) {
1158 return EFI_ALREADY_STARTED
;
1160 LanguageString
+= Index
;
1161 for (; *LanguageString
!= 0 && *LanguageString
== ';'; LanguageString
++);
1163 OldUnicodeStringTable
++;
1169 // Allocate space for a new Unicode String Table. It must hold the current number of
1170 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
1173 NewUnicodeStringTable
= AllocatePool ((NumberOfEntries
+ 2) * sizeof (EFI_UNICODE_STRING_TABLE
));
1174 if (NewUnicodeStringTable
== NULL
) {
1175 return EFI_OUT_OF_RESOURCES
;
1179 // If the current Unicode String Table contains any entries, then copy them to the
1180 // newly allocated Unicode String Table.
1182 if (*UnicodeStringTable
!= NULL
) {
1184 NewUnicodeStringTable
,
1185 *UnicodeStringTable
,
1186 NumberOfEntries
* sizeof (EFI_UNICODE_STRING_TABLE
)
1191 // Allocate space for a copy of the Language specifier
1193 NewUnicodeStringTable
[NumberOfEntries
].Language
= AllocateCopyPool (AsciiStrSize(Language
), Language
);
1194 if (NewUnicodeStringTable
[NumberOfEntries
].Language
== NULL
) {
1195 FreePool (NewUnicodeStringTable
);
1196 return EFI_OUT_OF_RESOURCES
;
1200 // Compute the length of the Unicode String
1202 for (UnicodeStringLength
= 0; UnicodeString
[UnicodeStringLength
] != 0; UnicodeStringLength
++);
1205 // Allocate space for a copy of the Unicode String
1207 NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
= AllocateCopyPool (StrSize (UnicodeString
), UnicodeString
);
1208 if (NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
== NULL
) {
1209 FreePool (NewUnicodeStringTable
[NumberOfEntries
].Language
);
1210 FreePool (NewUnicodeStringTable
);
1211 return EFI_OUT_OF_RESOURCES
;
1215 // Mark the end of the Unicode String Table
1217 NewUnicodeStringTable
[NumberOfEntries
+ 1].Language
= NULL
;
1218 NewUnicodeStringTable
[NumberOfEntries
+ 1].UnicodeString
= NULL
;
1221 // Free the old Unicode String Table
1223 if (*UnicodeStringTable
!= NULL
) {
1224 FreePool (*UnicodeStringTable
);
1228 // Point UnicodeStringTable at the newly allocated Unicode String Table
1230 *UnicodeStringTable
= NewUnicodeStringTable
;
1236 This function frees the table of Unicode strings in UnicodeStringTable.
1238 If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
1239 Otherwise, each language code, and each Unicode string in the Unicode string
1240 table are freed, and EFI_SUCCESS is returned.
1242 @param UnicodeStringTable A pointer to the table of Unicode strings.
1244 @retval EFI_SUCCESS The Unicode string table was freed.
1249 FreeUnicodeStringTable (
1250 IN EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
1256 // If the Unicode String Table is NULL, then it is already freed
1258 if (UnicodeStringTable
== NULL
) {
1263 // Loop through the Unicode String Table until we reach the end of table marker
1265 for (Index
= 0; UnicodeStringTable
[Index
].Language
!= NULL
; Index
++) {
1268 // Free the Language string from the Unicode String Table
1270 FreePool (UnicodeStringTable
[Index
].Language
);
1273 // Free the Unicode String from the Unicode String Table
1275 if (UnicodeStringTable
[Index
].UnicodeString
!= NULL
) {
1276 FreePool (UnicodeStringTable
[Index
].UnicodeString
);
1281 // Free the Unicode String Table itself
1283 FreePool (UnicodeStringTable
);
1290 Returns the status whether get the variable success. The function retrieves
1291 variable through the UEFI Runtime Service GetVariable(). The
1292 returned buffer is allocated using AllocatePool(). The caller is responsible
1293 for freeing this buffer with FreePool().
1295 If Name is NULL, then ASSERT().
1296 If Guid is NULL, then ASSERT().
1297 If Value is NULL, then ASSERT().
1299 @param[in] Name The pointer to a Null-terminated Unicode string.
1300 @param[in] Guid The pointer to an EFI_GUID structure
1301 @param[out] Value The buffer point saved the variable info.
1302 @param[out] Size The buffer size of the variable.
1304 @return EFI_OUT_OF_RESOURCES Allocate buffer failed.
1305 @return EFI_SUCCESS Find the specified variable.
1306 @return Others Errors Return errors from call to gRT->GetVariable.
1312 IN CONST CHAR16
*Name
,
1313 IN CONST EFI_GUID
*Guid
,
1315 OUT UINTN
*Size OPTIONAL
1321 ASSERT (Name
!= NULL
&& Guid
!= NULL
&& Value
!= NULL
);
1324 // Try to get the variable size.
1332 Status
= gRT
->GetVariable ((CHAR16
*) Name
, (EFI_GUID
*) Guid
, NULL
, &BufferSize
, *Value
);
1333 if (Status
!= EFI_BUFFER_TOO_SMALL
) {
1338 // Allocate buffer to get the variable.
1340 *Value
= AllocatePool (BufferSize
);
1341 ASSERT (*Value
!= NULL
);
1342 if (*Value
== NULL
) {
1343 return EFI_OUT_OF_RESOURCES
;
1347 // Get the variable data.
1349 Status
= gRT
->GetVariable ((CHAR16
*) Name
, (EFI_GUID
*) Guid
, NULL
, &BufferSize
, *Value
);
1350 if (EFI_ERROR (Status
)) {
1362 /** Return the attributes of the variable.
1364 Returns the status whether get the variable success. The function retrieves
1365 variable through the UEFI Runtime Service GetVariable(). The
1366 returned buffer is allocated using AllocatePool(). The caller is responsible
1367 for freeing this buffer with FreePool(). The attributes are returned if
1368 the caller provides a valid Attribute parameter.
1370 If Name is NULL, then ASSERT().
1371 If Guid is NULL, then ASSERT().
1372 If Value is NULL, then ASSERT().
1374 @param[in] Name The pointer to a Null-terminated Unicode string.
1375 @param[in] Guid The pointer to an EFI_GUID structure
1376 @param[out] Value The buffer point saved the variable info.
1377 @param[out] Size The buffer size of the variable.
1378 @param[out] Attr The pointer to the variable attributes as found in var store
1380 @retval EFI_OUT_OF_RESOURCES Allocate buffer failed.
1381 @retval EFI_SUCCESS Find the specified variable.
1382 @retval Others Errors Return errors from call to gRT->GetVariable.
1388 IN CONST CHAR16
*Name
,
1389 IN CONST EFI_GUID
*Guid
,
1391 OUT UINTN
*Size OPTIONAL
,
1392 OUT UINT32
*Attr OPTIONAL
1398 ASSERT(Name
!= NULL
&& Guid
!= NULL
&& Value
!= NULL
);
1401 // Try to get the variable size.
1413 Status
= gRT
->GetVariable((CHAR16
*)Name
, (EFI_GUID
*)Guid
, Attr
, &BufferSize
, *Value
);
1414 if (Status
!= EFI_BUFFER_TOO_SMALL
) {
1419 // Allocate buffer to get the variable.
1421 *Value
= AllocatePool(BufferSize
);
1422 ASSERT(*Value
!= NULL
);
1423 if (*Value
== NULL
) {
1424 return EFI_OUT_OF_RESOURCES
;
1428 // Get the variable data.
1430 Status
= gRT
->GetVariable((CHAR16
*)Name
, (EFI_GUID
*)Guid
, Attr
, &BufferSize
, *Value
);
1431 if (EFI_ERROR(Status
)) {
1444 Returns a pointer to an allocated buffer that contains the contents of a
1445 variable retrieved through the UEFI Runtime Service GetVariable(). This
1446 function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1447 The returned buffer is allocated using AllocatePool(). The caller is
1448 responsible for freeing this buffer with FreePool().
1450 If Name is NULL, then ASSERT().
1451 If Value is NULL, then ASSERT().
1453 @param[in] Name The pointer to a Null-terminated Unicode string.
1454 @param[out] Value The buffer point saved the variable info.
1455 @param[out] Size The buffer size of the variable.
1457 @return EFI_OUT_OF_RESOURCES Allocate buffer failed.
1458 @return EFI_SUCCESS Find the specified variable.
1459 @return Others Errors Return errors from call to gRT->GetVariable.
1464 GetEfiGlobalVariable2 (
1465 IN CONST CHAR16
*Name
,
1467 OUT UINTN
*Size OPTIONAL
1470 return GetVariable2 (Name
, &gEfiGlobalVariableGuid
, Value
, Size
);
1474 Returns a pointer to an allocated buffer that contains the best matching language
1475 from a set of supported languages.
1477 This function supports both ISO 639-2 and RFC 4646 language codes, but language
1478 code types may not be mixed in a single call to this function. The language
1479 code returned is allocated using AllocatePool(). The caller is responsible for
1480 freeing the allocated buffer using FreePool(). This function supports a variable
1481 argument list that allows the caller to pass in a prioritized list of language
1482 codes to test against all the language codes in SupportedLanguages.
1484 If SupportedLanguages is NULL, then ASSERT().
1486 @param[in] SupportedLanguages A pointer to a Null-terminated ASCII string that
1487 contains a set of language codes in the format
1488 specified by Iso639Language.
1489 @param[in] Iso639Language If not zero, then all language codes are assumed to be
1490 in ISO 639-2 format. If zero, then all language
1491 codes are assumed to be in RFC 4646 language format
1492 @param[in] ... A variable argument list that contains pointers to
1493 Null-terminated ASCII strings that contain one or more
1494 language codes in the format specified by Iso639Language.
1495 The first language code from each of these language
1496 code lists is used to determine if it is an exact or
1497 close match to any of the language codes in
1498 SupportedLanguages. Close matches only apply to RFC 4646
1499 language codes, and the matching algorithm from RFC 4647
1500 is used to determine if a close match is present. If
1501 an exact or close match is found, then the matching
1502 language code from SupportedLanguages is returned. If
1503 no matches are found, then the next variable argument
1504 parameter is evaluated. The variable argument list
1505 is terminated by a NULL.
1507 @retval NULL The best matching language could not be found in SupportedLanguages.
1508 @retval NULL There are not enough resources available to return the best matching
1510 @retval Other A pointer to a Null-terminated ASCII string that is the best matching
1511 language in SupportedLanguages.
1517 IN CONST CHAR8
*SupportedLanguages
,
1518 IN UINTN Iso639Language
,
1524 UINTN CompareLength
;
1525 UINTN LanguageLength
;
1526 CONST CHAR8
*Supported
;
1527 CHAR8
*BestLanguage
;
1529 ASSERT (SupportedLanguages
!= NULL
);
1531 VA_START (Args
, Iso639Language
);
1532 while ((Language
= VA_ARG (Args
, CHAR8
*)) != NULL
) {
1534 // Default to ISO 639-2 mode
1537 LanguageLength
= MIN (3, AsciiStrLen (Language
));
1540 // If in RFC 4646 mode, then determine the length of the first RFC 4646 language code in Language
1542 if (Iso639Language
== 0) {
1543 for (LanguageLength
= 0; Language
[LanguageLength
] != 0 && Language
[LanguageLength
] != ';'; LanguageLength
++);
1547 // Trim back the length of Language used until it is empty
1549 while (LanguageLength
> 0) {
1551 // Loop through all language codes in SupportedLanguages
1553 for (Supported
= SupportedLanguages
; *Supported
!= '\0'; Supported
+= CompareLength
) {
1555 // In RFC 4646 mode, then Loop through all language codes in SupportedLanguages
1557 if (Iso639Language
== 0) {
1559 // Skip ';' characters in Supported
1561 for (; *Supported
!= '\0' && *Supported
== ';'; Supported
++);
1563 // Determine the length of the next language code in Supported
1565 for (CompareLength
= 0; Supported
[CompareLength
] != 0 && Supported
[CompareLength
] != ';'; CompareLength
++);
1567 // If Language is longer than the Supported, then skip to the next language
1569 if (LanguageLength
> CompareLength
) {
1574 // See if the first LanguageLength characters in Supported match Language
1576 if (AsciiStrnCmp (Supported
, Language
, LanguageLength
) == 0) {
1579 // Allocate, copy, and return the best matching language code from SupportedLanguages
1581 BestLanguage
= AllocateZeroPool (CompareLength
+ 1);
1582 if (BestLanguage
== NULL
) {
1585 return CopyMem (BestLanguage
, Supported
, CompareLength
);
1589 if (Iso639Language
!= 0) {
1591 // If ISO 639 mode, then each language can only be tested once
1596 // If RFC 4646 mode, then trim Language from the right to the next '-' character
1598 for (LanguageLength
--; LanguageLength
> 0 && Language
[LanguageLength
] != '-'; LanguageLength
--);
1605 // No matches were found
1611 Returns an array of protocol instance that matches the given protocol.
1613 @param[in] Protocol Provides the protocol to search for.
1614 @param[out] NoProtocols The number of protocols returned in Buffer.
1615 @param[out] Buffer A pointer to the buffer to return the requested
1616 array of protocol instances that match Protocol.
1617 The returned buffer is allocated using
1618 EFI_BOOT_SERVICES.AllocatePool(). The caller is
1619 responsible for freeing this buffer with
1620 EFI_BOOT_SERVICES.FreePool().
1622 @retval EFI_SUCCESS The array of protocols was returned in Buffer,
1623 and the number of protocols in Buffer was
1624 returned in NoProtocols.
1625 @retval EFI_NOT_FOUND No protocols found.
1626 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
1628 @retval EFI_INVALID_PARAMETER Protocol is NULL.
1629 @retval EFI_INVALID_PARAMETER NoProtocols is NULL.
1630 @retval EFI_INVALID_PARAMETER Buffer is NULL.
1635 EfiLocateProtocolBuffer (
1636 IN EFI_GUID
*Protocol
,
1637 OUT UINTN
*NoProtocols
,
1643 EFI_HANDLE
*HandleBuffer
;
1647 // Check input parameters
1649 if (Protocol
== NULL
|| NoProtocols
== NULL
|| Buffer
== NULL
) {
1650 return EFI_INVALID_PARAMETER
;
1654 // Initialze output parameters
1660 // Retrieve the array of handles that support Protocol
1662 Status
= gBS
->LocateHandleBuffer (
1669 if (EFI_ERROR (Status
)) {
1674 // Allocate array of protocol instances
1676 Status
= gBS
->AllocatePool (
1677 EfiBootServicesData
,
1678 NoHandles
* sizeof (VOID
*),
1681 if (EFI_ERROR (Status
)) {
1683 // Free the handle buffer
1685 gBS
->FreePool (HandleBuffer
);
1686 return EFI_OUT_OF_RESOURCES
;
1688 ZeroMem (*Buffer
, NoHandles
* sizeof (VOID
*));
1691 // Lookup Protocol on each handle in HandleBuffer to fill in the array of
1692 // protocol instances. Handle case where protocol instance was present when
1693 // LocateHandleBuffer() was called, but is not present when HandleProtocol()
1696 for (Index
= 0, *NoProtocols
= 0; Index
< NoHandles
; Index
++) {
1697 Status
= gBS
->HandleProtocol (
1698 HandleBuffer
[Index
],
1700 &((*Buffer
)[*NoProtocols
])
1702 if (!EFI_ERROR (Status
)) {
1708 // Free the handle buffer
1710 gBS
->FreePool (HandleBuffer
);
1713 // Make sure at least one protocol instance was found
1715 if (*NoProtocols
== 0) {
1716 gBS
->FreePool (*Buffer
);
1718 return EFI_NOT_FOUND
;
1725 Open or create a file or directory, possibly creating the chain of
1726 directories leading up to the directory.
1728 EfiOpenFileByDevicePath() first locates EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on
1729 FilePath, and opens the root directory of that filesystem with
1730 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume().
1732 On the remaining device path, the longest initial sequence of
1733 FILEPATH_DEVICE_PATH nodes is node-wise traversed with
1734 EFI_FILE_PROTOCOL.Open().
1736 (As a consequence, if OpenMode includes EFI_FILE_MODE_CREATE, and Attributes
1737 includes EFI_FILE_DIRECTORY, and each FILEPATH_DEVICE_PATH specifies a single
1738 pathname component, then EfiOpenFileByDevicePath() ensures that the specified
1739 series of subdirectories exist on return.)
1741 The EFI_FILE_PROTOCOL identified by the last FILEPATH_DEVICE_PATH node is
1742 output to the caller; intermediate EFI_FILE_PROTOCOL instances are closed. If
1743 there are no FILEPATH_DEVICE_PATH nodes past the node that identifies the
1744 filesystem, then the EFI_FILE_PROTOCOL of the root directory of the
1745 filesystem is output to the caller. If a device path node that is different
1746 from FILEPATH_DEVICE_PATH is encountered relative to the filesystem, the
1747 traversal is stopped with an error, and a NULL EFI_FILE_PROTOCOL is output.
1749 @param[in,out] FilePath On input, the device path to the file or directory
1750 to open or create. The caller is responsible for
1751 ensuring that the device path pointed-to by FilePath
1752 is well-formed. On output, FilePath points one past
1753 the last node in the original device path that has
1754 been successfully processed. FilePath is set on
1755 output even if EfiOpenFileByDevicePath() returns an
1758 @param[out] File On error, File is set to NULL. On success, File is
1759 set to the EFI_FILE_PROTOCOL of the root directory
1760 of the filesystem, if there are no
1761 FILEPATH_DEVICE_PATH nodes in FilePath; otherwise,
1762 File is set to the EFI_FILE_PROTOCOL identified by
1763 the last node in FilePath.
1765 @param[in] OpenMode The OpenMode parameter to pass to
1766 EFI_FILE_PROTOCOL.Open().
1768 @param[in] Attributes The Attributes parameter to pass to
1769 EFI_FILE_PROTOCOL.Open().
1771 @retval EFI_SUCCESS The file or directory has been opened or
1774 @retval EFI_INVALID_PARAMETER FilePath is NULL; or File is NULL; or FilePath
1775 contains a device path node, past the node
1777 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL, that is not a
1778 FILEPATH_DEVICE_PATH node.
1780 @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
1782 @return Error codes propagated from the
1783 LocateDevicePath() and OpenProtocol() boot
1784 services, and from the
1785 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume()
1786 and EFI_FILE_PROTOCOL.Open() member functions.
1790 EfiOpenFileByDevicePath (
1791 IN OUT EFI_DEVICE_PATH_PROTOCOL
**FilePath
,
1792 OUT EFI_FILE_PROTOCOL
**File
,
1794 IN UINT64 Attributes
1798 EFI_HANDLE FileSystemHandle
;
1799 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
*FileSystem
;
1800 EFI_FILE_PROTOCOL
*LastFile
;
1801 FILEPATH_DEVICE_PATH
*FilePathNode
;
1802 CHAR16
*AlignedPathName
;
1804 EFI_FILE_PROTOCOL
*NextFile
;
1807 return EFI_INVALID_PARAMETER
;
1811 if (FilePath
== NULL
) {
1812 return EFI_INVALID_PARAMETER
;
1816 // Look up the filesystem.
1818 Status
= gBS
->LocateDevicePath (
1819 &gEfiSimpleFileSystemProtocolGuid
,
1823 if (EFI_ERROR (Status
)) {
1826 Status
= gBS
->OpenProtocol (
1828 &gEfiSimpleFileSystemProtocolGuid
,
1829 (VOID
**)&FileSystem
,
1832 EFI_OPEN_PROTOCOL_GET_PROTOCOL
1834 if (EFI_ERROR (Status
)) {
1839 // Open the root directory of the filesystem. After this operation succeeds,
1840 // we have to release LastFile on error.
1842 Status
= FileSystem
->OpenVolume (FileSystem
, &LastFile
);
1843 if (EFI_ERROR (Status
)) {
1848 // Traverse the device path nodes relative to the filesystem.
1850 while (!IsDevicePathEnd (*FilePath
)) {
1851 if (DevicePathType (*FilePath
) != MEDIA_DEVICE_PATH
||
1852 DevicePathSubType (*FilePath
) != MEDIA_FILEPATH_DP
) {
1853 Status
= EFI_INVALID_PARAMETER
;
1856 FilePathNode
= (FILEPATH_DEVICE_PATH
*)*FilePath
;
1859 // FilePathNode->PathName may be unaligned, and the UEFI specification
1860 // requires pointers that are passed to protocol member functions to be
1861 // aligned. Create an aligned copy of the pathname if necessary.
1863 if ((UINTN
)FilePathNode
->PathName
% sizeof *FilePathNode
->PathName
== 0) {
1864 AlignedPathName
= NULL
;
1865 PathName
= FilePathNode
->PathName
;
1867 AlignedPathName
= AllocateCopyPool (
1868 (DevicePathNodeLength (FilePathNode
) -
1869 SIZE_OF_FILEPATH_DEVICE_PATH
),
1870 FilePathNode
->PathName
1872 if (AlignedPathName
== NULL
) {
1873 Status
= EFI_OUT_OF_RESOURCES
;
1876 PathName
= AlignedPathName
;
1880 // Open or create the file corresponding to the next pathname fragment.
1882 Status
= LastFile
->Open (
1891 // Release any AlignedPathName on both error and success paths; PathName is
1892 // no longer needed.
1894 if (AlignedPathName
!= NULL
) {
1895 FreePool (AlignedPathName
);
1897 if (EFI_ERROR (Status
)) {
1902 // Advance to the next device path node.
1904 LastFile
->Close (LastFile
);
1905 LastFile
= NextFile
;
1906 *FilePath
= NextDevicePathNode (FilePathNode
);
1913 LastFile
->Close (LastFile
);
1916 // We are on the error path; we must have set an error Status for returning
1919 ASSERT (EFI_ERROR (Status
));