MdePkg/Library/DxeServicesLib/DxeServicesLib.c

   1 /** @file
   2   MDE DXE Services Library provides functions that simplify the development of DXE Drivers.
   3   These functions help access data from sections of FFS files or from file path.
   4
   5   Copyright (c) 2007 - 2012, Intel Corporation. All rights reserved.<BR>
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php.
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #include <PiDxe.h>
  17 #include <Library/DebugLib.h>
  18 #include <Library/MemoryAllocationLib.h>
  19 #include <Library/UefiBootServicesTableLib.h>
  20 #include <Library/DevicePathLib.h>
  21 #include <Library/UefiLib.h>
  22 #include <Library/DxeServicesLib.h>
  23 #include <Protocol/FirmwareVolume2.h>
  24 #include <Protocol/LoadedImage.h>
  25 #include <Protocol/LoadFile2.h>
  26 #include <Protocol/LoadFile.h>
  27 #include <Protocol/SimpleFileSystem.h>
  28 #include <Guid/FileInfo.h>
  29
  30 /**
  31   Identify the device handle from which the Image is loaded from. As this device handle is passed to
  32   GetSectionFromFv as the identifier for a Firmware Volume, an EFI_FIRMWARE_VOLUME2_PROTOCOL
  33   protocol instance should be located succesfully by calling gBS->HandleProtocol ().
  34
  35   This function locates the EFI_LOADED_IMAGE_PROTOCOL instance installed
  36   on ImageHandle. It then returns EFI_LOADED_IMAGE_PROTOCOL.DeviceHandle.
  37
  38   If ImageHandle is NULL, then ASSERT ();
  39   If failed to locate a EFI_LOADED_IMAGE_PROTOCOL on ImageHandle, then ASSERT ();
  40
  41   @param  ImageHandle         The firmware allocated handle for UEFI image.
  42
  43   @retval  EFI_HANDLE         The device handle from which the Image is loaded from.
  44
  45 **/
  46 EFI_HANDLE
  47 InternalImageHandleToFvHandle (
  48   EFI_HANDLE ImageHandle
  49   )
  50 {
  51   EFI_STATUS                    Status;
  52   EFI_LOADED_IMAGE_PROTOCOL     *LoadedImage;
  53
  54   ASSERT (ImageHandle != NULL);
  55
  56   Status = gBS->HandleProtocol (
  57              (EFI_HANDLE *) ImageHandle,
  58              &gEfiLoadedImageProtocolGuid,
  59              (VOID **) &LoadedImage
  60              );
  61
  62   ASSERT_EFI_ERROR (Status);
  63
  64   return LoadedImage->DeviceHandle;
  65
  66 }
  67
  68 /**
  69   Allocate and fill a buffer from a Firmware Section identified by a Firmware File GUID name, a Firmware
  70   Section type and instance number from the specified Firmware Volume.
  71
  72   This functions first locate the EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance on FvHandle in order to
  73   carry out the Firmware Volume read operation. The function then reads the Firmware Section found sepcifed
  74   by NameGuid, SectionType and SectionInstance.
  75
  76   The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
  77   found in PI Specification.
  78
  79   If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
  80   is not found, EFI_SECTION_PE32 will be used to try the search again. If no EFI_SECTION_PE32 section is found, EFI_NOT_FOUND
  81   is returned.
  82
  83   The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
  84   by this function. This function can be only called at TPL_NOTIFY and below.
  85
  86   If FvHandle is NULL, then ASSERT ();
  87   If NameGuid is NULL, then ASSERT();
  88   If Buffer is NULL, then ASSERT();
  89   If Size is NULL, then ASSERT().
  90
  91   @param  FvHandle                The device handle that contains a instance of
  92                                   EFI_FIRMWARE_VOLUME2_PROTOCOL instance.
  93   @param  NameGuid                The GUID name of a Firmware File.
  94   @param  SectionType             The Firmware Section type.
  95   @param  SectionInstance         The instance number of Firmware Section to
  96                                   read from starting from 0.
  97   @param  Buffer                  On output, Buffer contains the the data read
  98                                   from the section in the Firmware File found.
  99   @param  Size                    On output, the size of Buffer.
 100
 101   @retval  EFI_SUCCESS            The image is found and data and size is returned.
 102   @retval  EFI_NOT_FOUND          The image specified by NameGuid and SectionType
 103                                   can't be found.
 104   @retval  EFI_OUT_OF_RESOURCES   There were not enough resources to allocate the
 105                                   output data buffer or complete the operations.
 106   @retval  EFI_DEVICE_ERROR       A hardware error occurs during reading from the
 107                                   Firmware Volume.
 108   @retval  EFI_ACCESS_DENIED      The firmware volume containing the searched
 109                                   Firmware File is configured to disallow reads.
 110
 111 **/
 112 EFI_STATUS
 113 InternalGetSectionFromFv (
 114   IN  EFI_HANDLE                    FvHandle,
 115   IN  CONST EFI_GUID                *NameGuid,
 116   IN  EFI_SECTION_TYPE              SectionType,
 117   IN  UINTN                         SectionInstance,
 118   OUT VOID                          **Buffer,
 119   OUT UINTN                         *Size
 120   )
 121 {
 122   EFI_STATUS                    Status;
 123   EFI_FIRMWARE_VOLUME2_PROTOCOL *Fv;
 124   UINT32                        AuthenticationStatus;
 125
 126   ASSERT (NameGuid != NULL);
 127   ASSERT (Buffer != NULL);
 128   ASSERT (Size != NULL);
 129
 130   ASSERT (FvHandle != NULL);
 131
 132   Status = gBS->HandleProtocol (
 133                   FvHandle,
 134                   &gEfiFirmwareVolume2ProtocolGuid,
 135                   (VOID **) &Fv
 136                   );
 137   if (EFI_ERROR (Status)) {
 138     return EFI_NOT_FOUND;
 139   }
 140
 141   //
 142   // Read desired section content in NameGuid file
 143   //
 144   *Buffer     = NULL;
 145   *Size       = 0;
 146   Status      = Fv->ReadSection (
 147                       Fv,
 148                       NameGuid,
 149                       SectionType,
 150                       SectionInstance,
 151                       Buffer,
 152                       Size,
 153                       &AuthenticationStatus
 154                       );
 155
 156   if (EFI_ERROR (Status) && (SectionType == EFI_SECTION_TE)) {
 157     //
 158     // Try reading PE32 section, if the required section is TE type
 159     //
 160     *Buffer = NULL;
 161     *Size   = 0;
 162     Status  = Fv->ReadSection (
 163                     Fv,
 164                     NameGuid,
 165                     EFI_SECTION_PE32,
 166                     SectionInstance,
 167                     Buffer,
 168                     Size,
 169                     &AuthenticationStatus
 170                     );
 171   }
 172
 173   return Status;
 174 }
 175
 176 /**
 177   Searches all the available firmware volumes and returns the first matching FFS section.
 178
 179   This function searches all the firmware volumes for FFS files with FV file type specified by FileType
 180   The order that the firmware volumes is searched is not deterministic. For each available FV a search
 181   is made for FFS file of type FileType. If the FV contains more than one FFS file with the same FileType,
 182   the FileInstance instance will be the matched FFS file. For each FFS file found a search
 183   is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance instances
 184   of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer.
 185   Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size.
 186   It is the caller's responsibility to use FreePool() to free the allocated buffer.
 187   See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections
 188   are retrieved from an FFS file based on SectionType and SectionInstance.
 189
 190   If SectionType is EFI_SECTION_TE, and the search with an FFS file fails,
 191   the search will be retried with a section type of EFI_SECTION_PE32.
 192   This function must be called with a TPL <= TPL_NOTIFY.
 193
 194   If Buffer is NULL, then ASSERT().
 195   If Size is NULL, then ASSERT().
 196
 197   @param  FileType             Indicates the FV file type to search for within all
 198                                available FVs.
 199   @param  FileInstance         Indicates which file instance within all available
 200                                FVs specified by FileType.
 201                                FileInstance starts from zero.
 202   @param  SectionType          Indicates the FFS section type to search for
 203                                within the FFS file
 204                                specified by FileType with FileInstance.
 205   @param  SectionInstance      Indicates which section instance within the FFS file
 206                                specified by FileType with FileInstance to retrieve.
 207                                SectionInstance starts from zero.
 208   @param  Buffer               On output, a pointer to a callee allocated buffer
 209                                containing the FFS file section that was found.
 210                                Is it the caller's responsibility to free this
 211                                buffer using FreePool().
 212   @param  Size                 On output, a pointer to the size, in bytes, of Buffer.
 213
 214   @retval  EFI_SUCCESS          The specified FFS section was returned.
 215   @retval  EFI_NOT_FOUND        The specified FFS section could not be found.
 216   @retval  EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve
 217                                 the matching FFS section.
 218   @retval  EFI_DEVICE_ERROR     The FFS section could not be retrieves due to a
 219                                 device error.
 220   @retval  EFI_ACCESS_DENIED    The FFS section could not be retrieves because
 221                                 the firmware volume that
 222                                 contains the matching FFS section does not allow reads.
 223 **/
 224 EFI_STATUS
 225 EFIAPI
 226 GetSectionFromAnyFvByFileType  (
 227   IN  EFI_FV_FILETYPE               FileType,
 228   IN  UINTN                         FileInstance,
 229   IN  EFI_SECTION_TYPE              SectionType,
 230   IN  UINTN                         SectionInstance,
 231   OUT VOID                          **Buffer,
 232   OUT UINTN                         *Size
 233   )
 234 {
 235   EFI_STATUS                    Status;
 236   EFI_HANDLE                    *HandleBuffer;
 237   UINTN                         HandleCount;
 238   UINTN                         IndexFv;
 239   UINTN                         IndexFile;
 240   UINTN                         Key;
 241   EFI_GUID                      NameGuid;
 242   EFI_FV_FILE_ATTRIBUTES        Attributes;
 243   EFI_FIRMWARE_VOLUME2_PROTOCOL *Fv;
 244
 245   //
 246   // Locate all available FVs.
 247   //
 248   HandleBuffer = NULL;
 249   Status = gBS->LocateHandleBuffer (
 250                   ByProtocol,
 251                   &gEfiFirmwareVolume2ProtocolGuid,
 252                   NULL,
 253                   &HandleCount,
 254                   &HandleBuffer
 255                   );
 256   if (EFI_ERROR (Status)) {
 257     return Status;
 258   }
 259
 260   //
 261   // Go through FVs one by one to find the required section data.
 262   //
 263   for (IndexFv = 0; IndexFv < HandleCount; IndexFv++) {
 264     Status = gBS->HandleProtocol (
 265                     HandleBuffer[IndexFv],
 266                     &gEfiFirmwareVolume2ProtocolGuid,
 267                     (VOID **)&Fv
 268                     );
 269     if (EFI_ERROR (Status)) {
 270       continue;
 271     }
 272
 273     //
 274     // Use Firmware Volume 2 Protocol to search for a file of type FileType in all FVs.
 275     //
 276     IndexFile = FileInstance + 1;
 277     Key = 0;
 278     do {
 279       Status = Fv->GetNextFile (Fv, &Key, &FileType, &NameGuid, &Attributes, Size);
 280       if (EFI_ERROR (Status)) {
 281         break;
 282       }
 283       IndexFile --;
 284     } while (IndexFile > 0);
 285
 286     //
 287     // Fv File with the required FV file type is found.
 288     // Search the section file in the found FV file.
 289     //
 290     if (IndexFile == 0) {
 291       Status = InternalGetSectionFromFv (
 292                  HandleBuffer[IndexFv],
 293                  &NameGuid,
 294                  SectionType,
 295                  SectionInstance,
 296                  Buffer,
 297                  Size
 298                  );
 299
 300       if (!EFI_ERROR (Status)) {
 301         goto Done;
 302       }
 303     }
 304   }
 305
 306   //
 307   // The required FFS section file is not found.
 308   //
 309   if (IndexFv == HandleCount) {
 310     Status = EFI_NOT_FOUND;
 311   }
 312
 313 Done:
 314   if (HandleBuffer != NULL) {
 315     FreePool(HandleBuffer);
 316   }
 317
 318   return Status;
 319 }
 320
 321 /**
 322   Searches all the availables firmware volumes and returns the first matching FFS section.
 323
 324   This function searches all the firmware volumes for FFS files with an FFS filename specified by NameGuid.
 325   The order that the firmware volumes is searched is not deterministic. For each FFS file found a search
 326   is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance instances
 327   of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer.
 328   Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size.
 329   It is the caller's responsibility to use FreePool() to free the allocated buffer.
 330   See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections
 331   are retrieved from an FFS file based on SectionType and SectionInstance.
 332
 333   If SectionType is EFI_SECTION_TE, and the search with an FFS file fails,
 334   the search will be retried with a section type of EFI_SECTION_PE32.
 335   This function must be called with a TPL <= TPL_NOTIFY.
 336
 337   If NameGuid is NULL, then ASSERT().
 338   If Buffer is NULL, then ASSERT().
 339   If Size is NULL, then ASSERT().
 340
 341
 342   @param  NameGuid             A pointer to to the FFS filename GUID to search for
 343                                within any of the firmware volumes in the platform.
 344   @param  SectionType          Indicates the FFS section type to search for within
 345                                the FFS file specified by NameGuid.
 346   @param  SectionInstance      Indicates which section instance within the FFS file
 347                                specified by NameGuid to retrieve.
 348   @param  Buffer               On output, a pointer to a callee allocated buffer
 349                                containing the FFS file section that was found.
 350                                Is it the caller's responsibility to free this buffer
 351                                using FreePool().
 352   @param  Size                 On output, a pointer to the size, in bytes, of Buffer.
 353
 354   @retval  EFI_SUCCESS          The specified FFS section was returned.
 355   @retval  EFI_NOT_FOUND        The specified FFS section could not be found.
 356   @retval  EFI_OUT_OF_RESOURCES There are not enough resources available to
 357                                 retrieve the matching FFS section.
 358   @retval  EFI_DEVICE_ERROR     The FFS section could not be retrieves due to a
 359                                 device error.
 360   @retval  EFI_ACCESS_DENIED    The FFS section could not be retrieves because the
 361                                 firmware volume that
 362                                 contains the matching FFS section does not allow reads.
 363 **/
 364 EFI_STATUS
 365 EFIAPI
 366 GetSectionFromAnyFv  (
 367   IN CONST  EFI_GUID           *NameGuid,
 368   IN        EFI_SECTION_TYPE   SectionType,
 369   IN        UINTN              SectionInstance,
 370   OUT       VOID               **Buffer,
 371   OUT       UINTN              *Size
 372   )
 373 {
 374   EFI_STATUS                    Status;
 375   EFI_HANDLE                    *HandleBuffer;
 376   UINTN                         HandleCount;
 377   UINTN                         Index;
 378   EFI_HANDLE                    FvHandle;
 379
 380   //
 381   // Search the FV that contain the caller's FFS first.
 382   // FV builder can choose to build FFS into the this FV
 383   // so that this implementation of GetSectionFromAnyFv
 384   // will locate the FFS faster.
 385   //
 386   FvHandle = InternalImageHandleToFvHandle (gImageHandle);
 387   Status = InternalGetSectionFromFv (
 388              FvHandle,
 389              NameGuid,
 390              SectionType,
 391              SectionInstance,
 392              Buffer,
 393              Size
 394              );
 395   if (!EFI_ERROR (Status)) {
 396     return EFI_SUCCESS;
 397   }
 398
 399   HandleBuffer = NULL;
 400   Status = gBS->LocateHandleBuffer (
 401                   ByProtocol,
 402                   &gEfiFirmwareVolume2ProtocolGuid,
 403                   NULL,
 404                   &HandleCount,
 405                   &HandleBuffer
 406                   );
 407   if (EFI_ERROR (Status)) {
 408     goto Done;
 409   }
 410
 411   for (Index = 0; Index < HandleCount; Index++) {
 412     //
 413     // Skip the FV that contain the caller's FFS
 414     //
 415     if (HandleBuffer[Index] != FvHandle) {
 416       Status = InternalGetSectionFromFv (
 417                  HandleBuffer[Index],
 418                  NameGuid,
 419                  SectionType,
 420                  SectionInstance,
 421                  Buffer,
 422                  Size
 423                  );
 424
 425       if (!EFI_ERROR (Status)) {
 426         goto Done;
 427       }
 428     }
 429
 430   }
 431
 432   if (Index == HandleCount) {
 433     Status = EFI_NOT_FOUND;
 434   }
 435
 436 Done:
 437
 438   if (HandleBuffer != NULL) {
 439     FreePool(HandleBuffer);
 440   }
 441   return Status;
 442
 443 }
 444
 445 /**
 446   Searches the firmware volume that the currently executing module was loaded from and returns the first matching FFS section.
 447
 448   This function searches the firmware volume that the currently executing module was loaded
 449   from for an FFS file with an FFS filename specified by NameGuid. If the FFS file is found a search
 450   is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance
 451   instances of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer.
 452   Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size.
 453   It is the caller's responsibility to use FreePool() to free the allocated buffer.
 454   See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections are retrieved from
 455   an FFS file based on SectionType and SectionInstance.
 456
 457   If the currently executing module was not loaded from a firmware volume, then EFI_NOT_FOUND is returned.
 458   If SectionType is EFI_SECTION_TE, and the search with an FFS file fails,
 459   the search will be retried with a section type of EFI_SECTION_PE32.
 460
 461   This function must be called with a TPL <= TPL_NOTIFY.
 462   If NameGuid is NULL, then ASSERT().
 463   If Buffer is NULL, then ASSERT().
 464   If Size is NULL, then ASSERT().
 465
 466   @param  NameGuid             A pointer to to the FFS filename GUID to search for
 467                                within the firmware volumes that the currently
 468                                executing module was loaded from.
 469   @param  SectionType          Indicates the FFS section type to search for within
 470                                the FFS file specified by NameGuid.
 471   @param  SectionInstance      Indicates which section instance within the FFS file
 472                                specified by NameGuid to retrieve.
 473   @param  Buffer               On output, a pointer to a callee allocated buffer
 474                                containing the FFS file section that was found.
 475                                Is it the caller's responsibility to free this buffer
 476                                using FreePool().
 477   @param  Size                 On output, a pointer to the size, in bytes, of Buffer.
 478
 479
 480   @retval  EFI_SUCCESS          The specified FFS section was returned.
 481   @retval  EFI_NOT_FOUND        The specified FFS section could not be found.
 482   @retval  EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve
 483                                 the matching FFS section.
 484   @retval  EFI_DEVICE_ERROR     The FFS section could not be retrieves due to a
 485                                 device error.
 486   @retval  EFI_ACCESS_DENIED    The FFS section could not be retrieves because the
 487                                 firmware volume that contains the matching FFS
 488                                 section does not allow reads.
 489 **/
 490 EFI_STATUS
 491 EFIAPI
 492 GetSectionFromFv (
 493   IN  CONST EFI_GUID                *NameGuid,
 494   IN  EFI_SECTION_TYPE              SectionType,
 495   IN  UINTN                         SectionInstance,
 496   OUT VOID                          **Buffer,
 497   OUT UINTN                         *Size
 498     )
 499 {
 500   return InternalGetSectionFromFv (
 501            InternalImageHandleToFvHandle(gImageHandle),
 502            NameGuid,
 503            SectionType,
 504            SectionInstance,
 505            Buffer,
 506            Size
 507            );
 508 }
 509
 510
 511 /**
 512   Searches the FFS file the the currently executing module was loaded from and returns the first matching FFS section.
 513
 514   This function searches the FFS file that the currently executing module was loaded from for a FFS sections of type SectionType.
 515   If the FFS file contains at least SectionInstance instances of the FFS section specified by SectionType,
 516   then the SectionInstance instance is returned in Buffer. Buffer is allocated using AllocatePool(),
 517   and the size of the allocated buffer is returned in Size. It is the caller's responsibility
 518   to use FreePool() to free the allocated buffer. See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for
 519   details on how sections are retrieved from an FFS file based on SectionType and SectionInstance.
 520
 521   If the currently executing module was not loaded from an FFS file, then EFI_NOT_FOUND is returned.
 522   If SectionType is EFI_SECTION_TE, and the search with an FFS file fails,
 523   the search will be retried with a section type of EFI_SECTION_PE32.
 524   This function must be called with a TPL <= TPL_NOTIFY.
 525
 526   If Buffer is NULL, then ASSERT().
 527   If Size is NULL, then ASSERT().
 528
 529
 530   @param  SectionType          Indicates the FFS section type to search for within
 531                                the FFS file that the currently executing module
 532                                was loaded from.
 533   @param  SectionInstance      Indicates which section instance to retrieve within
 534                                the FFS file that the currently executing module
 535                                was loaded from.
 536   @param  Buffer               On output, a pointer to a callee allocated buffer
 537                                containing the FFS file section that was found.
 538                                Is it the caller's responsibility to free this buffer
 539                                using FreePool().
 540   @param  Size                 On output, a pointer to the size, in bytes, of Buffer.
 541
 542   @retval  EFI_SUCCESS          The specified FFS section was returned.
 543   @retval  EFI_NOT_FOUND        The specified FFS section could not be found.
 544   @retval  EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve
 545                                 the matching FFS section.
 546   @retval  EFI_DEVICE_ERROR     The FFS section could not be retrieves due to a
 547                                 device error.
 548   @retval  EFI_ACCESS_DENIED    The FFS section could not be retrieves because the
 549                                 firmware volume that contains the matching FFS
 550                                 section does not allow reads.
 551
 552 **/
 553 EFI_STATUS
 554 EFIAPI
 555 GetSectionFromFfs (
 556   IN  EFI_SECTION_TYPE              SectionType,
 557   IN  UINTN                         SectionInstance,
 558   OUT VOID                          **Buffer,
 559   OUT UINTN                         *Size
 560     )
 561 {
 562   return InternalGetSectionFromFv(
 563            InternalImageHandleToFvHandle(gImageHandle),
 564            &gEfiCallerIdGuid,
 565            SectionType,
 566            SectionInstance,
 567            Buffer,
 568            Size
 569            );
 570 }
 571
 572
 573 /**
 574   Get the image file buffer data and buffer size by its device path.
 575
 576   Access the file either from a firmware volume, from a file system interface,
 577   or from the load file interface.
 578
 579   Allocate memory to store the found image. The caller is responsible to free memory.
 580
 581   If FilePath is NULL, then NULL is returned.
 582   If FileSize is NULL, then NULL is returned.
 583   If AuthenticationStatus is NULL, then NULL is returned.
 584
 585   @param[in]       BootPolicy           Policy for Open Image File.If TRUE, indicates
 586                                         that the request originates from the boot
 587                                         manager, and that the boot manager is
 588                                         attempting to load FilePath as a boot
 589                                         selection. If FALSE, then FilePath must
 590                                         match an exact file to be loaded.
 591   @param[in]       FilePath             The pointer to the device path of the file
 592                                         that is absracted to the file buffer.
 593   @param[out]      FileSize             The pointer to the size of the abstracted
 594                                         file buffer.
 595   @param[out]      AuthenticationStatus Pointer to the authentication status.
 596
 597   @retval NULL   FilePath is NULL, or FileSize is NULL, or AuthenticationStatus is NULL, or the file can't be found.
 598   @retval other  The abstracted file buffer. The caller is responsible to free memory.
 599 **/
 600 VOID *
 601 EFIAPI
 602 GetFileBufferByFilePath (
 603   IN BOOLEAN                           BootPolicy,
 604   IN CONST EFI_DEVICE_PATH_PROTOCOL    *FilePath,
 605   OUT      UINTN                       *FileSize,
 606   OUT UINT32                           *AuthenticationStatus
 607   )
 608 {
 609   EFI_DEVICE_PATH_PROTOCOL          *DevicePathNode;
 610   EFI_DEVICE_PATH_PROTOCOL          *OrigDevicePathNode;
 611   EFI_DEVICE_PATH_PROTOCOL          *TempDevicePathNode;
 612   EFI_HANDLE                        Handle;
 613   EFI_GUID                          *FvNameGuid;
 614   EFI_FIRMWARE_VOLUME2_PROTOCOL     *FwVol;
 615   EFI_SECTION_TYPE                  SectionType;
 616   UINT8                             *ImageBuffer;
 617   UINTN                             ImageBufferSize;
 618   EFI_FV_FILETYPE                   Type;
 619   EFI_FV_FILE_ATTRIBUTES            Attrib;
 620   EFI_SIMPLE_FILE_SYSTEM_PROTOCOL   *Volume;
 621   EFI_FILE_HANDLE                   FileHandle;
 622   EFI_FILE_HANDLE                   LastHandle;
 623   EFI_FILE_INFO                     *FileInfo;
 624   UINTN                             FileInfoSize;
 625   EFI_LOAD_FILE_PROTOCOL            *LoadFile;
 626   EFI_LOAD_FILE2_PROTOCOL           *LoadFile2;
 627   EFI_STATUS                        Status;
 628
 629   //
 630   // Check input File device path.
 631   //
 632   if (FilePath == NULL || FileSize == NULL || AuthenticationStatus == NULL) {
 633     return NULL;
 634   }
 635
 636   //
 637   // Init local variable
 638   //
 639   TempDevicePathNode  = NULL;
 640   FvNameGuid          = NULL;
 641   FileInfo            = NULL;
 642   FileHandle          = NULL;
 643   ImageBuffer         = NULL;
 644   ImageBufferSize     = 0;
 645   *AuthenticationStatus = 0;
 646
 647   //
 648   // Copy File Device Path
 649   //
 650   OrigDevicePathNode = DuplicateDevicePath (FilePath);
 651   if (OrigDevicePathNode == NULL) {
 652     return NULL;
 653   }
 654
 655   //
 656   // Check whether this device path support FV2 protocol.
 657   // Is so, this device path may contain a Image.
 658   //
 659   DevicePathNode = OrigDevicePathNode;
 660   Status = gBS->LocateDevicePath (&gEfiFirmwareVolume2ProtocolGuid, &DevicePathNode, &Handle);
 661   if (!EFI_ERROR (Status)) {
 662     //
 663     // For FwVol File system there is only a single file name that is a GUID.
 664     //
 665     FvNameGuid = EfiGetNameGuidFromFwVolDevicePathNode ((CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *) DevicePathNode);
 666     if (FvNameGuid == NULL) {
 667       Status = EFI_INVALID_PARAMETER;
 668     } else {
 669       //
 670       // Read image from the firmware file
 671       //
 672       Status = gBS->HandleProtocol (Handle, &gEfiFirmwareVolume2ProtocolGuid, (VOID**)&FwVol);
 673       if (!EFI_ERROR (Status)) {
 674         SectionType = EFI_SECTION_PE32;
 675         ImageBuffer = NULL;
 676         Status = FwVol->ReadSection (
 677                           FwVol,
 678                           FvNameGuid,
 679                           SectionType,
 680                           0,
 681                           (VOID **)&ImageBuffer,
 682                           &ImageBufferSize,
 683                           AuthenticationStatus
 684                           );
 685         if (EFI_ERROR (Status)) {
 686           //
 687           // Try a raw file, since a PE32 SECTION does not exist
 688           //
 689           if (ImageBuffer != NULL) {
 690             FreePool (ImageBuffer);
 691             *AuthenticationStatus = 0;
 692           }
 693           ImageBuffer = NULL;
 694           Status = FwVol->ReadFile (
 695                             FwVol,
 696                             FvNameGuid,
 697                             (VOID **)&ImageBuffer,
 698                             &ImageBufferSize,
 699                             &Type,
 700                             &Attrib,
 701                             AuthenticationStatus
 702                             );
 703         }
 704       }
 705     }
 706     if (!EFI_ERROR (Status)) {
 707       goto Finish;
 708     }
 709   }
 710
 711   //
 712   // Attempt to access the file via a file system interface
 713   //
 714   DevicePathNode = OrigDevicePathNode;
 715   Status = gBS->LocateDevicePath (&gEfiSimpleFileSystemProtocolGuid, &DevicePathNode, &Handle);
 716   if (!EFI_ERROR (Status)) {
 717     Status = gBS->HandleProtocol (Handle, &gEfiSimpleFileSystemProtocolGuid, (VOID**)&Volume);
 718     if (!EFI_ERROR (Status)) {
 719       //
 720       // Open the Volume to get the File System handle
 721       //
 722       Status = Volume->OpenVolume (Volume, &FileHandle);
 723       if (!EFI_ERROR (Status)) {
 724         //
 725         // Duplicate the device path to avoid the access to unaligned device path node.
 726         // Because the device path consists of one or more FILE PATH MEDIA DEVICE PATH
 727         // nodes, It assures the fields in device path nodes are 2 byte aligned.
 728         //
 729         TempDevicePathNode = DuplicateDevicePath (DevicePathNode);
 730         if (TempDevicePathNode == NULL) {
 731           FileHandle->Close (FileHandle);
 732           //
 733           // Setting Status to an EFI_ERROR value will cause the rest of
 734           // the file system support below to be skipped.
 735           //
 736           Status = EFI_OUT_OF_RESOURCES;
 737         }
 738         //
 739         // Parse each MEDIA_FILEPATH_DP node. There may be more than one, since the
 740         // directory information and filename can be seperate. The goal is to inch
 741         // our way down each device path node and close the previous node
 742         //
 743         DevicePathNode = TempDevicePathNode;
 744         while (!EFI_ERROR (Status) && !IsDevicePathEnd (DevicePathNode)) {
 745           if (DevicePathType (DevicePathNode) != MEDIA_DEVICE_PATH ||
 746               DevicePathSubType (DevicePathNode) != MEDIA_FILEPATH_DP) {
 747             Status = EFI_UNSUPPORTED;
 748             break;
 749           }
 750
 751           LastHandle = FileHandle;
 752           FileHandle = NULL;
 753
 754           Status = LastHandle->Open (
 755                                 LastHandle,
 756                                 &FileHandle,
 757                                 ((FILEPATH_DEVICE_PATH *) DevicePathNode)->PathName,
 758                                 EFI_FILE_MODE_READ,
 759                                 0
 760                                 );
 761
 762           //
 763           // Close the previous node
 764           //
 765           LastHandle->Close (LastHandle);
 766
 767           DevicePathNode = NextDevicePathNode (DevicePathNode);
 768         }
 769
 770         if (!EFI_ERROR (Status)) {
 771           //
 772           // We have found the file. Now we need to read it. Before we can read the file we need to
 773           // figure out how big the file is.
 774           //
 775           FileInfo = NULL;
 776           FileInfoSize = 0;
 777           Status = FileHandle->GetInfo (
 778                                 FileHandle,
 779                                 &gEfiFileInfoGuid,
 780                                 &FileInfoSize,
 781                                 FileInfo
 782                                 );
 783
 784           if (Status == EFI_BUFFER_TOO_SMALL) {
 785             FileInfo = AllocatePool (FileInfoSize);
 786             if (FileInfo == NULL) {
 787               Status = EFI_OUT_OF_RESOURCES;
 788             } else {
 789               Status = FileHandle->GetInfo (
 790                                     FileHandle,
 791                                     &gEfiFileInfoGuid,
 792                                     &FileInfoSize,
 793                                     FileInfo
 794                                     );
 795             }
 796           }
 797
 798           if (!EFI_ERROR (Status) && (FileInfo != NULL)) {
 799             //
 800             // Allocate space for the file
 801             //
 802             ImageBuffer = AllocatePool ((UINTN)FileInfo->FileSize);
 803             if (ImageBuffer == NULL) {
 804               Status = EFI_OUT_OF_RESOURCES;
 805             } else {
 806               //
 807               // Read the file into the buffer we allocated
 808               //
 809               ImageBufferSize = (UINTN)FileInfo->FileSize;
 810               Status          = FileHandle->Read (FileHandle, &ImageBufferSize, ImageBuffer);
 811             }
 812           }
 813         }
 814         //
 815         // Close the file and Free FileInfo and TempDevicePathNode since we are done
 816         //
 817         if (FileInfo != NULL) {
 818           FreePool (FileInfo);
 819         }
 820         if (FileHandle != NULL) {
 821           FileHandle->Close (FileHandle);
 822         }
 823         if (TempDevicePathNode != NULL) {
 824           FreePool (TempDevicePathNode);
 825         }
 826       }
 827     }
 828     if (!EFI_ERROR (Status)) {
 829       goto Finish;
 830     }
 831   }
 832
 833   //
 834   // Attempt to access the file via LoadFile2 interface
 835   //
 836   if (!BootPolicy) {
 837     DevicePathNode = OrigDevicePathNode;
 838     Status = gBS->LocateDevicePath (&gEfiLoadFile2ProtocolGuid, &DevicePathNode, &Handle);
 839     if (!EFI_ERROR (Status)) {
 840       Status = gBS->HandleProtocol (Handle, &gEfiLoadFile2ProtocolGuid, (VOID**)&LoadFile2);
 841       if (!EFI_ERROR (Status)) {
 842         //
 843         // Call LoadFile2 with the correct buffer size
 844         //
 845         ImageBufferSize = 0;
 846         ImageBuffer     = NULL;
 847         Status = LoadFile2->LoadFile (
 848                              LoadFile2,
 849                              DevicePathNode,
 850                              FALSE,
 851                              &ImageBufferSize,
 852                              ImageBuffer
 853                              );
 854         if (Status == EFI_BUFFER_TOO_SMALL) {
 855           ImageBuffer = AllocatePool (ImageBufferSize);
 856           if (ImageBuffer == NULL) {
 857             Status = EFI_OUT_OF_RESOURCES;
 858           } else {
 859             Status = LoadFile2->LoadFile (
 860                                  LoadFile2,
 861                                  DevicePathNode,
 862                                  FALSE,
 863                                  &ImageBufferSize,
 864                                  ImageBuffer
 865                                  );
 866           }
 867         }
 868       }
 869       if (!EFI_ERROR (Status)) {
 870         goto Finish;
 871       }
 872     }
 873   }
 874
 875   //
 876   // Attempt to access the file via LoadFile interface
 877   //
 878   DevicePathNode = OrigDevicePathNode;
 879   Status = gBS->LocateDevicePath (&gEfiLoadFileProtocolGuid, &DevicePathNode, &Handle);
 880   if (!EFI_ERROR (Status)) {
 881     Status = gBS->HandleProtocol (Handle, &gEfiLoadFileProtocolGuid, (VOID**)&LoadFile);
 882     if (!EFI_ERROR (Status)) {
 883       //
 884       // Call LoadFile with the correct buffer size
 885       //
 886       ImageBufferSize = 0;
 887       ImageBuffer     = NULL;
 888       Status = LoadFile->LoadFile (
 889                            LoadFile,
 890                            DevicePathNode,
 891                            BootPolicy,
 892                            &ImageBufferSize,
 893                            ImageBuffer
 894                            );
 895       if (Status == EFI_BUFFER_TOO_SMALL) {
 896         ImageBuffer = AllocatePool (ImageBufferSize);
 897         if (ImageBuffer == NULL) {
 898           Status = EFI_OUT_OF_RESOURCES;
 899         } else {
 900           Status = LoadFile->LoadFile (
 901                                LoadFile,
 902                                DevicePathNode,
 903                                BootPolicy,
 904                                &ImageBufferSize,
 905                                ImageBuffer
 906                                );
 907         }
 908       }
 909     }
 910   }
 911
 912 Finish:
 913
 914   if (EFI_ERROR (Status)) {
 915     if (ImageBuffer != NULL) {
 916       FreePool (ImageBuffer);
 917       ImageBuffer = NULL;
 918     }
 919     *FileSize = 0;
 920   } else {
 921     *FileSize = ImageBufferSize;
 922   }
 923
 924   FreePool (OrigDevicePathNode);
 925
 926   return ImageBuffer;
 927 }