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   IN     CONST CHAR8               *Language,
 869   IN     CONST CHAR8               *SupportedLanguages,
 870   IN OUT EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 871   IN     CONST CHAR16              *UnicodeString
 872   )
 873 {
 874   UINTN                     NumberOfEntries;
 875   EFI_UNICODE_STRING_TABLE  *OldUnicodeStringTable;
 876   EFI_UNICODE_STRING_TABLE  *NewUnicodeStringTable;
 877   UINTN                     UnicodeStringLength;
 878
 879   //
 880   // Make sure the parameter are valid
 881   //
 882   if (Language == NULL || UnicodeString == NULL || UnicodeStringTable == NULL) {
 883     return EFI_INVALID_PARAMETER;
 884   }
 885
 886   //
 887   // If there are no supported languages, then a Unicode String can not be added
 888   //
 889   if (SupportedLanguages == NULL) {
 890     return EFI_UNSUPPORTED;
 891   }
 892
 893   //
 894   // If the Unicode String is empty, then a Unicode String can not be added
 895   //
 896   if (UnicodeString[0] == 0) {
 897     return EFI_INVALID_PARAMETER;
 898   }
 899
 900   //
 901   // Make sure Language is a member of SupportedLanguages
 902   //
 903   while (*SupportedLanguages != 0) {
 904     if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
 905
 906       //
 907       // Determine the size of the Unicode String Table by looking for a NULL Language entry
 908       //
 909       NumberOfEntries = 0;
 910       if (*UnicodeStringTable != NULL) {
 911         OldUnicodeStringTable = *UnicodeStringTable;
 912         while (OldUnicodeStringTable->Language != NULL) {
 913           if (CompareIso639LanguageCode (Language, OldUnicodeStringTable->Language)) {
 914             return EFI_ALREADY_STARTED;
 915           }
 916
 917           OldUnicodeStringTable++;
 918           NumberOfEntries++;
 919         }
 920       }
 921
 922       //
 923       // Allocate space for a new Unicode String Table.  It must hold the current number of
 924       // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
 925       // marker
 926       //
 927       NewUnicodeStringTable = AllocatePool ((NumberOfEntries + 2) * sizeof (EFI_UNICODE_STRING_TABLE));
 928       if (NewUnicodeStringTable == NULL) {
 929         return EFI_OUT_OF_RESOURCES;
 930       }
 931
 932       //
 933       // If the current Unicode String Table contains any entries, then copy them to the
 934       // newly allocated Unicode String Table.
 935       //
 936       if (*UnicodeStringTable != NULL) {
 937         CopyMem (
 938            NewUnicodeStringTable,
 939            *UnicodeStringTable,
 940            NumberOfEntries * sizeof (EFI_UNICODE_STRING_TABLE)
 941            );
 942       }
 943
 944       //
 945       // Allocate space for a copy of the Language specifier
 946       //
 947       NewUnicodeStringTable[NumberOfEntries].Language = AllocateCopyPool (3, Language);
 948       if (NewUnicodeStringTable[NumberOfEntries].Language == NULL) {
 949         gBS->FreePool (NewUnicodeStringTable);
 950         return EFI_OUT_OF_RESOURCES;
 951       }
 952
 953       //
 954       // Compute the length of the Unicode String
 955       //
 956       for (UnicodeStringLength = 0; UnicodeString[UnicodeStringLength] != 0; UnicodeStringLength++)
 957         ;
 958
 959       //
 960       // Allocate space for a copy of the Unicode String
 961       //
 962       NewUnicodeStringTable[NumberOfEntries].UnicodeString = AllocateCopyPool (
 963                                                               (UnicodeStringLength + 1) * sizeof (CHAR16),
 964                                                               UnicodeString
 965                                                               );
 966       if (NewUnicodeStringTable[NumberOfEntries].UnicodeString == NULL) {
 967         gBS->FreePool (NewUnicodeStringTable[NumberOfEntries].Language);
 968         gBS->FreePool (NewUnicodeStringTable);
 969         return EFI_OUT_OF_RESOURCES;
 970       }
 971
 972       //
 973       // Mark the end of the Unicode String Table
 974       //
 975       NewUnicodeStringTable[NumberOfEntries + 1].Language       = NULL;
 976       NewUnicodeStringTable[NumberOfEntries + 1].UnicodeString  = NULL;
 977
 978       //
 979       // Free the old Unicode String Table
 980       //
 981       if (*UnicodeStringTable != NULL) {
 982         gBS->FreePool (*UnicodeStringTable);
 983       }
 984
 985       //
 986       // Point UnicodeStringTable at the newly allocated Unicode String Table
 987       //
 988       *UnicodeStringTable = NewUnicodeStringTable;
 989
 990       return EFI_SUCCESS;
 991     }
 992
 993     SupportedLanguages += 3;
 994   }
 995
 996   return EFI_UNSUPPORTED;
 997 }
 998
 999
