Update function description per UEFI2.3d. The main changes include:

[mirror_edk2.git] / MdeModulePkg / Core / Dxe / Image / Image.h

/** @file\r
  Data structure and functions to load and unload PeImage.\r
\r
Copyright (c) 2006 - 2009, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution.  The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
\r
#ifndef _IMAGE_H_\r
#define _IMAGE_H_\r
\r
#define LOADED_IMAGE_PRIVATE_DATA_SIGNATURE   SIGNATURE_32('l','d','r','i')\r
\r
typedef struct {\r
  UINTN                       Signature;\r
  /// Image handle\r
  EFI_HANDLE                  Handle;   \r
  /// Image type\r
  UINTN                       Type;           \r
  /// If entrypoint has been called\r
  BOOLEAN                     Started;        \r
  /// The image's entry point\r
  EFI_IMAGE_ENTRY_POINT       EntryPoint;     \r
  /// loaded image protocol\r
  EFI_LOADED_IMAGE_PROTOCOL   Info;           \r
  /// Location in memory\r
  EFI_PHYSICAL_ADDRESS        ImageBasePage;  \r
  /// Number of pages\r
  UINTN                       NumberOfPages;  \r
  /// Original fixup data\r
  CHAR8                       *FixupData;     \r
  /// Tpl of started image\r
  EFI_TPL                     Tpl;            \r
  /// Status returned by started image\r
  EFI_STATUS                  Status;         \r
  /// Size of ExitData from started image\r
  UINTN                       ExitDataSize;   \r
  /// Pointer to exit data from started image\r
  VOID                        *ExitData;      \r
  /// Pointer to pool allocation for context save/retore\r
  VOID                        *JumpBuffer;    \r
  /// Pointer to buffer for context save/retore\r
  BASE_LIBRARY_JUMP_BUFFER    *JumpContext;  \r
  /// Machine type from PE image\r
  UINT16                      Machine;        \r
  /// EBC Protocol pointer\r
  EFI_EBC_PROTOCOL            *Ebc;           \r
  /// Runtime image list\r
  EFI_RUNTIME_IMAGE_ENTRY     *RuntimeData;   \r
  /// Pointer to Loaded Image Device Path Protocl\r
  EFI_DEVICE_PATH_PROTOCOL    *LoadedImageDevicePath;  \r
  /// PeCoffLoader ImageContext\r
  PE_COFF_LOADER_IMAGE_CONTEXT  ImageContext; \r
\r
} LOADED_IMAGE_PRIVATE_DATA;\r
\r
#define LOADED_IMAGE_PRIVATE_DATA_FROM_THIS(a) \\r
          CR(a, LOADED_IMAGE_PRIVATE_DATA, Info, LOADED_IMAGE_PRIVATE_DATA_SIGNATURE)\r
\r
\r
#define LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE  SIGNATURE_32('l','p','e','i')\r
\r
typedef struct {\r
  UINTN                       Signature;\r
  /// Image handle\r
  EFI_HANDLE                  Handle;         \r
  EFI_PE32_IMAGE_PROTOCOL     Pe32Image;\r
} LOAD_PE32_IMAGE_PRIVATE_DATA;\r
\r
#define LOAD_PE32_IMAGE_PRIVATE_DATA_FROM_THIS(a) \\r
          CR(a, LOAD_PE32_IMAGE_PRIVATE_DATA, Pe32Image, LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE)\r
\r
\r
//\r
// Private Data Types\r
//\r
#define IMAGE_FILE_HANDLE_SIGNATURE       SIGNATURE_32('i','m','g','f')\r
typedef struct {\r
  UINTN               Signature;\r
  BOOLEAN             FreeBuffer;\r
  VOID                *Source;\r
  UINTN               SourceSize;\r
} IMAGE_FILE_HANDLE;\r
\r
/**\r
  Loads an EFI image into memory and returns a handle to the image with extended parameters.\r
\r
  @param  This                    Calling context\r
  @param  ParentImageHandle       The caller's image handle.\r
  @param  FilePath                The specific file path from which the image is\r
                                  loaded.\r
  @param  SourceBuffer            If not NULL, a pointer to the memory location\r
                                  containing a copy of the image to be loaded.\r
  @param  SourceSize              The size in bytes of SourceBuffer.\r
  @param  DstBuffer               The buffer to store the image.\r
  @param  NumberOfPages           For input, specifies the space size of the\r
                                  image by caller if not NULL. For output,\r
                                  specifies the actual space size needed.\r
  @param  ImageHandle             Image handle for output.\r
  @param  EntryPoint              Image entry point for output.\r
  @param  Attribute               The bit mask of attributes to set for the load\r
                                  PE image.\r
\r
  @retval EFI_SUCCESS             The image was loaded into memory.\r
  @retval EFI_NOT_FOUND           The FilePath was not found.\r
  @retval EFI_INVALID_PARAMETER   One of the parameters has an invalid value.\r
  @retval EFI_UNSUPPORTED         The image type is not supported, or the device\r
                                  path cannot be parsed to locate the proper\r
                                  protocol for loading the file.\r
  @retval EFI_OUT_OF_RESOURCES    Image was not loaded due to insufficient\r
                                  resources.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
CoreLoadImageEx (\r
  IN  EFI_PE32_IMAGE_PROTOCOL          *This,\r
  IN  EFI_HANDLE                       ParentImageHandle,\r
  IN  EFI_DEVICE_PATH_PROTOCOL         *FilePath,\r
  IN  VOID                             *SourceBuffer       OPTIONAL,\r
  IN  UINTN                            SourceSize,\r
  IN  EFI_PHYSICAL_ADDRESS             DstBuffer           OPTIONAL,\r
  OUT UINTN                            *NumberOfPages      OPTIONAL,\r
  OUT EFI_HANDLE                       *ImageHandle,\r
  OUT EFI_PHYSICAL_ADDRESS             *EntryPoint         OPTIONAL,\r
  IN  UINT32                           Attribute\r
  );\r
\r
\r
/**\r
  Unload the specified image.\r
\r
  @param  This                    Indicates the calling context.\r
  @param  ImageHandle             The specified image handle.\r
\r
  @retval EFI_INVALID_PARAMETER   Image handle is NULL.\r
  @retval EFI_UNSUPPORTED         Attempt to unload an unsupported image.\r
  @retval EFI_SUCCESS             Image successfully unloaded.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
CoreUnloadImageEx (\r
  IN EFI_PE32_IMAGE_PROTOCOL  *This,\r
  IN EFI_HANDLE                         ImageHandle\r
  );\r
#endif\r