MdePkg/Library/UefiLib/UefiLib.c

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