MdePkg UefiLib: Fix in EfiLocateProtocolBuffer()
[mirror_edk2.git] / MdePkg / Library / UefiLib / UefiLib.c
1 /** @file
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.
7
8 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
9 This program and the accompanying materials
10 are licensed and made available under the terms and conditions of the BSD License
11 which accompanies this distribution. The full text of the license may be found at
12 http://opensource.org/licenses/bsd-license.php.
13
14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16
17 **/
18
19
20 #include "UefiLibInternal.h"
21
22 /**
23 Empty constructor function that is required to resolve dependencies between
24 libraries.
25
26 ** DO NOT REMOVE **
27
28 @param ImageHandle The firmware allocated handle for the EFI image.
29 @param SystemTable A pointer to the EFI System Table.
30
31 @retval EFI_SUCCESS The constructor executed correctly.
32
33 **/
34 EFI_STATUS
35 EFIAPI
36 UefiLibConstructor (
37 IN EFI_HANDLE ImageHandle,
38 IN EFI_SYSTEM_TABLE *SystemTable
39 )
40 {
41 return EFI_SUCCESS;
42 }
43
44 /**
45 Compare whether two names of languages are identical.
46
47 @param Language1 Name of language 1.
48 @param Language2 Name of language 2.
49
50 @retval TRUE Language 1 and language 2 are the same.
51 @retval FALSE Language 1 and language 2 are not the same.
52
53 **/
54 BOOLEAN
55 CompareIso639LanguageCode (
56 IN CONST CHAR8 *Language1,
57 IN CONST CHAR8 *Language2
58 )
59 {
60 UINT32 Name1;
61 UINT32 Name2;
62
63 Name1 = ReadUnaligned24 ((CONST UINT32 *) Language1);
64 Name2 = ReadUnaligned24 ((CONST UINT32 *) Language2);
65
66 return (BOOLEAN) (Name1 == Name2);
67 }
68
69 /**
70 Retrieves a pointer to the system configuration table from the EFI System Table
71 based on a specified GUID.
72
73 This function searches the list of configuration tables stored in the EFI System Table
74 for a table with a GUID that matches TableGuid. If a match is found, then a pointer to
75 the configuration table is returned in Table., and EFI_SUCCESS is returned. If a matching GUID
76 is not found, then EFI_NOT_FOUND is returned.
77 If TableGuid is NULL, then ASSERT().
78 If Table is NULL, then ASSERT().
79
80 @param TableGuid The pointer to table's GUID type.
81 @param Table The pointer to the table associated with TableGuid in the EFI System Table.
82
83 @retval EFI_SUCCESS A configuration table matching TableGuid was found.
84 @retval EFI_NOT_FOUND A configuration table matching TableGuid could not be found.
85
86 **/
87 EFI_STATUS
88 EFIAPI
89 EfiGetSystemConfigurationTable (
90 IN EFI_GUID *TableGuid,
91 OUT VOID **Table
92 )
93 {
94 EFI_SYSTEM_TABLE *SystemTable;
95 UINTN Index;
96
97 ASSERT (TableGuid != NULL);
98 ASSERT (Table != NULL);
99
100 SystemTable = gST;
101 *Table = NULL;
102 for (Index = 0; Index < SystemTable->NumberOfTableEntries; Index++) {
103 if (CompareGuid (TableGuid, &(SystemTable->ConfigurationTable[Index].VendorGuid))) {
104 *Table = SystemTable->ConfigurationTable[Index].VendorTable;
105 return EFI_SUCCESS;
106 }
107 }
108
109 return EFI_NOT_FOUND;
110 }
111
112 /**
113 Creates and returns a notification event and registers that event with all the protocol
114 instances specified by ProtocolGuid.
115
116 This function causes the notification function to be executed for every protocol of type
117 ProtocolGuid instance that exists in the system when this function is invoked. If there are
118 no instances of ProtocolGuid in the handle database at the time this function is invoked,
119 then the notification function is still executed one time. In addition, every time a protocol
120 of type ProtocolGuid instance is installed or reinstalled, the notification function is also
121 executed. This function returns the notification event that was created.
122 If ProtocolGuid is NULL, then ASSERT().
123 If NotifyTpl is not a legal TPL value, then ASSERT().
124 If NotifyFunction is NULL, then ASSERT().
125 If Registration is NULL, then ASSERT().
126
127
128 @param ProtocolGuid Supplies GUID of the protocol upon whose installation the event is fired.
129 @param NotifyTpl Supplies the task priority level of the event notifications.
130 @param NotifyFunction Supplies the function to notify when the event is signaled.
131 @param NotifyContext The context parameter to pass to NotifyFunction.
132 @param Registration A pointer to a memory location to receive the registration value.
133 This value is passed to LocateHandle() to obtain new handles that
134 have been added that support the ProtocolGuid-specified protocol.
135
136 @return The notification event that was created.
137
138 **/
139 EFI_EVENT
140 EFIAPI
141 EfiCreateProtocolNotifyEvent(
142 IN EFI_GUID *ProtocolGuid,
143 IN EFI_TPL NotifyTpl,
144 IN EFI_EVENT_NOTIFY NotifyFunction,
145 IN VOID *NotifyContext, OPTIONAL
146 OUT VOID **Registration
147 )
148 {
149 EFI_STATUS Status;
150 EFI_EVENT Event;
151
152 ASSERT (ProtocolGuid != NULL);
153 ASSERT (NotifyFunction != NULL);
154 ASSERT (Registration != NULL);
155
156 //
157 // Create the event
158 //
159
160 Status = gBS->CreateEvent (
161 EVT_NOTIFY_SIGNAL,
162 NotifyTpl,
163 NotifyFunction,
164 NotifyContext,
165 &Event
166 );
167 ASSERT_EFI_ERROR (Status);
168
169 //
170 // Register for protocol notifications on this event
171 //
172
173 Status = gBS->RegisterProtocolNotify (
174 ProtocolGuid,
175 Event,
176 Registration
177 );
178
179 ASSERT_EFI_ERROR (Status);
180
181 //
182 // Kick the event so we will perform an initial pass of
183 // current installed drivers
184 //
185
186 gBS->SignalEvent (Event);
187 return Event;
188 }
189
190 /**
191 Creates a named event that can be signaled with EfiNamedEventSignal().
192
193 This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.
194 This event is signaled with EfiNamedEventSignal(). This provides the ability for one or more
195 listeners on the same event named by the GUID specified by Name.
196 If Name is NULL, then ASSERT().
197 If NotifyTpl is not a legal TPL value, then ASSERT().
198 If NotifyFunction is NULL, then ASSERT().
199
200 @param Name Supplies the GUID name of the event.
201 @param NotifyTpl Supplies the task priority level of the event notifications.
202 @param NotifyFunction Supplies the function to notify when the event is signaled.
203 @param NotifyContext The context parameter to pass to NotifyFunction.
204 @param Registration A pointer to a memory location to receive the registration value.
205
206 @retval EFI_SUCCESS A named event was created.
207 @retval EFI_OUT_OF_RESOURCES There are not enough resource to create the named event.
208
209 **/
210 EFI_STATUS
211 EFIAPI
212 EfiNamedEventListen (
213 IN CONST EFI_GUID *Name,
214 IN EFI_TPL NotifyTpl,
215 IN EFI_EVENT_NOTIFY NotifyFunction,
216 IN CONST VOID *NotifyContext, OPTIONAL
217 OUT VOID *Registration OPTIONAL
218 )
219 {
220 EFI_STATUS Status;
221 EFI_EVENT Event;
222 VOID *RegistrationLocal;
223
224 ASSERT (Name != NULL);
225 ASSERT (NotifyFunction != NULL);
226 ASSERT (NotifyTpl <= TPL_HIGH_LEVEL);
227
228 //
229 // Create event
230 //
231 Status = gBS->CreateEvent (
232 EVT_NOTIFY_SIGNAL,
233 NotifyTpl,
234 NotifyFunction,
235 (VOID *) NotifyContext,
236 &Event
237 );
238 ASSERT_EFI_ERROR (Status);
239
240 //
241 // The Registration is not optional to RegisterProtocolNotify().
242 // To make it optional to EfiNamedEventListen(), may need to substitute with a local.
243 //
244 if (Registration != NULL) {
245 RegistrationLocal = Registration;
246 } else {
247 RegistrationLocal = &RegistrationLocal;
248 }
249
250 //
251 // Register for an installation of protocol interface
252 //
253
254 Status = gBS->RegisterProtocolNotify (
255 (EFI_GUID *) Name,
256 Event,
257 RegistrationLocal
258 );
259 ASSERT_EFI_ERROR (Status);
260
261 return Status;
262 }
263
264 /**
265 Signals a named event created with EfiNamedEventListen().
266
267 This function signals the named event specified by Name. The named event must have been
268 created with EfiNamedEventListen().
269 If Name is NULL, then ASSERT().
270
271 @param Name Supplies the GUID name of the event.
272
273 @retval EFI_SUCCESS A named event was signaled.
274 @retval EFI_OUT_OF_RESOURCES There are not enough resource to signal the named event.
275
276 **/
277 EFI_STATUS
278 EFIAPI
279 EfiNamedEventSignal (
280 IN CONST EFI_GUID *Name
281 )
282 {
283 EFI_STATUS Status;
284 EFI_HANDLE Handle;
285
286 ASSERT(Name != NULL);
287
288 Handle = NULL;
289 Status = gBS->InstallProtocolInterface (
290 &Handle,
291 (EFI_GUID *) Name,
292 EFI_NATIVE_INTERFACE,
293 NULL
294 );
295 ASSERT_EFI_ERROR (Status);
296
297 Status = gBS->UninstallProtocolInterface (
298 Handle,
299 (EFI_GUID *) Name,
300 NULL
301 );
302 ASSERT_EFI_ERROR (Status);
303
304 return Status;
305 }
306
307 /**
308 Signals an event group by placing a new event in the group temporarily and
309 signaling it.
310
311 @param[in] EventGroup Supplies the unique identifier of the event
312 group to signal.
313
314 @retval EFI_SUCCESS The event group was signaled successfully.
315 @retval EFI_INVALID_PARAMETER EventGroup is NULL.
316 @return Error codes that report problems about event
317 creation or signaling.
318 **/
319 EFI_STATUS
320 EFIAPI
321 EfiEventGroupSignal (
322 IN CONST EFI_GUID *EventGroup
323 )
324 {
325 EFI_STATUS Status;
326 EFI_EVENT Event;
327
328 if (EventGroup == NULL) {
329 return EFI_INVALID_PARAMETER;
330 }
331
332 Status = gBS->CreateEventEx (
333 EVT_NOTIFY_SIGNAL,
334 TPL_CALLBACK,
335 EfiEventEmptyFunction,
336 NULL,
337 EventGroup,
338 &Event
339 );
340 if (EFI_ERROR (Status)) {
341 return Status;
342 }
343
344 Status = gBS->SignalEvent (Event);
345 gBS->CloseEvent (Event);
346
347 return Status;
348 }
349
350 /**
351 An empty function that can be used as NotifyFunction parameter of
352 CreateEvent() or CreateEventEx().
353
354 @param Event Event whose notification function is being invoked.
355 @param Context The pointer to the notification function's context,
356 which is implementation-dependent.
357
358 **/
359 VOID
360 EFIAPI
361 EfiEventEmptyFunction (
362 IN EFI_EVENT Event,
363 IN VOID *Context
364 )
365 {
366 }
367
368 /**
369 Returns the current TPL.
370
371 This function returns the current TPL. There is no EFI service to directly
372 retrieve the current TPL. Instead, the RaiseTPL() function is used to raise
373 the TPL to TPL_HIGH_LEVEL. This will return the current TPL. The TPL level
374 can then immediately be restored back to the current TPL level with a call
375 to RestoreTPL().
376
377 @return The current TPL.
378
379 **/
380 EFI_TPL
381 EFIAPI
382 EfiGetCurrentTpl (
383 VOID
384 )
385 {
386 EFI_TPL Tpl;
387
388 Tpl = gBS->RaiseTPL (TPL_HIGH_LEVEL);
389 gBS->RestoreTPL (Tpl);
390
391 return Tpl;
392 }
393
394
395 /**
396 Initializes a basic mutual exclusion lock.
397
398 This function initializes a basic mutual exclusion lock to the released state
399 and returns the lock. Each lock provides mutual exclusion access at its task
400 priority level. Since there is no preemption or multiprocessor support in EFI,
401 acquiring the lock only consists of raising to the locks TPL.
402 If Lock is NULL, then ASSERT().
403 If Priority is not a valid TPL value, then ASSERT().
404
405 @param Lock A pointer to the lock data structure to initialize.
406 @param Priority EFI TPL is associated with the lock.
407
408 @return The lock.
409
410 **/
411 EFI_LOCK *
412 EFIAPI
413 EfiInitializeLock (
414 IN OUT EFI_LOCK *Lock,
415 IN EFI_TPL Priority
416 )
417 {
418 ASSERT (Lock != NULL);
419 ASSERT (Priority <= TPL_HIGH_LEVEL);
420
421 Lock->Tpl = Priority;
422 Lock->OwnerTpl = TPL_APPLICATION;
423 Lock->Lock = EfiLockReleased ;
424 return Lock;
425 }
426
427 /**
428 Acquires ownership of a lock.
429
430 This function raises the system's current task priority level to the task
431 priority level of the mutual exclusion lock. Then, it places the lock in the
432 acquired state.
433 If Lock is NULL, then ASSERT().
434 If Lock is not initialized, then ASSERT().
435 If Lock is already in the acquired state, then ASSERT().
436
437 @param Lock A pointer to the lock to acquire.
438
439 **/
440 VOID
441 EFIAPI
442 EfiAcquireLock (
443 IN EFI_LOCK *Lock
444 )
445 {
446 ASSERT (Lock != NULL);
447 ASSERT (Lock->Lock == EfiLockReleased);
448
449 Lock->OwnerTpl = gBS->RaiseTPL (Lock->Tpl);
450 Lock->Lock = EfiLockAcquired;
451 }
452
453 /**
454 Acquires ownership of a lock.
455
456 This function raises the system's current task priority level to the task priority
457 level of the mutual exclusion lock. Then, it attempts to place the lock in the acquired state.
458 If the lock is already in the acquired state, then EFI_ACCESS_DENIED is returned.
459 Otherwise, EFI_SUCCESS is returned.
460 If Lock is NULL, then ASSERT().
461 If Lock is not initialized, then ASSERT().
462
463 @param Lock A pointer to the lock to acquire.
464
465 @retval EFI_SUCCESS The lock was acquired.
466 @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
467
468 **/
469 EFI_STATUS
470 EFIAPI
471 EfiAcquireLockOrFail (
472 IN EFI_LOCK *Lock
473 )
474 {
475
476 ASSERT (Lock != NULL);
477 ASSERT (Lock->Lock != EfiLockUninitialized);
478
479 if (Lock->Lock == EfiLockAcquired) {
480 //
481 // Lock is already owned, so bail out
482 //
483 return EFI_ACCESS_DENIED;
484 }
485
486 Lock->OwnerTpl = gBS->RaiseTPL (Lock->Tpl);
487
488 Lock->Lock = EfiLockAcquired;
489
490 return EFI_SUCCESS;
491 }
492
493 /**
494 Releases ownership of a lock.
495
496 This function transitions a mutual exclusion lock from the acquired state to
497 the released state, and restores the system's task priority level to its
498 previous level.
499 If Lock is NULL, then ASSERT().
500 If Lock is not initialized, then ASSERT().
501 If Lock is already in the released state, then ASSERT().
502
503 @param Lock A pointer to the lock to release.
504
505 **/
506 VOID
507 EFIAPI
508 EfiReleaseLock (
509 IN EFI_LOCK *Lock
510 )
511 {
512 EFI_TPL Tpl;
513
514 ASSERT (Lock != NULL);
515 ASSERT (Lock->Lock == EfiLockAcquired);
516
517 Tpl = Lock->OwnerTpl;
518
519 Lock->Lock = EfiLockReleased;
520
521 gBS->RestoreTPL (Tpl);
522 }
523
524 /**
525 Tests whether a controller handle is being managed by a specific driver.
526
527 This function tests whether the driver specified by DriverBindingHandle is
528 currently managing the controller specified by ControllerHandle. This test
529 is performed by evaluating if the the protocol specified by ProtocolGuid is
530 present on ControllerHandle and is was opened by DriverBindingHandle with an
531 attribute of EFI_OPEN_PROTOCOL_BY_DRIVER.
532 If ProtocolGuid is NULL, then ASSERT().
533
534 @param ControllerHandle A handle for a controller to test.
535 @param DriverBindingHandle Specifies the driver binding handle for the
536 driver.
537 @param ProtocolGuid Specifies the protocol that the driver specified
538 by DriverBindingHandle opens in its Start()
539 function.
540
541 @retval EFI_SUCCESS ControllerHandle is managed by the driver
542 specified by DriverBindingHandle.
543 @retval EFI_UNSUPPORTED ControllerHandle is not managed by the driver
544 specified by DriverBindingHandle.
545
546 **/
547 EFI_STATUS
548 EFIAPI
549 EfiTestManagedDevice (
550 IN CONST EFI_HANDLE ControllerHandle,
551 IN CONST EFI_HANDLE DriverBindingHandle,
552 IN CONST EFI_GUID *ProtocolGuid
553 )
554 {
555 EFI_STATUS Status;
556 VOID *ManagedInterface;
557
558 ASSERT (ProtocolGuid != NULL);
559
560 Status = gBS->OpenProtocol (
561 ControllerHandle,
562 (EFI_GUID *) ProtocolGuid,
563 &ManagedInterface,
564 DriverBindingHandle,
565 ControllerHandle,
566 EFI_OPEN_PROTOCOL_BY_DRIVER
567 );
568 if (!EFI_ERROR (Status)) {
569 gBS->CloseProtocol (
570 ControllerHandle,
571 (EFI_GUID *) ProtocolGuid,
572 DriverBindingHandle,
573 ControllerHandle
574 );
575 return EFI_UNSUPPORTED;
576 }
577
578 if (Status != EFI_ALREADY_STARTED) {
579 return EFI_UNSUPPORTED;
580 }
581
582 return EFI_SUCCESS;
583 }
584
585 /**
586 Tests whether a child handle is a child device of the controller.
587
588 This function tests whether ChildHandle is one of the children of
589 ControllerHandle. This test is performed by checking to see if the protocol
590 specified by ProtocolGuid is present on ControllerHandle and opened by
591 ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
592 If ProtocolGuid is NULL, then ASSERT().
593
594 @param ControllerHandle A handle for a (parent) controller to test.
595 @param ChildHandle A child handle to test.
596 @param ProtocolGuid Supplies the protocol that the child controller
597 opens on its parent controller.
598
599 @retval EFI_SUCCESS ChildHandle is a child of the ControllerHandle.
600 @retval EFI_UNSUPPORTED ChildHandle is not a child of the
601 ControllerHandle.
602
603 **/
604 EFI_STATUS
605 EFIAPI
606 EfiTestChildHandle (
607 IN CONST EFI_HANDLE ControllerHandle,
608 IN CONST EFI_HANDLE ChildHandle,
609 IN CONST EFI_GUID *ProtocolGuid
610 )
611 {
612 EFI_STATUS Status;
613 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY *OpenInfoBuffer;
614 UINTN EntryCount;
615 UINTN Index;
616
617 ASSERT (ProtocolGuid != NULL);
618
619 //
620 // Retrieve the list of agents that are consuming the specific protocol
621 // on ControllerHandle.
622 //
623 Status = gBS->OpenProtocolInformation (
624 ControllerHandle,
625 (EFI_GUID *) ProtocolGuid,
626 &OpenInfoBuffer,
627 &EntryCount
628 );
629 if (EFI_ERROR (Status)) {
630 return EFI_UNSUPPORTED;
631 }
632
633 //
634 // Inspect if ChildHandle is one of the agents.
635 //
636 Status = EFI_UNSUPPORTED;
637 for (Index = 0; Index < EntryCount; Index++) {
638 if ((OpenInfoBuffer[Index].ControllerHandle == ChildHandle) &&
639 (OpenInfoBuffer[Index].Attributes & EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER) != 0) {
640 Status = EFI_SUCCESS;
641 break;
642 }
643 }
644
645 FreePool (OpenInfoBuffer);
646 return Status;
647 }
648
649 /**
650 This function looks up a Unicode string in UnicodeStringTable.
651
652 If Language is a member of SupportedLanguages and a Unicode string is found in
653 UnicodeStringTable that matches the language code specified by Language, then it
654 is returned in UnicodeString.
655
656 @param Language A pointer to the ISO 639-2 language code for the
657 Unicode string to look up and return.
658 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
659 that the Unicode string table supports. Language
660 must be a member of this set.
661 @param UnicodeStringTable A pointer to the table of Unicode strings.
662 @param UnicodeString A pointer to the Unicode string from UnicodeStringTable
663 that matches the language specified by Language.
664
665 @retval EFI_SUCCESS The Unicode string that matches the language
666 specified by Language was found
667 in the table of Unicode strings UnicodeStringTable,
668 and it was returned in UnicodeString.
669 @retval EFI_INVALID_PARAMETER Language is NULL.
670 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
671 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
672 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
673 @retval EFI_UNSUPPORTED The language specified by Language is not a
674 member of SupportedLanguages.
675 @retval EFI_UNSUPPORTED The language specified by Language is not
676 supported by UnicodeStringTable.
677
678 **/
679 EFI_STATUS
680 EFIAPI
681 LookupUnicodeString (
682 IN CONST CHAR8 *Language,
683 IN CONST CHAR8 *SupportedLanguages,
684 IN CONST EFI_UNICODE_STRING_TABLE *UnicodeStringTable,
685 OUT CHAR16 **UnicodeString
686 )
687 {
688 //
689 // Make sure the parameters are valid
690 //
691 if (Language == NULL || UnicodeString == NULL) {
692 return EFI_INVALID_PARAMETER;
693 }
694
695 //
696 // If there are no supported languages, or the Unicode String Table is empty, then the
697 // Unicode String specified by Language is not supported by this Unicode String Table
698 //
699 if (SupportedLanguages == NULL || UnicodeStringTable == NULL) {
700 return EFI_UNSUPPORTED;
701 }
702
703 //
704 // Make sure Language is in the set of Supported Languages
705 //
706 while (*SupportedLanguages != 0) {
707 if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
708
709 //
710 // Search the Unicode String Table for the matching Language specifier
711 //
712 while (UnicodeStringTable->Language != NULL) {
713 if (CompareIso639LanguageCode (Language, UnicodeStringTable->Language)) {
714
715 //
716 // A matching string was found, so return it
717 //
718 *UnicodeString = UnicodeStringTable->UnicodeString;
719 return EFI_SUCCESS;
720 }
721
722 UnicodeStringTable++;
723 }
724
725 return EFI_UNSUPPORTED;
726 }
727
728 SupportedLanguages += 3;
729 }
730
731 return EFI_UNSUPPORTED;
732 }
733
734
735
736 /**
737 This function looks up a Unicode string in UnicodeStringTable.
738
739 If Language is a member of SupportedLanguages and a Unicode string is found in
740 UnicodeStringTable that matches the language code specified by Language, then
741 it is returned in UnicodeString.
742
743 @param Language A pointer to an ASCII string containing the ISO 639-2 or the
744 RFC 4646 language code for the Unicode string to look up and
745 return. If Iso639Language is TRUE, then this ASCII string is
746 not assumed to be Null-terminated, and only the first three
747 characters are used. If Iso639Language is FALSE, then this ASCII
748 string must be Null-terminated.
749 @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains a
750 set of ISO 639-2 or RFC 4646 language codes that the Unicode
751 string table supports. Language must be a member of this set.
752 If Iso639Language is TRUE, then this string contains one or more
753 ISO 639-2 language codes with no separator characters. If Iso639Language
754 is FALSE, then is string contains one or more RFC 4646 language
755 codes separated by ';'.
756 @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
757 is defined in "Related Definitions".
758 @param UnicodeString A pointer to the Null-terminated Unicode string from UnicodeStringTable
759 that matches the language specified by Language.
760 @param Iso639Language Specifies the supported language code format. If it is TRUE, then
761 Language and SupportedLanguages follow ISO 639-2 language code format.
762 Otherwise, they follow RFC 4646 language code format.
763
764
765 @retval EFI_SUCCESS The Unicode string that matches the language specified by Language
766 was found in the table of Unicode strings UnicodeStringTable, and
767 it was returned in UnicodeString.
768 @retval EFI_INVALID_PARAMETER Language is NULL.
769 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
770 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
771 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
772 @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages.
773 @retval EFI_UNSUPPORTED The language specified by Language is not supported by UnicodeStringTable.
774
775 **/
776 EFI_STATUS
777 EFIAPI
778 LookupUnicodeString2 (
779 IN CONST CHAR8 *Language,
780 IN CONST CHAR8 *SupportedLanguages,
781 IN CONST EFI_UNICODE_STRING_TABLE *UnicodeStringTable,
782 OUT CHAR16 **UnicodeString,
783 IN BOOLEAN Iso639Language
784 )
785 {
786 BOOLEAN Found;
787 UINTN Index;
788 CHAR8 *LanguageString;
789
790 //
791 // Make sure the parameters are valid
792 //
793 if (Language == NULL || UnicodeString == NULL) {
794 return EFI_INVALID_PARAMETER;
795 }
796
797 //
798 // If there are no supported languages, or the Unicode String Table is empty, then the
799 // Unicode String specified by Language is not supported by this Unicode String Table
800 //
801 if (SupportedLanguages == NULL || UnicodeStringTable == NULL) {
802 return EFI_UNSUPPORTED;
803 }
804
805 //
806 // Make sure Language is in the set of Supported Languages
807 //
808 Found = FALSE;
809 while (*SupportedLanguages != 0) {
810 if (Iso639Language) {
811 if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
812 Found = TRUE;
813 break;
814 }
815 SupportedLanguages += 3;
816 } else {
817 for (Index = 0; SupportedLanguages[Index] != 0 && SupportedLanguages[Index] != ';'; Index++);
818 if ((AsciiStrnCmp(SupportedLanguages, Language, Index) == 0) && (Language[Index] == 0)) {
819 Found = TRUE;
820 break;
821 }
822 SupportedLanguages += Index;
823 for (; *SupportedLanguages != 0 && *SupportedLanguages == ';'; SupportedLanguages++);
824 }
825 }
826
827 //
828 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
829 //
830 if (!Found) {
831 return EFI_UNSUPPORTED;
832 }
833
834 //
835 // Search the Unicode String Table for the matching Language specifier
836 //
837 while (UnicodeStringTable->Language != NULL) {
838 LanguageString = UnicodeStringTable->Language;
839 while (0 != *LanguageString) {
840 for (Index = 0 ;LanguageString[Index] != 0 && LanguageString[Index] != ';'; Index++);
841 if (AsciiStrnCmp(LanguageString, Language, Index) == 0) {
842 *UnicodeString = UnicodeStringTable->UnicodeString;
843 return EFI_SUCCESS;
844 }
845 LanguageString += Index;
846 for (Index = 0 ;LanguageString[Index] != 0 && LanguageString[Index] == ';'; Index++);
847 }
848 UnicodeStringTable++;
849 }
850
851 return EFI_UNSUPPORTED;
852 }
853
854
855 /**
856 This function adds a Unicode string to UnicodeStringTable.
857
858 If Language is a member of SupportedLanguages then UnicodeString is added to
859 UnicodeStringTable. New buffers are allocated for both Language and
860 UnicodeString. The contents of Language and UnicodeString are copied into
861 these new buffers. These buffers are automatically freed when
862 FreeUnicodeStringTable() is called.
863
864 @param Language A pointer to the ISO 639-2 language code for the Unicode
865 string to add.
866 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes
867 that the Unicode string table supports.
868 Language must be a member of this set.
869 @param UnicodeStringTable A pointer to the table of Unicode strings.
870 @param UnicodeString A pointer to the Unicode string to add.
871
872 @retval EFI_SUCCESS The Unicode string that matches the language
873 specified by Language was found in the table of
874 Unicode strings UnicodeStringTable, and it was
875 returned in UnicodeString.
876 @retval EFI_INVALID_PARAMETER Language is NULL.
877 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
878 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
879 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
880 @retval EFI_ALREADY_STARTED A Unicode string with language Language is
881 already present in UnicodeStringTable.
882 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another
883 Unicode string to UnicodeStringTable.
884 @retval EFI_UNSUPPORTED The language specified by Language is not a
885 member of SupportedLanguages.
886
887 **/
888 EFI_STATUS
889 EFIAPI
890 AddUnicodeString (
891 IN CONST CHAR8 *Language,
892 IN CONST CHAR8 *SupportedLanguages,
893 IN OUT EFI_UNICODE_STRING_TABLE **UnicodeStringTable,
894 IN CONST CHAR16 *UnicodeString
895 )
896 {
897 UINTN NumberOfEntries;
898 EFI_UNICODE_STRING_TABLE *OldUnicodeStringTable;
899 EFI_UNICODE_STRING_TABLE *NewUnicodeStringTable;
900 UINTN UnicodeStringLength;
901
902 //
903 // Make sure the parameter are valid
904 //
905 if (Language == NULL || UnicodeString == NULL || UnicodeStringTable == NULL) {
906 return EFI_INVALID_PARAMETER;
907 }
908
909 //
910 // If there are no supported languages, then a Unicode String can not be added
911 //
912 if (SupportedLanguages == NULL) {
913 return EFI_UNSUPPORTED;
914 }
915
916 //
917 // If the Unicode String is empty, then a Unicode String can not be added
918 //
919 if (UnicodeString[0] == 0) {
920 return EFI_INVALID_PARAMETER;
921 }
922
923 //
924 // Make sure Language is a member of SupportedLanguages
925 //
926 while (*SupportedLanguages != 0) {
927 if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
928
929 //
930 // Determine the size of the Unicode String Table by looking for a NULL Language entry
931 //
932 NumberOfEntries = 0;
933 if (*UnicodeStringTable != NULL) {
934 OldUnicodeStringTable = *UnicodeStringTable;
935 while (OldUnicodeStringTable->Language != NULL) {
936 if (CompareIso639LanguageCode (Language, OldUnicodeStringTable->Language)) {
937 return EFI_ALREADY_STARTED;
938 }
939
940 OldUnicodeStringTable++;
941 NumberOfEntries++;
942 }
943 }
944
945 //
946 // Allocate space for a new Unicode String Table. It must hold the current number of
947 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
948 // marker
949 //
950 NewUnicodeStringTable = AllocatePool ((NumberOfEntries + 2) * sizeof (EFI_UNICODE_STRING_TABLE));
951 if (NewUnicodeStringTable == NULL) {
952 return EFI_OUT_OF_RESOURCES;
953 }
954
955 //
956 // If the current Unicode String Table contains any entries, then copy them to the
957 // newly allocated Unicode String Table.
958 //
959 if (*UnicodeStringTable != NULL) {
960 CopyMem (
961 NewUnicodeStringTable,
962 *UnicodeStringTable,
963 NumberOfEntries * sizeof (EFI_UNICODE_STRING_TABLE)
964 );
965 }
966
967 //
968 // Allocate space for a copy of the Language specifier
969 //
970 NewUnicodeStringTable[NumberOfEntries].Language = AllocateCopyPool (3, Language);
971 if (NewUnicodeStringTable[NumberOfEntries].Language == NULL) {
972 FreePool (NewUnicodeStringTable);
973 return EFI_OUT_OF_RESOURCES;
974 }
975
976 //
977 // Compute the length of the Unicode String
978 //
979 for (UnicodeStringLength = 0; UnicodeString[UnicodeStringLength] != 0; UnicodeStringLength++)
980 ;
981
982 //
983 // Allocate space for a copy of the Unicode String
984 //
985 NewUnicodeStringTable[NumberOfEntries].UnicodeString = AllocateCopyPool (
986 (UnicodeStringLength + 1) * sizeof (CHAR16),
987 UnicodeString
988 );
989 if (NewUnicodeStringTable[NumberOfEntries].UnicodeString == NULL) {
990 FreePool (NewUnicodeStringTable[NumberOfEntries].Language);
991 FreePool (NewUnicodeStringTable);
992 return EFI_OUT_OF_RESOURCES;
993 }
994
995 //
996 // Mark the end of the Unicode String Table
997 //
998 NewUnicodeStringTable[NumberOfEntries + 1].Language = NULL;
999 NewUnicodeStringTable[NumberOfEntries + 1].UnicodeString = NULL;
1000
1001 //
1002 // Free the old Unicode String Table
1003 //
1004 if (*UnicodeStringTable != NULL) {
1005 FreePool (*UnicodeStringTable);
1006 }
1007
1008 //
1009 // Point UnicodeStringTable at the newly allocated Unicode String Table
1010 //
1011 *UnicodeStringTable = NewUnicodeStringTable;
1012
1013 return EFI_SUCCESS;
1014 }
1015
1016 SupportedLanguages += 3;
1017 }
1018
1019 return EFI_UNSUPPORTED;
1020 }
1021
1022
1023 /**
1024 This function adds the Null-terminated Unicode string specified by UnicodeString
1025 to UnicodeStringTable.
1026
1027 If Language is a member of SupportedLanguages then UnicodeString is added to
1028 UnicodeStringTable. New buffers are allocated for both Language and UnicodeString.
1029 The contents of Language and UnicodeString are copied into these new buffers.
1030 These buffers are automatically freed when EfiLibFreeUnicodeStringTable() is called.
1031
1032 @param Language A pointer to an ASCII string containing the ISO 639-2 or
1033 the RFC 4646 language code for the Unicode string to add.
1034 If Iso639Language is TRUE, then this ASCII string is not
1035 assumed to be Null-terminated, and only the first three
1036 chacters are used. If Iso639Language is FALSE, then this
1037 ASCII string must be Null-terminated.
1038 @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains
1039 a set of ISO 639-2 or RFC 4646 language codes that the Unicode
1040 string table supports. Language must be a member of this set.
1041 If Iso639Language is TRUE, then this string contains one or more
1042 ISO 639-2 language codes with no separator characters.
1043 If Iso639Language is FALSE, then is string contains one or more
1044 RFC 4646 language codes separated by ';'.
1045 @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
1046 is defined in "Related Definitions".
1047 @param UnicodeString A pointer to the Unicode string to add.
1048 @param Iso639Language Specifies the supported language code format. If it is TRUE,
1049 then Language and SupportedLanguages follow ISO 639-2 language code format.
1050 Otherwise, they follow RFC 4646 language code format.
1051
1052 @retval EFI_SUCCESS The Unicode string that matches the language specified by
1053 Language was found in the table of Unicode strings UnicodeStringTable,
1054 and it was returned in UnicodeString.
1055 @retval EFI_INVALID_PARAMETER Language is NULL.
1056 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
1057 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
1058 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
1059 @retval EFI_ALREADY_STARTED A Unicode string with language Language is already present in
1060 UnicodeStringTable.
1061 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another Unicode string UnicodeStringTable.
1062 @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages.
1063
1064 **/
1065 EFI_STATUS
1066 EFIAPI
1067 AddUnicodeString2 (
1068 IN CONST CHAR8 *Language,
1069 IN CONST CHAR8 *SupportedLanguages,
1070 IN OUT EFI_UNICODE_STRING_TABLE **UnicodeStringTable,
1071 IN CONST CHAR16 *UnicodeString,
1072 IN BOOLEAN Iso639Language
1073 )
1074 {
1075 UINTN NumberOfEntries;
1076 EFI_UNICODE_STRING_TABLE *OldUnicodeStringTable;
1077 EFI_UNICODE_STRING_TABLE *NewUnicodeStringTable;
1078 UINTN UnicodeStringLength;
1079 BOOLEAN Found;
1080 UINTN Index;
1081 CHAR8 *LanguageString;
1082
1083 //
1084 // Make sure the parameter are valid
1085 //
1086 if (Language == NULL || UnicodeString == NULL || UnicodeStringTable == NULL) {
1087 return EFI_INVALID_PARAMETER;
1088 }
1089
1090 //
1091 // If there are no supported languages, then a Unicode String can not be added
1092 //
1093 if (SupportedLanguages == NULL) {
1094 return EFI_UNSUPPORTED;
1095 }
1096
1097 //
1098 // If the Unicode String is empty, then a Unicode String can not be added
1099 //
1100 if (UnicodeString[0] == 0) {
1101 return EFI_INVALID_PARAMETER;
1102 }
1103
1104 //
1105 // Make sure Language is a member of SupportedLanguages
1106 //
1107 Found = FALSE;
1108 while (*SupportedLanguages != 0) {
1109 if (Iso639Language) {
1110 if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
1111 Found = TRUE;
1112 break;
1113 }
1114 SupportedLanguages += 3;
1115 } else {
1116 for (Index = 0; SupportedLanguages[Index] != 0 && SupportedLanguages[Index] != ';'; Index++);
1117 if (AsciiStrnCmp(SupportedLanguages, Language, Index) == 0) {
1118 Found = TRUE;
1119 break;
1120 }
1121 SupportedLanguages += Index;
1122 for (; *SupportedLanguages != 0 && *SupportedLanguages == ';'; SupportedLanguages++);
1123 }
1124 }
1125
1126 //
1127 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
1128 //
1129 if (!Found) {
1130 return EFI_UNSUPPORTED;
1131 }
1132
1133 //
1134 // Determine the size of the Unicode String Table by looking for a NULL Language entry
1135 //
1136 NumberOfEntries = 0;
1137 if (*UnicodeStringTable != NULL) {
1138 OldUnicodeStringTable = *UnicodeStringTable;
1139 while (OldUnicodeStringTable->Language != NULL) {
1140 LanguageString = OldUnicodeStringTable->Language;
1141
1142 while (*LanguageString != 0) {
1143 for (Index = 0; LanguageString[Index] != 0 && LanguageString[Index] != ';'; Index++);
1144
1145 if (AsciiStrnCmp (Language, LanguageString, Index) == 0) {
1146 return EFI_ALREADY_STARTED;
1147 }
1148 LanguageString += Index;
1149 for (; *LanguageString != 0 && *LanguageString == ';'; LanguageString++);
1150 }
1151 OldUnicodeStringTable++;
1152 NumberOfEntries++;
1153 }
1154 }
1155
1156 //
1157 // Allocate space for a new Unicode String Table. It must hold the current number of
1158 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
1159 // marker
1160 //
1161 NewUnicodeStringTable = AllocatePool ((NumberOfEntries + 2) * sizeof (EFI_UNICODE_STRING_TABLE));
1162 if (NewUnicodeStringTable == NULL) {
1163 return EFI_OUT_OF_RESOURCES;
1164 }
1165
1166 //
1167 // If the current Unicode String Table contains any entries, then copy them to the
1168 // newly allocated Unicode String Table.
1169 //
1170 if (*UnicodeStringTable != NULL) {
1171 CopyMem (
1172 NewUnicodeStringTable,
1173 *UnicodeStringTable,
1174 NumberOfEntries * sizeof (EFI_UNICODE_STRING_TABLE)
1175 );
1176 }
1177
1178 //
1179 // Allocate space for a copy of the Language specifier
1180 //
1181 NewUnicodeStringTable[NumberOfEntries].Language = AllocateCopyPool (AsciiStrSize(Language), Language);
1182 if (NewUnicodeStringTable[NumberOfEntries].Language == NULL) {
1183 FreePool (NewUnicodeStringTable);
1184 return EFI_OUT_OF_RESOURCES;
1185 }
1186
1187 //
1188 // Compute the length of the Unicode String
1189 //
1190 for (UnicodeStringLength = 0; UnicodeString[UnicodeStringLength] != 0; UnicodeStringLength++);
1191
1192 //
1193 // Allocate space for a copy of the Unicode String
1194 //
1195 NewUnicodeStringTable[NumberOfEntries].UnicodeString = AllocateCopyPool (StrSize (UnicodeString), UnicodeString);
1196 if (NewUnicodeStringTable[NumberOfEntries].UnicodeString == NULL) {
1197 FreePool (NewUnicodeStringTable[NumberOfEntries].Language);
1198 FreePool (NewUnicodeStringTable);
1199 return EFI_OUT_OF_RESOURCES;
1200 }
1201
1202 //
1203 // Mark the end of the Unicode String Table
1204 //
1205 NewUnicodeStringTable[NumberOfEntries + 1].Language = NULL;
1206 NewUnicodeStringTable[NumberOfEntries + 1].UnicodeString = NULL;
1207
1208 //
1209 // Free the old Unicode String Table
1210 //
1211 if (*UnicodeStringTable != NULL) {
1212 FreePool (*UnicodeStringTable);
1213 }
1214
1215 //
1216 // Point UnicodeStringTable at the newly allocated Unicode String Table
1217 //
1218 *UnicodeStringTable = NewUnicodeStringTable;
1219
1220 return EFI_SUCCESS;
1221 }
1222
1223 /**
1224 This function frees the table of Unicode strings in UnicodeStringTable.
1225
1226 If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
1227 Otherwise, each language code, and each Unicode string in the Unicode string
1228 table are freed, and EFI_SUCCESS is returned.
1229
1230 @param UnicodeStringTable A pointer to the table of Unicode strings.
1231
1232 @retval EFI_SUCCESS The Unicode string table was freed.
1233
1234 **/
1235 EFI_STATUS
1236 EFIAPI
1237 FreeUnicodeStringTable (
1238 IN EFI_UNICODE_STRING_TABLE *UnicodeStringTable
1239 )
1240 {
1241 UINTN Index;
1242
1243 //
1244 // If the Unicode String Table is NULL, then it is already freed
1245 //
1246 if (UnicodeStringTable == NULL) {
1247 return EFI_SUCCESS;
1248 }
1249
1250 //
1251 // Loop through the Unicode String Table until we reach the end of table marker
1252 //
1253 for (Index = 0; UnicodeStringTable[Index].Language != NULL; Index++) {
1254
1255 //
1256 // Free the Language string from the Unicode String Table
1257 //
1258 FreePool (UnicodeStringTable[Index].Language);
1259
1260 //
1261 // Free the Unicode String from the Unicode String Table
1262 //
1263 if (UnicodeStringTable[Index].UnicodeString != NULL) {
1264 FreePool (UnicodeStringTable[Index].UnicodeString);
1265 }
1266 }
1267
1268 //
1269 // Free the Unicode String Table itself
1270 //
1271 FreePool (UnicodeStringTable);
1272
1273 return EFI_SUCCESS;
1274 }
1275
1276 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1277
1278 /**
1279 [ATTENTION] This function will be deprecated for security reason.
1280
1281 Returns a pointer to an allocated buffer that contains the contents of a
1282 variable retrieved through the UEFI Runtime Service GetVariable(). The
1283 returned buffer is allocated using AllocatePool(). The caller is responsible
1284 for freeing this buffer with FreePool().
1285
1286 If Name is NULL, then ASSERT().
1287 If Guid is NULL, then ASSERT().
1288
1289 @param[in] Name The pointer to a Null-terminated Unicode string.
1290 @param[in] Guid The pointer to an EFI_GUID structure
1291
1292 @retval NULL The variable could not be retrieved.
1293 @retval NULL There are not enough resources available for the variable contents.
1294 @retval Other A pointer to allocated buffer containing the variable contents.
1295
1296 **/
1297 VOID *
1298 EFIAPI
1299 GetVariable (
1300 IN CONST CHAR16 *Name,
1301 IN CONST EFI_GUID *Guid
1302 )
1303 {
1304 EFI_STATUS Status;
1305 UINTN Size;
1306 VOID *Value;
1307
1308 ASSERT (Name != NULL);
1309 ASSERT (Guid != NULL);
1310
1311 //
1312 // Try to get the variable size.
1313 //
1314 Value = NULL;
1315 Size = 0;
1316 Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &Size, Value);
1317 if (Status != EFI_BUFFER_TOO_SMALL) {
1318 return NULL;
1319 }
1320
1321 //
1322 // Allocate buffer to get the variable.
1323 //
1324 Value = AllocatePool (Size);
1325 if (Value == NULL) {
1326 return NULL;
1327 }
1328
1329 //
1330 // Get the variable data.
1331 //
1332 Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &Size, Value);
1333 if (EFI_ERROR (Status)) {
1334 FreePool(Value);
1335 return NULL;
1336 }
1337
1338 return Value;
1339 }
1340
1341 /**
1342 [ATTENTION] This function will be deprecated for security reason.
1343
1344 Returns a pointer to an allocated buffer that contains the contents of a
1345 variable retrieved through the UEFI Runtime Service GetVariable(). This
1346 function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1347 The returned buffer is allocated using AllocatePool(). The caller is
1348 responsible for freeing this buffer with FreePool().
1349
1350 If Name is NULL, then ASSERT().
1351
1352 @param[in] Name The pointer to a Null-terminated Unicode string.
1353
1354 @retval NULL The variable could not be retrieved.
1355 @retval NULL There are not enough resources available for the variable contents.
1356 @retval Other A pointer to allocated buffer containing the variable contents.
1357
1358 **/
1359 VOID *
1360 EFIAPI
1361 GetEfiGlobalVariable (
1362 IN CONST CHAR16 *Name
1363 )
1364 {
1365 return GetVariable (Name, &gEfiGlobalVariableGuid);
1366 }
1367 #endif
1368
1369 /**
1370 Returns the status whether get the variable success. The function retrieves
1371 variable through the UEFI Runtime Service GetVariable(). The
1372 returned buffer is allocated using AllocatePool(). The caller is responsible
1373 for freeing this buffer with FreePool().
1374
1375 If Name is NULL, then ASSERT().
1376 If Guid is NULL, then ASSERT().
1377 If Value is NULL, then ASSERT().
1378
1379 @param[in] Name The pointer to a Null-terminated Unicode string.
1380 @param[in] Guid The pointer to an EFI_GUID structure
1381 @param[out] Value The buffer point saved the variable info.
1382 @param[out] Size The buffer size of the variable.
1383
1384 @return EFI_OUT_OF_RESOURCES Allocate buffer failed.
1385 @return EFI_SUCCESS Find the specified variable.
1386 @return Others Errors Return errors from call to gRT->GetVariable.
1387
1388 **/
1389 EFI_STATUS
1390 EFIAPI
1391 GetVariable2 (
1392 IN CONST CHAR16 *Name,
1393 IN CONST EFI_GUID *Guid,
1394 OUT VOID **Value,
1395 OUT UINTN *Size OPTIONAL
1396 )
1397 {
1398 EFI_STATUS Status;
1399 UINTN BufferSize;
1400
1401 ASSERT (Name != NULL && Guid != NULL && Value != NULL);
1402
1403 //
1404 // Try to get the variable size.
1405 //
1406 BufferSize = 0;
1407 *Value = NULL;
1408 if (Size != NULL) {
1409 *Size = 0;
1410 }
1411
1412 Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &BufferSize, *Value);
1413 if (Status != EFI_BUFFER_TOO_SMALL) {
1414 return Status;
1415 }
1416
1417 //
1418 // Allocate buffer to get the variable.
1419 //
1420 *Value = AllocatePool (BufferSize);
1421 ASSERT (*Value != NULL);
1422 if (*Value == NULL) {
1423 return EFI_OUT_OF_RESOURCES;
1424 }
1425
1426 //
1427 // Get the variable data.
1428 //
1429 Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &BufferSize, *Value);
1430 if (EFI_ERROR (Status)) {
1431 FreePool(*Value);
1432 *Value = NULL;
1433 }
1434
1435 if (Size != NULL) {
1436 *Size = BufferSize;
1437 }
1438
1439 return Status;
1440 }
1441
1442 /**
1443 Returns a pointer to an allocated buffer that contains the contents of a
1444 variable retrieved through the UEFI Runtime Service GetVariable(). This
1445 function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1446 The returned buffer is allocated using AllocatePool(). The caller is
1447 responsible for freeing this buffer with FreePool().
1448
1449 If Name is NULL, then ASSERT().
1450 If Value is NULL, then ASSERT().
1451
1452 @param[in] Name The pointer to a Null-terminated Unicode string.
1453 @param[out] Value The buffer point saved the variable info.
1454 @param[out] Size The buffer size of the variable.
1455
1456 @return EFI_OUT_OF_RESOURCES Allocate buffer failed.
1457 @return EFI_SUCCESS Find the specified variable.
1458 @return Others Errors Return errors from call to gRT->GetVariable.
1459
1460 **/
1461 EFI_STATUS
1462 EFIAPI
1463 GetEfiGlobalVariable2 (
1464 IN CONST CHAR16 *Name,
1465 OUT VOID **Value,
1466 OUT UINTN *Size OPTIONAL
1467 )
1468 {
1469 return GetVariable2 (Name, &gEfiGlobalVariableGuid, Value, Size);
1470 }
1471
1472 /**
1473 Returns a pointer to an allocated buffer that contains the best matching language
1474 from a set of supported languages.
1475
1476 This function supports both ISO 639-2 and RFC 4646 language codes, but language
1477 code types may not be mixed in a single call to this function. The language
1478 code returned is allocated using AllocatePool(). The caller is responsible for
1479 freeing the allocated buffer using FreePool(). This function supports a variable
1480 argument list that allows the caller to pass in a prioritized list of language
1481 codes to test against all the language codes in SupportedLanguages.
1482
1483 If SupportedLanguages is NULL, then ASSERT().
1484
1485 @param[in] SupportedLanguages A pointer to a Null-terminated ASCII string that
1486 contains a set of language codes in the format
1487 specified by Iso639Language.
1488 @param[in] Iso639Language If TRUE, then all language codes are assumed to be
1489 in ISO 639-2 format. If FALSE, then all language
1490 codes are assumed to be in RFC 4646 language format
1491 @param[in] ... A variable argument list that contains pointers to
1492 Null-terminated ASCII strings that contain one or more
1493 language codes in the format specified by Iso639Language.
1494 The first language code from each of these language
1495 code lists is used to determine if it is an exact or
1496 close match to any of the language codes in
1497 SupportedLanguages. Close matches only apply to RFC 4646
1498 language codes, and the matching algorithm from RFC 4647
1499 is used to determine if a close match is present. If
1500 an exact or close match is found, then the matching
1501 language code from SupportedLanguages is returned. If
1502 no matches are found, then the next variable argument
1503 parameter is evaluated. The variable argument list
1504 is terminated by a NULL.
1505
1506 @retval NULL The best matching language could not be found in SupportedLanguages.
1507 @retval NULL There are not enough resources available to return the best matching
1508 language.
1509 @retval Other A pointer to a Null-terminated ASCII string that is the best matching
1510 language in SupportedLanguages.
1511
1512 **/
1513 CHAR8 *
1514 EFIAPI
1515 GetBestLanguage (
1516 IN CONST CHAR8 *SupportedLanguages,
1517 IN UINTN Iso639Language,
1518 ...
1519 )
1520 {
1521 VA_LIST Args;
1522 CHAR8 *Language;
1523 UINTN CompareLength;
1524 UINTN LanguageLength;
1525 CONST CHAR8 *Supported;
1526 CHAR8 *BestLanguage;
1527
1528 ASSERT (SupportedLanguages != NULL);
1529
1530 VA_START (Args, Iso639Language);
1531 while ((Language = VA_ARG (Args, CHAR8 *)) != NULL) {
1532 //
1533 // Default to ISO 639-2 mode
1534 //
1535 CompareLength = 3;
1536 LanguageLength = MIN (3, AsciiStrLen (Language));
1537
1538 //
1539 // If in RFC 4646 mode, then determine the length of the first RFC 4646 language code in Language
1540 //
1541 if (!Iso639Language) {
1542 for (LanguageLength = 0; Language[LanguageLength] != 0 && Language[LanguageLength] != ';'; LanguageLength++);
1543 }
1544
1545 //
1546 // Trim back the length of Language used until it is empty
1547 //
1548 while (LanguageLength > 0) {
1549 //
1550 // Loop through all language codes in SupportedLanguages
1551 //
1552 for (Supported = SupportedLanguages; *Supported != '\0'; Supported += CompareLength) {
1553 //
1554 // In RFC 4646 mode, then Loop through all language codes in SupportedLanguages
1555 //
1556 if (!Iso639Language) {
1557 //
1558 // Skip ';' characters in Supported
1559 //
1560 for (; *Supported != '\0' && *Supported == ';'; Supported++);
1561 //
1562 // Determine the length of the next language code in Supported
1563 //
1564 for (CompareLength = 0; Supported[CompareLength] != 0 && Supported[CompareLength] != ';'; CompareLength++);
1565 //
1566 // If Language is longer than the Supported, then skip to the next language
1567 //
1568 if (LanguageLength > CompareLength) {
1569 continue;
1570 }
1571 }
1572 //
1573 // See if the first LanguageLength characters in Supported match Language
1574 //
1575 if (AsciiStrnCmp (Supported, Language, LanguageLength) == 0) {
1576 VA_END (Args);
1577 //
1578 // Allocate, copy, and return the best matching language code from SupportedLanguages
1579 //
1580 BestLanguage = AllocateZeroPool (CompareLength + 1);
1581 if (BestLanguage == NULL) {
1582 return NULL;
1583 }
1584 return CopyMem (BestLanguage, Supported, CompareLength);
1585 }
1586 }
1587
1588 if (Iso639Language) {
1589 //
1590 // If ISO 639 mode, then each language can only be tested once
1591 //
1592 LanguageLength = 0;
1593 } else {
1594 //
1595 // If RFC 4646 mode, then trim Language from the right to the next '-' character
1596 //
1597 for (LanguageLength--; LanguageLength > 0 && Language[LanguageLength] != '-'; LanguageLength--);
1598 }
1599 }
1600 }
1601 VA_END (Args);
1602
1603 //
1604 // No matches were found
1605 //
1606 return NULL;
1607 }
1608
1609 /**
1610 Returns an array of protocol instance that matches the given protocol.
1611
1612 @param[in] Protocol Provides the protocol to search for.
1613 @param[out] NoProtocols The number of protocols returned in Buffer.
1614 @param[out] Buffer A pointer to the buffer to return the requested
1615 array of protocol instances that match Protocol.
1616 The returned buffer is allocated using
1617 EFI_BOOT_SERVICES.AllocatePool(). The caller is
1618 responsible for freeing this buffer with
1619 EFI_BOOT_SERVICES.FreePool().
1620
1621 @retval EFI_SUCCESS The array of protocols was returned in Buffer,
1622 and the number of protocols in Buffer was
1623 returned in NoProtocols.
1624 @retval EFI_NOT_FOUND No protocols found.
1625 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
1626 matching results.
1627 @retval EFI_INVALID_PARAMETER Protocol is NULL.
1628 @retval EFI_INVALID_PARAMETER NoProtocols is NULL.
1629 @retval EFI_INVALID_PARAMETER Buffer is NULL.
1630
1631 **/
1632 EFI_STATUS
1633 EFIAPI
1634 EfiLocateProtocolBuffer (
1635 IN EFI_GUID *Protocol,
1636 OUT UINTN *NoProtocols,
1637 OUT VOID ***Buffer
1638 )
1639 {
1640 EFI_STATUS Status;
1641 UINTN NoHandles;
1642 EFI_HANDLE *HandleBuffer;
1643 UINTN Index;
1644
1645 //
1646 // Check input parameters
1647 //
1648 if (Protocol == NULL || NoProtocols == NULL || Buffer == NULL) {
1649 return EFI_INVALID_PARAMETER;
1650 }
1651
1652 //
1653 // Initialze output parameters
1654 //
1655 *NoProtocols = 0;
1656 *Buffer = NULL;
1657
1658 //
1659 // Retrieve the array of handles that support Protocol
1660 //
1661 Status = gBS->LocateHandleBuffer (
1662 ByProtocol,
1663 Protocol,
1664 NULL,
1665 &NoHandles,
1666 &HandleBuffer
1667 );
1668 if (EFI_ERROR (Status)) {
1669 return Status;
1670 }
1671
1672 //
1673 // Allocate array of protocol instances
1674 //
1675 Status = gBS->AllocatePool (
1676 EfiBootServicesData,
1677 NoHandles * sizeof (VOID *),
1678 (VOID **)Buffer
1679 );
1680 if (EFI_ERROR (Status)) {
1681 //
1682 // Free the handle buffer
1683 //
1684 gBS->FreePool (HandleBuffer);
1685 return EFI_OUT_OF_RESOURCES;
1686 }
1687 ZeroMem (*Buffer, NoHandles * sizeof (VOID *));
1688
1689 //
1690 // Lookup Protocol on each handle in HandleBuffer to fill in the array of
1691 // protocol instances. Handle case where protocol instance was present when
1692 // LocateHandleBuffer() was called, but is not present when HandleProtocol()
1693 // is called.
1694 //
1695 for (Index = 0, *NoProtocols = 0; Index < NoHandles; Index++) {
1696 Status = gBS->HandleProtocol (
1697 HandleBuffer[Index],
1698 Protocol,
1699 &((*Buffer)[*NoProtocols])
1700 );
1701 if (!EFI_ERROR (Status)) {
1702 (*NoProtocols)++;
1703 }
1704 }
1705
1706 //
1707 // Free the handle buffer
1708 //
1709 gBS->FreePool (HandleBuffer);
1710
1711 //
1712 // Make sure at least one protocol instance was found
1713 //
1714 if (*NoProtocols == 0) {
1715 gBS->FreePool (*Buffer);
1716 *Buffer = NULL;
1717 return EFI_NOT_FOUND;
1718 }
1719
1720 return EFI_SUCCESS;
1721 }