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
13 #include "UefiLibInternal.h"
16 Empty constructor function that is required to resolve dependencies between
21 @param ImageHandle The firmware allocated handle for the EFI image.
22 @param SystemTable A pointer to the EFI System Table.
24 @retval EFI_SUCCESS The constructor executed correctly.
30 IN EFI_HANDLE ImageHandle
,
31 IN EFI_SYSTEM_TABLE
*SystemTable
38 Compare whether two names of languages are identical.
40 @param Language1 Name of language 1.
41 @param Language2 Name of language 2.
43 @retval TRUE Language 1 and language 2 are the same.
44 @retval FALSE Language 1 and language 2 are not the same.
48 CompareIso639LanguageCode (
49 IN CONST CHAR8
*Language1
,
50 IN CONST CHAR8
*Language2
56 Name1
= ReadUnaligned24 ((CONST UINT32
*)Language1
);
57 Name2
= ReadUnaligned24 ((CONST UINT32
*)Language2
);
59 return (BOOLEAN
)(Name1
== Name2
);
63 Retrieves a pointer to the system configuration table from the EFI System Table
64 based on a specified GUID.
66 This function searches the list of configuration tables stored in the EFI System Table
67 for a table with a GUID that matches TableGuid. If a match is found, then a pointer to
68 the configuration table is returned in Table., and EFI_SUCCESS is returned. If a matching GUID
69 is not found, then EFI_NOT_FOUND is returned.
70 If TableGuid is NULL, then ASSERT().
71 If Table is NULL, then ASSERT().
73 @param TableGuid The pointer to table's GUID type.
74 @param Table The pointer to the table associated with TableGuid in the EFI System Table.
76 @retval EFI_SUCCESS A configuration table matching TableGuid was found.
77 @retval EFI_NOT_FOUND A configuration table matching TableGuid could not be found.
82 EfiGetSystemConfigurationTable (
83 IN EFI_GUID
*TableGuid
,
87 EFI_SYSTEM_TABLE
*SystemTable
;
90 ASSERT (TableGuid
!= NULL
);
91 ASSERT (Table
!= NULL
);
95 for (Index
= 0; Index
< SystemTable
->NumberOfTableEntries
; Index
++) {
96 if (CompareGuid (TableGuid
, &(SystemTable
->ConfigurationTable
[Index
].VendorGuid
))) {
97 *Table
= SystemTable
->ConfigurationTable
[Index
].VendorTable
;
102 return EFI_NOT_FOUND
;
106 Creates and returns a notification event and registers that event with all the protocol
107 instances specified by ProtocolGuid.
109 This function causes the notification function to be executed for every protocol of type
110 ProtocolGuid instance that exists in the system when this function is invoked. If there are
111 no instances of ProtocolGuid in the handle database at the time this function is invoked,
112 then the notification function is still executed one time. In addition, every time a protocol
113 of type ProtocolGuid instance is installed or reinstalled, the notification function is also
114 executed. This function returns the notification event that was created.
115 If ProtocolGuid is NULL, then ASSERT().
116 If NotifyTpl is not a legal TPL value, then ASSERT().
117 If NotifyFunction is NULL, then ASSERT().
118 If Registration is NULL, then ASSERT().
121 @param ProtocolGuid Supplies GUID of the protocol upon whose installation the event is fired.
122 @param NotifyTpl Supplies the task priority level of the event notifications.
123 @param NotifyFunction Supplies the function to notify when the event is signaled.
124 @param NotifyContext The context parameter to pass to NotifyFunction.
125 @param Registration A pointer to a memory location to receive the registration value.
126 This value is passed to LocateHandle() to obtain new handles that
127 have been added that support the ProtocolGuid-specified protocol.
129 @return The notification event that was created.
134 EfiCreateProtocolNotifyEvent (
135 IN EFI_GUID
*ProtocolGuid
,
136 IN EFI_TPL NotifyTpl
,
137 IN EFI_EVENT_NOTIFY NotifyFunction
,
138 IN VOID
*NotifyContext OPTIONAL
,
139 OUT VOID
**Registration
145 ASSERT (ProtocolGuid
!= NULL
);
146 ASSERT (NotifyFunction
!= NULL
);
147 ASSERT (Registration
!= NULL
);
153 Status
= gBS
->CreateEvent (
160 ASSERT_EFI_ERROR (Status
);
163 // Register for protocol notifications on this event
166 Status
= gBS
->RegisterProtocolNotify (
172 ASSERT_EFI_ERROR (Status
);
175 // Kick the event so we will perform an initial pass of
176 // current installed drivers
179 gBS
->SignalEvent (Event
);
184 Creates a named event that can be signaled with EfiNamedEventSignal().
186 This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.
187 This event is signaled with EfiNamedEventSignal(). This provides the ability for one or more
188 listeners on the same event named by the GUID specified by Name.
189 If Name is NULL, then ASSERT().
190 If NotifyTpl is not a legal TPL value, then ASSERT().
191 If NotifyFunction is NULL, then ASSERT().
193 @param Name Supplies the GUID name of the event.
194 @param NotifyTpl Supplies the task priority level of the event notifications.
195 @param NotifyFunction Supplies the function to notify when the event is signaled.
196 @param NotifyContext The context parameter to pass to NotifyFunction.
197 @param Registration A pointer to a memory location to receive the registration value.
199 @retval EFI_SUCCESS A named event was created.
200 @retval EFI_OUT_OF_RESOURCES There are not enough resource to create the named event.
205 EfiNamedEventListen (
206 IN CONST EFI_GUID
*Name
,
207 IN EFI_TPL NotifyTpl
,
208 IN EFI_EVENT_NOTIFY NotifyFunction
,
209 IN CONST VOID
*NotifyContext OPTIONAL
,
210 OUT VOID
*Registration OPTIONAL
215 VOID
*RegistrationLocal
;
217 ASSERT (Name
!= NULL
);
218 ASSERT (NotifyFunction
!= NULL
);
219 ASSERT (NotifyTpl
<= TPL_HIGH_LEVEL
);
224 Status
= gBS
->CreateEvent (
228 (VOID
*)NotifyContext
,
231 ASSERT_EFI_ERROR (Status
);
234 // The Registration is not optional to RegisterProtocolNotify().
235 // To make it optional to EfiNamedEventListen(), may need to substitute with a local.
237 if (Registration
!= NULL
) {
238 RegistrationLocal
= Registration
;
240 RegistrationLocal
= &RegistrationLocal
;
244 // Register for an installation of protocol interface
247 Status
= gBS
->RegisterProtocolNotify (
252 ASSERT_EFI_ERROR (Status
);
258 Signals a named event created with EfiNamedEventListen().
260 This function signals the named event specified by Name. The named event must have been
261 created with EfiNamedEventListen().
262 If Name is NULL, then ASSERT().
264 @param Name Supplies the GUID name of the event.
266 @retval EFI_SUCCESS A named event was signaled.
267 @retval EFI_OUT_OF_RESOURCES There are not enough resource to signal the named event.
272 EfiNamedEventSignal (
273 IN CONST EFI_GUID
*Name
279 ASSERT (Name
!= NULL
);
282 Status
= gBS
->InstallProtocolInterface (
285 EFI_NATIVE_INTERFACE
,
288 ASSERT_EFI_ERROR (Status
);
290 Status
= gBS
->UninstallProtocolInterface (
295 ASSERT_EFI_ERROR (Status
);
301 Signals an event group by placing a new event in the group temporarily and
304 @param[in] EventGroup Supplies the unique identifier of the event
307 @retval EFI_SUCCESS The event group was signaled successfully.
308 @retval EFI_INVALID_PARAMETER EventGroup is NULL.
309 @return Error codes that report problems about event
310 creation or signaling.
314 EfiEventGroupSignal (
315 IN CONST EFI_GUID
*EventGroup
321 if (EventGroup
== NULL
) {
322 return EFI_INVALID_PARAMETER
;
325 Status
= gBS
->CreateEventEx (
328 EfiEventEmptyFunction
,
333 if (EFI_ERROR (Status
)) {
337 Status
= gBS
->SignalEvent (Event
);
338 gBS
->CloseEvent (Event
);
344 An empty function that can be used as NotifyFunction parameter of
345 CreateEvent() or CreateEventEx().
347 @param Event Event whose notification function is being invoked.
348 @param Context The pointer to the notification function's context,
349 which is implementation-dependent.
354 EfiEventEmptyFunction (
362 Returns the current TPL.
364 This function returns the current TPL. There is no EFI service to directly
365 retrieve the current TPL. Instead, the RaiseTPL() function is used to raise
366 the TPL to TPL_HIGH_LEVEL. This will return the current TPL. The TPL level
367 can then immediately be restored back to the current TPL level with a call
370 @return The current TPL.
381 Tpl
= gBS
->RaiseTPL (TPL_HIGH_LEVEL
);
382 gBS
->RestoreTPL (Tpl
);
388 Initializes a basic mutual exclusion lock.
390 This function initializes a basic mutual exclusion lock to the released state
391 and returns the lock. Each lock provides mutual exclusion access at its task
392 priority level. Since there is no preemption or multiprocessor support in EFI,
393 acquiring the lock only consists of raising to the locks TPL.
394 If Lock is NULL, then ASSERT().
395 If Priority is not a valid TPL value, then ASSERT().
397 @param Lock A pointer to the lock data structure to initialize.
398 @param Priority EFI TPL is associated with the lock.
406 IN OUT EFI_LOCK
*Lock
,
410 ASSERT (Lock
!= NULL
);
411 ASSERT (Priority
<= TPL_HIGH_LEVEL
);
413 Lock
->Tpl
= Priority
;
414 Lock
->OwnerTpl
= TPL_APPLICATION
;
415 Lock
->Lock
= EfiLockReleased
;
420 Acquires ownership of a lock.
422 This function raises the system's current task priority level to the task
423 priority level of the mutual exclusion lock. Then, it places the lock in the
425 If Lock is NULL, then ASSERT().
426 If Lock is not initialized, then ASSERT().
427 If Lock is already in the acquired state, then ASSERT().
429 @param Lock A pointer to the lock to acquire.
438 ASSERT (Lock
!= NULL
);
439 ASSERT (Lock
->Lock
== EfiLockReleased
);
441 Lock
->OwnerTpl
= gBS
->RaiseTPL (Lock
->Tpl
);
442 Lock
->Lock
= EfiLockAcquired
;
446 Acquires ownership of a lock.
448 This function raises the system's current task priority level to the task priority
449 level of the mutual exclusion lock. Then, it attempts to place the lock in the acquired state.
450 If the lock is already in the acquired state, then EFI_ACCESS_DENIED is returned.
451 Otherwise, EFI_SUCCESS is returned.
452 If Lock is NULL, then ASSERT().
453 If Lock is not initialized, then ASSERT().
455 @param Lock A pointer to the lock to acquire.
457 @retval EFI_SUCCESS The lock was acquired.
458 @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
463 EfiAcquireLockOrFail (
467 ASSERT (Lock
!= NULL
);
468 ASSERT (Lock
->Lock
!= EfiLockUninitialized
);
470 if (Lock
->Lock
== EfiLockAcquired
) {
472 // Lock is already owned, so bail out
474 return EFI_ACCESS_DENIED
;
477 Lock
->OwnerTpl
= gBS
->RaiseTPL (Lock
->Tpl
);
479 Lock
->Lock
= EfiLockAcquired
;
485 Releases ownership of a lock.
487 This function transitions a mutual exclusion lock from the acquired state to
488 the released state, and restores the system's task priority level to its
490 If Lock is NULL, then ASSERT().
491 If Lock is not initialized, then ASSERT().
492 If Lock is already in the released state, then ASSERT().
494 @param Lock A pointer to the lock to release.
505 ASSERT (Lock
!= NULL
);
506 ASSERT (Lock
->Lock
== EfiLockAcquired
);
508 Tpl
= Lock
->OwnerTpl
;
510 Lock
->Lock
= EfiLockReleased
;
512 gBS
->RestoreTPL (Tpl
);
516 Tests whether a controller handle is being managed by a specific driver.
518 This function tests whether the driver specified by DriverBindingHandle is
519 currently managing the controller specified by ControllerHandle. This test
520 is performed by evaluating if the the protocol specified by ProtocolGuid is
521 present on ControllerHandle and is was opened by DriverBindingHandle with an
522 attribute of EFI_OPEN_PROTOCOL_BY_DRIVER.
523 If ProtocolGuid is NULL, then ASSERT().
525 @param ControllerHandle A handle for a controller to test.
526 @param DriverBindingHandle Specifies the driver binding handle for the
528 @param ProtocolGuid Specifies the protocol that the driver specified
529 by DriverBindingHandle opens in its Start()
532 @retval EFI_SUCCESS ControllerHandle is managed by the driver
533 specified by DriverBindingHandle.
534 @retval EFI_UNSUPPORTED ControllerHandle is not managed by the driver
535 specified by DriverBindingHandle.
540 EfiTestManagedDevice (
541 IN CONST EFI_HANDLE ControllerHandle
,
542 IN CONST EFI_HANDLE DriverBindingHandle
,
543 IN CONST EFI_GUID
*ProtocolGuid
547 VOID
*ManagedInterface
;
549 ASSERT (ProtocolGuid
!= NULL
);
551 Status
= gBS
->OpenProtocol (
553 (EFI_GUID
*)ProtocolGuid
,
557 EFI_OPEN_PROTOCOL_BY_DRIVER
559 if (!EFI_ERROR (Status
)) {
562 (EFI_GUID
*)ProtocolGuid
,
566 return EFI_UNSUPPORTED
;
569 if (Status
!= EFI_ALREADY_STARTED
) {
570 return EFI_UNSUPPORTED
;
577 Tests whether a child handle is a child device of the controller.
579 This function tests whether ChildHandle is one of the children of
580 ControllerHandle. This test is performed by checking to see if the protocol
581 specified by ProtocolGuid is present on ControllerHandle and opened by
582 ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
583 If ProtocolGuid is NULL, then ASSERT().
585 @param ControllerHandle A handle for a (parent) controller to test.
586 @param ChildHandle A child handle to test.
587 @param ProtocolGuid Supplies the protocol that the child controller
588 opens on its parent controller.
590 @retval EFI_SUCCESS ChildHandle is a child of the ControllerHandle.
591 @retval EFI_UNSUPPORTED ChildHandle is not a child of the
598 IN CONST EFI_HANDLE ControllerHandle
,
599 IN CONST EFI_HANDLE ChildHandle
,
600 IN CONST EFI_GUID
*ProtocolGuid
604 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
*OpenInfoBuffer
;
608 ASSERT (ProtocolGuid
!= NULL
);
611 // Retrieve the list of agents that are consuming the specific protocol
612 // on ControllerHandle.
614 Status
= gBS
->OpenProtocolInformation (
616 (EFI_GUID
*)ProtocolGuid
,
620 if (EFI_ERROR (Status
)) {
621 return EFI_UNSUPPORTED
;
625 // Inspect if ChildHandle is one of the agents.
627 Status
= EFI_UNSUPPORTED
;
628 for (Index
= 0; Index
< EntryCount
; Index
++) {
629 if ((OpenInfoBuffer
[Index
].ControllerHandle
== ChildHandle
) &&
630 ((OpenInfoBuffer
[Index
].Attributes
& EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
) != 0))
632 Status
= EFI_SUCCESS
;
637 FreePool (OpenInfoBuffer
);
642 This function checks the supported languages list for a target language,
643 This only supports RFC 4646 Languages.
645 @param SupportedLanguages The supported languages
646 @param TargetLanguage The target language
648 @retval Returns EFI_SUCCESS if the language is supported,
649 EFI_UNSUPPORTED otherwise
653 IsLanguageSupported (
654 IN CONST CHAR8
*SupportedLanguages
,
655 IN CONST CHAR8
*TargetLanguage
660 while (*SupportedLanguages
!= 0) {
661 for (Index
= 0; SupportedLanguages
[Index
] != 0 && SupportedLanguages
[Index
] != ';'; Index
++) {
664 if ((AsciiStrnCmp (SupportedLanguages
, TargetLanguage
, Index
) == 0) && (TargetLanguage
[Index
] == 0)) {
668 SupportedLanguages
+= Index
;
669 for ( ; *SupportedLanguages
!= 0 && *SupportedLanguages
== ';'; SupportedLanguages
++) {
673 return EFI_UNSUPPORTED
;
677 This function looks up a Unicode string in UnicodeStringTable.
679 If Language is a member of SupportedLanguages and a Unicode string is found in
680 UnicodeStringTable that matches the language code specified by Language, then it
681 is returned in UnicodeString.
683 @param Language A pointer to the ISO 639-2 language code for the
684 Unicode string to look up and return.
685 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
686 that the Unicode string table supports. Language
687 must be a member of this set.
688 @param UnicodeStringTable A pointer to the table of Unicode strings.
689 @param UnicodeString A pointer to the Unicode string from UnicodeStringTable
690 that matches the language specified by Language.
692 @retval EFI_SUCCESS The Unicode string that matches the language
693 specified by Language was found
694 in the table of Unicode strings UnicodeStringTable,
695 and it was returned in UnicodeString.
696 @retval EFI_INVALID_PARAMETER Language is NULL.
697 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
698 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
699 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
700 @retval EFI_UNSUPPORTED The language specified by Language is not a
701 member of SupportedLanguages.
702 @retval EFI_UNSUPPORTED The language specified by Language is not
703 supported by UnicodeStringTable.
708 LookupUnicodeString (
709 IN CONST CHAR8
*Language
,
710 IN CONST CHAR8
*SupportedLanguages
,
711 IN CONST EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
,
712 OUT CHAR16
**UnicodeString
716 // Make sure the parameters are valid
718 if ((Language
== NULL
) || (UnicodeString
== NULL
)) {
719 return EFI_INVALID_PARAMETER
;
723 // If there are no supported languages, or the Unicode String Table is empty, then the
724 // Unicode String specified by Language is not supported by this Unicode String Table
726 if ((SupportedLanguages
== NULL
) || (UnicodeStringTable
== NULL
)) {
727 return EFI_UNSUPPORTED
;
731 // Make sure Language is in the set of Supported Languages
733 while (*SupportedLanguages
!= 0) {
734 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
736 // Search the Unicode String Table for the matching Language specifier
738 while (UnicodeStringTable
->Language
!= NULL
) {
739 if (CompareIso639LanguageCode (Language
, UnicodeStringTable
->Language
)) {
741 // A matching string was found, so return it
743 *UnicodeString
= UnicodeStringTable
->UnicodeString
;
747 UnicodeStringTable
++;
750 return EFI_UNSUPPORTED
;
753 SupportedLanguages
+= 3;
756 return EFI_UNSUPPORTED
;
760 This function looks up a Unicode string in UnicodeStringTable.
762 If Language is a member of SupportedLanguages and a Unicode string is found in
763 UnicodeStringTable that matches the language code specified by Language, then
764 it is returned in UnicodeString.
766 @param Language A pointer to an ASCII string containing the ISO 639-2 or the
767 RFC 4646 language code for the Unicode string to look up and
768 return. If Iso639Language is TRUE, then this ASCII string is
769 not assumed to be Null-terminated, and only the first three
770 characters are used. If Iso639Language is FALSE, then this ASCII
771 string must be Null-terminated.
772 @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains a
773 set of ISO 639-2 or RFC 4646 language codes that the Unicode
774 string table supports. Language must be a member of this set.
775 If Iso639Language is TRUE, then this string contains one or more
776 ISO 639-2 language codes with no separator characters. If Iso639Language
777 is FALSE, then is string contains one or more RFC 4646 language
778 codes separated by ';'.
779 @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
780 is defined in "Related Definitions".
781 @param UnicodeString A pointer to the Null-terminated Unicode string from UnicodeStringTable
782 that matches the language specified by Language.
783 @param Iso639Language Specifies the supported language code format. If it is TRUE, then
784 Language and SupportedLanguages follow ISO 639-2 language code format.
785 Otherwise, they follow RFC 4646 language code format.
788 @retval EFI_SUCCESS The Unicode string that matches the language specified by Language
789 was found in the table of Unicode strings UnicodeStringTable, and
790 it was returned in UnicodeString.
791 @retval EFI_INVALID_PARAMETER Language is NULL.
792 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
793 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
794 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
795 @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages.
796 @retval EFI_UNSUPPORTED The language specified by Language is not supported by UnicodeStringTable.
801 LookupUnicodeString2 (
802 IN CONST CHAR8
*Language
,
803 IN CONST CHAR8
*SupportedLanguages
,
804 IN CONST EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
,
805 OUT CHAR16
**UnicodeString
,
806 IN BOOLEAN Iso639Language
811 CHAR8
*LanguageString
;
814 // Make sure the parameters are valid
816 if ((Language
== NULL
) || (UnicodeString
== NULL
)) {
817 return EFI_INVALID_PARAMETER
;
821 // If there are no supported languages, or the Unicode String Table is empty, then the
822 // Unicode String specified by Language is not supported by this Unicode String Table
824 if ((SupportedLanguages
== NULL
) || (UnicodeStringTable
== NULL
)) {
825 return EFI_UNSUPPORTED
;
829 // Make sure Language is in the set of Supported Languages
832 if (Iso639Language
) {
833 while (*SupportedLanguages
!= 0) {
834 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
839 SupportedLanguages
+= 3;
842 Found
= !IsLanguageSupported (SupportedLanguages
, Language
);
846 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
849 return EFI_UNSUPPORTED
;
853 // Search the Unicode String Table for the matching Language specifier
855 while (UnicodeStringTable
->Language
!= NULL
) {
856 LanguageString
= UnicodeStringTable
->Language
;
857 while (0 != *LanguageString
) {
858 for (Index
= 0; LanguageString
[Index
] != 0 && LanguageString
[Index
] != ';'; Index
++) {
861 if (AsciiStrnCmp (LanguageString
, Language
, Index
) == 0) {
862 *UnicodeString
= UnicodeStringTable
->UnicodeString
;
866 LanguageString
+= Index
;
867 for (Index
= 0; LanguageString
[Index
] != 0 && LanguageString
[Index
] == ';'; Index
++) {
871 UnicodeStringTable
++;
874 return EFI_UNSUPPORTED
;
878 This function adds a Unicode string to UnicodeStringTable.
880 If Language is a member of SupportedLanguages then UnicodeString is added to
881 UnicodeStringTable. New buffers are allocated for both Language and
882 UnicodeString. The contents of Language and UnicodeString are copied into
883 these new buffers. These buffers are automatically freed when
884 FreeUnicodeStringTable() is called.
886 @param Language A pointer to the ISO 639-2 language code for the Unicode
888 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
889 that the Unicode string table supports.
890 Language must be a member of this set.
891 @param UnicodeStringTable A pointer to the table of Unicode strings.
892 @param UnicodeString A pointer to the Unicode string to add.
894 @retval EFI_SUCCESS The Unicode string that matches the language
895 specified by Language was found in the table of
896 Unicode strings UnicodeStringTable, and it was
897 returned in UnicodeString.
898 @retval EFI_INVALID_PARAMETER Language is NULL.
899 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
900 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
901 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
902 @retval EFI_ALREADY_STARTED A Unicode string with language Language is
903 already present in UnicodeStringTable.
904 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another
905 Unicode string to UnicodeStringTable.
906 @retval EFI_UNSUPPORTED The language specified by Language is not a
907 member of SupportedLanguages.
913 IN CONST CHAR8
*Language
,
914 IN CONST CHAR8
*SupportedLanguages
,
915 IN OUT EFI_UNICODE_STRING_TABLE
**UnicodeStringTable
,
916 IN CONST CHAR16
*UnicodeString
919 UINTN NumberOfEntries
;
920 EFI_UNICODE_STRING_TABLE
*OldUnicodeStringTable
;
921 EFI_UNICODE_STRING_TABLE
*NewUnicodeStringTable
;
922 UINTN UnicodeStringLength
;
925 // Make sure the parameter are valid
927 if ((Language
== NULL
) || (UnicodeString
== NULL
) || (UnicodeStringTable
== NULL
)) {
928 return EFI_INVALID_PARAMETER
;
932 // If there are no supported languages, then a Unicode String can not be added
934 if (SupportedLanguages
== NULL
) {
935 return EFI_UNSUPPORTED
;
939 // If the Unicode String is empty, then a Unicode String can not be added
941 if (UnicodeString
[0] == 0) {
942 return EFI_INVALID_PARAMETER
;
946 // Make sure Language is a member of SupportedLanguages
948 while (*SupportedLanguages
!= 0) {
949 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
951 // Determine the size of the Unicode String Table by looking for a NULL Language entry
954 if (*UnicodeStringTable
!= NULL
) {
955 OldUnicodeStringTable
= *UnicodeStringTable
;
956 while (OldUnicodeStringTable
->Language
!= NULL
) {
957 if (CompareIso639LanguageCode (Language
, OldUnicodeStringTable
->Language
)) {
958 return EFI_ALREADY_STARTED
;
961 OldUnicodeStringTable
++;
967 // Allocate space for a new Unicode String Table. It must hold the current number of
968 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
971 NewUnicodeStringTable
= AllocatePool ((NumberOfEntries
+ 2) * sizeof (EFI_UNICODE_STRING_TABLE
));
972 if (NewUnicodeStringTable
== NULL
) {
973 return EFI_OUT_OF_RESOURCES
;
977 // If the current Unicode String Table contains any entries, then copy them to the
978 // newly allocated Unicode String Table.
980 if (*UnicodeStringTable
!= NULL
) {
982 NewUnicodeStringTable
,
984 NumberOfEntries
* sizeof (EFI_UNICODE_STRING_TABLE
)
989 // Allocate space for a copy of the Language specifier
991 NewUnicodeStringTable
[NumberOfEntries
].Language
= AllocateCopyPool (3, Language
);
992 if (NewUnicodeStringTable
[NumberOfEntries
].Language
== NULL
) {
993 FreePool (NewUnicodeStringTable
);
994 return EFI_OUT_OF_RESOURCES
;
998 // Compute the length of the Unicode String
1000 for (UnicodeStringLength
= 0; UnicodeString
[UnicodeStringLength
] != 0; UnicodeStringLength
++) {
1004 // Allocate space for a copy of the Unicode String
1006 NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
= AllocateCopyPool (
1007 (UnicodeStringLength
+ 1) * sizeof (CHAR16
),
1010 if (NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
== NULL
) {
1011 FreePool (NewUnicodeStringTable
[NumberOfEntries
].Language
);
1012 FreePool (NewUnicodeStringTable
);
1013 return EFI_OUT_OF_RESOURCES
;
1017 // Mark the end of the Unicode String Table
1019 NewUnicodeStringTable
[NumberOfEntries
+ 1].Language
= NULL
;
1020 NewUnicodeStringTable
[NumberOfEntries
+ 1].UnicodeString
= NULL
;
1023 // Free the old Unicode String Table
1025 if (*UnicodeStringTable
!= NULL
) {
1026 FreePool (*UnicodeStringTable
);
1030 // Point UnicodeStringTable at the newly allocated Unicode String Table
1032 *UnicodeStringTable
= NewUnicodeStringTable
;
1037 SupportedLanguages
+= 3;
1040 return EFI_UNSUPPORTED
;
1044 This function adds the Null-terminated Unicode string specified by UnicodeString
1045 to UnicodeStringTable.
1047 If Language is a member of SupportedLanguages then UnicodeString is added to
1048 UnicodeStringTable. New buffers are allocated for both Language and UnicodeString.
1049 The contents of Language and UnicodeString are copied into these new buffers.
1050 These buffers are automatically freed when EfiLibFreeUnicodeStringTable() is called.
1052 @param Language A pointer to an ASCII string containing the ISO 639-2 or
1053 the RFC 4646 language code for the Unicode string to add.
1054 If Iso639Language is TRUE, then this ASCII string is not
1055 assumed to be Null-terminated, and only the first three
1056 chacters are used. If Iso639Language is FALSE, then this
1057 ASCII string must be Null-terminated.
1058 @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains
1059 a set of ISO 639-2 or RFC 4646 language codes that the Unicode
1060 string table supports. Language must be a member of this set.
1061 If Iso639Language is TRUE, then this string contains one or more
1062 ISO 639-2 language codes with no separator characters.
1063 If Iso639Language is FALSE, then is string contains one or more
1064 RFC 4646 language codes separated by ';'.
1065 @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
1066 is defined in "Related Definitions".
1067 @param UnicodeString A pointer to the Unicode string to add.
1068 @param Iso639Language Specifies the supported language code format. If it is TRUE,
1069 then Language and SupportedLanguages follow ISO 639-2 language code format.
1070 Otherwise, they follow RFC 4646 language code format.
1072 @retval EFI_SUCCESS The Unicode string that matches the language specified by
1073 Language was found in the table of Unicode strings UnicodeStringTable,
1074 and it was returned in UnicodeString.
1075 @retval EFI_INVALID_PARAMETER Language is NULL.
1076 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
1077 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
1078 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
1079 @retval EFI_ALREADY_STARTED A Unicode string with language Language is already present in
1081 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another Unicode string UnicodeStringTable.
1082 @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages.
1088 IN CONST CHAR8
*Language
,
1089 IN CONST CHAR8
*SupportedLanguages
,
1090 IN OUT EFI_UNICODE_STRING_TABLE
**UnicodeStringTable
,
1091 IN CONST CHAR16
*UnicodeString
,
1092 IN BOOLEAN Iso639Language
1095 UINTN NumberOfEntries
;
1096 EFI_UNICODE_STRING_TABLE
*OldUnicodeStringTable
;
1097 EFI_UNICODE_STRING_TABLE
*NewUnicodeStringTable
;
1098 UINTN UnicodeStringLength
;
1101 CHAR8
*LanguageString
;
1104 // Make sure the parameter are valid
1106 if ((Language
== NULL
) || (UnicodeString
== NULL
) || (UnicodeStringTable
== NULL
)) {
1107 return EFI_INVALID_PARAMETER
;
1111 // If there are no supported languages, then a Unicode String can not be added
1113 if (SupportedLanguages
== NULL
) {
1114 return EFI_UNSUPPORTED
;
1118 // If the Unicode String is empty, then a Unicode String can not be added
1120 if (UnicodeString
[0] == 0) {
1121 return EFI_INVALID_PARAMETER
;
1125 // Make sure Language is a member of SupportedLanguages
1128 if (Iso639Language
) {
1129 while (*SupportedLanguages
!= 0) {
1130 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
1135 SupportedLanguages
+= 3;
1138 Found
= !IsLanguageSupported (SupportedLanguages
, Language
);
1142 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
1145 return EFI_UNSUPPORTED
;
1149 // Determine the size of the Unicode String Table by looking for a NULL Language entry
1151 NumberOfEntries
= 0;
1152 if (*UnicodeStringTable
!= NULL
) {
1153 OldUnicodeStringTable
= *UnicodeStringTable
;
1154 while (OldUnicodeStringTable
->Language
!= NULL
) {
1155 LanguageString
= OldUnicodeStringTable
->Language
;
1157 while (*LanguageString
!= 0) {
1158 for (Index
= 0; LanguageString
[Index
] != 0 && LanguageString
[Index
] != ';'; Index
++) {
1161 if (AsciiStrnCmp (Language
, LanguageString
, Index
) == 0) {
1162 return EFI_ALREADY_STARTED
;
1165 LanguageString
+= Index
;
1166 for ( ; *LanguageString
!= 0 && *LanguageString
== ';'; LanguageString
++) {
1170 OldUnicodeStringTable
++;
1176 // Allocate space for a new Unicode String Table. It must hold the current number of
1177 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
1180 NewUnicodeStringTable
= AllocatePool ((NumberOfEntries
+ 2) * sizeof (EFI_UNICODE_STRING_TABLE
));
1181 if (NewUnicodeStringTable
== NULL
) {
1182 return EFI_OUT_OF_RESOURCES
;
1186 // If the current Unicode String Table contains any entries, then copy them to the
1187 // newly allocated Unicode String Table.
1189 if (*UnicodeStringTable
!= NULL
) {
1191 NewUnicodeStringTable
,
1192 *UnicodeStringTable
,
1193 NumberOfEntries
* sizeof (EFI_UNICODE_STRING_TABLE
)
1198 // Allocate space for a copy of the Language specifier
1200 NewUnicodeStringTable
[NumberOfEntries
].Language
= AllocateCopyPool (AsciiStrSize (Language
), Language
);
1201 if (NewUnicodeStringTable
[NumberOfEntries
].Language
== NULL
) {
1202 FreePool (NewUnicodeStringTable
);
1203 return EFI_OUT_OF_RESOURCES
;
1207 // Compute the length of the Unicode String
1209 for (UnicodeStringLength
= 0; UnicodeString
[UnicodeStringLength
] != 0; UnicodeStringLength
++) {
1213 // Allocate space for a copy of the Unicode String
1215 NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
= AllocateCopyPool (StrSize (UnicodeString
), UnicodeString
);
1216 if (NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
== NULL
) {
1217 FreePool (NewUnicodeStringTable
[NumberOfEntries
].Language
);
1218 FreePool (NewUnicodeStringTable
);
1219 return EFI_OUT_OF_RESOURCES
;
1223 // Mark the end of the Unicode String Table
1225 NewUnicodeStringTable
[NumberOfEntries
+ 1].Language
= NULL
;
1226 NewUnicodeStringTable
[NumberOfEntries
+ 1].UnicodeString
= NULL
;
1229 // Free the old Unicode String Table
1231 if (*UnicodeStringTable
!= NULL
) {
1232 FreePool (*UnicodeStringTable
);
1236 // Point UnicodeStringTable at the newly allocated Unicode String Table
1238 *UnicodeStringTable
= NewUnicodeStringTable
;
1244 This function frees the table of Unicode strings in UnicodeStringTable.
1246 If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
1247 Otherwise, each language code, and each Unicode string in the Unicode string
1248 table are freed, and EFI_SUCCESS is returned.
1250 @param UnicodeStringTable A pointer to the table of Unicode strings.
1252 @retval EFI_SUCCESS The Unicode string table was freed.
1257 FreeUnicodeStringTable (
1258 IN EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
1264 // If the Unicode String Table is NULL, then it is already freed
1266 if (UnicodeStringTable
== NULL
) {
1271 // Loop through the Unicode String Table until we reach the end of table marker
1273 for (Index
= 0; UnicodeStringTable
[Index
].Language
!= NULL
; Index
++) {
1275 // Free the Language string from the Unicode String Table
1277 FreePool (UnicodeStringTable
[Index
].Language
);
1280 // Free the Unicode String from the Unicode String Table
1282 if (UnicodeStringTable
[Index
].UnicodeString
!= NULL
) {
1283 FreePool (UnicodeStringTable
[Index
].UnicodeString
);
1288 // Free the Unicode String Table itself
1290 FreePool (UnicodeStringTable
);
1296 Returns the status whether get the variable success. The function retrieves
1297 variable through the UEFI Runtime Service GetVariable(). The
1298 returned buffer is allocated using AllocatePool(). The caller is responsible
1299 for freeing this buffer with FreePool().
1301 If Name is NULL, then ASSERT().
1302 If Guid is NULL, then ASSERT().
1303 If Value is NULL, then ASSERT().
1305 @param[in] Name The pointer to a Null-terminated Unicode string.
1306 @param[in] Guid The pointer to an EFI_GUID structure
1307 @param[out] Value The buffer point saved the variable info.
1308 @param[out] Size The buffer size of the variable.
1310 @return EFI_OUT_OF_RESOURCES Allocate buffer failed.
1311 @return EFI_SUCCESS Find the specified variable.
1312 @return Others Errors Return errors from call to gRT->GetVariable.
1318 IN CONST CHAR16
*Name
,
1319 IN CONST EFI_GUID
*Guid
,
1321 OUT UINTN
*Size OPTIONAL
1327 ASSERT (Name
!= NULL
&& Guid
!= NULL
&& Value
!= NULL
);
1330 // Try to get the variable size.
1338 Status
= gRT
->GetVariable ((CHAR16
*)Name
, (EFI_GUID
*)Guid
, NULL
, &BufferSize
, *Value
);
1339 if (Status
!= EFI_BUFFER_TOO_SMALL
) {
1344 // Allocate buffer to get the variable.
1346 *Value
= AllocatePool (BufferSize
);
1347 ASSERT (*Value
!= NULL
);
1348 if (*Value
== NULL
) {
1349 return EFI_OUT_OF_RESOURCES
;
1353 // Get the variable data.
1355 Status
= gRT
->GetVariable ((CHAR16
*)Name
, (EFI_GUID
*)Guid
, NULL
, &BufferSize
, *Value
);
1356 if (EFI_ERROR (Status
)) {
1368 /** Return the attributes of the variable.
1370 Returns the status whether get the variable success. The function retrieves
1371 variable through the UEFI Runtime Service GetVariable(). The
1372 returned buffer is allocated using AllocatePool(). The caller is responsible
1373 for freeing this buffer with FreePool(). The attributes are returned if
1374 the caller provides a valid Attribute parameter.
1376 If Name is NULL, then ASSERT().
1377 If Guid is NULL, then ASSERT().
1378 If Value is NULL, then ASSERT().
1380 @param[in] Name The pointer to a Null-terminated Unicode string.
1381 @param[in] Guid The pointer to an EFI_GUID structure
1382 @param[out] Value The buffer point saved the variable info.
1383 @param[out] Size The buffer size of the variable.
1384 @param[out] Attr The pointer to the variable attributes as found in var store
1386 @retval EFI_OUT_OF_RESOURCES Allocate buffer failed.
1387 @retval EFI_SUCCESS Find the specified variable.
1388 @retval Others Errors Return errors from call to gRT->GetVariable.
1394 IN CONST CHAR16
*Name
,
1395 IN CONST EFI_GUID
*Guid
,
1397 OUT UINTN
*Size OPTIONAL
,
1398 OUT UINT32
*Attr OPTIONAL
1404 ASSERT (Name
!= NULL
&& Guid
!= NULL
&& Value
!= NULL
);
1407 // Try to get the variable size.
1419 Status
= gRT
->GetVariable ((CHAR16
*)Name
, (EFI_GUID
*)Guid
, Attr
, &BufferSize
, *Value
);
1420 if (Status
!= EFI_BUFFER_TOO_SMALL
) {
1425 // Allocate buffer to get the variable.
1427 *Value
= AllocatePool (BufferSize
);
1428 ASSERT (*Value
!= NULL
);
1429 if (*Value
== NULL
) {
1430 return EFI_OUT_OF_RESOURCES
;
1434 // Get the variable data.
1436 Status
= gRT
->GetVariable ((CHAR16
*)Name
, (EFI_GUID
*)Guid
, Attr
, &BufferSize
, *Value
);
1437 if (EFI_ERROR (Status
)) {
1450 Returns a pointer to an allocated buffer that contains the contents of a
1451 variable retrieved through the UEFI Runtime Service GetVariable(). This
1452 function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1453 The returned buffer is allocated using AllocatePool(). The caller is
1454 responsible for freeing this buffer with FreePool().
1456 If Name is NULL, then ASSERT().
1457 If Value is NULL, then ASSERT().
1459 @param[in] Name The pointer to a Null-terminated Unicode string.
1460 @param[out] Value The buffer point saved the variable info.
1461 @param[out] Size The buffer size of the variable.
1463 @return EFI_OUT_OF_RESOURCES Allocate buffer failed.
1464 @return EFI_SUCCESS Find the specified variable.
1465 @return Others Errors Return errors from call to gRT->GetVariable.
1470 GetEfiGlobalVariable2 (
1471 IN CONST CHAR16
*Name
,
1473 OUT UINTN
*Size OPTIONAL
1476 return GetVariable2 (Name
, &gEfiGlobalVariableGuid
, Value
, Size
);
1480 Returns a pointer to an allocated buffer that contains the best matching language
1481 from a set of supported languages.
1483 This function supports both ISO 639-2 and RFC 4646 language codes, but language
1484 code types may not be mixed in a single call to this function. The language
1485 code returned is allocated using AllocatePool(). The caller is responsible for
1486 freeing the allocated buffer using FreePool(). This function supports a variable
1487 argument list that allows the caller to pass in a prioritized list of language
1488 codes to test against all the language codes in SupportedLanguages.
1490 If SupportedLanguages is NULL, then ASSERT().
1492 @param[in] SupportedLanguages A pointer to a Null-terminated ASCII string that
1493 contains a set of language codes in the format
1494 specified by Iso639Language.
1495 @param[in] Iso639Language If not zero, then all language codes are assumed to be
1496 in ISO 639-2 format. If zero, then all language
1497 codes are assumed to be in RFC 4646 language format
1498 @param[in] ... A variable argument list that contains pointers to
1499 Null-terminated ASCII strings that contain one or more
1500 language codes in the format specified by Iso639Language.
1501 The first language code from each of these language
1502 code lists is used to determine if it is an exact or
1503 close match to any of the language codes in
1504 SupportedLanguages. Close matches only apply to RFC 4646
1505 language codes, and the matching algorithm from RFC 4647
1506 is used to determine if a close match is present. If
1507 an exact or close match is found, then the matching
1508 language code from SupportedLanguages is returned. If
1509 no matches are found, then the next variable argument
1510 parameter is evaluated. The variable argument list
1511 is terminated by a NULL.
1513 @retval NULL The best matching language could not be found in SupportedLanguages.
1514 @retval NULL There are not enough resources available to return the best matching
1516 @retval Other A pointer to a Null-terminated ASCII string that is the best matching
1517 language in SupportedLanguages.
1523 IN CONST CHAR8
*SupportedLanguages
,
1524 IN UINTN Iso639Language
,
1530 UINTN CompareLength
;
1531 UINTN LanguageLength
;
1532 CONST CHAR8
*Supported
;
1533 CHAR8
*BestLanguage
;
1535 ASSERT (SupportedLanguages
!= NULL
);
1537 VA_START (Args
, Iso639Language
);
1538 while ((Language
= VA_ARG (Args
, CHAR8
*)) != NULL
) {
1540 // Default to ISO 639-2 mode
1543 LanguageLength
= MIN (3, AsciiStrLen (Language
));
1546 // If in RFC 4646 mode, then determine the length of the first RFC 4646 language code in Language
1548 if (Iso639Language
== 0) {
1549 for (LanguageLength
= 0; Language
[LanguageLength
] != 0 && Language
[LanguageLength
] != ';'; LanguageLength
++) {
1554 // Trim back the length of Language used until it is empty
1556 while (LanguageLength
> 0) {
1558 // Loop through all language codes in SupportedLanguages
1560 for (Supported
= SupportedLanguages
; *Supported
!= '\0'; Supported
+= CompareLength
) {
1562 // In RFC 4646 mode, then Loop through all language codes in SupportedLanguages
1564 if (Iso639Language
== 0) {
1566 // Skip ';' characters in Supported
1568 for ( ; *Supported
!= '\0' && *Supported
== ';'; Supported
++) {
1572 // Determine the length of the next language code in Supported
1574 for (CompareLength
= 0; Supported
[CompareLength
] != 0 && Supported
[CompareLength
] != ';'; CompareLength
++) {
1578 // If Language is longer than the Supported, then skip to the next language
1580 if (LanguageLength
> CompareLength
) {
1586 // See if the first LanguageLength characters in Supported match Language
1588 if (AsciiStrnCmp (Supported
, Language
, LanguageLength
) == 0) {
1591 // Allocate, copy, and return the best matching language code from SupportedLanguages
1593 BestLanguage
= AllocateZeroPool (CompareLength
+ 1);
1594 if (BestLanguage
== NULL
) {
1598 return CopyMem (BestLanguage
, Supported
, CompareLength
);
1602 if (Iso639Language
!= 0) {
1604 // If ISO 639 mode, then each language can only be tested once
1609 // If RFC 4646 mode, then trim Language from the right to the next '-' character
1611 for (LanguageLength
--; LanguageLength
> 0 && Language
[LanguageLength
] != '-'; LanguageLength
--) {
1620 // No matches were found
1626 Returns an array of protocol instance that matches the given protocol.
1628 @param[in] Protocol Provides the protocol to search for.
1629 @param[out] NoProtocols The number of protocols returned in Buffer.
1630 @param[out] Buffer A pointer to the buffer to return the requested
1631 array of protocol instances that match Protocol.
1632 The returned buffer is allocated using
1633 EFI_BOOT_SERVICES.AllocatePool(). The caller is
1634 responsible for freeing this buffer with
1635 EFI_BOOT_SERVICES.FreePool().
1637 @retval EFI_SUCCESS The array of protocols was returned in Buffer,
1638 and the number of protocols in Buffer was
1639 returned in NoProtocols.
1640 @retval EFI_NOT_FOUND No protocols found.
1641 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
1643 @retval EFI_INVALID_PARAMETER Protocol is NULL.
1644 @retval EFI_INVALID_PARAMETER NoProtocols is NULL.
1645 @retval EFI_INVALID_PARAMETER Buffer is NULL.
1650 EfiLocateProtocolBuffer (
1651 IN EFI_GUID
*Protocol
,
1652 OUT UINTN
*NoProtocols
,
1658 EFI_HANDLE
*HandleBuffer
;
1662 // Check input parameters
1664 if ((Protocol
== NULL
) || (NoProtocols
== NULL
) || (Buffer
== NULL
)) {
1665 return EFI_INVALID_PARAMETER
;
1669 // Initialze output parameters
1675 // Retrieve the array of handles that support Protocol
1677 Status
= gBS
->LocateHandleBuffer (
1684 if (EFI_ERROR (Status
)) {
1689 // Allocate array of protocol instances
1691 Status
= gBS
->AllocatePool (
1692 EfiBootServicesData
,
1693 NoHandles
* sizeof (VOID
*),
1696 if (EFI_ERROR (Status
)) {
1698 // Free the handle buffer
1700 gBS
->FreePool (HandleBuffer
);
1701 return EFI_OUT_OF_RESOURCES
;
1704 ZeroMem (*Buffer
, NoHandles
* sizeof (VOID
*));
1707 // Lookup Protocol on each handle in HandleBuffer to fill in the array of
1708 // protocol instances. Handle case where protocol instance was present when
1709 // LocateHandleBuffer() was called, but is not present when HandleProtocol()
1712 for (Index
= 0, *NoProtocols
= 0; Index
< NoHandles
; Index
++) {
1713 Status
= gBS
->HandleProtocol (
1714 HandleBuffer
[Index
],
1716 &((*Buffer
)[*NoProtocols
])
1718 if (!EFI_ERROR (Status
)) {
1724 // Free the handle buffer
1726 gBS
->FreePool (HandleBuffer
);
1729 // Make sure at least one protocol instance was found
1731 if (*NoProtocols
== 0) {
1732 gBS
->FreePool (*Buffer
);
1734 return EFI_NOT_FOUND
;
1741 Open or create a file or directory, possibly creating the chain of
1742 directories leading up to the directory.
1744 EfiOpenFileByDevicePath() first locates EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on
1745 FilePath, and opens the root directory of that filesystem with
1746 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume().
1748 On the remaining device path, the longest initial sequence of
1749 FILEPATH_DEVICE_PATH nodes is node-wise traversed with
1750 EFI_FILE_PROTOCOL.Open().
1752 (As a consequence, if OpenMode includes EFI_FILE_MODE_CREATE, and Attributes
1753 includes EFI_FILE_DIRECTORY, and each FILEPATH_DEVICE_PATH specifies a single
1754 pathname component, then EfiOpenFileByDevicePath() ensures that the specified
1755 series of subdirectories exist on return.)
1757 The EFI_FILE_PROTOCOL identified by the last FILEPATH_DEVICE_PATH node is
1758 output to the caller; intermediate EFI_FILE_PROTOCOL instances are closed. If
1759 there are no FILEPATH_DEVICE_PATH nodes past the node that identifies the
1760 filesystem, then the EFI_FILE_PROTOCOL of the root directory of the
1761 filesystem is output to the caller. If a device path node that is different
1762 from FILEPATH_DEVICE_PATH is encountered relative to the filesystem, the
1763 traversal is stopped with an error, and a NULL EFI_FILE_PROTOCOL is output.
1765 @param[in,out] FilePath On input, the device path to the file or directory
1766 to open or create. The caller is responsible for
1767 ensuring that the device path pointed-to by FilePath
1768 is well-formed. On output, FilePath points one past
1769 the last node in the original device path that has
1770 been successfully processed. FilePath is set on
1771 output even if EfiOpenFileByDevicePath() returns an
1774 @param[out] File On error, File is set to NULL. On success, File is
1775 set to the EFI_FILE_PROTOCOL of the root directory
1776 of the filesystem, if there are no
1777 FILEPATH_DEVICE_PATH nodes in FilePath; otherwise,
1778 File is set to the EFI_FILE_PROTOCOL identified by
1779 the last node in FilePath.
1781 @param[in] OpenMode The OpenMode parameter to pass to
1782 EFI_FILE_PROTOCOL.Open().
1784 @param[in] Attributes The Attributes parameter to pass to
1785 EFI_FILE_PROTOCOL.Open().
1787 @retval EFI_SUCCESS The file or directory has been opened or
1790 @retval EFI_INVALID_PARAMETER FilePath is NULL; or File is NULL; or FilePath
1791 contains a device path node, past the node
1793 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL, that is not a
1794 FILEPATH_DEVICE_PATH node.
1796 @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
1798 @return Error codes propagated from the
1799 LocateDevicePath() and OpenProtocol() boot
1800 services, and from the
1801 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume()
1802 and EFI_FILE_PROTOCOL.Open() member functions.
1806 EfiOpenFileByDevicePath (
1807 IN OUT EFI_DEVICE_PATH_PROTOCOL
**FilePath
,
1808 OUT EFI_FILE_PROTOCOL
**File
,
1810 IN UINT64 Attributes
1814 EFI_HANDLE FileSystemHandle
;
1815 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
*FileSystem
;
1816 EFI_FILE_PROTOCOL
*LastFile
;
1817 FILEPATH_DEVICE_PATH
*FilePathNode
;
1818 CHAR16
*AlignedPathName
;
1820 EFI_FILE_PROTOCOL
*NextFile
;
1823 return EFI_INVALID_PARAMETER
;
1828 if (FilePath
== NULL
) {
1829 return EFI_INVALID_PARAMETER
;
1833 // Look up the filesystem.
1835 Status
= gBS
->LocateDevicePath (
1836 &gEfiSimpleFileSystemProtocolGuid
,
1840 if (EFI_ERROR (Status
)) {
1844 Status
= gBS
->OpenProtocol (
1846 &gEfiSimpleFileSystemProtocolGuid
,
1847 (VOID
**)&FileSystem
,
1850 EFI_OPEN_PROTOCOL_GET_PROTOCOL
1852 if (EFI_ERROR (Status
)) {
1857 // Open the root directory of the filesystem. After this operation succeeds,
1858 // we have to release LastFile on error.
1860 Status
= FileSystem
->OpenVolume (FileSystem
, &LastFile
);
1861 if (EFI_ERROR (Status
)) {
1866 // Traverse the device path nodes relative to the filesystem.
1868 while (!IsDevicePathEnd (*FilePath
)) {
1869 if ((DevicePathType (*FilePath
) != MEDIA_DEVICE_PATH
) ||
1870 (DevicePathSubType (*FilePath
) != MEDIA_FILEPATH_DP
))
1872 Status
= EFI_INVALID_PARAMETER
;
1876 FilePathNode
= (FILEPATH_DEVICE_PATH
*)*FilePath
;
1879 // FilePathNode->PathName may be unaligned, and the UEFI specification
1880 // requires pointers that are passed to protocol member functions to be
1881 // aligned. Create an aligned copy of the pathname if necessary.
1883 if ((UINTN
)FilePathNode
->PathName
% sizeof *FilePathNode
->PathName
== 0) {
1884 AlignedPathName
= NULL
;
1885 PathName
= FilePathNode
->PathName
;
1887 AlignedPathName
= AllocateCopyPool (
1888 (DevicePathNodeLength (FilePathNode
) -
1889 SIZE_OF_FILEPATH_DEVICE_PATH
),
1890 FilePathNode
->PathName
1892 if (AlignedPathName
== NULL
) {
1893 Status
= EFI_OUT_OF_RESOURCES
;
1897 PathName
= AlignedPathName
;
1901 // Open or create the file corresponding to the next pathname fragment.
1903 Status
= LastFile
->Open (
1912 // Release any AlignedPathName on both error and success paths; PathName is
1913 // no longer needed.
1915 if (AlignedPathName
!= NULL
) {
1916 FreePool (AlignedPathName
);
1919 if (EFI_ERROR (Status
)) {
1924 // Advance to the next device path node.
1926 LastFile
->Close (LastFile
);
1927 LastFile
= NextFile
;
1928 *FilePath
= NextDevicePathNode (FilePathNode
);
1935 LastFile
->Close (LastFile
);
1938 // We are on the error path; we must have set an error Status for returning
1941 ASSERT (EFI_ERROR (Status
));