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