diff options
Diffstat (limited to 'MdeModulePkg/Core/Dxe/Image.h')
| -rw-r--r-- | MdeModulePkg/Core/Dxe/Image.h | 304 |
1 files changed, 127 insertions, 177 deletions
diff --git a/MdeModulePkg/Core/Dxe/Image.h b/MdeModulePkg/Core/Dxe/Image.h index e233104..0b8201e 100644 --- a/MdeModulePkg/Core/Dxe/Image.h +++ b/MdeModulePkg/Core/Dxe/Image.h @@ -89,6 +89,30 @@ typedef struct { // Abstractions for reading image contents
//
+
+/**
+ Opens a file for (simple) reading. The simple read abstraction
+ will access the file either from a memory copy, from a file
+ system interface, or from the load file interface.
+
+ @param BootPolicy Policy for Open Image File.
+ @param SourceBuffer Pointer to the memory location containing copy
+ of the image to be loaded.
+ @param SourceSize The size in bytes of SourceBuffer.
+ @param FilePath The specific file path from which the image is
+ loaded
+ @param DeviceHandle Pointer to the return device handle.
+ @param ImageFileHandle Pointer to the image file handle.
+ @param AuthenticationStatus Pointer to a caller-allocated UINT32 in which
+ the authentication status is returned.
+
+ @retval EFI_SUCCESS Image file successfully opened.
+ @retval EFI_LOAD_ERROR If the caller passed a copy of the file, and
+ SourceSize is 0.
+ @retval EFI_INVALID_PARAMETER File path is not valid.
+ @retval EFI_NOT_FOUND File not found.
+
+**/
EFI_STATUS
CoreOpenImageFile (
IN BOOLEAN BootPolicy,
@@ -99,33 +123,24 @@ CoreOpenImageFile ( IN IMAGE_FILE_HANDLE *ImageFileHandle,
OUT UINT32 *AuthenticationStatus
)
-/*++
-
-Routine Description:
-
- Opens a file for (simple) reading. The simple read abstraction
- will access the file either from a memory copy, from a file
- system interface, or from the load file interface.
-
-Arguments:
+;
- BootPolicy - Policy for Open Image File.
- SourceBuffer - Pointer to the memory location containing copy
- of the image to be loaded.
- SourceSize - The size in bytes of SourceBuffer.
- FilePath - The specific file path from which the image is loaded
- DeviceHandle - Pointer to the return device handle.
- ImageFileHandle - Pointer to the image file handle.
- AuthenticationStatus - Pointer to a caller-allocated UINT32 in which the authentication status is returned.
-Returns:
- A handle to access the file
+/**
+ Read image file (specified by UserHandle) into user specified buffer with specified offset
+ and length.
---*/
-;
+ @param UserHandle Image file handle
+ @param Offset Offset to the source file
+ @param ReadSize For input, pointer of size to read; For output,
+ pointer of size actually read.
+ @param Buffer Buffer to write into
+ @retval EFI_SUCCESS Successfully read the specified part of file
+ into buffer.
+**/
EFI_STATUS
EFIAPI
CoreReadImageFile (
@@ -134,56 +149,39 @@ CoreReadImageFile ( IN OUT UINTN *ReadSize,
OUT VOID *Buffer
)
-/*++
-
-Routine Description:
-
- Read image file (specified by UserHandle) into user specified buffer with specified offset
- and length.
-
-Arguments:
-
- UserHandle - Image file handle
-
- Offset - Offset to the source file
-
- ReadSize - For input, pointer of size to read;
- For output, pointer of size actually read.
-
- Buffer - Buffer to write into
+;
-Returns:
- EFI_SUCCESS - Successfully read the specified part of file into buffer.
+/**
+ A function out of date, should be removed.
---*/
-;
+ @param ImageFileHandle Handle of the file to close
+**/
VOID
EFIAPI
CoreCloseImageFile (
IN IMAGE_FILE_HANDLE *ImageFileHandle
)
-/*++
-
-Routine Description:
-
- A function out of date, should be removed.
-
-Arguments:
-
- ImageFileHandle - Handle of the file to close
-
-Returns:
-
- None
-
---*/
;
//
// Image processing worker functions
//
+
+/**
+ Search a handle to a device on a specified device path that supports a specified protocol,
+ interface of that protocol on that handle is another output.
+
+ @param Protocol The protocol to search for
+ @param FilePath The specified device path
+ @param Interface Interface of the protocol on the handle
+ @param Handle The handle to the device on the specified device
+ path that supports the protocol.
+
+ @return Status code.
+
+**/
EFI_STATUS
CoreDevicePathToInterface (
IN EFI_GUID *Protocol,
@@ -191,30 +189,30 @@ CoreDevicePathToInterface ( OUT VOID **Interface,
OUT EFI_HANDLE *Handle
)
-/*++
-
-Routine Description:
-
- Search a handle to a device on a specified device path that supports a specified protocol,
- interface of that protocol on that handle is another output.
-
-Arguments:
-
- Protocol - The protocol to search for
-
- FilePath - The specified device path
-
- Interface - Interface of the protocol on the handle
-
- Handle - The handle to the device on the specified device path that supports the protocol.
+;
-Returns:
- Status code.
+/**
+ Loads, relocates, and invokes a PE/COFF image
---*/
-;
+ @param BootPolicy If TRUE, indicates that the request originates
+ from the boot manager, and that the boot
+ manager is attempting to load FilePath as a
+ boot selection.
+ @param Pe32Handle The handle of PE32 image
+ @param Image PE image to be loaded
+ @param DstBuffer The buffer to store the image
+ @param EntryPoint A pointer to the entry point
+ @param Attribute The bit mask of attributes to set for the load
+ PE image
+
+ @retval EFI_SUCCESS The file was loaded, relocated, and invoked
+ @retval EFI_OUT_OF_RESOURCES There was not enough memory to load and
+ relocate the PE/COFF file
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_BUFFER_TOO_SMALL Buffer for image is too small
+**/
EFI_STATUS
CoreLoadPeImage (
IN BOOLEAN BootPolicy,
@@ -224,76 +222,36 @@ CoreLoadPeImage ( OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,
IN UINT32 Attribute
)
-/*++
-
-Routine Description:
-
- Loads, relocates, and invokes a PE/COFF image
-
-Arguments:
-
- BootPolicy - Policy for Open Image File.
- Pe32Handle - The handle of PE32 image
- Image - PE image to be loaded
- DstBuffer - The buffer to store the image
- EntryPoint - A pointer to the entry point
- Attribute - The bit mask of attributes to set for the load PE image
-
-Returns:
-
- EFI_SUCCESS - The file was loaded, relocated, and invoked
+;
- EFI_OUT_OF_RESOURCES - There was not enough memory to load and relocate the PE/COFF file
- EFI_INVALID_PARAMETER - Invalid parameter
+/**
+ Get the image's private data from its handle.
- EFI_BUFFER_TOO_SMALL - Buffer for image is too small
+ @param ImageHandle The image handle
---*/
-;
+ @return Return the image private data associated with ImageHandle.
+**/
LOADED_IMAGE_PRIVATE_DATA *
CoreLoadedImageInfo (
IN EFI_HANDLE ImageHandle
)
-/*++
-
-Routine Description:
-
- TODO: Add function description
-
-Arguments:
-
- ImageHandle - TODO: add argument description
+;
-Returns:
- TODO: add return values
+/**
+ Unloads EFI image from memory.
---*/
-;
+ @param Image EFI image
+ @param FreePage Free allocated pages
+**/
VOID
CoreUnloadAndCloseImage (
IN LOADED_IMAGE_PRIVATE_DATA *Image,
IN BOOLEAN FreePage
)
-/*++
-
-Routine Description:
-
- Unloads EFI image from memory.
-
-Arguments:
-
- Image - EFI image
- FreePage - Free allocated pages
-
-Returns:
-
- None
-
---*/
;
@@ -301,6 +259,36 @@ Returns: // Exported Image functions
//
+
+/**
+ Loads an EFI image into memory and returns a handle to the image with extended parameters.
+
+ @param This Calling context
+ @param ParentImageHandle The caller's image handle.
+ @param FilePath The specific file path from which the image is
+ loaded.
+ @param SourceBuffer If not NULL, a pointer to the memory location
+ containing a copy of the image to be loaded.
+ @param SourceSize The size in bytes of SourceBuffer.
+ @param DstBuffer The buffer to store the image.
+ @param NumberOfPages For input, specifies the space size of the
+ image by caller if not NULL. For output,
+ specifies the actual space size needed.
+ @param ImageHandle Image handle for output.
+ @param EntryPoint Image entry point for output.
+ @param Attribute The bit mask of attributes to set for the load
+ PE image.
+
+ @retval EFI_SUCCESS The image was loaded into memory.
+ @retval EFI_NOT_FOUND The FilePath was not found.
+ @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
+ @retval EFI_UNSUPPORTED The image type is not supported, or the device
+ path cannot be parsed to locate the proper
+ protocol for loading the file.
+ @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
+ resources.
+
+**/
EFI_STATUS
EFIAPI
CoreLoadImageEx (
@@ -315,63 +303,25 @@ CoreLoadImageEx ( OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,
IN UINT32 Attribute
)
-/*++
+;
-Routine Description:
- Loads an EFI image into memory and returns a handle to the image with extended parameters.
+/**
+ Unload the specified image.
-Arguments:
-
- ParentImageHandle - The caller's image handle.
- FilePath - The specific file path from which the image is loaded.
- SourceBuffer - If not NULL, a pointer to the memory location containing a copy of
- the image to be loaded.
- SourceSize - The size in bytes of SourceBuffer.
- DstBuffer - The buffer to store the image.
- NumberOfPages - For input, specifies the space size of the image by caller if not NULL.
- For output, specifies the actual space size needed.
- ImageHandle - Image handle for output.
- EntryPoint - Image entry point for output.
- Attribute - The bit mask of attributes to set for the load PE image.
-
-Returns:
-
- EFI_SUCCESS - The image was loaded into memory.
- EFI_NOT_FOUND - The FilePath was not found.
- EFI_INVALID_PARAMETER - One of the parameters has an invalid value.
- EFI_UNSUPPORTED - The image type is not supported, or the device path cannot be
- parsed to locate the proper protocol for loading the file.
- EFI_OUT_OF_RESOURCES - Image was not loaded due to insufficient resources.
---*/
-;
+ @param This Indicates the calling context.
+ @param ImageHandle The specified image handle.
+
+ @retval EFI_INVALID_PARAMETER Image handle is NULL.
+ @retval EFI_UNSUPPORTED Attempt to unload an unsupported image.
+ @retval EFI_SUCCESS Image successfully unloaded.
+**/
EFI_STATUS
EFIAPI
CoreUnloadImageEx (
IN EFI_PE32_IMAGE_PROTOCOL *This,
IN EFI_HANDLE ImageHandle
)
-/*++
-
-Routine Description:
-
- Unload the specified image.
-
-Arguments:
-
- This - Indicates the calling context.
-
- ImageHandle - The specified image handle.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Image handle is NULL.
-
- EFI_UNSUPPORTED - Attempt to unload an unsupported image.
-
- EFI_SUCCESS - Image successfully unloaded.
-
---*/
;
#endif
|