// 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
\r
-Returns:\r
\r
- Status code.\r
+/**\r
+ Loads, relocates, and invokes a PE/COFF image\r
\r
---*/\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