MdePkg/Library/UefiLib/UefiLib.c

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