MdePkg/Library/UefiLib/UefiLib.c

   1 /** @file
   2   The UEFI Library provides functions and macros that simplify the development of
   3   UEFI Drivers and UEFI Applications.  These functions and macros help manage EFI
   4   events, build simple locks utilizing EFI Task Priority Levels (TPLs), install
   5   EFI Driver Model related protocols, manage Unicode string tables for UEFI Drivers,
   6   and print messages on the console output and standard error devices.
   7
   8   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   9   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   Signals an event group by placing a new event in the group temporarily and
 309   signaling it.
 310
 311   @param[in] EventGroup          Supplies the unique identifier of the event
 312                                  group to signal.
 313
 314   @retval EFI_SUCCESS            The event group was signaled successfully.
 315   @retval EFI_INVALID_PARAMETER  EventGroup is NULL.
 316   @return                        Error codes that report problems about event
 317                                  creation or signaling.
 318 **/
 319 EFI_STATUS
 320 EFIAPI
 321 EfiEventGroupSignal (
 322   IN CONST EFI_GUID *EventGroup
 323   )
 324 {
 325   EFI_STATUS Status;
 326   EFI_EVENT  Event;
 327
 328   if (EventGroup == NULL) {
 329     return EFI_INVALID_PARAMETER;
 330   }
 331
 332   Status = gBS->CreateEventEx (
 333                   EVT_NOTIFY_SIGNAL,
 334                   TPL_CALLBACK,
 335                   EfiEventEmptyFunction,
 336                   NULL,
 337                   EventGroup,
 338                   &Event
 339                   );
 340   if (EFI_ERROR (Status)) {
 341     return Status;
 342   }
 343
 344   Status = gBS->SignalEvent (Event);
 345   gBS->CloseEvent (Event);
 346
 347   return Status;
 348 }
 349
 350 /**
 351   An empty function that can be used as NotifyFunction parameter of
 352   CreateEvent() or CreateEventEx().
 353
 354   @param Event              Event whose notification function is being invoked.
 355   @param Context            The pointer to the notification function's context,
 356                             which is implementation-dependent.
 357
 358 **/
 359 VOID
 360 EFIAPI
 361 EfiEventEmptyFunction (
 362   IN EFI_EVENT              Event,
 363   IN VOID                   *Context
 364   )
 365 {
 366 }
 367
 368 /**
 369   Returns the current TPL.
 370
 371   This function returns the current TPL.  There is no EFI service to directly
 372   retrieve the current TPL. Instead, the RaiseTPL() function is used to raise
 373   the TPL to TPL_HIGH_LEVEL.  This will return the current TPL.  The TPL level
 374   can then immediately be restored back to the current TPL level with a call
 375   to RestoreTPL().
 376
 377   @return The current TPL.
 378
 379 **/
 380 EFI_TPL
 381 EFIAPI
 382 EfiGetCurrentTpl (
 383   VOID
 384   )
 385 {
 386   EFI_TPL Tpl;
 387
 388   Tpl = gBS->RaiseTPL (TPL_HIGH_LEVEL);
 389   gBS->RestoreTPL (Tpl);
 390
 391   return Tpl;
 392 }
 393
 394
 395 /**
 396   Initializes a basic mutual exclusion lock.
 397
 398   This function initializes a basic mutual exclusion lock to the released state
 399   and returns the lock.  Each lock provides mutual exclusion access at its task
 400   priority level.  Since there is no preemption or multiprocessor support in EFI,
 401   acquiring the lock only consists of raising to the locks TPL.
 402   If Lock is NULL, then ASSERT().
 403   If Priority is not a valid TPL value, then ASSERT().
 404
 405   @param  Lock       A pointer to the lock data structure to initialize.
 406   @param  Priority   EFI TPL is associated with the lock.
 407
 408   @return The lock.
 409
 410 **/
 411 EFI_LOCK *
 412 EFIAPI
 413 EfiInitializeLock (
 414   IN OUT EFI_LOCK  *Lock,
 415   IN EFI_TPL        Priority
 416   )
 417 {
 418   ASSERT (Lock != NULL);
 419   ASSERT (Priority <= TPL_HIGH_LEVEL);
 420
 421   Lock->Tpl       = Priority;
 422   Lock->OwnerTpl  = TPL_APPLICATION;
 423   Lock->Lock      = EfiLockReleased ;
 424   return Lock;
 425 }
 426
 427 /**
 428   Acquires ownership of a lock.
 429
 430   This function raises the system's current task priority level to the task
 431   priority level of the mutual exclusion lock.  Then, it places the lock in the
 432   acquired state.
 433   If Lock is NULL, then ASSERT().
 434   If Lock is not initialized, then ASSERT().
 435   If Lock is already in the acquired state, then ASSERT().
 436
 437   @param  Lock              A pointer to the lock to acquire.
 438
 439 **/
 440 VOID
 441 EFIAPI
 442 EfiAcquireLock (
 443   IN EFI_LOCK  *Lock
 444   )
 445 {
 446   ASSERT (Lock != NULL);
 447   ASSERT (Lock->Lock == EfiLockReleased);
 448
 449   Lock->OwnerTpl = gBS->RaiseTPL (Lock->Tpl);
 450   Lock->Lock     = EfiLockAcquired;
 451 }
 452
 453 /**
 454   Acquires ownership of a lock.
 455
 456   This function raises the system's current task priority level to the task priority
 457   level of the mutual exclusion lock.  Then, it attempts to place the lock in the acquired state.
 458   If the lock is already in the acquired state, then EFI_ACCESS_DENIED is returned.
 459   Otherwise, EFI_SUCCESS is returned.
 460   If Lock is NULL, then ASSERT().
 461   If Lock is not initialized, then ASSERT().
 462
 463   @param  Lock              A pointer to the lock to acquire.
 464
 465   @retval EFI_SUCCESS       The lock was acquired.
 466   @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
 467
 468 **/
 469 EFI_STATUS
 470 EFIAPI
 471 EfiAcquireLockOrFail (
 472   IN EFI_LOCK  *Lock
 473   )
 474 {
 475
 476   ASSERT (Lock != NULL);
 477   ASSERT (Lock->Lock != EfiLockUninitialized);
 478
 479   if (Lock->Lock == EfiLockAcquired) {
 480     //
 481     // Lock is already owned, so bail out
 482     //
 483     return EFI_ACCESS_DENIED;
 484   }
 485
 486   Lock->OwnerTpl = gBS->RaiseTPL (Lock->Tpl);
 487
 488   Lock->Lock = EfiLockAcquired;
 489
 490   return EFI_SUCCESS;
 491 }
 492
 493 /**
 494   Releases ownership of a lock.
 495
 496   This function transitions a mutual exclusion lock from the acquired state to
 497   the released state, and restores the system's task priority level to its
 498   previous level.
 499   If Lock is NULL, then ASSERT().
 500   If Lock is not initialized, then ASSERT().
 501   If Lock is already in the released state, then ASSERT().
 502
 503   @param  Lock  A pointer to the lock to release.
 504
 505 **/
 506 VOID
 507 EFIAPI
 508 EfiReleaseLock (
 509   IN EFI_LOCK  *Lock
 510   )
 511 {
 512   EFI_TPL Tpl;
 513
 514   ASSERT (Lock != NULL);
 515   ASSERT (Lock->Lock == EfiLockAcquired);
 516
 517   Tpl = Lock->OwnerTpl;
 518
 519   Lock->Lock = EfiLockReleased;
 520
 521   gBS->RestoreTPL (Tpl);
 522 }
 523
 524 /**
 525   Tests whether a controller handle is being managed by a specific driver.
 526
 527   This function tests whether the driver specified by DriverBindingHandle is
 528   currently managing the controller specified by ControllerHandle.  This test
 529   is performed by evaluating if the the protocol specified by ProtocolGuid is
 530   present on ControllerHandle and is was opened by DriverBindingHandle with an
 531   attribute of EFI_OPEN_PROTOCOL_BY_DRIVER.
 532   If ProtocolGuid is NULL, then ASSERT().
 533
 534   @param  ControllerHandle     A handle for a controller to test.
 535   @param  DriverBindingHandle  Specifies the driver binding handle for the
 536                                driver.
 537   @param  ProtocolGuid         Specifies the protocol that the driver specified
 538                                by DriverBindingHandle opens in its Start()
 539                                function.
 540
 541   @retval EFI_SUCCESS          ControllerHandle is managed by the driver
 542                                specified by DriverBindingHandle.
 543   @retval EFI_UNSUPPORTED      ControllerHandle is not managed by the driver
 544                                specified by DriverBindingHandle.
 545
 546 **/
 547 EFI_STATUS
 548 EFIAPI
 549 EfiTestManagedDevice (
 550   IN CONST EFI_HANDLE       ControllerHandle,
 551   IN CONST EFI_HANDLE       DriverBindingHandle,
 552   IN CONST EFI_GUID         *ProtocolGuid
 553   )
 554 {
 555   EFI_STATUS     Status;
 556   VOID           *ManagedInterface;
 557
 558   ASSERT (ProtocolGuid != NULL);
 559
 560   Status = gBS->OpenProtocol (
 561                   ControllerHandle,
 562                   (EFI_GUID *) ProtocolGuid,
 563                   &ManagedInterface,
 564                   DriverBindingHandle,
 565                   ControllerHandle,
 566                   EFI_OPEN_PROTOCOL_BY_DRIVER
 567                   );
 568   if (!EFI_ERROR (Status)) {
 569     gBS->CloseProtocol (
 570            ControllerHandle,
 571            (EFI_GUID *) ProtocolGuid,
 572            DriverBindingHandle,
 573            ControllerHandle
 574            );
 575     return EFI_UNSUPPORTED;
 576   }
 577
 578   if (Status != EFI_ALREADY_STARTED) {
 579     return EFI_UNSUPPORTED;
 580   }
 581
 582   return EFI_SUCCESS;
 583 }
 584
 585 /**
 586   Tests whether a child handle is a child device of the controller.
 587
 588   This function tests whether ChildHandle is one of the children of
 589   ControllerHandle.  This test is performed by checking to see if the protocol
 590   specified by ProtocolGuid is present on ControllerHandle and opened by
 591   ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 592   If ProtocolGuid is NULL, then ASSERT().
 593
 594   @param  ControllerHandle     A handle for a (parent) controller to test.
 595   @param  ChildHandle          A child handle to test.
 596   @param  ProtocolGuid         Supplies the protocol that the child controller
 597                                opens on its parent controller.
 598
 599   @retval EFI_SUCCESS          ChildHandle is a child of the ControllerHandle.
 600   @retval EFI_UNSUPPORTED      ChildHandle is not a child of the
 601                                ControllerHandle.
 602
 603 **/
 604 EFI_STATUS
 605 EFIAPI
 606 EfiTestChildHandle (
 607   IN CONST EFI_HANDLE       ControllerHandle,
 608   IN CONST EFI_HANDLE       ChildHandle,
 609   IN CONST EFI_GUID         *ProtocolGuid
 610   )
 611 {
 612   EFI_STATUS                            Status;
 613   EFI_OPEN_PROTOCOL_INFORMATION_ENTRY   *OpenInfoBuffer;
 614   UINTN                                 EntryCount;
 615   UINTN                                 Index;
 616
 617   ASSERT (ProtocolGuid != NULL);
 618
 619   //
 620   // Retrieve the list of agents that are consuming the specific protocol
 621   // on ControllerHandle.
 622   //
 623   Status = gBS->OpenProtocolInformation (
 624                   ControllerHandle,
 625                   (EFI_GUID *) ProtocolGuid,
 626                   &OpenInfoBuffer,
 627                   &EntryCount
 628                   );
 629   if (EFI_ERROR (Status)) {
 630     return EFI_UNSUPPORTED;
 631   }
 632
 633   //
 634   // Inspect if ChildHandle is one of the agents.
 635   //
 636   Status = EFI_UNSUPPORTED;
 637   for (Index = 0; Index < EntryCount; Index++) {
 638     if ((OpenInfoBuffer[Index].ControllerHandle == ChildHandle) &&
 639         (OpenInfoBuffer[Index].Attributes & EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER) != 0) {
 640       Status = EFI_SUCCESS;
 641       break;
 642     }
 643   }
 644
 645   FreePool (OpenInfoBuffer);
 646   return Status;
 647 }
 648
 649 /**
 650   This function looks up a Unicode string in UnicodeStringTable.
 651
 652   If Language is a member of SupportedLanguages and a Unicode string is found in
 653   UnicodeStringTable that matches the language code specified by Language, then it
 654   is returned in UnicodeString.
 655
 656   @param  Language                A pointer to the ISO 639-2 language code for the
 657                                   Unicode string to look up and return.
 658   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 659                                   that the Unicode string table supports.  Language
 660                                   must be a member of this set.
 661   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 662   @param  UnicodeString           A pointer to the Unicode string from UnicodeStringTable
 663                                   that matches the language specified by Language.
 664
 665   @retval EFI_SUCCESS             The Unicode string that matches the language
 666                                   specified by Language was found
 667                                   in the table of Unicode strings UnicodeStringTable,
 668                                   and it was returned in UnicodeString.
 669   @retval EFI_INVALID_PARAMETER   Language is NULL.
 670   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 671   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 672   @retval EFI_UNSUPPORTED         UnicodeStringTable is NULL.
 673   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 674                                   member of SupportedLanguages.
 675   @retval EFI_UNSUPPORTED         The language specified by Language is not
 676                                   supported by UnicodeStringTable.
 677
 678 **/
 679 EFI_STATUS
 680 EFIAPI
 681 LookupUnicodeString (
 682   IN CONST CHAR8                     *Language,
 683   IN CONST CHAR8                     *SupportedLanguages,
 684   IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 685   OUT CHAR16                         **UnicodeString
 686   )
 687 {
 688   //
 689   // Make sure the parameters are valid
 690   //
 691   if (Language == NULL || UnicodeString == NULL) {
 692     return EFI_INVALID_PARAMETER;
 693   }
 694
 695   //
 696   // If there are no supported languages, or the Unicode String Table is empty, then the
 697   // Unicode String specified by Language is not supported by this Unicode String Table
 698   //
 699   if (SupportedLanguages == NULL || UnicodeStringTable == NULL) {
 700     return EFI_UNSUPPORTED;
 701   }
 702
 703   //
 704   // Make sure Language is in the set of Supported Languages
 705   //
 706   while (*SupportedLanguages != 0) {
 707     if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
 708
 709       //
 710       // Search the Unicode String Table for the matching Language specifier
 711       //
 712       while (UnicodeStringTable->Language != NULL) {
 713         if (CompareIso639LanguageCode (Language, UnicodeStringTable->Language)) {
 714
 715           //
 716           // A matching string was found, so return it
 717           //
 718           *UnicodeString = UnicodeStringTable->UnicodeString;
 719           return EFI_SUCCESS;
 720         }
 721
 722         UnicodeStringTable++;
 723       }
 724
 725       return EFI_UNSUPPORTED;
 726     }
 727
 728     SupportedLanguages += 3;
 729   }
 730
 731   return EFI_UNSUPPORTED;
 732 }
 733
 734
 735
 736 /**
 737   This function looks up a Unicode string in UnicodeStringTable.
 738
 739   If Language is a member of SupportedLanguages and a Unicode string is found in
 740   UnicodeStringTable that matches the language code specified by Language, then
 741   it is returned in UnicodeString.
 742
 743   @param  Language             A pointer to an ASCII string containing the ISO 639-2 or the
 744                                RFC 4646 language code for the Unicode string to look up and
 745                                return. If Iso639Language is TRUE, then this ASCII string is
 746                                not assumed to be Null-terminated, and only the first three
 747                                characters are used. If Iso639Language is FALSE, then this ASCII
 748                                string must be Null-terminated.
 749   @param  SupportedLanguages   A pointer to a Null-terminated ASCII string that contains a
 750                                set of ISO 639-2 or RFC 4646 language codes that the Unicode
 751                                string table supports.  Language must be a member of this set.
 752                                If Iso639Language is TRUE, then this string contains one or more
 753                                ISO 639-2 language codes with no separator characters. If Iso639Language
 754                                is FALSE, then is string contains one or more RFC 4646 language
 755                                codes separated by ';'.
 756   @param  UnicodeStringTable   A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
 757                                is defined in "Related Definitions".
 758   @param  UnicodeString        A pointer to the Null-terminated Unicode string from UnicodeStringTable
 759                                that matches the language specified by Language.
 760   @param  Iso639Language       Specifies the supported language code format. If it is TRUE, then
 761                                Language and SupportedLanguages follow ISO 639-2 language code format.
 762                                Otherwise, they follow RFC 4646 language code format.
 763
 764
 765   @retval  EFI_SUCCESS            The Unicode string that matches the language specified by Language
 766                                   was found in the table of Unicode strings UnicodeStringTable, and
 767                                   it was returned in UnicodeString.
 768   @retval  EFI_INVALID_PARAMETER  Language is NULL.
 769   @retval  EFI_INVALID_PARAMETER  UnicodeString is NULL.
 770   @retval  EFI_UNSUPPORTED        SupportedLanguages is NULL.
 771   @retval  EFI_UNSUPPORTED        UnicodeStringTable is NULL.
 772   @retval  EFI_UNSUPPORTED        The language specified by Language is not a member of SupportedLanguages.
 773   @retval  EFI_UNSUPPORTED        The language specified by Language is not supported by UnicodeStringTable.
 774
 775 **/
 776 EFI_STATUS
 777 EFIAPI
 778 LookupUnicodeString2 (
 779   IN CONST CHAR8                     *Language,
 780   IN CONST CHAR8                     *SupportedLanguages,
 781   IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 782   OUT CHAR16                         **UnicodeString,
 783   IN BOOLEAN                         Iso639Language
 784   )
 785 {
 786   BOOLEAN   Found;
 787   UINTN     Index;
 788   CHAR8     *LanguageString;
 789
 790   //
 791   // Make sure the parameters are valid
 792   //
 793   if (Language == NULL || UnicodeString == NULL) {
 794     return EFI_INVALID_PARAMETER;
 795   }
 796
 797   //
 798   // If there are no supported languages, or the Unicode String Table is empty, then the
 799   // Unicode String specified by Language is not supported by this Unicode String Table
 800   //
 801   if (SupportedLanguages == NULL || UnicodeStringTable == NULL) {
 802     return EFI_UNSUPPORTED;
 803   }
 804
 805   //
 806   // Make sure Language is in the set of Supported Languages
 807   //
 808   Found = FALSE;
 809   while (*SupportedLanguages != 0) {
 810     if (Iso639Language) {
 811       if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
 812         Found = TRUE;
 813         break;
 814       }
 815       SupportedLanguages += 3;
 816     } else {
 817       for (Index = 0; SupportedLanguages[Index] != 0 && SupportedLanguages[Index] != ';'; Index++);
 818       if ((AsciiStrnCmp(SupportedLanguages, Language, Index) == 0) && (Language[Index] == 0)) {
 819         Found = TRUE;
 820         break;
 821       }
 822       SupportedLanguages += Index;
 823       for (; *SupportedLanguages != 0 && *SupportedLanguages == ';'; SupportedLanguages++);
 824     }
 825   }
 826
 827   //
 828   // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
 829   //
 830   if (!Found) {
 831     return EFI_UNSUPPORTED;
 832   }
 833
 834   //
 835   // Search the Unicode String Table for the matching Language specifier
 836   //
 837   while (UnicodeStringTable->Language != NULL) {
 838     LanguageString = UnicodeStringTable->Language;
 839     while (0 != *LanguageString) {
 840       for (Index = 0 ;LanguageString[Index] != 0 && LanguageString[Index] != ';'; Index++);
 841       if (AsciiStrnCmp(LanguageString, Language, Index) == 0) {
 842         *UnicodeString = UnicodeStringTable->UnicodeString;
 843         return EFI_SUCCESS;
 844       }
 845       LanguageString += Index;
 846       for (Index = 0 ;LanguageString[Index] != 0 && LanguageString[Index] == ';'; Index++);
 847     }
 848     UnicodeStringTable++;
 849   }
 850
 851   return EFI_UNSUPPORTED;
 852 }
 853
 854
 855 /**
 856   This function adds a Unicode string to UnicodeStringTable.
 857
 858   If Language is a member of SupportedLanguages then UnicodeString is added to
 859   UnicodeStringTable.  New buffers are allocated for both Language and
 860   UnicodeString.  The contents of Language and UnicodeString are copied into
 861   these new buffers.  These buffers are automatically freed when
 862   FreeUnicodeStringTable() is called.
 863
 864   @param  Language                A pointer to the ISO 639-2 language code for the Unicode
 865                                   string to add.
 866   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 867                                   that the Unicode string table supports.
 868                                   Language must be a member of this set.
 869   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 870   @param  UnicodeString           A pointer to the Unicode string to add.
 871
 872   @retval EFI_SUCCESS             The Unicode string that matches the language
 873                                   specified by Language was found in the table of
 874                                   Unicode strings UnicodeStringTable, and it was
 875                                   returned in UnicodeString.
 876   @retval EFI_INVALID_PARAMETER   Language is NULL.
 877   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 878   @retval EFI_INVALID_PARAMETER   UnicodeString is an empty string.
 879   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 880   @retval EFI_ALREADY_STARTED     A Unicode string with language Language is
 881                                   already present in UnicodeStringTable.
 882   @retval EFI_OUT_OF_RESOURCES    There is not enough memory to add another
 883                                   Unicode string to UnicodeStringTable.
 884   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 885                                   member of SupportedLanguages.
 886
 887 **/
 888 EFI_STATUS
 889 EFIAPI
 890 AddUnicodeString (
 891   IN     CONST CHAR8               *Language,
 892   IN     CONST CHAR8               *SupportedLanguages,
 893   IN OUT EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 894   IN     CONST CHAR16              *UnicodeString
 895   )
 896 {
 897   UINTN                     NumberOfEntries;
 898   EFI_UNICODE_STRING_TABLE  *OldUnicodeStringTable;
 899   EFI_UNICODE_STRING_TABLE  *NewUnicodeStringTable;
 900   UINTN                     UnicodeStringLength;
 901
 902   //
 903   // Make sure the parameter are valid
 904   //
 905   if (Language == NULL || UnicodeString == NULL || UnicodeStringTable == NULL) {
 906     return EFI_INVALID_PARAMETER;
 907   }
 908
 909   //
 910   // If there are no supported languages, then a Unicode String can not be added
 911   //
 912   if (SupportedLanguages == NULL) {
 913     return EFI_UNSUPPORTED;
 914   }
 915
 916   //
 917   // If the Unicode String is empty, then a Unicode String can not be added
 918   //
 919   if (UnicodeString[0] == 0) {
 920     return EFI_INVALID_PARAMETER;
 921   }
 922
 923   //
 924   // Make sure Language is a member of SupportedLanguages
 925   //
 926   while (*SupportedLanguages != 0) {
 927     if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
 928
 929       //
 930       // Determine the size of the Unicode String Table by looking for a NULL Language entry
 931       //
 932       NumberOfEntries = 0;
 933       if (*UnicodeStringTable != NULL) {
 934         OldUnicodeStringTable = *UnicodeStringTable;
 935         while (OldUnicodeStringTable->Language != NULL) {
 936           if (CompareIso639LanguageCode (Language, OldUnicodeStringTable->Language)) {
 937             return EFI_ALREADY_STARTED;
 938           }
 939
 940           OldUnicodeStringTable++;
 941           NumberOfEntries++;
 942         }
 943       }
 944
 945       //
 946       // Allocate space for a new Unicode String Table.  It must hold the current number of
 947       // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
 948       // marker
 949       //
 950       NewUnicodeStringTable = AllocatePool ((NumberOfEntries + 2) * sizeof (EFI_UNICODE_STRING_TABLE));
 951       if (NewUnicodeStringTable == NULL) {
 952         return EFI_OUT_OF_RESOURCES;
 953       }
 954
 955       //
 956       // If the current Unicode String Table contains any entries, then copy them to the
 957       // newly allocated Unicode String Table.
 958       //
 959       if (*UnicodeStringTable != NULL) {
 960         CopyMem (
 961            NewUnicodeStringTable,
 962            *UnicodeStringTable,
 963            NumberOfEntries * sizeof (EFI_UNICODE_STRING_TABLE)
 964            );
 965       }
 966
 967       //
 968       // Allocate space for a copy of the Language specifier
 969       //
 970       NewUnicodeStringTable[NumberOfEntries].Language = AllocateCopyPool (3, Language);
 971       if (NewUnicodeStringTable[NumberOfEntries].Language == NULL) {
 972         FreePool (NewUnicodeStringTable);
 973         return EFI_OUT_OF_RESOURCES;
 974       }
 975
 976       //
 977       // Compute the length of the Unicode String
 978       //
 979       for (UnicodeStringLength = 0; UnicodeString[UnicodeStringLength] != 0; UnicodeStringLength++)
 980         ;
 981
 982       //
 983       // Allocate space for a copy of the Unicode String
 984       //
 985       NewUnicodeStringTable[NumberOfEntries].UnicodeString = AllocateCopyPool (
 986                                                               (UnicodeStringLength + 1) * sizeof (CHAR16),
 987                                                               UnicodeString
 988                                                               );
 989       if (NewUnicodeStringTable[NumberOfEntries].UnicodeString == NULL) {
 990         FreePool (NewUnicodeStringTable[NumberOfEntries].Language);
 991         FreePool (NewUnicodeStringTable);
 992         return EFI_OUT_OF_RESOURCES;
 993       }
 994
 995       //
 996       // Mark the end of the Unicode String Table
 997       //
 998       NewUnicodeStringTable[NumberOfEntries + 1].Language       = NULL;
 999       NewUnicodeStringTable[NumberOfEntries + 1].UnicodeString  = NULL;
1000
1001       //
1002       // Free the old Unicode String Table
1003       //
1004       if (*UnicodeStringTable != NULL) {
1005         FreePool (*UnicodeStringTable);
1006       }
1007
1008       //
1009       // Point UnicodeStringTable at the newly allocated Unicode String Table
1010       //
1011       *UnicodeStringTable = NewUnicodeStringTable;
1012
1013       return EFI_SUCCESS;
1014     }
1015
1016     SupportedLanguages += 3;
1017   }
1018
1019   return EFI_UNSUPPORTED;
1020 }
1021
1022
1023 /**
1024   This function adds the Null-terminated Unicode string specified by UnicodeString
1025   to UnicodeStringTable.
1026
1027   If Language is a member of SupportedLanguages then UnicodeString is added to
1028   UnicodeStringTable.  New buffers are allocated for both Language and UnicodeString.
1029   The contents of Language and UnicodeString are copied into these new buffers.
1030   These buffers are automatically freed when EfiLibFreeUnicodeStringTable() is called.
1031
1032   @param  Language            A pointer to an ASCII string containing the ISO 639-2 or
1033                               the RFC 4646 language code for the Unicode string to add.
1034                               If Iso639Language is TRUE, then this ASCII string is not
1035                               assumed to be Null-terminated, and only the first three
1036                               chacters are used. If Iso639Language is FALSE, then this
1037                               ASCII string must be Null-terminated.
1038   @param  SupportedLanguages  A pointer to a Null-terminated ASCII string that contains
1039                               a set of ISO 639-2 or RFC 4646 language codes that the Unicode
1040                               string table supports.  Language must be a member of this set.
1041                               If Iso639Language is TRUE, then this string contains one or more
1042                               ISO 639-2 language codes with no separator characters.
1043                               If Iso639Language is FALSE, then is string contains one or more
1044                               RFC 4646 language codes separated by ';'.
1045   @param  UnicodeStringTable  A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
1046                               is defined in "Related Definitions".
1047   @param  UnicodeString       A pointer to the Unicode string to add.
1048   @param  Iso639Language      Specifies the supported language code format. If it is TRUE,
1049                               then Language and SupportedLanguages follow ISO 639-2 language code format.
1050                               Otherwise, they follow RFC 4646 language code format.
1051
1052   @retval EFI_SUCCESS            The Unicode string that matches the language specified by
1053                                  Language was found in the table of Unicode strings UnicodeStringTable,
1054                                  and it was returned in UnicodeString.
1055   @retval EFI_INVALID_PARAMETER  Language is NULL.
1056   @retval EFI_INVALID_PARAMETER  UnicodeString is NULL.
1057   @retval EFI_INVALID_PARAMETER  UnicodeString is an empty string.
1058   @retval EFI_UNSUPPORTED        SupportedLanguages is NULL.
1059   @retval EFI_ALREADY_STARTED    A Unicode string with language Language is already present in
1060                                  UnicodeStringTable.
1061   @retval EFI_OUT_OF_RESOURCES   There is not enough memory to add another Unicode string UnicodeStringTable.
1062   @retval EFI_UNSUPPORTED        The language specified by Language is not a member of SupportedLanguages.
1063
1064 **/
1065 EFI_STATUS
1066 EFIAPI
1067 AddUnicodeString2 (
1068   IN     CONST CHAR8               *Language,
1069   IN     CONST CHAR8               *SupportedLanguages,
1070   IN OUT EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
1071   IN     CONST CHAR16              *UnicodeString,
1072   IN     BOOLEAN                   Iso639Language
1073   )
1074 {
1075   UINTN                     NumberOfEntries;
1076   EFI_UNICODE_STRING_TABLE  *OldUnicodeStringTable;
1077   EFI_UNICODE_STRING_TABLE  *NewUnicodeStringTable;
1078   UINTN                     UnicodeStringLength;
1079   BOOLEAN                   Found;
1080   UINTN                     Index;
1081   CHAR8                     *LanguageString;
1082
1083   //
1084   // Make sure the parameter are valid
1085   //
1086   if (Language == NULL || UnicodeString == NULL || UnicodeStringTable == NULL) {
1087     return EFI_INVALID_PARAMETER;
1088   }
1089
1090   //
1091   // If there are no supported languages, then a Unicode String can not be added
1092   //
1093   if (SupportedLanguages == NULL) {
1094     return EFI_UNSUPPORTED;
1095   }
1096
1097   //
1098   // If the Unicode String is empty, then a Unicode String can not be added
1099   //
1100   if (UnicodeString[0] == 0) {
1101     return EFI_INVALID_PARAMETER;
1102   }
1103
1104   //
1105   // Make sure Language is a member of SupportedLanguages
1106   //
1107   Found = FALSE;
1108   while (*SupportedLanguages != 0) {
1109     if (Iso639Language) {
1110       if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
1111         Found = TRUE;
1112         break;
1113       }
1114       SupportedLanguages += 3;
1115     } else {
1116       for (Index = 0; SupportedLanguages[Index] != 0 && SupportedLanguages[Index] != ';'; Index++);
1117       if (AsciiStrnCmp(SupportedLanguages, Language, Index) == 0) {
1118         Found = TRUE;
1119         break;
1120       }
1121       SupportedLanguages += Index;
1122       for (; *SupportedLanguages != 0 && *SupportedLanguages == ';'; SupportedLanguages++);
1123     }
1124   }
1125
1126   //
1127   // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
1128   //
1129   if (!Found) {
1130     return EFI_UNSUPPORTED;
1131   }
1132
1133   //
1134   // Determine the size of the Unicode String Table by looking for a NULL Language entry
1135   //
1136   NumberOfEntries = 0;
1137   if (*UnicodeStringTable != NULL) {
1138     OldUnicodeStringTable = *UnicodeStringTable;
1139     while (OldUnicodeStringTable->Language != NULL) {
1140       LanguageString = OldUnicodeStringTable->Language;
1141
1142       while (*LanguageString != 0) {
1143         for (Index = 0; LanguageString[Index] != 0 && LanguageString[Index] != ';'; Index++);
1144
1145         if (AsciiStrnCmp (Language, LanguageString, Index) == 0) {
1146           return EFI_ALREADY_STARTED;
1147         }
1148         LanguageString += Index;
1149         for (; *LanguageString != 0 && *LanguageString == ';'; LanguageString++);
1150       }
1151       OldUnicodeStringTable++;
1152       NumberOfEntries++;
1153     }
1154   }
1155
1156   //
1157   // Allocate space for a new Unicode String Table.  It must hold the current number of
1158   // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
1159   // marker
1160   //
1161   NewUnicodeStringTable = AllocatePool ((NumberOfEntries + 2) * sizeof (EFI_UNICODE_STRING_TABLE));
1162   if (NewUnicodeStringTable == NULL) {
1163     return EFI_OUT_OF_RESOURCES;
1164   }
1165
1166   //
1167   // If the current Unicode String Table contains any entries, then copy them to the
1168   // newly allocated Unicode String Table.
1169   //
1170   if (*UnicodeStringTable != NULL) {
1171     CopyMem (
1172       NewUnicodeStringTable,
1173       *UnicodeStringTable,
1174       NumberOfEntries * sizeof (EFI_UNICODE_STRING_TABLE)
1175       );
1176   }
1177
1178   //
1179   // Allocate space for a copy of the Language specifier
1180   //
1181   NewUnicodeStringTable[NumberOfEntries].Language = AllocateCopyPool (AsciiStrSize(Language), Language);
1182   if (NewUnicodeStringTable[NumberOfEntries].Language == NULL) {
1183     FreePool (NewUnicodeStringTable);
1184     return EFI_OUT_OF_RESOURCES;
1185   }
1186
1187   //
1188   // Compute the length of the Unicode String
1189   //
1190   for (UnicodeStringLength = 0; UnicodeString[UnicodeStringLength] != 0; UnicodeStringLength++);
1191
1192   //
1193   // Allocate space for a copy of the Unicode String
1194   //
1195   NewUnicodeStringTable[NumberOfEntries].UnicodeString = AllocateCopyPool (StrSize (UnicodeString), UnicodeString);
1196   if (NewUnicodeStringTable[NumberOfEntries].UnicodeString == NULL) {
1197     FreePool (NewUnicodeStringTable[NumberOfEntries].Language);
1198     FreePool (NewUnicodeStringTable);
1199     return EFI_OUT_OF_RESOURCES;
1200   }
1201
1202   //
1203   // Mark the end of the Unicode String Table
1204   //
1205   NewUnicodeStringTable[NumberOfEntries + 1].Language       = NULL;
1206   NewUnicodeStringTable[NumberOfEntries + 1].UnicodeString  = NULL;
1207
1208   //
1209   // Free the old Unicode String Table
1210   //
1211   if (*UnicodeStringTable != NULL) {
1212     FreePool (*UnicodeStringTable);
1213   }
1214
1215   //
1216   // Point UnicodeStringTable at the newly allocated Unicode String Table
1217   //
1218   *UnicodeStringTable = NewUnicodeStringTable;
1219
1220   return EFI_SUCCESS;
1221 }
1222
1223 /**
1224   This function frees the table of Unicode strings in UnicodeStringTable.
1225
1226   If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
1227   Otherwise, each language code, and each Unicode string in the Unicode string
1228   table are freed, and EFI_SUCCESS is returned.
1229
1230   @param  UnicodeStringTable  A pointer to the table of Unicode strings.
1231
1232   @retval EFI_SUCCESS         The Unicode string table was freed.
1233
1234 **/
1235 EFI_STATUS
1236 EFIAPI
1237 FreeUnicodeStringTable (
1238   IN EFI_UNICODE_STRING_TABLE  *UnicodeStringTable
1239   )
1240 {
1241   UINTN Index;
1242
1243   //
1244   // If the Unicode String Table is NULL, then it is already freed
1245   //
1246   if (UnicodeStringTable == NULL) {
1247     return EFI_SUCCESS;
1248   }
1249
1250   //
1251   // Loop through the Unicode String Table until we reach the end of table marker
1252   //
1253   for (Index = 0; UnicodeStringTable[Index].Language != NULL; Index++) {
1254
1255     //
1256     // Free the Language string from the Unicode String Table
1257     //
1258     FreePool (UnicodeStringTable[Index].Language);
1259
1260     //
1261     // Free the Unicode String from the Unicode String Table
1262     //
1263     if (UnicodeStringTable[Index].UnicodeString != NULL) {
1264       FreePool (UnicodeStringTable[Index].UnicodeString);
1265     }
1266   }
1267
1268   //
1269   // Free the Unicode String Table itself
1270   //
1271   FreePool (UnicodeStringTable);
1272
1273   return EFI_SUCCESS;
1274 }
1275
1276 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1277
1278 /**
1279   [ATTENTION] This function will be deprecated for security reason.
1280
1281   Returns a pointer to an allocated buffer that contains the contents of a
1282   variable retrieved through the UEFI Runtime Service GetVariable().  The
1283   returned buffer is allocated using AllocatePool().  The caller is responsible
1284   for freeing this buffer with FreePool().
1285
1286   If Name is NULL, then ASSERT().
1287   If Guid is NULL, then ASSERT().
1288
1289   @param[in]  Name  The pointer to a Null-terminated Unicode string.
1290   @param[in]  Guid  The pointer to an EFI_GUID structure
1291
1292   @retval NULL   The variable could not be retrieved.
1293   @retval NULL   There are not enough resources available for the variable contents.
1294   @retval Other  A pointer to allocated buffer containing the variable contents.
1295
1296 **/
1297 VOID *
1298 EFIAPI
1299 GetVariable (
1300   IN CONST CHAR16    *Name,
1301   IN CONST EFI_GUID  *Guid
1302   )
1303 {
1304   EFI_STATUS  Status;
1305   UINTN       Size;
1306   VOID        *Value;
1307
1308   ASSERT (Name != NULL);
1309   ASSERT (Guid != NULL);
1310
1311   //
1312   // Try to get the variable size.
1313   //
1314   Value = NULL;
1315   Size = 0;
1316   Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &Size, Value);
1317   if (Status != EFI_BUFFER_TOO_SMALL) {
1318     return NULL;
1319   }
1320
1321   //
1322   // Allocate buffer to get the variable.
1323   //
1324   Value = AllocatePool (Size);
1325   if (Value == NULL) {
1326     return NULL;
1327   }
1328
1329   //
1330   // Get the variable data.
1331   //
1332   Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &Size, Value);
1333   if (EFI_ERROR (Status)) {
1334     FreePool(Value);
1335     return NULL;
1336   }
1337
1338   return Value;
1339 }
1340
1341 /**
1342   [ATTENTION] This function will be deprecated for security reason.
1343
1344   Returns a pointer to an allocated buffer that contains the contents of a
1345   variable retrieved through the UEFI Runtime Service GetVariable().  This
1346   function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1347   The returned buffer is allocated using AllocatePool().  The caller is
1348   responsible for freeing this buffer with FreePool().
1349
1350   If Name is NULL, then ASSERT().
1351
1352   @param[in]  Name  The pointer to a Null-terminated Unicode string.
1353
1354   @retval NULL   The variable could not be retrieved.
1355   @retval NULL   There are not enough resources available for the variable contents.
1356   @retval Other  A pointer to allocated buffer containing the variable contents.
1357
1358 **/
1359 VOID *
1360 EFIAPI
1361 GetEfiGlobalVariable (
1362   IN CONST CHAR16  *Name
1363   )
1364 {
1365   return GetVariable (Name, &gEfiGlobalVariableGuid);
1366 }
1367 #endif
1368
1369 /**
1370   Returns the status whether get the variable success. The function retrieves
1371   variable  through the UEFI Runtime Service GetVariable().  The
1372   returned buffer is allocated using AllocatePool().  The caller is responsible
1373   for freeing this buffer with FreePool().
1374
1375   If Name  is NULL, then ASSERT().
1376   If Guid  is NULL, then ASSERT().
1377   If Value is NULL, then ASSERT().
1378
1379   @param[in]  Name  The pointer to a Null-terminated Unicode string.
1380   @param[in]  Guid  The pointer to an EFI_GUID structure
1381   @param[out] Value The buffer point saved the variable info.
1382   @param[out] Size  The buffer size of the variable.
1383
1384   @return EFI_OUT_OF_RESOURCES      Allocate buffer failed.
1385   @return EFI_SUCCESS               Find the specified variable.
1386   @return Others Errors             Return errors from call to gRT->GetVariable.
1387
1388 **/
1389 EFI_STATUS
1390 EFIAPI
1391 GetVariable2 (
1392   IN CONST CHAR16    *Name,
1393   IN CONST EFI_GUID  *Guid,
1394   OUT VOID           **Value,
1395   OUT UINTN          *Size OPTIONAL
1396   )
1397 {
1398   EFI_STATUS  Status;
1399   UINTN       BufferSize;
1400
1401   ASSERT (Name != NULL && Guid != NULL && Value != NULL);
1402
1403   //
1404   // Try to get the variable size.
1405   //
1406   BufferSize = 0;
1407   *Value     = NULL;
1408   if (Size != NULL) {
1409     *Size  = 0;
1410   }
1411
1412   Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &BufferSize, *Value);
1413   if (Status != EFI_BUFFER_TOO_SMALL) {
1414     return Status;
1415   }
1416
1417   //
1418   // Allocate buffer to get the variable.
1419   //
1420   *Value = AllocatePool (BufferSize);
1421   ASSERT (*Value != NULL);
1422   if (*Value == NULL) {
1423     return EFI_OUT_OF_RESOURCES;
1424   }
1425
1426   //
1427   // Get the variable data.
1428   //
1429   Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &BufferSize, *Value);
1430   if (EFI_ERROR (Status)) {
1431     FreePool(*Value);
1432     *Value = NULL;
1433   }
1434
1435   if (Size != NULL) {
1436     *Size = BufferSize;
1437   }
1438
1439   return Status;
1440 }
1441
1442 /**
1443   Returns a pointer to an allocated buffer that contains the contents of a
1444   variable retrieved through the UEFI Runtime Service GetVariable().  This
1445   function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1446   The returned buffer is allocated using AllocatePool().  The caller is
1447   responsible for freeing this buffer with FreePool().
1448
1449   If Name is NULL, then ASSERT().
1450   If Value is NULL, then ASSERT().
1451
1452   @param[in]  Name  The pointer to a Null-terminated Unicode string.
1453   @param[out] Value The buffer point saved the variable info.
1454   @param[out] Size  The buffer size of the variable.
1455
1456   @return EFI_OUT_OF_RESOURCES      Allocate buffer failed.
1457   @return EFI_SUCCESS               Find the specified variable.
1458   @return Others Errors             Return errors from call to gRT->GetVariable.
1459
1460 **/
1461 EFI_STATUS
1462 EFIAPI
1463 GetEfiGlobalVariable2 (
1464   IN CONST CHAR16    *Name,
1465   OUT VOID           **Value,
1466   OUT UINTN          *Size OPTIONAL
1467   )
1468 {
1469   return GetVariable2 (Name, &gEfiGlobalVariableGuid, Value, Size);
1470 }
1471
1472 /**
1473   Returns a pointer to an allocated buffer that contains the best matching language
1474   from a set of supported languages.
1475
1476   This function supports both ISO 639-2 and RFC 4646 language codes, but language
1477   code types may not be mixed in a single call to this function.  The language
1478   code returned is allocated using AllocatePool().  The caller is responsible for
1479   freeing the allocated buffer using FreePool().  This function supports a variable
1480   argument list that allows the caller to pass in a prioritized list of language
1481   codes to test against all the language codes in SupportedLanguages.
1482
1483   If SupportedLanguages is NULL, then ASSERT().
1484
1485   @param[in]  SupportedLanguages  A pointer to a Null-terminated ASCII string that
1486                                   contains a set of language codes in the format
1487                                   specified by Iso639Language.
1488   @param[in]  Iso639Language      If TRUE, then all language codes are assumed to be
1489                                   in ISO 639-2 format.  If FALSE, then all language
1490                                   codes are assumed to be in RFC 4646 language format
1491   @param[in]  ...                 A variable argument list that contains pointers to
1492                                   Null-terminated ASCII strings that contain one or more
1493                                   language codes in the format specified by Iso639Language.
1494                                   The first language code from each of these language
1495                                   code lists is used to determine if it is an exact or
1496                                   close match to any of the language codes in
1497                                   SupportedLanguages.  Close matches only apply to RFC 4646
1498                                   language codes, and the matching algorithm from RFC 4647
1499                                   is used to determine if a close match is present.  If
1500                                   an exact or close match is found, then the matching
1501                                   language code from SupportedLanguages is returned.  If
1502                                   no matches are found, then the next variable argument
1503                                   parameter is evaluated.  The variable argument list
1504                                   is terminated by a NULL.
1505
1506   @retval NULL   The best matching language could not be found in SupportedLanguages.
1507   @retval NULL   There are not enough resources available to return the best matching
1508                  language.
1509   @retval Other  A pointer to a Null-terminated ASCII string that is the best matching
1510                  language in SupportedLanguages.
1511
1512 **/
1513 CHAR8 *
1514 EFIAPI
1515 GetBestLanguage (
1516   IN CONST CHAR8  *SupportedLanguages,
1517   IN UINTN        Iso639Language,
1518   ...
1519   )
1520 {
1521   VA_LIST      Args;
1522   CHAR8        *Language;
1523   UINTN        CompareLength;
1524   UINTN        LanguageLength;
1525   CONST CHAR8  *Supported;
1526   CHAR8        *BestLanguage;
1527
1528   ASSERT (SupportedLanguages != NULL);
1529
1530   VA_START (Args, Iso639Language);
1531   while ((Language = VA_ARG (Args, CHAR8 *)) != NULL) {
1532     //
1533     // Default to ISO 639-2 mode
1534     //
1535     CompareLength  = 3;
1536     LanguageLength = MIN (3, AsciiStrLen (Language));
1537
1538     //
1539     // If in RFC 4646 mode, then determine the length of the first RFC 4646 language code in Language
1540     //
1541     if (!Iso639Language) {
1542       for (LanguageLength = 0; Language[LanguageLength] != 0 && Language[LanguageLength] != ';'; LanguageLength++);
1543     }
1544
1545     //
1546     // Trim back the length of Language used until it is empty
1547     //
1548     while (LanguageLength > 0) {
1549       //
1550       // Loop through all language codes in SupportedLanguages
1551       //
1552       for (Supported = SupportedLanguages; *Supported != '\0'; Supported += CompareLength) {
1553         //
1554         // In RFC 4646 mode, then Loop through all language codes in SupportedLanguages
1555         //
1556         if (!Iso639Language) {
1557           //
1558           // Skip ';' characters in Supported
1559           //
1560           for (; *Supported != '\0' && *Supported == ';'; Supported++);
1561           //
1562           // Determine the length of the next language code in Supported
1563           //
1564           for (CompareLength = 0; Supported[CompareLength] != 0 && Supported[CompareLength] != ';'; CompareLength++);
1565           //
1566           // If Language is longer than the Supported, then skip to the next language
1567           //
1568           if (LanguageLength > CompareLength) {
1569             continue;
1570           }
1571         }
1572         //
1573         // See if the first LanguageLength characters in Supported match Language
1574         //
1575         if (AsciiStrnCmp (Supported, Language, LanguageLength) == 0) {
1576           VA_END (Args);
1577           //
1578           // Allocate, copy, and return the best matching language code from SupportedLanguages
1579           //
1580           BestLanguage = AllocateZeroPool (CompareLength + 1);
1581           if (BestLanguage == NULL) {
1582             return NULL;
1583           }
1584           return CopyMem (BestLanguage, Supported, CompareLength);
1585         }
1586       }
1587
1588       if (Iso639Language) {
1589         //
1590         // If ISO 639 mode, then each language can only be tested once
1591         //
1592         LanguageLength = 0;
1593       } else {
1594         //
1595         // If RFC 4646 mode, then trim Language from the right to the next '-' character
1596         //
1597         for (LanguageLength--; LanguageLength > 0 && Language[LanguageLength] != '-'; LanguageLength--);
1598       }
1599     }
1600   }
1601   VA_END (Args);
1602
1603   //
1604   // No matches were found
1605   //
1606   return NULL;
1607 }
1608
1609 /**
1610   Returns an array of protocol instance that matches the given protocol.
1611
1612   @param[in]  Protocol      Provides the protocol to search for.
1613   @param[out] NoProtocols   The number of protocols returned in Buffer.
1614   @param[out] Buffer        A pointer to the buffer to return the requested
1615                             array of protocol instances that match Protocol.
1616                             The returned buffer is allocated using
1617                             EFI_BOOT_SERVICES.AllocatePool().  The caller is
1618                             responsible for freeing this buffer with
1619                             EFI_BOOT_SERVICES.FreePool().
1620
1621   @retval EFI_SUCCESS            The array of protocols was returned in Buffer,
1622                                  and the number of protocols in Buffer was
1623                                  returned in NoProtocols.
1624   @retval EFI_NOT_FOUND          No protocols found.
1625   @retval EFI_OUT_OF_RESOURCES   There is not enough pool memory to store the
1626                                  matching results.
1627   @retval EFI_INVALID_PARAMETER  Protocol is NULL.
1628   @retval EFI_INVALID_PARAMETER  NoProtocols is NULL.
1629   @retval EFI_INVALID_PARAMETER  Buffer is NULL.
1630
1631 **/
1632 EFI_STATUS
1633 EFIAPI
1634 EfiLocateProtocolBuffer (
1635   IN  EFI_GUID  *Protocol,
1636   OUT UINTN     *NoProtocols,
1637   OUT VOID      ***Buffer
1638   )
1639 {
1640   EFI_STATUS  Status;
1641   UINTN       NoHandles;
1642   EFI_HANDLE  *HandleBuffer;
1643   UINTN       Index;
1644
1645   //
1646   // Check input parameters
1647   //
1648   if (Protocol == NULL || NoProtocols == NULL || Buffer == NULL) {
1649     return EFI_INVALID_PARAMETER;
1650   }
1651
1652   //
1653   // Initialze output parameters
1654   //
1655   *NoProtocols = 0;
1656   *Buffer = NULL;
1657
1658   //
1659   // Retrieve the array of handles that support Protocol
1660   //
1661   Status = gBS->LocateHandleBuffer (
1662                   ByProtocol,
1663                   Protocol,
1664                   NULL,
1665                   &NoHandles,
1666                   &HandleBuffer
1667                   );
1668   if (EFI_ERROR (Status)) {
1669     return Status;
1670   }
1671
1672   //
1673   // Allocate array of protocol instances
1674   //
1675   Status = gBS->AllocatePool (
1676                   EfiBootServicesData,
1677                   NoHandles * sizeof (VOID *),
1678                   (VOID **)Buffer
1679                   );
1680   if (EFI_ERROR (Status)) {
1681     //
1682     // Free the handle buffer
1683     //
1684     gBS->FreePool (HandleBuffer);
1685     return EFI_OUT_OF_RESOURCES;
1686   }
1687   ZeroMem (*Buffer, NoHandles * sizeof (VOID *));
1688
1689   //
1690   // Lookup Protocol on each handle in HandleBuffer to fill in the array of
1691   // protocol instances.  Handle case where protocol instance was present when
1692   // LocateHandleBuffer() was called, but is not present when HandleProtocol()
1693   // is called.
1694   //
1695   for (Index = 0, *NoProtocols = 0; Index < NoHandles; Index++) {
1696     Status = gBS->HandleProtocol (
1697                     HandleBuffer[Index],
1698                     Protocol,
1699                     &((*Buffer)[*NoProtocols])
1700                     );
1701     if (!EFI_ERROR (Status)) {
1702       (*NoProtocols)++;
1703     }
1704   }
1705
1706   //
1707   // Free the handle buffer
1708   //
1709   gBS->FreePool (HandleBuffer);
1710
1711   //
1712   // Make sure at least one protocol instance was found
1713   //
1714   if (*NoProtocols == 0) {
1715     gBS->FreePool (*Buffer);
1716     *Buffer = NULL;
1717     return EFI_NOT_FOUND;
1718   }
1719
1720   return EFI_SUCCESS;
1721 }