MdePkg/Include/Library/DxePiLib.h

   1 /** @file
   2   MDE PI library functions and macros
   3
   4   Copyright (c) 2007, Intel Corporation
   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 #ifndef __PI_LIB_H__
  16 #define __PI_LIB_H__
  17
  18 #include <Pi/PiFirmwareFile.h>
  19
  20
  21 /**
  22   Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
  23
  24   PiLibGetSectionFromAnyFv () is used to read a specific section from a file within a firmware volume. The function
  25   will search the first file with the specified name in all firmware volumes in the system. The search order for firmware
  26   volumes in the system is determistic but abitrary if no new firmware volume is added into the system between
  27   each calls of this function.
  28
  29   After the specific file is located, the function searches the specifc firmware section with type SectionType in this file.
  30   The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
  31   found in PI Specification.
  32
  33   If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
  34   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
  35   is returned.
  36
  37   The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
  38   by this function. This function can only be called at TPL_NOTIFY and below.
  39
  40   If NameGuid is NULL, then ASSERT();
  41   If Buffer is NULL, then ASSERT();
  42   If Size is NULL, then ASSERT().
  43
  44   @param  NameGuid             Pointer to an EFI_GUID, which indicates the file name from which the requested
  45                                section will be read. Type EFI_GUID is defined in
  46                                InstallProtocolInterface() in the UEFI 2.0 specification.
  47   @param  SectionType          Indicates the section type to return. SectionType in conjunction with
  48                                SectionInstance indicates which section to return. Type
  49                                EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
  50   @param  SectionInstance      Indicates which instance of sections with a type of SectionType to return.
  51                                SectionType in conjunction with SectionInstance indicates which section to
  52                                return. SectionInstance is zero based.
  53   @param  Buffer               Pointer to a pointer to a buffer in which the section contents are returned, not
  54                                including the section header. Caller is responsible to free this memory.
  55   @param  Size                 Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
  56                                *Buffer.
  57
  58   @retval  EFI_SUCCESS        The image is found and data and size is returned.
  59   @retval  EFI_NOT_FOUND      The image specified by NameGuid and SectionType can't be found.
  60   @retval  EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
  61   @retval  EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
  62   @retval  EFI_ACCESS_DENIED  The firmware volume containing the searched Firmware File is configured to disallow reads.
  63
  64 **/
  65 EFI_STATUS
  66 EFIAPI
  67 PiLibGetSectionFromAnyFv (
  68   IN  CONST EFI_GUID                *NameGuid,
  69   IN  EFI_SECTION_TYPE              SectionType,
  70   IN  UINTN                         SectionInstance,
  71   OUT VOID                          **Buffer,
  72   OUT UINTN                         *Size
  73   );
  74
  75 /**
  76   Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
  77
  78   PiLibGetSectionFromCurrentFv () is used to read a specific section from a file within the same firmware volume from which
  79   the running image is loaded. If the specific file is found, the function searches the specifc firmware section with type SectionType.
  80   The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
  81   found in PI Specification.
  82
  83   If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
  84   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
  85   is returned.
  86
  87   The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
  88   by this function. This function can be only called at TPL_NOTIFY and below.
  89
  90   If NameGuid is NULL, then ASSERT();
  91   If Buffer is NULL, then ASSERT();
  92   If Size is NULL, then ASSERT().
  93
  94   @param  NameGuid             Pointer to an EFI_GUID, which indicates the file name from which the requested
  95                                section will be read. Type EFI_GUID is defined in
  96                                InstallProtocolInterface() in the UEFI 2.0 specification.
  97   @param  SectionType          Indicates the section type to return. SectionType in conjunction with
  98                                SectionInstance indicates which section to return. Type
  99                                EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
 100   @param  SectionInstance      Indicates which instance of sections with a type of SectionType to return.
 101                                SectionType in conjunction with SectionInstance indicates which section to
 102                                return. SectionInstance is zero based.
 103   @param  Buffer               Pointer to a pointer to a buffer in which the section contents are returned, not
 104                                including the section header. Caller is responsible to free this memory.
 105   @param  Size                 Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
 106                                *Buffer.
 107
 108
 109   @retval  EFI_SUCCESS        The image is found and data and size is returned.
 110   @retval  EFI_UNSUPPORTED   FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.
 111   @retval  EFI_NOT_FOUND      The image specified by NameGuid and SectionType can't be found.
 112   @retval  EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
 113   @retval  EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
 114   @retval  EFI_ACCESS_DENIED  The firmware volume containing the searched Firmware File is configured to disallow reads.
 115
 116 **/
 117 EFI_STATUS
 118 EFIAPI
 119 PiLibGetSectionFromCurrentFv (
 120   IN  CONST EFI_GUID                *NameGuid,
 121   IN  EFI_SECTION_TYPE              SectionType,
 122   IN  UINTN                         SectionInstance,
 123   OUT VOID                          **Buffer,
 124   OUT UINTN                         *Size
 125   );
 126
 127
 128 /**
 129   Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
 130
 131   PiLibGetSectionFromCurrentFfs () searches the specifc firmware section with type SectionType in the same firmware file from
 132   which the running image is loaded. The details of this search order is defined in description of
 133   EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection () found in PI Specification.
 134
 135   If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
 136   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
 137   is returned.
 138
 139
 140   The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
 141   by this function. This function can only be called at TPL_NOTIFY and below.
 142
 143   If Buffer is NULL, then ASSERT();
 144   If Size is NULL, then ASSERT().
 145
 146   @param  SectionType          Indicates the section type to return. SectionType in conjunction with
 147                                SectionInstance indicates which section to return. Type
 148                                EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
 149   @param  SectionInstance      Indicates which instance of sections with a type of SectionType to return.
 150                                SectionType in conjunction with SectionInstance indicates which section to
 151                                return. SectionInstance is zero based.
 152   @param  Buffer               Pointer to a pointer to a buffer in which the section contents are returned, not
 153                                including the section header. Caller is responsible to free this memory.
 154   @param  Size                 Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
 155                                *Buffer.
 156
 157   @retval  EFI_SUCCESS        The image is found and data and size is returned.
 158   @retval  EFI_NOT_FOUND      The image specified by NameGuid and SectionType can't be found.
 159   @retval  EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
 160   @retval  EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
 161   @retval  EFI_ACCESS_DENIED  The firmware volume containing the searched Firmware File is configured to disallow reads.
 162
 163 **/
 164 EFI_STATUS
 165 EFIAPI
 166 PiLibGetSectionFromCurrentFfs (
 167   IN  EFI_SECTION_TYPE              SectionType,
 168   IN  UINTN                         SectionInstance,
 169   OUT VOID                          **Buffer,
 170   OUT UINTN                         *Size
 171   );
 172
 173 #endif
 174