1000 /**
1001   This function adds the Null-terminated Unicode string specified by UnicodeString
1002   to UnicodeStringTable.
1003
1004   If Language is a member of SupportedLanguages then UnicodeString is added to
1005   UnicodeStringTable.  New buffers are allocated for both Language and UnicodeString.
1006   The contents of Language and UnicodeString are copied into these new buffers.
1007   These buffers are automatically freed when EfiLibFreeUnicodeStringTable() is called.
1008
1009   @param  Language            A pointer to an ASCII string containing the ISO 639-2 or
1010                               the RFC 4646 language code for the Unicode string to add.
1011                               If Iso639Language is TRUE, then this ASCII string is not
1012                               assumed to be Null-terminated, and only the first three
1013                               chacters are used. If Iso639Language is FALSE, then this
1014                               ASCII string must be Null-terminated.
1015   @param  SupportedLanguages  A pointer to a Null-terminated ASCII string that contains
1016                               a set of ISO 639-2 or RFC 4646 language codes that the Unicode
1017                               string table supports.  Language must be a member of this set.
1018                               If Iso639Language is TRUE, then this string contains one or more
1019                               ISO 639-2 language codes with no separator characters.
1020                               If Iso639Language is FALSE, then is string contains one or more
1021                               RFC 4646 language codes separated by ';'.
1022   @param  UnicodeStringTable  A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
1023                               is defined in "Related Definitions".
1024   @param  UnicodeString       A pointer to the Unicode string to add.
1025   @param  Iso639Language      Specifies the supported language code format. If it is TRUE,
1026                               then Language and SupportedLanguages follow ISO 639-2 language code format.
1027                               Otherwise, they follow RFC 4646 language code format.
1028
1029   @retval EFI_SUCCESS            The Unicode string that matches the language specified by
1030                                  Language was found in the table of Unicode strings UnicodeStringTable,
1031                                  and it was returned in UnicodeString.
1032   @retval EFI_INVALID_PARAMETER  Language is NULL.
1033   @retval EFI_INVALID_PARAMETER  UnicodeString is NULL.
1034   @retval EFI_INVALID_PARAMETER  UnicodeString is an empty string.
1035   @retval EFI_UNSUPPORTED        SupportedLanguages is NULL.
1036   @retval EFI_ALREADY_STARTED    A Unicode string with language Language is already present in
1037                                  UnicodeStringTable.
1038   @retval EFI_OUT_OF_RESOURCES   There is not enough memory to add another Unicode string UnicodeStringTable.
1039   @retval EFI_UNSUPPORTED        The language specified by Language is not a member of SupportedLanguages.
1040
1041 **/
1042 EFI_STATUS
1043 EFIAPI
1044 AddUnicodeString2 (
1045   IN     CONST CHAR8               *Language,
1046   IN     CONST CHAR8               *SupportedLanguages,
1047   IN OUT EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
1048   IN     CONST CHAR16              *UnicodeString,
1049   IN     BOOLEAN                   Iso639Language
1050   )
1051 {
1052   UINTN                     NumberOfEntries;
1053   EFI_UNICODE_STRING_TABLE  *OldUnicodeStringTable;
1054   EFI_UNICODE_STRING_TABLE  *NewUnicodeStringTable;
1055   UINTN                     UnicodeStringLength;
1056   BOOLEAN                   Found;
1057   UINTN                     Index;
1058   CHAR8                     *LanguageString;
1059
1060   //
1061   // Make sure the parameter are valid
1062   //
1063   if (Language == NULL || UnicodeString == NULL || UnicodeStringTable == NULL) {
1064     return EFI_INVALID_PARAMETER;
1065   }
1066
1067   //
1068   // If there are no supported languages, then a Unicode String can not be added
1069   //
1070   if (SupportedLanguages == NULL) {
1071     return EFI_UNSUPPORTED;
1072   }
1073
1074   //
1075   // If the Unicode String is empty, then a Unicode String can not be added
1076   //
1077   if (UnicodeString[0] == 0) {
1078     return EFI_INVALID_PARAMETER;
1079   }
1080
1081   //
1082   // Make sure Language is a member of SupportedLanguages
1083   //
1084   Found = FALSE;
1085   while (*SupportedLanguages != 0) {
1086     if (Iso639Language) {
1087       if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
1088         Found = TRUE;
1089         break;
1090       }
1091       SupportedLanguages += 3;
1092     } else {
1093       for (Index = 0; SupportedLanguages[Index] != 0 && SupportedLanguages[Index] != ';'; Index++);
1094       if (AsciiStrnCmp(SupportedLanguages, Language, Index) == 0) {
1095         Found = TRUE;
1096         break;
1097       }
1098       SupportedLanguages += Index;
1099       for (; *SupportedLanguages != 0 && *SupportedLanguages == ';'; SupportedLanguages++);
1100     }
1101   }
1102
1103   //
1104   // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
1105   //
1106   if (!Found) {
1107     return EFI_UNSUPPORTED;
1108   }
1109
1110   //
1111   // Determine the size of the Unicode String Table by looking for a NULL Language entry
1112   //
1113   NumberOfEntries = 0;
1114   if (*UnicodeStringTable != NULL) {
1115     OldUnicodeStringTable = *UnicodeStringTable;
1116     while (OldUnicodeStringTable->Language != NULL) {
1117       LanguageString = OldUnicodeStringTable->Language;
1118
1119       while (*LanguageString != 0) {
1120         for (Index = 0; LanguageString[Index] != 0 && LanguageString[Index] != ';'; Index++);
1121
1122         if (AsciiStrnCmp (Language, LanguageString, Index) == 0) {
1123           return EFI_ALREADY_STARTED;
1124         }
1125         LanguageString += Index;
1126         for (; *LanguageString != 0 && *LanguageString == ';'; LanguageString++);
1127       }
1128       OldUnicodeStringTable++;
1129       NumberOfEntries++;
1130     }
1131   }
1132
1133   //
1134   // Allocate space for a new Unicode String Table.  It must hold the current number of
1135   // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
1136   // marker
1137   //
1138   NewUnicodeStringTable = AllocatePool ((NumberOfEntries + 2) * sizeof (EFI_UNICODE_STRING_TABLE));
1139   if (NewUnicodeStringTable == NULL) {
1140     return EFI_OUT_OF_RESOURCES;
1141   }
1142
1143   //
1144   // If the current Unicode String Table contains any entries, then copy them to the
1145   // newly allocated Unicode String Table.
1146   //
1147   if (*UnicodeStringTable != NULL) {
1148     CopyMem (
1149       NewUnicodeStringTable,
1150       *UnicodeStringTable,
1151       NumberOfEntries * sizeof (EFI_UNICODE_STRING_TABLE)
1152       );
1153   }
1154
1155   //
1156   // Allocate space for a copy of the Language specifier
1157   //
1158   NewUnicodeStringTable[NumberOfEntries].Language = AllocateCopyPool (AsciiStrSize(Language), Language);
1159   if (NewUnicodeStringTable[NumberOfEntries].Language == NULL) {
1160     gBS->FreePool (NewUnicodeStringTable);
1161     return EFI_OUT_OF_RESOURCES;
1162   }
1163
1164   //
1165   // Compute the length of the Unicode String
1166   //
1167   for (UnicodeStringLength = 0; UnicodeString[UnicodeStringLength] != 0; UnicodeStringLength++);
1168
1169   //
1170   // Allocate space for a copy of the Unicode String
1171   //
1172   NewUnicodeStringTable[NumberOfEntries].UnicodeString = AllocateCopyPool (StrSize (UnicodeString), UnicodeString);
1173   if (NewUnicodeStringTable[NumberOfEntries].UnicodeString == NULL) {
1174     gBS->FreePool (NewUnicodeStringTable[NumberOfEntries].Language);
1175     gBS->FreePool (NewUnicodeStringTable);
1176     return EFI_OUT_OF_RESOURCES;
1177   }
1178
1179   //
1180   // Mark the end of the Unicode String Table
1181   //
1182   NewUnicodeStringTable[NumberOfEntries + 1].Language       = NULL;
1183   NewUnicodeStringTable[NumberOfEntries + 1].UnicodeString  = NULL;
1184
1185   //
1186   // Free the old Unicode String Table
1187   //
1188   if (*UnicodeStringTable != NULL) {
1189     gBS->FreePool (*UnicodeStringTable);
1190   }
1191
1192   //
1193   // Point UnicodeStringTable at the newly allocated Unicode String Table
1194   //
1195   *UnicodeStringTable = NewUnicodeStringTable;
1196
1197   return EFI_SUCCESS;
1198 }
1199
1200 /**
1201   This function frees the table of Unicode strings in UnicodeStringTable.
1202
1203   If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
1204   Otherwise, each language code, and each Unicode string in the Unicode string
1205   table are freed, and EFI_SUCCESS is returned.
1206
1207   @param  UnicodeStringTable  A pointer to the table of Unicode strings.
1208
1209   @retval EFI_SUCCESS         The Unicode string table was freed.
1210
1211 **/
1212 EFI_STATUS
1213 EFIAPI
1214 FreeUnicodeStringTable (
1215   IN EFI_UNICODE_STRING_TABLE  *UnicodeStringTable
1216   )
1217 {
1218   UINTN Index;
1219
1220   //
1221   // If the Unicode String Table is NULL, then it is already freed
1222   //
1223   if (UnicodeStringTable == NULL) {
1224     return EFI_SUCCESS;
1225   }
1226
1227   //
1228   // Loop through the Unicode String Table until we reach the end of table marker
1229   //
1230   for (Index = 0; UnicodeStringTable[Index].Language != NULL; Index++) {
1231
1232     //
1233     // Free the Language string from the Unicode String Table
1234     //
1235     gBS->FreePool (UnicodeStringTable[Index].Language);
1236
1237     //
1238     // Free the Unicode String from the Unicode String Table
1239     //
1240     if (UnicodeStringTable[Index].UnicodeString != NULL) {
1241       gBS->FreePool (UnicodeStringTable[Index].UnicodeString);
1242     }
1243   }
1244
1245   //
1246   // Free the Unicode String Table itself
1247   //
1248   gBS->FreePool (UnicodeStringTable);
1249
1250   return EFI_SUCCESS;
1251 }
1252
1253 /**
1254   Returns a pointer to an allocated buffer that contains the contents of a
1255   variable retrieved through the UEFI Runtime Service GetVariable().  The
1256   returned buffer is allocated using AllocatePool().  The caller is responsible
1257   for freeing this buffer with FreePool().
1258
1259   If Name is NULL, then ASSERT().
1260   If Guid is NULL, then ASSERT().
1261
1262   @param[in]  Name  Pointer to a Null-terminated Unicode string.
1263   @param[in]  Guid  Pointer to an EFI_GUID structure
1264
1265   @retval NULL   The variable could not be retrieved.
1266   @retval NULL   There are not enough resources available for the variable contents.
1267   @retval Other  A pointer to allocated buffer containing the variable contents.
1268
1269 **/
1270 VOID *
1271 EFIAPI
1272 GetVariable (
1273   IN CONST CHAR16    *Name,
1274   IN CONST EFI_GUID  *Guid
1275   )
1276 {
1277   EFI_STATUS  Status;
1278   UINTN       Size;
1279   VOID        *Value;
1280
1281   ASSERT (Name != NULL);
1282   ASSERT (Guid != NULL);
1283
1284   //
1285   // Try to get the variable size.
1286   //
1287   Value = NULL;
1288   Size = 0;
1289   Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &Size, Value);
1290   if (Status != EFI_BUFFER_TOO_SMALL) {
1291     return NULL;
1292   }
1293
1294   //
1295   // Allocate buffer to get the variable.
1296   //
1297   Value = AllocatePool (Size);
1298   if (Value == NULL) {
1299     return NULL;
1300   }
1301
1302   //
1303   // Get the variable data.
1304   //
1305   Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &Size, Value);
1306   if (EFI_ERROR (Status)) {
1307     FreePool(Value);
1308     return NULL;
1309   }
1310
1311   return Value;
1312 }
1313
1314
1315 /**
1316   Returns a pointer to an allocated buffer that contains the contents of a
1317   variable retrieved through the UEFI Runtime Service GetVariable().  This
1318   function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1319   The returned buffer is allocated using AllocatePool().  The caller is
1320   responsible for freeing this buffer with FreePool().
1321
1322   If Name is NULL, then ASSERT().
1323
1324   @param[in]  Name  Pointer to a Null-terminated Unicode string.
1325
1326   @retval NULL   The variable could not be retrieved.
1327   @retval NULL   There are not enough resources available for the variable contents.
1328   @retval Other  A pointer to allocated buffer containing the variable contents.
1329
1330 **/
1331 VOID *
1332 EFIAPI
1333 GetEfiGlobalVariable (
1334   IN CONST CHAR16  *Name
1335   )
1336 {
1337   return GetVariable (Name, &gEfiGlobalVariableGuid);
1338 }
1339
1340 /**
1341   Returns the status whether get the variable success. The function retrieves
1342   variable  through the UEFI Runtime Service GetVariable().  The
1343   returned buffer is allocated using AllocatePool().  The caller is responsible
1344   for freeing this buffer with FreePool().
1345
1346   If Name  is NULL, then ASSERT().
1347   If Guid  is NULL, then ASSERT().
1348   If Value is NULL, then ASSERT().
1349
1350   @param[in]  Name  The pointer to a Null-terminated Unicode string.
1351   @param[in]  Guid  The pointer to an EFI_GUID structure
1352   @param[out] Value The buffer point saved the variable info.
1353   @param[out] Size  The buffer size of the variable.
1354
1355   @return EFI_OUT_OF_RESOURCES      Allocate buffer failed.
1356   @return EFI_SUCCESS               Find the specified variable.
1357   @return Others Errors             Return errors from call to gRT->GetVariable.
1358
1359 **/
1360 EFI_STATUS
1361 EFIAPI
1362 GetVariable2 (
1363   IN CONST CHAR16    *Name,
1364   IN CONST EFI_GUID  *Guid,
1365   OUT VOID           **Value,
1366   OUT UINTN          *Size OPTIONAL
1367   )
1368 {
1369   EFI_STATUS  Status;
1370   UINTN       BufferSize;
1371
1372   ASSERT (Name != NULL && Guid != NULL && Value != NULL);
1373
1374   //
1375   // Try to get the variable size.
1376   //
1377   BufferSize = 0;
1378   *Value     = NULL;
1379   if (Size != NULL) {
1380     *Size  = 0;
1381   }
1382
1383   Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &BufferSize, *Value);
1384   if (Status != EFI_BUFFER_TOO_SMALL) {
1385     return Status;
1386   }
1387
1388   //
1389   // Allocate buffer to get the variable.
1390   //
1391   *Value = AllocatePool (BufferSize);
1392   ASSERT (*Value != NULL);
1393   if (*Value == NULL) {
1394     return EFI_OUT_OF_RESOURCES;
1395   }
1396
1397   //
1398   // Get the variable data.
1399   //
1400   Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &BufferSize, *Value);
1401   if (EFI_ERROR (Status)) {
1402     FreePool(*Value);
1403     *Value = NULL;
1404   }
1405
1406   if (Size != NULL) {
1407     *Size = BufferSize;
1408   }
1409
1410   return Status;
1411 }
1412
1413 /**
1414   Returns a pointer to an allocated buffer that contains the contents of a
1415   variable retrieved through the UEFI Runtime Service GetVariable().  This
1416   function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1417   The returned buffer is allocated using AllocatePool().  The caller is
1418   responsible for freeing this buffer with FreePool().
1419
1420   If Name is NULL, then ASSERT().
1421   If Value is NULL, then ASSERT().
1422
1423   @param[in]  Name  The pointer to a Null-terminated Unicode string.
1424   @param[out] Value The buffer point saved the variable info.
1425   @param[out] Size  The buffer size of the variable.
1426
1427   @return EFI_OUT_OF_RESOURCES      Allocate buffer failed.
1428   @return EFI_SUCCESS               Find the specified variable.
1429   @return Others Errors             Return errors from call to gRT->GetVariable.
1430
1431 **/
1432 EFI_STATUS
1433 EFIAPI
1434 GetEfiGlobalVariable2 (
1435   IN CONST CHAR16    *Name,
1436   OUT VOID           **Value,
1437   OUT UINTN          *Size OPTIONAL
1438   )
1439 {
1440   return GetVariable2 (Name, &gEfiGlobalVariableGuid, Value, Size);
1441 }
1442
1443 /**
1444   Returns a pointer to an allocated buffer that contains the best matching language
1445   from a set of supported languages.
1446
1447   This function supports both ISO 639-2 and RFC 4646 language codes, but language
1448   code types may not be mixed in a single call to this function.  The language
1449   code returned is allocated using AllocatePool().  The caller is responsible for
1450   freeing the allocated buffer using FreePool().  This function supports a variable
1451   argument list that allows the caller to pass in a prioritized list of language
1452   codes to test against all the language codes in SupportedLanguages.
1453
1454   If SupportedLanguages is NULL, then ASSERT().
1455
1456   @param[in]  SupportedLanguages  A pointer to a Null-terminated ASCII string that
1457                                   contains a set of language codes in the format
1458                                   specified by Iso639Language.
1459   @param[in]  Iso639Language      If TRUE, then all language codes are assumed to be
1460                                   in ISO 639-2 format.  If FALSE, then all language
1461                                   codes are assumed to be in RFC 4646 language format
1462   @param[in]  ...                 A variable argument list that contains pointers to
1463                                   Null-terminated ASCII strings that contain one or more
1464                                   language codes in the format specified by Iso639Language.
1465                                   The first language code from each of these language
1466                                   code lists is used to determine if it is an exact or
1467                                   close match to any of the language codes in
1468                                   SupportedLanguages.  Close matches only apply to RFC 4646
1469                                   language codes, and the matching algorithm from RFC 4647
1470                                   is used to determine if a close match is present.  If
1471                                   an exact or close match is found, then the matching
1472                                   language code from SupportedLanguages is returned.  If
1473                                   no matches are found, then the next variable argument
1474                                   parameter is evaluated.  The variable argument list
1475                                   is terminated by a NULL.
1476
1477   @retval NULL   The best matching language could not be found in SupportedLanguages.
1478   @retval NULL   There are not enough resources available to return the best matching
1479                  language.
1480   @retval Other  A pointer to a Null-terminated ASCII string that is the best matching
1481                  language in SupportedLanguages.
1482
1483 **/
1484 CHAR8 *
1485 EFIAPI
1486 GetBestLanguage (
1487   IN CONST CHAR8  *SupportedLanguages,
1488   IN BOOLEAN      Iso639Language,
1489   ...
1490   )
1491 {
1492   VA_LIST      Args;
1493   CHAR8        *Language;
1494   UINTN        CompareLength;
1495   UINTN        LanguageLength;
1496   CONST CHAR8  *Supported;
1497   CHAR8        *BestLanguage;
1498
1499   ASSERT (SupportedLanguages != NULL);
1500
1501   VA_START (Args, Iso639Language);
1502   while ((Language = VA_ARG (Args, CHAR8 *)) != NULL) {
1503     //
1504     // Default to ISO 639-2 mode
1505     //
1506     CompareLength  = 3;
1507     LanguageLength = MIN (3, AsciiStrLen (Language));
1508
1509     //
1510     // If in RFC 4646 mode, then determine the length of the first RFC 4646 language code in Language
1511     //
1512     if (!Iso639Language) {
1513       for (LanguageLength = 0; Language[LanguageLength] != 0 && Language[LanguageLength] != ';'; LanguageLength++);
1514     }
1515
1516     //
1517     // Trim back the length of Language used until it is empty
1518     //
1519     while (LanguageLength > 0) {
1520       //
1521       // Loop through all language codes in SupportedLanguages
1522       //
1523       for (Supported = SupportedLanguages; *Supported != '\0'; Supported += CompareLength) {
1524         //
1525         // In RFC 4646 mode, then Loop through all language codes in SupportedLanguages
1526         //
1527         if (!Iso639Language) {
1528           //
1529           // Skip ';' characters in Supported
1530           //
1531           for (; *Supported != '\0' && *Supported == ';'; Supported++);
1532           //
1533           // Determine the length of the next language code in Supported
1534           //
1535           for (CompareLength = 0; Supported[CompareLength] != 0 && Supported[CompareLength] != ';'; CompareLength++);
1536           //
1537           // If Language is longer than the Supported, then skip to the next language
1538           //
1539           if (LanguageLength > CompareLength) {
1540             continue;
1541           }
1542         }
1543         //
1544         // See if the first LanguageLength characters in Supported match Language
1545         //
1546         if (AsciiStrnCmp (Supported, Language, LanguageLength) == 0) {
1547           VA_END (Args);
1548           //
1549           // Allocate, copy, and return the best matching language code from SupportedLanguages
1550           //
1551           BestLanguage = AllocateZeroPool (CompareLength + 1);
1552           if (BestLanguage == NULL) {
1553             return NULL;
1554           }
1555           return CopyMem (BestLanguage, Supported, CompareLength);
1556         }
1557       }
1558
1559       if (Iso639Language) {
1560         //
1561         // If ISO 639 mode, then each language can only be tested once
1562         //
1563         LanguageLength = 0;
1564       } else {
1565         //
1566         // If RFC 4646 mode, then trim Language from the right to the next '-' character
1567         //
1568         for (LanguageLength--; LanguageLength > 0 && Language[LanguageLength] != '-'; LanguageLength--);
1569       }
1570     }
1571   }
1572   VA_END (Args);
1573
1574   //
1575   // No matches were found
1576   //
1577   return NULL;
1578 }
1579
1580 /**
1581   Returns an array of protocol instance that matches the given protocol.
1582
1583   @param[in]  Protocol      Provides the protocol to search for.
1584   @param[out] NoProtocols   The number of protocols returned in Buffer.
1585   @param[out] Buffer        A pointer to the buffer to return the requested
1586                             array of protocol instances that match Protocol.
1587                             The returned buffer is allocated using
1588                             EFI_BOOT_SERVICES.AllocatePool().  The caller is
1589                             responsible for freeing this buffer with
1590                             EFI_BOOT_SERVICES.FreePool().
1591
1592   @retval EFI_SUCCESS            The array of protocols was returned in Buffer,
1593                                  and the number of protocols in Buffer was
1594                                  returned in NoProtocols.
1595   @retval EFI_NOT_FOUND          No protocols found.
1596   @retval EFI_OUT_OF_RESOURCES   There is not enough pool memory to store the
1597                                  matching results.
1598   @retval EFI_INVALID_PARAMETER  Protocol is NULL.
1599   @retval EFI_INVALID_PARAMETER  NoProtocols is NULL.
1600   @retval EFI_INVALID_PARAMETER  Buffer is NULL.
1601
1602 **/
1603 EFI_STATUS
1604 EFIAPI
1605 EfiLocateProtocolBuffer (
1606   IN  EFI_GUID  *Protocol,
1607   OUT UINTN     *NoProtocols,
1608   OUT VOID      ***Buffer
1609   )
1610 {
1611   EFI_STATUS  Status;
1612   UINTN       NoHandles;
1613   EFI_HANDLE  *HandleBuffer;
1614   UINTN       Index;
1615
1616   //
1617   // Check input parameters
1618   //
1619   if (Protocol == NULL || NoProtocols == NULL || Buffer == NULL) {
1620     return EFI_INVALID_PARAMETER;
1621   }
1622
1623   //
1624   // Initialze output parameters
1625   //
1626   *NoProtocols = 0;
1627   *Buffer = NULL;
1628
1629   //
1630   // Retrieve the array of handles that support Protocol
1631   //
1632   Status = gBS->LocateHandleBuffer (
1633                   ByProtocol,
1634                   Protocol,
1635                   NULL,
1636                   &NoHandles,
1637                   &HandleBuffer
1638                   );
1639   if (EFI_ERROR (Status)) {
1640     return Status;
1641   }
1642
1643   //
1644   // Allocate array of protocol instances
1645   //
1646   Status = gBS->AllocatePool (
1647                   EfiBootServicesData,
1648                   NoHandles * sizeof (VOID *),
1649                   (VOID **)Buffer
1650                   );
1651   if (EFI_ERROR (Status)) {
1652     return EFI_OUT_OF_RESOURCES;
1653   }
1654   ZeroMem (*Buffer, NoHandles * sizeof (VOID *));
1655
1656   //
1657   // Lookup Protocol on each handle in HandleBuffer to fill in the array of
1658   // protocol instances.  Handle case where protocol instance was present when
1659   // LocateHandleBuffer() was called, but is not present when HandleProtocol()
1660   // is called.
1661   //
1662   for (Index = 0, *NoProtocols = 0; Index < NoHandles; Index++) {
1663     Status = gBS->HandleProtocol (
1664                     HandleBuffer[Index],
1665                     Protocol,
1666                     &((*Buffer)[*NoProtocols])
1667                     );
1668     if (!EFI_ERROR (Status)) {
1669       (*NoProtocols)++;
1670     }
1671   }
1672
1673   //
1674   // Free the handle buffer
1675   //
1676   gBS->FreePool (HandleBuffer);
1677
1678   //
1679   // Make sure at least one protocol instance was found
1680   //
1681   if (*NoProtocols == 0) {
1682     gBS->FreePool (*Buffer);
1683     *Buffer = NULL;
1684     return EFI_NOT_FOUND;
1685   }
1686
1687   return EFI_SUCCESS;
1688 }