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