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(Language
, SupportedLanguages
);
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(Language
, SupportedLanguages
);
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
);
1288 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1291 [ATTENTION] This function will be deprecated for security reason.
1293 Returns a pointer to an allocated buffer that contains the contents of a
1294 variable retrieved through the UEFI Runtime Service GetVariable(). The
1295 returned buffer is allocated using AllocatePool(). The caller is responsible
1296 for freeing this buffer with FreePool().
1298 If Name is NULL, then ASSERT().
1299 If Guid is NULL, then ASSERT().
1301 @param[in] Name The pointer to a Null-terminated Unicode string.
1302 @param[in] Guid The pointer to an EFI_GUID structure
1304 @retval NULL The variable could not be retrieved.
1305 @retval NULL There are not enough resources available for the variable contents.
1306 @retval Other A pointer to allocated buffer containing the variable contents.
1312 IN CONST CHAR16
*Name
,
1313 IN CONST EFI_GUID
*Guid
1320 ASSERT (Name
!= NULL
);
1321 ASSERT (Guid
!= NULL
);
1324 // Try to get the variable size.
1328 Status
= gRT
->GetVariable ((CHAR16
*) Name
, (EFI_GUID
*) Guid
, NULL
, &Size
, Value
);
1329 if (Status
!= EFI_BUFFER_TOO_SMALL
) {
1334 // Allocate buffer to get the variable.
1336 Value
= AllocatePool (Size
);
1337 if (Value
== NULL
) {
1342 // Get the variable data.
1344 Status
= gRT
->GetVariable ((CHAR16
*) Name
, (EFI_GUID
*) Guid
, NULL
, &Size
, Value
);
1345 if (EFI_ERROR (Status
)) {
1354 [ATTENTION] This function will be deprecated for security reason.
1356 Returns a pointer to an allocated buffer that contains the contents of a
1357 variable retrieved through the UEFI Runtime Service GetVariable(). This
1358 function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1359 The returned buffer is allocated using AllocatePool(). The caller is
1360 responsible for freeing this buffer with FreePool().
1362 If Name is NULL, then ASSERT().
1364 @param[in] Name The pointer to a Null-terminated Unicode string.
1366 @retval NULL The variable could not be retrieved.
1367 @retval NULL There are not enough resources available for the variable contents.
1368 @retval Other A pointer to allocated buffer containing the variable contents.
1373 GetEfiGlobalVariable (
1374 IN CONST CHAR16
*Name
1377 return GetVariable (Name
, &gEfiGlobalVariableGuid
);
1382 Returns the status whether get the variable success. The function retrieves
1383 variable through the UEFI Runtime Service GetVariable(). The
1384 returned buffer is allocated using AllocatePool(). The caller is responsible
1385 for freeing this buffer with FreePool().
1387 If Name is NULL, then ASSERT().
1388 If Guid is NULL, then ASSERT().
1389 If Value is NULL, then ASSERT().
1391 @param[in] Name The pointer to a Null-terminated Unicode string.
1392 @param[in] Guid The pointer to an EFI_GUID structure
1393 @param[out] Value The buffer point saved the variable info.
1394 @param[out] Size The buffer size of the variable.
1396 @return EFI_OUT_OF_RESOURCES Allocate buffer failed.
1397 @return EFI_SUCCESS Find the specified variable.
1398 @return Others Errors Return errors from call to gRT->GetVariable.
1404 IN CONST CHAR16
*Name
,
1405 IN CONST EFI_GUID
*Guid
,
1407 OUT UINTN
*Size OPTIONAL
1413 ASSERT (Name
!= NULL
&& Guid
!= NULL
&& Value
!= NULL
);
1416 // Try to get the variable size.
1424 Status
= gRT
->GetVariable ((CHAR16
*) Name
, (EFI_GUID
*) Guid
, NULL
, &BufferSize
, *Value
);
1425 if (Status
!= EFI_BUFFER_TOO_SMALL
) {
1430 // Allocate buffer to get the variable.
1432 *Value
= AllocatePool (BufferSize
);
1433 ASSERT (*Value
!= NULL
);
1434 if (*Value
== NULL
) {
1435 return EFI_OUT_OF_RESOURCES
;
1439 // Get the variable data.
1441 Status
= gRT
->GetVariable ((CHAR16
*) Name
, (EFI_GUID
*) Guid
, NULL
, &BufferSize
, *Value
);
1442 if (EFI_ERROR (Status
)) {
1454 /** Return the attributes of the variable.
1456 Returns the status whether get the variable success. The function retrieves
1457 variable through the UEFI Runtime Service GetVariable(). The
1458 returned buffer is allocated using AllocatePool(). The caller is responsible
1459 for freeing this buffer with FreePool(). The attributes are returned if
1460 the caller provides a valid Attribute parameter.
1462 If Name is NULL, then ASSERT().
1463 If Guid is NULL, then ASSERT().
1464 If Value is NULL, then ASSERT().
1466 @param[in] Name The pointer to a Null-terminated Unicode string.
1467 @param[in] Guid The pointer to an EFI_GUID structure
1468 @param[out] Value The buffer point saved the variable info.
1469 @param[out] Size The buffer size of the variable.
1470 @param[out] Attr The pointer to the variable attributes as found in var store
1472 @retval EFI_OUT_OF_RESOURCES Allocate buffer failed.
1473 @retval EFI_SUCCESS Find the specified variable.
1474 @retval Others Errors Return errors from call to gRT->GetVariable.
1480 IN CONST CHAR16
*Name
,
1481 IN CONST EFI_GUID
*Guid
,
1483 OUT UINTN
*Size OPTIONAL
,
1484 OUT UINT32
*Attr OPTIONAL
1490 ASSERT(Name
!= NULL
&& Guid
!= NULL
&& Value
!= NULL
);
1493 // Try to get the variable size.
1505 Status
= gRT
->GetVariable((CHAR16
*)Name
, (EFI_GUID
*)Guid
, Attr
, &BufferSize
, *Value
);
1506 if (Status
!= EFI_BUFFER_TOO_SMALL
) {
1511 // Allocate buffer to get the variable.
1513 *Value
= AllocatePool(BufferSize
);
1514 ASSERT(*Value
!= NULL
);
1515 if (*Value
== NULL
) {
1516 return EFI_OUT_OF_RESOURCES
;
1520 // Get the variable data.
1522 Status
= gRT
->GetVariable((CHAR16
*)Name
, (EFI_GUID
*)Guid
, Attr
, &BufferSize
, *Value
);
1523 if (EFI_ERROR(Status
)) {
1536 Returns a pointer to an allocated buffer that contains the contents of a
1537 variable retrieved through the UEFI Runtime Service GetVariable(). This
1538 function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1539 The returned buffer is allocated using AllocatePool(). The caller is
1540 responsible for freeing this buffer with FreePool().
1542 If Name is NULL, then ASSERT().
1543 If Value is NULL, then ASSERT().
1545 @param[in] Name The pointer to a Null-terminated Unicode string.
1546 @param[out] Value The buffer point saved the variable info.
1547 @param[out] Size The buffer size of the variable.
1549 @return EFI_OUT_OF_RESOURCES Allocate buffer failed.
1550 @return EFI_SUCCESS Find the specified variable.
1551 @return Others Errors Return errors from call to gRT->GetVariable.
1556 GetEfiGlobalVariable2 (
1557 IN CONST CHAR16
*Name
,
1559 OUT UINTN
*Size OPTIONAL
1562 return GetVariable2 (Name
, &gEfiGlobalVariableGuid
, Value
, Size
);
1566 Returns a pointer to an allocated buffer that contains the best matching language
1567 from a set of supported languages.
1569 This function supports both ISO 639-2 and RFC 4646 language codes, but language
1570 code types may not be mixed in a single call to this function. The language
1571 code returned is allocated using AllocatePool(). The caller is responsible for
1572 freeing the allocated buffer using FreePool(). This function supports a variable
1573 argument list that allows the caller to pass in a prioritized list of language
1574 codes to test against all the language codes in SupportedLanguages.
1576 If SupportedLanguages is NULL, then ASSERT().
1578 @param[in] SupportedLanguages A pointer to a Null-terminated ASCII string that
1579 contains a set of language codes in the format
1580 specified by Iso639Language.
1581 @param[in] Iso639Language If not zero, then all language codes are assumed to be
1582 in ISO 639-2 format. If zero, then all language
1583 codes are assumed to be in RFC 4646 language format
1584 @param[in] ... A variable argument list that contains pointers to
1585 Null-terminated ASCII strings that contain one or more
1586 language codes in the format specified by Iso639Language.
1587 The first language code from each of these language
1588 code lists is used to determine if it is an exact or
1589 close match to any of the language codes in
1590 SupportedLanguages. Close matches only apply to RFC 4646
1591 language codes, and the matching algorithm from RFC 4647
1592 is used to determine if a close match is present. If
1593 an exact or close match is found, then the matching
1594 language code from SupportedLanguages is returned. If
1595 no matches are found, then the next variable argument
1596 parameter is evaluated. The variable argument list
1597 is terminated by a NULL.
1599 @retval NULL The best matching language could not be found in SupportedLanguages.
1600 @retval NULL There are not enough resources available to return the best matching
1602 @retval Other A pointer to a Null-terminated ASCII string that is the best matching
1603 language in SupportedLanguages.
1609 IN CONST CHAR8
*SupportedLanguages
,
1610 IN UINTN Iso639Language
,
1616 UINTN CompareLength
;
1617 UINTN LanguageLength
;
1618 CONST CHAR8
*Supported
;
1619 CHAR8
*BestLanguage
;
1621 ASSERT (SupportedLanguages
!= NULL
);
1623 VA_START (Args
, Iso639Language
);
1624 while ((Language
= VA_ARG (Args
, CHAR8
*)) != NULL
) {
1626 // Default to ISO 639-2 mode
1629 LanguageLength
= MIN (3, AsciiStrLen (Language
));
1632 // If in RFC 4646 mode, then determine the length of the first RFC 4646 language code in Language
1634 if (Iso639Language
== 0) {
1635 for (LanguageLength
= 0; Language
[LanguageLength
] != 0 && Language
[LanguageLength
] != ';'; LanguageLength
++);
1639 // Trim back the length of Language used until it is empty
1641 while (LanguageLength
> 0) {
1643 // Loop through all language codes in SupportedLanguages
1645 for (Supported
= SupportedLanguages
; *Supported
!= '\0'; Supported
+= CompareLength
) {
1647 // In RFC 4646 mode, then Loop through all language codes in SupportedLanguages
1649 if (Iso639Language
== 0) {
1651 // Skip ';' characters in Supported
1653 for (; *Supported
!= '\0' && *Supported
== ';'; Supported
++);
1655 // Determine the length of the next language code in Supported
1657 for (CompareLength
= 0; Supported
[CompareLength
] != 0 && Supported
[CompareLength
] != ';'; CompareLength
++);
1659 // If Language is longer than the Supported, then skip to the next language
1661 if (LanguageLength
> CompareLength
) {
1666 // See if the first LanguageLength characters in Supported match Language
1668 if (AsciiStrnCmp (Supported
, Language
, LanguageLength
) == 0) {
1671 // Allocate, copy, and return the best matching language code from SupportedLanguages
1673 BestLanguage
= AllocateZeroPool (CompareLength
+ 1);
1674 if (BestLanguage
== NULL
) {
1677 return CopyMem (BestLanguage
, Supported
, CompareLength
);
1681 if (Iso639Language
!= 0) {
1683 // If ISO 639 mode, then each language can only be tested once
1688 // If RFC 4646 mode, then trim Language from the right to the next '-' character
1690 for (LanguageLength
--; LanguageLength
> 0 && Language
[LanguageLength
] != '-'; LanguageLength
--);
1697 // No matches were found
1703 Returns an array of protocol instance that matches the given protocol.
1705 @param[in] Protocol Provides the protocol to search for.
1706 @param[out] NoProtocols The number of protocols returned in Buffer.
1707 @param[out] Buffer A pointer to the buffer to return the requested
1708 array of protocol instances that match Protocol.
1709 The returned buffer is allocated using
1710 EFI_BOOT_SERVICES.AllocatePool(). The caller is
1711 responsible for freeing this buffer with
1712 EFI_BOOT_SERVICES.FreePool().
1714 @retval EFI_SUCCESS The array of protocols was returned in Buffer,
1715 and the number of protocols in Buffer was
1716 returned in NoProtocols.
1717 @retval EFI_NOT_FOUND No protocols found.
1718 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
1720 @retval EFI_INVALID_PARAMETER Protocol is NULL.
1721 @retval EFI_INVALID_PARAMETER NoProtocols is NULL.
1722 @retval EFI_INVALID_PARAMETER Buffer is NULL.
1727 EfiLocateProtocolBuffer (
1728 IN EFI_GUID
*Protocol
,
1729 OUT UINTN
*NoProtocols
,
1735 EFI_HANDLE
*HandleBuffer
;
1739 // Check input parameters
1741 if (Protocol
== NULL
|| NoProtocols
== NULL
|| Buffer
== NULL
) {
1742 return EFI_INVALID_PARAMETER
;
1746 // Initialze output parameters
1752 // Retrieve the array of handles that support Protocol
1754 Status
= gBS
->LocateHandleBuffer (
1761 if (EFI_ERROR (Status
)) {
1766 // Allocate array of protocol instances
1768 Status
= gBS
->AllocatePool (
1769 EfiBootServicesData
,
1770 NoHandles
* sizeof (VOID
*),
1773 if (EFI_ERROR (Status
)) {
1775 // Free the handle buffer
1777 gBS
->FreePool (HandleBuffer
);
1778 return EFI_OUT_OF_RESOURCES
;
1780 ZeroMem (*Buffer
, NoHandles
* sizeof (VOID
*));
1783 // Lookup Protocol on each handle in HandleBuffer to fill in the array of
1784 // protocol instances. Handle case where protocol instance was present when
1785 // LocateHandleBuffer() was called, but is not present when HandleProtocol()
1788 for (Index
= 0, *NoProtocols
= 0; Index
< NoHandles
; Index
++) {
1789 Status
= gBS
->HandleProtocol (
1790 HandleBuffer
[Index
],
1792 &((*Buffer
)[*NoProtocols
])
1794 if (!EFI_ERROR (Status
)) {
1800 // Free the handle buffer
1802 gBS
->FreePool (HandleBuffer
);
1805 // Make sure at least one protocol instance was found
1807 if (*NoProtocols
== 0) {
1808 gBS
->FreePool (*Buffer
);
1810 return EFI_NOT_FOUND
;
1817 Open or create a file or directory, possibly creating the chain of
1818 directories leading up to the directory.
1820 EfiOpenFileByDevicePath() first locates EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on
1821 FilePath, and opens the root directory of that filesystem with
1822 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume().
1824 On the remaining device path, the longest initial sequence of
1825 FILEPATH_DEVICE_PATH nodes is node-wise traversed with
1826 EFI_FILE_PROTOCOL.Open().
1828 (As a consequence, if OpenMode includes EFI_FILE_MODE_CREATE, and Attributes
1829 includes EFI_FILE_DIRECTORY, and each FILEPATH_DEVICE_PATH specifies a single
1830 pathname component, then EfiOpenFileByDevicePath() ensures that the specified
1831 series of subdirectories exist on return.)
1833 The EFI_FILE_PROTOCOL identified by the last FILEPATH_DEVICE_PATH node is
1834 output to the caller; intermediate EFI_FILE_PROTOCOL instances are closed. If
1835 there are no FILEPATH_DEVICE_PATH nodes past the node that identifies the
1836 filesystem, then the EFI_FILE_PROTOCOL of the root directory of the
1837 filesystem is output to the caller. If a device path node that is different
1838 from FILEPATH_DEVICE_PATH is encountered relative to the filesystem, the
1839 traversal is stopped with an error, and a NULL EFI_FILE_PROTOCOL is output.
1841 @param[in,out] FilePath On input, the device path to the file or directory
1842 to open or create. The caller is responsible for
1843 ensuring that the device path pointed-to by FilePath
1844 is well-formed. On output, FilePath points one past
1845 the last node in the original device path that has
1846 been successfully processed. FilePath is set on
1847 output even if EfiOpenFileByDevicePath() returns an
1850 @param[out] File On error, File is set to NULL. On success, File is
1851 set to the EFI_FILE_PROTOCOL of the root directory
1852 of the filesystem, if there are no
1853 FILEPATH_DEVICE_PATH nodes in FilePath; otherwise,
1854 File is set to the EFI_FILE_PROTOCOL identified by
1855 the last node in FilePath.
1857 @param[in] OpenMode The OpenMode parameter to pass to
1858 EFI_FILE_PROTOCOL.Open().
1860 @param[in] Attributes The Attributes parameter to pass to
1861 EFI_FILE_PROTOCOL.Open().
1863 @retval EFI_SUCCESS The file or directory has been opened or
1866 @retval EFI_INVALID_PARAMETER FilePath is NULL; or File is NULL; or FilePath
1867 contains a device path node, past the node
1869 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL, that is not a
1870 FILEPATH_DEVICE_PATH node.
1872 @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
1874 @return Error codes propagated from the
1875 LocateDevicePath() and OpenProtocol() boot
1876 services, and from the
1877 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume()
1878 and EFI_FILE_PROTOCOL.Open() member functions.
1882 EfiOpenFileByDevicePath (
1883 IN OUT EFI_DEVICE_PATH_PROTOCOL
**FilePath
,
1884 OUT EFI_FILE_PROTOCOL
**File
,
1886 IN UINT64 Attributes
1890 EFI_HANDLE FileSystemHandle
;
1891 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
*FileSystem
;
1892 EFI_FILE_PROTOCOL
*LastFile
;
1893 FILEPATH_DEVICE_PATH
*FilePathNode
;
1894 CHAR16
*AlignedPathName
;
1896 EFI_FILE_PROTOCOL
*NextFile
;
1899 return EFI_INVALID_PARAMETER
;
1903 if (FilePath
== NULL
) {
1904 return EFI_INVALID_PARAMETER
;
1908 // Look up the filesystem.
1910 Status
= gBS
->LocateDevicePath (
1911 &gEfiSimpleFileSystemProtocolGuid
,
1915 if (EFI_ERROR (Status
)) {
1918 Status
= gBS
->OpenProtocol (
1920 &gEfiSimpleFileSystemProtocolGuid
,
1921 (VOID
**)&FileSystem
,
1924 EFI_OPEN_PROTOCOL_GET_PROTOCOL
1926 if (EFI_ERROR (Status
)) {
1931 // Open the root directory of the filesystem. After this operation succeeds,
1932 // we have to release LastFile on error.
1934 Status
= FileSystem
->OpenVolume (FileSystem
, &LastFile
);
1935 if (EFI_ERROR (Status
)) {
1940 // Traverse the device path nodes relative to the filesystem.
1942 while (!IsDevicePathEnd (*FilePath
)) {
1943 if (DevicePathType (*FilePath
) != MEDIA_DEVICE_PATH
||
1944 DevicePathSubType (*FilePath
) != MEDIA_FILEPATH_DP
) {
1945 Status
= EFI_INVALID_PARAMETER
;
1948 FilePathNode
= (FILEPATH_DEVICE_PATH
*)*FilePath
;
1951 // FilePathNode->PathName may be unaligned, and the UEFI specification
1952 // requires pointers that are passed to protocol member functions to be
1953 // aligned. Create an aligned copy of the pathname if necessary.
1955 if ((UINTN
)FilePathNode
->PathName
% sizeof *FilePathNode
->PathName
== 0) {
1956 AlignedPathName
= NULL
;
1957 PathName
= FilePathNode
->PathName
;
1959 AlignedPathName
= AllocateCopyPool (
1960 (DevicePathNodeLength (FilePathNode
) -
1961 SIZE_OF_FILEPATH_DEVICE_PATH
),
1962 FilePathNode
->PathName
1964 if (AlignedPathName
== NULL
) {
1965 Status
= EFI_OUT_OF_RESOURCES
;
1968 PathName
= AlignedPathName
;
1972 // Open or create the file corresponding to the next pathname fragment.
1974 Status
= LastFile
->Open (
1983 // Release any AlignedPathName on both error and success paths; PathName is
1984 // no longer needed.
1986 if (AlignedPathName
!= NULL
) {
1987 FreePool (AlignedPathName
);
1989 if (EFI_ERROR (Status
)) {
1994 // Advance to the next device path node.
1996 LastFile
->Close (LastFile
);
1997 LastFile
= NextFile
;
1998 *FilePath
= NextDevicePathNode (FilePathNode
);
2005 LastFile
->Close (LastFile
);
2008 // We are on the error path; we must have set an error Status for returning
2011 ASSERT (EFI_ERROR (Status
));