BaseTools: Source/C/Common: Fix doc block locations and convert to Doxygen

Move the documentation blocks from between the parameter list and function
body to above the function.

Convert all the documentation blocks to Doxygen format.

Signed-off-by: Rebecca Cran <rebecca@bsdio.com>
Reviewed-by: Liming Gao <gaoliming@byosoft.com.cn>

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;