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 Compare whether two names of languages are identical.
19 @param Language1 Name of language 1.
20 @param Language2 Name of language 2.
22 @retval TRUE Language 1 and language 2 are the same.
23 @retval FALSE Language 1 and language 2 are not the same.
27 CompareIso639LanguageCode (
28 IN CONST CHAR8
*Language1
,
29 IN CONST CHAR8
*Language2
35 Name1
= ReadUnaligned24 ((CONST UINT32
*) Language1
);
36 Name2
= ReadUnaligned24 ((CONST UINT32
*) Language2
);
38 return (BOOLEAN
) (Name1
== Name2
);
42 Retrieves a pointer to the system configuration table from the EFI System Table
43 based on a specified GUID.
45 This function searches the list of configuration tables stored in the EFI System Table
46 for a table with a GUID that matches TableGuid. If a match is found, then a pointer to
47 the configuration table is returned in Table., and EFI_SUCCESS is returned. If a matching GUID
48 is not found, then EFI_NOT_FOUND is returned.
49 If TableGuid is NULL, then ASSERT().
50 If Table is NULL, then ASSERT().
52 @param TableGuid Pointer to table's GUID type..
53 @param Table Pointer to the table associated with TableGuid in the EFI System Table.
55 @retval EFI_SUCCESS A configuration table matching TableGuid was found.
56 @retval EFI_NOT_FOUND A configuration table matching TableGuid could not be found.
61 EfiGetSystemConfigurationTable (
62 IN EFI_GUID
*TableGuid
,
66 EFI_SYSTEM_TABLE
*SystemTable
;
69 ASSERT (TableGuid
!= NULL
);
70 ASSERT (Table
!= NULL
);
74 for (Index
= 0; Index
< SystemTable
->NumberOfTableEntries
; Index
++) {
75 if (CompareGuid (TableGuid
, &(SystemTable
->ConfigurationTable
[Index
].VendorGuid
))) {
76 *Table
= SystemTable
->ConfigurationTable
[Index
].VendorTable
;
85 Creates and returns a notification event and registers that event with all the protocol
86 instances specified by ProtocolGuid.
88 This function causes the notification function to be executed for every protocol of type
89 ProtocolGuid instance that exists in the system when this function is invoked. If there are
90 no instances of ProtocolGuid in the handle database at the time this function is invoked,
91 then the notification function is still executed one time. In addition, every time a protocol
92 of type ProtocolGuid instance is installed or reinstalled, the notification function is also
93 executed. This function returns the notification event that was created.
94 If ProtocolGuid is NULL, then ASSERT().
95 If NotifyTpl is not a legal TPL value, then ASSERT().
96 If NotifyFunction is NULL, then ASSERT().
97 If Registration is NULL, then ASSERT().
100 @param ProtocolGuid Supplies GUID of the protocol upon whose installation the event is fired.
101 @param NotifyTpl Supplies the task priority level of the event notifications.
102 @param NotifyFunction Supplies the function to notify when the event is signaled.
103 @param NotifyContext The context parameter to pass to NotifyFunction.
104 @param Registration A pointer to a memory location to receive the registration value.
105 This value is passed to LocateHandle() to obtain new handles that
106 have been added that support the ProtocolGuid-specified protocol.
108 @return The notification event that was created.
113 EfiCreateProtocolNotifyEvent(
114 IN EFI_GUID
*ProtocolGuid
,
115 IN EFI_TPL NotifyTpl
,
116 IN EFI_EVENT_NOTIFY NotifyFunction
,
117 IN VOID
*NotifyContext
, OPTIONAL
118 OUT VOID
**Registration
124 ASSERT (ProtocolGuid
!= NULL
);
125 ASSERT (NotifyFunction
!= NULL
);
126 ASSERT (Registration
!= NULL
);
132 Status
= gBS
->CreateEvent (
139 ASSERT_EFI_ERROR (Status
);
142 // Register for protocol notifications on this event
145 Status
= gBS
->RegisterProtocolNotify (
151 ASSERT_EFI_ERROR (Status
);
154 // Kick the event so we will perform an initial pass of
155 // current installed drivers
158 gBS
->SignalEvent (Event
);
163 Creates a named event that can be signaled with EfiNamedEventSignal().
165 This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.
166 This event is signaled with EfiNamedEventSignal(). This provides the ability for one or more
167 listeners on the same event named by the GUID specified by Name.
168 If Name is NULL, then ASSERT().
169 If NotifyTpl is not a legal TPL value, then ASSERT().
170 If NotifyFunction is NULL, then ASSERT().
172 @param Name Supplies GUID name of the event.
173 @param NotifyTpl Supplies the task priority level of the event notifications.
174 @param NotifyFunction Supplies the function to notify when the event is signaled.
175 @param NotifyContext The context parameter to pass to NotifyFunction.
176 @param Registration A pointer to a memory location to receive the registration value.
178 @retval EFI_SUCCESS A named event was created.
179 @retval EFI_OUT_OF_RESOURCES There are not enough resource to create the named event.
184 EfiNamedEventListen (
185 IN CONST EFI_GUID
*Name
,
186 IN EFI_TPL NotifyTpl
,
187 IN EFI_EVENT_NOTIFY NotifyFunction
,
188 IN CONST VOID
*NotifyContext
, OPTIONAL
189 OUT VOID
*Registration OPTIONAL
194 VOID
*RegistrationLocal
;
196 ASSERT (Name
!= NULL
);
197 ASSERT (NotifyFunction
!= NULL
);
198 ASSERT (NotifyTpl
<= TPL_HIGH_LEVEL
);
203 Status
= gBS
->CreateEvent (
207 (VOID
*) NotifyContext
,
210 ASSERT_EFI_ERROR (Status
);
213 // The Registration is not optional to RegisterProtocolNotify().
214 // To make it optional to EfiNamedEventListen(), may need to substitute with a local.
216 if (Registration
!= NULL
) {
217 RegistrationLocal
= Registration
;
219 RegistrationLocal
= &RegistrationLocal
;
223 // Register for an installation of protocol interface
226 Status
= gBS
->RegisterProtocolNotify (
231 ASSERT_EFI_ERROR (Status
);
237 Signals a named event created with EfiNamedEventListen().
239 This function signals the named event specified by Name. The named event must have been
240 created with EfiNamedEventListen().
241 If Name is NULL, then ASSERT().
243 @param Name Supplies GUID name of the event.
245 @retval EFI_SUCCESS A named event was signaled.
246 @retval EFI_OUT_OF_RESOURCES There are not enough resource to signal the named event.
251 EfiNamedEventSignal (
252 IN CONST EFI_GUID
*Name
258 ASSERT(Name
!= NULL
);
261 Status
= gBS
->InstallProtocolInterface (
264 EFI_NATIVE_INTERFACE
,
267 ASSERT_EFI_ERROR (Status
);
269 Status
= gBS
->UninstallProtocolInterface (
274 ASSERT_EFI_ERROR (Status
);
280 Signals an event group by placing a new event in the group temporarily and
283 @param[in] EventGroup Supplies the unique identifier of the event
286 @retval EFI_SUCCESS The event group was signaled successfully.
287 @retval EFI_INVALID_PARAMETER EventGroup is NULL.
288 @return Error codes that report problems about event
289 creation or signaling.
293 EfiEventGroupSignal (
294 IN CONST EFI_GUID
*EventGroup
300 if (EventGroup
== NULL
) {
301 return EFI_INVALID_PARAMETER
;
304 Status
= gBS
->CreateEventEx (
307 EfiEventEmptyFunction
,
312 if (EFI_ERROR (Status
)) {
316 Status
= gBS
->SignalEvent (Event
);
317 gBS
->CloseEvent (Event
);
323 An empty function that can be used as NotifyFunction parameter of
324 CreateEvent() or CreateEventEx().
326 @param Event Event whose notification function is being invoked.
327 @param Context The pointer to the notification function's context,
328 which is implementation-dependent.
333 EfiEventEmptyFunction (
341 Returns the current TPL.
343 This function returns the current TPL. There is no EFI service to directly
344 retrieve the current TPL. Instead, the RaiseTPL() function is used to raise
345 the TPL to TPL_HIGH_LEVEL. This will return the current TPL. The TPL level
346 can then immediately be restored back to the current TPL level with a call
349 @return The current TPL.
360 Tpl
= gBS
->RaiseTPL (TPL_HIGH_LEVEL
);
361 gBS
->RestoreTPL (Tpl
);
368 Initializes a basic mutual exclusion lock.
370 This function initializes a basic mutual exclusion lock to the released state
371 and returns the lock. Each lock provides mutual exclusion access at its task
372 priority level. Since there is no preemption or multiprocessor support in EFI,
373 acquiring the lock only consists of raising to the locks TPL.
374 If Lock is NULL, then ASSERT().
375 If Priority is not a valid TPL value, then ASSERT().
377 @param Lock A pointer to the lock data structure to initialize.
378 @param Priority EFI TPL associated with the lock.
386 IN OUT EFI_LOCK
*Lock
,
390 ASSERT (Lock
!= NULL
);
391 ASSERT (Priority
<= TPL_HIGH_LEVEL
);
393 Lock
->Tpl
= Priority
;
394 Lock
->OwnerTpl
= TPL_APPLICATION
;
395 Lock
->Lock
= EfiLockReleased
;
400 Acquires ownership of a lock.
402 This function raises the system's current task priority level to the task
403 priority level of the mutual exclusion lock. Then, it places the lock in the
405 If Lock is NULL, then ASSERT().
406 If Lock is not initialized, then ASSERT().
407 If Lock is already in the acquired state, then ASSERT().
409 @param Lock A pointer to the lock to acquire.
418 ASSERT (Lock
!= NULL
);
419 ASSERT (Lock
->Lock
== EfiLockReleased
);
421 Lock
->OwnerTpl
= gBS
->RaiseTPL (Lock
->Tpl
);
422 Lock
->Lock
= EfiLockAcquired
;
426 Acquires ownership of a lock.
428 This function raises the system's current task priority level to the task priority
429 level of the mutual exclusion lock. Then, it attempts to place the lock in the acquired state.
430 If the lock is already in the acquired state, then EFI_ACCESS_DENIED is returned.
431 Otherwise, EFI_SUCCESS is returned.
432 If Lock is NULL, then ASSERT().
433 If Lock is not initialized, then ASSERT().
435 @param Lock A pointer to the lock to acquire.
437 @retval EFI_SUCCESS The lock was acquired.
438 @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
443 EfiAcquireLockOrFail (
448 ASSERT (Lock
!= NULL
);
449 ASSERT (Lock
->Lock
!= EfiLockUninitialized
);
451 if (Lock
->Lock
== EfiLockAcquired
) {
453 // Lock is already owned, so bail out
455 return EFI_ACCESS_DENIED
;
458 Lock
->OwnerTpl
= gBS
->RaiseTPL (Lock
->Tpl
);
460 Lock
->Lock
= EfiLockAcquired
;
466 Releases ownership of a lock.
468 This function transitions a mutual exclusion lock from the acquired state to
469 the released state, and restores the system's task priority level to its
471 If Lock is NULL, then ASSERT().
472 If Lock is not initialized, then ASSERT().
473 If Lock is already in the released state, then ASSERT().
475 @param Lock A pointer to the lock to release.
486 ASSERT (Lock
!= NULL
);
487 ASSERT (Lock
->Lock
== EfiLockAcquired
);
489 Tpl
= Lock
->OwnerTpl
;
491 Lock
->Lock
= EfiLockReleased
;
493 gBS
->RestoreTPL (Tpl
);
497 Tests whether a controller handle is being managed by a specific driver.
499 This function tests whether the driver specified by DriverBindingHandle is
500 currently managing the controller specified by ControllerHandle. This test
501 is performed by evaluating if the the protocol specified by ProtocolGuid is
502 present on ControllerHandle and is was opened by DriverBindingHandle with an
503 attribute of EFI_OPEN_PROTOCOL_BY_DRIVER.
504 If ProtocolGuid is NULL, then ASSERT().
506 @param ControllerHandle A handle for a controller to test.
507 @param DriverBindingHandle Specifies the driver binding handle for the
509 @param ProtocolGuid Specifies the protocol that the driver specified
510 by DriverBindingHandle opens in its Start()
513 @retval EFI_SUCCESS ControllerHandle is managed by the driver
514 specified by DriverBindingHandle.
515 @retval EFI_UNSUPPORTED ControllerHandle is not managed by the driver
516 specified by DriverBindingHandle.
521 EfiTestManagedDevice (
522 IN CONST EFI_HANDLE ControllerHandle
,
523 IN CONST EFI_HANDLE DriverBindingHandle
,
524 IN CONST EFI_GUID
*ProtocolGuid
528 VOID
*ManagedInterface
;
530 ASSERT (ProtocolGuid
!= NULL
);
532 Status
= gBS
->OpenProtocol (
534 (EFI_GUID
*) ProtocolGuid
,
538 EFI_OPEN_PROTOCOL_BY_DRIVER
540 if (!EFI_ERROR (Status
)) {
543 (EFI_GUID
*) ProtocolGuid
,
547 return EFI_UNSUPPORTED
;
550 if (Status
!= EFI_ALREADY_STARTED
) {
551 return EFI_UNSUPPORTED
;
558 Tests whether a child handle is a child device of the controller.
560 This function tests whether ChildHandle is one of the children of
561 ControllerHandle. This test is performed by checking to see if the protocol
562 specified by ProtocolGuid is present on ControllerHandle and opened by
563 ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
564 If ProtocolGuid is NULL, then ASSERT().
566 @param ControllerHandle A handle for a (parent) controller to test.
567 @param ChildHandle A child handle to test.
568 @param ProtocolGuid Supplies the protocol that the child controller
569 opens on its parent controller.
571 @retval EFI_SUCCESS ChildHandle is a child of the ControllerHandle.
572 @retval EFI_UNSUPPORTED ChildHandle is not a child of the
579 IN CONST EFI_HANDLE ControllerHandle
,
580 IN CONST EFI_HANDLE ChildHandle
,
581 IN CONST EFI_GUID
*ProtocolGuid
585 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
*OpenInfoBuffer
;
589 ASSERT (ProtocolGuid
!= NULL
);
592 // Retrieve the list of agents that are consuming the specific protocol
593 // on ControllerHandle.
595 Status
= gBS
->OpenProtocolInformation (
597 (EFI_GUID
*) ProtocolGuid
,
601 if (EFI_ERROR (Status
)) {
602 return EFI_UNSUPPORTED
;
606 // Inspect if ChildHandle is one of the agents.
608 Status
= EFI_UNSUPPORTED
;
609 for (Index
= 0; Index
< EntryCount
; Index
++) {
610 if ((OpenInfoBuffer
[Index
].ControllerHandle
== ChildHandle
) &&
611 (OpenInfoBuffer
[Index
].Attributes
& EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
) != 0) {
612 Status
= EFI_SUCCESS
;
617 FreePool (OpenInfoBuffer
);
622 This function looks up a Unicode string in UnicodeStringTable.
624 If Language is a member of SupportedLanguages and a Unicode string is found in
625 UnicodeStringTable that matches the language code specified by Language, then it
626 is returned in UnicodeString.
628 @param Language A pointer to the ISO 639-2 language code for the
629 Unicode string to look up and return.
630 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
631 that the Unicode string table supports. Language
632 must be a member of this set.
633 @param UnicodeStringTable A pointer to the table of Unicode strings.
634 @param UnicodeString A pointer to the Unicode string from UnicodeStringTable
635 that matches the language specified by Language.
637 @retval EFI_SUCCESS The Unicode string that matches the language
638 specified by Language was found
639 in the table of Unicode strings UnicodeStringTable,
640 and it was returned in UnicodeString.
641 @retval EFI_INVALID_PARAMETER Language is NULL.
642 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
643 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
644 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
645 @retval EFI_UNSUPPORTED The language specified by Language is not a
646 member of SupportedLanguages.
647 @retval EFI_UNSUPPORTED The language specified by Language is not
648 supported by UnicodeStringTable.
653 LookupUnicodeString (
654 IN CONST CHAR8
*Language
,
655 IN CONST CHAR8
*SupportedLanguages
,
656 IN CONST EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
,
657 OUT CHAR16
**UnicodeString
661 // Make sure the parameters are valid
663 if (Language
== NULL
|| UnicodeString
== NULL
) {
664 return EFI_INVALID_PARAMETER
;
668 // If there are no supported languages, or the Unicode String Table is empty, then the
669 // Unicode String specified by Language is not supported by this Unicode String Table
671 if (SupportedLanguages
== NULL
|| UnicodeStringTable
== NULL
) {
672 return EFI_UNSUPPORTED
;
676 // Make sure Language is in the set of Supported Languages
678 while (*SupportedLanguages
!= 0) {
679 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
682 // Search the Unicode String Table for the matching Language specifier
684 while (UnicodeStringTable
->Language
!= NULL
) {
685 if (CompareIso639LanguageCode (Language
, UnicodeStringTable
->Language
)) {
688 // A matching string was found, so return it
690 *UnicodeString
= UnicodeStringTable
->UnicodeString
;
694 UnicodeStringTable
++;
697 return EFI_UNSUPPORTED
;
700 SupportedLanguages
+= 3;
703 return EFI_UNSUPPORTED
;
709 This function looks up a Unicode string in UnicodeStringTable.
711 If Language is a member of SupportedLanguages and a Unicode string is found in
712 UnicodeStringTable that matches the language code specified by Language, then
713 it is returned in UnicodeString.
715 @param Language A pointer to an ASCII string containing the ISO 639-2 or the
716 RFC 4646 language code for the Unicode string to look up and
717 return. If Iso639Language is TRUE, then this ASCII string is
718 not assumed to be Null-terminated, and only the first three
719 characters are used. If Iso639Language is FALSE, then this ASCII
720 string must be Null-terminated.
721 @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains a
722 set of ISO 639-2 or RFC 4646 language codes that the Unicode
723 string table supports. Language must be a member of this set.
724 If Iso639Language is TRUE, then this string contains one or more
725 ISO 639-2 language codes with no separator characters. If Iso639Language
726 is FALSE, then is string contains one or more RFC 4646 language
727 codes separated by ';'.
728 @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
729 is defined in "Related Definitions".
730 @param UnicodeString A pointer to the Null-terminated Unicode string from UnicodeStringTable
731 that matches the language specified by Language.
732 @param Iso639Language Specifies the supported language code format. If it is TRUE, then
733 Language and SupportedLanguages follow ISO 639-2 language code format.
734 Otherwise, they follow RFC 4646 language code format.
737 @retval EFI_SUCCESS The Unicode string that matches the language specified by Language
738 was found in the table of Unicode strings UnicodeStringTable, and
739 it was returned in UnicodeString.
740 @retval EFI_INVALID_PARAMETER Language is NULL.
741 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
742 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
743 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
744 @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages.
745 @retval EFI_UNSUPPORTED The language specified by Language is not supported by UnicodeStringTable.
750 LookupUnicodeString2 (
751 IN CONST CHAR8
*Language
,
752 IN CONST CHAR8
*SupportedLanguages
,
753 IN CONST EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
,
754 OUT CHAR16
**UnicodeString
,
755 IN BOOLEAN Iso639Language
760 CHAR8
*LanguageString
;
763 // Make sure the parameters are valid
765 if (Language
== NULL
|| UnicodeString
== NULL
) {
766 return EFI_INVALID_PARAMETER
;
770 // If there are no supported languages, or the Unicode String Table is empty, then the
771 // Unicode String specified by Language is not supported by this Unicode String Table
773 if (SupportedLanguages
== NULL
|| UnicodeStringTable
== NULL
) {
774 return EFI_UNSUPPORTED
;
778 // Make sure Language is in the set of Supported Languages
781 while (*SupportedLanguages
!= 0) {
782 if (Iso639Language
) {
783 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
787 SupportedLanguages
+= 3;
789 for (Index
= 0; SupportedLanguages
[Index
] != 0 && SupportedLanguages
[Index
] != ';'; Index
++);
790 if ((AsciiStrnCmp(SupportedLanguages
, Language
, Index
) == 0) && (Language
[Index
] == 0)) {
794 SupportedLanguages
+= Index
;
795 for (; *SupportedLanguages
!= 0 && *SupportedLanguages
== ';'; SupportedLanguages
++);
800 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
803 return EFI_UNSUPPORTED
;
807 // Search the Unicode String Table for the matching Language specifier
809 while (UnicodeStringTable
->Language
!= NULL
) {
810 LanguageString
= UnicodeStringTable
->Language
;
811 while (0 != *LanguageString
) {
812 for (Index
= 0 ;LanguageString
[Index
] != 0 && LanguageString
[Index
] != ';'; Index
++);
813 if (AsciiStrnCmp(LanguageString
, Language
, Index
) == 0) {
814 *UnicodeString
= UnicodeStringTable
->UnicodeString
;
817 LanguageString
+= Index
;
818 for (Index
= 0 ;LanguageString
[Index
] != 0 && LanguageString
[Index
] == ';'; Index
++);
820 UnicodeStringTable
++;
823 return EFI_UNSUPPORTED
;
828 This function adds a Unicode string to UnicodeStringTable.
830 If Language is a member of SupportedLanguages then UnicodeString is added to
831 UnicodeStringTable. New buffers are allocated for both Language and
832 UnicodeString. The contents of Language and UnicodeString are copied into
833 these new buffers. These buffers are automatically freed when
834 FreeUnicodeStringTable() is called.
836 @param Language A pointer to the ISO 639-2 language code for the Unicode
838 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
839 that the Unicode string table supports.
840 Language must be a member of this set.
841 @param UnicodeStringTable A pointer to the table of Unicode strings.
842 @param UnicodeString A pointer to the Unicode string to add.
844 @retval EFI_SUCCESS The Unicode string that matches the language
845 specified by Language was found in the table of
846 Unicode strings UnicodeStringTable, and it was
847 returned in UnicodeString.
848 @retval EFI_INVALID_PARAMETER Language is NULL.
849 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
850 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
851 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
852 @retval EFI_ALREADY_STARTED A Unicode string with language Language is
853 already present in UnicodeStringTable.
854 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another
855 Unicode string to UnicodeStringTable.
856 @retval EFI_UNSUPPORTED The language specified by Language is not a
857 member of SupportedLanguages.
863 IN CONST CHAR8
*Language
,
864 IN CONST CHAR8
*SupportedLanguages
,
865 IN OUT EFI_UNICODE_STRING_TABLE
**UnicodeStringTable
,
866 IN CONST CHAR16
*UnicodeString
869 UINTN NumberOfEntries
;
870 EFI_UNICODE_STRING_TABLE
*OldUnicodeStringTable
;
871 EFI_UNICODE_STRING_TABLE
*NewUnicodeStringTable
;
872 UINTN UnicodeStringLength
;
875 // Make sure the parameter are valid
877 if (Language
== NULL
|| UnicodeString
== NULL
|| UnicodeStringTable
== NULL
) {
878 return EFI_INVALID_PARAMETER
;
882 // If there are no supported languages, then a Unicode String can not be added
884 if (SupportedLanguages
== NULL
) {
885 return EFI_UNSUPPORTED
;
889 // If the Unicode String is empty, then a Unicode String can not be added
891 if (UnicodeString
[0] == 0) {
892 return EFI_INVALID_PARAMETER
;
896 // Make sure Language is a member of SupportedLanguages
898 while (*SupportedLanguages
!= 0) {
899 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
902 // Determine the size of the Unicode String Table by looking for a NULL Language entry
905 if (*UnicodeStringTable
!= NULL
) {
906 OldUnicodeStringTable
= *UnicodeStringTable
;
907 while (OldUnicodeStringTable
->Language
!= NULL
) {
908 if (CompareIso639LanguageCode (Language
, OldUnicodeStringTable
->Language
)) {
909 return EFI_ALREADY_STARTED
;
912 OldUnicodeStringTable
++;
918 // Allocate space for a new Unicode String Table. It must hold the current number of
919 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
922 NewUnicodeStringTable
= AllocatePool ((NumberOfEntries
+ 2) * sizeof (EFI_UNICODE_STRING_TABLE
));
923 if (NewUnicodeStringTable
== NULL
) {
924 return EFI_OUT_OF_RESOURCES
;
928 // If the current Unicode String Table contains any entries, then copy them to the
929 // newly allocated Unicode String Table.
931 if (*UnicodeStringTable
!= NULL
) {
933 NewUnicodeStringTable
,
935 NumberOfEntries
* sizeof (EFI_UNICODE_STRING_TABLE
)
940 // Allocate space for a copy of the Language specifier
942 NewUnicodeStringTable
[NumberOfEntries
].Language
= AllocateCopyPool (3, Language
);
943 if (NewUnicodeStringTable
[NumberOfEntries
].Language
== NULL
) {
944 gBS
->FreePool (NewUnicodeStringTable
);
945 return EFI_OUT_OF_RESOURCES
;
949 // Compute the length of the Unicode String
951 for (UnicodeStringLength
= 0; UnicodeString
[UnicodeStringLength
] != 0; UnicodeStringLength
++)
955 // Allocate space for a copy of the Unicode String
957 NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
= AllocateCopyPool (
958 (UnicodeStringLength
+ 1) * sizeof (CHAR16
),
961 if (NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
== NULL
) {
962 gBS
->FreePool (NewUnicodeStringTable
[NumberOfEntries
].Language
);
963 gBS
->FreePool (NewUnicodeStringTable
);
964 return EFI_OUT_OF_RESOURCES
;
968 // Mark the end of the Unicode String Table
970 NewUnicodeStringTable
[NumberOfEntries
+ 1].Language
= NULL
;
971 NewUnicodeStringTable
[NumberOfEntries
+ 1].UnicodeString
= NULL
;
974 // Free the old Unicode String Table
976 if (*UnicodeStringTable
!= NULL
) {
977 gBS
->FreePool (*UnicodeStringTable
);
981 // Point UnicodeStringTable at the newly allocated Unicode String Table
983 *UnicodeStringTable
= NewUnicodeStringTable
;
988 SupportedLanguages
+= 3;
991 return EFI_UNSUPPORTED
;
996 This function adds the Null-terminated Unicode string specified by UnicodeString
997 to UnicodeStringTable.
999 If Language is a member of SupportedLanguages then UnicodeString is added to
1000 UnicodeStringTable. New buffers are allocated for both Language and UnicodeString.
1001 The contents of Language and UnicodeString are copied into these new buffers.
1002 These buffers are automatically freed when EfiLibFreeUnicodeStringTable() is called.
1004 @param Language A pointer to an ASCII string containing the ISO 639-2 or
1005 the RFC 4646 language code for the Unicode string to add.
1006 If Iso639Language is TRUE, then this ASCII string is not
1007 assumed to be Null-terminated, and only the first three
1008 chacters are used. If Iso639Language is FALSE, then this
1009 ASCII string must be Null-terminated.
1010 @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains
1011 a set of ISO 639-2 or RFC 4646 language codes that the Unicode
1012 string table supports. Language must be a member of this set.
1013 If Iso639Language is TRUE, then this string contains one or more
1014 ISO 639-2 language codes with no separator characters.
1015 If Iso639Language is FALSE, then is string contains one or more
1016 RFC 4646 language codes separated by ';'.
1017 @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
1018 is defined in "Related Definitions".
1019 @param UnicodeString A pointer to the Unicode string to add.
1020 @param Iso639Language Specifies the supported language code format. If it is TRUE,
1021 then Language and SupportedLanguages follow ISO 639-2 language code format.
1022 Otherwise, they follow RFC 4646 language code format.
1024 @retval EFI_SUCCESS The Unicode string that matches the language specified by
1025 Language was found in the table of Unicode strings UnicodeStringTable,
1026 and it was returned in UnicodeString.
1027 @retval EFI_INVALID_PARAMETER Language is NULL.
1028 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
1029 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
1030 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
1031 @retval EFI_ALREADY_STARTED A Unicode string with language Language is already present in
1033 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another Unicode string UnicodeStringTable.
1034 @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages.
1040 IN CONST CHAR8
*Language
,
1041 IN CONST CHAR8
*SupportedLanguages
,
1042 IN OUT EFI_UNICODE_STRING_TABLE
**UnicodeStringTable
,
1043 IN CONST CHAR16
*UnicodeString
,
1044 IN BOOLEAN Iso639Language
1047 UINTN NumberOfEntries
;
1048 EFI_UNICODE_STRING_TABLE
*OldUnicodeStringTable
;
1049 EFI_UNICODE_STRING_TABLE
*NewUnicodeStringTable
;
1050 UINTN UnicodeStringLength
;
1053 CHAR8
*LanguageString
;
1056 // Make sure the parameter are valid
1058 if (Language
== NULL
|| UnicodeString
== NULL
|| UnicodeStringTable
== NULL
) {
1059 return EFI_INVALID_PARAMETER
;
1063 // If there are no supported languages, then a Unicode String can not be added
1065 if (SupportedLanguages
== NULL
) {
1066 return EFI_UNSUPPORTED
;
1070 // If the Unicode String is empty, then a Unicode String can not be added
1072 if (UnicodeString
[0] == 0) {
1073 return EFI_INVALID_PARAMETER
;
1077 // Make sure Language is a member of SupportedLanguages
1080 while (*SupportedLanguages
!= 0) {
1081 if (Iso639Language
) {
1082 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
1086 SupportedLanguages
+= 3;
1088 for (Index
= 0; SupportedLanguages
[Index
] != 0 && SupportedLanguages
[Index
] != ';'; Index
++);
1089 if (AsciiStrnCmp(SupportedLanguages
, Language
, Index
) == 0) {
1093 SupportedLanguages
+= Index
;
1094 for (; *SupportedLanguages
!= 0 && *SupportedLanguages
== ';'; SupportedLanguages
++);
1099 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
1102 return EFI_UNSUPPORTED
;
1106 // Determine the size of the Unicode String Table by looking for a NULL Language entry
1108 NumberOfEntries
= 0;
1109 if (*UnicodeStringTable
!= NULL
) {
1110 OldUnicodeStringTable
= *UnicodeStringTable
;
1111 while (OldUnicodeStringTable
->Language
!= NULL
) {
1112 LanguageString
= OldUnicodeStringTable
->Language
;
1114 while (*LanguageString
!= 0) {
1115 for (Index
= 0; LanguageString
[Index
] != 0 && LanguageString
[Index
] != ';'; Index
++);
1117 if (AsciiStrnCmp (Language
, LanguageString
, Index
) == 0) {
1118 return EFI_ALREADY_STARTED
;
1120 LanguageString
+= Index
;
1121 for (; *LanguageString
!= 0 && *LanguageString
== ';'; LanguageString
++);
1123 OldUnicodeStringTable
++;
1129 // Allocate space for a new Unicode String Table. It must hold the current number of
1130 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
1133 NewUnicodeStringTable
= AllocatePool ((NumberOfEntries
+ 2) * sizeof (EFI_UNICODE_STRING_TABLE
));
1134 if (NewUnicodeStringTable
== NULL
) {
1135 return EFI_OUT_OF_RESOURCES
;
1139 // If the current Unicode String Table contains any entries, then copy them to the
1140 // newly allocated Unicode String Table.
1142 if (*UnicodeStringTable
!= NULL
) {
1144 NewUnicodeStringTable
,
1145 *UnicodeStringTable
,
1146 NumberOfEntries
* sizeof (EFI_UNICODE_STRING_TABLE
)
1151 // Allocate space for a copy of the Language specifier
1153 NewUnicodeStringTable
[NumberOfEntries
].Language
= AllocateCopyPool (AsciiStrSize(Language
), Language
);
1154 if (NewUnicodeStringTable
[NumberOfEntries
].Language
== NULL
) {
1155 gBS
->FreePool (NewUnicodeStringTable
);
1156 return EFI_OUT_OF_RESOURCES
;
1160 // Compute the length of the Unicode String
1162 for (UnicodeStringLength
= 0; UnicodeString
[UnicodeStringLength
] != 0; UnicodeStringLength
++);
1165 // Allocate space for a copy of the Unicode String
1167 NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
= AllocateCopyPool (StrSize (UnicodeString
), UnicodeString
);
1168 if (NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
== NULL
) {
1169 gBS
->FreePool (NewUnicodeStringTable
[NumberOfEntries
].Language
);
1170 gBS
->FreePool (NewUnicodeStringTable
);
1171 return EFI_OUT_OF_RESOURCES
;
1175 // Mark the end of the Unicode String Table
1177 NewUnicodeStringTable
[NumberOfEntries
+ 1].Language
= NULL
;
1178 NewUnicodeStringTable
[NumberOfEntries
+ 1].UnicodeString
= NULL
;
1181 // Free the old Unicode String Table
1183 if (*UnicodeStringTable
!= NULL
) {
1184 gBS
->FreePool (*UnicodeStringTable
);
1188 // Point UnicodeStringTable at the newly allocated Unicode String Table
1190 *UnicodeStringTable
= NewUnicodeStringTable
;
1196 This function frees the table of Unicode strings in UnicodeStringTable.
1198 If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
1199 Otherwise, each language code, and each Unicode string in the Unicode string
1200 table are freed, and EFI_SUCCESS is returned.
1202 @param UnicodeStringTable A pointer to the table of Unicode strings.
1204 @retval EFI_SUCCESS The Unicode string table was freed.
1209 FreeUnicodeStringTable (
1210 IN EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
1216 // If the Unicode String Table is NULL, then it is already freed
1218 if (UnicodeStringTable
== NULL
) {
1223 // Loop through the Unicode String Table until we reach the end of table marker
1225 for (Index
= 0; UnicodeStringTable
[Index
].Language
!= NULL
; Index
++) {
1228 // Free the Language string from the Unicode String Table
1230 gBS
->FreePool (UnicodeStringTable
[Index
].Language
);
1233 // Free the Unicode String from the Unicode String Table
1235 if (UnicodeStringTable
[Index
].UnicodeString
!= NULL
) {
1236 gBS
->FreePool (UnicodeStringTable
[Index
].UnicodeString
);
1241 // Free the Unicode String Table itself
1243 gBS
->FreePool (UnicodeStringTable
);
1249 Returns a pointer to an allocated buffer that contains the contents of a
1250 variable retrieved through the UEFI Runtime Service GetVariable(). The
1251 returned buffer is allocated using AllocatePool(). The caller is responsible
1252 for freeing this buffer with FreePool().
1254 If Name is NULL, then ASSERT().
1255 If Guid is NULL, then ASSERT().
1257 @param[in] Name Pointer to a Null-terminated Unicode string.
1258 @param[in] Guid Pointer to an EFI_GUID structure
1260 @retval NULL The variable could not be retrieved.
1261 @retval NULL There are not enough resources available for the variable contents.
1262 @retval Other A pointer to allocated buffer containing the variable contents.
1268 IN CONST CHAR16
*Name
,
1269 IN CONST EFI_GUID
*Guid
1276 ASSERT (Name
!= NULL
);
1277 ASSERT (Guid
!= NULL
);
1280 // Try to get the variable size.
1284 Status
= gRT
->GetVariable ((CHAR16
*) Name
, (EFI_GUID
*) Guid
, NULL
, &Size
, Value
);
1285 if (Status
!= EFI_BUFFER_TOO_SMALL
) {
1290 // Allocate buffer to get the variable.
1292 Value
= AllocatePool (Size
);
1293 if (Value
== NULL
) {
1298 // Get the variable data.
1300 Status
= gRT
->GetVariable ((CHAR16
*) Name
, (EFI_GUID
*) Guid
, NULL
, &Size
, Value
);
1301 if (EFI_ERROR (Status
)) {
1311 Returns a pointer to an allocated buffer that contains the contents of a
1312 variable retrieved through the UEFI Runtime Service GetVariable(). This
1313 function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1314 The returned buffer is allocated using AllocatePool(). The caller is
1315 responsible for freeing this buffer with FreePool().
1317 If Name is NULL, then ASSERT().
1319 @param[in] Name Pointer to a Null-terminated Unicode string.
1321 @retval NULL The variable could not be retrieved.
1322 @retval NULL There are not enough resources available for the variable contents.
1323 @retval Other A pointer to allocated buffer containing the variable contents.
1328 GetEfiGlobalVariable (
1329 IN CONST CHAR16
*Name
1332 return GetVariable (Name
, &gEfiGlobalVariableGuid
);
1336 Returns the status whether get the variable success. The function retrieves
1337 variable through the UEFI Runtime Service GetVariable(). The
1338 returned buffer is allocated using AllocatePool(). The caller is responsible
1339 for freeing this buffer with FreePool().
1341 If Name is NULL, then ASSERT().
1342 If Guid is NULL, then ASSERT().
1343 If Value is NULL, then ASSERT().
1345 @param[in] Name The pointer to a Null-terminated Unicode string.
1346 @param[in] Guid The pointer to an EFI_GUID structure
1347 @param[out] Value The buffer point saved the variable info.
1348 @param[out] Size The buffer size of the variable.
1350 @return EFI_OUT_OF_RESOURCES Allocate buffer failed.
1351 @return EFI_SUCCESS Find the specified variable.
1352 @return Others Errors Return errors from call to gRT->GetVariable.
1358 IN CONST CHAR16
*Name
,
1359 IN CONST EFI_GUID
*Guid
,
1361 OUT UINTN
*Size OPTIONAL
1367 ASSERT (Name
!= NULL
&& Guid
!= NULL
&& Value
!= NULL
);
1370 // Try to get the variable size.
1378 Status
= gRT
->GetVariable ((CHAR16
*) Name
, (EFI_GUID
*) Guid
, NULL
, &BufferSize
, *Value
);
1379 if (Status
!= EFI_BUFFER_TOO_SMALL
) {
1384 // Allocate buffer to get the variable.
1386 *Value
= AllocatePool (BufferSize
);
1387 ASSERT (*Value
!= NULL
);
1388 if (*Value
== NULL
) {
1389 return EFI_OUT_OF_RESOURCES
;
1393 // Get the variable data.
1395 Status
= gRT
->GetVariable ((CHAR16
*) Name
, (EFI_GUID
*) Guid
, NULL
, &BufferSize
, *Value
);
1396 if (EFI_ERROR (Status
)) {
1409 Returns a pointer to an allocated buffer that contains the contents of a
1410 variable retrieved through the UEFI Runtime Service GetVariable(). This
1411 function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1412 The returned buffer is allocated using AllocatePool(). The caller is
1413 responsible for freeing this buffer with FreePool().
1415 If Name is NULL, then ASSERT().
1416 If Value is NULL, then ASSERT().
1418 @param[in] Name The pointer to a Null-terminated Unicode string.
1419 @param[out] Value The buffer point saved the variable info.
1420 @param[out] Size The buffer size of the variable.
1422 @return EFI_OUT_OF_RESOURCES Allocate buffer failed.
1423 @return EFI_SUCCESS Find the specified variable.
1424 @return Others Errors Return errors from call to gRT->GetVariable.
1429 GetEfiGlobalVariable2 (
1430 IN CONST CHAR16
*Name
,
1432 OUT UINTN
*Size OPTIONAL
1435 return GetVariable2 (Name
, &gEfiGlobalVariableGuid
, Value
, Size
);
1439 Returns a pointer to an allocated buffer that contains the best matching language
1440 from a set of supported languages.
1442 This function supports both ISO 639-2 and RFC 4646 language codes, but language
1443 code types may not be mixed in a single call to this function. The language
1444 code returned is allocated using AllocatePool(). The caller is responsible for
1445 freeing the allocated buffer using FreePool(). This function supports a variable
1446 argument list that allows the caller to pass in a prioritized list of language
1447 codes to test against all the language codes in SupportedLanguages.
1449 If SupportedLanguages is NULL, then ASSERT().
1451 @param[in] SupportedLanguages A pointer to a Null-terminated ASCII string that
1452 contains a set of language codes in the format
1453 specified by Iso639Language.
1454 @param[in] Iso639Language If not zero, then all language codes are assumed to be
1455 in ISO 639-2 format. If zero, then all language
1456 codes are assumed to be in RFC 4646 language format
1457 @param[in] ... A variable argument list that contains pointers to
1458 Null-terminated ASCII strings that contain one or more
1459 language codes in the format specified by Iso639Language.
1460 The first language code from each of these language
1461 code lists is used to determine if it is an exact or
1462 close match to any of the language codes in
1463 SupportedLanguages. Close matches only apply to RFC 4646
1464 language codes, and the matching algorithm from RFC 4647
1465 is used to determine if a close match is present. If
1466 an exact or close match is found, then the matching
1467 language code from SupportedLanguages is returned. If
1468 no matches are found, then the next variable argument
1469 parameter is evaluated. The variable argument list
1470 is terminated by a NULL.
1472 @retval NULL The best matching language could not be found in SupportedLanguages.
1473 @retval NULL There are not enough resources available to return the best matching
1475 @retval Other A pointer to a Null-terminated ASCII string that is the best matching
1476 language in SupportedLanguages.
1482 IN CONST CHAR8
*SupportedLanguages
,
1483 IN UINTN Iso639Language
,
1489 UINTN CompareLength
;
1490 UINTN LanguageLength
;
1491 CONST CHAR8
*Supported
;
1492 CHAR8
*BestLanguage
;
1494 ASSERT (SupportedLanguages
!= NULL
);
1496 VA_START (Args
, Iso639Language
);
1497 while ((Language
= VA_ARG (Args
, CHAR8
*)) != NULL
) {
1499 // Default to ISO 639-2 mode
1502 LanguageLength
= MIN (3, AsciiStrLen (Language
));
1505 // If in RFC 4646 mode, then determine the length of the first RFC 4646 language code in Language
1507 if (Iso639Language
== 0) {
1508 for (LanguageLength
= 0; Language
[LanguageLength
] != 0 && Language
[LanguageLength
] != ';'; LanguageLength
++);
1512 // Trim back the length of Language used until it is empty
1514 while (LanguageLength
> 0) {
1516 // Loop through all language codes in SupportedLanguages
1518 for (Supported
= SupportedLanguages
; *Supported
!= '\0'; Supported
+= CompareLength
) {
1520 // In RFC 4646 mode, then Loop through all language codes in SupportedLanguages
1522 if (Iso639Language
== 0) {
1524 // Skip ';' characters in Supported
1526 for (; *Supported
!= '\0' && *Supported
== ';'; Supported
++);
1528 // Determine the length of the next language code in Supported
1530 for (CompareLength
= 0; Supported
[CompareLength
] != 0 && Supported
[CompareLength
] != ';'; CompareLength
++);
1532 // If Language is longer than the Supported, then skip to the next language
1534 if (LanguageLength
> CompareLength
) {
1539 // See if the first LanguageLength characters in Supported match Language
1541 if (AsciiStrnCmp (Supported
, Language
, LanguageLength
) == 0) {
1544 // Allocate, copy, and return the best matching language code from SupportedLanguages
1546 BestLanguage
= AllocateZeroPool (CompareLength
+ 1);
1547 if (BestLanguage
== NULL
) {
1550 return CopyMem (BestLanguage
, Supported
, CompareLength
);
1554 if (Iso639Language
!= 0) {
1556 // If ISO 639 mode, then each language can only be tested once
1561 // If RFC 4646 mode, then trim Language from the right to the next '-' character
1563 for (LanguageLength
--; LanguageLength
> 0 && Language
[LanguageLength
] != '-'; LanguageLength
--);
1570 // No matches were found
1576 Returns an array of protocol instance that matches the given protocol.
1578 @param[in] Protocol Provides the protocol to search for.
1579 @param[out] NoProtocols The number of protocols returned in Buffer.
1580 @param[out] Buffer A pointer to the buffer to return the requested
1581 array of protocol instances that match Protocol.
1582 The returned buffer is allocated using
1583 EFI_BOOT_SERVICES.AllocatePool(). The caller is
1584 responsible for freeing this buffer with
1585 EFI_BOOT_SERVICES.FreePool().
1587 @retval EFI_SUCCESS The array of protocols was returned in Buffer,
1588 and the number of protocols in Buffer was
1589 returned in NoProtocols.
1590 @retval EFI_NOT_FOUND No protocols found.
1591 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
1593 @retval EFI_INVALID_PARAMETER Protocol is NULL.
1594 @retval EFI_INVALID_PARAMETER NoProtocols is NULL.
1595 @retval EFI_INVALID_PARAMETER Buffer is NULL.
1600 EfiLocateProtocolBuffer (
1601 IN EFI_GUID
*Protocol
,
1602 OUT UINTN
*NoProtocols
,
1608 EFI_HANDLE
*HandleBuffer
;
1612 // Check input parameters
1614 if (Protocol
== NULL
|| NoProtocols
== NULL
|| Buffer
== NULL
) {
1615 return EFI_INVALID_PARAMETER
;
1619 // Initialze output parameters
1625 // Retrieve the array of handles that support Protocol
1627 Status
= gBS
->LocateHandleBuffer (
1634 if (EFI_ERROR (Status
)) {
1639 // Allocate array of protocol instances
1641 Status
= gBS
->AllocatePool (
1642 EfiBootServicesData
,
1643 NoHandles
* sizeof (VOID
*),
1646 if (EFI_ERROR (Status
)) {
1648 // Free the handle buffer
1650 gBS
->FreePool (HandleBuffer
);
1651 return EFI_OUT_OF_RESOURCES
;
1653 ZeroMem (*Buffer
, NoHandles
* sizeof (VOID
*));
1656 // Lookup Protocol on each handle in HandleBuffer to fill in the array of
1657 // protocol instances. Handle case where protocol instance was present when
1658 // LocateHandleBuffer() was called, but is not present when HandleProtocol()
1661 for (Index
= 0, *NoProtocols
= 0; Index
< NoHandles
; Index
++) {
1662 Status
= gBS
->HandleProtocol (
1663 HandleBuffer
[Index
],
1665 &((*Buffer
)[*NoProtocols
])
1667 if (!EFI_ERROR (Status
)) {
1673 // Free the handle buffer
1675 gBS
->FreePool (HandleBuffer
);
1678 // Make sure at least one protocol instance was found
1680 if (*NoProtocols
== 0) {
1681 gBS
->FreePool (*Buffer
);
1683 return EFI_NOT_FOUND
;
1690 Open or create a file or directory, possibly creating the chain of
1691 directories leading up to the directory.
1693 EfiOpenFileByDevicePath() first locates EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on
1694 FilePath, and opens the root directory of that filesystem with
1695 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume().
1697 On the remaining device path, the longest initial sequence of
1698 FILEPATH_DEVICE_PATH nodes is node-wise traversed with
1699 EFI_FILE_PROTOCOL.Open().
1701 (As a consequence, if OpenMode includes EFI_FILE_MODE_CREATE, and Attributes
1702 includes EFI_FILE_DIRECTORY, and each FILEPATH_DEVICE_PATH specifies a single
1703 pathname component, then EfiOpenFileByDevicePath() ensures that the specified
1704 series of subdirectories exist on return.)
1706 The EFI_FILE_PROTOCOL identified by the last FILEPATH_DEVICE_PATH node is
1707 output to the caller; intermediate EFI_FILE_PROTOCOL instances are closed. If
1708 there are no FILEPATH_DEVICE_PATH nodes past the node that identifies the
1709 filesystem, then the EFI_FILE_PROTOCOL of the root directory of the
1710 filesystem is output to the caller. If a device path node that is different
1711 from FILEPATH_DEVICE_PATH is encountered relative to the filesystem, the
1712 traversal is stopped with an error, and a NULL EFI_FILE_PROTOCOL is output.
1714 @param[in,out] FilePath On input, the device path to the file or directory
1715 to open or create. The caller is responsible for
1716 ensuring that the device path pointed-to by FilePath
1717 is well-formed. On output, FilePath points one past
1718 the last node in the original device path that has
1719 been successfully processed. FilePath is set on
1720 output even if EfiOpenFileByDevicePath() returns an
1723 @param[out] File On error, File is set to NULL. On success, File is
1724 set to the EFI_FILE_PROTOCOL of the root directory
1725 of the filesystem, if there are no
1726 FILEPATH_DEVICE_PATH nodes in FilePath; otherwise,
1727 File is set to the EFI_FILE_PROTOCOL identified by
1728 the last node in FilePath.
1730 @param[in] OpenMode The OpenMode parameter to pass to
1731 EFI_FILE_PROTOCOL.Open().
1733 @param[in] Attributes The Attributes parameter to pass to
1734 EFI_FILE_PROTOCOL.Open().
1736 @retval EFI_SUCCESS The file or directory has been opened or
1739 @retval EFI_INVALID_PARAMETER FilePath is NULL; or File is NULL; or FilePath
1740 contains a device path node, past the node
1742 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL, that is not a
1743 FILEPATH_DEVICE_PATH node.
1745 @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
1747 @return Error codes propagated from the
1748 LocateDevicePath() and OpenProtocol() boot
1749 services, and from the
1750 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume()
1751 and EFI_FILE_PROTOCOL.Open() member functions.
1755 EfiOpenFileByDevicePath (
1756 IN OUT EFI_DEVICE_PATH_PROTOCOL
**FilePath
,
1757 OUT EFI_FILE_PROTOCOL
**File
,
1759 IN UINT64 Attributes
1763 EFI_HANDLE FileSystemHandle
;
1764 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
*FileSystem
;
1765 EFI_FILE_PROTOCOL
*LastFile
;
1766 FILEPATH_DEVICE_PATH
*FilePathNode
;
1767 CHAR16
*AlignedPathName
;
1769 EFI_FILE_PROTOCOL
*NextFile
;
1772 return EFI_INVALID_PARAMETER
;
1776 if (FilePath
== NULL
) {
1777 return EFI_INVALID_PARAMETER
;
1781 // Look up the filesystem.
1783 Status
= gBS
->LocateDevicePath (
1784 &gEfiSimpleFileSystemProtocolGuid
,
1788 if (EFI_ERROR (Status
)) {
1791 Status
= gBS
->OpenProtocol (
1793 &gEfiSimpleFileSystemProtocolGuid
,
1794 (VOID
**)&FileSystem
,
1797 EFI_OPEN_PROTOCOL_GET_PROTOCOL
1799 if (EFI_ERROR (Status
)) {
1804 // Open the root directory of the filesystem. After this operation succeeds,
1805 // we have to release LastFile on error.
1807 Status
= FileSystem
->OpenVolume (FileSystem
, &LastFile
);
1808 if (EFI_ERROR (Status
)) {
1813 // Traverse the device path nodes relative to the filesystem.
1815 while (!IsDevicePathEnd (*FilePath
)) {
1816 if (DevicePathType (*FilePath
) != MEDIA_DEVICE_PATH
||
1817 DevicePathSubType (*FilePath
) != MEDIA_FILEPATH_DP
) {
1818 Status
= EFI_INVALID_PARAMETER
;
1821 FilePathNode
= (FILEPATH_DEVICE_PATH
*)*FilePath
;
1824 // FilePathNode->PathName may be unaligned, and the UEFI specification
1825 // requires pointers that are passed to protocol member functions to be
1826 // aligned. Create an aligned copy of the pathname if necessary.
1828 if ((UINTN
)FilePathNode
->PathName
% sizeof *FilePathNode
->PathName
== 0) {
1829 AlignedPathName
= NULL
;
1830 PathName
= FilePathNode
->PathName
;
1832 AlignedPathName
= AllocateCopyPool (
1833 (DevicePathNodeLength (FilePathNode
) -
1834 SIZE_OF_FILEPATH_DEVICE_PATH
),
1835 FilePathNode
->PathName
1837 if (AlignedPathName
== NULL
) {
1838 Status
= EFI_OUT_OF_RESOURCES
;
1841 PathName
= AlignedPathName
;
1845 // Open or create the file corresponding to the next pathname fragment.
1847 Status
= LastFile
->Open (
1856 // Release any AlignedPathName on both error and success paths; PathName is
1857 // no longer needed.
1859 if (AlignedPathName
!= NULL
) {
1860 FreePool (AlignedPathName
);
1862 if (EFI_ERROR (Status
)) {
1867 // Advance to the next device path node.
1869 LastFile
->Close (LastFile
);
1870 LastFile
= NextFile
;
1871 *FilePath
= NextDevicePathNode (FilePathNode
);
1878 LastFile
->Close (LastFile
);
1881 // We are on the error path; we must have set an error Status for returning
1884 ASSERT (EFI_ERROR (Status
));