MdePkg/Library/DxeServicesLib/DxeServicesLib.c

   1 /** @file
   2   Mde PI library functions.
   3
   4   Copyright (c) 2007 - 2008, Intel Corporation<BR>
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #include <PiDxe.h>
  16 #include <Library/DebugLib.h>
  17 #include <Library/MemoryAllocationLib.h>
  18 #include <Library/UefiBootServicesTableLib.h>
  19 #include <Library/DxeServicesLib.h>
  20 #include <Protocol/FirmwareVolume2.h>
  21 #include <Protocol/LoadedImage.h>
  22
  23
  24 /**
  25   Identify the device handle from which the Image is loaded from. As this device handle is passed to
  26   GetSectionFromFv as the identifier for a Firmware Volume, an EFI_FIRMWARE_VOLUME2_PROTOCOL
  27   protocol instance should be located succesfully by calling gBS->HandleProtocol ().
  28
  29   This function locates the EFI_LOADED_IMAGE_PROTOCOL instance installed
  30   on ImageHandle. It then returns EFI_LOADED_IMAGE_PROTOCOL.DeviceHandle.
  31
  32   If ImageHandle is NULL, then ASSERT ();
  33   If failed to locate a EFI_LOADED_IMAGE_PROTOCOL on ImageHandle, then ASSERT ();
  34
  35   @param  ImageHandle         The firmware allocated handle for UEFI image.
  36
  37   @retval  EFI_HANDLE           The device handle from which the Image is loaded from.
  38
  39 **/
  40 EFI_HANDLE
  41 InternalImageHandleToFvHandle (
  42   EFI_HANDLE ImageHandle
  43   )
  44 {
  45   EFI_STATUS                    Status;
  46   EFI_LOADED_IMAGE_PROTOCOL     *LoadedImage;
  47
  48   ASSERT (ImageHandle != NULL);
  49
  50   Status = gBS->HandleProtocol (
  51              (EFI_HANDLE *) ImageHandle,
  52              &gEfiLoadedImageProtocolGuid,
  53              (VOID **) &LoadedImage
  54              );
  55
  56   ASSERT_EFI_ERROR (Status);
  57
  58   return LoadedImage->DeviceHandle;
  59
  60 }
  61
  62 /**
  63     Allocate and fill a buffer from a Firmware Section identified by a Firmware File GUID name, a Firmware
  64     Section type and instance number from the specified Firmware Volume.
  65
  66     This functions first locate the EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance on FvHandle in order to
  67     carry out the Firmware Volume read operation. The function then reads the Firmware Section found sepcifed
  68     by NameGuid, SectionType and SectionInstance.
  69
  70     The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
  71     found in PI Specification.
  72
  73     If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
  74     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
  75     is returned.
  76
  77     The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
  78     by this function. This function can be only called at TPL_NOTIFY and below.
  79
  80     If FvHandle is NULL, then ASSERT ();
  81     If NameGuid is NULL, then ASSERT();
  82     If Buffer is NULL, then ASSERT();
  83     If Size is NULL, then ASSERT().
  84
  85     @param  FvHandle                The device handle that contains a instance of EFI_FIRMWARE_VOLUME2_PROTOCOL instance.
  86     @param  NameGuid                The GUID name of a Firmware File.
  87     @param  SectionType             The Firmware Section type.
  88     @param  SectionInstance         The instance number of Firmware Section to read from starting from 0.
  89     @param  Buffer                  On output, Buffer contains the the data read from the section in the Firmware File found.
  90     @param  Size                    On output, the size of Buffer.
  91
  92     @retval  EFI_SUCCESS            The image is found and data and size is returned.
  93     @retval  EFI_UNSUPPORTED        FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.
  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 Status;
 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   Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
 168
 169   GetSectionFromAnyFv  () is used to read a specific section from a file within a firmware volume. The function
 170   will search the first file with the specified name in all firmware volumes in the system. The search order for firmware
 171   volumes in the system is determistic but abitrary if no new firmware volume is added into the system between
 172   each calls of this function.
 173
 174   After the specific file is located, the function searches the specifc firmware section with type SectionType in this file.
 175   The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
 176   found in PI Specification.
 177
 178   If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
 179   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
 180   is returned.
 181
 182   The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
 183   by this function. This function can only be called at TPL_NOTIFY and below.
 184
 185   If NameGuid is NULL, then ASSERT();
 186   If Buffer is NULL, then ASSERT();
 187   If Size is NULL, then ASSERT().
 188
 189   @param  NameGuid             Pointer to an EFI_GUID, which indicates the file name from which the requested
 190                                section will be read. Type EFI_GUID is defined in
 191                                InstallProtocolInterface() in the UEFI 2.0 specification.
 192   @param  SectionType          Indicates the section type to return. SectionType in conjunction with
 193                                SectionInstance indicates which section to return. Type
 194                                EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
 195   @param  SectionInstance      Indicates which instance of sections with a type of SectionType to return.
 196                                SectionType in conjunction with SectionInstance indicates which section to
 197                                return. SectionInstance is zero based.
 198   @param  Buffer               Pointer to a pointer to a buffer in which the section contents are returned, not
 199                                including the section header. Caller is responsible to free this memory.
 200   @param  Size                 Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
 201                                *Buffer.
 202
 203   @retval  EFI_SUCCESS        The image is found and data and size is returned.
 204   @retval  EFI_NOT_FOUND      The image specified by NameGuid and SectionType can't be found.
 205   @retval  EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
 206   @retval  EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
 207   @retval  EFI_ACCESS_DENIED  The firmware volume containing the searched Firmware File is configured to disallow reads.
 208
 209 **/
 210 EFI_STATUS
 211 EFIAPI
 212 GetSectionFromAnyFv  (
 213   IN CONST  EFI_GUID           *NameGuid,
 214   IN        EFI_SECTION_TYPE   SectionType,
 215   IN        UINTN              SectionInstance,
 216   OUT       VOID               **Buffer,
 217   OUT       UINTN              *Size
 218   )
 219 {
 220   EFI_STATUS                    Status;
 221   EFI_HANDLE                    *HandleBuffer;
 222   UINTN                         HandleCount;
 223   UINTN                         Index;
 224   EFI_HANDLE                    FvHandle;
 225
 226   //
 227   // Search the FV that contain the caller's FFS first.
 228   // FV builder can choose to build FFS into the this FV
 229   // so that this implementation of GetSectionFromAnyFv
 230   // will locate the FFS faster.
 231   //
 232   FvHandle = InternalImageHandleToFvHandle (gImageHandle);
 233   Status = InternalGetSectionFromFv (
 234              FvHandle,
 235              NameGuid,
 236              SectionType,
 237              SectionInstance,
 238              Buffer,
 239              Size
 240              );
 241   if (!EFI_ERROR (Status)) {
 242     return EFI_SUCCESS;
 243   }
 244
 245   HandleBuffer = NULL;
 246   Status = gBS->LocateHandleBuffer (
 247                   ByProtocol,
 248                   &gEfiFirmwareVolume2ProtocolGuid,
 249                   NULL,
 250                   &HandleCount,
 251                   &HandleBuffer
 252                   );
 253   if (EFI_ERROR (Status)) {
 254     goto Done;
 255   }
 256
 257   for (Index = 0; Index < HandleCount; Index++) {
 258     //
 259     // Skip the FV that contain the caller's FFS
 260     //
 261     if (HandleBuffer[Index] != FvHandle) {
 262       Status = InternalGetSectionFromFv (
 263                  HandleBuffer[Index],
 264                  NameGuid,
 265                  SectionType,
 266                  SectionInstance,
 267                  Buffer,
 268                  Size
 269                  );
 270
 271       if (!EFI_ERROR (Status)) {
 272         goto Done;
 273       }
 274     }
 275
 276   }
 277
 278   if (Index == HandleCount) {
 279     Status = EFI_NOT_FOUND;
 280   }
 281
 282 Done:
 283
 284   if (HandleBuffer != NULL) {
 285     FreePool(HandleBuffer);
 286   }
 287   return Status;
 288
 289 }
 290
 291 /**
 292   Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
 293
 294   GetSectionFromFv () is used to read a specific section from a file within the same firmware volume from which
 295   the running image is loaded. If the specific file is found, the function searches the specifc firmware section with type SectionType.
 296   The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
 297   found in PI Specification.
 298
 299   If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
 300   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
 301   is returned.
 302
 303   The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
 304   by this function. This function can be only called at TPL_NOTIFY and below.
 305
 306   If NameGuid is NULL, then ASSERT();
 307   If Buffer is NULL, then ASSERT();
 308   If Size is NULL, then ASSERT().
 309
 310   @param  NameGuid             Pointer to an EFI_GUID, which indicates the file name from which the requested
 311                                section will be read. Type EFI_GUID is defined in
 312                                InstallProtocolInterface() in the UEFI 2.0 specification.
 313   @param  SectionType          Indicates the section type to return. SectionType in conjunction with
 314                                SectionInstance indicates which section to return. Type
 315                                EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
 316   @param  SectionInstance      Indicates which instance of sections with a type of SectionType to return.
 317                                SectionType in conjunction with SectionInstance indicates which section to
 318                                return. SectionInstance is zero based.
 319   @param  Buffer               Pointer to a pointer to a buffer in which the section contents are returned, not
 320                                including the section header. Caller is responsible to free this memory.
 321   @param  Size                 Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
 322                                *Buffer.
 323
 324
 325   @retval  EFI_SUCCESS        The image is found and data and size is returned.
 326   @retval  EFI_UNSUPPORTED   FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.
 327   @retval  EFI_NOT_FOUND      The image specified by NameGuid and SectionType can't be found.
 328   @retval  EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
 329   @retval  EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
 330   @retval  EFI_ACCESS_DENIED  The firmware volume containing the searched Firmware File is configured to disallow reads.
 331
 332 **/
 333 EFI_STATUS
 334 EFIAPI
 335 GetSectionFromFv (
 336   IN  CONST EFI_GUID                *NameGuid,
 337   IN  EFI_SECTION_TYPE              SectionType,
 338   IN  UINTN                         SectionInstance,
 339   OUT VOID                          **Buffer,
 340   OUT UINTN                         *Size
 341     )
 342 {
 343   return InternalGetSectionFromFv (
 344            InternalImageHandleToFvHandle(gImageHandle),
 345            NameGuid,
 346            SectionType,
 347            SectionInstance,
 348            Buffer,
 349            Size
 350            );
 351 }
 352
 353
 354 /**
 355   Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
 356
 357   GetSectionFromFfs () searches the specifc firmware section with type SectionType in the same firmware file from
 358   which the running image is loaded. The details of this search order is defined in description of
 359   EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection () found in PI Specification.
 360
 361   If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
 362   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
 363   is returned.
 364
 365
 366   The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
 367   by this function. This function can only be called at TPL_NOTIFY and below.
 368
 369   If Buffer is NULL, then ASSERT();
 370   If Size is NULL, then ASSERT().
 371
 372   @param  SectionType          Indicates the section type to return. SectionType in conjunction with
 373                                SectionInstance indicates which section to return. Type
 374                                EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
 375   @param  SectionInstance      Indicates which instance of sections with a type of SectionType to return.
 376                                SectionType in conjunction with SectionInstance indicates which section to
 377                                return. SectionInstance is zero based.
 378   @param  Buffer               Pointer to a pointer to a buffer in which the section contents are returned, not
 379                                including the section header. Caller is responsible to free this memory.
 380   @param  Size                 Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
 381                                *Buffer.
 382
 383   @retval  EFI_SUCCESS        The image is found and data and size is returned.
 384   @retval  EFI_NOT_FOUND      The image specified by NameGuid and SectionType can't be found.
 385   @retval  EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
 386   @retval  EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
 387   @retval  EFI_ACCESS_DENIED  The firmware volume containing the searched Firmware File is configured to disallow reads.
 388
 389 **/
 390 EFI_STATUS
 391 EFIAPI
 392 GetSectionFromFfs (
 393   IN  EFI_SECTION_TYPE              SectionType,
 394   IN  UINTN                         SectionInstance,
 395   OUT VOID                          **Buffer,
 396   OUT UINTN                         *Size
 397     )
 398 {
 399   return InternalGetSectionFromFv(
 400            InternalImageHandleToFvHandle(gImageHandle),
 401            &gEfiCallerIdGuid,
 402            SectionType,
 403            SectionInstance,
 404            Buffer,
 405            Size
 406            );
 407 }
 408