IntelFrameworkPkg/Library/FrameworkUefiLib/UefiLib.c

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