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