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 looks up a Unicode string in UnicodeStringTable.
 645
 646   If Language is a member of SupportedLanguages and a Unicode string is found in
 647   UnicodeStringTable that matches the language code specified by Language, then it
 648   is returned in UnicodeString.
 649
 650   @param  Language                A pointer to the ISO 639-2 language code for the
 651                                   Unicode string to look up and return.
 652   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 653                                   that the Unicode string table supports.  Language
 654                                   must be a member of this set.
 655   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 656   @param  UnicodeString           A pointer to the Unicode string from UnicodeStringTable
 657                                   that matches the language specified by Language.
 658
 659   @retval EFI_SUCCESS             The Unicode string that matches the language
 660                                   specified by Language was found
 661                                   in the table of Unicode strings UnicodeStringTable,
 662                                   and it was returned in UnicodeString.
 663   @retval EFI_INVALID_PARAMETER   Language is NULL.
 664   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 665   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 666   @retval EFI_UNSUPPORTED         UnicodeStringTable is NULL.
 667   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 668                                   member of SupportedLanguages.
 669   @retval EFI_UNSUPPORTED         The language specified by Language is not
 670                                   supported by UnicodeStringTable.
 671
 672 **/
 673 EFI_STATUS
 674 EFIAPI
 675 LookupUnicodeString (
 676   IN CONST CHAR8                     *Language,
 677   IN CONST CHAR8                     *SupportedLanguages,
 678   IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 679   OUT CHAR16                         **UnicodeString
 680   )
 681 {
 682   //
 683   // Make sure the parameters are valid
 684   //
 685   if (Language == NULL || UnicodeString == NULL) {
 686     return EFI_INVALID_PARAMETER;
 687   }
 688
 689   //
 690   // If there are no supported languages, or the Unicode String Table is empty, then the
 691   // Unicode String specified by Language is not supported by this Unicode String Table
 692   //
 693   if (SupportedLanguages == NULL || UnicodeStringTable == NULL) {
 694     return EFI_UNSUPPORTED;
 695   }
 696
 697   //
 698   // Make sure Language is in the set of Supported Languages
 699   //
 700   while (*SupportedLanguages != 0) {
 701     if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
 702
 703       //
 704       // Search the Unicode String Table for the matching Language specifier
 705       //
 706       while (UnicodeStringTable->Language != NULL) {
 707         if (CompareIso639LanguageCode (Language, UnicodeStringTable->Language)) {
 708
 709           //
 710           // A matching string was found, so return it
 711           //
 712           *UnicodeString = UnicodeStringTable->UnicodeString;
 713           return EFI_SUCCESS;
 714         }
 715
 716         UnicodeStringTable++;
 717       }
 718
 719       return EFI_UNSUPPORTED;
 720     }
 721
 722     SupportedLanguages += 3;
 723   }
 724
 725   return EFI_UNSUPPORTED;
 726 }
 727
 728
 729
 730 /**
 731   This function looks up a Unicode string in UnicodeStringTable.
 732
 733   If Language is a member of SupportedLanguages and a Unicode string is found in
 734   UnicodeStringTable that matches the language code specified by Language, then
 735   it is returned in UnicodeString.
 736
 737   @param  Language             A pointer to an ASCII string containing the ISO 639-2 or the
 738                                RFC 4646 language code for the Unicode string to look up and
 739                                return. If Iso639Language is TRUE, then this ASCII string is
 740                                not assumed to be Null-terminated, and only the first three
 741                                characters are used. If Iso639Language is FALSE, then this ASCII
 742                                string must be Null-terminated.
 743   @param  SupportedLanguages   A pointer to a Null-terminated ASCII string that contains a
 744                                set of ISO 639-2 or RFC 4646 language codes that the Unicode
 745                                string table supports.  Language must be a member of this set.
 746                                If Iso639Language is TRUE, then this string contains one or more
 747                                ISO 639-2 language codes with no separator characters. If Iso639Language
 748                                is FALSE, then is string contains one or more RFC 4646 language
 749                                codes separated by ';'.
 750   @param  UnicodeStringTable   A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
 751                                is defined in "Related Definitions".
 752   @param  UnicodeString        A pointer to the Null-terminated Unicode string from UnicodeStringTable
 753                                that matches the language specified by Language.
 754   @param  Iso639Language       Specifies the supported language code format. If it is TRUE, then
 755                                Language and SupportedLanguages follow ISO 639-2 language code format.
 756                                Otherwise, they follow RFC 4646 language code format.
 757
 758
 759   @retval  EFI_SUCCESS            The Unicode string that matches the language specified by Language
 760                                   was found in the table of Unicode strings UnicodeStringTable, and
 761                                   it was returned in UnicodeString.
 762   @retval  EFI_INVALID_PARAMETER  Language is NULL.
 763   @retval  EFI_INVALID_PARAMETER  UnicodeString is NULL.
 764   @retval  EFI_UNSUPPORTED        SupportedLanguages is NULL.
 765   @retval  EFI_UNSUPPORTED        UnicodeStringTable is NULL.
 766   @retval  EFI_UNSUPPORTED        The language specified by Language is not a member of SupportedLanguages.
 767   @retval  EFI_UNSUPPORTED        The language specified by Language is not supported by UnicodeStringTable.
 768
 769 **/
 770 EFI_STATUS
 771 EFIAPI
 772 LookupUnicodeString2 (
 773   IN CONST CHAR8                     *Language,
 774   IN CONST CHAR8                     *SupportedLanguages,
 775   IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,
 776   OUT CHAR16                         **UnicodeString,
 777   IN BOOLEAN                         Iso639Language
 778   )
 779 {
 780   BOOLEAN   Found;
 781   UINTN     Index;
 782   CHAR8     *LanguageString;
 783
 784   //
 785   // Make sure the parameters are valid
 786   //
 787   if (Language == NULL || UnicodeString == NULL) {
 788     return EFI_INVALID_PARAMETER;
 789   }
 790
 791   //
 792   // If there are no supported languages, or the Unicode String Table is empty, then the
 793   // Unicode String specified by Language is not supported by this Unicode String Table
 794   //
 795   if (SupportedLanguages == NULL || UnicodeStringTable == NULL) {
 796     return EFI_UNSUPPORTED;
 797   }
 798
 799   //
 800   // Make sure Language is in the set of Supported Languages
 801   //
 802   Found = FALSE;
 803   while (*SupportedLanguages != 0) {
 804     if (Iso639Language) {
 805       if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
 806         Found = TRUE;
 807         break;
 808       }
 809       SupportedLanguages += 3;
 810     } else {
 811       for (Index = 0; SupportedLanguages[Index] != 0 && SupportedLanguages[Index] != ';'; Index++);
 812       if ((AsciiStrnCmp(SupportedLanguages, Language, Index) == 0) && (Language[Index] == 0)) {
 813         Found = TRUE;
 814         break;
 815       }
 816       SupportedLanguages += Index;
 817       for (; *SupportedLanguages != 0 && *SupportedLanguages == ';'; SupportedLanguages++);
 818     }
 819   }
 820
 821   //
 822   // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
 823   //
 824   if (!Found) {
 825     return EFI_UNSUPPORTED;
 826   }
 827
 828   //
 829   // Search the Unicode String Table for the matching Language specifier
 830   //
 831   while (UnicodeStringTable->Language != NULL) {
 832     LanguageString = UnicodeStringTable->Language;
 833     while (0 != *LanguageString) {
 834       for (Index = 0 ;LanguageString[Index] != 0 && LanguageString[Index] != ';'; Index++);
 835       if (AsciiStrnCmp(LanguageString, Language, Index) == 0) {
 836         *UnicodeString = UnicodeStringTable->UnicodeString;
 837         return EFI_SUCCESS;
 838       }
 839       LanguageString += Index;
 840       for (Index = 0 ;LanguageString[Index] != 0 && LanguageString[Index] == ';'; Index++);
 841     }
 842     UnicodeStringTable++;
 843   }
 844
 845   return EFI_UNSUPPORTED;
 846 }
 847
 848
 849 /**
 850   This function adds a Unicode string to UnicodeStringTable.
 851
 852   If Language is a member of SupportedLanguages then UnicodeString is added to
 853   UnicodeStringTable.  New buffers are allocated for both Language and
 854   UnicodeString.  The contents of Language and UnicodeString are copied into
 855   these new buffers.  These buffers are automatically freed when
 856   FreeUnicodeStringTable() is called.
 857
 858   @param  Language                A pointer to the ISO 639-2 language code for the Unicode
 859                                   string to add.
 860   @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes
 861                                   that the Unicode string table supports.
 862                                   Language must be a member of this set.
 863   @param  UnicodeStringTable      A pointer to the table of Unicode strings.
 864   @param  UnicodeString           A pointer to the Unicode string to add.
 865
 866   @retval EFI_SUCCESS             The Unicode string that matches the language
 867                                   specified by Language was found in the table of
 868                                   Unicode strings UnicodeStringTable, and it was
 869                                   returned in UnicodeString.
 870   @retval EFI_INVALID_PARAMETER   Language is NULL.
 871   @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.
 872   @retval EFI_INVALID_PARAMETER   UnicodeString is an empty string.
 873   @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.
 874   @retval EFI_ALREADY_STARTED     A Unicode string with language Language is
 875                                   already present in UnicodeStringTable.
 876   @retval EFI_OUT_OF_RESOURCES    There is not enough memory to add another
 877                                   Unicode string to UnicodeStringTable.
 878   @retval EFI_UNSUPPORTED         The language specified by Language is not a
 879                                   member of SupportedLanguages.
 880
 881 **/
 882 EFI_STATUS
 883 EFIAPI
 884 AddUnicodeString (
 885   IN     CONST CHAR8               *Language,
 886   IN     CONST CHAR8               *SupportedLanguages,
 887   IN OUT EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
 888   IN     CONST CHAR16              *UnicodeString
 889   )
 890 {
 891   UINTN                     NumberOfEntries;
 892   EFI_UNICODE_STRING_TABLE  *OldUnicodeStringTable;
 893   EFI_UNICODE_STRING_TABLE  *NewUnicodeStringTable;
 894   UINTN                     UnicodeStringLength;
 895
 896   //
 897   // Make sure the parameter are valid
 898   //
 899   if (Language == NULL || UnicodeString == NULL || UnicodeStringTable == NULL) {
 900     return EFI_INVALID_PARAMETER;
 901   }
 902
 903   //
 904   // If there are no supported languages, then a Unicode String can not be added
 905   //
 906   if (SupportedLanguages == NULL) {
 907     return EFI_UNSUPPORTED;
 908   }
 909
 910   //
 911   // If the Unicode String is empty, then a Unicode String can not be added
 912   //
 913   if (UnicodeString[0] == 0) {
 914     return EFI_INVALID_PARAMETER;
 915   }
 916
 917   //
 918   // Make sure Language is a member of SupportedLanguages
 919   //
 920   while (*SupportedLanguages != 0) {
 921     if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
 922
 923       //
 924       // Determine the size of the Unicode String Table by looking for a NULL Language entry
 925       //
 926       NumberOfEntries = 0;
 927       if (*UnicodeStringTable != NULL) {
 928         OldUnicodeStringTable = *UnicodeStringTable;
 929         while (OldUnicodeStringTable->Language != NULL) {
 930           if (CompareIso639LanguageCode (Language, OldUnicodeStringTable->Language)) {
 931             return EFI_ALREADY_STARTED;
 932           }
 933
 934           OldUnicodeStringTable++;
 935           NumberOfEntries++;
 936         }
 937       }
 938
 939       //
 940       // Allocate space for a new Unicode String Table.  It must hold the current number of
 941       // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
 942       // marker
 943       //
 944       NewUnicodeStringTable = AllocatePool ((NumberOfEntries + 2) * sizeof (EFI_UNICODE_STRING_TABLE));
 945       if (NewUnicodeStringTable == NULL) {
 946         return EFI_OUT_OF_RESOURCES;
 947       }
 948
 949       //
 950       // If the current Unicode String Table contains any entries, then copy them to the
 951       // newly allocated Unicode String Table.
 952       //
 953       if (*UnicodeStringTable != NULL) {
 954         CopyMem (
 955            NewUnicodeStringTable,
 956            *UnicodeStringTable,
 957            NumberOfEntries * sizeof (EFI_UNICODE_STRING_TABLE)
 958            );
 959       }
 960
 961       //
 962       // Allocate space for a copy of the Language specifier
 963       //
 964       NewUnicodeStringTable[NumberOfEntries].Language = AllocateCopyPool (3, Language);
 965       if (NewUnicodeStringTable[NumberOfEntries].Language == NULL) {
 966         FreePool (NewUnicodeStringTable);
 967         return EFI_OUT_OF_RESOURCES;
 968       }
 969
 970       //
 971       // Compute the length of the Unicode String
 972       //
 973       for (UnicodeStringLength = 0; UnicodeString[UnicodeStringLength] != 0; UnicodeStringLength++)
 974         ;
 975
 976       //
 977       // Allocate space for a copy of the Unicode String
 978       //
 979       NewUnicodeStringTable[NumberOfEntries].UnicodeString = AllocateCopyPool (
 980                                                               (UnicodeStringLength + 1) * sizeof (CHAR16),
 981                                                               UnicodeString
 982                                                               );
 983       if (NewUnicodeStringTable[NumberOfEntries].UnicodeString == NULL) {
 984         FreePool (NewUnicodeStringTable[NumberOfEntries].Language);
 985         FreePool (NewUnicodeStringTable);
 986         return EFI_OUT_OF_RESOURCES;
 987       }
 988
 989       //
 990       // Mark the end of the Unicode String Table
 991       //
 992       NewUnicodeStringTable[NumberOfEntries + 1].Language       = NULL;
 993       NewUnicodeStringTable[NumberOfEntries + 1].UnicodeString  = NULL;
 994
 995       //
 996       // Free the old Unicode String Table
 997       //
 998       if (*UnicodeStringTable != NULL) {
 999         FreePool (*UnicodeStringTable);
1000       }
1001
1002       //
1003       // Point UnicodeStringTable at the newly allocated Unicode String Table
1004       //
1005       *UnicodeStringTable = NewUnicodeStringTable;
1006
1007       return EFI_SUCCESS;
1008     }
1009
1010     SupportedLanguages += 3;
1011   }
1012
1013   return EFI_UNSUPPORTED;
1014 }
1015
1016
1017 /**
1018   This function adds the Null-terminated Unicode string specified by UnicodeString
1019   to UnicodeStringTable.
1020
1021   If Language is a member of SupportedLanguages then UnicodeString is added to
1022   UnicodeStringTable.  New buffers are allocated for both Language and UnicodeString.
1023   The contents of Language and UnicodeString are copied into these new buffers.
1024   These buffers are automatically freed when EfiLibFreeUnicodeStringTable() is called.
1025
1026   @param  Language            A pointer to an ASCII string containing the ISO 639-2 or
1027                               the RFC 4646 language code for the Unicode string to add.
1028                               If Iso639Language is TRUE, then this ASCII string is not
1029                               assumed to be Null-terminated, and only the first three
1030                               chacters are used. If Iso639Language is FALSE, then this
1031                               ASCII string must be Null-terminated.
1032   @param  SupportedLanguages  A pointer to a Null-terminated ASCII string that contains
1033                               a set of ISO 639-2 or RFC 4646 language codes that the Unicode
1034                               string table supports.  Language must be a member of this set.
1035                               If Iso639Language is TRUE, then this string contains one or more
1036                               ISO 639-2 language codes with no separator characters.
1037                               If Iso639Language is FALSE, then is string contains one or more
1038                               RFC 4646 language codes separated by ';'.
1039   @param  UnicodeStringTable  A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE
1040                               is defined in "Related Definitions".
1041   @param  UnicodeString       A pointer to the Unicode string to add.
1042   @param  Iso639Language      Specifies the supported language code format. If it is TRUE,
1043                               then Language and SupportedLanguages follow ISO 639-2 language code format.
1044                               Otherwise, they follow RFC 4646 language code format.
1045
1046   @retval EFI_SUCCESS            The Unicode string that matches the language specified by
1047                                  Language was found in the table of Unicode strings UnicodeStringTable,
1048                                  and it was returned in UnicodeString.
1049   @retval EFI_INVALID_PARAMETER  Language is NULL.
1050   @retval EFI_INVALID_PARAMETER  UnicodeString is NULL.
1051   @retval EFI_INVALID_PARAMETER  UnicodeString is an empty string.
1052   @retval EFI_UNSUPPORTED        SupportedLanguages is NULL.
1053   @retval EFI_ALREADY_STARTED    A Unicode string with language Language is already present in
1054                                  UnicodeStringTable.
1055   @retval EFI_OUT_OF_RESOURCES   There is not enough memory to add another Unicode string UnicodeStringTable.
1056   @retval EFI_UNSUPPORTED        The language specified by Language is not a member of SupportedLanguages.
1057
1058 **/
1059 EFI_STATUS
1060 EFIAPI
1061 AddUnicodeString2 (
1062   IN     CONST CHAR8               *Language,
1063   IN     CONST CHAR8               *SupportedLanguages,
1064   IN OUT EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,
1065   IN     CONST CHAR16              *UnicodeString,
1066   IN     BOOLEAN                   Iso639Language
1067   )
1068 {
1069   UINTN                     NumberOfEntries;
1070   EFI_UNICODE_STRING_TABLE  *OldUnicodeStringTable;
1071   EFI_UNICODE_STRING_TABLE  *NewUnicodeStringTable;
1072   UINTN                     UnicodeStringLength;
1073   BOOLEAN                   Found;
1074   UINTN                     Index;
1075   CHAR8                     *LanguageString;
1076
1077   //
1078   // Make sure the parameter are valid
1079   //
1080   if (Language == NULL || UnicodeString == NULL || UnicodeStringTable == NULL) {
1081     return EFI_INVALID_PARAMETER;
1082   }
1083
1084   //
1085   // If there are no supported languages, then a Unicode String can not be added
1086   //
1087   if (SupportedLanguages == NULL) {
1088     return EFI_UNSUPPORTED;
1089   }
1090
1091   //
1092   // If the Unicode String is empty, then a Unicode String can not be added
1093   //
1094   if (UnicodeString[0] == 0) {
1095     return EFI_INVALID_PARAMETER;
1096   }
1097
1098   //
1099   // Make sure Language is a member of SupportedLanguages
1100   //
1101   Found = FALSE;
1102   while (*SupportedLanguages != 0) {
1103     if (Iso639Language) {
1104       if (CompareIso639LanguageCode (Language, SupportedLanguages)) {
1105         Found = TRUE;
1106         break;
1107       }
1108       SupportedLanguages += 3;
1109     } else {
1110       for (Index = 0; SupportedLanguages[Index] != 0 && SupportedLanguages[Index] != ';'; Index++);
1111       if (AsciiStrnCmp(SupportedLanguages, Language, Index) == 0) {
1112         Found = TRUE;
1113         break;
1114       }
1115       SupportedLanguages += Index;
1116       for (; *SupportedLanguages != 0 && *SupportedLanguages == ';'; SupportedLanguages++);
1117     }
1118   }
1119
1120   //
1121   // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
1122   //
1123   if (!Found) {
1124     return EFI_UNSUPPORTED;
1125   }
1126
1127   //
1128   // Determine the size of the Unicode String Table by looking for a NULL Language entry
1129   //
1130   NumberOfEntries = 0;
1131   if (*UnicodeStringTable != NULL) {
1132     OldUnicodeStringTable = *UnicodeStringTable;
1133     while (OldUnicodeStringTable->Language != NULL) {
1134       LanguageString = OldUnicodeStringTable->Language;
1135
1136       while (*LanguageString != 0) {
1137         for (Index = 0; LanguageString[Index] != 0 && LanguageString[Index] != ';'; Index++);
1138
1139         if (AsciiStrnCmp (Language, LanguageString, Index) == 0) {
1140           return EFI_ALREADY_STARTED;
1141         }
1142         LanguageString += Index;
1143         for (; *LanguageString != 0 && *LanguageString == ';'; LanguageString++);
1144       }
1145       OldUnicodeStringTable++;
1146       NumberOfEntries++;
1147     }
1148   }
1149
1150   //
1151   // Allocate space for a new Unicode String Table.  It must hold the current number of
1152   // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
1153   // marker
1154   //
1155   NewUnicodeStringTable = AllocatePool ((NumberOfEntries + 2) * sizeof (EFI_UNICODE_STRING_TABLE));
1156   if (NewUnicodeStringTable == NULL) {
1157     return EFI_OUT_OF_RESOURCES;
1158   }
1159
1160   //
1161   // If the current Unicode String Table contains any entries, then copy them to the
1162   // newly allocated Unicode String Table.
1163   //
1164   if (*UnicodeStringTable != NULL) {
1165     CopyMem (
1166       NewUnicodeStringTable,
1167       *UnicodeStringTable,
1168       NumberOfEntries * sizeof (EFI_UNICODE_STRING_TABLE)
1169       );
1170   }
1171
1172   //
1173   // Allocate space for a copy of the Language specifier
1174   //
1175   NewUnicodeStringTable[NumberOfEntries].Language = AllocateCopyPool (AsciiStrSize(Language), Language);
1176   if (NewUnicodeStringTable[NumberOfEntries].Language == NULL) {
1177     FreePool (NewUnicodeStringTable);
1178     return EFI_OUT_OF_RESOURCES;
1179   }
1180
1181   //
1182   // Compute the length of the Unicode String
1183   //
1184   for (UnicodeStringLength = 0; UnicodeString[UnicodeStringLength] != 0; UnicodeStringLength++);
1185
1186   //
1187   // Allocate space for a copy of the Unicode String
1188   //
1189   NewUnicodeStringTable[NumberOfEntries].UnicodeString = AllocateCopyPool (StrSize (UnicodeString), UnicodeString);
1190   if (NewUnicodeStringTable[NumberOfEntries].UnicodeString == NULL) {
1191     FreePool (NewUnicodeStringTable[NumberOfEntries].Language);
1192     FreePool (NewUnicodeStringTable);
1193     return EFI_OUT_OF_RESOURCES;
1194   }
1195
1196   //
1197   // Mark the end of the Unicode String Table
1198   //
1199   NewUnicodeStringTable[NumberOfEntries + 1].Language       = NULL;
1200   NewUnicodeStringTable[NumberOfEntries + 1].UnicodeString  = NULL;
1201
1202   //
1203   // Free the old Unicode String Table
1204   //
1205   if (*UnicodeStringTable != NULL) {
1206     FreePool (*UnicodeStringTable);
1207   }
1208
1209   //
1210   // Point UnicodeStringTable at the newly allocated Unicode String Table
1211   //
1212   *UnicodeStringTable = NewUnicodeStringTable;
1213
1214   return EFI_SUCCESS;
1215 }
1216
1217 /**
1218   This function frees the table of Unicode strings in UnicodeStringTable.
1219
1220   If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
1221   Otherwise, each language code, and each Unicode string in the Unicode string
1222   table are freed, and EFI_SUCCESS is returned.
1223
1224   @param  UnicodeStringTable  A pointer to the table of Unicode strings.
1225
1226   @retval EFI_SUCCESS         The Unicode string table was freed.
1227
1228 **/
1229 EFI_STATUS
1230 EFIAPI
1231 FreeUnicodeStringTable (
1232   IN EFI_UNICODE_STRING_TABLE  *UnicodeStringTable
1233   )
1234 {
1235   UINTN Index;
1236
1237   //
1238   // If the Unicode String Table is NULL, then it is already freed
1239   //
1240   if (UnicodeStringTable == NULL) {
1241     return EFI_SUCCESS;
1242   }
1243
1244   //
1245   // Loop through the Unicode String Table until we reach the end of table marker
1246   //
1247   for (Index = 0; UnicodeStringTable[Index].Language != NULL; Index++) {
1248
1249     //
1250     // Free the Language string from the Unicode String Table
1251     //
1252     FreePool (UnicodeStringTable[Index].Language);
1253
1254     //
1255     // Free the Unicode String from the Unicode String Table
1256     //
1257     if (UnicodeStringTable[Index].UnicodeString != NULL) {
1258       FreePool (UnicodeStringTable[Index].UnicodeString);
1259     }
1260   }
1261
1262   //
1263   // Free the Unicode String Table itself
1264   //
1265   FreePool (UnicodeStringTable);
1266
1267   return EFI_SUCCESS;
1268 }
1269
1270 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1271
1272 /**
1273   [ATTENTION] This function will be deprecated for security reason.
1274
1275   Returns a pointer to an allocated buffer that contains the contents of a
1276   variable retrieved through the UEFI Runtime Service GetVariable().  The
1277   returned buffer is allocated using AllocatePool().  The caller is responsible
1278   for freeing this buffer with FreePool().
1279
1280   If Name is NULL, then ASSERT().
1281   If Guid is NULL, then ASSERT().
1282
1283   @param[in]  Name  The pointer to a Null-terminated Unicode string.
1284   @param[in]  Guid  The pointer to an EFI_GUID structure
1285
1286   @retval NULL   The variable could not be retrieved.
1287   @retval NULL   There are not enough resources available for the variable contents.
1288   @retval Other  A pointer to allocated buffer containing the variable contents.
1289
1290 **/
1291 VOID *
1292 EFIAPI
1293 GetVariable (
1294   IN CONST CHAR16    *Name,
1295   IN CONST EFI_GUID  *Guid
1296   )
1297 {
1298   EFI_STATUS  Status;
1299   UINTN       Size;
1300   VOID        *Value;
1301
1302   ASSERT (Name != NULL);
1303   ASSERT (Guid != NULL);
1304
1305   //
1306   // Try to get the variable size.
1307   //
1308   Value = NULL;
1309   Size = 0;
1310   Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &Size, Value);
1311   if (Status != EFI_BUFFER_TOO_SMALL) {
1312     return NULL;
1313   }
1314
1315   //
1316   // Allocate buffer to get the variable.
1317   //
1318   Value = AllocatePool (Size);
1319   if (Value == NULL) {
1320     return NULL;
1321   }
1322
1323   //
1324   // Get the variable data.
1325   //
1326   Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &Size, Value);
1327   if (EFI_ERROR (Status)) {
1328     FreePool(Value);
1329     return NULL;
1330   }
1331
1332   return Value;
1333 }
1334
1335 /**
1336   [ATTENTION] This function will be deprecated for security reason.
1337
1338   Returns a pointer to an allocated buffer that contains the contents of a
1339   variable retrieved through the UEFI Runtime Service GetVariable().  This
1340   function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1341   The returned buffer is allocated using AllocatePool().  The caller is
1342   responsible for freeing this buffer with FreePool().
1343
1344   If Name is NULL, then ASSERT().
1345
1346   @param[in]  Name  The pointer to a Null-terminated Unicode string.
1347
1348   @retval NULL   The variable could not be retrieved.
1349   @retval NULL   There are not enough resources available for the variable contents.
1350   @retval Other  A pointer to allocated buffer containing the variable contents.
1351
1352 **/
1353 VOID *
1354 EFIAPI
1355 GetEfiGlobalVariable (
1356   IN CONST CHAR16  *Name
1357   )
1358 {
1359   return GetVariable (Name, &gEfiGlobalVariableGuid);
1360 }
1361 #endif
1362
1363 /**
1364   Returns the status whether get the variable success. The function retrieves
1365   variable  through the UEFI Runtime Service GetVariable().  The
1366   returned buffer is allocated using AllocatePool().  The caller is responsible
1367   for freeing this buffer with FreePool().
1368
1369   If Name  is NULL, then ASSERT().
1370   If Guid  is NULL, then ASSERT().
1371   If Value is NULL, then ASSERT().
1372
1373   @param[in]  Name  The pointer to a Null-terminated Unicode string.
1374   @param[in]  Guid  The pointer to an EFI_GUID structure
1375   @param[out] Value The buffer point saved the variable info.
1376   @param[out] Size  The buffer size of the variable.
1377
1378   @return EFI_OUT_OF_RESOURCES      Allocate buffer failed.
1379   @return EFI_SUCCESS               Find the specified variable.
1380   @return Others Errors             Return errors from call to gRT->GetVariable.
1381
1382 **/
1383 EFI_STATUS
1384 EFIAPI
1385 GetVariable2 (
1386   IN CONST CHAR16    *Name,
1387   IN CONST EFI_GUID  *Guid,
1388   OUT VOID           **Value,
1389   OUT UINTN          *Size OPTIONAL
1390   )
1391 {
1392   EFI_STATUS  Status;
1393   UINTN       BufferSize;
1394
1395   ASSERT (Name != NULL && Guid != NULL && Value != NULL);
1396
1397   //
1398   // Try to get the variable size.
1399   //
1400   BufferSize = 0;
1401   *Value     = NULL;
1402   if (Size != NULL) {
1403     *Size  = 0;
1404   }
1405
1406   Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &BufferSize, *Value);
1407   if (Status != EFI_BUFFER_TOO_SMALL) {
1408     return Status;
1409   }
1410
1411   //
1412   // Allocate buffer to get the variable.
1413   //
1414   *Value = AllocatePool (BufferSize);
1415   ASSERT (*Value != NULL);
1416   if (*Value == NULL) {
1417     return EFI_OUT_OF_RESOURCES;
1418   }
1419
1420   //
1421   // Get the variable data.
1422   //
1423   Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &BufferSize, *Value);
1424   if (EFI_ERROR (Status)) {
1425     FreePool(*Value);
1426     *Value = NULL;
1427   }
1428
1429   if (Size != NULL) {
1430     *Size = BufferSize;
1431   }
1432
1433   return Status;
1434 }
1435
1436 /** Return the attributes of the variable.
1437
1438   Returns the status whether get the variable success. The function retrieves
1439   variable  through the UEFI Runtime Service GetVariable().  The
1440   returned buffer is allocated using AllocatePool().  The caller is responsible
1441   for freeing this buffer with FreePool().  The attributes are returned if
1442   the caller provides a valid Attribute parameter.
1443
1444   If Name  is NULL, then ASSERT().
1445   If Guid  is NULL, then ASSERT().
1446   If Value is NULL, then ASSERT().
1447
1448   @param[in]  Name  The pointer to a Null-terminated Unicode string.
1449   @param[in]  Guid  The pointer to an EFI_GUID structure
1450   @param[out] Value The buffer point saved the variable info.
1451   @param[out] Size  The buffer size of the variable.
1452   @param[out] Attr  The pointer to the variable attributes as found in var store
1453
1454   @retval EFI_OUT_OF_RESOURCES      Allocate buffer failed.
1455   @retval EFI_SUCCESS               Find the specified variable.
1456   @retval Others Errors             Return errors from call to gRT->GetVariable.
1457
1458 **/
1459 EFI_STATUS
1460 EFIAPI
1461 GetVariable3(
1462   IN CONST CHAR16       *Name,
1463   IN CONST EFI_GUID     *Guid,
1464      OUT VOID           **Value,
1465      OUT UINTN          *Size OPTIONAL,
1466      OUT UINT32         *Attr OPTIONAL
1467   )
1468 {
1469   EFI_STATUS  Status;
1470   UINTN       BufferSize;
1471
1472   ASSERT(Name != NULL && Guid != NULL && Value != NULL);
1473
1474   //
1475   // Try to get the variable size.
1476   //
1477   BufferSize = 0;
1478   *Value = NULL;
1479   if (Size != NULL) {
1480     *Size = 0;
1481   }
1482
1483   if (Attr != NULL) {
1484     *Attr = 0;
1485   }
1486
1487   Status = gRT->GetVariable((CHAR16 *)Name, (EFI_GUID *)Guid, Attr, &BufferSize, *Value);
1488   if (Status != EFI_BUFFER_TOO_SMALL) {
1489     return Status;
1490   }
1491
1492   //
1493   // Allocate buffer to get the variable.
1494   //
1495   *Value = AllocatePool(BufferSize);
1496   ASSERT(*Value != NULL);
1497   if (*Value == NULL) {
1498     return EFI_OUT_OF_RESOURCES;
1499   }
1500
1501   //
1502   // Get the variable data.
1503   //
1504   Status = gRT->GetVariable((CHAR16 *)Name, (EFI_GUID *)Guid, Attr, &BufferSize, *Value);
1505   if (EFI_ERROR(Status)) {
1506     FreePool(*Value);
1507     *Value = NULL;
1508   }
1509
1510   if (Size != NULL) {
1511     *Size = BufferSize;
1512   }
1513
1514   return Status;
1515 }
1516
1517 /**
1518   Returns a pointer to an allocated buffer that contains the contents of a
1519   variable retrieved through the UEFI Runtime Service GetVariable().  This
1520   function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.
1521   The returned buffer is allocated using AllocatePool().  The caller is
1522   responsible for freeing this buffer with FreePool().
1523
1524   If Name is NULL, then ASSERT().
1525   If Value is NULL, then ASSERT().
1526
1527   @param[in]  Name  The pointer to a Null-terminated Unicode string.
1528   @param[out] Value The buffer point saved the variable info.
1529   @param[out] Size  The buffer size of the variable.
1530
1531   @return EFI_OUT_OF_RESOURCES      Allocate buffer failed.
1532   @return EFI_SUCCESS               Find the specified variable.
1533   @return Others Errors             Return errors from call to gRT->GetVariable.
1534
1535 **/
1536 EFI_STATUS
1537 EFIAPI
1538 GetEfiGlobalVariable2 (
1539   IN CONST CHAR16    *Name,
1540   OUT VOID           **Value,
1541   OUT UINTN          *Size OPTIONAL
1542   )
1543 {
1544   return GetVariable2 (Name, &gEfiGlobalVariableGuid, Value, Size);
1545 }
1546
1547 /**
1548   Returns a pointer to an allocated buffer that contains the best matching language
1549   from a set of supported languages.
1550
1551   This function supports both ISO 639-2 and RFC 4646 language codes, but language
1552   code types may not be mixed in a single call to this function.  The language
1553   code returned is allocated using AllocatePool().  The caller is responsible for
1554   freeing the allocated buffer using FreePool().  This function supports a variable
1555   argument list that allows the caller to pass in a prioritized list of language
1556   codes to test against all the language codes in SupportedLanguages.
1557
1558   If SupportedLanguages is NULL, then ASSERT().
1559
1560   @param[in]  SupportedLanguages  A pointer to a Null-terminated ASCII string that
1561                                   contains a set of language codes in the format
1562                                   specified by Iso639Language.
1563   @param[in]  Iso639Language      If not zero, then all language codes are assumed to be
1564                                   in ISO 639-2 format.  If zero, then all language
1565                                   codes are assumed to be in RFC 4646 language format
1566   @param[in]  ...                 A variable argument list that contains pointers to
1567                                   Null-terminated ASCII strings that contain one or more
1568                                   language codes in the format specified by Iso639Language.
1569                                   The first language code from each of these language
1570                                   code lists is used to determine if it is an exact or
1571                                   close match to any of the language codes in
1572                                   SupportedLanguages.  Close matches only apply to RFC 4646
1573                                   language codes, and the matching algorithm from RFC 4647
1574                                   is used to determine if a close match is present.  If
1575                                   an exact or close match is found, then the matching
1576                                   language code from SupportedLanguages is returned.  If
1577                                   no matches are found, then the next variable argument
1578                                   parameter is evaluated.  The variable argument list
1579                                   is terminated by a NULL.
1580
1581   @retval NULL   The best matching language could not be found in SupportedLanguages.
1582   @retval NULL   There are not enough resources available to return the best matching
1583                  language.
1584   @retval Other  A pointer to a Null-terminated ASCII string that is the best matching
1585                  language in SupportedLanguages.
1586
1587 **/
1588 CHAR8 *
1589 EFIAPI
1590 GetBestLanguage (
1591   IN CONST CHAR8  *SupportedLanguages,
1592   IN UINTN        Iso639Language,
1593   ...
1594   )
1595 {
1596   VA_LIST      Args;
1597   CHAR8        *Language;
1598   UINTN        CompareLength;
1599   UINTN        LanguageLength;
1600   CONST CHAR8  *Supported;
1601   CHAR8        *BestLanguage;
1602
1603   ASSERT (SupportedLanguages != NULL);
1604
1605   VA_START (Args, Iso639Language);
1606   while ((Language = VA_ARG (Args, CHAR8 *)) != NULL) {
1607     //
1608     // Default to ISO 639-2 mode
1609     //
1610     CompareLength  = 3;
1611     LanguageLength = MIN (3, AsciiStrLen (Language));
1612
1613     //
1614     // If in RFC 4646 mode, then determine the length of the first RFC 4646 language code in Language
1615     //
1616     if (Iso639Language == 0) {
1617       for (LanguageLength = 0; Language[LanguageLength] != 0 && Language[LanguageLength] != ';'; LanguageLength++);
1618     }
1619
1620     //
1621     // Trim back the length of Language used until it is empty
1622     //
1623     while (LanguageLength > 0) {
1624       //
1625       // Loop through all language codes in SupportedLanguages
1626       //
1627       for (Supported = SupportedLanguages; *Supported != '\0'; Supported += CompareLength) {
1628         //
1629         // In RFC 4646 mode, then Loop through all language codes in SupportedLanguages
1630         //
1631         if (Iso639Language == 0) {
1632           //
1633           // Skip ';' characters in Supported
1634           //
1635           for (; *Supported != '\0' && *Supported == ';'; Supported++);
1636           //
1637           // Determine the length of the next language code in Supported
1638           //
1639           for (CompareLength = 0; Supported[CompareLength] != 0 && Supported[CompareLength] != ';'; CompareLength++);
1640           //
1641           // If Language is longer than the Supported, then skip to the next language
1642           //
1643           if (LanguageLength > CompareLength) {
1644             continue;
1645           }
1646         }
1647         //
1648         // See if the first LanguageLength characters in Supported match Language
1649         //
1650         if (AsciiStrnCmp (Supported, Language, LanguageLength) == 0) {
1651           VA_END (Args);
1652           //
1653           // Allocate, copy, and return the best matching language code from SupportedLanguages
1654           //
1655           BestLanguage = AllocateZeroPool (CompareLength + 1);
1656           if (BestLanguage == NULL) {
1657             return NULL;
1658           }
1659           return CopyMem (BestLanguage, Supported, CompareLength);
1660         }
1661       }
1662
1663       if (Iso639Language != 0) {
1664         //
1665         // If ISO 639 mode, then each language can only be tested once
1666         //
1667         LanguageLength = 0;
1668       } else {
1669         //
1670         // If RFC 4646 mode, then trim Language from the right to the next '-' character
1671         //
1672         for (LanguageLength--; LanguageLength > 0 && Language[LanguageLength] != '-'; LanguageLength--);
1673       }
1674     }
1675   }
1676   VA_END (Args);
1677
1678   //
1679   // No matches were found
1680   //
1681   return NULL;
1682 }
1683
1684 /**
1685   Returns an array of protocol instance that matches the given protocol.
1686
1687   @param[in]  Protocol      Provides the protocol to search for.
1688   @param[out] NoProtocols   The number of protocols returned in Buffer.
1689   @param[out] Buffer        A pointer to the buffer to return the requested
1690                             array of protocol instances that match Protocol.
1691                             The returned buffer is allocated using
1692                             EFI_BOOT_SERVICES.AllocatePool().  The caller is
1693                             responsible for freeing this buffer with
1694                             EFI_BOOT_SERVICES.FreePool().
1695
1696   @retval EFI_SUCCESS            The array of protocols was returned in Buffer,
1697                                  and the number of protocols in Buffer was
1698                                  returned in NoProtocols.
1699   @retval EFI_NOT_FOUND          No protocols found.
1700   @retval EFI_OUT_OF_RESOURCES   There is not enough pool memory to store the
1701                                  matching results.
1702   @retval EFI_INVALID_PARAMETER  Protocol is NULL.
1703   @retval EFI_INVALID_PARAMETER  NoProtocols is NULL.
1704   @retval EFI_INVALID_PARAMETER  Buffer is NULL.
1705
1706 **/
1707 EFI_STATUS
1708 EFIAPI
1709 EfiLocateProtocolBuffer (
1710   IN  EFI_GUID  *Protocol,
1711   OUT UINTN     *NoProtocols,
1712   OUT VOID      ***Buffer
1713   )
1714 {
1715   EFI_STATUS  Status;
1716   UINTN       NoHandles;
1717   EFI_HANDLE  *HandleBuffer;
1718   UINTN       Index;
1719
1720   //
1721   // Check input parameters
1722   //
1723   if (Protocol == NULL || NoProtocols == NULL || Buffer == NULL) {
1724     return EFI_INVALID_PARAMETER;
1725   }
1726
1727   //
1728   // Initialze output parameters
1729   //
1730   *NoProtocols = 0;
1731   *Buffer = NULL;
1732
1733   //
1734   // Retrieve the array of handles that support Protocol
1735   //
1736   Status = gBS->LocateHandleBuffer (
1737                   ByProtocol,
1738                   Protocol,
1739                   NULL,
1740                   &NoHandles,
1741                   &HandleBuffer
1742                   );
1743   if (EFI_ERROR (Status)) {
1744     return Status;
1745   }
1746
1747   //
1748   // Allocate array of protocol instances
1749   //
1750   Status = gBS->AllocatePool (
1751                   EfiBootServicesData,
1752                   NoHandles * sizeof (VOID *),
1753                   (VOID **)Buffer
1754                   );
1755   if (EFI_ERROR (Status)) {
1756     //
1757     // Free the handle buffer
1758     //
1759     gBS->FreePool (HandleBuffer);
1760     return EFI_OUT_OF_RESOURCES;
1761   }
1762   ZeroMem (*Buffer, NoHandles * sizeof (VOID *));
1763
1764   //
1765   // Lookup Protocol on each handle in HandleBuffer to fill in the array of
1766   // protocol instances.  Handle case where protocol instance was present when
1767   // LocateHandleBuffer() was called, but is not present when HandleProtocol()
1768   // is called.
1769   //
1770   for (Index = 0, *NoProtocols = 0; Index < NoHandles; Index++) {
1771     Status = gBS->HandleProtocol (
1772                     HandleBuffer[Index],
1773                     Protocol,
1774                     &((*Buffer)[*NoProtocols])
1775                     );
1776     if (!EFI_ERROR (Status)) {
1777       (*NoProtocols)++;
1778     }
1779   }
1780
1781   //
1782   // Free the handle buffer
1783   //
1784   gBS->FreePool (HandleBuffer);
1785
1786   //
1787   // Make sure at least one protocol instance was found
1788   //
1789   if (*NoProtocols == 0) {
1790     gBS->FreePool (*Buffer);
1791     *Buffer = NULL;
1792     return EFI_NOT_FOUND;
1793   }
1794
1795   return EFI_SUCCESS;
1796 }
1797
1798 /**
1799   Open or create a file or directory, possibly creating the chain of
1800   directories leading up to the directory.
1801
1802   EfiOpenFileByDevicePath() first locates EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on
1803   FilePath, and opens the root directory of that filesystem with
1804   EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume().
1805
1806   On the remaining device path, the longest initial sequence of
1807   FILEPATH_DEVICE_PATH nodes is node-wise traversed with
1808   EFI_FILE_PROTOCOL.Open().
1809
1810   (As a consequence, if OpenMode includes EFI_FILE_MODE_CREATE, and Attributes
1811   includes EFI_FILE_DIRECTORY, and each FILEPATH_DEVICE_PATH specifies a single
1812   pathname component, then EfiOpenFileByDevicePath() ensures that the specified
1813   series of subdirectories exist on return.)
1814
1815   The EFI_FILE_PROTOCOL identified by the last FILEPATH_DEVICE_PATH node is
1816   output to the caller; intermediate EFI_FILE_PROTOCOL instances are closed. If
1817   there are no FILEPATH_DEVICE_PATH nodes past the node that identifies the
1818   filesystem, then the EFI_FILE_PROTOCOL of the root directory of the
1819   filesystem is output to the caller. If a device path node that is different
1820   from FILEPATH_DEVICE_PATH is encountered relative to the filesystem, the
1821   traversal is stopped with an error, and a NULL EFI_FILE_PROTOCOL is output.
1822
1823   @param[in,out] FilePath  On input, the device path to the file or directory
1824                            to open or create. The caller is responsible for
1825                            ensuring that the device path pointed-to by FilePath
1826                            is well-formed. On output, FilePath points one past
1827                            the last node in the original device path that has
1828                            been successfully processed. FilePath is set on
1829                            output even if EfiOpenFileByDevicePath() returns an
1830                            error.
1831
1832   @param[out] File         On error, File is set to NULL. On success, File is
1833                            set to the EFI_FILE_PROTOCOL of the root directory
1834                            of the filesystem, if there are no
1835                            FILEPATH_DEVICE_PATH nodes in FilePath; otherwise,
1836                            File is set to the EFI_FILE_PROTOCOL identified by
1837                            the last node in FilePath.
1838
1839   @param[in] OpenMode      The OpenMode parameter to pass to
1840                            EFI_FILE_PROTOCOL.Open().
1841
1842   @param[in] Attributes    The Attributes parameter to pass to
1843                            EFI_FILE_PROTOCOL.Open().
1844
1845   @retval EFI_SUCCESS            The file or directory has been opened or
1846                                  created.
1847
1848   @retval EFI_INVALID_PARAMETER  FilePath is NULL; or File is NULL; or FilePath
1849                                  contains a device path node, past the node
1850                                  that identifies
1851                                  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL, that is not a
1852                                  FILEPATH_DEVICE_PATH node.
1853
1854   @retval EFI_OUT_OF_RESOURCES   Memory allocation failed.
1855
1856   @return                        Error codes propagated from the
1857                                  LocateDevicePath() and OpenProtocol() boot
1858                                  services, and from the
1859                                  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume()
1860                                  and EFI_FILE_PROTOCOL.Open() member functions.
1861 **/
1862 EFI_STATUS
1863 EFIAPI
1864 EfiOpenFileByDevicePath (
1865   IN OUT EFI_DEVICE_PATH_PROTOCOL  **FilePath,
1866   OUT    EFI_FILE_PROTOCOL         **File,
1867   IN     UINT64                    OpenMode,
1868   IN     UINT64                    Attributes
1869   )
1870 {
1871   EFI_STATUS                      Status;
1872   EFI_HANDLE                      FileSystemHandle;
1873   EFI_SIMPLE_FILE_SYSTEM_PROTOCOL *FileSystem;
1874   EFI_FILE_PROTOCOL               *LastFile;
1875   FILEPATH_DEVICE_PATH            *FilePathNode;
1876   CHAR16                          *AlignedPathName;
1877   CHAR16                          *PathName;
1878   EFI_FILE_PROTOCOL               *NextFile;
1879
1880   if (File == NULL) {
1881     return EFI_INVALID_PARAMETER;
1882   }
1883   *File = NULL;
1884
1885   if (FilePath == NULL) {
1886     return EFI_INVALID_PARAMETER;
1887   }
1888
1889   //
1890   // Look up the filesystem.
1891   //
1892   Status = gBS->LocateDevicePath (
1893                   &gEfiSimpleFileSystemProtocolGuid,
1894                   FilePath,
1895                   &FileSystemHandle
1896                   );
1897   if (EFI_ERROR (Status)) {
1898     return Status;
1899   }
1900   Status = gBS->OpenProtocol (
1901                   FileSystemHandle,
1902                   &gEfiSimpleFileSystemProtocolGuid,
1903                   (VOID **)&FileSystem,
1904                   gImageHandle,
1905                   NULL,
1906                   EFI_OPEN_PROTOCOL_GET_PROTOCOL
1907                   );
1908   if (EFI_ERROR (Status)) {
1909     return Status;
1910   }
1911
1912   //
1913   // Open the root directory of the filesystem. After this operation succeeds,
1914   // we have to release LastFile on error.
1915   //
1916   Status = FileSystem->OpenVolume (FileSystem, &LastFile);
1917   if (EFI_ERROR (Status)) {
1918     return Status;
1919   }
1920
1921   //
1922   // Traverse the device path nodes relative to the filesystem.
1923   //
1924   while (!IsDevicePathEnd (*FilePath)) {
1925     if (DevicePathType (*FilePath) != MEDIA_DEVICE_PATH ||
1926         DevicePathSubType (*FilePath) != MEDIA_FILEPATH_DP) {
1927       Status = EFI_INVALID_PARAMETER;
1928       goto CloseLastFile;
1929     }
1930     FilePathNode = (FILEPATH_DEVICE_PATH *)*FilePath;
1931
1932     //
1933     // FilePathNode->PathName may be unaligned, and the UEFI specification
1934     // requires pointers that are passed to protocol member functions to be
1935     // aligned. Create an aligned copy of the pathname if necessary.
1936     //
1937     if ((UINTN)FilePathNode->PathName % sizeof *FilePathNode->PathName == 0) {
1938       AlignedPathName = NULL;
1939       PathName = FilePathNode->PathName;
1940     } else {
1941       AlignedPathName = AllocateCopyPool (
1942                           (DevicePathNodeLength (FilePathNode) -
1943                            SIZE_OF_FILEPATH_DEVICE_PATH),
1944                           FilePathNode->PathName
1945                           );
1946       if (AlignedPathName == NULL) {
1947         Status = EFI_OUT_OF_RESOURCES;
1948         goto CloseLastFile;
1949       }
1950       PathName = AlignedPathName;
1951     }
1952
1953     //
1954     // Open or create the file corresponding to the next pathname fragment.
1955     //
1956     Status = LastFile->Open (
1957                          LastFile,
1958                          &NextFile,
1959                          PathName,
1960                          OpenMode,
1961                          Attributes
1962                          );
1963
1964     //
1965     // Release any AlignedPathName on both error and success paths; PathName is
1966     // no longer needed.
1967     //
1968     if (AlignedPathName != NULL) {
1969       FreePool (AlignedPathName);
1970     }
1971     if (EFI_ERROR (Status)) {
1972       goto CloseLastFile;
1973     }
1974
1975     //
1976     // Advance to the next device path node.
1977     //
1978     LastFile->Close (LastFile);
1979     LastFile = NextFile;
1980     *FilePath = NextDevicePathNode (FilePathNode);
1981   }
1982
1983   *File = LastFile;
1984   return EFI_SUCCESS;
1985
1986 CloseLastFile:
1987   LastFile->Close (LastFile);
1988
1989   //
1990   // We are on the error path; we must have set an error Status for returning
1991   // to the caller.
1992   //
1993   ASSERT (EFI_ERROR (Status));
1994   return Status;
1995 }