1 files changed, 144 insertions, 243 deletions
diff --git a/BaseTools/Source/C/Common/FvLib.c b/BaseTools/Source/C/Common/FvLib.c
index 82dc557..37631f4 100644
--- a/BaseTools/Source/C/Common/FvLib.c
+++ b/BaseTools/Source/C/Common/FvLib.c
@@ -22,29 +22,22 @@ UINT32                      mFvLength   = 0;
 //
 // External function implementations
 //
-EFI_STATUS
-InitializeFvLib (
-  IN VOID                         *Fv,
-  IN UINT32                       FvLength
-  )
-/*++
-
-Routine Description:
 
+/**
   This initializes the FV lib with a pointer to the FV and length.  It does not
   verify the FV in any way.
 
-Arguments:
+  @param Fv            Buffer containing the FV.
+  @param FvLength      Length of the FV
 
-  Fv            Buffer containing the FV.
-  FvLength      Length of the FV
-
-Returns:
-
-  EFI_SUCCESS             Function Completed successfully.
-  EFI_INVALID_PARAMETER   A required parameter was NULL.
-
---*/
+  @retval EFI_SUCCESS             Function Completed successfully.
+  @retval EFI_INVALID_PARAMETER   A required parameter was NULL.
+**/
+EFI_STATUS
+InitializeFvLib (
+  IN VOID                         *Fv,
+  IN UINT32                       FvLength
+  )
 {
   //
   // Verify input arguments
@@ -59,29 +52,21 @@ Returns:
   return EFI_SUCCESS;
 }
 
+/**
+  This function returns a pointer to the current FV and the size.
+
+  @param FvHeader      Pointer to the FV buffer.
+  @param FvLength      Length of the FV
+
+  @retval EFI_SUCCESS             Function Completed successfully.
+  @retval EFI_INVALID_PARAMETER   A required parameter was NULL.
+  @retvalEFI_ABORTED             The library needs to be initialized.
+**/
 EFI_STATUS
 GetFvHeader (
   OUT EFI_FIRMWARE_VOLUME_HEADER  **FvHeader,
   OUT UINT32                      *FvLength
   )
-/*++
-
-Routine Description:
-
-  This function returns a pointer to the current FV and the size.
-
-Arguments:
-
-  FvHeader      Pointer to the FV buffer.
-  FvLength      Length of the FV
-
-Returns:
-
-  EFI_SUCCESS             Function Completed successfully.
-  EFI_INVALID_PARAMETER   A required parameter was NULL.
-  EFI_ABORTED             The library needs to be initialized.
-
---*/
 {
   //
   // Verify library has been initialized.
@@ -101,31 +86,23 @@ Returns:
   return EFI_SUCCESS;
 }
 
-EFI_STATUS
-GetNextFile (
-  IN EFI_FFS_FILE_HEADER          *CurrentFile,
-  OUT EFI_FFS_FILE_HEADER         **NextFile
-  )
-/*++
-
-Routine Description:
-
+/**
   This function returns the next file.  If the current file is NULL, it returns
   the first file in the FV.  If the function returns EFI_SUCCESS and the file
   pointer is NULL, then there are no more files in the FV.
 
-Arguments:
-
-  CurrentFile   Pointer to the current file, must be within the current FV.
-  NextFile      Pointer to the next file in the FV.
-
-Returns:
+  @param CurrentFile   Pointer to the current file, must be within the current FV.
+  @param NextFile      Pointer to the next file in the FV.
 
-  EFI_SUCCESS             Function completed successfully.
-  EFI_INVALID_PARAMETER   A required parameter was NULL or is out of range.
-  EFI_ABORTED             The library needs to be initialized.
-
---*/
+  @retval EFI_SUCCESS             Function completed successfully.
+  @retval EFI_INVALID_PARAMETER   A required parameter was NULL or is out of range.
+  @retval EFI_ABORTED             The library needs to be initialized.
+**/
+EFI_STATUS
+GetNextFile (
+  IN EFI_FFS_FILE_HEADER          *CurrentFile,
+  OUT EFI_FFS_FILE_HEADER         **NextFile
+  )
 {
   EFI_STATUS  Status;
 
@@ -214,29 +191,21 @@ Returns:
   return EFI_SUCCESS;
 }
 
