[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 - 2008, Intel Corporation. <BR>\r
All rights reserved. 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
/**\r
  Opens a file for (simple) reading.  The simple read abstraction\r
  will access the file either from a memory copy, from a file\r
  system interface, or from the load file interface.\r
\r
  @param  BootPolicy             Policy for Open Image File.\r
  @param  SourceBuffer           Pointer to the memory location containing copy\r
                                 of the image to be loaded.\r
  @param  SourceSize             The size in bytes of SourceBuffer.\r
  @param  FilePath               The specific file path from which the image is\r
                                 loaded\r
  @param  DeviceHandle           Pointer to the return device handle.\r
  @param  ImageFileHandle        Pointer to the image file handle.\r
  @param  AuthenticationStatus   Pointer to a caller-allocated UINT32 in which\r
                                 the authentication status is returned.\r
\r
  @retval EFI_SUCCESS            Image file successfully opened.\r
  @retval EFI_LOAD_ERROR         If the caller passed a copy of the file, and\r
                                 SourceSize is 0.\r
  @retval EFI_INVALID_PARAMETER  File path is not valid.\r
  @retval EFI_NOT_FOUND          File not found.\r
\r
**/\r
EFI_STATUS\r
CoreOpenImageFile (\r
  IN BOOLEAN                        BootPolicy,\r
  IN VOID                           *SourceBuffer   OPTIONAL,\r
  IN UINTN                          SourceSize,\r
  IN OUT EFI_DEVICE_PATH_PROTOCOL   **FilePath,\r
  OUT EFI_HANDLE                    *DeviceHandle,\r
  IN IMAGE_FILE_HANDLE              *ImageFileHandle,\r
  OUT UINT32                        *AuthenticationStatus\r
  );\r
\r
\r
\r
/**\r
  Read image file (specified by UserHandle) into user specified buffer with specified offset\r
  and length.\r
\r
  @param  UserHandle             Image file handle\r
  @param  Offset                 Offset to the source file\r
  @param  ReadSize               For input, pointer of size to read; For output,\r
                                 pointer of size actually read.\r
  @param  Buffer                 Buffer to write into\r
\r
  @retval EFI_SUCCESS            Successfully read the specified part of file\r
                                 into buffer.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
CoreReadImageFile (\r
  IN     VOID    *UserHandle,\r
  IN     UINTN   Offset,\r
  IN OUT UINTN   *ReadSize,\r
  OUT    VOID    *Buffer\r
  );\r
\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
Commit	Line	Data
	1	/** @file\r
	2	Data structure and functions to load and unload PeImage.\r
	3	\r
	4	Copyright (c) 2006 - 2008, Intel Corporation. <BR>\r
	5	All rights reserved. This program and the accompanying materials\r
	6	are licensed and made available under the terms and conditions of the BSD License\r
	7	which accompanies this distribution. The full text of the license may be found at\r
	8	http://opensource.org/licenses/bsd-license.php\r
	9	\r
	10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	12	\r
	13	**/\r
	14	\r
	15	\r
	16	#ifndef _IMAGE_H_\r
	17	#define _IMAGE_H_\r
	18	\r
	19	#define LOADED_IMAGE_PRIVATE_DATA_SIGNATURE SIGNATURE_32('l','d','r','i')\r
	20	\r
	21	typedef struct {\r
	22	UINTN Signature;\r
	23	/// Image handle\r
	24	EFI_HANDLE Handle; \r
	25	/// Image type\r
	26	UINTN Type; \r
	27	/// If entrypoint has been called\r
	28	BOOLEAN Started; \r
	29	/// The image's entry point\r
	30	EFI_IMAGE_ENTRY_POINT EntryPoint; \r
	31	/// loaded image protocol\r
	32	EFI_LOADED_IMAGE_PROTOCOL Info; \r
	33	/// Location in memory\r
	34	EFI_PHYSICAL_ADDRESS ImageBasePage; \r
	35	/// Number of pages\r
	36	UINTN NumberOfPages; \r
	37	/// Original fixup data\r
	38	CHAR8 *FixupData; \r
	39	/// Tpl of started image\r
	40	EFI_TPL Tpl; \r
	41	/// Status returned by started image\r
	42	EFI_STATUS Status; \r
	43	/// Size of ExitData from started image\r
	44	UINTN ExitDataSize; \r
	45	/// Pointer to exit data from started image\r
	46	VOID *ExitData; \r
	47	/// Pointer to pool allocation for context save/retore\r
	48	VOID *JumpBuffer; \r
	49	/// Pointer to buffer for context save/retore\r
	50	BASE_LIBRARY_JUMP_BUFFER *JumpContext; \r
	51	/// Machine type from PE image\r
	52	UINT16 Machine; \r
	53	/// EBC Protocol pointer\r
	54	EFI_EBC_PROTOCOL *Ebc; \r
	55	/// Runtime image list\r
	56	EFI_RUNTIME_IMAGE_ENTRY *RuntimeData; \r
	57	/// Pointer to Loaded Image Device Path Protocl\r
	58	EFI_DEVICE_PATH_PROTOCOL *LoadedImageDevicePath; \r
	59	/// PeCoffLoader ImageContext\r
	60	PE_COFF_LOADER_IMAGE_CONTEXT ImageContext; \r
	61	\r
	62	} LOADED_IMAGE_PRIVATE_DATA;\r
	63	\r
	64	#define LOADED_IMAGE_PRIVATE_DATA_FROM_THIS(a) \\r
	65	CR(a, LOADED_IMAGE_PRIVATE_DATA, Info, LOADED_IMAGE_PRIVATE_DATA_SIGNATURE)\r
	66	\r
	67	\r
	68	#define LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE SIGNATURE_32('l','p','e','i')\r
	69	\r
	70	typedef struct {\r
	71	UINTN Signature;\r
	72	/// Image handle\r
	73	EFI_HANDLE Handle; \r
	74	EFI_PE32_IMAGE_PROTOCOL Pe32Image;\r
	75	} LOAD_PE32_IMAGE_PRIVATE_DATA;\r
	76	\r
	77	#define LOAD_PE32_IMAGE_PRIVATE_DATA_FROM_THIS(a) \\r
	78	CR(a, LOAD_PE32_IMAGE_PRIVATE_DATA, Pe32Image, LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE)\r
	79	\r
	80	\r
	81	//\r
	82	// Private Data Types\r
	83	//\r
	84	#define IMAGE_FILE_HANDLE_SIGNATURE SIGNATURE_32('i','m','g','f')\r
	85	typedef struct {\r
	86	UINTN Signature;\r
	87	BOOLEAN FreeBuffer;\r
	88	VOID *Source;\r
	89	UINTN SourceSize;\r
	90	} IMAGE_FILE_HANDLE;\r
	91	\r
	92	\r
	93	/**\r
	94	Opens a file for (simple) reading. The simple read abstraction\r
	95	will access the file either from a memory copy, from a file\r
	96	system interface, or from the load file interface.\r
	97	\r
	98	@param BootPolicy Policy for Open Image File.\r
	99	@param SourceBuffer Pointer to the memory location containing copy\r
	100	of the image to be loaded.\r
	101	@param SourceSize The size in bytes of SourceBuffer.\r
	102	@param FilePath The specific file path from which the image is\r
	103	loaded\r
	104	@param DeviceHandle Pointer to the return device handle.\r
	105	@param ImageFileHandle Pointer to the image file handle.\r
	106	@param AuthenticationStatus Pointer to a caller-allocated UINT32 in which\r
	107	the authentication status is returned.\r
	108	\r
	109	@retval EFI_SUCCESS Image file successfully opened.\r
	110	@retval EFI_LOAD_ERROR If the caller passed a copy of the file, and\r
	111	SourceSize is 0.\r
	112	@retval EFI_INVALID_PARAMETER File path is not valid.\r
	113	@retval EFI_NOT_FOUND File not found.\r
	114	\r
	115	**/\r
	116	EFI_STATUS\r
	117	CoreOpenImageFile (\r
	118	IN BOOLEAN BootPolicy,\r
	119	IN VOID *SourceBuffer OPTIONAL,\r
	120	IN UINTN SourceSize,\r
	121	IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath,\r
	122	OUT EFI_HANDLE *DeviceHandle,\r
	123	IN IMAGE_FILE_HANDLE *ImageFileHandle,\r
	124	OUT UINT32 *AuthenticationStatus\r
	125	);\r
	126	\r
	127	\r
	128	\r
	129	/**\r
	130	Read image file (specified by UserHandle) into user specified buffer with specified offset\r
	131	and length.\r
	132	\r
	133	@param UserHandle Image file handle\r
	134	@param Offset Offset to the source file\r
	135	@param ReadSize For input, pointer of size to read; For output,\r
	136	pointer of size actually read.\r
	137	@param Buffer Buffer to write into\r
	138	\r
	139	@retval EFI_SUCCESS Successfully read the specified part of file\r
	140	into buffer.\r
	141	\r
	142	**/\r
	143	EFI_STATUS\r
	144	EFIAPI\r
	145	CoreReadImageFile (\r
	146	IN VOID *UserHandle,\r
	147	IN UINTN Offset,\r
	148	IN OUT UINTN *ReadSize,\r
	149	OUT VOID *Buffer\r
	150	);\r
	151	\r
	152	\r
	153	/**\r
	154	Loads an EFI image into memory and returns a handle to the image with extended parameters.\r
	155	\r
	156	@param This Calling context\r
	157	@param ParentImageHandle The caller's image handle.\r
	158	@param FilePath The specific file path from which the image is\r
	159	loaded.\r
	160	@param SourceBuffer If not NULL, a pointer to the memory location\r
	161	containing a copy of the image to be loaded.\r
	162	@param SourceSize The size in bytes of SourceBuffer.\r
	163	@param DstBuffer The buffer to store the image.\r
	164	@param NumberOfPages For input, specifies the space size of the\r
	165	image by caller if not NULL. For output,\r
	166	specifies the actual space size needed.\r
	167	@param ImageHandle Image handle for output.\r
	168	@param EntryPoint Image entry point for output.\r
	169	@param Attribute The bit mask of attributes to set for the load\r
	170	PE image.\r
	171	\r
	172	@retval EFI_SUCCESS The image was loaded into memory.\r
	173	@retval EFI_NOT_FOUND The FilePath was not found.\r
	174	@retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.\r
	175	@retval EFI_UNSUPPORTED The image type is not supported, or the device\r
	176	path cannot be parsed to locate the proper\r
	177	protocol for loading the file.\r
	178	@retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient\r
	179	resources.\r
	180	\r
	181	**/\r
	182	EFI_STATUS\r
	183	EFIAPI\r
	184	CoreLoadImageEx (\r
	185	IN EFI_PE32_IMAGE_PROTOCOL *This,\r
	186	IN EFI_HANDLE ParentImageHandle,\r
	187	IN EFI_DEVICE_PATH_PROTOCOL *FilePath,\r
	188	IN VOID *SourceBuffer OPTIONAL,\r
	189	IN UINTN SourceSize,\r
	190	IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL,\r
	191	OUT UINTN *NumberOfPages OPTIONAL,\r
	192	OUT EFI_HANDLE *ImageHandle,\r
	193	OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,\r
	194	IN UINT32 Attribute\r
	195	);\r
	196	\r
	197	\r
	198	/**\r
	199	Unload the specified image.\r
	200	\r
	201	@param This Indicates the calling context.\r
	202	@param ImageHandle The specified image handle.\r
	203	\r
	204	@retval EFI_INVALID_PARAMETER Image handle is NULL.\r
	205	@retval EFI_UNSUPPORTED Attempt to unload an unsupported image.\r
	206	@retval EFI_SUCCESS Image successfully unloaded.\r
	207	\r
	208	**/\r
	209	EFI_STATUS\r
	210	EFIAPI\r
	211	CoreUnloadImageEx (\r
	212	IN EFI_PE32_IMAGE_PROTOCOL *This,\r
	213	IN EFI_HANDLE ImageHandle\r
	214	);\r
	215	#endif\r