move BUGBUG comments and add some comments to comply with Spec

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5897 6f19259b-4bc3-4df7-8a09-765794883524

1 files changed, 89 insertions, 4 deletions

diff --git a/MdePkg/Include/Library/PeCoffLib.h b/MdePkg/Include/Library/PeCoffLib.h
index 3f9fa6735f..47b70fff92 100644
--- a/MdePkg/Include/Library/PeCoffLib.h
+++ b/MdePkg/Include/Library/PeCoffLib.h
@@ -18,7 +18,6 @@
 #include <IndustryStandard/PeImage.h>

 //

 // Return status codes from the PE/COFF Loader services

-// BUGBUG: Find where used and see if can be replaced by RETURN_STATUS codes

 //

 #define IMAGE_ERROR_SUCCESS                      0

 #define IMAGE_ERROR_IMAGE_READ                   1  

@@ -44,30 +43,116 @@ RETURN_STATUS
   OUT    VOID   *Buffer

   );

 

-//

-// Context structure used while PE/COFF image is being loaded and relocated

-//

+///

+/// Context structure used while PE/COFF image is being loaded and relocated

+///

 typedef struct {

+  ///

+  /// Is set by PeCoffLoaderGetImageInfo() to the ImageBase in the PE/COFF header

+  ///

   PHYSICAL_ADDRESS                  ImageAddress;

+  ///

+  /// Is set by PeCoffLoaderGetImageInfo() to the SizeOfImage in the PE/COFF header.

+  /// Image size includes the size of Debug Entry if it is present.

+  ///

   UINT64                            ImageSize;

+  ///

+  /// Is set to zero by PeCoffLoaderGetImageInfo(). If DestinationAddress is non zero,

+  /// PeCoffLoaderRelocateImage() will relocate the image using this base address.

+  /// If the DestinationAddress is zero, the ImageAddress will be used as the base

+  /// address of relocation.

+  ///

   PHYSICAL_ADDRESS                  DestinationAddress;

+  ///

+  /// PeCoffLoaderLoadImage() sets EntryPoint to to the entry point of the PE/COFF image.

+  ///

   PHYSICAL_ADDRESS                  EntryPoint;

+  ///

+  /// Passed in by the caller to PeCoffLoaderGetImageInfo() and PeCoffLoaderLoadImage()

+  /// to abstract accessing the image from the library.

+  ///

   PE_COFF_LOADER_READ_FILE          ImageRead;

+  ///

+  /// Used as the FileHandle passed into the ImageRead function when it's called.

+  ///

   VOID                              *Handle;

+  ///

+  /// Caller allocated buffer of size FixupDataSize that can be optionally allocated

+  /// prior to calling PeCoffLoaderRelocateImage(). 

+  /// This buffer is filled with the information used to fix up the image. 

+  /// The fixups have been applied to the image and this entry is just for information.

+  ///

   VOID                              *FixupData;

+  ///

+  /// Is set by PeCoffLoaderGetImageInfo() to the Section Alignment in the PE/COFF header

+  ///

   UINT32                            SectionAlignment;

+  ///

+  /// Set by PeCoffLoaderGetImageInfo() to offset to the PE/COFF header.

+  /// If the PE/COFF image does not start with a DOS header, this value is zero; 

+  /// otherwise, it's the offset to the PE/COFF header.

+  ///

   UINT32                            PeCoffHeaderOffset;

+  ///

+  /// Set by PeCoffLoaderGetImageInfo() to the Relative Virtual Address of the debug directory

+  /// if it exists in the image

+  ///

   UINT32                            DebugDirectoryEntryRva;

+  ///

+  /// Set by PeCoffLoaderLoadImage() to CodeView area of the PE/COFF Debug directory.

+  ///

   VOID                              *CodeView;

+  ///

+  /// Set by PeCoffLoaderLoadImage() to point to the PDB entry contained in the CodeView area.

+  /// The PdbPointer points to the filename of the PDB file used for source-level debug of 

+  /// the image by a debugger.

+  ///

   CHAR8                             *PdbPointer;

+  ///

+  /// Is set by PeCoffLoaderGetImageInfo() to the Section Alignment in the PE/COFF header.

+  ///

   UINTN                             SizeOfHeaders;

+  ///

+  /// Not used by this library class. Other library classes that layer on  top of this library

+  /// class fill in this value as part of their GetImageInfo call. 

+  /// This allows the caller of the library to know what type of memory needs to be allocated

+  /// to load and relocate the image.

+  ///

   UINT32                            ImageCodeMemoryType;

+  ///

+  /// Not used by this library class. Other library classes that layer on top of this library 

+  /// class fill in this value as part of their GetImageInfo call.

+  /// This allows the caller of the library to know what type of memory needs to be allocated

+  /// to load and relocate the image

+  ///

   UINT32                            ImageDataMemoryType;

+  ///

+  /// Set by any of the library functions if they encounter an error. 

+  ///

   UINT32                            ImageError;

+  ///

+  /// Set by PeCoffLoaderLoadImage() to indicate the size of FixupData that the caller must

+  /// allocate before calling PeCoffLoaderRelocateImage()

+  ///

   UINTN                             FixupDataSize;

+  ///

+  /// Set by PeCoffLoaderGetImageInfo() to the machine type stored in the PE/COFF header

+  ///

   UINT16                            Machine;

+  ///

+  /// Set by PeCoffLoaderGetImageInfo() to the subsystem type stored in the PE/COFF header.

+  ///

   UINT16                            ImageType;

+  ///

+  /// Set by PeCoffLoaderGetImageInfo() to TRUE if the PE/COFF image does not contain

+  /// relocation information.

+  ///

   BOOLEAN                           RelocationsStripped;

+  ///

+  /// Set by PeCoffLoaderGetImageInfo() to TRUE if the image is a TE image. 

+  /// For a definition of the TE Image format, see the Platform Initialization Pre-EFI

+  /// Initialization Core Interface Specification.

+  ///

   BOOLEAN                           IsTeImage;

 } PE_COFF_LOADER_IMAGE_CONTEXT;