-/*++\r
-\r
-Copyright (c) 2006, Intel Corporation\r
+/** @file \r
+ \r
+ Data structure and functions to load and unload PeImage.\r
+ \r
+Copyright (c) 2006 - 2008, Intel Corporation\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
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
-Module Name:\r
-\r
- Image.h\r
-\r
-Abstract:\r
-\r
-Revision History\r
-\r
---*/\r
+**/\r
\r
\r
#ifndef _IMAGE_H_\r
\r
EFI_RUNTIME_IMAGE_ENTRY *RuntimeData; // Runtime image list\r
\r
- EFI_DEVICE_PATH_PROTOCOL *DeviceHandleDevicePath;\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
// 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 IMAGE_FILE_HANDLE *ImageFileHandle,\r
OUT UINT32 *AuthenticationStatus\r
)\r
-/*++\r
-\r
-Routine Description:\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
-Arguments:\r
+;\r
\r
- BootPolicy - Policy for Open Image File.\r
- SourceBuffer - Pointer to the memory location containing copy\r
- of the image to be loaded.\r
- SourceSize - The size in bytes of SourceBuffer.\r
- FilePath - The specific file path from which the image is loaded\r
- DeviceHandle - Pointer to the return device handle.\r
- ImageFileHandle - Pointer to the image file handle.\r
- AuthenticationStatus - Pointer to a caller-allocated UINT32 in which the authentication status is returned.\r
\r
-Returns:\r
\r
- A handle to access the file\r
+/**\r
+ Read image file (specified by UserHandle) into user specified buffer with specified offset\r
+ and length.\r
\r
---*/\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 OUT UINTN *ReadSize,\r
OUT VOID *Buffer\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Read image file (specified by UserHandle) into user specified buffer with specified offset\r
- and length.\r
-\r
-Arguments:\r
-\r
- UserHandle - Image file handle\r
-\r
- Offset - Offset to the source file\r
-\r
- ReadSize - For input, pointer of size to read;\r
- For output, pointer of size actually read.\r
-\r
- Buffer - Buffer to write into\r
+;\r
\r
-Returns:\r
\r
- EFI_SUCCESS - Successfully read the specified part of file into buffer.\r
+/**\r
+ A function out of date, should be removed.\r
\r
---*/\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
-Routine Description:\r
-\r
- A function out of date, should be removed.\r
-\r
-Arguments:\r
-\r
- ImageFileHandle - Handle of the file to close\r
-\r
-Returns:\r
-\r
- None\r
-\r
---*/\r
;\r
\r
//\r
// Image processing worker functions\r
//\r
+\r
+/**\r
+ Search a handle to a device on a specified device path that supports a specified protocol,\r
+ interface of that protocol on that handle is another output.\r
+\r
+ @param Protocol The protocol to search for \r
+ @param FilePath The specified device path \r
+ @param Interface Interface of the protocol on the handle \r
+ @param Handle The handle to the device on the specified device \r
+ path that supports the protocol. \r
+\r
+ @return Status code.\r
+\r
+**/\r
EFI_STATUS\r
CoreDevicePathToInterface (\r
IN EFI_GUID *Protocol,\r
OUT VOID **Interface,\r
OUT EFI_HANDLE *Handle\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Search a handle to a device on a specified device path that supports a specified protocol,\r
- interface of that protocol on that handle is another output.\r
-\r
-Arguments:\r
-\r
- Protocol - The protocol to search for\r
-\r
- FilePath - The specified device path\r
-\r
- Interface - Interface of the protocol on the handle\r
-\r
- Handle - The handle to the device on the specified device path that supports the protocol.\r
-\r
-Returns:\r
+;\r
\r
- Status code.\r
\r
---*/\r
-;\r
+/**\r
+ Loads, relocates, and invokes a PE/COFF image\r
\r
+ @param BootPolicy If TRUE, indicates that the request originates \r
+ from the boot manager, and that the boot \r
+ manager is attempting to load FilePath as a \r
+ boot selection. \r
+ @param Pe32Handle The handle of PE32 image \r
+ @param Image PE image to be loaded \r
+ @param DstBuffer The buffer to store the image \r
+ @param EntryPoint A pointer to the entry point \r
+ @param Attribute The bit mask of attributes to set for the load \r
+ PE image \r
+\r
+ @retval EFI_SUCCESS The file was loaded, relocated, and invoked \r
+ @retval EFI_OUT_OF_RESOURCES There was not enough memory to load and \r
+ relocate the PE/COFF file \r
+ @retval EFI_INVALID_PARAMETER Invalid parameter \r
+ @retval EFI_BUFFER_TOO_SMALL Buffer for image is too small\r
+\r
+**/\r
EFI_STATUS\r
CoreLoadPeImage (\r
IN BOOLEAN BootPolicy,\r
OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,\r
IN UINT32 Attribute\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Loads, relocates, and invokes a PE/COFF image\r
-\r
-Arguments:\r
-\r
- BootPolicy - Policy for Open Image File.\r
- Pe32Handle - The handle of PE32 image\r
- Image - PE image to be loaded\r
- DstBuffer - The buffer to store the image\r
- EntryPoint - A pointer to the entry point\r
- Attribute - The bit mask of attributes to set for the load PE image\r
-\r
-Returns:\r
-\r
- EFI_SUCCESS - The file was loaded, relocated, and invoked\r
+;\r
\r
- EFI_OUT_OF_RESOURCES - There was not enough memory to load and relocate the PE/COFF file\r
\r
- EFI_INVALID_PARAMETER - Invalid parameter\r
+/**\r
+ Get the image's private data from its handle.\r
\r
- EFI_BUFFER_TOO_SMALL - Buffer for image is too small\r
+ @param ImageHandle The image handle \r
\r
---*/\r
-;\r
+ @return Return the image private data associated with ImageHandle.\r
\r
+**/\r
LOADED_IMAGE_PRIVATE_DATA *\r
CoreLoadedImageInfo (\r
IN EFI_HANDLE ImageHandle\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
-\r
- ImageHandle - TODO: add argument description\r
+;\r
\r
-Returns:\r
\r
- TODO: add return values\r
+/**\r
+ Unloads EFI image from memory.\r
\r
---*/\r
-;\r
+ @param Image EFI image \r
+ @param FreePage Free allocated pages\r
\r
+**/\r
VOID\r
CoreUnloadAndCloseImage (\r
IN LOADED_IMAGE_PRIVATE_DATA *Image,\r
IN BOOLEAN FreePage\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Unloads EFI image from memory.\r
-\r
-Arguments:\r
-\r
- Image - EFI image\r
- FreePage - Free allocated pages\r
-\r
-Returns:\r
-\r
- None\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
OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,\r
IN UINT32 Attribute\r
)\r
-/*++\r
+;\r
\r
-Routine Description:\r
\r
- Loads an EFI image into memory and returns a handle to the image with extended parameters.\r
+/**\r
+ Unload the specified image.\r
\r
-Arguments:\r
-\r
- ParentImageHandle - The caller's image handle.\r
- FilePath - The specific file path from which the image is loaded.\r
- SourceBuffer - If not NULL, a pointer to the memory location containing a copy of\r
- the image to be loaded.\r
- SourceSize - The size in bytes of SourceBuffer.\r
- DstBuffer - The buffer to store the image.\r
- NumberOfPages - For input, specifies the space size of the image by caller if not NULL.\r
- For output, specifies the actual space size needed.\r
- ImageHandle - Image handle for output.\r
- EntryPoint - Image entry point for output.\r
- Attribute - The bit mask of attributes to set for the load PE image.\r
-\r
-Returns:\r
-\r
- EFI_SUCCESS - The image was loaded into memory.\r
- EFI_NOT_FOUND - The FilePath was not found.\r
- EFI_INVALID_PARAMETER - One of the parameters has an invalid value.\r
- EFI_UNSUPPORTED - The image type is not supported, or the device path cannot be\r
- parsed to locate the proper protocol for loading the file.\r
- EFI_OUT_OF_RESOURCES - Image was not loaded due to insufficient resources.\r
---*/\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
-/*++\r
-\r
-Routine Description:\r
-\r
- Unload the specified image.\r
-\r
-Arguments:\r
-\r
- This - Indicates the calling context.\r
-\r
- ImageHandle - The specified image handle.\r
-\r
-Returns:\r
-\r
- EFI_INVALID_PARAMETER - Image handle is NULL.\r
-\r
- EFI_UNSUPPORTED - Attempt to unload an unsupported image.\r
-\r
- EFI_SUCCESS - Image successfully unloaded.\r
-\r
---*/\r
;\r
#endif\r
projects / mirror_edk2.git / blobdiff