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 - 2010, 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 File 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 The pointer to a caller-allocated UINT32
 596                                         in which the authentication status is returned.
 597
 598   @retval NULL   File is NULL, or FileSize is NULL. Or, the file can't be found.
 599   @retval other  The abstracted file buffer. The caller is responsible to free memory.
 600 **/
 601 VOID *
 602 EFIAPI
 603 GetFileBufferByFilePath (
 604   IN BOOLEAN                           BootPolicy,
 605   IN CONST EFI_DEVICE_PATH_PROTOCOL    *FilePath,
 606   OUT      UINTN                       *FileSize,
 607   OUT UINT32                           *AuthenticationStatus
 608   )
 609 {
 610   EFI_DEVICE_PATH_PROTOCOL          *DevicePathNode;
 611   EFI_DEVICE_PATH_PROTOCOL          *OrigDevicePathNode;
 612   EFI_DEVICE_PATH_PROTOCOL          *TempDevicePathNode;
 613   EFI_HANDLE                        Handle;
 614   EFI_GUID                          *FvNameGuid;
 615   EFI_FIRMWARE_VOLUME2_PROTOCOL     *FwVol;
 616   EFI_SECTION_TYPE                  SectionType;
 617   UINT8                             *ImageBuffer;
 618   UINTN                             ImageBufferSize;
 619   EFI_FV_FILETYPE                   Type;
 620   EFI_FV_FILE_ATTRIBUTES            Attrib;
 621   EFI_SIMPLE_FILE_SYSTEM_PROTOCOL   *Volume;
 622   EFI_FILE_HANDLE                   FileHandle;
 623   EFI_FILE_HANDLE                   LastHandle;
 624   EFI_FILE_INFO                     *FileInfo;
 625   UINTN                             FileInfoSize;
 626   EFI_LOAD_FILE_PROTOCOL            *LoadFile;
 627   EFI_LOAD_FILE2_PROTOCOL           *LoadFile2;
 628   EFI_STATUS                        Status;
 629
 630   //
 631   // Check input File device path.
 632   //
 633   if (FilePath == NULL || FileSize == NULL || AuthenticationStatus == NULL) {
 634     return NULL;
 635   }
 636
 637   //
 638   // Init local variable
 639   //
 640   TempDevicePathNode  = NULL;
 641   FvNameGuid          = NULL;
 642   FileInfo            = NULL;
 643   FileHandle          = NULL;
 644   ImageBuffer         = NULL;
 645   ImageBufferSize     = 0;
 646   *AuthenticationStatus = 0;
 647
 648   //
 649   // Copy File Device Path
 650   //
 651   OrigDevicePathNode = DuplicateDevicePath (FilePath);
 652   if (OrigDevicePathNode == NULL) {
 653     return NULL;
 654   }
 655
 656   //
 657   // Check whether this device path support FV2 protocol.
 658   // Is so, this device path may contain a Image.
 659   //
 660   DevicePathNode = OrigDevicePathNode;
 661   Status = gBS->LocateDevicePath (&gEfiFirmwareVolume2ProtocolGuid, &DevicePathNode, &Handle);
 662   if (!EFI_ERROR (Status)) {
 663     //
 664     // For FwVol File system there is only a single file name that is a GUID.
 665     //
 666     FvNameGuid = EfiGetNameGuidFromFwVolDevicePathNode ((CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *) DevicePathNode);
 667     if (FvNameGuid == NULL) {
 668       Status = EFI_INVALID_PARAMETER;
 669     } else {
 670       //
 671       // Read image from the firmware file
 672       //
 673       Status = gBS->HandleProtocol (Handle, &gEfiFirmwareVolume2ProtocolGuid, (VOID**)&FwVol);
 674       if (!EFI_ERROR (Status)) {
 675         SectionType = EFI_SECTION_PE32;
 676         ImageBuffer = NULL;
 677         Status = FwVol->ReadSection (
 678                           FwVol,
 679                           FvNameGuid,
 680                           SectionType,
 681                           0,
 682                           (VOID **)&ImageBuffer,
 683                           &ImageBufferSize,
 684                           AuthenticationStatus
 685                           );
 686         if (EFI_ERROR (Status)) {
 687           //
 688           // Try a raw file, since a PE32 SECTION does not exist
 689           //
 690           if (ImageBuffer != NULL) {
 691             FreePool (ImageBuffer);
 692             *AuthenticationStatus = 0;
 693           }
 694           ImageBuffer = NULL;
 695           Status = FwVol->ReadFile (
 696                             FwVol,
 697                             FvNameGuid,
 698                             (VOID **)&ImageBuffer,
 699                             &ImageBufferSize,
 700                             &Type,
 701                             &Attrib,
 702                             AuthenticationStatus
 703                             );
 704         }
 705       }
 706     }
 707     goto Finish;
 708   }
 709
 710   //
 711   // Attempt to access the file via a file system interface
 712   //
 713   DevicePathNode = OrigDevicePathNode;
 714   Status = gBS->LocateDevicePath (&gEfiSimpleFileSystemProtocolGuid, &DevicePathNode, &Handle);
 715   if (!EFI_ERROR (Status)) {
 716     Status = gBS->HandleProtocol (Handle, &gEfiSimpleFileSystemProtocolGuid, (VOID**)&Volume);
 717     if (!EFI_ERROR (Status)) {
 718       //
 719       // Open the Volume to get the File System handle
 720       //
 721       Status = Volume->OpenVolume (Volume, &FileHandle);
 722       if (!EFI_ERROR (Status)) {
 723         //
 724         // Duplicate the device path to avoid the access to unaligned device path node.
 725         // Because the device path consists of one or more FILE PATH MEDIA DEVICE PATH
 726         // nodes, It assures the fields in device path nodes are 2 byte aligned.
 727         //
 728         TempDevicePathNode = DuplicateDevicePath (DevicePathNode);
 729         if (TempDevicePathNode == NULL) {
 730           FileHandle->Close (FileHandle);
 731           Status = EFI_OUT_OF_RESOURCES;
 732           goto Finish;
 733         }
 734         //
 735         // Parse each MEDIA_FILEPATH_DP node. There may be more than one, since the
 736         // directory information and filename can be seperate. The goal is to inch
 737         // our way down each device path node and close the previous node
 738         //
 739         DevicePathNode = TempDevicePathNode;
 740         while (!IsDevicePathEnd (DevicePathNode) && !EFI_ERROR (Status)) {
 741           if (DevicePathType (DevicePathNode) != MEDIA_DEVICE_PATH ||
 742               DevicePathSubType (DevicePathNode) != MEDIA_FILEPATH_DP) {
 743             Status = EFI_UNSUPPORTED;
 744             break;
 745           }
 746
 747           LastHandle = FileHandle;
 748           FileHandle = NULL;
 749
 750           Status = LastHandle->Open (
 751                                 LastHandle,
 752                                 &FileHandle,
 753                                 ((FILEPATH_DEVICE_PATH *) DevicePathNode)->PathName,
 754                                 EFI_FILE_MODE_READ,
 755                                 0
 756                                 );
 757
 758           //
 759           // Close the previous node
 760           //
 761           LastHandle->Close (LastHandle);
 762
 763           DevicePathNode = NextDevicePathNode (DevicePathNode);
 764         }
 765
 766         if (!EFI_ERROR (Status)) {
 767           //
 768           // We have found the file. Now we need to read it. Before we can read the file we need to
 769           // figure out how big the file is.
 770           //
 771           FileInfo = NULL;
 772           FileInfoSize = 0;
 773           Status = FileHandle->GetInfo (
 774                                 FileHandle,
 775                                 &gEfiFileInfoGuid,
 776                                 &FileInfoSize,
 777                                 FileInfo
 778                                 );
 779
 780           if (Status == EFI_BUFFER_TOO_SMALL) {
 781             FileInfo = AllocatePool (FileInfoSize);
 782             if (FileInfo == NULL) {
 783               Status = EFI_OUT_OF_RESOURCES;
 784             } else {
 785               Status = FileHandle->GetInfo (
 786                                     FileHandle,
 787                                     &gEfiFileInfoGuid,
 788                                     &FileInfoSize,
 789                                     FileInfo
 790                                     );
 791             }
 792           }
 793
 794           if (!EFI_ERROR (Status) && (FileInfo != NULL)) {
 795             //
 796             // Allocate space for the file
 797             //
 798             ImageBuffer = AllocatePool ((UINTN)FileInfo->FileSize);
 799             if (ImageBuffer == NULL) {
 800               Status = EFI_OUT_OF_RESOURCES;
 801             } else {
 802               //
 803               // Read the file into the buffer we allocated
 804               //
 805               ImageBufferSize = (UINTN)FileInfo->FileSize;
 806               Status          = FileHandle->Read (FileHandle, &ImageBufferSize, ImageBuffer);
 807             }
 808           }
 809         }
 810         //
 811         // Close the file and Free FileInfo and TempDevicePathNode since we are done
 812         //
 813         if (FileInfo != NULL) {
 814           FreePool (FileInfo);
 815         }
 816         if (FileHandle != NULL) {
 817           FileHandle->Close (FileHandle);
 818         }
 819         FreePool (TempDevicePathNode);
 820       }
 821     }
 822     goto Finish;
 823   }
 824
 825   //
 826   // Attempt to access the file via LoadFile2 interface
 827   //
 828   if (!BootPolicy) {
 829     DevicePathNode = OrigDevicePathNode;
 830     Status = gBS->LocateDevicePath (&gEfiLoadFile2ProtocolGuid, &DevicePathNode, &Handle);
 831     if (!EFI_ERROR (Status)) {
 832       Status = gBS->HandleProtocol (Handle, &gEfiLoadFile2ProtocolGuid, (VOID**)&LoadFile2);
 833       if (!EFI_ERROR (Status)) {
 834         //
 835         // Call LoadFile2 with the correct buffer size
 836         //
 837         ImageBufferSize = 0;
 838         ImageBuffer     = NULL;
 839         Status = LoadFile2->LoadFile (
 840                              LoadFile2,
 841                              DevicePathNode,
 842                              FALSE,
 843                              &ImageBufferSize,
 844                              ImageBuffer
 845                              );
 846         if (Status == EFI_BUFFER_TOO_SMALL) {
 847           ImageBuffer = AllocatePool (ImageBufferSize);
 848           if (ImageBuffer == NULL) {
 849             Status = EFI_OUT_OF_RESOURCES;
 850           } else {
 851             Status = LoadFile2->LoadFile (
 852                                  LoadFile2,
 853                                  DevicePathNode,
 854                                  FALSE,
 855                                  &ImageBufferSize,
 856                                  ImageBuffer
 857                                  );
 858           }
 859         }
 860       }
 861       goto Finish;
 862     }
 863   }
 864
 865   //
 866   // Attempt to access the file via LoadFile interface
 867   //
 868   DevicePathNode = OrigDevicePathNode;
 869   Status = gBS->LocateDevicePath (&gEfiLoadFileProtocolGuid, &DevicePathNode, &Handle);
 870   if (!EFI_ERROR (Status)) {
 871     Status = gBS->HandleProtocol (Handle, &gEfiLoadFileProtocolGuid, (VOID**)&LoadFile);
 872     if (!EFI_ERROR (Status)) {
 873       //
 874       // Call LoadFile with the correct buffer size
 875       //
 876       ImageBufferSize = 0;
 877       ImageBuffer     = NULL;
 878       Status = LoadFile->LoadFile (
 879                            LoadFile,
 880                            DevicePathNode,
 881                            BootPolicy,
 882                            &ImageBufferSize,
 883                            ImageBuffer
 884                            );
 885       if (Status == EFI_BUFFER_TOO_SMALL) {
 886         ImageBuffer = AllocatePool (ImageBufferSize);
 887         if (ImageBuffer == NULL) {
 888           Status = EFI_OUT_OF_RESOURCES;
 889         } else {
 890           Status = LoadFile->LoadFile (
 891                                LoadFile,
 892                                DevicePathNode,
 893                                BootPolicy,
 894                                &ImageBufferSize,
 895                                ImageBuffer
 896                                );
 897         }
 898       }
 899     }
 900   }
 901
 902 Finish:
 903
 904   if (EFI_ERROR (Status)) {
 905     if (ImageBuffer != NULL) {
 906       FreePool (ImageBuffer);
 907       ImageBuffer = NULL;
 908     }
 909     *FileSize = 0;
 910   } else {
 911     *FileSize = ImageBufferSize;
 912   }
 913
 914   FreePool (OrigDevicePathNode);
 915
 916   return ImageBuffer;
 917 }