+/**
+  Find a file by name.  The function will return NULL if the file is not found.
+
+  @param FileName    The GUID file name of the file to search for.
+  @param File        Return pointer.  In the case of an error, contents are undefined.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_ABORTED             An error was encountered.
+  @retval EFI_INVALID_PARAMETER   One of the parameters was NULL.
+**/
 EFI_STATUS
 GetFileByName (
   IN EFI_GUID                     *FileName,
   OUT EFI_FFS_FILE_HEADER         **File
   )
-/*++
-
-Routine Description:
-
-  Find a file by name.  The function will return NULL if the file is not found.
-
-Arguments:
-
-  FileName    The GUID file name of the file to search for.
-  File        Return pointer.  In the case of an error, contents are undefined.
-
-Returns:
-
-  EFI_SUCCESS             The function completed successfully.
-  EFI_ABORTED             An error was encountered.
-  EFI_INVALID_PARAMETER   One of the parameters was NULL.
-
---*/
 {
   EFI_FFS_FILE_HEADER *CurrentFile;
   EFI_STATUS          Status;
@@ -295,33 +264,25 @@ Returns:
   return EFI_SUCCESS;
 }
 
+/**
+  Find a file by type and instance.  An instance of 1 is the first instance.
+  The function will return NULL if a matching file cannot be found.
+  File type EFI_FV_FILETYPE_ALL means any file type is valid.
+
+  @param FileType    Type of file to search for.
+  @param Instance    Instance of the file type to return.
+  @param File        Return pointer.  In the case of an error, contents are undefined.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_ABORTED             An error was encountered.
+  @retval EFI_INVALID_PARAMETER   One of the parameters was NULL.
+**/
 EFI_STATUS
 GetFileByType (
   IN EFI_FV_FILETYPE              FileType,
   IN UINTN                        Instance,
   OUT EFI_FFS_FILE_HEADER         **File
   )
-/*++
-
-Routine Description:
-
-  Find a file by type and instance.  An instance of 1 is the first instance.
-  The function will return NULL if a matching file cannot be found.
-  File type EFI_FV_FILETYPE_ALL means any file type is valid.
-
-Arguments:
-
-  FileType    Type of file to search for.
-  Instance    Instance of the file type to return.
-  File        Return pointer.  In the case of an error, contents are undefined.
-
-Returns:
-
-  EFI_SUCCESS             The function completed successfully.
-  EFI_ABORTED             An error was encountered.
-  EFI_INVALID_PARAMETER   One of the parameters was NULL.
-
---*/
 {
   EFI_FFS_FILE_HEADER *CurrentFile;
   EFI_STATUS          Status;
@@ -383,6 +344,23 @@ Returns:
   return EFI_SUCCESS;
 }
 
