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.
   4
   5   Copyright (c) 2007 - 2008, Intel Corporation<BR>
   6   All rights reserved. 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/DxeServicesLib.h>
  21 #include <Protocol/FirmwareVolume2.h>
  22 #include <Protocol/LoadedImage.h>
  23
  24
  25 /**
  26   Identify the device handle from which the Image is loaded from. As this device handle is passed to
  27   GetSectionFromFv as the identifier for a Firmware Volume, an EFI_FIRMWARE_VOLUME2_PROTOCOL
  28   protocol instance should be located succesfully by calling gBS->HandleProtocol ().
  29
  30   This function locates the EFI_LOADED_IMAGE_PROTOCOL instance installed
  31   on ImageHandle. It then returns EFI_LOADED_IMAGE_PROTOCOL.DeviceHandle.
  32
  33   If ImageHandle is NULL, then ASSERT ();
  34   If failed to locate a EFI_LOADED_IMAGE_PROTOCOL on ImageHandle, then ASSERT ();
  35
  36   @param  ImageHandle         The firmware allocated handle for UEFI image.
  37
  38   @retval  EFI_HANDLE          The device handle from which the Image is loaded from.
  39
  40 **/
  41 EFI_HANDLE
  42 InternalImageHandleToFvHandle (
  43   EFI_HANDLE ImageHandle
  44   )
  45 {
  46   EFI_STATUS                    Status;
  47   EFI_LOADED_IMAGE_PROTOCOL     *LoadedImage;
  48
  49   ASSERT (ImageHandle != NULL);
  50
  51   Status = gBS->HandleProtocol (
  52              (EFI_HANDLE *) ImageHandle,
  53              &gEfiLoadedImageProtocolGuid,
  54              (VOID **) &LoadedImage
  55              );
  56
  57   ASSERT_EFI_ERROR (Status);
  58
  59   return LoadedImage->DeviceHandle;
  60
  61 }
  62
  63 /**
  64   Allocate and fill a buffer from a Firmware Section identified by a Firmware File GUID name, a Firmware
  65   Section type and instance number from the specified Firmware Volume.
  66
  67   This functions first locate the EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance on FvHandle in order to
  68   carry out the Firmware Volume read operation. The function then reads the Firmware Section found sepcifed
  69   by NameGuid, SectionType and SectionInstance.
  70
  71   The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
  72   found in PI Specification.
  73
  74   If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
  75   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
  76   is returned.
  77
  78   The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
  79   by this function. This function can be only called at TPL_NOTIFY and below.
  80
  81   If FvHandle is NULL, then ASSERT ();
  82   If NameGuid is NULL, then ASSERT();
  83   If Buffer is NULL, then ASSERT();
  84   If Size is NULL, then ASSERT().
  85
  86   @param  FvHandle                The device handle that contains a instance of EFI_FIRMWARE_VOLUME2_PROTOCOL instance.
  87   @param  NameGuid                The GUID name of a Firmware File.
  88   @param  SectionType             The Firmware Section type.
  89   @param  SectionInstance         The instance number of Firmware Section to read from starting from 0.
  90   @param  Buffer                  On output, Buffer contains the the data read from the section in the Firmware File found.
  91   @param  Size                    On output, the size of Buffer.
  92
  93   @retval  EFI_SUCCESS            The image is found and data and size is returned.
  94   @retval  EFI_NOT_FOUND          The image specified by NameGuid and SectionType can't be found.
  95   @retval  EFI_OUT_OF_RESOURCES   There were not enough resources to allocate the output data buffer or complete the operations.
  96   @retval  EFI_DEVICE_ERROR       A hardware error occurs during reading from the Firmware Volume.
  97   @retval  EFI_ACCESS_DENIED      The firmware volume containing the searched Firmware File is configured to disallow reads.
  98
  99 **/
 100 EFI_STATUS
 101 InternalGetSectionFromFv (
 102   IN  EFI_HANDLE                    FvHandle,
 103   IN  CONST EFI_GUID                *NameGuid,
 104   IN  EFI_SECTION_TYPE              SectionType,
 105   IN  UINTN                         SectionInstance,
 106   OUT VOID                          **Buffer,
 107   OUT UINTN                         *Size
 108   )
 109 {
 110   EFI_STATUS                    Status;
 111   EFI_FIRMWARE_VOLUME2_PROTOCOL *Fv;
 112   UINT32                        AuthenticationStatus;
 113
 114   ASSERT (NameGuid != NULL);
 115   ASSERT (Buffer != NULL);
 116   ASSERT (Size != NULL);
 117
 118   ASSERT (FvHandle != NULL);
 119
 120   Status = gBS->HandleProtocol (
 121                   FvHandle,
 122                   &gEfiFirmwareVolume2ProtocolGuid,
 123                   (VOID **) &Fv
 124                   );
 125   if (EFI_ERROR (Status)) {
 126     return EFI_NOT_FOUND;
 127   }
 128
 129   //
 130   // Read desired section content in NameGuid file
 131   //
 132   *Buffer     = NULL;
 133   *Size       = 0;
 134   Status      = Fv->ReadSection (
 135                       Fv,
 136                       NameGuid,
 137                       SectionType,
 138                       SectionInstance,
 139                       Buffer,
 140                       Size,
 141                       &AuthenticationStatus
 142                       );
 143
 144   if (EFI_ERROR (Status) && (SectionType == EFI_SECTION_TE)) {
 145     //
 146     // Try reading PE32 section, if the required section is TE type
 147     //
 148     *Buffer = NULL;
 149     *Size   = 0;
 150     Status  = Fv->ReadSection (
 151                     Fv,
 152                     NameGuid,
 153                     EFI_SECTION_PE32,
 154                     SectionInstance,
 155                     Buffer,
 156                     Size,
 157                     &AuthenticationStatus
 158                     );
 159   }
 160
 161   return Status;
 162 }
 163
 164
 165
 166 /**
 167   Searches all the availables firmware volumes and returns the first matching FFS section.
 168
 169   This function searches all the firmware volumes for FFS files with an FFS filename specified by NameGuid.
 170   The order that the firmware volumes is searched is not deterministic. For each FFS file found a search
 171   is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance instances
 172   of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer.
 173   Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size.
 174   It is the caller's responsibility to use FreePool() to free the allocated buffer.
 175   See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections
 176   are retrieved from an FFS file based on SectionType and SectionInstance.
 177
 178   If SectionType is EFI_SECTION_TE, and the search with an FFS file fails,
 179   the search will be retried with a section type of EFI_SECTION_PE32.
 180   This function must be called with a TPL <= TPL_NOTIFY.
 181
 182   If NameGuid is NULL, then ASSERT().
 183   If Buffer is NULL, then ASSERT().
 184   If Size is NULL, then ASSERT().
 185
 186
 187   @param  NameGuid             A pointer to to the FFS filename GUID to search for within
 188                                any of the firmware volumes in the platform.
 189   @param  SectionType          Indicates the FFS section type to search for within the FFS file specified by NameGuid.
 190   @param  SectionInstance      Indicates which section instance within the FFS file specified by NameGuid to retrieve.
 191   @param  Buffer               On output, a pointer to a callee allocated buffer containing the FFS file section that was found.
 192                                Is it the caller's responsibility to free this buffer using FreePool().
 193   @param  Size                 On output, a pointer to the size, in bytes, of Buffer.
 194
 195   @retval  EFI_SUCCESS          The specified FFS section was returned.
 196   @retval  EFI_NOT_FOUND        The specified FFS section could not be found.
 197   @retval  EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve the matching FFS section.
 198   @retval  EFI_DEVICE_ERROR     The FFS section could not be retrieves due to a device error.
 199   @retval  EFI_ACCESS_DENIED    The FFS section could not be retrieves because the firmware volume that
 200                                 contains the matching FFS section does not allow reads.
 201 **/
 202 EFI_STATUS
 203 EFIAPI
 204 GetSectionFromAnyFv  (
 205   IN CONST  EFI_GUID           *NameGuid,
 206   IN        EFI_SECTION_TYPE   SectionType,
 207   IN        UINTN              SectionInstance,
 208   OUT       VOID               **Buffer,
 209   OUT       UINTN              *Size
 210   )
 211 {
 212   EFI_STATUS                    Status;
 213   EFI_HANDLE                    *HandleBuffer;
 214   UINTN                         HandleCount;
 215   UINTN                         Index;
 216   EFI_HANDLE                    FvHandle;
 217
 218   //
 219   // Search the FV that contain the caller's FFS first.
 220   // FV builder can choose to build FFS into the this FV
 221   // so that this implementation of GetSectionFromAnyFv
 222   // will locate the FFS faster.
 223   //
 224   FvHandle = InternalImageHandleToFvHandle (gImageHandle);
 225   Status = InternalGetSectionFromFv (
 226              FvHandle,
 227              NameGuid,
 228              SectionType,
 229              SectionInstance,
 230              Buffer,
 231              Size
 232              );
 233   if (!EFI_ERROR (Status)) {
 234     return EFI_SUCCESS;
 235   }
 236
 237   HandleBuffer = NULL;
 238   Status = gBS->LocateHandleBuffer (
 239                   ByProtocol,
 240                   &gEfiFirmwareVolume2ProtocolGuid,
 241                   NULL,
 242                   &HandleCount,
 243                   &HandleBuffer
 244                   );
 245   if (EFI_ERROR (Status)) {
 246     goto Done;
 247   }
 248
 249   for (Index = 0; Index < HandleCount; Index++) {
 250     //
 251     // Skip the FV that contain the caller's FFS
 252     //
 253     if (HandleBuffer[Index] != FvHandle) {
 254       Status = InternalGetSectionFromFv (
 255                  HandleBuffer[Index],
 256                  NameGuid,
 257                  SectionType,
 258                  SectionInstance,
 259                  Buffer,
 260                  Size
 261                  );
 262
 263       if (!EFI_ERROR (Status)) {
 264         goto Done;
 265       }
 266     }
 267
 268   }
 269
 270   if (Index == HandleCount) {
 271     Status = EFI_NOT_FOUND;
 272   }
 273
 274 Done:
 275
 276   if (HandleBuffer != NULL) {
 277     FreePool(HandleBuffer);
 278   }
 279   return Status;
 280
 281 }
 282
 283 /**
 284   Searches the firmware volume that the currently executing module was loaded from and returns the first matching FFS section.
 285
 286   This function searches the firmware volume that the currently executing module was loaded
 287   from for an FFS file with an FFS filename specified by NameGuid. If the FFS file is found a search
 288   is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance
 289   instances of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer.
 290   Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size.
 291   It is the caller's responsibility to use FreePool() to free the allocated buffer.
 292   See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections are retrieved from
 293   an FFS file based on SectionType and SectionInstance.
 294
 295   If the currently executing module was not loaded from a firmware volume, then EFI_NOT_FOUND is returned.
 296   If SectionType is EFI_SECTION_TE, and the search with an FFS file fails,
 297   the search will be retried with a section type of EFI_SECTION_PE32.
 298
 299   This function must be called with a TPL <= TPL_NOTIFY.
 300   If NameGuid is NULL, then ASSERT().
 301   If Buffer is NULL, then ASSERT().
 302   If Size is NULL, then ASSERT().
 303
 304   @param  NameGuid             A pointer to to the FFS filename GUID to search for within
 305                                the firmware volumes that the currently executing module was loaded from.
 306   @param  SectionType          Indicates the FFS section type to search for within the FFS file specified by NameGuid.
 307   @param  SectionInstance      Indicates which section instance within the FFS file specified by NameGuid to retrieve.
 308   @param  Buffer               On output, a pointer to a callee allocated buffer containing the FFS file section that was found.
 309                                Is it the caller's responsibility to free this buffer using FreePool().
 310   @param  Size                 On output, a pointer to the size, in bytes, of Buffer.
 311
 312
 313   @retval  EFI_SUCCESS          The specified FFS section was returned.
 314   @retval  EFI_NOT_FOUND        The specified FFS section could not be found.
 315   @retval  EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve the matching FFS section.
 316   @retval  EFI_DEVICE_ERROR     The FFS section could not be retrieves due to a device error.
 317   @retval  EFI_ACCESS_DENIED    The FFS section could not be retrieves because the firmware volume that
 318                                 contains the matching FFS section does not allow reads.
 319 **/
 320 EFI_STATUS
 321 EFIAPI
 322 GetSectionFromFv (
 323   IN  CONST EFI_GUID                *NameGuid,
 324   IN  EFI_SECTION_TYPE              SectionType,
 325   IN  UINTN                         SectionInstance,
 326   OUT VOID                          **Buffer,
 327   OUT UINTN                         *Size
 328     )
 329 {
 330   return InternalGetSectionFromFv (
 331            InternalImageHandleToFvHandle(gImageHandle),
 332            NameGuid,
 333            SectionType,
 334            SectionInstance,
 335            Buffer,
 336            Size
 337            );
 338 }
 339
 340
 341 /**
 342   Searches the FFS file the the currently executing module was loaded from and returns the first matching FFS section.
 343
 344   This function searches the FFS file that the currently executing module was loaded from for a FFS sections of type SectionType.
 345   If the FFS file contains at least SectionInstance instances of the FFS section specified by SectionType,
 346   then the SectionInstance instance is returned in Buffer. Buffer is allocated using AllocatePool(),
 347   and the size of the allocated buffer is returned in Size. It is the caller's responsibility
 348   to use FreePool() to free the allocated buffer. See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for
 349   details on how sections are retrieved from an FFS file based on SectionType and SectionInstance.
 350
 351   If the currently executing module was not loaded from an FFS file, then EFI_NOT_FOUND is returned.
 352   If SectionType is EFI_SECTION_TE, and the search with an FFS file fails,
 353   the search will be retried with a section type of EFI_SECTION_PE32.
 354   This function must be called with a TPL <= TPL_NOTIFY.
 355
 356   If Buffer is NULL, then ASSERT().
 357   If Size is NULL, then ASSERT().
 358
 359
 360   @param  SectionType          Indicates the FFS section type to search for within the FFS file
 361                                that the currently executing module was loaded from.
 362   @param  SectionInstance      Indicates which section instance to retrieve within the FFS file
 363                                that the currently executing module was loaded from.
 364   @param  Buffer               On output, a pointer to a callee allocated buffer containing the FFS file section that was found.
 365                                Is it the caller's responsibility to free this buffer using FreePool().
 366   @param  Size                 On output, a pointer to the size, in bytes, of Buffer.
 367
 368   @retval  EFI_SUCCESS          The specified FFS section was returned.
 369   @retval  EFI_NOT_FOUND        The specified FFS section could not be found.
 370   @retval  EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve the matching FFS section.
 371   @retval  EFI_DEVICE_ERROR     The FFS section could not be retrieves due to a device error.
 372   @retval  EFI_ACCESS_DENIED    The FFS section could not be retrieves because the firmware volume that
 373                                 contains the matching FFS section does not allow reads.
 374
 375 **/
 376 EFI_STATUS
 377 EFIAPI
 378 GetSectionFromFfs (
 379   IN  EFI_SECTION_TYPE              SectionType,
 380   IN  UINTN                         SectionInstance,
 381   OUT VOID                          **Buffer,
 382   OUT UINTN                         *Size
 383     )
 384 {
 385   return InternalGetSectionFromFv(
 386            InternalImageHandleToFvHandle(gImageHandle),
 387            &gEfiCallerIdGuid,
 388            SectionType,
 389            SectionInstance,
 390            Buffer,
 391            Size
 392            );
 393 }
 394