Import BaseMemoryLibMmx;
[mirror_edk2.git] / MdePkg / Library / UefiLib / UefiLib.c
1 /** @file
2 Mde UEFI library functions.
3
4 Copyright (c) 2006 - 2007, Intel Corporation<BR>
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 Module Name: UefiLib.c
14
15 **/
16
17 //
18 // Include common header file for this module.
19 //
20 #include "CommonHeader.h"
21
22 /**
23 Compare whether two names of languages are identical.
24
25 @param Language1 Name of language 1.
26 @param Language2 Name of language 2.
27
28 @retval TRUE Language 1 and language 2 are the same.
29 @retval FALSE Language 1 and language 2 are not the same.
30
31 **/
32 STATIC
33 BOOLEAN
34 CompareIso639LanguageCode (
35 IN CONST CHAR8 *Language1,
36 IN CONST CHAR8 *Language2
37 )
38 {
39 UINT32 Name1;
40 UINT32 Name2;
41
42 Name1 = ReadUnaligned24 ((CONST UINT32 *) Language1);
43 Name2 = ReadUnaligned24 ((CONST UINT32 *) Language2);
44
45 return (BOOLEAN) (Name1 == Name2);
46 }
47
48 /**
49 This function searches the list of configuration tables stored in the EFI System
50 Table for a table with a GUID that matches TableGuid. If a match is found,
51 then a pointer to the configuration table is returned in Table, and EFI_SUCCESS
52 is returned. If a matching GUID is not found, then EFI_NOT_FOUND is returned.
53
54 @param TableGuid Pointer to table's GUID type..
55 @param Table Pointer to the table associated with TableGuid in the EFI System Table.
56
57 @retval EFI_SUCCESS A configuration table matching TableGuid was found.
58 @retval EFI_NOT_FOUND A configuration table matching TableGuid could not be found.
59
60 **/
61 EFI_STATUS
62 EFIAPI
63 EfiGetSystemConfigurationTable (
64 IN EFI_GUID *TableGuid,
65 OUT VOID **Table
66 )
67 {
68 EFI_SYSTEM_TABLE *SystemTable;
69 UINTN Index;
70
71 ASSERT (TableGuid != NULL);
72 ASSERT (Table != NULL);
73
74 SystemTable = gST;
75 *Table = NULL;
76 for (Index = 0; Index < SystemTable->NumberOfTableEntries; Index++) {
77 if (CompareGuid (TableGuid, &(SystemTable->ConfigurationTable[Index].VendorGuid))) {
78 *Table = SystemTable->ConfigurationTable[Index].VendorTable;
79 return EFI_SUCCESS;
80 }
81 }
82
83 return EFI_NOT_FOUND;
84 }
85
86 /**
87 This function causes the notification function to be executed for every protocol
88 of type ProtocolGuid instance that exists in the system when this function is
89 invoked. In addition, every time a protocol of type ProtocolGuid instance is
90 installed or reinstalled, the notification function is also executed.
91
92 @param ProtocolGuid Supplies GUID of the protocol upon whose installation the event is fired.
93 @param NotifyTpl Supplies the task priority level of the event notifications.
94 @param NotifyFunction Supplies the function to notify when the event is signaled.
95 @param NotifyContext The context parameter to pass to NotifyFunction.
96 @param Registration A pointer to a memory location to receive the registration value.
97
98 @return The notification event that was created.
99
100 **/
101 EFI_EVENT
102 EFIAPI
103 EfiCreateProtocolNotifyEvent(
104 IN EFI_GUID *ProtocolGuid,
105 IN EFI_TPL NotifyTpl,
106 IN EFI_EVENT_NOTIFY NotifyFunction,
107 IN VOID *NotifyContext, OPTIONAL
108 OUT VOID **Registration
109 )
110 {
111 EFI_STATUS Status;
112 EFI_EVENT Event;
113
114 //
115 // Create the event
116 //
117
118 Status = gBS->CreateEvent (
119 EVT_NOTIFY_SIGNAL,
120 NotifyTpl,
121 NotifyFunction,
122 NotifyContext,
123 &Event
124 );
125 ASSERT_EFI_ERROR (Status);
126
127 //
128 // Register for protocol notifactions on this event
129 //
130
131 Status = gBS->RegisterProtocolNotify (
132 ProtocolGuid,
133 Event,
134 Registration
135 );
136
137 ASSERT_EFI_ERROR (Status);
138
139 //
140 // Kick the event so we will perform an initial pass of
141 // current installed drivers
142 //
143
144 gBS->SignalEvent (Event);
145 return Event;
146 }
147
148 /**
149 This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.
150 This event is signaled with EfiNamedEventSignal(). This provide the ability for
151 one or more listeners on the same event named by the GUID specified by Name.
152
153 @param Name Supplies GUID name of the event.
154 @param NotifyTpl Supplies the task priority level of the event notifications.
155 @param NotifyFunction Supplies the function to notify when the event is signaled.
156 @param NotifyContext The context parameter to pass to NotifyFunction.
157 @param Registration A pointer to a memory location to receive the registration value.
158
159 @retval EFI_SUCCESS A named event was created.
160 @retval EFI_OUT_OF_RESOURCES There are not enough resource to create the named event.
161
162 **/
163 EFI_STATUS
164 EFIAPI
165 EfiNamedEventListen (
166 IN CONST EFI_GUID *Name,
167 IN EFI_TPL NotifyTpl,
168 IN EFI_EVENT_NOTIFY NotifyFunction,
169 IN CONST VOID *NotifyContext, OPTIONAL
170 OUT VOID *Registration OPTIONAL
171 )
172 {
173 EFI_STATUS Status;
174 EFI_EVENT Event;
175 VOID *RegistrationLocal;
176
177 //
178 // Create event
179 //
180 Status = gBS->CreateEvent (
181 EVT_NOTIFY_SIGNAL,
182 NotifyTpl,
183 NotifyFunction,
184 (VOID *) NotifyContext,
185 &Event
186 );
187 ASSERT_EFI_ERROR (Status);
188
189 //
190 // The Registration is not optional to RegisterProtocolNotify().
191 // To make it optional to EfiNamedEventListen(), may need to substitute with a local.
192 //
193 if (Registration != NULL) {
194 RegistrationLocal = Registration;
195 } else {
196 RegistrationLocal = &RegistrationLocal;
197 }
198
199 //
200 // Register for an installation of protocol interface
201 //
202
203 Status = gBS->RegisterProtocolNotify (
204 (EFI_GUID *) Name,
205 Event,
206 RegistrationLocal
207 );
208 ASSERT_EFI_ERROR (Status);
209
210 return EFI_SUCCESS;
211 }
212
213 /**
214 This function signals the named event specified by Name. The named event must
215 have been created with EfiNamedEventListen().
216
217 @param Name Supplies GUID name of the event.
218
219 @retval EFI_SUCCESS A named event was signaled.
220 @retval EFI_OUT_OF_RESOURCES There are not enough resource to signal the named event.
221
222 **/
223 EFI_STATUS
224 EFIAPI
225 EfiNamedEventSignal (
226 IN CONST EFI_GUID *Name
227 )
228 {
229 EFI_STATUS Status;
230 EFI_HANDLE Handle;
231
232 Handle = NULL;
233 Status = gBS->InstallProtocolInterface (
234 &Handle,
235 (EFI_GUID *) Name,
236 EFI_NATIVE_INTERFACE,
237 NULL
238 );
239 ASSERT_EFI_ERROR (Status);
240
241 Status = gBS->UninstallProtocolInterface (
242 Handle,
243 (EFI_GUID *) Name,
244 NULL
245 );
246 ASSERT_EFI_ERROR (Status);
247
248 return EFI_SUCCESS;
249 }
250
251 /**
252 Returns the current TPL.
253
254 This function returns the current TPL. There is no EFI service to directly
255 retrieve the current TPL. Instead, the RaiseTPL() function is used to raise
256 the TPL to TPL_HIGH_LEVEL. This will return the current TPL. The TPL level
257 can then immediately be restored back to the current TPL level with a call
258 to RestoreTPL().
259
260 @param VOID
261
262 @retvale EFI_TPL The current TPL.
263
264 **/
265 EFI_TPL
266 EFIAPI
267 EfiGetCurrentTpl (
268 VOID
269 )
270 {
271 EFI_TPL Tpl;
272
273 Tpl = gBS->RaiseTPL (TPL_HIGH_LEVEL);
274 gBS->RestoreTPL (Tpl);
275
276 return Tpl;
277 }
278
279
280 /**
281 This function initializes a basic mutual exclusion lock to the released state
282 and returns the lock. Each lock provides mutual exclusion access at its task
283 priority level. Since there is no preemption or multiprocessor support in EFI,
284 acquiring the lock only consists of raising to the locks TPL.
285
286 @param Lock A pointer to the lock data structure to initialize.
287 @param Priority EFI TPL associated with the lock.
288
289 @return The lock.
290
291 **/
292 EFI_LOCK *
293 EFIAPI
294 EfiInitializeLock (
295 IN OUT EFI_LOCK *Lock,
296 IN EFI_TPL Priority
297 )
298 {
299 ASSERT (Lock != NULL);
300 ASSERT (Priority <= TPL_HIGH_LEVEL);
301
302 Lock->Tpl = Priority;
303 Lock->OwnerTpl = TPL_APPLICATION;
304 Lock->Lock = EfiLockReleased ;
305 return Lock;
306 }
307
308 /**
309 This function raises the system's current task priority level to the task
310 priority level of the mutual exclusion lock. Then, it places the lock in the
311 acquired state.
312
313 @param Priority The task priority level of the lock.
314
315 **/
316 VOID
317 EFIAPI
318 EfiAcquireLock (
319 IN EFI_LOCK *Lock
320 )
321 {
322 ASSERT (Lock != NULL);
323 ASSERT (Lock->Lock == EfiLockReleased);
324
325 Lock->OwnerTpl = gBS->RaiseTPL (Lock->Tpl);
326 Lock->Lock = EfiLockAcquired;
327 }
328
329 /**
330 This function raises the system's current task priority level to the task
331 priority level of the mutual exclusion lock. Then, it attempts to place the
332 lock in the acquired state.
333
334 @param Lock A pointer to the lock to acquire.
335
336 @retval EFI_SUCCESS The lock was acquired.
337 @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
338
339 **/
340 EFI_STATUS
341 EFIAPI
342 EfiAcquireLockOrFail (
343 IN EFI_LOCK *Lock
344 )
345 {
346
347 ASSERT (Lock != NULL);
348 ASSERT (Lock->Lock != EfiLockUninitialized);
349
350 if (Lock->Lock == EfiLockAcquired) {
351 //
352 // Lock is already owned, so bail out
353 //
354 return EFI_ACCESS_DENIED;
355 }
356
357 Lock->OwnerTpl = gBS->RaiseTPL (Lock->Tpl);
358
359 Lock->Lock = EfiLockAcquired;
360
361 return EFI_SUCCESS;
362 }
363
364 /**
365 This function transitions a mutual exclusion lock from the acquired state to
366 the released state, and restores the system's task priority level to its
367 previous level.
368
369 @param Lock A pointer to the lock to release.
370
371 **/
372 VOID
373 EFIAPI
374 EfiReleaseLock (
375 IN EFI_LOCK *Lock
376 )
377 {
378 EFI_TPL Tpl;
379
380 ASSERT (Lock != NULL);
381 ASSERT (Lock->Lock == EfiLockAcquired);
382
383 Tpl = Lock->OwnerTpl;
384
385 Lock->Lock = EfiLockReleased;
386
387 gBS->RestoreTPL (Tpl);
388 }
389
390 /**
391 Tests whether a controller handle is being managed by a specific driver.
392
393 This function tests whether the driver specified by DriverBindingHandle is
394 currently managing the controller specified by ControllerHandle. This test
395 is performed by evaluating if the the protocol specified by ProtocolGuid is
396 present on ControllerHandle and is was opened by DriverBindingHandle with an
397 attribute of EFI_OPEN_PROTOCOL_BY_DRIVER.
398 If ProtocolGuid is NULL, then ASSERT().
399
400 @param ControllerHandle A handle for a controller to test.
401 @param DriverBindingHandle Specifies the driver binding handle for the
402 driver.
403 @param ProtocolGuid Specifies the protocol that the driver specified
404 by DriverBindingHandle opens in its Start()
405 function.
406
407 @retval EFI_SUCCESS ControllerHandle is managed by the driver
408 specifed by DriverBindingHandle.
409 @retval EFI_UNSUPPORTED ControllerHandle is not managed by the driver
410 specifed by DriverBindingHandle.
411
412 **/
413 EFI_STATUS
414 EFIAPI
415 EfiTestManagedDevice (
416 IN CONST EFI_HANDLE ControllerHandle,
417 IN CONST EFI_HANDLE DriverBindingHandle,
418 IN CONST EFI_GUID *ProtocolGuid
419 )
420 {
421 EFI_STATUS Status;
422 VOID *ManagedInterface;
423
424 ASSERT (ProtocolGuid != NULL);
425
426 Status = gBS->OpenProtocol (
427 ControllerHandle,
428 (EFI_GUID *) ProtocolGuid,
429 &ManagedInterface,
430 DriverBindingHandle,
431 ControllerHandle,
432 EFI_OPEN_PROTOCOL_BY_DRIVER
433 );
434 if (!EFI_ERROR (Status)) {
435 gBS->CloseProtocol (
436 ControllerHandle,
437 (EFI_GUID *) ProtocolGuid,
438 DriverBindingHandle,
439 ControllerHandle
440 );
441 return EFI_UNSUPPORTED;
442 }
443
444 if (Status != EFI_ALREADY_STARTED) {
445 return EFI_UNSUPPORTED;
446 }
447
448 return EFI_SUCCESS;
449 }
450
451 /**
452 Tests whether a child handle is a child device of the controller.
453
454 This function tests whether ChildHandle is one of the children of
455 ControllerHandle. This test is performed by checking to see if the protocol
456 specified by ProtocolGuid is present on ControllerHandle and opened by
457 ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
458 If ProtocolGuid is NULL, then ASSERT().
459
460 @param ControllerHandle A handle for a (parent) controller to test.
461 @param ChildHandle A child handle to test.
462 @param ConsumsedGuid Supplies the protocol that the child controller
463 opens on its parent controller.
464
465 @retval EFI_SUCCESS ChildHandle is a child of the ControllerHandle.
466 @retval EFI_UNSUPPORTED ChildHandle is not a child of the
467 ControllerHandle.
468
469 **/
470 EFI_STATUS
471 EFIAPI
472 EfiTestChildHandle (
473 IN CONST EFI_HANDLE ControllerHandle,
474 IN CONST EFI_HANDLE ChildHandle,
475 IN CONST EFI_GUID *ProtocolGuid
476 )
477 {
478 EFI_STATUS Status;
479 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY *OpenInfoBuffer;
480 UINTN EntryCount;
481 UINTN Index;
482
483 ASSERT (ProtocolGuid != NULL);
484
485 //
486 // Retrieve the list of agents that are consuming the specific protocol
487 // on ControllerHandle.
488 //
489 Status = gBS->OpenProtocolInformation (
490 ControllerHandle,
491 (EFI_GUID *) ProtocolGuid,
492 &OpenInfoBuffer,
493 &EntryCount
494 );
495 if (EFI_ERROR (Status)) {
496 return EFI_UNSUPPORTED;
497 }
498
499 //
500 // Inspect if ChildHandle is one of the agents.
501 //
502 Status = EFI_UNSUPPORTED;
503 for (Index = 0; Index < EntryCount; Index++) {
504 if ((OpenInfoBuffer[Index].ControllerHandle == ChildHandle) &&
505 (OpenInfoBuffer[Index].Attributes & EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER) != 0) {
506 Status = EFI_SUCCESS;
507 break;
508 }
509 }
510
511 FreePool (OpenInfoBuffer);
512 return Status;
513 }
514
515 /**
516 This function looks up a Unicode string in UnicodeStringTable.
517 If Language is a member of SupportedLanguages and a Unicode
518 string is found in UnicodeStringTable that matches the
519 language code specified by Language, then it is returned in
520 UnicodeString.
521
522 @param Language A pointer to the ISO 639-2
523 language code for the Unicode
524 string to look up and return.
525
526 @param SupportedLanguages A pointer to the set of ISO
527 639-2language
528 codes that the Unicode string
529 table supports. Language must
530 be a member of this set.
531
532 @param UnicodeStringTable A pointer to the table of
533 Unicode strings.
534
535 @param UnicodeString A pointer to the Unicode
536 string from UnicodeStringTable
537 that matches the language
538 specified by Language.
539
540 @retval EFI_SUCCESS The Unicode string that
541 matches the language specified
542 by Language was found in the
543 table of Unicoide strings
544 UnicodeStringTable, and it was
545 returned in UnicodeString.
546
547 @retval EFI_INVALID_PARAMETER Language is NULL.
548
549 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
550 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
551
552 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
553
554 @retval EFI_UNSUPPORTED The language specified by
555 Language is not a member
556 ofSupportedLanguages.
557
558 @retval EFI_UNSUPPORTED The language specified by
559 Language is not supported by
560 UnicodeStringTable.
561
562 **/
563 EFI_STATUS
564 EFIAPI
565 LookupUnicodeString (
566 IN CONST CHAR8 *Language,
567 IN CONST CHAR8 *SupportedLanguages,
568 IN CONST EFI_UNICODE_STRING_TABLE *UnicodeStringTable,
569 OUT CHAR16 **UnicodeString
570 )
571 {
572 //
573 // Make sure the parameters are valid
574 //
575 if (Language == NULL || UnicodeString == NULL) {
576 return EFI_INVALID_PARAMETER;
577 }
578
579 //
580 // If there are no supported languages, or the Unicode String Table is empty, then the
581 // Unicode String specified by Language is not supported by this Unicode String Table
582 //
583 if (SupportedLanguages == NULL || UnicodeStringTable == NULL) {
584 return EFI_UNSUPPORTED;
585 }
586
587 //
588 // Make sure Language is in the set of Supported Languages
589 //
590 while (*SupportedLanguages != 0) {
591 if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
592
593 //
594 // Search the Unicode String Table for the matching Language specifier
595 //
596 while (UnicodeStringTable->Language != NULL) {
597 if (CompareIso639LanguageCode (Language, UnicodeStringTable->Language)) {
598
599 //
600 // A matching string was found, so return it
601 //
602 *UnicodeString = UnicodeStringTable->UnicodeString;
603 return EFI_SUCCESS;
604 }
605
606 UnicodeStringTable++;
607 }
608
609 return EFI_UNSUPPORTED;
610 }
611
612 SupportedLanguages += 3;
613 }
614
615 return EFI_UNSUPPORTED;
616 }
617
618
619
620 /**
621 This function looks up a Unicode string in UnicodeStringTable.
622 If Language is a member of SupportedLanguages and a Unicode
623 string is found in UnicodeStringTable that matches the
624 language code specified by Language, then it is returned in
625 UnicodeString.
626
627 @param Language A pointer to the ISO 639-2 or
628 RFC 3066 language code for the
629 Unicode string to look up and
630 return.
631
632 @param SupportedLanguages A pointer to the set of ISO
633 639-2 or RFC 3066 language
634 codes that the Unicode string
635 table supports. Language must
636 be a member of this set.
637
638 @param UnicodeStringTable A pointer to the table of
639 Unicode strings.
640
641 @param UnicodeString A pointer to the Unicode
642 string from UnicodeStringTable
643 that matches the language
644 specified by Language.
645
646 @param Iso639Language Specify the language code
647 format supported. If true,
648 then the format follow ISO
649 639-2. If false, then it
650 follows RFC3066.
651
652 @retval EFI_SUCCESS The Unicode string that
653 matches the language specified
654 by Language was found in the
655 table of Unicoide strings
656 UnicodeStringTable, and it was
657 returned in UnicodeString.
658
659 @retval EFI_INVALID_PARAMETER Language is NULL.
660
661 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
662
663 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
664
665 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
666
667 @retval EFI_UNSUPPORTED The language specified by
668 Language is not a member
669 ofSupportedLanguages.
670
671 @retval EFI_UNSUPPORTED The language specified by
672 Language is not supported by
673 UnicodeStringTable.
674
675 **/
676 EFI_STATUS
677 EFIAPI
678 LookupUnicodeString2 (
679 IN CONST CHAR8 *Language,
680 IN CONST CHAR8 *SupportedLanguages,
681 IN CONST EFI_UNICODE_STRING_TABLE *UnicodeStringTable,
682 OUT CHAR16 **UnicodeString,
683 IN BOOLEAN Iso639Language
684 )
685 {
686 BOOLEAN Found;
687 UINTN Index;
688 CHAR8 *LanguageString;
689
690 //
691 // Make sure the parameters are valid
692 //
693 if (Language == NULL || UnicodeString == NULL) {
694 return EFI_INVALID_PARAMETER;
695 }
696
697 //
698 // If there are no supported languages, or the Unicode String Table is empty, then the
699 // Unicode String specified by Language is not supported by this Unicode String Table
700 //
701 if (SupportedLanguages == NULL || UnicodeStringTable == NULL) {
702 return EFI_UNSUPPORTED;
703 }
704
705 //
706 // Make sure Language is in the set of Supported Languages
707 //
708 Found = FALSE;
709 while (*SupportedLanguages != 0) {
710 if (Iso639Language) {
711 if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
712 Found = TRUE;
713 break;
714 }
715 SupportedLanguages += 3;
716 } else {
717 for (Index = 0; SupportedLanguages[Index] != 0 && SupportedLanguages[Index] != ';'; Index++);
718 if (AsciiStrnCmp(SupportedLanguages, Language, Index) == 0) {
719 Found = TRUE;
720 break;
721 }
722 SupportedLanguages += Index;
723 for (; *SupportedLanguages != 0 && *SupportedLanguages == ';'; SupportedLanguages++);
724 }
725 }
726
727 //
728 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
729 //
730 if (!Found) {
731 return EFI_UNSUPPORTED;
732 }
733
734 //
735 // Search the Unicode String Table for the matching Language specifier
736 //
737 while (UnicodeStringTable->Language != NULL) {
738 LanguageString = UnicodeStringTable->Language;
739 while (0 != *LanguageString) {
740 for (Index = 0 ;LanguageString[Index] != 0 && LanguageString[Index] != ';'; Index++);
741 if (AsciiStrnCmp(LanguageString, Language, Index) == 0) {
742 *UnicodeString = UnicodeStringTable->UnicodeString;
743 return EFI_SUCCESS;
744 }
745 LanguageString += Index;
746 for (Index = 0 ;LanguageString[Index] != 0 && LanguageString[Index] == ';'; Index++);
747 }
748 UnicodeStringTable++;
749 }
750
751 return EFI_UNSUPPORTED;
752 }
753
754
755 /**
756
757 This function adds a Unicode string to UnicodeStringTable.
758 If Language is a member of SupportedLanguages then
759 UnicodeString is added to UnicodeStringTable. New buffers are
760 allocated for both Language and UnicodeString. The contents
761 of Language and UnicodeString are copied into these new
762 buffers. These buffers are automatically freed when
763 FreeUnicodeStringTable() is called.
764
765 @param Language A pointer to the ISO 639-2
766 language code for the Unicode
767 string to add.
768
769 @param SupportedLanguages A pointer to the set of ISO
770 639-2 language codes that the
771 Unicode string table supports.
772 Language must be a member of
773 this set.
774
775 @param UnicodeStringTable A pointer to the table of
776 Unicode strings.
777
778 @param UnicodeString A pointer to the Unicode
779 string to add.
780
781 @retval EFI_SUCCESS The Unicode string that
782 matches the language specified
783 by Language was found in the
784 table of Unicode strings
785 UnicodeStringTable, and it was
786 returned in UnicodeString.
787
788 @retval EFI_INVALID_PARAMETER Language is NULL.
789
790 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
791
792 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
793
794 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
795
796 @retval EFI_ALREADY_STARTED A Unicode string with language
797 Language is already present in
798 UnicodeStringTable.
799
800 @retval EFI_OUT_OF_RESOURCES There is not enough memory to
801 add another Unicode string to
802 UnicodeStringTable.
803
804 @retval EFI_UNSUPPORTED The language specified by
805 Language is not a member of
806 SupportedLanguages.
807
808 **/
809 EFI_STATUS
810 EFIAPI
811 AddUnicodeString (
812 IN CONST CHAR8 *Language,
813 IN CONST CHAR8 *SupportedLanguages,
814 IN EFI_UNICODE_STRING_TABLE **UnicodeStringTable,
815 IN CONST CHAR16 *UnicodeString
816 )
817 {
818 UINTN NumberOfEntries;
819 EFI_UNICODE_STRING_TABLE *OldUnicodeStringTable;
820 EFI_UNICODE_STRING_TABLE *NewUnicodeStringTable;
821 UINTN UnicodeStringLength;
822
823 //
824 // Make sure the parameter are valid
825 //
826 if (Language == NULL || UnicodeString == NULL || UnicodeStringTable == NULL) {
827 return EFI_INVALID_PARAMETER;
828 }
829
830 //
831 // If there are no supported languages, then a Unicode String can not be added
832 //
833 if (SupportedLanguages == NULL) {
834 return EFI_UNSUPPORTED;
835 }
836
837 //
838 // If the Unicode String is empty, then a Unicode String can not be added
839 //
840 if (UnicodeString[0] == 0) {
841 return EFI_INVALID_PARAMETER;
842 }
843
844 //
845 // Make sure Language is a member of SupportedLanguages
846 //
847 while (*SupportedLanguages != 0) {
848 if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
849
850 //
851 // Determine the size of the Unicode String Table by looking for a NULL Language entry
852 //
853 NumberOfEntries = 0;
854 if (*UnicodeStringTable != NULL) {
855 OldUnicodeStringTable = *UnicodeStringTable;
856 while (OldUnicodeStringTable->Language != NULL) {
857 if (CompareIso639LanguageCode (Language, OldUnicodeStringTable->Language)) {
858 return EFI_ALREADY_STARTED;
859 }
860
861 OldUnicodeStringTable++;
862 NumberOfEntries++;
863 }
864 }
865
866 //
867 // Allocate space for a new Unicode String Table. It must hold the current number of
868 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
869 // marker
870 //
871 NewUnicodeStringTable = AllocatePool ((NumberOfEntries + 2) * sizeof (EFI_UNICODE_STRING_TABLE));
872 if (NewUnicodeStringTable == NULL) {
873 return EFI_OUT_OF_RESOURCES;
874 }
875
876 //
877 // If the current Unicode String Table contains any entries, then copy them to the
878 // newly allocated Unicode String Table.
879 //
880 if (*UnicodeStringTable != NULL) {
881 CopyMem (
882 NewUnicodeStringTable,
883 *UnicodeStringTable,
884 NumberOfEntries * sizeof (EFI_UNICODE_STRING_TABLE)
885 );
886 }
887
888 //
889 // Allocate space for a copy of the Language specifier
890 //
891 NewUnicodeStringTable[NumberOfEntries].Language = AllocateCopyPool (3, Language);
892 if (NewUnicodeStringTable[NumberOfEntries].Language == NULL) {
893 gBS->FreePool (NewUnicodeStringTable);
894 return EFI_OUT_OF_RESOURCES;
895 }
896
897 //
898 // Compute the length of the Unicode String
899 //
900 for (UnicodeStringLength = 0; UnicodeString[UnicodeStringLength] != 0; UnicodeStringLength++)
901 ;
902
903 //
904 // Allocate space for a copy of the Unicode String
905 //
906 NewUnicodeStringTable[NumberOfEntries].UnicodeString = AllocateCopyPool (
907 (UnicodeStringLength + 1) * sizeof (CHAR16),
908 UnicodeString
909 );
910 if (NewUnicodeStringTable[NumberOfEntries].UnicodeString == NULL) {
911 gBS->FreePool (NewUnicodeStringTable[NumberOfEntries].Language);
912 gBS->FreePool (NewUnicodeStringTable);
913 return EFI_OUT_OF_RESOURCES;
914 }
915
916 //
917 // Mark the end of the Unicode String Table
918 //
919 NewUnicodeStringTable[NumberOfEntries + 1].Language = NULL;
920 NewUnicodeStringTable[NumberOfEntries + 1].UnicodeString = NULL;
921
922 //
923 // Free the old Unicode String Table
924 //
925 if (*UnicodeStringTable != NULL) {
926 gBS->FreePool (*UnicodeStringTable);
927 }
928
929 //
930 // Point UnicodeStringTable at the newly allocated Unicode String Table
931 //
932 *UnicodeStringTable = NewUnicodeStringTable;
933
934 return EFI_SUCCESS;
935 }
936
937 SupportedLanguages += 3;
938 }
939
940 return EFI_UNSUPPORTED;
941 }
942
943
944 /**
945
946 This function adds a Unicode string to UnicodeStringTable.
947 If Language is a member of SupportedLanguages then
948 UnicodeString is added to UnicodeStringTable. New buffers are
949 allocated for both Language and UnicodeString. The contents
950 of Language and UnicodeString are copied into these new
951 buffers. These buffers are automatically freed when
952 FreeUnicodeStringTable() is called.
953
954 @param Language A pointer to the ISO 639-2 or
955 RFC 3066 language code for the
956 Unicode string to add.
957
958 @param SupportedLanguages A pointer to the set of ISO
959 639-2 or RFC 3.66 language
960 codes that the Unicode string
961 table supports. Language must
962 be a member of this set.
963
964 @param UnicodeStringTable A pointer to the table of
965 Unicode strings.
966
967 @param UnicodeString A pointer to the Unicode
968 string to add.
969
970 @param Iso639Language Specify the language code
971 format supported. If true,
972 then the format follow ISO
973 639-2. If false, then it
974 follows RFC3066.
975
976 @retval EFI_SUCCESS The Unicode string that
977 matches the language specified
978 by Language was found in the
979 table of Unicode strings
980 UnicodeStringTable, and it was
981 returned in UnicodeString.
982
983 @retval EFI_INVALID_PARAMETER Language is NULL.
984
985 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
986
987 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
988
989 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
990
991 @retval EFI_ALREADY_STARTED A Unicode string with language
992 Language is already present in
993 UnicodeStringTable.
994
995 @retval EFI_OUT_OF_RESOURCES There is not enough memory to
996 add another Unicode string to
997 UnicodeStringTable.
998
999 @retval EFI_UNSUPPORTED The language specified by
1000 Language is not a member of
1001 SupportedLanguages.
1002
1003 **/
1004 EFI_STATUS
1005 EFIAPI
1006 AddUnicodeString2 (
1007 IN CONST CHAR8 *Language,
1008 IN CONST CHAR8 *SupportedLanguages,
1009 IN EFI_UNICODE_STRING_TABLE **UnicodeStringTable,
1010 IN CONST CHAR16 *UnicodeString,
1011 IN BOOLEAN Iso639Language
1012 )
1013 {
1014 UINTN NumberOfEntries;
1015 EFI_UNICODE_STRING_TABLE *OldUnicodeStringTable;
1016 EFI_UNICODE_STRING_TABLE *NewUnicodeStringTable;
1017 UINTN UnicodeStringLength;
1018 BOOLEAN Found;
1019 UINTN Index;
1020 CHAR8 *LanguageString;
1021
1022 //
1023 // Make sure the parameter are valid
1024 //
1025 if (Language == NULL || UnicodeString == NULL || UnicodeStringTable == NULL) {
1026 return EFI_INVALID_PARAMETER;
1027 }
1028
1029 //
1030 // If there are no supported languages, then a Unicode String can not be added
1031 //
1032 if (SupportedLanguages == NULL) {
1033 return EFI_UNSUPPORTED;
1034 }
1035
1036 //
1037 // If the Unicode String is empty, then a Unicode String can not be added
1038 //
1039 if (UnicodeString[0] == 0) {
1040 return EFI_INVALID_PARAMETER;
1041 }
1042
1043 //
1044 // Make sure Language is a member of SupportedLanguages
1045 //
1046 Found = FALSE;
1047 while (*SupportedLanguages != 0) {
1048 if (Iso639Language) {
1049 if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
1050 Found = TRUE;
1051 break;
1052 }
1053 SupportedLanguages += 3;
1054 } else {
1055 for (Index = 0; SupportedLanguages[Index] != 0 && SupportedLanguages[Index] != ';'; Index++);
1056 if (AsciiStrnCmp(SupportedLanguages, Language, Index) == 0) {
1057 Found = TRUE;
1058 break;
1059 }
1060 SupportedLanguages += Index;
1061 for (; *SupportedLanguages != 0 && *SupportedLanguages == ';'; SupportedLanguages++);
1062 }
1063 }
1064
1065 //
1066 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
1067 //
1068 if (!Found) {
1069 return EFI_UNSUPPORTED;
1070 }
1071
1072 //
1073 // Determine the size of the Unicode String Table by looking for a NULL Language entry
1074 //
1075 NumberOfEntries = 0;
1076 if (*UnicodeStringTable != NULL) {
1077 OldUnicodeStringTable = *UnicodeStringTable;
1078 while (OldUnicodeStringTable->Language != NULL) {
1079 LanguageString = OldUnicodeStringTable->Language;
1080
1081 while (*LanguageString) {
1082 for (Index = 0; LanguageString[Index] != 0 && LanguageString[Index] != ';'; Index++);
1083
1084 if (AsciiStrnCmp (Language, LanguageString, Index) == 0) {
1085 return EFI_ALREADY_STARTED;
1086 }
1087 LanguageString += Index;
1088 for (; *LanguageString != 0 && *LanguageString == ';'; LanguageString++);
1089 }
1090 OldUnicodeStringTable++;
1091 NumberOfEntries++;
1092 }
1093 }
1094
1095 //
1096 // Allocate space for a new Unicode String Table. It must hold the current number of
1097 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
1098 // marker
1099 //
1100 NewUnicodeStringTable = AllocatePool ((NumberOfEntries + 2) * sizeof (EFI_UNICODE_STRING_TABLE));
1101 if (NewUnicodeStringTable == NULL) {
1102 return EFI_OUT_OF_RESOURCES;
1103 }
1104
1105 //
1106 // If the current Unicode String Table contains any entries, then copy them to the
1107 // newly allocated Unicode String Table.
1108 //
1109 if (*UnicodeStringTable != NULL) {
1110 CopyMem (
1111 NewUnicodeStringTable,
1112 *UnicodeStringTable,
1113 NumberOfEntries * sizeof (EFI_UNICODE_STRING_TABLE)
1114 );
1115 }
1116
1117 //
1118 // Allocate space for a copy of the Language specifier
1119 //
1120 NewUnicodeStringTable[NumberOfEntries].Language = AllocateCopyPool (AsciiStrSize(Language), Language);
1121 if (NewUnicodeStringTable[NumberOfEntries].Language == NULL) {
1122 gBS->FreePool (NewUnicodeStringTable);
1123 return EFI_OUT_OF_RESOURCES;
1124 }
1125
1126 //
1127 // Compute the length of the Unicode String
1128 //
1129 for (UnicodeStringLength = 0; UnicodeString[UnicodeStringLength] != 0; UnicodeStringLength++);
1130
1131 //
1132 // Allocate space for a copy of the Unicode String
1133 //
1134 NewUnicodeStringTable[NumberOfEntries].UnicodeString = AllocateCopyPool (StrSize (UnicodeString), UnicodeString);
1135 if (NewUnicodeStringTable[NumberOfEntries].UnicodeString == NULL) {
1136 gBS->FreePool (NewUnicodeStringTable[NumberOfEntries].Language);
1137 gBS->FreePool (NewUnicodeStringTable);
1138 return EFI_OUT_OF_RESOURCES;
1139 }
1140
1141 //
1142 // Mark the end of the Unicode String Table
1143 //
1144 NewUnicodeStringTable[NumberOfEntries + 1].Language = NULL;
1145 NewUnicodeStringTable[NumberOfEntries + 1].UnicodeString = NULL;
1146
1147 //
1148 // Free the old Unicode String Table
1149 //
1150 if (*UnicodeStringTable != NULL) {
1151 gBS->FreePool (*UnicodeStringTable);
1152 }
1153
1154 //
1155 // Point UnicodeStringTable at the newly allocated Unicode String Table
1156 //
1157 *UnicodeStringTable = NewUnicodeStringTable;
1158
1159 return EFI_SUCCESS;
1160 }
1161
1162 /**
1163 This function frees the table of Unicode strings in UnicodeStringTable.
1164 If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
1165 Otherwise, each language code, and each Unicode string in the Unicode string
1166 table are freed, and EFI_SUCCESS is returned.
1167
1168 @param UnicodeStringTable A pointer to the table of Unicode strings.
1169
1170 @retval EFI_SUCCESS The Unicode string table was freed.
1171
1172 **/
1173 EFI_STATUS
1174 EFIAPI
1175 FreeUnicodeStringTable (
1176 IN EFI_UNICODE_STRING_TABLE *UnicodeStringTable
1177 )
1178 {
1179 UINTN Index;
1180
1181 //
1182 // If the Unicode String Table is NULL, then it is already freed
1183 //
1184 if (UnicodeStringTable == NULL) {
1185 return EFI_SUCCESS;
1186 }
1187
1188 //
1189 // Loop through the Unicode String Table until we reach the end of table marker
1190 //
1191 for (Index = 0; UnicodeStringTable[Index].Language != NULL; Index++) {
1192
1193 //
1194 // Free the Language string from the Unicode String Table
1195 //
1196 gBS->FreePool (UnicodeStringTable[Index].Language);
1197
1198 //
1199 // Free the Unicode String from the Unicode String Table
1200 //
1201 if (UnicodeStringTable[Index].UnicodeString != NULL) {
1202 gBS->FreePool (UnicodeStringTable[Index].UnicodeString);
1203 }
1204 }
1205
1206 //
1207 // Free the Unicode String Table itself
1208 //
1209 gBS->FreePool (UnicodeStringTable);
1210
1211 return EFI_SUCCESS;
1212 }
1213