+/**
+  Helper function to search a sequence of sections from the section pointed
+  by FirstSection to SearchEnd for the Instance-th section of type SectionType.
+  The current counter is saved in StartIndex and when the section is found, it's
+  saved in Section. GUID-defined sections, if special processing is not required,
+  are searched recursively in a depth-first manner.
+
+  @param FirstSection The first section to start searching from.
+  @param SearchEnd    The end address to stop search.
+  @param SectionType  The type of section to search.
+  @param StartIndex   The current counter is saved.
+  @param Instance     The requested n-th section number.
+  @param Section      The found section returned.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_NOT_FOUND           The section is not found.
+**/
 EFI_STATUS
 SearchSectionByType (
   IN EFI_FILE_SECTION_POINTER  FirstSection,
@@ -392,30 +370,6 @@ SearchSectionByType (
   IN UINTN                     Instance,
   OUT EFI_FILE_SECTION_POINTER *Section
   )
-/*++
-
-Routine Description:
-
-  Helper function to search a sequence of sections from the section pointed
-  by FirstSection to SearchEnd for the Instance-th section of type SectionType.
-  The current counter is saved in StartIndex and when the section is found, it's
-  saved in Section. GUID-defined sections, if special processing is not required,
-  are searched recursively in a depth-first manner.
-
-Arguments:
-
-  FirstSection The first section to start searching from.
-  SearchEnd    The end address to stop search.
-  SectionType  The type of section to search.
-  StartIndex   The current counter is saved.
-  Instance     The requested n-th section number.
-  Section      The found section returned.
-
-Returns:
-
-  EFI_SUCCESS             The function completed successfully.
-  EFI_NOT_FOUND           The section is not found.
---*/
 {
   EFI_FILE_SECTION_POINTER  CurrentSection;
   EFI_FILE_SECTION_POINTER  InnerSection;
@@ -479,6 +433,22 @@ Returns:
   return EFI_NOT_FOUND;
 }
 
+/**
+  Find a section in a file by type and instance.  An instance of 1 is the first
+  instance.  The function will return NULL if a matching section cannot be found.
+  GUID-defined sections, if special processing is not needed, are handled in a
+  depth-first manner.
+
+  @param File        The file to search.
+  @param SectionType Type of file to search for.
+  @param Instance    Instance of the section to return.
+  @param Section     Return pointer.  In the case of an error, contents are undefined.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_ABORTED             An error was encountered.
+  @retval EFI_INVALID_PARAMETER   One of the parameters was NULL.
+  @retval EFI_NOT_FOUND           No found.
+**/
 EFI_STATUS
 GetSectionByType (
   IN EFI_FFS_FILE_HEADER          *File,
@@ -486,29 +456,6 @@ GetSectionByType (
   IN UINTN                        Instance,
   OUT EFI_FILE_SECTION_POINTER    *Section
   )
-/*++
-
-Routine Description:
-
-  Find a section in a file by type and instance.  An instance of 1 is the first
-  instance.  The function will return NULL if a matching section cannot be found.
-  GUID-defined sections, if special processing is not needed, are handled in a
-  depth-first manner.
-
-Arguments:
-
-  File        The file to search.
-  SectionType Type of file to search for.
-  Instance    Instance of the section to return.
-  Section     Return pointer.  In the case of an error, contents are undefined.
-
-Returns:
-
-  EFI_SUCCESS             The function completed successfully.
-  EFI_ABORTED             An error was encountered.
-  EFI_INVALID_PARAMETER   One of the parameters was NULL.
-  EFI_NOT_FOUND           No found.
---*/
 {
   EFI_FILE_SECTION_POINTER  CurrentSection;
   EFI_STATUS                Status;
@@ -560,31 +507,25 @@ Returns:
     return EFI_NOT_FOUND;
   }
 }
+
 //
 // will not parse compressed sections
 //
-EFI_STATUS
-VerifyFv (
-  IN EFI_FIRMWARE_VOLUME_HEADER   *FvHeader
-  )
-/*++
-
-Routine Description:
 
+/**
   Verify the current pointer points to a valid FV header.
 
-Arguments:
-
-  FvHeader     Pointer to an alleged FV file.
-
-Returns:
-
-  EFI_SUCCESS             The FV header is valid.
-  EFI_VOLUME_CORRUPTED    The FV header is not valid.
-  EFI_INVALID_PARAMETER   A required parameter was NULL.
-  EFI_ABORTED             Operation aborted.
+  @param FvHeader     Pointer to an alleged FV file.
 
---*/
+  @retval EFI_SUCCESS             The FV header is valid.
+  @retval EFI_VOLUME_CORRUPTED    The FV header is not valid.
+  @retval EFI_INVALID_PARAMETER   A required parameter was NULL.
+  @retval EFI_ABORTED             Operation aborted.
+**/
+EFI_STATUS
+VerifyFv (
+  IN EFI_FIRMWARE_VOLUME_HEADER   *FvHeader
+  )
 {
   UINT16  Checksum;
 
@@ -612,28 +553,20 @@ Returns:
   return EFI_SUCCESS;
 }
 
+/**
+  Verify the current pointer points to a FFS file header.
+
+  @param FfsHeader     Pointer to an alleged FFS file.
+
+  @retval EFI_SUCCESS           The Ffs header is valid.
+  @retval EFI_NOT_FOUND         This "file" is the beginning of free space.
+  @retval EFI_VOLUME_CORRUPTED  The Ffs header is not valid.
+  @retval EFI_ABORTED           The erase polarity is not known.
+**/
 EFI_STATUS
 VerifyFfsFile (
   IN EFI_FFS_FILE_HEADER  *FfsHeader
   )
-/*++
-
-Routine Description:
-
-  Verify the current pointer points to a FFS file header.
-
-Arguments:
-
-  FfsHeader     Pointer to an alleged FFS file.
-
-Returns:
-
-  EFI_SUCCESS           The Ffs header is valid.
-  EFI_NOT_FOUND         This "file" is the beginning of free space.
-  EFI_VOLUME_CORRUPTED  The Ffs header is not valid.
-  EFI_ABORTED           The erase polarity is not known.
-
---*/
 {
   BOOLEAN             ErasePolarity;
   EFI_STATUS          Status;
@@ -754,25 +687,17 @@ GetSectionHeaderLength(
   return sizeof(EFI_COMMON_SECTION_HEADER);
 }
 
+/**
+  Get FFS file length including FFS header.
+
+  @param FfsHeader   Pointer to EFI_FFS_FILE_HEADER.
+
+  @return UINT32      Length of FFS file header.
+**/
 UINT32
 GetFfsFileLength (
   EFI_FFS_FILE_HEADER *FfsHeader
   )
-/*++
-
-Routine Description:
-
-  Get FFS file length including FFS header.
-
-Arguments:
-
-  FfsHeader   Pointer to EFI_FFS_FILE_HEADER.
-
-Returns:
-
-  UINT32      Length of FFS file header.
-
---*/
 {
   if (FfsHeader == NULL) {
     return 0;
@@ -800,25 +725,17 @@ GetSectionFileLength (
   return Length;
 }
 
+/**
+  Converts a three byte length value into a UINT32.
+
+  @param ThreeByteLength   Pointer to the first of the 3 byte length.
+
+  @return UINT32      Size of the section
+**/
 UINT32
 GetLength (
   UINT8     *ThreeByteLength
   )
-/*++
-
-Routine Description:
-
-  Converts a three byte length value into a UINT32.
-
-Arguments:
-
-  ThreeByteLength   Pointer to the first of the 3 byte length.
-
-Returns:
-
-  UINT32      Size of the section
-
---*/
 {
   UINT32  Length;
 
@@ -832,28 +749,20 @@ Returns:
   return Length;
 }
 
-EFI_STATUS
-GetErasePolarity (
-  OUT BOOLEAN   *ErasePolarity
-  )
-/*++
-
-Routine Description:
-
+/**
   This function returns with the FV erase polarity.  If the erase polarity
   for a bit is 1, the function return TRUE.
 
-Arguments:
-
-  ErasePolarity   A pointer to the erase polarity.
-
-Returns:
+  @param ErasePolarity   A pointer to the erase polarity.
 
-  EFI_SUCCESS              The function completed successfully.
-  EFI_INVALID_PARAMETER    One of the input parameters was invalid.
-  EFI_ABORTED              Operation aborted.
-
---*/
+  @retval EFI_SUCCESS              The function completed successfully.
+  @retval EFI_INVALID_PARAMETER    One of the input parameters was invalid.
+  @retval EFI_ABORTED              Operation aborted.
+**/
+EFI_STATUS
+GetErasePolarity (
+  OUT BOOLEAN   *ErasePolarity
+  )
 {
   EFI_STATUS  Status;
 
@@ -886,28 +795,20 @@ Returns:
   return EFI_SUCCESS;
 }
 
+/**
+  This function returns a the highest state bit in the FFS that is set.
+  It in no way validate the FFS file.
+
+  @param ErasePolarity The erase polarity for the file state bits.
+  @param FfsHeader     Pointer to a FFS file.
+
+  @retval UINT8   The hightest set state of the file.
+**/
 UINT8
 GetFileState (
   IN BOOLEAN              ErasePolarity,
   IN EFI_FFS_FILE_HEADER  *FfsHeader
   )
-/*++
-
-Routine Description:
-
-  This function returns a the highest state bit in the FFS that is set.
-  It in no way validate the FFS file.
-
-Arguments:
-
-  ErasePolarity The erase polarity for the file state bits.
-  FfsHeader     Pointer to a FFS file.
-
-Returns:
-
-  UINT8   The hightest set state of the file.
-
---*/
 {
   UINT8 FileState;
   UINT8 HighestBit;