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