From: "Rebecca Cran" <rebecca@bsdio.com>
To: devel@edk2.groups.io, Bob Feng <bob.c.feng@intel.com>,
Liming Gao <gaoliming@byosoft.com.cn>,
Yuwei Chen <yuwei.chen@intel.com>
Cc: Rebecca Cran <rebecca@bsdio.com>
Subject: [PATCH 1/3] BaseTools: Source/C/Common: Fix doc block locations and convert to Doxygen
Date: Fri, 24 Feb 2023 17:54:29 -0700 [thread overview]
Message-ID: <20230225005431.12173-2-rebecca@bsdio.com> (raw)
In-Reply-To: <20230225005431.12173-1-rebecca@bsdio.com>
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>
---
BaseTools/Source/C/Common/CommonLib.h | 14 +-
BaseTools/Source/C/Common/Compress.h | 45 +-
BaseTools/Source/C/Common/Crc32.h | 30 +-
BaseTools/Source/C/Common/Decompress.h | 118 ++-
BaseTools/Source/C/Common/MemoryFile.h | 72 +-
BaseTools/Source/C/Common/MyAlloc.h | 146 ++--
BaseTools/Source/C/Common/OsPath.h | 90 +-
BaseTools/Source/C/Common/ParseGuidedSectionTools.h | 95 +--
BaseTools/Source/C/Common/ParseInf.h | 204 ++---
BaseTools/Source/C/Common/PcdValueCommon.h | 175 ++--
BaseTools/Source/C/Common/StringFuncs.h | 191 ++---
BaseTools/Source/C/Common/BasePeCoff.c | 202 ++---
BaseTools/Source/C/Common/CommonLib.c | 336 +++-----
BaseTools/Source/C/Common/Crc32.c | 30 +-
BaseTools/Source/C/Common/Decompress.c | 470 ++++-------
BaseTools/Source/C/Common/EfiCompress.c | 574 +++++--------
BaseTools/Source/C/Common/EfiUtilityMsgs.c | 522 +++++-------
BaseTools/Source/C/Common/FirmwareVolumeBuffer.c | 869 +++++++-------------
BaseTools/Source/C/Common/FvLib.c | 401 ++++-----
BaseTools/Source/C/Common/MemoryFile.c | 84 +-
BaseTools/Source/C/Common/MyAlloc.c | 155 ++--
BaseTools/Source/C/Common/OsPath.c | 101 +--
BaseTools/Source/C/Common/ParseGuidedSectionTools.c | 92 +--
BaseTools/Source/C/Common/ParseInf.c | 225 ++---
BaseTools/Source/C/Common/PcdValueCommon.c | 303 +++----
BaseTools/Source/C/Common/PeCoffLoaderEx.c | 66 +-
BaseTools/Source/C/Common/SimpleFileParsing.c | 430 ++++------
BaseTools/Source/C/Common/StringFuncs.c | 246 ++----
BaseTools/Source/C/Common/TianoCompress.c | 610 +++++---------
29 files changed, 2452 insertions(+), 4444 deletions(-)
diff --git a/BaseTools/Source/C/Common/CommonLib.h b/BaseTools/Source/C/Common/CommonLib.h
index 0f05d88db206..a841029c2aaa 100644
--- a/BaseTools/Source/C/Common/CommonLib.h
+++ b/BaseTools/Source/C/Common/CommonLib.h
@@ -95,13 +95,6 @@ GetFileImage (
)
;
-EFI_STATUS
-PutFileImage (
- IN CHAR8 *OutputFileName,
- IN CHAR8 *OutputFileImage,
- IN UINT32 BytesToWrite
- )
-;
/*++
Routine Description:
@@ -122,6 +115,13 @@ Routine Description:
EFI_OUT_OF_RESOURCES No resource to complete operations.
**/
+EFI_STATUS
+PutFileImage (
+ IN CHAR8 *OutputFileName,
+ IN CHAR8 *OutputFileImage,
+ IN UINT32 BytesToWrite
+ )
+;
UINT8
CalculateChecksum8 (
diff --git a/BaseTools/Source/C/Common/Compress.h b/BaseTools/Source/C/Common/Compress.h
index 40255a9665da..499e183c2b40 100644
--- a/BaseTools/Source/C/Common/Compress.h
+++ b/BaseTools/Source/C/Common/Compress.h
@@ -15,13 +15,10 @@ SPDX-License-Identifier: BSD-2-Clause-Patent
#include "CommonLib.h"
#include <Common/UefiBaseTypes.h>
-/*++
-
-Routine Description:
+/**
Tiano compression routine.
-
---*/
+**/
EFI_STATUS
TianoCompress (
IN UINT8 *SrcBuffer,
@@ -31,13 +28,9 @@ TianoCompress (
)
;
-/*++
-
-Routine Description:
-
+/**
Efi compression routine.
-
---*/
+**/
EFI_STATUS
EfiCompress (
IN UINT8 *SrcBuffer,
@@ -47,29 +40,21 @@ EfiCompress (
)
;
-/*++
-
-Routine Description:
-
+/**
The compression routine.
-Arguments:
+ @param SrcBuffer The buffer storing the source data
+ @param SrcSize The size of source data
+ @param DstBuffer The buffer to store the compressed data
+ @param DstSize On input, the size of DstBuffer; On output,
+ the size of the actual compressed data.
- SrcBuffer - The buffer storing the source data
- SrcSize - The size of source data
- DstBuffer - The buffer to store the compressed data
- DstSize - On input, the size of DstBuffer; On output,
- the size of the actual compressed data.
-
-Returns:
-
- EFI_BUFFER_TOO_SMALL - The DstBuffer is too small. In this case,
+ @retval EFI_BUFFER_TOO_SMALL The DstBuffer is too small. In this case,
DstSize contains the size needed.
- EFI_SUCCESS - Compression is successful.
- EFI_OUT_OF_RESOURCES - No resource to complete function.
- EFI_INVALID_PARAMETER - Parameter supplied is wrong.
-
---*/
+ @retval EFI_SUCCESS Compression is successful.
+ @retval EFI_OUT_OF_RESOURCES No resource to complete function.
+ @retval EFI_INVALID_PARAMETER Parameter supplied is wrong.
+**/
typedef
EFI_STATUS
(*COMPRESS_FUNCTION) (
diff --git a/BaseTools/Source/C/Common/Crc32.h b/BaseTools/Source/C/Common/Crc32.h
index 61f99b96b565..3f6b5b35fc36 100644
--- a/BaseTools/Source/C/Common/Crc32.h
+++ b/BaseTools/Source/C/Common/Crc32.h
@@ -11,31 +11,23 @@ SPDX-License-Identifier: BSD-2-Clause-Patent
#include <Common/UefiBaseTypes.h>
+/**
+ The CalculateCrc32 routine.
+
+ @param Data The buffer containing the data to be processed
+ @param DataSize The size of data to be processed
+ @param CrcOut A pointer to the caller allocated UINT32 that on
+ contains the CRC32 checksum of Data
+
+ @retval EFI_SUCCESS - Calculation is successful.
+ @retval EFI_INVALID_PARAMETER - Data / CrcOut = NULL, or DataSize = 0
+**/
EFI_STATUS
CalculateCrc32 (
IN UINT8 *Data,
IN UINTN DataSize,
IN OUT UINT32 *CrcOut
)
-/*++
-
-Routine Description:
-
- The CalculateCrc32 routine.
-
-Arguments:
-
- Data - The buffer containing the data to be processed
- DataSize - The size of data to be processed
- CrcOut - A pointer to the caller allocated UINT32 that on
- contains the CRC32 checksum of Data
-
-Returns:
-
- EFI_SUCCESS - Calculation is successful.
- EFI_INVALID_PARAMETER - Data / CrcOut = NULL, or DataSize = 0
-
---*/
;
#endif
diff --git a/BaseTools/Source/C/Common/Decompress.h b/BaseTools/Source/C/Common/Decompress.h
index 983a27d8fc26..00a1e31b8c21 100644
--- a/BaseTools/Source/C/Common/Decompress.h
+++ b/BaseTools/Source/C/Common/Decompress.h
@@ -11,13 +11,6 @@ SPDX-License-Identifier: BSD-2-Clause-Patent
#include <Common/UefiBaseTypes.h>
-EFI_STATUS
-EfiGetInfo (
- IN VOID *Source,
- IN UINT32 SrcSize,
- OUT UINT32 *DstSize,
- OUT UINT32 *ScratchSize
- );
/**
Routine Description:
@@ -37,95 +30,78 @@ Routine Description:
EFI_INVALID_PARAMETER - The source data is corrupted
**/
-
EFI_STATUS
-EfiDecompress (
+EfiGetInfo (
IN VOID *Source,
IN UINT32 SrcSize,
- IN OUT VOID *Destination,
- IN UINT32 DstSize,
- IN OUT VOID *Scratch,
- IN UINT32 ScratchSize
+ OUT UINT32 *DstSize,
+ OUT UINT32 *ScratchSize
);
+
/**
-
-Routine Description:
-
The implementation of Efi Decompress().
-Arguments:
-
- Source - The source buffer containing the compressed data.
- SrcSize - The size of source buffer
- Destination - The destination buffer to store the decompressed data
- DstSize - The size of destination buffer.
- Scratch - The buffer used internally by the decompress routine. This buffer is needed to store intermediate data.
- ScratchSize - The size of scratch buffer.
-
-Returns:
-
- EFI_SUCCESS - Decompression is successful
- EFI_INVALID_PARAMETER - The source data is corrupted
-
+ @param Source The source buffer containing the compressed data.
+ @param SrcSize The size of source buffer
+ @param Destination The destination buffer to store the decompressed data
+ @param DstSize The size of destination buffer.
+ @param Scratch The buffer used internally by the decompress routine. This buffer is needed to store intermediate data.
+ @param ScratchSize The size of scratch buffer.
+
+ @retval EFI_SUCCESS Decompression is successful
+ @retval EFI_INVALID_PARAMETER The source data is corrupted
**/
-
EFI_STATUS
-TianoGetInfo (
+EfiDecompress (
IN VOID *Source,
IN UINT32 SrcSize,
- OUT UINT32 *DstSize,
- OUT UINT32 *ScratchSize
+ IN OUT VOID *Destination,
+ IN UINT32 DstSize,
+ IN OUT VOID *Scratch,
+ IN UINT32 ScratchSize
);
+
/**
-
-Routine Description:
-
The implementation Tiano Decompress GetInfo().
-Arguments:
-
- Source - The source buffer containing the compressed data.
- SrcSize - The size of source buffer
- DstSize - The size of destination buffer.
- ScratchSize - The size of scratch buffer.
-
-Returns:
-
- EFI_SUCCESS - The size of destination buffer and the size of scratch buffer are successfully retrieved.
- EFI_INVALID_PARAMETER - The source data is corrupted
+ @param Source The source buffer containing the compressed data.
+ @param SrcSize The size of source buffer
+ @param DstSize The size of destination buffer.
+ @param ScratchSize The size of scratch buffer.
+ @retval EFI_SUCCESS The size of destination buffer and the size of scratch buffer are successfully retrieved.
+ @retval EFI_INVALID_PARAMETER The source data is corrupted
**/
-
EFI_STATUS
-TianoDecompress (
+TianoGetInfo (
IN VOID *Source,
IN UINT32 SrcSize,
- IN OUT VOID *Destination,
- IN UINT32 DstSize,
- IN OUT VOID *Scratch,
- IN UINT32 ScratchSize
+ OUT UINT32 *DstSize,
+ OUT UINT32 *ScratchSize
);
+
/**
-
-Routine Description:
-
The implementation of Tiano Decompress().
-Arguments:
-
- Source - The source buffer containing the compressed data.
- SrcSize - The size of source buffer
- Destination - The destination buffer to store the decompressed data
- DstSize - The size of destination buffer.
- Scratch - The buffer used internally by the decompress routine. This buffer is needed to store intermediate data.
- ScratchSize - The size of scratch buffer.
-
-Returns:
-
- EFI_SUCCESS - Decompression is successful
- EFI_INVALID_PARAMETER - The source data is corrupted
-
+ @param Source The source buffer containing the compressed data.
+ @param SrcSize The size of source buffer
+ @param Destination The destination buffer to store the decompressed data
+ @param DstSize The size of destination buffer.
+ @param Scratch The buffer used internally by the decompress routine. This buffer is needed to store intermediate data.
+ @param ScratchSize The size of scratch buffer.
+
+ @retval EFI_SUCCESS Decompression is successful
+ @retval EFI_INVALID_PARAMETER The source data is corrupted
**/
+EFI_STATUS
+TianoDecompress (
+ IN VOID *Source,
+ IN UINT32 SrcSize,
+ IN OUT VOID *Destination,
+ IN UINT32 DstSize,
+ IN OUT VOID *Scratch,
+ IN UINT32 ScratchSize
+ );
typedef
EFI_STATUS
diff --git a/BaseTools/Source/C/Common/MemoryFile.h b/BaseTools/Source/C/Common/MemoryFile.h
index 58fc8bb224f3..c84848cf15d6 100644
--- a/BaseTools/Source/C/Common/MemoryFile.h
+++ b/BaseTools/Source/C/Common/MemoryFile.h
@@ -27,79 +27,53 @@ typedef struct {
// Functions declarations
//
-EFI_STATUS
-GetMemoryFile (
- IN CHAR8 *InputFileName,
- OUT EFI_HANDLE *OutputMemoryFile
- )
-;
/**
-
-Routine Description:
-
This opens a file, reads it into memory and returns a memory file
object.
-Arguments:
+ @param InputFile Memory file image.
+ @param OutputMemoryFile Handle to memory file
- InputFile Memory file image.
- OutputMemoryFile Handle to memory file
-
-Returns:
-
- EFI_STATUS
+ @return EFI_STATUS
OutputMemoryFile is valid if !EFI_ERROR
-
**/
+EFI_STATUS
+GetMemoryFile (
+ IN CHAR8 *InputFileName,
+ OUT EFI_HANDLE *OutputMemoryFile
+ )
+;
+
+/**
+ Frees all memory associated with the input memory file.
+ @param InputMemoryFile Handle to memory file
+ @return EFI_STATUS
+**/
EFI_STATUS
FreeMemoryFile (
IN EFI_HANDLE InputMemoryFile
)
;
-/**
-
-Routine Description:
-
- Frees all memory associated with the input memory file.
-
-Arguments:
-
- InputMemoryFile Handle to memory file
-
-Returns:
- EFI_STATUS
-
-**/
-
-
-CHAR8 *
-ReadMemoryFileLine (
- IN EFI_HANDLE InputMemoryFile
- )
-;
/**
-
-Routine Description:
-
This function reads a line from the memory file. The newline characters
are stripped and a null terminated string is returned.
If the string pointer returned is non-NULL, then the caller must free the
memory associated with this string.
-Arguments:
-
- InputMemoryFile Handle to memory file
-
-Returns:
-
- NULL if error or EOF
- NULL character termincated string otherwise (MUST BE FREED BY CALLER)
+ @param InputMemoryFile Handle to memory file
+ @retval NULL if error or EOF
+ @retval NULL character termincated string otherwise (MUST BE FREED BY CALLER)
**/
+CHAR8 *
+ReadMemoryFileLine (
+ IN EFI_HANDLE InputMemoryFile
+ )
+;
#endif
diff --git a/BaseTools/Source/C/Common/MyAlloc.h b/BaseTools/Source/C/Common/MyAlloc.h
index aff29d05ab7d..de3323d30d97 100644
--- a/BaseTools/Source/C/Common/MyAlloc.h
+++ b/BaseTools/Source/C/Common/MyAlloc.h
@@ -71,6 +71,17 @@ typedef struct MyAllocStruct {
#define MYALLOC_HEAD_MAGIK 0xBADFACED
#define MYALLOC_TAIL_MAGIK 0xDEADBEEF
+/**
+ Check for corruptions in the allocated memory chain. If a corruption
+ is detection program operation stops w/ an exit(1) call.
+
+ @param Final When FALSE, MyCheck() returns if the allocated memory chain
+ has not been corrupted. When TRUE, MyCheck() returns if there
+ are no un-freed allocations. If there are un-freed allocations,
+ they are displayed and exit(1) is called.
+ @param File Set to __FILE__ by macro expansion.
+ @param Line Set to __LINE__ by macro expansion.
+**/
VOID
MyCheck (
BOOLEAN Final,
@@ -78,31 +89,20 @@ MyCheck (
UINTN Line
)
;
-//
-// *++
-// Description:
-//
-// Check for corruptions in the allocated memory chain. If a corruption
-// is detection program operation stops w/ an exit(1) call.
-//
-// Parameters:
-//
-// Final := When FALSE, MyCheck() returns if the allocated memory chain
-// has not been corrupted. When TRUE, MyCheck() returns if there
-// are no un-freed allocations. If there are un-freed allocations,
-// they are displayed and exit(1) is called.
-//
-//
-// File := Set to __FILE__ by macro expansion.
-//
-// Line := Set to __LINE__ by macro expansion.
-//
-// Returns:
-//
-// n/a
-//
-// --*/
-//
+
+/**
+ Allocate a new link in the allocation chain along with enough storage
+ for the File[] string, requested Size and alignment overhead. If
+ memory cannot be allocated or the allocation chain has been corrupted,
+ exit(1) will be called.
+
+ @param Size Number of bytes (UINT8) requested by the called.
+ Size cannot be zero.
+ @param File Set to __FILE__ by macro expansion.
+ @param Line Set to __LINE__ by macro expansion.
+
+ @return Pointer to the caller's buffer.
+**/
VOID *
MyAlloc (
UINTN Size,
@@ -110,30 +110,20 @@ MyAlloc (
UINTN Line
)
;
-//
-// *++
-// Description:
-//
-// Allocate a new link in the allocation chain along with enough storage
-// for the File[] string, requested Size and alignment overhead. If
-// memory cannot be allocated or the allocation chain has been corrupted,
-// exit(1) will be called.
-//
-// Parameters:
-//
-// Size := Number of bytes (UINT8) requested by the called.
-// Size cannot be zero.
-//
-// File := Set to __FILE__ by macro expansion.
-//
-// Line := Set to __LINE__ by macro expansion.
-//
-// Returns:
-//
-// Pointer to the caller's buffer.
-//
-// --*/
-//
+
+/**
+ This does a MyAlloc(), memcpy() and MyFree(). There is no optimization
+ for shrinking or expanding buffers. An invalid parameter will cause
+ MyRealloc() to fail with a call to exit(1).
+
+ @param Ptr Pointer to the caller's buffer to be re-allocated.
+ Ptr cannot be NULL.
+ @param Size Size of new buffer. Size cannot be zero.
+ @param File Set to __FILE__ by macro expansion.
+ @param Line Set to __LINE__ by macro expansion.
+
+ @return Pointer to new caller's buffer.
+**/
VOID *
MyRealloc (
VOID *Ptr,
@@ -142,31 +132,16 @@ MyRealloc (
UINTN Line
)
;
-//
-// *++
-// Description:
-//
-// This does a MyAlloc(), memcpy() and MyFree(). There is no optimization
-// for shrinking or expanding buffers. An invalid parameter will cause
-// MyRealloc() to fail with a call to exit(1).
-//
-// Parameters:
-//
-// Ptr := Pointer to the caller's buffer to be re-allocated.
-// Ptr cannot be NULL.
-//
-// Size := Size of new buffer. Size cannot be zero.
-//
-// File := Set to __FILE__ by macro expansion.
-//
-// Line := Set to __LINE__ by macro expansion.
-//
-// Returns:
-//
-// Pointer to new caller's buffer.
-//
-// --*/
-//
+
+/**
+ Release a previously allocated buffer. Invalid parameters will cause
+ MyFree() to fail with an exit(1) call.
+
+ @param Ptr Pointer to the caller's buffer to be freed.
+ A NULL pointer will be ignored.
+ @param File Set to __FILE__ by macro expansion.
+ @param Line Set to __LINE__ by macro expansion.
+**/
VOID
MyFree (
VOID *Ptr,
@@ -174,28 +149,7 @@ MyFree (
UINTN Line
)
;
-//
-// *++
-// Description:
-//
-// Release a previously allocated buffer. Invalid parameters will cause
-// MyFree() to fail with an exit(1) call.
-//
-// Parameters:
-//
-// Ptr := Pointer to the caller's buffer to be freed.
-// A NULL pointer will be ignored.
-//
-// File := Set to __FILE__ by macro expansion.
-//
-// Line := Set to __LINE__ by macro expansion.
-//
-// Returns:
-//
-// n/a
-//
-// --*/
-//
+
#else /* USE_MYALLOC */
//
diff --git a/BaseTools/Source/C/Common/OsPath.h b/BaseTools/Source/C/Common/OsPath.h
index 1868103e7f1b..b1881c4a1ec7 100644
--- a/BaseTools/Source/C/Common/OsPath.h
+++ b/BaseTools/Source/C/Common/OsPath.h
@@ -16,15 +16,7 @@ SPDX-License-Identifier: BSD-2-Clause-Patent
// Functions declarations
//
-CHAR8*
-OsPathDirName (
- IN CHAR8 *FilePath
- )
-;
/**
-
-Routine Description:
-
This function returns the directory path which contains the particular path.
Some examples:
"a/b/c" -> "a/b"
@@ -37,26 +29,17 @@ Routine Description:
The caller must free the string returned.
-Arguments:
-
- FilePath Path name of file to get the parent directory for.
-
-Returns:
-
- NULL if error
+ @param FilePath Path name of file to get the parent directory for.
+ @return NULL if error
**/
-
-
-VOID
-OsPathNormPathInPlace (
- IN CHAR8 *Path
+CHAR8*
+OsPathDirName (
+ IN CHAR8 *FilePath
)
;
+
/**
-
-Routine Description:
-
This function returns the directory path which contains the particular path.
Some examples:
"a/b/../c" -> "a/c"
@@ -65,27 +48,17 @@ Routine Description:
This function does not check for the existence of the file.
-Arguments:
-
- Path Path name of file to normalize
-
-Returns:
-
- The string is altered in place.
+ @param Path Path name of file to normalize
+ @return The string is altered in place.
**/
-
-
-CHAR8*
-OsPathPeerFilePath (
- IN CHAR8 *OldPath,
- IN CHAR8 *Peer
+VOID
+OsPathNormPathInPlace (
+ IN CHAR8 *Path
)
;
+
/**
-
-Routine Description:
-
This function replaces the final portion of a path with an alternative
'peer' filename. For example:
"a/b/../c", "peer" -> "a/b/../peer"
@@ -95,39 +68,30 @@ Routine Description:
This function does not check for the existence of the file.
-Arguments:
+ @param OldPath Path name of replace the final segment
+ @param Peer The new path name to concatenate to become the peer path
- OldPath Path name of replace the final segment
- Peer The new path name to concatenate to become the peer path
+ @return A CHAR8* string, which must be freed by the caller
+**/
+CHAR8*
+OsPathPeerFilePath (
+ IN CHAR8 *OldPath,
+ IN CHAR8 *Peer
+ )
+;
-Returns:
+/**
+ Checks if a file exists
- A CHAR8* string, which must be freed by the caller
+ @param InputFileName The name of the file to check for existence
+ @retval TRUE The file exists
+ @retval FALSE The file does not exist
**/
-
-
BOOLEAN
OsPathExists (
IN CHAR8 *InputFileName
)
;
-/**
-
-Routine Description:
-
- Checks if a file exists
-
-Arguments:
-
- InputFileName The name of the file to check for existence
-
-Returns:
-
- TRUE The file exists
- FALSE The file does not exist
-
-**/
-
#endif
diff --git a/BaseTools/Source/C/Common/ParseGuidedSectionTools.h b/BaseTools/Source/C/Common/ParseGuidedSectionTools.h
index 2714b8ce8222..2180bbd0740f 100644
--- a/BaseTools/Source/C/Common/ParseGuidedSectionTools.h
+++ b/BaseTools/Source/C/Common/ParseGuidedSectionTools.h
@@ -15,106 +15,73 @@ SPDX-License-Identifier: BSD-2-Clause-Patent
// Functions declarations
//
+/**
+ This function parses the tools_def.txt file. It returns a
+ EFI_HANDLE object which can be used for the other library
+ functions and should be passed to FreeParsedToolsDefHandle
+ to free resources when the tools_def.txt information is no
+ longer needed.
+
+ @param InputFile Path name of file to read
+
+ @retval NULL if error parsing
+ @retval A non-NULL EFI_HANDLE otherwise
+**/
EFI_HANDLE
ParseGuidedSectionToolsFile (
IN CHAR8 *InputFile
)
;
+
/**
-
-Routine Description:
-
This function parses the tools_def.txt file. It returns a
EFI_HANDLE object which can be used for the other library
functions and should be passed to FreeParsedToolsDefHandle
to free resources when the tools_def.txt information is no
longer needed.
-Arguments:
-
- InputFile Path name of file to read
-
-Returns:
-
- NULL if error parsing
- A non-NULL EFI_HANDLE otherwise
+ @param InputFile Memory file image.
+ @retval NULL if error parsing
+ @retval A non-NULL EFI_HANDLE otherwise
**/
-
-
EFI_HANDLE
ParseGuidedSectionToolsMemoryFile (
IN EFI_HANDLE InputFile
)
;
+
/**
+ This function looks up the appropriate tool to use for extracting
+ a GUID defined FV section.
-Routine Description:
-
- This function parses the tools_def.txt file. It returns a
- EFI_HANDLE object which can be used for the other library
- functions and should be passed to FreeParsedToolsDefHandle
- to free resources when the tools_def.txt information is no
- longer needed.
-
-Arguments:
-
- InputFile Memory file image.
-
-Returns:
-
- NULL if error parsing
- A non-NULL EFI_HANDLE otherwise
+ @param ParsedGuidedSectionToolsHandle A parsed GUID section tools handle.
+ @param SectionGuid The GUID for the section.
+ @retval NULL if no tool is found or there is another error
+ @retval Non-NULL The tool to use to access the section contents. (The caller
+ must free the memory associated with this string.)
**/
-
CHAR8*
LookupGuidedSectionToolPath (
IN EFI_HANDLE ParsedGuidedSectionToolsHandle,
IN EFI_GUID *SectionGuid
)
;
-/**
-
-Routine Description:
-
- This function looks up the appropriate tool to use for extracting
- a GUID defined FV section.
-
-Arguments:
-
- ParsedGuidedSectionToolsHandle A parsed GUID section tools handle.
- SectionGuid The GUID for the section.
-Returns:
-
- NULL - if no tool is found or there is another error
- Non-NULL - The tool to use to access the section contents. (The caller
- must free the memory associated with this string.)
-
-**/
-
-EFI_STATUS
-FreeParsedGuidedSectionToolsHandle (
- IN EFI_HANDLE ParsedGuidedSectionToolsHandle
- )
-;
/**
-
-Routine Description:
-
Frees resources that were allocated by ParseGuidedSectionToolsFile.
After freeing these resources, the information that was parsed
is no longer accessible.
-Arguments:
-
- ParsedToolDefHandle Handle returned from ParseGuidedSectionToolsFile
-
-Returns:
-
- EFI_STATUS
+ @param ParsedToolDefHandle Handle returned from ParseGuidedSectionToolsFile
+ @return EFI_STATUS
**/
+EFI_STATUS
+FreeParsedGuidedSectionToolsHandle (
+ IN EFI_HANDLE ParsedGuidedSectionToolsHandle
+ )
+;
#endif
diff --git a/BaseTools/Source/C/Common/ParseInf.h b/BaseTools/Source/C/Common/ParseInf.h
index 596cb3aa3bbb..a0881a5c9ed0 100644
--- a/BaseTools/Source/C/Common/ParseInf.h
+++ b/BaseTools/Source/C/Common/ParseInf.h
@@ -20,18 +20,8 @@ extern "C" {
//
// Functions declarations
//
-CHAR8 *
-ReadLine (
- IN MEMORY_FILE *InputFile,
- IN OUT CHAR8 *InputBuffer,
- IN UINTN MaxLength
- )
-;
-
-/*++
-
-Routine Description:
+/**
This function reads a line, stripping any comments.
The function reads a string from the input stream argument and stores it in
the input string. ReadLine reads characters from the current file position
@@ -39,18 +29,31 @@ Routine Description:
until the number of characters read is equal to MaxLength - 1, whichever
comes first. The newline character, if read, is replaced with a \0.
-Arguments:
+ @param InputFile Memory file image.
+ @param InputBuffer Buffer to read into, must be MaxLength size.
+ @param MaxLength The maximum size of the input buffer.
- InputFile Memory file image.
- InputBuffer Buffer to read into, must be MaxLength size.
- MaxLength The maximum size of the input buffer.
+ @retval NULL if error or EOF
+ @retval InputBuffer otherwise
+**/
+CHAR8 *
+ReadLine (
+ IN MEMORY_FILE *InputFile,
+ IN OUT CHAR8 *InputBuffer,
+ IN UINTN MaxLength
+ )
+;
-Returns:
+/**
+ This function parses a file from the beginning to find a section.
+ The section string may be anywhere within a line.
- NULL if error or EOF
- InputBuffer otherwise
+ @param InputFile Memory file image.
+ @param Section Section to search for
---*/
+ @retval FALSE if error or EOF
+ @retval TRUE if section found
+**/
BOOLEAN
FindSection (
IN MEMORY_FILE *InputFile,
@@ -58,24 +61,21 @@ FindSection (
)
;
-/*++
-
-Routine Description:
-
- This function parses a file from the beginning to find a section.
- The section string may be anywhere within a line.
-
-Arguments:
-
- InputFile Memory file image.
- Section Section to search for
-
-Returns:
-
- FALSE if error or EOF
- TRUE if section found
-
---*/
+/**
+ Finds a token value given the section and token to search for.
+
+ @param InputFile Memory file image.
+ @param Section The section to search for, a string within [].
+ @param Token The token to search for, e.g. EFI_PEIM_RECOVERY, followed by an = in the INF file.
+ @param Instance The instance of the token to search for. Zero is the first instance.
+ @param Value The string that holds the value following the =. Must be MAX_LONG_FILE_PATH in size.
+
+ @retval EFI_SUCCESS Value found.
+ @retval EFI_ABORTED Format error detected in INF file.
+ @retval EFI_INVALID_PARAMETER Input argument was null.
+ @retval EFI_LOAD_ERROR Error reading from the file.
+ @retval EFI_NOT_FOUND Section/Token/Value not found.
+**/
EFI_STATUS
FindToken (
IN MEMORY_FILE *InputFile,
@@ -86,29 +86,16 @@ FindToken (
)
;
-/*++
+/**
+ Converts a string to an EFI_GUID. The string must be in the
+ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx format.
-Routine Description:
+ @param GuidBuffer pointer to destination Guid
+ @param AsciiGuidBuffer pointer to ascii string
- Finds a token value given the section and token to search for.
-
-Arguments:
-
- InputFile Memory file image.
- Section The section to search for, a string within [].
- Token The token to search for, e.g. EFI_PEIM_RECOVERY, followed by an = in the INF file.
- Instance The instance of the token to search for. Zero is the first instance.
- Value The string that holds the value following the =. Must be MAX_LONG_FILE_PATH in size.
-
-Returns:
-
- EFI_SUCCESS Value found.
- EFI_ABORTED Format error detected in INF file.
- EFI_INVALID_PARAMETER Input argument was null.
- EFI_LOAD_ERROR Error reading from the file.
- EFI_NOT_FOUND Section/Token/Value not found.
-
---*/
+ @retval EFI_ABORTED Could not convert the string
+ @retval EFI_SUCCESS The string was successfully converted
+**/
EFI_STATUS
StringToGuid (
IN CHAR8 *AsciiGuidBuffer,
@@ -116,53 +103,36 @@ StringToGuid (
)
;
-/*++
-
-Routine Description:
-
- Converts a string to an EFI_GUID. The string must be in the
- xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx format.
-
-Arguments:
-
- GuidBuffer - pointer to destination Guid
- AsciiGuidBuffer - pointer to ascii string
-
-Returns:
-
- EFI_ABORTED Could not convert the string
- EFI_SUCCESS The string was successfully converted
-
---*/
-EFI_STATUS
-AsciiStringToUint64 (
- IN CONST CHAR8 *AsciiString,
- IN BOOLEAN IsHex,
- OUT UINT64 *ReturnValue
- )
-;
-
-/*++
-
-Routine Description:
-
+/**
Converts a null terminated ascii string that represents a number into a
UINT64 value. A hex number may be preceded by a 0x, but may not be
succeeded by an h. A number without 0x or 0X is considered to be base 10
unless the IsHex input is true.
-Arguments:
+ @param AsciiString The string to convert.
+ @param IsHex Force the string to be treated as a hex number.
+ @param ReturnValue The return value.
- AsciiString The string to convert.
- IsHex Force the string to be treated as a hex number.
- ReturnValue The return value.
+ @retval EFI_SUCCESS Number successfully converted.
+ @retval EFI_ABORTED Invalid character encountered.
+**/
+EFI_STATUS
+AsciiStringToUint64 (
+ IN CONST CHAR8 *AsciiString,
+ IN BOOLEAN IsHex,
+ OUT UINT64 *ReturnValue
+ )
+;
-Returns:
+/**
+ This function reads a line, stripping any comments.
- EFI_SUCCESS Number successfully converted.
- EFI_ABORTED Invalid character encountered.
+ @param InputFile Stream pointer.
+ @param InputBuffer Buffer to read into, must be MAX_LONG_FILE_PATH size.
---*/
+ @retval NULL if error or EOF
+ @retval InputBuffer otherwise
+**/
CHAR8 *
ReadLineInStream (
IN FILE *InputFile,
@@ -170,23 +140,16 @@ ReadLineInStream (
)
;
-/*++
+/**
+ This function parses a stream file from the beginning to find a section.
+ The section string may be anywhere within a line.
-Routine Description:
+ @param InputFile Stream pointer.
+ @param Section Section to search for
- This function reads a line, stripping any comments.
-
-Arguments:
-
- InputFile Stream pointer.
- InputBuffer Buffer to read into, must be MAX_LONG_FILE_PATH size.
-
-Returns:
-
- NULL if error or EOF
- InputBuffer otherwise
-
---*/
+ @retval FALSE if error or EOF
+ @retval TRUE if section found
+**/
BOOLEAN
FindSectionInStream (
IN FILE *InputFile,
@@ -194,25 +157,6 @@ FindSectionInStream (
)
;
-/*++
-
-Routine Description:
-
- This function parses a stream file from the beginning to find a section.
- The section string may be anywhere within a line.
-
-Arguments:
-
- InputFile Stream pointer.
- Section Section to search for
-
-Returns:
-
- FALSE if error or EOF
- TRUE if section found
-
---*/
-
#ifdef __cplusplus
}
#endif
diff --git a/BaseTools/Source/C/Common/PcdValueCommon.h b/BaseTools/Source/C/Common/PcdValueCommon.h
index 1652bd543039..02ef803be479 100644
--- a/BaseTools/Source/C/Common/PcdValueCommon.h
+++ b/BaseTools/Source/C/Common/PcdValueCommon.h
@@ -24,101 +24,81 @@ SPDX-License-Identifier: BSD-2-Clause-Patent
#define __STATIC_ASSERT _Static_assert
#endif
+/**
+ Main function updates PCD values. It is auto generated by Build
+**/
VOID
PcdEntryPoint (
VOID
)
-/*++
-Routine Description:
-
- Main function updates PCD values. It is auto generated by Build
-
-Arguments:
-
- None
-
-Returns:
- None
---*/
;
+/**
+ Main function updates PCD values.
+
+ @param argc Number of command line parameters.
+ @param argv Array of pointers to parameter strings.
+
+ @retval EXIT_SUCCESS
+**/
int
PcdValueMain (
int argc,
char *argv[]
)
-/*++
-
-Routine Description:
-
- Main function updates PCD values.
-
-Arguments:
-
- argc Number of command line parameters.
- argv Array of pointers to parameter strings.
-
-Returns:
- EXIT_SUCCESS
---*/
;
-VOID
-__PcdSet (
- CHAR8 *SkuName OPTIONAL,
- CHAR8 *DefaultValueName OPTIONAL,
- CHAR8 *TokenSpaceGuidName,
- CHAR8 *TokenName,
- UINT64 Value
- )
-/*++
-
-Routine Description:
-
- Get PCD value
-
-Arguments:
-
- SkuName SkuName String
- DefaultValueName DefaultValueName String
- TokenSpaceGuidName TokenSpaceGuidName String
- TokenName TokenName String
-
-Returns:
-
- PCD value
---*/
-;
-
-VOID
-__PcdSet (
- CHAR8 *SkuName OPTIONAL,
- CHAR8 *DefaultValueName OPTIONAL,
- CHAR8 *TokenSpaceGuidName,
- CHAR8 *TokenName,
- UINT64 Value
- )
-/*++
-
-Routine Description:
-
+/**
Set PCD value
-Arguments:
+ @param SkuName SkuName String
+ @param DefaultValueName DefaultValueName String
+ @param TokenSpaceGuidName TokenSpaceGuidName String
+ @param TokenName TokenName String
+ @param Value PCD value to be set
+**/
+VOID
+__PcdSet (
+ CHAR8 *SkuName OPTIONAL,
+ CHAR8 *DefaultValueName OPTIONAL,
+ CHAR8 *TokenSpaceGuidName,
+ CHAR8 *TokenName,
+ UINT64 Value
+ )
+;
- SkuName SkuName String
- DefaultValueName DefaultValueName String
- TokenSpaceGuidName TokenSpaceGuidName String
- TokenName TokenName String
- Value PCD value to be set
+/**
+ Get PCD value
-Returns:
+ @param SkuName SkuName String
+ @param DefaultValueName DefaultValueName String
+ @param TokenSpaceGuidName TokenSpaceGuidName String
+ @param TokenName TokenName String
- None
---*/
+ @return PCD value
+**/
+VOID
+__PcdSet (
+ CHAR8 *SkuName OPTIONAL,
+ CHAR8 *DefaultValueName OPTIONAL,
+ CHAR8 *TokenSpaceGuidName,
+ CHAR8 *TokenName,
+ UINT64 Value
+ )
;
+/**
+ Get PCD value buffer
+
+ @param SkuName SkuName String
+ @param DefaultValueName DefaultValueName String
+ @param TokenSpaceGuidName TokenSpaceGuidName String
+ @param TokenName TokenName String
+ @param Size Size of PCD value buffer
+
+ @return PCD value buffer
+**/
VOID *
__PcdGetPtr (
CHAR8 *SkuName OPTIONAL,
@@ -127,26 +107,18 @@ __PcdGetPtr (
CHAR8 *TokenName,
UINT32 *Size
)
-/*++
-
-Routine Description:
-
- Get PCD value buffer
-
-Arguments:
-
- SkuName SkuName String
- DefaultValueName DefaultValueName String
- TokenSpaceGuidName TokenSpaceGuidName String
- TokenName TokenName String
- Size Size of PCD value buffer
-
-Returns:
-
- PCD value buffer
---*/
;
+/**
+ Set PCD value buffer
+
+ @param SkuName SkuName String
+ @param DefaultValueName DefaultValueName String
+ @param TokenSpaceGuidName TokenSpaceGuidName String
+ @param TokenName TokenName String
+ @param Size Size of PCD value
+ @param Value Pointer to the updated PCD value buffer
+**/
VOID
__PcdSetPtr (
CHAR8 *SkuName OPTIONAL,
@@ -156,25 +128,6 @@ __PcdSetPtr (
UINT32 Size,
UINT8 *Value
)
-/*++
-
-Routine Description:
-
- Set PCD value buffer
-
-Arguments:
-
- SkuName SkuName String
- DefaultValueName DefaultValueName String
- TokenSpaceGuidName TokenSpaceGuidName String
- TokenName TokenName String
- Size Size of PCD value
- Value Pointer to the updated PCD value buffer
-
-Returns:
-
- None
---*/
;
#define PcdGet(A, B, C, D) __PcdGet(#A, #B, #C, #D)
diff --git a/BaseTools/Source/C/Common/StringFuncs.h b/BaseTools/Source/C/Common/StringFuncs.h
index 8fc616de8034..23dce2724448 100644
--- a/BaseTools/Source/C/Common/StringFuncs.h
+++ b/BaseTools/Source/C/Common/StringFuncs.h
@@ -29,216 +29,139 @@ typedef struct {
// Functions declarations
//
-CHAR8*
-CloneString (
- IN CHAR8 *String
- )
-;
/**
-
-Routine Description:
-
Allocates a new string and copies 'String' to clone it
-Arguments:
-
- String The string to clone
-
-Returns:
-
- CHAR8* - NULL if there are not enough resources
+ @param String The string to clone
+ @return CHAR8* - NULL if there are not enough resources
**/
-
-
-EFI_STATUS
-StripInfDscStringInPlace (
+CHAR8*
+CloneString (
IN CHAR8 *String
)
;
+
/**
-
-Routine Description:
-
Remove all comments, leading and trailing whitespace from the string.
-Arguments:
-
- String The string to 'strip'
-
-Returns:
-
- EFI_STATUS
+ @param String The string to 'strip'
+ @return EFI_STATUS
**/
-
-
-STRING_LIST*
-SplitStringByWhitespace (
+EFI_STATUS
+StripInfDscStringInPlace (
IN CHAR8 *String
)
;
+
/**
-
-Routine Description:
-
Creates and returns a 'split' STRING_LIST by splitting the string
on whitespace boundaries.
-Arguments:
-
- String The string to 'split'
-
-Returns:
-
- EFI_STATUS
+ @param String The string to 'split'
+ @return EFI_STATUS
**/
-
-
STRING_LIST*
-NewStringList (
+SplitStringByWhitespace (
+ IN CHAR8 *String
)
;
+
/**
-
-Routine Description:
-
Creates a new STRING_LIST with 0 strings.
-Returns:
-
- STRING_LIST* - Null if there is not enough resources to create the object.
-
+ @return STRING_LIST* - Null if there is not enough resources to create the object.
**/
-
-
-EFI_STATUS
-AppendCopyOfStringToList (
- IN OUT STRING_LIST **StringList,
- IN CHAR8 *String
+STRING_LIST*
+NewStringList (
)
;
+
+
/**
-
-Routine Description:
-
Adds String to StringList. A new copy of String is made before it is
added to StringList.
-Returns:
-
- EFI_STATUS
-
+ @return EFI_STATUS
**/
-
-
EFI_STATUS
-RemoveLastStringFromList (
- IN STRING_LIST *StringList
+AppendCopyOfStringToList (
+ IN OUT STRING_LIST **StringList,
+ IN CHAR8 *String
)
;
+
/**
-
-Routine Description:
-
Removes the last string from StringList and frees the memory associated
with it.
-Arguments:
+ @param StringList The string list to remove the string from
- StringList The string list to remove the string from
-
-Returns:
+ @return EFI_STATUS
+**/
+EFI_STATUS
+RemoveLastStringFromList (
+ IN STRING_LIST *StringList
+ )
+;
- EFI_STATUS
-**/
+/**
+ Allocates a STRING_LIST structure that can store StringCount strings.
+ @param StringCount The number of strings that need to be stored
+ @return EFI_STATUS
+**/
STRING_LIST*
AllocateStringListStruct (
IN UINTN StringCount
)
;
-/**
-
-Routine Description:
-
- Allocates a STRING_LIST structure that can store StringCount strings.
-
-Arguments:
-
- StringCount The number of strings that need to be stored
-Returns:
- EFI_STATUS
-
-**/
-
-
-VOID
-FreeStringList (
- IN STRING_LIST *StringList
- )
-;
/**
-
-Routine Description:
-
Frees all memory associated with StringList.
-Arguments:
-
- StringList The string list to free
-
-Returns:
-
- EFI_STATUS
+ @param StringList The string list to free
+ @return EFI_STATUS
**/
-
-
-CHAR8*
-StringListToString (
+VOID
+FreeStringList (
IN STRING_LIST *StringList
)
;
+
+
/**
-
-Routine Description:
-
Generates a string that represents the STRING_LIST
-Arguments:
+ @param StringList The string list to convert to a string
- StringList The string list to convert to a string
-
-Returns:
-
- CHAR8* - The string list represented with a single string. The returned
+ @return CHAR8* The string list represented with a single string. The returned
string must be freed by the caller.
-
**/
-
-
-VOID
-PrintStringList (
+CHAR8*
+StringListToString (
IN STRING_LIST *StringList
)
;
+
+
/**
-
-Routine Description:
-
Prints out the string list
-Arguments:
-
- StringList The string list to print
-
+ @param StringList The string list to print
**/
+VOID
+PrintStringList (
+ IN STRING_LIST *StringList
+ )
+;
+
#endif
diff --git a/BaseTools/Source/C/Common/BasePeCoff.c b/BaseTools/Source/C/Common/BasePeCoff.c
index 30400d1341dc..b8bfb7b58b91 100644
--- a/BaseTools/Source/C/Common/BasePeCoff.c
+++ b/BaseTools/Source/C/Common/BasePeCoff.c
@@ -77,33 +77,23 @@ PeCoffLoaderRelocateLoongArch64Image (
IN UINT64 Adjust
);
-STATIC
-RETURN_STATUS
-PeCoffLoaderGetPeHeader (
- IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext,
- OUT EFI_IMAGE_OPTIONAL_HEADER_UNION **PeHdr,
- OUT EFI_TE_IMAGE_HEADER **TeHdr
- )
-/*++
-
-Routine Description:
-
+/**
Retrieves the PE or TE Header from a PE/COFF or TE image
-Arguments:
+ @param ImageContext The context of the image being loaded
+ @param PeHdr The buffer in which to return the PE header
+ @param TeHdr The buffer in which to return the TE header
- ImageContext - The context of the image being loaded
-
- PeHdr - The buffer in which to return the PE header
-
- TeHdr - The buffer in which to return the TE header
-
-Returns:
-
- RETURN_SUCCESS if the PE or TE Header is read,
+ @return RETURN_SUCCESS if the PE or TE Header is read,
Otherwise, the error status from reading the PE/COFF or TE image using the ImageRead function.
-
---*/
+**/
+STATIC
+RETURN_STATUS
+PeCoffLoaderGetPeHeader (
+ IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext,
+ OUT EFI_IMAGE_OPTIONAL_HEADER_UNION **PeHdr,
+ OUT EFI_TE_IMAGE_HEADER **TeHdr
+ )
{
RETURN_STATUS Status;
EFI_IMAGE_DOS_HEADER DosHdr;
@@ -150,6 +140,17 @@ Routine Description:
return RETURN_SUCCESS;
}
+/**
+ Checks the PE or TE header of a PE/COFF or TE image to determine if it supported
+
+ @param ImageContext The context of the image being loaded
+ @param PeHdr The buffer in which to return the PE header
+ @param TeHdr The buffer in which to return the TE header
+
+ @retval RETURN_SUCCESS if the PE/COFF or TE image is supported
+ @retval RETURN_UNSUPPORTED of the PE/COFF or TE image is not supported.
+
+**/
STATIC
RETURN_STATUS
PeCoffLoaderCheckImageType (
@@ -157,26 +158,6 @@ PeCoffLoaderCheckImageType (
IN EFI_IMAGE_OPTIONAL_HEADER_UNION *PeHdr,
IN EFI_TE_IMAGE_HEADER *TeHdr
)
-/*++
-
-Routine Description:
-
- Checks the PE or TE header of a PE/COFF or TE image to determine if it supported
-
-Arguments:
-
- ImageContext - The context of the image being loaded
-
- PeHdr - The buffer in which to return the PE header
-
- TeHdr - The buffer in which to return the TE header
-
-Returns:
-
- RETURN_SUCCESS if the PE/COFF or TE image is supported
- RETURN_UNSUPPORTED of the PE/COFF or TE image is not supported.
-
---*/
{
//
// See if the machine type is supported.
@@ -239,31 +220,24 @@ Routine Description:
return RETURN_SUCCESS;
}
+/**
+ Retrieves information on a PE/COFF image
+
+ @param This Calling context
+ @param ImageContext The context of the image being loaded
+
+ @retval RETURN_SUCCESS The information on the PE/COFF image was collected.
+ @retval RETURN_INVALID_PARAMETER ImageContext is NULL.
+ @retval RETURN_UNSUPPORTED The PE/COFF image is not supported.
+ @retval Otherwise The error status from reading the PE/COFF image using the
+ ImageContext->ImageRead() function
+
+**/
RETURN_STATUS
EFIAPI
PeCoffLoaderGetImageInfo (
IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext
)
-/*++
-
-Routine Description:
-
- Retrieves information on a PE/COFF image
-
-Arguments:
-
- This - Calling context
- ImageContext - The context of the image being loaded
-
-Returns:
-
- RETURN_SUCCESS - The information on the PE/COFF image was collected.
- RETURN_INVALID_PARAMETER - ImageContext is NULL.
- RETURN_UNSUPPORTED - The PE/COFF image is not supported.
- Otherwise - The error status from reading the PE/COFF image using the
- ImageContext->ImageRead() function
-
---*/
{
RETURN_STATUS Status;
EFI_IMAGE_OPTIONAL_HEADER_UNION *PeHdr;
@@ -539,29 +513,21 @@ Routine Description:
return RETURN_SUCCESS;
}
-STATIC
-VOID *
-PeCoffLoaderImageAddress (
- IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext,
- IN UINTN Address
- )
-/*++
-
-Routine Description:
-
+/**
Converts an image address to the loaded address
-Arguments:
+ @param ImageContext The context of the image being loaded
+ @param Address The address to be converted to the loaded address
- ImageContext - The context of the image being loaded
-
- Address - The address to be converted to the loaded address
-
-Returns:
-
- NULL if the address can not be converted, otherwise, the converted address
+ @return NULL if the address can not be converted, otherwise, the converted address
--*/
+STATIC
+VOID *
+PeCoffLoaderImageAddress (
+ IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext,
+ IN UINTN Address
+ )
{
if (Address >= ImageContext->ImageSize) {
ImageContext->ImageError = IMAGE_ERROR_INVALID_IMAGE_ADDRESS;
@@ -571,30 +537,22 @@ Routine Description:
return (UINT8 *) ((UINTN) ImageContext->ImageAddress + Address);
}
-RETURN_STATUS
-EFIAPI
-PeCoffLoaderRelocateImage (
- IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext
- )
-/*++
-
-Routine Description:
-
+/**
Relocates a PE/COFF image in memory
-Arguments:
-
- This - Calling context
-
- ImageContext - Contains information on the loaded image to relocate
-
-Returns:
-
- RETURN_SUCCESS if the PE/COFF image was relocated
- RETURN_LOAD_ERROR if the image is not a valid PE/COFF image
- RETURN_UNSUPPORTED not support
-
---*/
+ @param This Calling context
+ @param ImageContext Contains information on the loaded image to relocate
+
+ @retval RETURN_SUCCESS if the PE/COFF image was relocated
+ @retval RETURN_LOAD_ERROR if the image is not a valid PE/COFF image
+ @retval RETURN_UNSUPPORTED not support
+
+**/
+RETURN_STATUS
+EFIAPI
+PeCoffLoaderRelocateImage (
+ IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext
+ )
{
RETURN_STATUS Status;
EFI_IMAGE_OPTIONAL_HEADER_UNION *PeHdr;
@@ -853,31 +811,23 @@ Routine Description:
return RETURN_SUCCESS;
}
-RETURN_STATUS
-EFIAPI
-PeCoffLoaderLoadImage (
- IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext
- )
-/*++
-
-Routine Description:
-
+/**
Loads a PE/COFF image into memory
-Arguments:
-
- This - Calling context
-
- ImageContext - Contains information on image to load into memory
-
-Returns:
-
- RETURN_SUCCESS if the PE/COFF image was loaded
- RETURN_BUFFER_TOO_SMALL if the caller did not provide a large enough buffer
- RETURN_LOAD_ERROR if the image is a runtime driver with no relocations
- RETURN_INVALID_PARAMETER if the image address is invalid
-
---*/
+ @param This Calling context
+ @param ImageContext Contains information on image to load into memory
+
+ @retval RETURN_SUCCESS if the PE/COFF image was loaded
+ @retval RETURN_BUFFER_TOO_SMALL if the caller did not provide a large enough buffer
+ @retval RETURN_LOAD_ERROR if the image is a runtime driver with no relocations
+ @retval RETURN_INVALID_PARAMETER if the image address is invalid
+
+**/
+RETURN_STATUS
+EFIAPI
+PeCoffLoaderLoadImage (
+ IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext
+ )
{
RETURN_STATUS Status;
EFI_IMAGE_OPTIONAL_HEADER_UNION *PeHdr;
diff --git a/BaseTools/Source/C/Common/CommonLib.c b/BaseTools/Source/C/Common/CommonLib.c
index 7fb4ab764fcd..cd270f9a9074 100644
--- a/BaseTools/Source/C/Common/CommonLib.c
+++ b/BaseTools/Source/C/Common/CommonLib.c
@@ -26,28 +26,17 @@ SPDX-License-Identifier: BSD-2-Clause-Patent
} \
} while (FALSE)
-VOID
-PeiZeroMem (
- IN VOID *Buffer,
- IN UINTN Size
- )
-/*++
-
-Routine Description:
-
+/**
Set Buffer to zero for Size bytes.
-Arguments:
-
- Buffer - Memory to set.
-
- Size - Number of bytes to set
-
-Returns:
-
- None
-
---*/
+ @param Buffer Memory to set.
+ @param Size Number of bytes to set
+**/
+VOID
+PeiZeroMem (
+ IN VOID *Buffer,
+ IN UINTN Size
+ )
{
INT8 *Ptr;
@@ -57,31 +46,19 @@ Routine Description:
}
}
-VOID
-PeiCopyMem (
- IN VOID *Destination,
- IN VOID *Source,
- IN UINTN Length
- )
-/*++
-
-Routine Description:
-
+/**
Copy Length bytes from Source to Destination.
-Arguments:
-
- Destination - Target of copy
-
- Source - Place to copy from
-
- Length - Number of bytes to copy
-
-Returns:
-
- None
-
---*/
+ @param Destination Target of copy
+ @param Source Place to copy from
+ @param Length Number of bytes to copy
+**/
+VOID
+PeiCopyMem (
+ IN VOID *Destination,
+ IN VOID *Source,
+ IN UINTN Length
+ )
{
CHAR8 *Destination8;
CHAR8 *Source8;
@@ -112,27 +89,20 @@ CopyMem (
PeiCopyMem (Destination, Source, Length);
}
+/**
+ Compares to GUIDs
+
+ @param Guid1 guid to compare
+ @param Guid2 guid to compare
+
+ @retval = 0 if Guid1 == Guid2
+ @retval != 0 if Guid1 != Guid2
+**/
INTN
CompareGuid (
IN EFI_GUID *Guid1,
IN EFI_GUID *Guid2
)
-/*++
-
-Routine Description:
-
- Compares to GUIDs
-
-Arguments:
-
- Guid1 - guid to compare
- Guid2 - guid to compare
-
-Returns:
- = 0 if Guid1 == Guid2
- != 0 if Guid1 != Guid2
-
---*/
{
INT32 *g1;
INT32 *g2;
@@ -152,34 +122,25 @@ Routine Description:
return r;
}
+/**
+ This function opens a file and reads it into a memory buffer. The function
+ will allocate the memory buffer and returns the size of the buffer.
+ @param InputFileName The name of the file to read.
+ @param InputFileImage A pointer to the memory buffer.
+ @param BytesRead The size of the memory buffer.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER One of the input parameters was invalid.
+ @retval EFI_ABORTED An error occurred.
+ @retval EFI_OUT_OF_RESOURCES No resource to complete operations.
+**/
EFI_STATUS
GetFileImage (
IN CHAR8 *InputFileName,
OUT CHAR8 **InputFileImage,
OUT UINT32 *BytesRead
)
-/*++
-
-Routine Description:
-
- This function opens a file and reads it into a memory buffer. The function
- will allocate the memory buffer and returns the size of the buffer.
-
-Arguments:
-
- InputFileName The name of the file to read.
- InputFileImage A pointer to the memory buffer.
- BytesRead The size of the memory buffer.
-
-Returns:
-
- EFI_SUCCESS The function completed successfully.
- EFI_INVALID_PARAMETER One of the input parameters was invalid.
- EFI_ABORTED An error occurred.
- EFI_OUT_OF_RESOURCES No resource to complete operations.
-
---*/
{
FILE *InputFile;
UINT32 FileSize;
@@ -255,32 +216,24 @@ Routine Description:
return EFI_SUCCESS;
}
+/**
+ This function opens a file and writes OutputFileImage into the file.
+
+ @param OutputFileName The name of the file to write.
+ @param OutputFileImage A pointer to the memory buffer.
+ @param BytesToWrite The size of the memory buffer.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER One of the input parameters was invalid.
+ @retval EFI_ABORTED An error occurred.
+ @retval EFI_OUT_OF_RESOURCES No resource to complete operations.
+**/
EFI_STATUS
PutFileImage (
IN CHAR8 *OutputFileName,
IN CHAR8 *OutputFileImage,
IN UINT32 BytesToWrite
)
-/*++
-
-Routine Description:
-
- This function opens a file and writes OutputFileImage into the file.
-
-Arguments:
-
- OutputFileName The name of the file to write.
- OutputFileImage A pointer to the memory buffer.
- BytesToWrite The size of the memory buffer.
-
-Returns:
-
- EFI_SUCCESS The function completed successfully.
- EFI_INVALID_PARAMETER One of the input parameters was invalid.
- EFI_ABORTED An error occurred.
- EFI_OUT_OF_RESOURCES No resource to complete operations.
-
---*/
{
FILE *OutputFile;
UINT32 BytesWrote;
@@ -320,52 +273,36 @@ Routine Description:
return EFI_SUCCESS;
}
+/**
+ This function calculates the value needed for a valid UINT8 checksum
+
+ @param Buffer Pointer to buffer containing byte data of component.
+ @param Size Size of the buffer
+
+ @return The 8 bit checksum value needed.
+**/
UINT8
CalculateChecksum8 (
IN UINT8 *Buffer,
IN UINTN Size
)
-/*++
-
-Routine Description:
-
- This function calculates the value needed for a valid UINT8 checksum
-
-Arguments:
-
- Buffer Pointer to buffer containing byte data of component.
- Size Size of the buffer
-
-Returns:
-
- The 8 bit checksum value needed.
-
---*/
{
return (UINT8) (0x100 - CalculateSum8 (Buffer, Size));
}
+/**
+ This function calculates the UINT8 sum for the requested region.
+
+ @param Buffer Pointer to buffer containing byte data of component.
+ @param Size Size of the buffer
+
+ @return The 8 bit checksum value needed.
+**/
UINT8
CalculateSum8 (
IN UINT8 *Buffer,
IN UINTN Size
)
-/*++
-
-Routine Description::
-
- This function calculates the UINT8 sum for the requested region.
-
-Arguments:
-
- Buffer Pointer to buffer containing byte data of component.
- Size Size of the buffer
-
-Returns:
-
- The 8 bit checksum value needed.
-
---*/
{
UINTN Index;
UINT8 Sum;
@@ -382,52 +319,36 @@ Routine Description::
return Sum;
}
-UINT16
-CalculateChecksum16 (
- IN UINT16 *Buffer,
- IN UINTN Size
- )
-/*++
-
-Routine Description::
-
+/**
This function calculates the value needed for a valid UINT16 checksum
-Arguments:
-
- Buffer Pointer to buffer containing byte data of component.
- Size Size of the buffer
-
-Returns:
-
- The 16 bit checksum value needed.
-
---*/
+ @param Buffer Pointer to buffer containing byte data of component.
+ @param Size Size of the buffer
+
+ @return The 16 bit checksum value needed.
+**/
+UINT16
+CalculateChecksum16 (
+ IN UINT16 *Buffer,
+ IN UINTN Size
+ )
{
return (UINT16) (0x10000 - CalculateSum16 (Buffer, Size));
}
-UINT16
-CalculateSum16 (
- IN UINT16 *Buffer,
- IN UINTN Size
- )
-/*++
-
-Routine Description:
-
+/**
This function calculates the UINT16 sum for the requested region.
-Arguments:
-
- Buffer Pointer to buffer containing byte data of component.
- Size Size of the buffer
-
-Returns:
-
- The 16 bit checksum
-
---*/
+ @param Buffer Pointer to buffer containing byte data of component.
+ @param Size Size of the buffer
+
+ @return The 16 bit checksum
+**/
+UINT16
+CalculateSum16 (
+ IN UINT16 *Buffer,
+ IN UINTN Size
+ )
{
UINTN Index;
UINT16 Sum;
@@ -444,26 +365,18 @@ Routine Description:
return (UINT16) Sum;
}
+/**
+ This function prints a GUID to STDOUT.
+
+ @param Guid Pointer to a GUID to print.
+
+ @retval EFI_SUCCESS The GUID was printed.
+ @retval EFI_INVALID_PARAMETER The input was NULL.
+**/
EFI_STATUS
PrintGuid (
IN EFI_GUID *Guid
)
-/*++
-
-Routine Description:
-
- This function prints a GUID to STDOUT.
-
-Arguments:
-
- Guid Pointer to a GUID to print.
-
-Returns:
-
- EFI_SUCCESS The GUID was printed.
- EFI_INVALID_PARAMETER The input was NULL.
-
---*/
{
if (Guid == NULL) {
Error (NULL, 0, 2000, "Invalid parameter", "PrintGuidToBuffer() called with a NULL value");
@@ -487,6 +400,18 @@ Routine Description:
return EFI_SUCCESS;
}
+/**
+ This function prints a GUID to a buffer
+
+ @param Guid Pointer to a GUID to print.
+ @param Buffer Pointer to a user-provided buffer to print to
+ @param BufferLen Size of the Buffer
+ @param Uppercase If use upper case.
+
+ @retval EFI_SUCCESS The GUID was printed.
+ @retval EFI_INVALID_PARAMETER The input was NULL.
+ @retval EFI_BUFFER_TOO_SMALL The input buffer was not big enough
+**/
EFI_STATUS
PrintGuidToBuffer (
IN EFI_GUID *Guid,
@@ -494,26 +419,6 @@ PrintGuidToBuffer (
IN UINT32 BufferLen,
IN BOOLEAN Uppercase
)
-/*++
-
-Routine Description:
-
- This function prints a GUID to a buffer
-
-Arguments:
-
- Guid - Pointer to a GUID to print.
- Buffer - Pointer to a user-provided buffer to print to
- BufferLen - Size of the Buffer
- Uppercase - If use upper case.
-
-Returns:
-
- EFI_SUCCESS The GUID was printed.
- EFI_INVALID_PARAMETER The input was NULL.
- EFI_BUFFER_TOO_SMALL The input buffer was not big enough
-
---*/
{
if (Guid == NULL) {
Error (NULL, 0, 2000, "Invalid parameter", "PrintGuidToBuffer() called with a NULL value");
@@ -591,22 +496,17 @@ char *strlwr(char *s)
//
CHAR8 mCommonLibFullPath[MAX_LONG_FILE_PATH];
+/**
+ Convert FileName to the long file path, which can support larger than 260 length.
+
+ @param FileName FileName.
+
+ @return LongFilePath A pointer to the converted long file path.
+**/
CHAR8 *
LongFilePath (
IN CHAR8 *FileName
)
-/*++
-
-Routine Description:
- Convert FileName to the long file path, which can support larger than 260 length.
-
-Arguments:
- FileName - FileName.
-
-Returns:
- LongFilePath A pointer to the converted long file path.
-
---*/
{
#ifdef __GNUC__
//
diff --git a/BaseTools/Source/C/Common/Crc32.c b/BaseTools/Source/C/Common/Crc32.c
index 7281d5f0e913..00cae948985d 100644
--- a/BaseTools/Source/C/Common/Crc32.c
+++ b/BaseTools/Source/C/Common/Crc32.c
@@ -268,31 +268,23 @@ UINT32 mCrcTable[256] = {
0x2D02EF8D
};
+/**
+ The CalculateCrc32 routine.
+
+ @param Data The buffer containing the data to be processed
+ @param DataSize The size of data to be processed
+ @param CrcOut A pointer to the caller allocated UINT32 that on
+ contains the CRC32 checksum of Data
+
+ @retval EFI_SUCCESS Calculation is successful.
+ @retval EFI_INVALID_PARAMETER Data / CrcOut = NULL, or DataSize = 0
+**/
EFI_STATUS
CalculateCrc32 (
IN UINT8 *Data,
IN UINTN DataSize,
IN OUT UINT32 *CrcOut
)
-/*++
-
-Routine Description:
-
- The CalculateCrc32 routine.
-
-Arguments:
-
- Data - The buffer containing the data to be processed
- DataSize - The size of data to be processed
- CrcOut - A pointer to the caller allocated UINT32 that on
- contains the CRC32 checksum of Data
-
-Returns:
-
- EFI_SUCCESS - Calculation is successful.
- EFI_INVALID_PARAMETER - Data / CrcOut = NULL, or DataSize = 0
-
---*/
{
UINT32 Crc;
UINTN Index;
diff --git a/BaseTools/Source/C/Common/Decompress.c b/BaseTools/Source/C/Common/Decompress.c
index d85098f13140..a0f54c08342b 100644
--- a/BaseTools/Source/C/Common/Decompress.c
+++ b/BaseTools/Source/C/Common/Decompress.c
@@ -62,26 +62,18 @@ typedef struct {
STATIC UINT16 mPbit = EFIPBIT;
-STATIC
-VOID
-FillBuf (
- IN SCRATCH_DATA *Sd,
- IN UINT16 NumOfBits
- )
-/*++
-
-Routine Description:
-
+/**
Shift mBitBuf NumOfBits left. Read in NumOfBits of bits from source.
-Arguments:
-
- Sd - The global scratch data
- NumOfBit - The number of bits to shift and read.
-
-Returns: (VOID)
-
---*/
+ @param Sd The global scratch data
+ @param NumOfBit The number of bits to shift and read.
+**/
+STATIC
+VOID
+FillBuf (
+ IN SCRATCH_DATA *Sd,
+ IN UINT16 NumOfBits
+ )
{
Sd->mBitBuf = (UINT32) (((UINT64)Sd->mBitBuf) << NumOfBits);
@@ -112,30 +104,22 @@ Returns: (VOID)
Sd->mBitBuf |= Sd->mSubBitBuf >> Sd->mBitCount;
}
-STATIC
-UINT32
-GetBits (
- IN SCRATCH_DATA *Sd,
- IN UINT16 NumOfBits
- )
-/*++
-
-Routine Description:
-
+/**
Get NumOfBits of bits out from mBitBuf. Fill mBitBuf with subsequent
NumOfBits of bits from source. Returns NumOfBits of bits that are
popped out.
-Arguments:
-
- Sd - The global scratch data.
- NumOfBits - The number of bits to pop and read.
-
-Returns:
-
- The bits that are popped out.
-
---*/
+ @param Sd The global scratch data.
+ @param NumOfBits The number of bits to pop and read.
+
+ @return The bits that are popped out.
+**/
+STATIC
+UINT32
+GetBits (
+ IN SCRATCH_DATA *Sd,
+ IN UINT16 NumOfBits
+ )
{
UINT32 OutBits;
@@ -146,6 +130,18 @@ Routine Description:
return OutBits;
}
+/**
+ Creates Huffman Code mapping table according to code length array.
+
+ @param Sd The global scratch data
+ @param NumOfChar Number of symbols in the symbol set
+ @param BitLen Code length array
+ @param TableBits The width of the mapping table
+ @param Table The table
+
+ @retval 0 - OK.
+ @retval BAD_TABLE - The table is corrupted.
+**/
STATIC
UINT16
MakeTable (
@@ -155,26 +151,6 @@ MakeTable (
IN UINT16 TableBits,
OUT UINT16 *Table
)
-/*++
-
-Routine Description:
-
- Creates Huffman Code mapping table according to code length array.
-
-Arguments:
-
- Sd - The global scratch data
- NumOfChar - Number of symbols in the symbol set
- BitLen - Code length array
- TableBits - The width of the mapping table
- Table - The table
-
-Returns:
-
- 0 - OK.
- BAD_TABLE - The table is corrupted.
-
---*/
{
UINT16 Count[17];
UINT16 Weight[17];
@@ -290,26 +266,18 @@ Routine Description:
return 0;
}
+/**
+ Decodes a position value.
+
+ @param Sd the global scratch data
+
+ @return The position value decoded.
+**/
STATIC
UINT32
DecodeP (
IN SCRATCH_DATA *Sd
)
-/*++
-
-Routine Description:
-
- Decodes a position value.
-
-Arguments:
-
- Sd - the global scratch data
-
-Returns:
-
- The position value decoded.
-
---*/
{
UINT16 Val;
UINT32 Mask;
@@ -344,6 +312,17 @@ Routine Description:
return Pos;
}
+/**
+ Reads code lengths for the Extra Set or the Position Set
+
+ @param Sd The global scratch data
+ @param nn Number of symbols
+ @param nbit Number of bits needed to represent nn
+ @param Special The special symbol that needs to be taken care of
+
+ @retval 0 - OK.
+ @retval BAD_TABLE - Table is corrupted.
+**/
STATIC
UINT16
ReadPTLen (
@@ -352,25 +331,6 @@ ReadPTLen (
IN UINT16 nbit,
IN UINT16 Special
)
-/*++
-
-Routine Description:
-
- Reads code lengths for the Extra Set or the Position Set
-
-Arguments:
-
- Sd - The global scratch data
- nn - Number of symbols
- nbit - Number of bits needed to represent nn
- Special - The special symbol that needs to be taken care of
-
-Returns:
-
- 0 - OK.
- BAD_TABLE - Table is corrupted.
-
---*/
{
UINT16 Number;
UINT16 CharC;
@@ -430,24 +390,16 @@ Routine Description:
return MakeTable (Sd, nn, Sd->mPTLen, 8, Sd->mPTTable);
}
-STATIC
-VOID
-ReadCLen (
- SCRATCH_DATA *Sd
- )
-/*++
-
-Routine Description:
-
+/**
Reads code lengths for Char&Len Set.
-Arguments:
-
- Sd - the global scratch data
-
-Returns: (VOID)
-
---*/
+ @param Sd the global scratch data
+**/
+STATIC
+VOID
+ReadCLen (
+ SCRATCH_DATA *Sd
+ )
{
UINT16 Number;
UINT16 CharC;
@@ -526,26 +478,18 @@ Returns: (VOID)
return ;
}
-STATIC
-UINT16
-DecodeC (
- SCRATCH_DATA *Sd
- )
-/*++
-
-Routine Description:
-
+/**
Decode a character/length value.
-Arguments:
-
- Sd - The global scratch data.
-
-Returns:
-
- The value decoded.
-
---*/
+ @param Sd The global scratch data.
+
+ @return The value decoded.
+**/
+STATIC
+UINT16
+DecodeC (
+ SCRATCH_DATA *Sd
+ )
{
UINT16 Index2;
UINT32 Mask;
@@ -592,24 +536,16 @@ Routine Description:
return Index2;
}
-STATIC
-VOID
-Decode (
- SCRATCH_DATA *Sd
- )
-/*++
-
-Routine Description:
-
+/**
Decode the source data and put the resulting data into the destination buffer.
-Arguments:
-
- Sd - The global scratch data
-
-Returns: (VOID)
-
- --*/
+ @param Sd The global scratch data
+ **/
+STATIC
+VOID
+Decode (
+ SCRATCH_DATA *Sd
+ )
{
UINT16 BytesRemain;
UINT32 DataIdx;
@@ -669,32 +605,24 @@ Returns: (VOID)
return ;
}
-EFI_STATUS
-GetInfo (
- IN VOID *Source,
- IN UINT32 SrcSize,
- OUT UINT32 *DstSize,
- OUT UINT32 *ScratchSize
- )
-/*++
-
-Routine Description:
-
+/**
The implementation of EFI_DECOMPRESS_PROTOCOL.GetInfo().
-Arguments:
-
- Source - The source buffer containing the compressed data.
- SrcSize - The size of source buffer
- DstSize - The size of destination buffer.
- ScratchSize - The size of scratch buffer.
-
-Returns:
-
- EFI_SUCCESS - The size of destination buffer and the size of scratch buffer are successfully retrieved.
- EFI_INVALID_PARAMETER - The source data is corrupted
-
---*/
+ @param Source The source buffer containing the compressed data.
+ @param SrcSize The size of source buffer
+ @param DstSize The size of destination buffer.
+ @param ScratchSize The size of scratch buffer.
+
+ @retval EFI_SUCCESS - The size of destination buffer and the size of scratch buffer are successfully retrieved.
+ @retval EFI_INVALID_PARAMETER - The source data is corrupted
+**/
+EFI_STATUS
+GetInfo (
+ IN VOID *Source,
+ IN UINT32 SrcSize,
+ OUT UINT32 *DstSize,
+ OUT UINT32 *ScratchSize
+ )
{
UINT8 *Src;
UINT32 CompSize;
@@ -716,36 +644,28 @@ Routine Description:
return EFI_SUCCESS;
}
-EFI_STATUS
-Decompress (
- IN VOID *Source,
- IN UINT32 SrcSize,
- IN OUT VOID *Destination,
- IN UINT32 DstSize,
- IN OUT VOID *Scratch,
- IN UINT32 ScratchSize
- )
-/*++
-
-Routine Description:
-
+/**
The implementation Efi and Tiano Decompress().
-Arguments:
+ @param Source - The source buffer containing the compressed data.
+ @param SrcSize - The size of source buffer
+ @param Destination - The destination buffer to store the decompressed data
+ @param DstSize - The size of destination buffer.
+ @param Scratch - The buffer used internally by the decompress routine. This buffer is needed to store intermediate data.
+ @param ScratchSize - The size of scratch buffer.
- Source - The source buffer containing the compressed data.
- SrcSize - The size of source buffer
- Destination - The destination buffer to store the decompressed data
- DstSize - The size of destination buffer.
- Scratch - The buffer used internally by the decompress routine. This buffer is needed to store intermediate data.
- ScratchSize - The size of scratch buffer.
-
-Returns:
-
- EFI_SUCCESS - Decompression is successful
- EFI_INVALID_PARAMETER - The source data is corrupted
-
---*/
+ @retval EFI_SUCCESS - Decompression is successful
+ @retval EFI_INVALID_PARAMETER - The source data is corrupted
+**/
+EFI_STATUS
+Decompress (
+ IN VOID *Source,
+ IN UINT32 SrcSize,
+ IN OUT VOID *Destination,
+ IN UINT32 DstSize,
+ IN OUT VOID *Scratch,
+ IN UINT32 ScratchSize
+ )
{
UINT32 Index;
UINT32 CompSize;
@@ -811,131 +731,99 @@ Routine Description:
return Status;
}
-EFI_STATUS
-EfiGetInfo (
- IN VOID *Source,
- IN UINT32 SrcSize,
- OUT UINT32 *DstSize,
- OUT UINT32 *ScratchSize
- )
-/*++
-
-Routine Description:
-
+/**
The implementation Efi Decompress GetInfo().
-Arguments:
-
- Source - The source buffer containing the compressed data.
- SrcSize - The size of source buffer
- DstSize - The size of destination buffer.
- ScratchSize - The size of scratch buffer.
-
-Returns:
-
- EFI_SUCCESS - The size of destination buffer and the size of scratch buffer are successfully retrieved.
- EFI_INVALID_PARAMETER - The source data is corrupted
-
---*/
-{
- return GetInfo (Source, SrcSize, DstSize, ScratchSize);
-}
-
+ @param Source The source buffer containing the compressed data.
+ @param SrcSize The size of source buffer
+ @param DstSize The size of destination buffer.
+ @param ScratchSize The size of scratch buffer.
+
+ @retval EFI_SUCCESS The size of destination buffer and the size of scratch buffer are successfully retrieved.
+ @retval EFI_INVALID_PARAMETER The source data is corrupted
+**/
EFI_STATUS
-TianoGetInfo (
+EfiGetInfo (
IN VOID *Source,
IN UINT32 SrcSize,
OUT UINT32 *DstSize,
OUT UINT32 *ScratchSize
)
-/*++
-
-Routine Description:
+{
+ return GetInfo (Source, SrcSize, DstSize, ScratchSize);
+}
+/**
The implementation Tiano Decompress GetInfo().
-Arguments:
-
- Source - The source buffer containing the compressed data.
- SrcSize - The size of source buffer
- DstSize - The size of destination buffer.
- ScratchSize - The size of scratch buffer.
-
-Returns:
-
- EFI_SUCCESS - The size of destination buffer and the size of scratch buffer are successfully retrieved.
- EFI_INVALID_PARAMETER - The source data is corrupted
-
---*/
-{
- return GetInfo (Source, SrcSize, DstSize, ScratchSize);
-}
-
+ @param Source The source buffer containing the compressed data.
+ @param SrcSize The size of source buffer
+ @param DstSize The size of destination buffer.
+ @param ScratchSize The size of scratch buffer.
+
+ @retval EFI_SUCCESS The size of destination buffer and the size of scratch buffer are successfully retrieved.
+ @retval EFI_INVALID_PARAMETER The source data is corrupted
+**/
EFI_STATUS
-EfiDecompress (
+TianoGetInfo (
IN VOID *Source,
IN UINT32 SrcSize,
- IN OUT VOID *Destination,
- IN UINT32 DstSize,
- IN OUT VOID *Scratch,
- IN UINT32 ScratchSize
+ OUT UINT32 *DstSize,
+ OUT UINT32 *ScratchSize
)
-/*++
-
-Routine Description:
+{
+ return GetInfo (Source, SrcSize, DstSize, ScratchSize);
+}
+/**
The implementation of Efi Decompress().
-Arguments:
+ @param Source The source buffer containing the compressed data.
+ @param SrcSize The size of source buffer
+ @param Destination The destination buffer to store the decompressed data
+ @param DstSize The size of destination buffer.
+ @param Scratch The buffer used internally by the decompress routine. This buffer is needed to store intermediate data.
+ @param ScratchSize The size of scratch buffer.
- Source - The source buffer containing the compressed data.
- SrcSize - The size of source buffer
- Destination - The destination buffer to store the decompressed data
- DstSize - The size of destination buffer.
- Scratch - The buffer used internally by the decompress routine. This buffer is needed to store intermediate data.
- ScratchSize - The size of scratch buffer.
-
-Returns:
-
- EFI_SUCCESS - Decompression is successful
- EFI_INVALID_PARAMETER - The source data is corrupted
-
---*/
+ @retval EFI_SUCCESS Decompression is successful
+ @retval EFI_INVALID_PARAMETER The source data is corrupted
+**/
+EFI_STATUS
+EfiDecompress (
+ IN VOID *Source,
+ IN UINT32 SrcSize,
+ IN OUT VOID *Destination,
+ IN UINT32 DstSize,
+ IN OUT VOID *Scratch,
+ IN UINT32 ScratchSize
+ )
{
mPbit = EFIPBIT;
return Decompress (Source, SrcSize, Destination, DstSize, Scratch, ScratchSize);
}
-EFI_STATUS
-TianoDecompress (
- IN VOID *Source,
- IN UINT32 SrcSize,
- IN OUT VOID *Destination,
- IN UINT32 DstSize,
- IN OUT VOID *Scratch,
- IN UINT32 ScratchSize
- )
-/*++
-
-Routine Description:
-
+/**
The implementation of Tiano Decompress().
-Arguments:
+ @param Source The source buffer containing the compressed data.
+ @param SrcSize The size of source buffer
+ @param Destination The destination buffer to store the decompressed data
+ @param DstSize The size of destination buffer.
+ @param Scratch The buffer used internally by the decompress routine. This buffer is needed to store intermediate data.
+ @param ScratchSize The size of scratch buffer.
- Source - The source buffer containing the compressed data.
- SrcSize - The size of source buffer
- Destination - The destination buffer to store the decompressed data
- DstSize - The size of destination buffer.
- Scratch - The buffer used internally by the decompress routine. This buffer is needed to store intermediate data.
- ScratchSize - The size of scratch buffer.
-
-Returns:
-
- EFI_SUCCESS - Decompression is successful
- EFI_INVALID_PARAMETER - The source data is corrupted
-
---*/
+ @retval EFI_SUCCESS Decompression is successful
+ @retval EFI_INVALID_PARAMETER The source data is corrupted
+**/
+EFI_STATUS
+TianoDecompress (
+ IN VOID *Source,
+ IN UINT32 SrcSize,
+ IN OUT VOID *Destination,
+ IN UINT32 DstSize,
+ IN OUT VOID *Scratch,
+ IN UINT32 ScratchSize
+ )
{
mPbit = MAXPBIT;
return Decompress (Source, SrcSize, Destination, DstSize, Scratch, ScratchSize);
diff --git a/BaseTools/Source/C/Common/EfiCompress.c b/BaseTools/Source/C/Common/EfiCompress.c
index db5ebe3157d2..0db958b8535a 100644
--- a/BaseTools/Source/C/Common/EfiCompress.c
+++ b/BaseTools/Source/C/Common/EfiCompress.c
@@ -250,6 +250,20 @@ STATIC NODE mPos, mMatchPos, mAvail, *mPosition, *mParent, *mPrev, *mNext = NU
// functions
//
+/**
+ The main compression routine.
+
+ @param SrcBuffer The buffer storing the source data
+ @param SrcSize The size of source data
+ @param DstBuffer The buffer to store the compressed data
+ @param DstSize On input, the size of DstBuffer; On output,
+ the size of the actual compressed data.
+
+ @retval EFI_BUFFER_TOO_SMALL The DstBuffer is too small. In this case,
+ DstSize contains the size needed.
+ @retval EFI_SUCCESS Compression is successful.
+
+**/
EFI_STATUS
EfiCompress (
IN UINT8 *SrcBuffer,
@@ -257,27 +271,6 @@ EfiCompress (
IN UINT8 *DstBuffer,
IN OUT UINT32 *DstSize
)
-/*++
-
-Routine Description:
-
- The main compression routine.
-
-Arguments:
-
- SrcBuffer - The buffer storing the source data
- SrcSize - The size of source data
- DstBuffer - The buffer to store the compressed data
- DstSize - On input, the size of DstBuffer; On output,
- the size of the actual compressed data.
-
-Returns:
-
- EFI_BUFFER_TOO_SMALL - The DstBuffer is too small. In this case,
- DstSize contains the size needed.
- EFI_SUCCESS - Compression is successful.
-
---*/
{
EFI_STATUS Status = EFI_SUCCESS;
@@ -345,24 +338,16 @@ Routine Description:
}
-STATIC
-VOID
-PutDword(
- IN UINT32 Data
- )
-/*++
-
-Routine Description:
-
+/**
Put a dword to output stream
-Arguments:
-
- Data - the dword to put
-
-Returns: (VOID)
-
---*/
+ @param Data the dword to put
+**/
+STATIC
+VOID
+PutDword(
+ IN UINT32 Data
+ )
{
if (mDst < mDstUpperLimit) {
*mDst++ = (UINT8)(((UINT8)(Data )) & 0xff);
@@ -381,23 +366,15 @@ Returns: (VOID)
}
}
-STATIC
-EFI_STATUS
-AllocateMemory ()
-/*++
-
-Routine Description:
-
+/**
Allocate memory spaces for data structures used in compression process
-Arguments: (VOID)
-
-Returns:
-
- EFI_SUCCESS - Memory is allocated successfully
- EFI_OUT_OF_RESOURCES - Allocation fails
-
---*/
+ @retval EFI_SUCCESS Memory is allocated successfully
+ @retva; EFI_OUT_OF_RESOURCES Allocation fails
+**/
+STATIC
+EFI_STATUS
+AllocateMemory ()
{
UINT32 i;
@@ -432,19 +409,11 @@ Arguments: (VOID)
return EFI_SUCCESS;
}
-VOID
-FreeMemory ()
-/*++
-
-Routine Description:
-
+/**
Called when compression is completed to free memory previously allocated.
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+VOID
+FreeMemory ()
{
if (mText) {
free (mText);
@@ -481,21 +450,12 @@ Returns: (VOID)
return;
}
-
-STATIC
-VOID
-InitSlide ()
-/*++
-
-Routine Description:
-
+/**
Initialize String Info Log data structures
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+InitSlide ()
{
NODE i;
@@ -517,29 +477,20 @@ Returns: (VOID)
}
}
-
-STATIC
-NODE
-Child (
- IN NODE q,
- IN UINT8 c
- )
-/*++
-
-Routine Description:
-
+/**
Find child node given the parent node and the edge character
-Arguments:
-
- q - the parent node
- c - the edge character
-
-Returns:
-
- The child node (NIL if not found)
-
---*/
+ @param q the parent node
+ @param c the edge character
+
+ @return The child node (NIL if not found)
+**/
+STATIC
+NODE
+Child (
+ IN NODE q,
+ IN UINT8 c
+ )
{
NODE r;
@@ -552,28 +503,20 @@ Routine Description:
return r;
}
-STATIC
-VOID
-MakeChild (
- IN NODE q,
- IN UINT8 c,
- IN NODE r
- )
-/*++
-
-Routine Description:
-
+/**
Create a new child for a given parent node.
-Arguments:
-
- q - the parent node
- c - the edge character
- r - the child node
-
-Returns: (VOID)
-
---*/
+ @param q the parent node
+ @param c the edge character
+ @param r the child node
+**/
+STATIC
+VOID
+MakeChild (
+ IN NODE q,
+ IN UINT8 c,
+ IN NODE r
+ )
{
NODE h, t;
@@ -587,24 +530,16 @@ Returns: (VOID)
mChildCount[q]++;
}
-STATIC
-VOID
-Split (
- NODE Old
- )
-/*++
-
-Routine Description:
-
+/**
Split a node.
-Arguments:
-
- Old - the node to split
-
-Returns: (VOID)
-
---*/
+ @param Old the node to split
+**/
+STATIC
+VOID
+Split (
+ NODE Old
+ )
{
NODE New, t;
@@ -624,20 +559,12 @@ Returns: (VOID)
MakeChild(New, mText[mPos + mMatchLen], mPos);
}
-STATIC
-VOID
-InsertNode ()
-/*++
-
-Routine Description:
-
+/**
Insert string info for current position into the String Info Log
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+InsertNode ()
{
NODE q, r, j, t;
UINT8 c, *t1, *t2;
@@ -739,21 +666,13 @@ Returns: (VOID)
}
-STATIC
-VOID
-DeleteNode ()
-/*++
-
-Routine Description:
-
+/**
Delete outdated string info. (The Usage of PERC_FLAG
ensures a clean deletion)
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+DeleteNode ()
{
NODE q, r, s, t, u;
@@ -813,21 +732,13 @@ Returns: (VOID)
mAvail = r;
}
-STATIC
-VOID
-GetNextMatch ()
-/*++
-
-Routine Description:
-
+/**
Advance the current position (read in new data if needed).
Delete outdated string info. Find a match string for current position.
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+GetNextMatch ()
{
INT32 n;
@@ -842,23 +753,15 @@ Returns: (VOID)
InsertNode();
}
-STATIC
-EFI_STATUS
-Encode ()
-/*++
-
-Routine Description:
-
+/**
The main controlling routine for compression process.
-Arguments: (VOID)
-
-Returns:
-
- EFI_SUCCESS - The compression is successful
- EFI_OUT_0F_RESOURCES - Not enough memory for compression process
-
---*/
+ @retval EFI_SUCCESS The compression is successful
+ @retval EFI_OUT_0F_RESOURCES Not enough memory for compression process
+**/
+STATIC
+EFI_STATUS
+Encode ()
{
EFI_STATUS Status;
INT32 LastMatchLen;
@@ -920,20 +823,12 @@ Arguments: (VOID)
return EFI_SUCCESS;
}
-STATIC
-VOID
-CountTFreq ()
-/*++
-
-Routine Description:
-
+/**
Count the frequencies for the Extra Set
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+CountTFreq ()
{
INT32 i, k, n, Count;
@@ -969,28 +864,20 @@ Returns: (VOID)
}
}
-STATIC
-VOID
-WritePTLen (
- IN INT32 n,
- IN INT32 nbit,
- IN INT32 Special
- )
-/*++
-
-Routine Description:
-
+/**
Outputs the code length array for the Extra Set or the Position Set.
-Arguments:
-
- n - the number of symbols
- nbit - the number of bits needed to represent 'n'
- Special - the special symbol that needs to be take care of
-
-Returns: (VOID)
-
---*/
+ @param n the number of symbols
+ @param nbit the number of bits needed to represent 'n'
+ @param Special the special symbol that needs to be take care of
+**/
+STATIC
+VOID
+WritePTLen (
+ IN INT32 n,
+ IN INT32 nbit,
+ IN INT32 Special
+ )
{
INT32 i, k;
@@ -1015,20 +902,12 @@ Returns: (VOID)
}
}
-STATIC
-VOID
-WriteCLen ()
-/*++
-
-Routine Description:
-
+/**
Outputs the code length array for Char&Length Set
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+WriteCLen ()
{
INT32 i, k, n, Count;
@@ -1096,20 +975,12 @@ EncodeP (
}
}
-STATIC
-VOID
-SendBlock ()
-/*++
-
-Routine Description:
-
+/**
Huffman code the block and output it.
-
-Argument: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+SendBlock ()
{
UINT32 i, k, Flags, Root, Pos, Size;
Flags = 0;
@@ -1164,27 +1035,18 @@ Returns: (VOID)
}
}
-
-STATIC
-VOID
-Output (
- IN UINT32 c,
- IN UINT32 p
- )
-/*++
-
-Routine Description:
-
+/**
Outputs an Original Character or a Pointer
-Arguments:
-
- c - The original character or the 'String Length' element of a Pointer
- p - The 'Position' field of a Pointer
-
-Returns: (VOID)
-
---*/
+ @param c The original character or the 'String Length' element of a Pointer
+ @param p The 'Position' field of a Pointer
+**/
+STATIC
+VOID
+Output (
+ IN UINT32 c,
+ IN UINT32 p
+ )
{
STATIC UINT32 CPos;
@@ -1263,26 +1125,18 @@ MakeCrcTable ()
}
}
-STATIC
-VOID
-PutBits (
- IN INT32 n,
- IN UINT32 x
- )
-/*++
-
-Routine Description:
-
+/**
Outputs rightmost n bits of x
-Arguments:
-
- n - the rightmost n bits of the data is used
- x - the data
-
-Returns: (VOID)
-
---*/
+ @param n the rightmost n bits of the data is used
+ @param x the data
+**/
+STATIC
+VOID
+PutBits (
+ IN INT32 n,
+ IN UINT32 x
+ )
{
UINT8 Temp;
@@ -1311,28 +1165,20 @@ Returns: (VOID)
}
}
-STATIC
-INT32
-FreadCrc (
- OUT UINT8 *p,
- IN INT32 n
- )
-/*++
-
-Routine Description:
-
+/**
Read in source data
-Arguments:
-
- p - the buffer to hold the data
- n - number of bytes to read
-
-Returns:
-
- number of bytes actually read
-
---*/
+ @param p the buffer to hold the data
+ @param n number of bytes to read
+
+ @return number of bytes actually read
+**/
+STATIC
+INT32
+FreadCrc (
+ OUT UINT8 *p,
+ IN INT32 n
+ )
{
INT32 i;
@@ -1358,24 +1204,16 @@ InitPutBits ()
mSubBitBuf = 0;
}
-STATIC
-VOID
-CountLen (
- IN INT32 i
- )
-/*++
-
-Routine Description:
-
+/**
Count the number of each code length for a Huffman tree.
-Arguments:
-
- i - the top node
-
-Returns: (VOID)
-
---*/
+ @param i the top node
+**/
+STATIC
+VOID
+CountLen (
+ IN INT32 i
+ )
{
STATIC INT32 Depth = 0;
@@ -1389,22 +1227,16 @@ Returns: (VOID)
}
}
-STATIC
-VOID
-MakeLen (
- IN INT32 Root
- )
-/*++
-
-Routine Description:
-
+/**
Create code length array for a Huffman tree
-Arguments:
-
- Root - the root of the tree
-
---*/
+ @param Root the root of the tree
+**/
+STATIC
+VOID
+MakeLen (
+ IN INT32 Root
+ )
{
INT32 i, k;
UINT32 Cum;
@@ -1468,28 +1300,20 @@ DownHeap (
mHeap[i] = (INT16)k;
}
-STATIC
-VOID
-MakeCode (
- IN INT32 n,
- IN UINT8 Len[],
- OUT UINT16 Code[]
- )
-/*++
-
-Routine Description:
-
+/**
Assign code to each symbol based on the code length array
-Arguments:
-
- n - number of symbols
- Len - the code length array
- Code - stores codes for each symbol
-
-Returns: (VOID)
-
---*/
+ @param n number of symbols
+ @param Len the code length array
+ @param Code stores codes for each symbol
+**/
+STATIC
+VOID
+MakeCode (
+ IN INT32 n,
+ IN UINT8 Len[],
+ OUT UINT16 Code[]
+ )
{
INT32 i;
UINT16 Start[18];
@@ -1503,32 +1327,24 @@ Returns: (VOID)
}
}
-STATIC
-INT32
-MakeTree (
- IN INT32 NParm,
- IN UINT16 FreqParm[],
- OUT UINT8 LenParm[],
- OUT UINT16 CodeParm[]
- )
-/*++
-
-Routine Description:
-
+/**
Generates Huffman codes given a frequency distribution of symbols
-Arguments:
-
- NParm - number of symbols
- FreqParm - frequency of each symbol
- LenParm - code length for each symbol
- CodeParm - code for each symbol
-
-Returns:
-
- Root of the Huffman tree.
-
---*/
+ @param NParm number of symbols
+ @param FreqParm frequency of each symbol
+ @param LenParm code length for each symbol
+ @param CodeParm code for each symbol
+
+ @return Root of the Huffman tree.
+**/
+STATIC
+INT32
+MakeTree (
+ IN INT32 NParm,
+ IN UINT16 FreqParm[],
+ OUT UINT8 LenParm[],
+ OUT UINT16 CodeParm[]
+ )
{
INT32 i, j, k, Avail;
diff --git a/BaseTools/Source/C/Common/EfiUtilityMsgs.c b/BaseTools/Source/C/Common/EfiUtilityMsgs.c
index f8d2a40be1e1..89524550884a 100644
--- a/BaseTools/Source/C/Common/EfiUtilityMsgs.c
+++ b/BaseTools/Source/C/Common/EfiUtilityMsgs.c
@@ -36,65 +36,59 @@ PrintLimitExceeded (
VOID
);
-VOID
-Error (
- CHAR8 *FileName,
- UINT32 LineNumber,
- UINT32 MessageCode,
- CHAR8 *Text,
- CHAR8 *MsgFmt,
- ...
- )
-/*++
-
-Routine Description:
+/**
Prints an error message.
-Arguments:
All arguments are optional, though the printed message may be useless if
at least something valid is not specified.
+
+ @note:
+ We print the following (similar to the Warn() and Debug()
+ W
+ Typical error/warning message format:
- FileName - name of the file or application. If not specified, then the
+ bin\VfrCompile.cpp(330) : error C2660: 'AddVfrDataStructField' : function does not take 2 parameters
+
+ BUGBUG -- these three utility functions are almost identical, and
+ should be modified to share code.
+
+ Visual Studio does not find error messages with:
+
+ " error :"
+ " error 1:"
+ " error c1:"
+ " error 1000:"
+ " error c100:"
+
+ It does find:
+ " error c1000:"
+
+ @param FileName name of the file or application. If not specified, then the
utility name (as set by the utility calling SetUtilityName()
earlier) is used. Otherwise "Unknown utility" is used.
- LineNumber - the line number of error, typically used by parsers. If the
+ @param LineNumber the line number of error, typically used by parsers. If the
utility is not a parser, then 0 should be specified. Otherwise
the FileName and LineNumber info can be used to cause
MS Visual Studio to jump to the error.
- MessageCode - an application-specific error code that can be referenced in
+ @param MessageCode an application-specific error code that can be referenced in
other documentation.
- Text - the text in question, typically used by parsers.
+ @param Text the text in question, typically used by parsers.
- MsgFmt - the format string for the error message. Can contain formatting
+ @param MsgFmt the format string for the error message. Can contain formatting
controls for use with the varargs.
-
-Returns:
- None.
-
-Notes:
- We print the following (similar to the Warn() and Debug()
- W
- Typical error/warning message format:
-
- bin\VfrCompile.cpp(330) : error C2660: 'AddVfrDataStructField' : function does not take 2 parameters
-
- BUGBUG -- these three utility functions are almost identical, and
- should be modified to share code.
-
- Visual Studio does not find error messages with:
-
- " error :"
- " error 1:"
- " error c1:"
- " error 1000:"
- " error c100:"
-
- It does find:
- " error c1000:"
---*/
+**/
+VOID
+Error (
+ CHAR8 *FileName,
+ UINT32 LineNumber,
+ UINT32 MessageCode,
+ CHAR8 *Text,
+ CHAR8 *MsgFmt,
+ ...
+ )
{
va_list List;
//
@@ -127,28 +121,21 @@ Routine Description:
va_end (List);
}
-VOID
-ParserError (
- UINT32 MessageCode,
- CHAR8 *Text,
- CHAR8 *MsgFmt,
- ...
- )
-/*++
-
-Routine Description:
+/**
Print a parser error, using the source file name and line number
set by a previous call to SetParserPosition().
-Arguments:
- MessageCode - application-specific error code
- Text - text to print in the error message
- MsgFmt - format string to print at the end of the error message
-
-Returns:
- NA
-
---*/
+ @param MessageCode application-specific error code
+ @param Text text to print in the error message
+ @param MsgFmt format string to print at the end of the error message
+**/
+VOID
+ParserError (
+ UINT32 MessageCode,
+ CHAR8 *Text,
+ CHAR8 *MsgFmt,
+ ...
+ )
{
va_list List;
//
@@ -181,6 +168,14 @@ Routine Description:
va_end (List);
}
+/**
+ Print a parser warning, using the source file name and line number
+ set by a previous call to SetParserPosition().
+
+ @param ErrorCode application-specific error code
+ @param OffendingText text to print in the warning message
+ @param MsgFmt format string to print at the end of the warning message
+**/
VOID
ParserWarning (
UINT32 ErrorCode,
@@ -188,21 +183,6 @@ ParserWarning (
CHAR8 *MsgFmt,
...
)
-/*++
-
-Routine Description:
- Print a parser warning, using the source file name and line number
- set by a previous call to SetParserPosition().
-
-Arguments:
- ErrorCode - application-specific error code
- OffendingText - text to print in the warning message
- MsgFmt - format string to print at the end of the warning message
-
-Returns:
- NA
-
---*/
{
va_list List;
//
@@ -241,39 +221,28 @@ Routine Description:
// }
}
-VOID
-Warning (
- CHAR8 *FileName,
- UINT32 LineNumber,
- UINT32 MessageCode,
- CHAR8 *Text,
- CHAR8 *MsgFmt,
- ...
- )
-/*++
-
-Routine Description:
+/**
Print a warning message.
-Arguments:
- FileName - name of the file where the warning was detected, or the name
- of the application that detected the warning
-
- LineNumber - the line number where the warning was detected (parsers).
- 0 should be specified if the utility is not a parser.
-
- MessageCode - an application-specific warning code that can be referenced in
- other documentation.
-
- Text - the text in question (parsers)
-
- MsgFmt - the format string for the warning message. Can contain formatting
- controls for use with varargs.
-
-Returns:
- None.
-
---*/
+ @param FileName name of the file where the warning was detected, or the name
+ of the application that detected the warning
+ @param LineNumber the line number where the warning was detected (parsers).
+ 0 should be specified if the utility is not a parser.
+ @param MessageCode an application-specific warning code that can be referenced in
+ other documentation.
+ @param Text the text in question (parsers)
+ @param MsgFmt the format string for the warning message. Can contain formatting
+ controls for use with varargs.
+**/
+VOID
+Warning (
+ CHAR8 *FileName,
+ UINT32 LineNumber,
+ UINT32 MessageCode,
+ CHAR8 *Text,
+ CHAR8 *MsgFmt,
+ ...
+ )
{
va_list List;
@@ -313,6 +282,18 @@ Routine Description:
va_end (List);
}
+/**
+ Print a Debug message.
+
+ @param FileName typically the name of the utility printing the debug message, but
+ can be the name of a file being parsed.
+ @param LineNumber the line number in FileName (parsers)
+ @param MsgLevel Debug message print level (0~9)
+ @param Text the text in question (parsers)
+ @param MsgFmt the format string for the debug message. Can contain formatting
+ controls for use with varargs.
+
+**/
VOID
DebugMsg (
CHAR8 *FileName,
@@ -322,28 +303,6 @@ DebugMsg (
CHAR8 *MsgFmt,
...
)
-/*++
-
-Routine Description:
- Print a Debug message.
-
-Arguments:
- FileName - typically the name of the utility printing the debug message, but
- can be the name of a file being parsed.
-
- LineNumber - the line number in FileName (parsers)
-
- MsgLevel - Debug message print level (0~9)
-
- Text - the text in question (parsers)
-
- MsgFmt - the format string for the debug message. Can contain formatting
- controls for use with varargs.
-
-Returns:
- None.
-
---*/
{
va_list List;
//
@@ -358,64 +317,52 @@ Routine Description:
va_end (List);
}
-VOID
-PrintMessage (
- CHAR8 *Type,
- CHAR8 *FileName,
- UINT32 LineNumber,
- UINT32 MessageCode,
- CHAR8 *Text,
- CHAR8 *MsgFmt,
- va_list List
- )
-/*++
-
-Routine Description:
+/**
Worker routine for all the utility printing services. Prints the message in
a format that Visual Studio will find when scanning build outputs for
errors or warnings.
+
+ @note:
+ If FileName == NULL then this utility will use the string passed into SetUtilityName().
-Arguments:
- Type - "warning" or "error" string to insert into the message to be
+ LineNumber is only used if the caller is a parser, in which case FileName refers to the
+ file being parsed.
+
+ Text and MsgFmt are both optional, though it would be of little use calling this function with
+ them both NULL.
+
+ Output will typically be of the form:
+ <FileName>(<LineNumber>) : <Type> <Type[0]><MessageCode>: <Text> : <MsgFmt>
+
+ Parser (LineNumber != 0)
+ VfrCompile.cpp(330) : error E2660: AddVfrDataStructField : function does not take 2 parameters
+ Generic utility (LineNumber == 0)
+ UtilityName : error E1234 : Text string : MsgFmt string and args
+
+ @param Type "warning" or "error" string to insert into the message to be
printed. The first character of this string (converted to uppercase)
is used to precede the MessageCode value in the output string.
-
- FileName - name of the file where the warning was detected, or the name
+ @param FileName name of the file where the warning was detected, or the name
of the application that detected the warning
-
- LineNumber - the line number where the warning was detected (parsers).
+ @param LineNumber the line number where the warning was detected (parsers).
0 should be specified if the utility is not a parser.
-
- MessageCode - an application-specific warning code that can be referenced in
+ @param MessageCode an application-specific warning code that can be referenced in
other documentation.
-
- Text - part of the message to print
-
- MsgFmt - the format string for the message. Can contain formatting
+ @param Text part of the message to print
+ @param MsgFmt the format string for the message. Can contain formatting
controls for use with varargs.
- List - the variable list.
-
-Returns:
- None.
-
-Notes:
- If FileName == NULL then this utility will use the string passed into SetUtilityName().
-
- LineNumber is only used if the caller is a parser, in which case FileName refers to the
- file being parsed.
-
- Text and MsgFmt are both optional, though it would be of little use calling this function with
- them both NULL.
-
- Output will typically be of the form:
- <FileName>(<LineNumber>) : <Type> <Type[0]><MessageCode>: <Text> : <MsgFmt>
-
- Parser (LineNumber != 0)
- VfrCompile.cpp(330) : error E2660: AddVfrDataStructField : function does not take 2 parameters
- Generic utility (LineNumber == 0)
- UtilityName : error E1234 : Text string : MsgFmt string and args
-
---*/
+ @param List the variable list.
+**/
+VOID
+PrintMessage (
+ CHAR8 *Type,
+ CHAR8 *FileName,
+ UINT32 LineNumber,
+ UINT32 MessageCode,
+ CHAR8 *Text,
+ CHAR8 *MsgFmt,
+ va_list List
+ )
{
CHAR8 Line[MAX_LINE_LEN];
CHAR8 Line2[MAX_LINE_LEN];
@@ -523,24 +470,19 @@ Routine Description:
}
-STATIC
-VOID
-PrintSimpleMessage (
- CHAR8 *MsgFmt,
- va_list List
- )
-/*++
-Routine Description:
+/**
Print message into stdout.
-Arguments:
- MsgFmt - the format string for the message. Can contain formatting
- controls for use with varargs.
- List - the variable list.
-
-Returns:
- None.
---*/
+ @param MsgFmt the format string for the message. Can contain formatting
+ controls for use with varargs.
+ @param List the variable list.
+**/
+STATIC
+VOID
+PrintSimpleMessage (
+ CHAR8 *MsgFmt,
+ va_list List
+ )
{
CHAR8 Line[MAX_LINE_LEN];
//
@@ -552,51 +494,37 @@ Routine Description:
}
}
+/**
+ Set the position in a file being parsed. This can be used to
+ print error messages deeper down in a parser.
+
+ @param SourceFileName name of the source file being parsed
+ @param LineNum line number of the source file being parsed
+**/
VOID
ParserSetPosition (
CHAR8 *SourceFileName,
UINT32 LineNum
)
-/*++
-
-Routine Description:
- Set the position in a file being parsed. This can be used to
- print error messages deeper down in a parser.
-
-Arguments:
- SourceFileName - name of the source file being parsed
- LineNum - line number of the source file being parsed
-
-Returns:
- NA
-
---*/
{
mSourceFileName = SourceFileName;
mSourceFileLineNum = LineNum;
}
-VOID
-SetUtilityName (
- CHAR8 *UtilityName
- )
-/*++
-
-Routine Description:
+/**
All printed error/warning/debug messages follow the same format, and
typically will print a filename or utility name followed by the error
text. However if a filename is not passed to the print routines, then
they'll print the utility name if you call this function early in your
app to set the utility name.
-Arguments:
- UtilityName - name of the utility, which will be printed with all
- error/warning/debug messages.
-
-Returns:
- NA
-
---*/
+ @param UtilityName name of the utility, which will be printed with all
+ error/warning/debug messages.
+**/
+VOID
+SetUtilityName (
+ CHAR8 *UtilityName
+ )
{
//
// Save the name of the utility in our local variable. Make sure its
@@ -613,69 +541,48 @@ Routine Description:
}
}
-STATUS
-GetUtilityStatus (
- VOID
- )
-/*++
-
-Routine Description:
+/**
When you call Error() or Warning(), this module keeps track of it and
sets a local mStatus to STATUS_ERROR or STATUS_WARNING. When the utility
exits, it can call this function to get the status and use it as a return
value.
-Arguments:
- None.
-
-Returns:
- Worst-case status reported, as defined by which print function was called.
-
---*/
+ @return Worst-case status reported, as defined by which print function was called.
+**/
+STATUS
+GetUtilityStatus (
+ VOID
+ )
{
return mStatus;
}
-VOID
-SetPrintLevel (
- UINT64 LogLevel
- )
-/*++
-
-Routine Description:
+/**
Set the printing message Level. This is used by the PrintMsg() function
to determine when/if a message should be printed.
-Arguments:
- LogLevel - 0~50 to specify the different level message.
-
-Returns:
- NA
-
---*/
+ @param LogLevel 0~50 to specify the different level message.
+**/
+VOID
+SetPrintLevel (
+ UINT64 LogLevel
+ )
{
mPrintLogLevel = LogLevel;
}
-VOID
-VerboseMsg (
- CHAR8 *MsgFmt,
- ...
- )
-/*++
-
-Routine Description:
+/**
Print a verbose level message.
-Arguments:
- MsgFmt - the format string for the message. Can contain formatting
- controls for use with varargs.
- List - the variable list.
-
-Returns:
- NA
-
---*/
+ @param MsgFmt the format string for the message. Can contain formatting
+ controls for use with varargs.
+ @param List the variable list.
+**/
+VOID
+VerboseMsg (
+ CHAR8 *MsgFmt,
+ ...
+ )
{
va_list List;
//
@@ -690,25 +597,18 @@ Routine Description:
va_end (List);
}
-VOID
-NormalMsg (
- CHAR8 *MsgFmt,
- ...
- )
-/*++
-
-Routine Description:
+/**
Print a default level message.
-Arguments:
- MsgFmt - the format string for the message. Can contain formatting
- controls for use with varargs.
- List - the variable list.
-
-Returns:
- NA
-
---*/
+ @param MsgFmt the format string for the message. Can contain formatting
+ controls for use with varargs.
+ @param List the variable list.
+**/
+VOID
+NormalMsg (
+ CHAR8 *MsgFmt,
+ ...
+ )
{
va_list List;
//
@@ -723,25 +623,18 @@ Routine Description:
va_end (List);
}
-VOID
-KeyMsg (
- CHAR8 *MsgFmt,
- ...
- )
-/*++
-
-Routine Description:
+/**
Print a key level message.
-Arguments:
- MsgFmt - the format string for the message. Can contain formatting
- controls for use with varargs.
- List - the variable list.
-
-Returns:
- NA
-
---*/
+ @param MsgFmt the format string for the message. Can contain formatting
+ controls for use with varargs.
+ @param List the variable list.
+**/
+VOID
+KeyMsg (
+ CHAR8 *MsgFmt,
+ ...
+ )
{
va_list List;
//
@@ -756,28 +649,21 @@ Routine Description:
va_end (List);
}
+/**
+ Set the limits of how many errors, warnings, and errors+warnings
+ we will print.
+
+ @param MaxErrors maximum number of error messages to print
+ @param MaxWarnings maximum number of warning messages to print
+ @param MaxWarningsPlusErrors
+ maximum number of errors+warnings to print
+**/
VOID
SetPrintLimits (
UINT32 MaxErrors,
UINT32 MaxWarnings,
UINT32 MaxWarningsPlusErrors
)
-/*++
-
-Routine Description:
- Set the limits of how many errors, warnings, and errors+warnings
- we will print.
-
-Arguments:
- MaxErrors - maximum number of error messages to print
- MaxWarnings - maximum number of warning messages to print
- MaxWarningsPlusErrors
- - maximum number of errors+warnings to print
-
-Returns:
- NA
-
---*/
{
mMaxErrors = MaxErrors;
mMaxWarnings = MaxWarnings;
diff --git a/BaseTools/Source/C/Common/FirmwareVolumeBuffer.c b/BaseTools/Source/C/Common/FirmwareVolumeBuffer.c
index ace26eb71c6b..3fae6f901da0 100644
--- a/BaseTools/Source/C/Common/FirmwareVolumeBuffer.c
+++ b/BaseTools/Source/C/Common/FirmwareVolumeBuffer.c
@@ -78,29 +78,21 @@ FvBufCalculateChecksum8 (
// Procedures start
//
+/**
+ Clears out all files from the Fv buffer in memory
+
+ @param SourceFv Address of the Fv in memory, this firmware volume will
+ be modified, if SourceFfsFile exists
+ @param SourceFfsFile Input FFS file to replace
+
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+**/
EFI_STATUS
FvBufRemoveFileNew (
IN OUT VOID *Fv,
IN EFI_GUID *Name
)
-/*++
-
-Routine Description:
-
- Clears out all files from the Fv buffer in memory
-
-Arguments:
-
- SourceFv - Address of the Fv in memory, this firmware volume will
- be modified, if SourceFfsFile exists
- SourceFfsFile - Input FFS file to replace
-
-Returns:
-
- EFI_SUCCESS
- EFI_NOT_FOUND
-
---*/
{
EFI_STATUS Status;
EFI_FFS_FILE_HEADER* FileToRm;
@@ -127,30 +119,21 @@ Routine Description:
return EFI_SUCCESS;
}
+/**
+ Clears out all files from the Fv buffer in memory
+ @param SourceFv Address of the Fv in memory, this firmware volume will
+ be modified, if SourceFfsFile exists
+ @param SourceFfsFile Input FFS file to replace
+
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+**/
EFI_STATUS
FvBufRemoveFile (
IN OUT VOID *Fv,
IN EFI_GUID *Name
)
-/*++
-
-Routine Description:
-
- Clears out all files from the Fv buffer in memory
-
-Arguments:
-
- SourceFv - Address of the Fv in memory, this firmware volume will
- be modified, if SourceFfsFile exists
- SourceFfsFile - Input FFS file to replace
-
-Returns:
-
- EFI_SUCCESS
- EFI_NOT_FOUND
-
---*/
{
EFI_STATUS Status;
EFI_FFS_FILE_HEADER *NextFile;
@@ -216,27 +199,18 @@ Routine Description:
return EFI_SUCCESS;
}
+/**
+ Clears out all files from the Fv buffer in memory
+ @param SourceFfsFile Input FFS file to update the checksum for
+
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+**/
EFI_STATUS
FvBufChecksumFile (
IN OUT VOID *FfsFile
)
-/*++
-
-Routine Description:
-
- Clears out all files from the Fv buffer in memory
-
-Arguments:
-
- SourceFfsFile - Input FFS file to update the checksum for
-
-Returns:
-
- EFI_SUCCESS
- EFI_NOT_FOUND
-
---*/
{
EFI_FFS_FILE_HEADER* File = (EFI_FFS_FILE_HEADER*)FfsFile;
EFI_FFS_FILE_STATE StateBackup;
@@ -272,29 +246,20 @@ Routine Description:
return EFI_SUCCESS;
}
+/**
+ Clears out all files from the Fv buffer in memory
+ @param SourceFv Address of the Fv in memory, this firmware volume will
+ be modified, if SourceFfsFile exists
+ @param SourceFfsFile Input FFS file to replace
+
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+**/
EFI_STATUS
FvBufChecksumHeader (
IN OUT VOID *Fv
)
-/*++
-
-Routine Description:
-
- Clears out all files from the Fv buffer in memory
-
-Arguments:
-
- SourceFv - Address of the Fv in memory, this firmware volume will
- be modified, if SourceFfsFile exists
- SourceFfsFile - Input FFS file to replace
-
-Returns:
-
- EFI_SUCCESS
- EFI_NOT_FOUND
-
---*/
{
EFI_FIRMWARE_VOLUME_HEADER* FvHeader = (EFI_FIRMWARE_VOLUME_HEADER*)Fv;
@@ -308,31 +273,22 @@ Routine Description:
return EFI_SUCCESS;
}
-
-EFI_STATUS
-FvBufDuplicate (
- IN VOID *SourceFv,
- IN OUT VOID **DestinationFv
- )
-/*++
-
-Routine Description:
-
+/**
Clears out all files from the Fv buffer in memory
-Arguments:
-
- SourceFv - Address of the Fv in memory
- DestinationFv - Output for destination Fv
+ @param SourceFv - Address of the Fv in memory
+ @param DestinationFv - Output for destination Fv
DestinationFv == NULL - invalid parameter
*DestinationFv == NULL - memory will be allocated
*DestinationFv != NULL - this address will be the destination
-Returns:
-
- EFI_SUCCESS
-
---*/
+ @retval EFI_SUCCESS
+**/
+EFI_STATUS
+FvBufDuplicate (
+ IN VOID *SourceFv,
+ IN OUT VOID **DestinationFv
+ )
{
EFI_STATUS Status;
UINTN size;
@@ -358,35 +314,26 @@ Routine Description:
return EFI_SUCCESS;
}
+/**
+ Extends a firmware volume by the given number of bytes.
+ BUGBUG: Does not handle the case where the firmware volume has a
+ VTF (Volume Top File). The VTF will not be moved to the
+ end of the extended FV.
+
+ @param Fv Source and destination firmware volume.
+ Note: The original firmware volume buffer is freed!
+
+ @param Size The minimum size that the firmware volume is to be extended by.
+ The FV may be extended more than this size.
+
+ @retval EFI_SUCCESS
+**/
EFI_STATUS
FvBufExtend (
IN VOID **Fv,
IN UINTN Size
)
-/*++
-
-Routine Description:
-
- Extends a firmware volume by the given number of bytes.
-
- BUGBUG: Does not handle the case where the firmware volume has a
- VTF (Volume Top File). The VTF will not be moved to the
- end of the extended FV.
-
-Arguments:
-
- Fv - Source and destination firmware volume.
- Note: The original firmware volume buffer is freed!
-
- Size - The minimum size that the firmware volume is to be extended by.
- The FV may be extended more than this size.
-
-Returns:
-
- EFI_SUCCESS
-
---*/
{
EFI_STATUS Status;
UINTN OldSize;
@@ -469,27 +416,17 @@ Routine Description:
}
+/**
+ Clears out all files from the Fv buffer in memory
+ @param Fv Address of the Fv in memory
+
+ @retval EFI_SUCCESS
+**/
EFI_STATUS
FvBufClearAllFiles (
IN OUT VOID *Fv
)
-/*++
-
-Routine Description:
-
- Clears out all files from the Fv buffer in memory
-
-Arguments:
-
- Fv - Address of the Fv in memory
-
-Returns:
-
- EFI_SUCCESS
-
---*/
-
{
EFI_FIRMWARE_VOLUME_HEADER *hdr = (EFI_FIRMWARE_VOLUME_HEADER*)Fv;
EFI_STATUS Status;
@@ -509,28 +446,18 @@ Routine Description:
return EFI_SUCCESS;
}
+/**
+ Clears out all files from the Fv buffer in memory
+ @param Fv Address of the Fv in memory
+
+ @retval EFI_SUCCESS
+**/
EFI_STATUS
FvBufGetSize (
IN VOID *Fv,
OUT UINTN *Size
)
-/*++
-
-Routine Description:
-
- Clears out all files from the Fv buffer in memory
-
-Arguments:
-
- Fv - Address of the Fv in memory
-
-Returns:
-
- EFI_SUCCESS
-
---*/
-
{
EFI_FIRMWARE_VOLUME_HEADER *hdr = (EFI_FIRMWARE_VOLUME_HEADER*)Fv;
EFI_FV_BLOCK_MAP_ENTRY *blk = hdr->BlockMap;
@@ -554,28 +481,19 @@ Routine Description:
return EFI_SUCCESS;
}
-
-EFI_STATUS
-FvBufAddFile (
- IN OUT VOID *Fv,
- IN VOID *File
- )
-/*++
-
-Routine Description:
-
+/**
Adds a new FFS file
-Arguments:
-
- Fv - Address of the Fv in memory
- File - FFS file to add to Fv
-
-Returns:
-
- EFI_SUCCESS
-
---*/
+ @param Fv Address of the Fv in memory
+ @param File FFS file to add to Fv
+
+ @retval EFI_SUCCESS
+**/
+EFI_STATUS
+FvBufAddFile (
+ IN OUT VOID *Fv,
+ IN VOID *File
+ )
{
EFI_FIRMWARE_VOLUME_HEADER *hdr = (EFI_FIRMWARE_VOLUME_HEADER*)Fv;
@@ -652,32 +570,23 @@ Routine Description:
return EFI_SUCCESS;
}
-
-EFI_STATUS
-FvBufAddFileWithExtend (
- IN OUT VOID **Fv,
- IN VOID *File
- )
-/*++
-
-Routine Description:
-
+/**
Adds a new FFS file. Extends the firmware volume if needed.
-Arguments:
-
- Fv - Source and destination firmware volume.
- Note: If the FV is extended, then the original firmware volume
+ @param Fv Source and destination firmware volume.
+ Note: If the FV is extended, then the original firmware volume
buffer is freed!
- Size - The minimum size that the firmware volume is to be extended by.
- The FV may be extended more than this size.
+ @param Size The minimum size that the firmware volume is to be extended by.
+ The FV may be extended more than this size.
-Returns:
-
- EFI_SUCCESS
-
---*/
+ @retval EFI_SUCCESS
+**/
+EFI_STATUS
+FvBufAddFileWithExtend (
+ IN OUT VOID **Fv,
+ IN VOID *File
+ )
{
EFI_STATUS Status;
EFI_FFS_FILE_HEADER* NewFile;
@@ -706,29 +615,20 @@ Routine Description:
return Status;
}
-
-EFI_STATUS
-FvBufAddVtfFile (
- IN OUT VOID *Fv,
- IN VOID *File
- )
-/*++
-
-Routine Description:
-
+/**
Adds a new FFS VFT (Volume Top File) file. In other words, adds the
file to the end of the firmware volume.
-Arguments:
-
- Fv - Address of the Fv in memory
- File - FFS file to add to Fv
-
-Returns:
-
- EFI_SUCCESS
-
---*/
+ @param Fv Address of the Fv in memory
+ @param File FFS file to add to Fv
+
+ @retval EFI_SUCCESS
+**/
+EFI_STATUS
+FvBufAddVtfFile (
+ IN OUT VOID *Fv,
+ IN VOID *File
+ )
{
EFI_STATUS Status;
@@ -811,52 +711,35 @@ Routine Description:
return EFI_SUCCESS;
}
+/**
+ Expands the 3 byte size commonly used in Firmware Volume data structures
+ @param Size Address of the 3 byte array representing the size
+
+ @return UINT32
+**/
VOID
FvBufCompact3ByteSize (
OUT VOID* SizeDest,
IN UINT32 Size
)
-/*++
-
-Routine Description:
-
- Expands the 3 byte size commonly used in Firmware Volume data structures
-
-Arguments:
-
- Size - Address of the 3 byte array representing the size
-
-Returns:
-
- UINT32
-
---*/
{
((UINT8*)SizeDest)[0] = (UINT8)Size;
((UINT8*)SizeDest)[1] = (UINT8)(Size >> 8);
((UINT8*)SizeDest)[2] = (UINT8)(Size >> 16);
}
-UINT32
-FvBufGetFfsFileSize (
- IN EFI_FFS_FILE_HEADER *Ffs
- )
-/*++
-
-Routine Description:
-
+/**
Get the FFS file size.
-Arguments:
-
- Ffs - Pointer to FFS header
-
-Returns:
-
- UINT32
-
---*/
+ @param Ffs Pointer to FFS header
+
+ @return UINT32
+**/
+UINT32
+FvBufGetFfsFileSize (
+ IN EFI_FFS_FILE_HEADER *Ffs
+ )
{
if (Ffs == NULL) {
return 0;
@@ -867,25 +750,17 @@ Routine Description:
return FvBufExpand3ByteSize(Ffs->Size);
}
-UINT32
-FvBufGetFfsHeaderSize (
- IN EFI_FFS_FILE_HEADER *Ffs
- )
-/*++
-
-Routine Description:
-
+/**
Get the FFS header size.
-Arguments:
-
- Ffs - Pointer to FFS header
-
-Returns:
-
- UINT32
-
---*/
+ @param Ffs Pointer to FFS header
+
+ @return UINT32
+**/
+UINT32
+FvBufGetFfsHeaderSize (
+ IN EFI_FFS_FILE_HEADER *Ffs
+ )
{
if (Ffs == NULL) {
return 0;
@@ -896,60 +771,44 @@ Routine Description:
return sizeof(EFI_FFS_FILE_HEADER);
}
+/**
+ Expands the 3 byte size commonly used in Firmware Volume data structures
+
+ @param Size Address of the 3 byte array representing the size
+
+ @return UINT32
+**/
UINT32
FvBufExpand3ByteSize (
IN VOID* Size
)
-/*++
-
-Routine Description:
-
- Expands the 3 byte size commonly used in Firmware Volume data structures
-
-Arguments:
-
- Size - Address of the 3 byte array representing the size
-
-Returns:
-
- UINT32
-
---*/
{
return (((UINT8*)Size)[2] << 16) +
(((UINT8*)Size)[1] << 8) +
((UINT8*)Size)[0];
}
-EFI_STATUS
-FvBufFindNextFile (
- IN VOID *Fv,
- IN OUT UINTN *Key,
- OUT VOID **File
- )
-/*++
-
-Routine Description:
-
+/**
Iterates through the files contained within the firmware volume
-Arguments:
-
- Fv - Address of the Fv in memory
- Key - Should be 0 to get the first file. After that, it should be
- passed back in without modifying its contents to retrieve
- subsequent files.
- File - Output file pointer
+ @param Fv Address of the Fv in memory
+ @param Key Should be 0 to get the first file. After that, it should be
+ passed back in without modifying its contents to retrieve
+ subsequent files.
+ @param File Output file pointer
File == NULL - invalid parameter
otherwise - *File will be update to the location of the file
-Returns:
-
- EFI_SUCCESS
- EFI_NOT_FOUND
- EFI_VOLUME_CORRUPTED
-
---*/
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+ @retval EFI_VOLUME_CORRUPTED
+**/
+EFI_STATUS
+FvBufFindNextFile (
+ IN VOID *Fv,
+ IN OUT UINTN *Key,
+ OUT VOID **File
+ )
{
EFI_FIRMWARE_VOLUME_HEADER *hdr = (EFI_FIRMWARE_VOLUME_HEADER*)Fv;
@@ -1028,35 +887,26 @@ Routine Description:
return EFI_NOT_FOUND;
}
-
-EFI_STATUS
-FvBufFindFileByName (
- IN VOID *Fv,
- IN EFI_GUID *Name,
- OUT VOID **File
- )
-/*++
-
-Routine Description:
-
+/**
Searches the Fv for a file by its name
-Arguments:
-
- Fv - Address of the Fv in memory
- Name - Guid filename to search for in the firmware volume
- File - Output file pointer
+ @param Fv Address of the Fv in memory
+ @param Name Guid filename to search for in the firmware volume
+ @param File Output file pointer
File == NULL - Only determine if the file exists, based on return
value from the function call.
otherwise - *File will be update to the location of the file
-Returns:
-
- EFI_SUCCESS
- EFI_NOT_FOUND
- EFI_VOLUME_CORRUPTED
-
---*/
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+ @retval EFI_VOLUME_CORRUPTED
+**/
+EFI_STATUS
+FvBufFindFileByName (
+ IN VOID *Fv,
+ IN EFI_GUID *Name,
+ OUT VOID **File
+ )
{
EFI_STATUS Status;
UINTN Key;
@@ -1080,35 +930,26 @@ Routine Description:
return EFI_NOT_FOUND;
}
-
-EFI_STATUS
-FvBufFindFileByType (
- IN VOID *Fv,
- IN EFI_FV_FILETYPE Type,
- OUT VOID **File
- )
-/*++
-
-Routine Description:
-
+/**
Searches the Fv for a file by its type
-Arguments:
-
- Fv - Address of the Fv in memory
- Type - FFS FILE type to search for
- File - Output file pointer
+ @param Fv Address of the Fv in memory
+ @param Type FFS FILE type to search for
+ @param File Output file pointer
(File == NULL) -> Only determine if the file exists, based on return
value from the function call.
otherwise -> *File will be update to the location of the file
-Returns:
-
- EFI_SUCCESS
- EFI_NOT_FOUND
- EFI_VOLUME_CORRUPTED
-
---*/
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+ @retval EFI_VOLUME_CORRUPTED
+**/
+EFI_STATUS
+FvBufFindFileByType (
+ IN VOID *Fv,
+ IN EFI_FV_FILETYPE Type,
+ OUT VOID **File
+ )
{
EFI_STATUS Status;
UINTN Key;
@@ -1132,34 +973,25 @@ Routine Description:
return EFI_NOT_FOUND;
}
+/**
+ Searches the requested file for raw data.
+ This routine either returns all the payload of a EFI_FV_FILETYPE_RAW file,
+ or finds the EFI_SECTION_RAW section within the file and returns its data.
+
+ @param FfsFile Address of the FFS file in memory
+ @param RawData Pointer to the raw data within the file
+ (This is NOT allocated. It is within the file.)
+ @param RawDataSize Size of the raw data within the file
+
+ @return EFI_STATUS
+**/
EFI_STATUS
FvBufGetFileRawData (
IN VOID* FfsFile,
OUT VOID** RawData,
OUT UINTN* RawDataSize
)
-/*++
-
-Routine Description:
-
- Searches the requested file for raw data.
-
- This routine either returns all the payload of a EFI_FV_FILETYPE_RAW file,
- or finds the EFI_SECTION_RAW section within the file and returns its data.
-
-Arguments:
-
- FfsFile - Address of the FFS file in memory
- RawData - Pointer to the raw data within the file
- (This is NOT allocated. It is within the file.)
- RawDataSize - Size of the raw data within the file
-
-Returns:
-
- EFI_STATUS
-
---*/
{
EFI_STATUS Status;
EFI_FFS_FILE_HEADER* File;
@@ -1195,7 +1027,19 @@ Routine Description:
}
+/**
+ Packages up a FFS file containing the input raw data.
+ The file created will have a type of EFI_FV_FILETYPE_FREEFORM, and will
+ contain one EFI_FV_FILETYPE_RAW section.
+
+ @param RawData Pointer to the raw data to be packed
+ @param RawDataSize Size of the raw data to be packed
+ @param FfsFile Address of the packaged FFS file.
+ Note: The called must deallocate this memory!
+
+ @return EFI_STATUS
+**/
EFI_STATUS
FvBufPackageFreeformRawFile (
IN EFI_GUID* Filename,
@@ -1203,27 +1047,6 @@ FvBufPackageFreeformRawFile (
IN UINTN RawDataSize,
OUT VOID** FfsFile
)
-/*++
-
-Routine Description:
-
- Packages up a FFS file containing the input raw data.
-
- The file created will have a type of EFI_FV_FILETYPE_FREEFORM, and will
- contain one EFI_FV_FILETYPE_RAW section.
-
-Arguments:
-
- RawData - Pointer to the raw data to be packed
- RawDataSize - Size of the raw data to be packed
- FfsFile - Address of the packaged FFS file.
- Note: The called must deallocate this memory!
-
-Returns:
-
- EFI_STATUS
-
---*/
{
EFI_FFS_FILE_HEADER* NewFile;
UINT32 NewFileSize;
@@ -1304,7 +1127,22 @@ Routine Description:
return EFI_SUCCESS;
}
+/**
+ Iterates through the sections contained within a given array of sections
+ @param SectionsStart Address of the start of the FFS sections array
+ @param TotalSectionsSize Total size of all the sections
+ @param Key Should be 0 to get the first section. After that, it should be
+ passed back in without modifying its contents to retrieve
+ subsequent files.
+ @param Section Output section pointer
+ (Section == NULL) -> invalid parameter
+ otherwise -> *Section will be update to the location of the file
+
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+ @retval EFI_VOLUME_CORRUPTED
+**/
EFI_STATUS
FvBufFindNextSection (
IN VOID *SectionsStart,
@@ -1312,30 +1150,6 @@ FvBufFindNextSection (
IN OUT UINTN *Key,
OUT VOID **Section
)
-/*++
-
-Routine Description:
-
- Iterates through the sections contained within a given array of sections
-
-Arguments:
-
- SectionsStart - Address of the start of the FFS sections array
- TotalSectionsSize - Total size of all the sections
- Key - Should be 0 to get the first section. After that, it should be
- passed back in without modifying its contents to retrieve
- subsequent files.
- Section - Output section pointer
- (Section == NULL) -> invalid parameter
- otherwise -> *Section will be update to the location of the file
-
-Returns:
-
- EFI_SUCCESS
- EFI_NOT_FOUND
- EFI_VOLUME_CORRUPTED
-
---*/
{
EFI_COMMON_SECTION_HEADER *sectionHdr;
UINTN sectionSize;
@@ -1363,31 +1177,22 @@ Routine Description:
}
+/**
+ Searches the FFS file and counts the number of sections found.
+ The sections are NOT recursed.
+ @param FfsFile Address of the FFS file in memory
+ @param Count The location to store the section count in
+
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+ @retval EFI_VOLUME_CORRUPTED
+**/
EFI_STATUS
FvBufCountSections (
IN VOID* FfsFile,
IN UINTN* Count
)
-/*++
-
-Routine Description:
-
- Searches the FFS file and counts the number of sections found.
- The sections are NOT recursed.
-
-Arguments:
-
- FfsFile - Address of the FFS file in memory
- Count - The location to store the section count in
-
-Returns:
-
- EFI_SUCCESS
- EFI_NOT_FOUND
- EFI_VOLUME_CORRUPTED
-
---*/
{
EFI_STATUS Status;
UINTN Key;
@@ -1424,35 +1229,26 @@ Routine Description:
return EFI_NOT_FOUND;
}
+/**
+ Searches the FFS file for a section by its type
+ @param FfsFile Address of the FFS file in memory
+ @param Type FFS FILE section type to search for
+ @param Section Output section pointer
+ (Section == NULL) -> Only determine if the section exists, based on return
+ value from the function call.
+ otherwise -> *Section will be update to the location of the file
+
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+ @retval EFI_VOLUME_CORRUPTED
+**/
EFI_STATUS
FvBufFindSectionByType (
IN VOID *FfsFile,
IN UINT8 Type,
OUT VOID **Section
)
-/*++
-
-Routine Description:
-
- Searches the FFS file for a section by its type
-
-Arguments:
-
- FfsFile - Address of the FFS file in memory
- Type - FFS FILE section type to search for
- Section - Output section pointer
- (Section == NULL) -> Only determine if the section exists, based on return
- value from the function call.
- otherwise -> *Section will be update to the location of the file
-
-Returns:
-
- EFI_SUCCESS
- EFI_NOT_FOUND
- EFI_VOLUME_CORRUPTED
-
---*/
{
EFI_STATUS Status;
UINTN Key;
@@ -1487,30 +1283,21 @@ Routine Description:
return EFI_NOT_FOUND;
}
+/**
+ Shrinks a firmware volume (in place) to provide a minimal FV.
+ BUGBUG: Does not handle the case where the firmware volume has a
+ VTF (Volume Top File). The VTF will not be moved to the
+ end of the extended FV.
+
+ @param Fv Firmware volume.
+
+ @retval EFI_SUCCESS
+**/
EFI_STATUS
FvBufShrinkWrap (
IN VOID *Fv
)
-/*++
-
-Routine Description:
-
- Shrinks a firmware volume (in place) to provide a minimal FV.
-
- BUGBUG: Does not handle the case where the firmware volume has a
- VTF (Volume Top File). The VTF will not be moved to the
- end of the extended FV.
-
-Arguments:
-
- Fv - Firmware volume.
-
-Returns:
-
- EFI_SUCCESS
-
---*/
{
EFI_STATUS Status;
UINTN OldSize;
@@ -1569,32 +1356,23 @@ Routine Description:
}
+/**
+ Searches the FFS file for a section by its type
+ @param Fv Address of the Fv in memory
+ @param BlockSize The size of the blocks to convert the Fv to. If the total size
+ of the Fv is not evenly divisible by this size, then
+ EFI_INVALID_PARAMETER will be returned.
+
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+ @retval EFI_VOLUME_CORRUPTED
+**/
EFI_STATUS
FvBufUnifyBlockSizes (
IN OUT VOID *Fv,
IN UINTN BlockSize
)
-/*++
-
-Routine Description:
-
- Searches the FFS file for a section by its type
-
-Arguments:
-
- Fv - Address of the Fv in memory
- BlockSize - The size of the blocks to convert the Fv to. If the total size
- of the Fv is not evenly divisible by this size, then
- EFI_INVALID_PARAMETER will be returned.
-
-Returns:
-
- EFI_SUCCESS
- EFI_NOT_FOUND
- EFI_VOLUME_CORRUPTED
-
---*/
{
EFI_FIRMWARE_VOLUME_HEADER *hdr = (EFI_FIRMWARE_VOLUME_HEADER*)Fv;
EFI_FV_BLOCK_MAP_ENTRY *blk = hdr->BlockMap;
@@ -1641,28 +1419,20 @@ Routine Description:
return EFI_SUCCESS;
}
-STATIC
-UINT16
-FvBufCalculateSum16 (
- IN UINT16 *Buffer,
- IN UINTN Size
- )
-/*++
-
-Routine Description:
-
+/**
This function calculates the UINT16 sum for the requested region.
-Arguments:
-
- Buffer Pointer to buffer containing byte data of component.
- Size Size of the buffer
-
-Returns:
-
- The 16 bit checksum
-
---*/
+ @param Buffer Pointer to buffer containing byte data of component.
+ @param Size Size of the buffer
+
+ @return The 16 bit checksum
+**/
+STATIC
+UINT16
+FvBufCalculateSum16 (
+ IN UINT16 *Buffer,
+ IN UINTN Size
+ )
{
UINTN Index;
UINT16 Sum;
@@ -1679,56 +1449,38 @@ Routine Description:
return (UINT16) Sum;
}
-
-STATIC
-UINT16
-FvBufCalculateChecksum16 (
- IN UINT16 *Buffer,
- IN UINTN Size
- )
-/*++
-
-Routine Description::
-
+/**
This function calculates the value needed for a valid UINT16 checksum
-Arguments:
-
- Buffer Pointer to buffer containing byte data of component.
- Size Size of the buffer
-
-Returns:
-
- The 16 bit checksum value needed.
-
---*/
+ @param Buffer Pointer to buffer containing byte data of component.
+ @param Size Size of the buffer
+
+ @return The 16 bit checksum value needed.
+**/
+STATIC
+UINT16
+FvBufCalculateChecksum16 (
+ IN UINT16 *Buffer,
+ IN UINTN Size
+ )
{
return (UINT16)(0x10000 - FvBufCalculateSum16 (Buffer, Size));
}
+/**
+ This function calculates the UINT8 sum for the requested region.
+ @param Buffer Pointer to buffer containing byte data of component.
+ @param Size Size of the buffer
+
+ @return The 8 bit checksum value needed.
+**/
STATIC
UINT8
FvBufCalculateSum8 (
IN UINT8 *Buffer,
IN UINTN Size
)
-/*++
-
-Description:
-
- This function calculates the UINT8 sum for the requested region.
-
-Input:
-
- Buffer Pointer to buffer containing byte data of component.
- Size Size of the buffer
-
-Return:
-
- The 8 bit checksum value needed.
-
---*/
{
UINTN Index;
UINT8 Sum;
@@ -1745,29 +1497,20 @@ FvBufCalculateSum8 (
return Sum;
}
-
-STATIC
-UINT8
-FvBufCalculateChecksum8 (
- IN UINT8 *Buffer,
- IN UINTN Size
- )
-/*++
-
-Description:
-
+/**
This function calculates the value needed for a valid UINT8 checksum
-Input:
-
- Buffer Pointer to buffer containing byte data of component.
- Size Size of the buffer
-
-Return:
-
- The 8 bit checksum value needed.
-
---*/
+ @param Buffer Pointer to buffer containing byte data of component.
+ @param Size Size of the buffer
+
+ @return The 8 bit checksum value needed.
+**/
+STATIC
+UINT8
+FvBufCalculateChecksum8 (
+ IN UINT8 *Buffer,
+ IN UINTN Size
+ )
{
return (UINT8)(0x100 - FvBufCalculateSum8 (Buffer, Size));
}
diff --git a/BaseTools/Source/C/Common/FvLib.c b/BaseTools/Source/C/Common/FvLib.c
index 82dc557bb7db..37631f470f2a 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
//
+
+/**
+ This initializes the FV lib with a pointer to the FV and length. It does not
+ verify the FV in any way.
+
+ @param Fv Buffer containing the FV.
+ @param FvLength Length of the FV
+
+ @retval EFI_SUCCESS Function Completed successfully.
+ @retval EFI_INVALID_PARAMETER A required parameter was NULL.
+**/
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:
-
- Fv Buffer containing the FV.
- FvLength Length of the FV
-
-Returns:
-
- EFI_SUCCESS Function Completed successfully.
- EFI_INVALID_PARAMETER A required parameter was NULL.
-
---*/
{
//
// Verify input arguments
@@ -59,29 +52,21 @@ Routine Description:
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 @@ Routine Description:
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:
-
- 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.
-
---*/
+ @param CurrentFile Pointer to the current file, must be within the current FV.
+ @param NextFile Pointer to the next file in the FV.
+
+ @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 @@ Routine Description:
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 @@ Routine Description:
return EFI_SUCCESS;
}
-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.
-
---*/
+ @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
+ )
{
EFI_FFS_FILE_HEADER *CurrentFile;
EFI_STATUS Status;
@@ -383,6 +344,23 @@ Routine Description:
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,36 +433,29 @@ Routine Description:
return EFI_NOT_FOUND;
}
-EFI_STATUS
-GetSectionByType (
- IN EFI_FFS_FILE_HEADER *File,
- IN EFI_SECTION_TYPE SectionType,
- 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:
+ @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.
- 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.
---*/
+ @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,
+ IN EFI_SECTION_TYPE SectionType,
+ IN UINTN Instance,
+ OUT EFI_FILE_SECTION_POINTER *Section
+ )
{
EFI_FILE_SECTION_POINTER CurrentSection;
EFI_STATUS Status;
@@ -560,31 +507,25 @@ Routine Description:
return EFI_NOT_FOUND;
}
}
+
//
// will not parse compressed sections
//
+
+/**
+ Verify the current pointer points to a valid FV header.
+
+ @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
)
-/*++
-
-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.
-
---*/
{
UINT16 Checksum;
@@ -612,28 +553,20 @@ Routine Description:
return EFI_SUCCESS;
}
-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.
-
---*/
+ @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
+ )
{
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 @@ Routine Description:
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:
-
- EFI_SUCCESS The function completed successfully.
- EFI_INVALID_PARAMETER One of the input parameters was invalid.
- EFI_ABORTED Operation aborted.
-
---*/
+ @param ErasePolarity A pointer to the erase polarity.
+
+ @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 @@ Routine Description:
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;
diff --git a/BaseTools/Source/C/Common/MemoryFile.c b/BaseTools/Source/C/Common/MemoryFile.c
index 8154a3c99006..47481326833e 100644
--- a/BaseTools/Source/C/Common/MemoryFile.c
+++ b/BaseTools/Source/C/Common/MemoryFile.c
@@ -27,29 +27,21 @@ CheckMemoryFileState (
// Function implementations
//
-EFI_STATUS
-GetMemoryFile (
- IN CHAR8 *InputFileName,
- OUT EFI_HANDLE *OutputMemoryFile
- )
-/*++
-
-Routine Description:
-
+/**
This opens a file, reads it into memory and returns a memory file
object.
-Arguments:
+ @param InputFile Memory file image.
+ @param OutputMemoryFile Handle to memory file
- InputFile Memory file image.
- OutputMemoryFile Handle to memory file
-
-Returns:
-
- EFI_STATUS
+ @return EFI_STATUS
OutputMemoryFile is valid if !EFI_ERROR
-
---*/
+**/
+EFI_STATUS
+GetMemoryFile (
+ IN CHAR8 *InputFileName,
+ OUT EFI_HANDLE *OutputMemoryFile
+ )
{
EFI_STATUS Status;
CHAR8 *InputFileImage;
@@ -78,26 +70,17 @@ Routine Description:
return EFI_SUCCESS;
}
-
-EFI_STATUS
-FreeMemoryFile (
- IN EFI_HANDLE InputMemoryFile
- )
-/*++
-
-Routine Description:
-
+/**
Frees all memory associated with the input memory file.
-Arguments:
-
- InputMemoryFile Handle to memory file
-
-Returns:
-
- EFI_STATUS
-
---*/
+ @param InputMemoryFile Handle to memory file
+
+ @return EFI_STATUS
+**/
+EFI_STATUS
+FreeMemoryFile (
+ IN EFI_HANDLE InputMemoryFile
+ )
{
MEMORY_FILE *MemoryFile;
@@ -118,31 +101,22 @@ Routine Description:
return EFI_SUCCESS;
}
-
-CHAR8 *
-ReadMemoryFileLine (
- IN EFI_HANDLE InputMemoryFile
- )
-/*++
-
-Routine Description:
-
+/**
This function reads a line from the memory file. The newline characters
are stripped and a null terminated string is returned.
If the string pointer returned is non-NULL, then the caller must free the
memory associated with this string.
-Arguments:
-
- InputMemoryFile Handle to memory file
-
-Returns:
-
- NULL if error or EOF
- NULL character termincated string otherwise (MUST BE FREED BY CALLER)
-
---*/
+ @param InputMemoryFile Handle to memory file
+
+ @retval NULL if error or EOF
+ @retval NULL character termincated string otherwise (MUST BE FREED BY CALLER)
+**/
+CHAR8 *
+ReadMemoryFileLine (
+ IN EFI_HANDLE InputMemoryFile
+ )
{
CHAR8 *EndOfLine;
UINTN CharsToCopy;
diff --git a/BaseTools/Source/C/Common/MyAlloc.c b/BaseTools/Source/C/Common/MyAlloc.c
index d104795d4687..17ff5cfbbd3e 100644
--- a/BaseTools/Source/C/Common/MyAlloc.c
+++ b/BaseTools/Source/C/Common/MyAlloc.c
@@ -27,40 +27,23 @@ STATIC MY_ALLOC_STRUCT *MyAllocData = NULL;
STATIC UINT32 MyAllocHeadMagik = MYALLOC_HEAD_MAGIK;
STATIC UINT32 MyAllocTailMagik = MYALLOC_TAIL_MAGIK;
-//
-// ////////////////////////////////////////////////////////////////////////////
-//
-//
+/**
+ Check for corruptions in the allocated memory chain. If a corruption
+ is detection program operation stops w/ an exit(1) call.
+
+ @param Final When FALSE, MyCheck() returns if the allocated memory chain
+ has not been corrupted. When TRUE, MyCheck() returns if there
+ are no un-freed allocations. If there are un-freed allocations,
+ they are displayed and exit(1) is called.
+ @param File Set to __FILE__ by macro expansion.
+ @param Line Set to __LINE__ by macro expansion.
+**/
VOID
MyCheck (
BOOLEAN Final,
UINT8 File[],
UINTN Line
)
-// *++
-// Description:
-//
-// Check for corruptions in the allocated memory chain. If a corruption
-// is detection program operation stops w/ an exit(1) call.
-//
-// Parameters:
-//
-// Final := When FALSE, MyCheck() returns if the allocated memory chain
-// has not been corrupted. When TRUE, MyCheck() returns if there
-// are no un-freed allocations. If there are un-freed allocations,
-// they are displayed and exit(1) is called.
-//
-//
-// File := Set to __FILE__ by macro expansion.
-//
-// Line := Set to __LINE__ by macro expansion.
-//
-// Returns:
-//
-// n/a
-//
-// --*/
-//
{
MY_ALLOC_STRUCT *Tmp;
@@ -155,39 +138,26 @@ MyCheck (
}
}
}
-//
-// ////////////////////////////////////////////////////////////////////////////
-//
-//
+
+/**
+ Allocate a new link in the allocation chain along with enough storage
+ for the File[] string, requested Size and alignment overhead. If
+ memory cannot be allocated or the allocation chain has been corrupted,
+ exit(1) will be called.
+
+ @param Size Number of bytes (UINT8) requested by the called.
+ Size cannot be zero.
+ @param File Set to __FILE__ by macro expansion.
+ @param Line Set to __LINE__ by macro expansion.
+
+ @return Pointer to the caller's buffer.
+**/
VOID *
MyAlloc (
UINTN Size,
UINT8 File[],
UINTN Line
)
-// *++
-// Description:
-//
-// Allocate a new link in the allocation chain along with enough storage
-// for the File[] string, requested Size and alignment overhead. If
-// memory cannot be allocated or the allocation chain has been corrupted,
-// exit(1) will be called.
-//
-// Parameters:
-//
-// Size := Number of bytes (UINT8) requested by the called.
-// Size cannot be zero.
-//
-// File := Set to __FILE__ by macro expansion.
-//
-// Line := Set to __LINE__ by macro expansion.
-//
-// Returns:
-//
-// Pointer to the caller's buffer.
-//
-// --*/
-//
{
MY_ALLOC_STRUCT *Tmp;
UINTN Len;
@@ -278,10 +248,19 @@ MyAlloc (
return Tmp->Buffer + sizeof (UINT32);
}
-//
-// ////////////////////////////////////////////////////////////////////////////
-//
-//
+
+/**
+ This does a MyAlloc(), memcpy() and MyFree(). There is no optimization
+ for shrinking or expanding buffers. An invalid parameter will cause
+ MyRealloc() to fail with a call to exit(1).
+
+ @param Ptr Pointer to the caller's buffer to be re-allocated.
+ @param Size Size of new buffer. Size cannot be zero.
+ @param File Set to __FILE__ by macro expansion.
+ @param Line Set to __LINE__ by macro expansion.
+
+ @return Pointer to new caller's buffer.
+**/
VOID *
MyRealloc (
VOID *Ptr,
@@ -289,29 +268,6 @@ MyRealloc (
UINT8 File[],
UINTN Line
)
-// *++
-// Description:
-//
-// This does a MyAlloc(), memcpy() and MyFree(). There is no optimization
-// for shrinking or expanding buffers. An invalid parameter will cause
-// MyRealloc() to fail with a call to exit(1).
-//
-// Parameters:
-//
-// Ptr := Pointer to the caller's buffer to be re-allocated.
-//
-// Size := Size of new buffer. Size cannot be zero.
-//
-// File := Set to __FILE__ by macro expansion.
-//
-// Line := Set to __LINE__ by macro expansion.
-//
-// Returns:
-//
-// Pointer to new caller's buffer.
-//
-// --*/
-//
{
MY_ALLOC_STRUCT *Tmp;
VOID *Buffer;
@@ -398,37 +354,22 @@ MyRealloc (
return Buffer;
}
-//
-// ////////////////////////////////////////////////////////////////////////////
-//
-//
+
+/**
+ Release a previously allocated buffer. Invalid parameters will cause
+ MyFree() to fail with an exit(1) call.
+
+ @param Ptr Pointer to the caller's buffer to be freed.
+ A NULL pointer will be ignored.
+ @param File Set to __FILE__ by macro expansion.
+ @param Line Set to __LINE__ by macro expansion.
+**/
VOID
MyFree (
VOID *Ptr,
UINT8 File[],
UINTN Line
)
-// *++
-// Description:
-//
-// Release a previously allocated buffer. Invalid parameters will cause
-// MyFree() to fail with an exit(1) call.
-//
-// Parameters:
-//
-// Ptr := Pointer to the caller's buffer to be freed.
-// A NULL pointer will be ignored.
-//
-// File := Set to __FILE__ by macro expansion.
-//
-// Line := Set to __LINE__ by macro expansion.
-//
-// Returns:
-//
-// n/a
-//
-// --*/
-//
{
MY_ALLOC_STRUCT *Tmp;
MY_ALLOC_STRUCT *Tmp2;
diff --git a/BaseTools/Source/C/Common/OsPath.c b/BaseTools/Source/C/Common/OsPath.c
index 35ca54761f14..9901f686c98f 100644
--- a/BaseTools/Source/C/Common/OsPath.c
+++ b/BaseTools/Source/C/Common/OsPath.c
@@ -20,14 +20,8 @@ SPDX-License-Identifier: BSD-2-Clause-Patent
//
// BUGBUG: Not fully implemented yet.
//
-CHAR8*
-OsPathDirName (
- IN CHAR8 *FilePath
- )
-/*++
-
-Routine Description:
+/**
This function returns the directory path which contains the particular path.
Some examples:
"a/b/c" -> "a/b"
@@ -40,15 +34,15 @@ Routine Description:
The caller must free the string returned.
-Arguments:
+ @param FilePath Path name of file to get the parent directory for.
- FilePath Path name of file to get the parent directory for.
+ @return NULL if error
+**/
+CHAR8*
+OsPathDirName (
+ IN CHAR8 *FilePath
+ )
-Returns:
-
- NULL if error
-
---*/
{
CHAR8 *Return;
CHAR8 *Pos;
@@ -97,14 +91,8 @@ Routine Description:
//
// BUGBUG: Not fully implemented yet.
//
-VOID
-OsPathNormPathInPlace (
- IN CHAR8 *Path
- )
-/*++
-
-Routine Description:
+/**
This function returns the directory path which contains the particular path.
Some examples:
"a/b/../c" -> "a/c"
@@ -113,15 +101,14 @@ Routine Description:
This function does not check for the existence of the file.
-Arguments:
-
- Path Path name of file to normalize
-
-Returns:
-
- The string is altered in place.
-
---*/
+ @param Path Path name of file to normalize
+
+ @return The string is altered in place.
+**/
+VOID
+OsPathNormPathInPlace (
+ IN CHAR8 *Path
+ )
{
CHAR8 *Pos;
INTN Offset;
@@ -200,16 +187,7 @@ Routine Description:
}
#endif
-
-CHAR8*
-OsPathPeerFilePath (
- IN CHAR8 *OldPath,
- IN CHAR8 *Peer
- )
-/*++
-
-Routine Description:
-
+/**
This function replaces the final portion of a path with an alternative
'peer' filename. For example:
"a/b/../c", "peer" -> "a/b/../peer"
@@ -219,16 +197,16 @@ Routine Description:
This function does not check for the existence of the file.
-Arguments:
-
- OldPath Path name of replace the final segment
- Peer The new path name to concatenate to become the peer path
-
-Returns:
-
- A CHAR8* string, which must be freed by the caller
-
---*/
+ @param OldPath Path name of replace the final segment
+ @param Peer The new path name to concatenate to become the peer path
+
+ @return A CHAR8* string, which must be freed by the caller
+**/
+CHAR8*
+OsPathPeerFilePath (
+ IN CHAR8 *OldPath,
+ IN CHAR8 *Peer
+ )
{
CHAR8 *Result;
INTN Offset;
@@ -259,27 +237,18 @@ Routine Description:
return Result;
}
+/**
+ Checks if a file exists
+ @param InputFileName The name of the file to check for existence
+
+ @retval TRUE The file exists
+ @retval FALSE The file does not exist
+**/
BOOLEAN
OsPathExists (
IN CHAR8 *InputFileName
)
-/*++
-
-Routine Description:
-
- Checks if a file exists
-
-Arguments:
-
- InputFileName The name of the file to check for existence
-
-Returns:
-
- TRUE The file exists
- FALSE The file does not exist
-
---*/
{
FILE *InputFile;
InputFile = fopen (LongFilePath (InputFileName), "rb");
diff --git a/BaseTools/Source/C/Common/ParseGuidedSectionTools.c b/BaseTools/Source/C/Common/ParseGuidedSectionTools.c
index a34581ecb61a..e1e9a97e7bf6 100644
--- a/BaseTools/Source/C/Common/ParseGuidedSectionTools.c
+++ b/BaseTools/Source/C/Common/ParseGuidedSectionTools.c
@@ -33,30 +33,22 @@ typedef struct _GUID_SEC_TOOL_ENTRY {
// Function Implementation
//
+/**
+ This function parses the tools_def.txt file. It returns a
+ EFI_HANDLE object which can be used for the other library
+ functions and should be passed to FreeParsedGuidedSectionToolsHandle
+ to free resources when the tools_def.txt information is no
+ longer needed.
+
+ @param InputFile Path name of file to read
+
+ @retval NULL if error parsing
+ @retval A non-NULL EFI_HANDLE otherwise
+**/
EFI_HANDLE
ParseGuidedSectionToolsFile (
IN CHAR8 *InputFile
)
-/*++
-
-Routine Description:
-
- This function parses the tools_def.txt file. It returns a
- EFI_HANDLE object which can be used for the other library
- functions and should be passed to FreeParsedGuidedSectionToolsHandle
- to free resources when the tools_def.txt information is no
- longer needed.
-
-Arguments:
-
- InputFile Path name of file to read
-
-Returns:
-
- NULL if error parsing
- A non-NULL EFI_HANDLE otherwise
-
---*/
{
EFI_STATUS Status;
EFI_HANDLE MemoryFile;
@@ -74,31 +66,22 @@ Routine Description:
return ParsedGuidedSectionTools;
}
+/**
+ This function parses the tools_def.txt file. It returns a
+ EFI_HANDLE object which can be used for the other library
+ functions and should be passed to FreeParsedGuidedSectionToolsHandle
+ to free resources when the tools_def.txt information is no
+ longer needed.
+ @param InputFile Memory file image.
+
+ @retval NULL if error or EOF
+ @retval InputBuffer otherwise
+**/
EFI_HANDLE
ParseGuidedSectionToolsMemoryFile (
IN EFI_HANDLE InputFile
)
-/*++
-
-Routine Description:
-
- This function parses the tools_def.txt file. It returns a
- EFI_HANDLE object which can be used for the other library
- functions and should be passed to FreeParsedGuidedSectionToolsHandle
- to free resources when the tools_def.txt information is no
- longer needed.
-
-Arguments:
-
- InputFile Memory file image.
-
-Returns:
-
- NULL if error or EOF
- InputBuffer otherwise
-
---*/
{
EFI_STATUS Status;
CHAR8 *NextLine;
@@ -160,31 +143,22 @@ Routine Description:
return FirstGuidTool;
}
+/**
+ This function looks up the appropriate tool to use for extracting
+ a GUID defined FV section.
+ @param ParsedGuidedSectionToolsHandle A parsed GUID section tools handle.
+ @param SectionGuid The GUID for the section.
+
+ @retval NULL if no tool is found or there is another error
+ @retval Non-NULL The tool to use to access the section contents. (The caller
+ must free the memory associated with this string.)
+**/
CHAR8*
LookupGuidedSectionToolPath (
IN EFI_HANDLE ParsedGuidedSectionToolsHandle,
IN EFI_GUID *SectionGuid
)
-/*++
-
-Routine Description:
-
- This function looks up the appropriate tool to use for extracting
- a GUID defined FV section.
-
-Arguments:
-
- ParsedGuidedSectionToolsHandle A parsed GUID section tools handle.
- SectionGuid The GUID for the section.
-
-Returns:
-
- NULL - if no tool is found or there is another error
- Non-NULL - The tool to use to access the section contents. (The caller
- must free the memory associated with this string.)
-
---*/
{
GUID_SEC_TOOL_ENTRY *GuidTool;
diff --git a/BaseTools/Source/C/Common/ParseInf.c b/BaseTools/Source/C/Common/ParseInf.c
index 5ef8f1306d65..63da3d647cb7 100644
--- a/BaseTools/Source/C/Common/ParseInf.c
+++ b/BaseTools/Source/C/Common/ParseInf.c
@@ -14,16 +14,7 @@ SPDX-License-Identifier: BSD-2-Clause-Patent
#include "ParseInf.h"
#include "CommonLib.h"
-CHAR8 *
-ReadLine (
- IN MEMORY_FILE *InputFile,
- IN OUT CHAR8 *InputBuffer,
- IN UINTN MaxLength
- )
-/*++
-
-Routine Description:
-
+/**
This function reads a line, stripping any comments.
The function reads a string from the input stream argument and stores it in
the input string. ReadLine reads characters from the current file position
@@ -31,18 +22,20 @@ Routine Description:
until the number of characters read is equal to MaxLength - 1, whichever
comes first. The newline character, if read, is replaced with a \0.
-Arguments:
+ @param InputFile Memory file image.
+ @param InputBuffer Buffer to read into, must be MaxLength size.
+ @param MaxLength The maximum size of the input buffer.
+
+ @retval NULL if error or EOF
+ @retval InputBuffer otherwise
+**/
+CHAR8 *
+ReadLine (
+ IN MEMORY_FILE *InputFile,
+ IN OUT CHAR8 *InputBuffer,
+ IN UINTN MaxLength
+ )
- InputFile Memory file image.
- InputBuffer Buffer to read into, must be MaxLength size.
- MaxLength The maximum size of the input buffer.
-
-Returns:
-
- NULL if error or EOF
- InputBuffer otherwise
-
---*/
{
CHAR8 *CharPtr;
CHAR8 *EndOfLine;
@@ -129,29 +122,21 @@ Routine Description:
return InputBuffer;
}
+/**
+ This function parses a file from the beginning to find a section.
+ The section string may be anywhere within a line.
+
+ @param InputFile Memory file image.
+ @param Section Section to search for
+
+ @retval FALSE if error or EOF
+ @retval TRUE if section found
+**/
BOOLEAN
FindSection (
IN MEMORY_FILE *InputFile,
IN CHAR8 *Section
)
-/*++
-
-Routine Description:
-
- This function parses a file from the beginning to find a section.
- The section string may be anywhere within a line.
-
-Arguments:
-
- InputFile Memory file image.
- Section Section to search for
-
-Returns:
-
- FALSE if error or EOF
- TRUE if section found
-
---*/
{
CHAR8 InputBuffer[MAX_LONG_FILE_PATH];
CHAR8 *CurrentToken;
@@ -190,6 +175,21 @@ Routine Description:
return FALSE;
}
+/**
+ Finds a token value given the section and token to search for.
+
+ @param InputFile Memory file image.
+ @param Section The section to search for, a string within [].
+ @param Token The token to search for, e.g. EFI_PEIM_RECOVERY, followed by an = in the INF file.
+ @param Instance The instance of the token to search for. Zero is the first instance.
+ @param Value The string that holds the value following the =. Must be MAX_LONG_FILE_PATH in size.
+
+ @retval EFI_SUCCESS Value found.
+ @retval EFI_ABORTED Format error detected in INF file.
+ @retval EFI_INVALID_PARAMETER Input argument was null.
+ @retval EFI_LOAD_ERROR Error reading from the file.
+ @retval EFI_NOT_FOUND Section/Token/Value not found.
+**/
EFI_STATUS
FindToken (
IN MEMORY_FILE *InputFile,
@@ -198,29 +198,6 @@ FindToken (
IN UINTN Instance,
OUT CHAR8 *Value
)
-/*++
-
-Routine Description:
-
- Finds a token value given the section and token to search for.
-
-Arguments:
-
- InputFile Memory file image.
- Section The section to search for, a string within [].
- Token The token to search for, e.g. EFI_PEIM_RECOVERY, followed by an = in the INF file.
- Instance The instance of the token to search for. Zero is the first instance.
- Value The string that holds the value following the =. Must be MAX_LONG_FILE_PATH in size.
-
-Returns:
-
- EFI_SUCCESS Value found.
- EFI_ABORTED Format error detected in INF file.
- EFI_INVALID_PARAMETER Input argument was null.
- EFI_LOAD_ERROR Error reading from the file.
- EFI_NOT_FOUND Section/Token/Value not found.
-
---*/
{
CHAR8 InputBuffer[MAX_LONG_FILE_PATH];
CHAR8 *CurrentToken;
@@ -359,30 +336,22 @@ Routine Description:
return EFI_NOT_FOUND;
}
+/**
+ Converts a string to an EFI_GUID. The string must be in the
+ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx format.
+
+ @param AsciiGuidBuffer pointer to ascii string
+ @param GuidBuffer pointer to destination Guid
+
+ @retval EFI_ABORTED Could not convert the string
+ @retval EFI_SUCCESS The string was successfully converted
+ @retval EFI_INVALID_PARAMETER Input parameter is invalid.
+**/
EFI_STATUS
StringToGuid (
IN CHAR8 *AsciiGuidBuffer,
OUT EFI_GUID *GuidBuffer
)
-/*++
-
-Routine Description:
-
- Converts a string to an EFI_GUID. The string must be in the
- xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx format.
-
-Arguments:
-
- AsciiGuidBuffer - pointer to ascii string
- GuidBuffer - pointer to destination Guid
-
-Returns:
-
- EFI_ABORTED Could not convert the string
- EFI_SUCCESS The string was successfully converted
- EFI_INVALID_PARAMETER Input parameter is invalid.
-
---*/
{
INT32 Index;
int Data1;
@@ -461,33 +430,25 @@ Routine Description:
return EFI_SUCCESS;
}
-EFI_STATUS
-AsciiStringToUint64 (
- IN CONST CHAR8 *AsciiString,
- IN BOOLEAN IsHex,
- OUT UINT64 *ReturnValue
- )
-/*++
-
-Routine Description:
-
+/**
Converts a null terminated ascii string that represents a number into a
UINT64 value. A hex number may be preceded by a 0x, but may not be
succeeded by an h. A number without 0x or 0X is considered to be base 10
unless the IsHex input is true.
-Arguments:
-
- AsciiString The string to convert.
- IsHex Force the string to be treated as a hex number.
- ReturnValue The return value.
-
-Returns:
-
- EFI_SUCCESS Number successfully converted.
- EFI_ABORTED Invalid character encountered.
-
---*/
+ @param AsciiString The string to convert.
+ @param IsHex Force the string to be treated as a hex number.
+ @param ReturnValue The return value.
+
+ @retval EFI_SUCCESS Number successfully converted.
+ @retval EFI_ABORTED Invalid character encountered.
+**/
+EFI_STATUS
+AsciiStringToUint64 (
+ IN CONST CHAR8 *AsciiString,
+ IN BOOLEAN IsHex,
+ OUT UINT64 *ReturnValue
+ )
{
UINT8 Index;
UINT64 Value;
@@ -577,29 +538,21 @@ Routine Description:
return EFI_SUCCESS;
}
+/**
+ This function reads a line, stripping any comments.
+ // BUGBUG: This is obsolete once genmake goes away...
+
+ @param InputFile Stream pointer.
+ @param InputBuffer Buffer to read into, must be MAX_LONG_FILE_PATH size.
+
+ @retval NULL if error or EOF
+ @retval InputBuffer otherwise
+**/
CHAR8 *
ReadLineInStream (
IN FILE *InputFile,
IN OUT CHAR8 *InputBuffer
)
-/*++
-
-Routine Description:
-
- This function reads a line, stripping any comments.
- // BUGBUG: This is obsolete once genmake goes away...
-
-Arguments:
-
- InputFile Stream pointer.
- InputBuffer Buffer to read into, must be MAX_LONG_FILE_PATH size.
-
-Returns:
-
- NULL if error or EOF
- InputBuffer otherwise
-
---*/
{
CHAR8 *CharPtr;
@@ -633,30 +586,22 @@ Routine Description:
return InputBuffer;
}
+/**
+ This function parses a stream file from the beginning to find a section.
+ The section string may be anywhere within a line.
+ // BUGBUG: This is obsolete once genmake goes away...
+
+ @param InputFile Stream pointer.
+ @param Section Section to search for
+
+ @retval FALSE if error or EOF
+ @retval TRUE if section found
+**/
BOOLEAN
FindSectionInStream (
IN FILE *InputFile,
IN CHAR8 *Section
)
-/*++
-
-Routine Description:
-
- This function parses a stream file from the beginning to find a section.
- The section string may be anywhere within a line.
- // BUGBUG: This is obsolete once genmake goes away...
-
-Arguments:
-
- InputFile Stream pointer.
- Section Section to search for
-
-Returns:
-
- FALSE if error or EOF
- TRUE if section found
-
---*/
{
CHAR8 InputBuffer[MAX_LONG_FILE_PATH];
CHAR8 *CurrentToken;
diff --git a/BaseTools/Source/C/Common/PcdValueCommon.c b/BaseTools/Source/C/Common/PcdValueCommon.c
index 98023e8786d8..591a7787828c 100644
--- a/BaseTools/Source/C/Common/PcdValueCommon.c
+++ b/BaseTools/Source/C/Common/PcdValueCommon.c
@@ -35,6 +35,15 @@ typedef struct {
PCD_ENTRY *PcdList;
UINT32 PcdListLength;
+/**
+ Record new token information
+
+ @param FileBuffer File Buffer to be record
+ @param PcdIndex Index of PCD in database
+ @param TokenIndex Index of Token
+ @param TokenStart Start of Token
+ @param TokenEnd End of Token
+**/
VOID
STATIC
RecordToken (
@@ -44,24 +53,7 @@ RecordToken (
UINT32 TokenStart,
UINT32 TokenEnd
)
-/*++
-Routine Description:
-
- Record new token information
-
-Arguments:
-
- FileBuffer File Buffer to be record
- PcdIndex Index of PCD in database
- TokenIndex Index of Token
- TokenStart Start of Token
- TokenEnd End of Token
-
-Returns:
-
- None
---*/
{
CHAR8 *Token;
@@ -109,31 +101,24 @@ Routine Description:
}
}
-int
-STATIC
-LookupPcdIndex (
- CHAR8 *SkuName OPTIONAL,
- CHAR8 *DefaultValueName OPTIONAL,
- CHAR8 *TokenSpaceGuidName,
- CHAR8 *TokenName
- )
-/*++
-
-Routine Description:
-
+/**
Get PCD index in Pcd database
-Arguments:
+ @param SkuName SkuName String
+ @param DefaultValueName DefaultValueName String
+ @param TokenSpaceGuidName TokenSpaceGuidName String
+ @param TokenName TokenName String
- SkuName SkuName String
- DefaultValueName DefaultValueName String
- TokenSpaceGuidName TokenSpaceGuidName String
- TokenName TokenName String
-
-Returns:
-
- Index of PCD in Pcd database
---*/
+ @return Index of PCD in Pcd database
+**/
+int
+STATIC
+LookupPcdIndex (
+ CHAR8 *SkuName OPTIONAL,
+ CHAR8 *DefaultValueName OPTIONAL,
+ CHAR8 *TokenSpaceGuidName,
+ CHAR8 *TokenName
+ )
{
UINT32 Index;
@@ -161,6 +146,16 @@ Routine Description:
return -1;
}
+/**
+ Get PCD value
+
+ @param SkuName SkuName String
+ @param DefaultValueName DefaultValueName String
+ @param TokenSpaceGuidName TokenSpaceGuidName String
+ @param TokenName TokenName String
+
+ @return PCD value
+**/
UINT64
__PcdGet (
CHAR8 *SkuName OPTIONAL,
@@ -168,23 +163,6 @@ __PcdGet (
CHAR8 *TokenSpaceGuidName,
CHAR8 *TokenName
)
-/*++
-
-Routine Description:
-
- Get PCD value
-
-Arguments:
-
- SkuName SkuName String
- DefaultValueName DefaultValueName String
- TokenSpaceGuidName TokenSpaceGuidName String
- TokenName TokenName String
-
-Returns:
-
- PCD value
---*/
{
int Index;
CHAR8 *End;
@@ -212,6 +190,15 @@ Routine Description:
return 0;
}
+/**
+ Set PCD value
+
+ @param SkuName SkuName String
+ @param DefaultValueName DefaultValueName String
+ @param TokenSpaceGuidName TokenSpaceGuidName String
+ @param TokenName TokenName String
+ @param Value PCD value to be set
+**/
VOID
__PcdSet (
CHAR8 *SkuName OPTIONAL,
@@ -220,24 +207,6 @@ __PcdSet (
CHAR8 *TokenName,
UINT64 Value
)
-/*++
-
-Routine Description:
-
- Set PCD value
-
-Arguments:
-
- SkuName SkuName String
- DefaultValueName DefaultValueName String
- TokenSpaceGuidName TokenSpaceGuidName String
- TokenName TokenName String
- Value PCD value to be set
-
-Returns:
-
- None
---*/
{
int Index;
@@ -275,6 +244,17 @@ Routine Description:
}
}
+/**
+ Get PCD value buffer
+
+ @param SkuName SkuName String
+ @param DefaultValueName DefaultValueName String
+ @param TokenSpaceGuidName TokenSpaceGuidName String
+ @param TokenName TokenName String
+ @param Size Size of PCD value buffer
+
+ @return PCD value buffer
+**/
VOID *
__PcdGetPtr (
CHAR8 *SkuName OPTIONAL,
@@ -283,24 +263,6 @@ __PcdGetPtr (
CHAR8 *TokenName,
UINT32 *Size
)
-/*++
-
-Routine Description:
-
- Get PCD value buffer
-
-Arguments:
-
- SkuName SkuName String
- DefaultValueName DefaultValueName String
- TokenSpaceGuidName TokenSpaceGuidName String
- TokenName TokenName String
- Size Size of PCD value buffer
-
-Returns:
-
- PCD value buffer
---*/
{
int Index;
CHAR8 *Value;
@@ -341,6 +303,16 @@ Routine Description:
return 0;
}
+/**
+ Set PCD value buffer
+
+ @param SkuName SkuName String
+ @param DefaultValueName DefaultValueName String
+ @param TokenSpaceGuidName TokenSpaceGuidName String
+ @param TokenName TokenName String
+ @param Size Size of PCD value
+ @param Value Pointer to the updated PCD value buffer
+**/
VOID
__PcdSetPtr (
CHAR8 *SkuName OPTIONAL,
@@ -350,25 +322,6 @@ __PcdSetPtr (
UINT32 Size,
UINT8 *Value
)
-/*++
-
-Routine Description:
-
- Set PCD value buffer
-
-Arguments:
-
- SkuName SkuName String
- DefaultValueName DefaultValueName String
- TokenSpaceGuidName TokenSpaceGuidName String
- TokenName TokenName String
- Size Size of PCD value
- Value Pointer to the updated PCD value buffer
-
-Returns:
-
- None
---*/
{
int Index;
UINT32 ValueIndex;
@@ -400,6 +353,13 @@ Routine Description:
}
}
+/**
+ Read the file buffer from the input file.
+
+ @param InputFileName Point to the input file name.
+ @param FileBuffer Point to the input file buffer.
+ @param FileSize Size of the file buffer.
+**/
VOID
STATIC
ReadInputFile (
@@ -407,22 +367,6 @@ ReadInputFile (
UINT8 **FileBuffer,
UINT32 *FileSize
)
-/*++
-
-Routine Description:
-
- Read the file buffer from the input file.
-
-Arguments:
-
- InputFileName Point to the input file name.
- FileBuffer Point to the input file buffer.
- FileSize Size of the file buffer.
-
-Returns:
-
- None
---*/
{
FILE *InputFile;
UINT32 BytesRead;
@@ -492,27 +436,18 @@ Routine Description:
fclose (InputFile);
}
+/**
+ Read the initial PCD value from the input file buffer.
+
+ @param FileBuffer Point to the input file buffer.
+ @param FileSize Size of the file buffer.
+**/
VOID
STATIC
ParseFile (
UINT8 *FileBuffer,
UINT32 FileSize
)
-/*++
-
-Routine Description:
-
- Read the initial PCD value from the input file buffer.
-
-Arguments:
-
- FileBuffer Point to the input file buffer.
- FileSize Size of the file buffer.
-
-Returns:
-
- None
---*/
{
UINT32 Index;
UINT32 NumLines;
@@ -552,25 +487,16 @@ Routine Description:
}
}
+/**
+ Write the updated PCD value into the output file name.
+
+ @param OutputFileName Point to the output file name.
+**/
VOID
STATIC
WriteOutputFile (
CHAR8 *OutputFileName
)
-/*++
-
-Routine Description:
-
- Write the updated PCD value into the output file name.
-
-Arguments:
-
- OutputFileName Point to the output file name.
-
-Returns:
-
- None
---*/
{
FILE *OutputFile;
UINT32 Index;
@@ -605,26 +531,14 @@ Routine Description:
}
}
+/**
+ Displays the utility usage syntax to STDOUT
+**/
VOID
STATIC
Usage (
VOID
)
-/*++
-
-Routine Description:
-
- Displays the utility usage syntax to STDOUT
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
{
fprintf (stdout, "Usage: -i <input_file> -o <output_file>\n\n");
fprintf (stdout, "optional arguments:\n");
@@ -635,6 +549,14 @@ Routine Description:
PCD Database Output file name\n");
}
+/**
+ Parse the input parameters to get the input/output file name.
+
+ @param argc Number of command line parameters.
+ @param argv Array of pointers to parameter strings.
+ @param InputFileName Point to the input file name.
+ @param OutputFileName Point to the output file name.
+**/
VOID
STATIC
ParseArguments (
@@ -643,23 +565,6 @@ ParseArguments (
CHAR8 **InputFileName,
CHAR8 **OutputFileName
)
-/*++
-
-Routine Description:
-
- Parse the input parameters to get the input/output file name.
-
-Arguments:
-
- argc Number of command line parameters.
- argv Array of pointers to parameter strings.
- InputFileName Point to the input file name.
- OutputFileName Point to the output file name.
-
-Returns:
-
- None
---*/
{
if (argc == 1) {
fprintf (stderr, "Missing options\n");
@@ -722,25 +627,19 @@ Routine Description:
}
}
+/**
+ Main function updates PCD values.
+
+ @param argc Number of command line parameters.
+ @param argv Array of pointers to parameter strings.
+
+ @retval EXIT_SUCCESS
+**/
int
PcdValueMain (
int argc,
char *argv[]
)
-/*++
-
-Routine Description:
-
- Main function updates PCD values.
-
-Arguments:
-
- argc Number of command line parameters.
- argv Array of pointers to parameter strings.
-
-Returns:
- EXIT_SUCCESS
---*/
{
CHAR8 *InputFileName;
CHAR8 *OutputFileName;
diff --git a/BaseTools/Source/C/Common/PeCoffLoaderEx.c b/BaseTools/Source/C/Common/PeCoffLoaderEx.c
index 2cc428d733b4..181192035ef1 100644
--- a/BaseTools/Source/C/Common/PeCoffLoaderEx.c
+++ b/BaseTools/Source/C/Common/PeCoffLoaderEx.c
@@ -65,59 +65,37 @@ SPDX-License-Identifier: BSD-2-Clause-Patent
UINT32 *RiscVHi20Fixup = NULL;
-RETURN_STATUS
-PeCoffLoaderRelocateIa32Image (
- IN UINT16 *Reloc,
- IN OUT CHAR8 *Fixup,
- IN OUT CHAR8 **FixupData,
- IN UINT64 Adjust
- )
-/*++
-
-Routine Description:
-
+/**
Performs an IA-32 specific relocation fixup
-Arguments:
-
- Reloc - Pointer to the relocation record
-
- Fixup - Pointer to the address to fix up
-
- FixupData - Pointer to a buffer to log the fixups
-
- Adjust - The offset to adjust the fixup
-
-Returns:
-
- EFI_UNSUPPORTED - Unsupported now
-
---*/
+ @param Reloc Pointer to the relocation record
+ @param Fixup Pointer to the address to fix up
+ @param FixupData Pointer to a buffer to log the fixups
+ @param Adjust The offset to adjust the fixup
+
+ @retval EFI_UNSUPPORTED - Unsupported now
+**/
+RETURN_STATUS
+PeCoffLoaderRelocateIa32Image (
+ IN UINT16 *Reloc,
+ IN OUT CHAR8 *Fixup,
+ IN OUT CHAR8 **FixupData,
+ IN UINT64 Adjust
+ )
{
return RETURN_UNSUPPORTED;
}
-/*++
-
-Routine Description:
-
+/**
Performs an RISC-V specific relocation fixup
-Arguments:
+ @param Reloc Pointer to the relocation record
+ @param Fixup Pointer to the address to fix up
+ @param FixupData Pointer to a buffer to log the fixups
+ @param Adjust The offset to adjust the fixup
- Reloc - Pointer to the relocation record
-
- Fixup - Pointer to the address to fix up
-
- FixupData - Pointer to a buffer to log the fixups
-
- Adjust - The offset to adjust the fixup
-
-Returns:
-
- Status code
-
---*/
+ @return Status code
+**/
RETURN_STATUS
PeCoffLoaderRelocateRiscVImage (
IN UINT16 *Reloc,
diff --git a/BaseTools/Source/C/Common/SimpleFileParsing.c b/BaseTools/Source/C/Common/SimpleFileParsing.c
index eb6abea1bec7..51d59cf4a765 100644
--- a/BaseTools/Source/C/Common/SimpleFileParsing.c
+++ b/BaseTools/Source/C/Common/SimpleFileParsing.c
@@ -152,65 +152,43 @@ SetFilePosition (
FILE_POSITION *Fpos
);
+/**
+ @retval STATUS_SUCCESS always
+**/
STATUS
SFPInit (
VOID
)
-/*++
-
-Routine Description:
-
-Arguments:
- None.
-
-Returns:
- STATUS_SUCCESS always
-
---*/
{
memset ((VOID *) &mGlobals, 0, sizeof (mGlobals));
return STATUS_SUCCESS;
}
-UINTN
-SFPGetLineNumber (
- VOID
- )
-/*++
-
-Routine Description:
+/**
Return the line number of the file we're parsing. Used
for error reporting purposes.
-Arguments:
- None.
-
-Returns:
- The line number, or 0 if no file is being processed
-
---*/
+ @return The line number, or 0 if no file is being processed
+**/
+UINTN
+SFPGetLineNumber (
+ VOID
+ )
{
return mGlobals.SourceFile.LineNum;
}
-CHAR8 *
-SFPGetFileName (
- VOID
- )
-/*++
-
-Routine Description:
+/**
Return the name of the file we're parsing. Used
for error reporting purposes.
-Arguments:
- None.
-
-Returns:
- A pointer to the file name. Null if no file is being
+ @return A pointer to the file name. Null if no file is being
processed.
-
---*/
+**/
+CHAR8 *
+SFPGetFileName (
+ VOID
+ )
{
if (mGlobals.SourceFile.FileName[0]) {
return mGlobals.SourceFile.FileName;
@@ -219,22 +197,15 @@ Routine Description:
return NULL;
}
+/**
+ Open a file for parsing.
+
+ @param FileName name of the file to parse
+**/
STATUS
SFPOpenFile (
CHAR8 *FileName
)
-/*++
-
-Routine Description:
- Open a file for parsing.
-
-Arguments:
- FileName - name of the file to parse
-
-Returns:
-
-
---*/
{
STATUS Status;
t_strcpy (mGlobals.SourceFile.FileName, FileName);
@@ -242,31 +213,26 @@ Routine Description:
return Status;
}
-BOOLEAN
-SFPIsToken (
- CHAR8 *Str
- )
-/*++
-
-Routine Description:
+/**
Check to see if the specified token is found at
the current position in the input file.
-Arguments:
- Str - the token to look for
+ @note:
+ We do a simple string comparison on this function. It is
+ the responsibility of the caller to ensure that the token
+ is not a subset of some other token.
-Returns:
- TRUE - the token is next
- FALSE - the token is not next
+ The file pointer is advanced past the token in the input file.
+
+ @param Str the token to look for
-Notes:
- We do a simple string comparison on this function. It is
- the responsibility of the caller to ensure that the token
- is not a subset of some other token.
-
- The file pointer is advanced past the token in the input file.
-
---*/
+ @retval TRUE the token is next
+ @retval FALSE the token is not next
+**/
+BOOLEAN
+SFPIsToken (
+ CHAR8 *Str
+ )
{
UINTN Len;
SkipWhiteSpace (&mGlobals.SourceFile);
@@ -286,28 +252,23 @@ Routine Description:
return FALSE;
}
-BOOLEAN
-SFPIsKeyword (
- CHAR8 *Str
- )
-/*++
-
-Routine Description:
+/**
Check to see if the specified keyword is found at
the current position in the input file.
-Arguments:
- Str - keyword to look for
+ @note:
+ A keyword is defined as a "special" string that has a non-alphanumeric
+ character following it.
+
+ @param Str keyword to look for
-Returns:
- TRUE - the keyword is next
- FALSE - the keyword is not next
-
-Notes:
- A keyword is defined as a "special" string that has a non-alphanumeric
- character following it.
-
---*/
+ @retval TRUE the keyword is next
+ @retval FALSE the keyword is not next
+**/
+BOOLEAN
+SFPIsKeyword (
+ CHAR8 *Str
+ )
{
UINTN Len;
SkipWhiteSpace (&mGlobals.SourceFile);
@@ -331,30 +292,25 @@ Routine Description:
return FALSE;
}
+/**
+ Get the next token from the input stream.
+
+ @note:
+ Preceding white space is ignored.
+ The parser's buffer pointer is advanced past the end of the
+ token.
+
+ @param Str pointer to a copy of the next token
+ @param Len size of buffer pointed to by Str
+
+ @retval TRUE next token successfully returned
+ @retval FALSE otherwise
+**/
BOOLEAN
SFPGetNextToken (
CHAR8 *Str,
UINTN Len
)
-/*++
-
-Routine Description:
- Get the next token from the input stream.
-
-Arguments:
- Str - pointer to a copy of the next token
- Len - size of buffer pointed to by Str
-
-Returns:
- TRUE - next token successfully returned
- FALSE - otherwise
-
-Notes:
- Preceding white space is ignored.
- The parser's buffer pointer is advanced past the end of the
- token.
-
---*/
{
UINTN Index;
CHAR8 TempChar;
@@ -436,25 +392,20 @@ Routine Description:
return FALSE;
}
+/**
+ Parse a GUID from the input stream. Stop when you discover white space.
+
+ @param Str pointer to a copy of the next token
+ @param Len size of buffer pointed to by Str
+
+ @retval TRUE GUID string returned successfully
+ @retval FALSE otherwise
+**/
BOOLEAN
SFPGetGuidToken (
CHAR8 *Str,
UINT32 Len
)
-/*++
-
-Routine Description:
- Parse a GUID from the input stream. Stop when you discover white space.
-
-Arguments:
- Str - pointer to a copy of the next token
- Len - size of buffer pointed to by Str
-
-Returns:
- TRUE - GUID string returned successfully
- FALSE - otherwise
-
---*/
{
UINT32 Index;
SkipWhiteSpace (&mGlobals.SourceFile);
@@ -505,24 +456,19 @@ SFPSkipToToken (
return FALSE;
}
-BOOLEAN
-SFPGetNumber (
- UINTN *Value
- )
-/*++
-
-Routine Description:
+/**
Check the token at the current file position for a numeric value.
May be either decimal or hex.
-Arguments:
- Value - pointer where to store the value
+ @param Value pointer where to store the value
-Returns:
- FALSE - current token is not a number
- TRUE - current token is a number
-
---*/
+ @retval FALSE current token is not a number
+ @retval TRUE current token is a number
+**/
+BOOLEAN
+SFPGetNumber (
+ UINTN *Value
+ )
{
int Val;
@@ -561,23 +507,16 @@ Routine Description:
}
}
-STATUS
-SFPCloseFile (
- VOID
- )
-/*++
-
-Routine Description:
+/**
Close the file being parsed.
-Arguments:
- None.
-
-Returns:
- STATUS_SUCCESS - the file was closed
- STATUS_ERROR - no file is currently open
-
---*/
+ @retval STATUS_SUCCESS the file was closed
+ @retval STATUS_ERROR no file is currently open
+**/
+STATUS
+SFPCloseFile (
+ VOID
+ )
{
if (mGlobals.SourceFile.FileBuffer != NULL) {
free (mGlobals.SourceFile.FileBuffer);
@@ -588,28 +527,20 @@ Routine Description:
return STATUS_ERROR;
}
-STATIC
-STATUS
-ProcessIncludeFile (
- SOURCE_FILE *SourceFile,
- SOURCE_FILE *ParentSourceFile
- )
-/*++
-
-Routine Description:
-
+/**
Given a source file, open the file and parse it
-Arguments:
-
- SourceFile - name of file to parse
- ParentSourceFile - for error reporting purposes, the file that #included SourceFile.
-
-Returns:
-
- Standard status.
-
---*/
+ @param SourceFile name of file to parse
+ @param ParentSourceFile for error reporting purposes, the file that #included SourceFile.
+
+ @return Standard status.
+**/
+STATIC
+STATUS
+ProcessIncludeFile (
+ SOURCE_FILE *SourceFile,
+ SOURCE_FILE *ParentSourceFile
+ )
{
STATIC UINTN NestDepth = 0;
CHAR8 FoundFileName[MAX_PATH];
@@ -657,27 +588,19 @@ Routine Description:
return Status;
}
-STATIC
-STATUS
-ProcessFile (
- SOURCE_FILE *SourceFile
- )
-/*++
-
-Routine Description:
-
+/**
Given a source file that's been opened, read the contents into an internal
buffer and pre-process it to remove comments.
-Arguments:
-
- SourceFile - structure containing info on the file to process
-
-Returns:
-
- Standard status.
-
---*/
+ @param SourceFile structure containing info on the file to process
+
+ @return Standard status.
+**/
+STATIC
+STATUS
+ProcessFile (
+ SOURCE_FILE *SourceFile
+ )
{
//
// Get the file size, and then read the entire thing into memory.
@@ -706,24 +629,17 @@ Routine Description:
return STATUS_SUCCESS;
}
-STATIC
-VOID
-PreprocessFile (
- SOURCE_FILE *SourceFile
- )
-/*++
-
-Routine Description:
+/**
Preprocess a file to replace all carriage returns with NULLs so
we can print lines (as part of error messages) from the file to the screen.
-Arguments:
- SourceFile - structure that we use to keep track of an input file.
-
-Returns:
- Nothing.
-
---*/
+ @param SourceFile structure that we use to keep track of an input file.
+**/
+STATIC
+VOID
+PreprocessFile (
+ SOURCE_FILE *SourceFile
+ )
{
BOOLEAN InComment;
BOOLEAN SlashSlashComment;
@@ -812,26 +728,21 @@ Routine Description:
}
}
+/**
+ Retrieve a quoted-string from the input file.
+
+ @param Str pointer to a copy of the quoted string parsed
+ @param Length size of buffer pointed to by Str
+
+ @retval TRUE next token in input stream was a quoted string, and
+ the string value was returned in Str
+ @retval FALSE otherwise
+**/
BOOLEAN
SFPGetQuotedString (
CHAR8 *Str,
INTN Length
)
-/*++
-
-Routine Description:
- Retrieve a quoted-string from the input file.
-
-Arguments:
- Str - pointer to a copy of the quoted string parsed
- Length - size of buffer pointed to by Str
-
-Returns:
- TRUE - next token in input stream was a quoted string, and
- the string value was returned in Str
- FALSE - otherwise
-
---*/
{
SkipWhiteSpace (&mGlobals.SourceFile);
if (EndOfFile (&mGlobals.SourceFile)) {
@@ -866,24 +777,17 @@ Routine Description:
return FALSE;
}
-BOOLEAN
-SFPIsEOF (
- VOID
- )
-/*++
-
-Routine Description:
+/**
Return TRUE of FALSE to indicate whether or not we've reached the end of the
file we're parsing.
-Arguments:
- NA
-
-Returns:
- TRUE - EOF reached
- FALSE - otherwise
-
---*/
+ @retval TRUE EOF reached
+ @retval FALSE otherwise
+**/
+BOOLEAN
+SFPIsEOF (
+ VOID
+ )
{
SkipWhiteSpace (&mGlobals.SourceFile);
return EndOfFile (&mGlobals.SourceFile);
@@ -1112,27 +1016,22 @@ SkipWhiteSpace (
return Count;
}
-STATIC
-UINTN
-t_strcmp (
- CHAR8 *Buffer,
- CHAR8 *Str
- )
-/*++
-
-Routine Description:
+/**
Compare two strings for equality. The string pointed to by 'Buffer' may or may not be null-terminated,
so only compare up to the length of Str.
-Arguments:
- Buffer - pointer to first (possibly not null-terminated) string
- Str - pointer to null-terminated string to compare to Buffer
+ @param Buffer pointer to first (possibly not null-terminated) string
+ @param Str pointer to null-terminated string to compare to Buffer
-Returns:
- Number of bytes matched if exact match
- 0 if Buffer does not start with Str
-
---*/
+ @retval Number of bytes matched if exact match
+ @retval 0 if Buffer does not start with Str
+**/
+STATIC
+UINTN
+t_strcmp (
+ CHAR8 *Buffer,
+ CHAR8 *Str
+ )
{
UINTN Len;
@@ -1245,28 +1144,23 @@ GetHexChars (
return Len;
}
+/**
+ Parse a GUID from the input stream. Stop when you discover white space.
+
+ GUID styles
+ Style[0] 12345678-1234-5678-AAAA-BBBBCCCCDDDD
+
+ @param GuidStyle Style of the following GUID token
+ @param Value pointer to EFI_GUID struct for output
+
+ @retval TRUE GUID string parsed successfully
+ @retval FALSE otherwise
+**/
BOOLEAN
SFPGetGuid (
INTN GuidStyle,
EFI_GUID *Value
)
-/*++
-
-Routine Description:
- Parse a GUID from the input stream. Stop when you discover white space.
-
-Arguments:
- GuidStyle - Style of the following GUID token
- Value - pointer to EFI_GUID struct for output
-
-Returns:
- TRUE - GUID string parsed successfully
- FALSE - otherwise
-
- GUID styles
- Style[0] 12345678-1234-5678-AAAA-BBBBCCCCDDDD
-
---*/
{
INT32 Value32;
UINT32 Index;
diff --git a/BaseTools/Source/C/Common/StringFuncs.c b/BaseTools/Source/C/Common/StringFuncs.c
index 50573fdf0999..bc85ba012440 100644
--- a/BaseTools/Source/C/Common/StringFuncs.c
+++ b/BaseTools/Source/C/Common/StringFuncs.c
@@ -14,25 +14,17 @@ SPDX-License-Identifier: BSD-2-Clause-Patent
// Functions implementations
//
-CHAR8*
-CloneString (
- IN CHAR8 *String
- )
-/*++
-
-Routine Description:
-
+/**
Allocates a new string and copies 'String' to clone it
-Arguments:
-
- String The string to clone
-
-Returns:
-
- CHAR8* - NULL if there are not enough resources
-
---*/
+ @param String The string to clone
+
+ @return CHAR8* - NULL if there are not enough resources
+**/
+CHAR8*
+CloneString (
+ IN CHAR8 *String
+ )
{
CHAR8* NewString;
@@ -44,26 +36,17 @@ Routine Description:
return NewString;
}
-
-EFI_STATUS
-StripInfDscStringInPlace (
- IN CHAR8 *String
- )
-/*++
-
-Routine Description:
-
+/**
Remove all comments, leading and trailing whitespace from the string.
-Arguments:
-
- String The string to 'strip'
-
-Returns:
-
- EFI_STATUS
-
---*/
+ @param String The string to 'strip'
+
+ @return EFI_STATUS
+**/
+EFI_STATUS
+StripInfDscStringInPlace (
+ IN CHAR8 *String
+ )
{
CHAR8 *Pos;
@@ -110,27 +93,18 @@ Routine Description:
return EFI_SUCCESS;
}
-
-STRING_LIST*
-SplitStringByWhitespace (
- IN CHAR8 *String
- )
-/*++
-
-Routine Description:
-
+/**
Creates and returns a 'split' STRING_LIST by splitting the string
on whitespace boundaries.
-Arguments:
-
- String The string to 'split'
-
-Returns:
-
- EFI_STATUS
-
---*/
+ @param String The string to 'split'
+
+ @return EFI_STATUS
+**/
+STRING_LIST*
+SplitStringByWhitespace (
+ IN CHAR8 *String
+ )
{
CHAR8 *Pos;
CHAR8 *EndOfSubString;
@@ -172,21 +146,14 @@ Routine Description:
return Output;
}
-
-STRING_LIST*
-NewStringList (
- )
-/*++
-
-Routine Description:
-
+/**
Creates a new STRING_LIST with 0 strings.
-Returns:
-
- STRING_LIST* - Null if there is not enough resources to create the object.
-
---*/
+ @return STRING_LIST* - Null if there is not enough resources to create the object.
+**/
+STRING_LIST*
+NewStringList (
+ )
{
STRING_LIST *NewList;
NewList = AllocateStringListStruct (0);
@@ -196,24 +163,17 @@ Routine Description:
return NewList;
}
-
-EFI_STATUS
-AppendCopyOfStringToList (
- IN OUT STRING_LIST **StringList,
- IN CHAR8 *String
- )
-/*++
-
-Routine Description:
-
+/**
Adds String to StringList. A new copy of String is made before it is
added to StringList.
-Returns:
-
- EFI_STATUS
-
---*/
+ @return EFI_STATUS
+**/
+EFI_STATUS
+AppendCopyOfStringToList (
+ IN OUT STRING_LIST **StringList,
+ IN CHAR8 *String
+ )
{
STRING_LIST *OldList;
STRING_LIST *NewList;
@@ -245,27 +205,18 @@ Routine Description:
return EFI_SUCCESS;
}
-
-EFI_STATUS
-RemoveLastStringFromList (
- IN STRING_LIST *StringList
- )
-/*++
-
-Routine Description:
-
+/**
Removes the last string from StringList and frees the memory associated
with it.
-Arguments:
-
- StringList The string list to remove the string from
-
-Returns:
-
- EFI_STATUS
-
---*/
+ @param StringList The string list to remove the string from
+
+ @return EFI_STATUS
+**/
+EFI_STATUS
+RemoveLastStringFromList (
+ IN STRING_LIST *StringList
+ )
{
if (StringList->Count == 0) {
return EFI_INVALID_PARAMETER;
@@ -276,49 +227,30 @@ Routine Description:
return EFI_SUCCESS;
}
+/**
+ Allocates a STRING_LIST structure that can store StringCount strings.
+ @param StringCount The number of strings that need to be stored
+
+ @return EFI_STATUS
+**/
STRING_LIST*
AllocateStringListStruct (
IN UINTN StringCount
)
-/*++
-
-Routine Description:
-
- Allocates a STRING_LIST structure that can store StringCount strings.
-
-Arguments:
-
- StringCount The number of strings that need to be stored
-
-Returns:
-
- EFI_STATUS
-
---*/
{
return malloc (OFFSET_OF(STRING_LIST, Strings[StringCount + 1]));
}
-
-VOID
-FreeStringList (
- IN STRING_LIST *StringList
- )
-/*++
-
-Routine Description:
-
+/**
Frees all memory associated with StringList.
-Arguments:
-
- StringList The string list to free
-
-Returns:
-
- VOID
---*/
+ @param StringList The string list to free
+**/
+VOID
+FreeStringList (
+ IN STRING_LIST *StringList
+ )
{
while (StringList->Count > 0) {
RemoveLastStringFromList (StringList);
@@ -327,27 +259,18 @@ Routine Description:
free (StringList);
}
-
-CHAR8*
-StringListToString (
- IN STRING_LIST *StringList
- )
-/*++
-
-Routine Description:
-
+/**
Generates a string that represents the STRING_LIST
-Arguments:
+ @param StringList The string list to convert to a string
- StringList The string list to convert to a string
-
-Returns:
-
- CHAR8* - The string list represented with a single string. The returned
+ @return CHAR8* - The string list represented with a single string. The returned
string must be freed by the caller.
-
---*/
+**/
+CHAR8*
+StringListToString (
+ IN STRING_LIST *StringList
+ )
{
UINTN Count;
UINTN Length;
@@ -381,26 +304,17 @@ Routine Description:
return NewString;
}
-
-VOID
-PrintStringList (
- IN STRING_LIST *StringList
- )
-/*++
-
-Routine Description:
-
+/**
Prints out the string list
-Arguments:
-
- StringList The string list to print
-
-Returns:
-
- EFI_STATUS
-
---*/
+ @param StringList The string list to print
+
+ @return EFI_STATUS
+**/
+VOID
+PrintStringList (
+ IN STRING_LIST *StringList
+ )
{
CHAR8* String;
String = StringListToString (StringList);
diff --git a/BaseTools/Source/C/Common/TianoCompress.c b/BaseTools/Source/C/Common/TianoCompress.c
index 030cdca025b8..2f484b9731dc 100644
--- a/BaseTools/Source/C/Common/TianoCompress.c
+++ b/BaseTools/Source/C/Common/TianoCompress.c
@@ -256,6 +256,25 @@ STATIC NODE mPos, mMatchPos, mAvail, *mPosition, *mParent, *mPrev, *mNext = NU
//
// functions
//
+
+/**
+ The internal implementation of [Efi/Tiano]Compress().
+
+ @param SrcBuffer The buffer storing the source data
+ @param SrcSize The size of source data
+ @param DstBuffer The buffer to store the compressed data
+ @param DstSize On input, the size of DstBuffer; On output,
+ the size of the actual compressed data.
+ @param Version The version of de/compression algorithm.
+ Version 1 for UEFI 2.0 de/compression algorithm.
+ Version 2 for Tiano de/compression algorithm.
+
+ @retval EFI_BUFFER_TOO_SMALL The DstBuffer is too small. In this case,
+ DstSize contains the size needed.
+ @retval EFI_SUCCESS Compression is successful.
+ @retval EFI_OUT_OF_RESOURCES No resource to complete function.
+ @retval EFI_INVALID_PARAMETER Parameter supplied is wrong.
+**/
EFI_STATUS
TianoCompress (
IN UINT8 *SrcBuffer,
@@ -263,32 +282,6 @@ TianoCompress (
IN UINT8 *DstBuffer,
IN OUT UINT32 *DstSize
)
-/*++
-
-Routine Description:
-
- The internal implementation of [Efi/Tiano]Compress().
-
-Arguments:
-
- SrcBuffer - The buffer storing the source data
- SrcSize - The size of source data
- DstBuffer - The buffer to store the compressed data
- DstSize - On input, the size of DstBuffer; On output,
- the size of the actual compressed data.
- Version - The version of de/compression algorithm.
- Version 1 for UEFI 2.0 de/compression algorithm.
- Version 2 for Tiano de/compression algorithm.
-
-Returns:
-
- EFI_BUFFER_TOO_SMALL - The DstBuffer is too small. In this case,
- DstSize contains the size needed.
- EFI_SUCCESS - Compression is successful.
- EFI_OUT_OF_RESOURCES - No resource to complete function.
- EFI_INVALID_PARAMETER - Parameter supplied is wrong.
-
---*/
{
EFI_STATUS Status;
@@ -351,24 +344,16 @@ Routine Description:
}
-STATIC
-VOID
-PutDword (
- IN UINT32 Data
- )
-/*++
-
-Routine Description:
-
+/**
Put a dword to output stream
-Arguments:
-
- Data - the dword to put
-
-Returns: (VOID)
-
---*/
+ @param Data the dword to put
+**/
+STATIC
+VOID
+PutDword (
+ IN UINT32 Data
+ )
{
if (mDst < mDstUpperLimit) {
*mDst++ = (UINT8) (((UINT8) (Data)) & 0xff);
@@ -387,26 +372,17 @@ Returns: (VOID)
}
}
-STATIC
-EFI_STATUS
-AllocateMemory (
- VOID
- )
-/*++
-
-Routine Description:
-
+/**
Allocate memory spaces for data structures used in compression process
-Arguments:
+ @retval EFI_SUCCESS Memory is allocated successfully
+ @retval EFI_OUT_OF_RESOURCES Allocation fails
+**/
+STATIC
+EFI_STATUS
+AllocateMemory (
VOID
-
-Returns:
-
- EFI_SUCCESS - Memory is allocated successfully
- EFI_OUT_OF_RESOURCES - Allocation fails
-
---*/
+ )
{
UINT32 Index;
@@ -445,21 +421,13 @@ Routine Description:
return EFI_SUCCESS;
}
-VOID
-FreeMemory (
- VOID
- )
-/*++
-
-Routine Description:
-
+/**
Called when compression is completed to free memory previously allocated.
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+VOID
+FreeMemory (
+ VOID
+ )
{
if (mText != NULL) {
free (mText);
@@ -496,22 +464,14 @@ Returns: (VOID)
return ;
}
-STATIC
-VOID
-InitSlide (
- VOID
- )
-/*++
-
-Routine Description:
-
+/**
Initialize String Info Log data structures
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+InitSlide (
+ VOID
+ )
{
NODE Index;
@@ -535,28 +495,20 @@ Returns: (VOID)
}
}
-STATIC
-NODE
-Child (
- IN NODE NodeQ,
- IN UINT8 CharC
- )
-/*++
-
-Routine Description:
-
+/**
Find child node given the parent node and the edge character
-Arguments:
-
- NodeQ - the parent node
- CharC - the edge character
-
-Returns:
-
- The child node (NIL if not found)
-
---*/
+ @param NodeQ the parent node
+ @param CharC the edge character
+
+ @return The child node (NIL if not found)
+**/
+STATIC
+NODE
+Child (
+ IN NODE NodeQ,
+ IN UINT8 CharC
+ )
{
NODE NodeR;
@@ -572,6 +524,13 @@ Routine Description:
return NodeR;
}
+/**
+ Create a new child for a given parent node.
+
+ @param Parent the parent node
+ @param CharC the edge character
+ @param Child the child node
+**/
STATIC
VOID
MakeChild (
@@ -579,21 +538,6 @@ MakeChild (
IN UINT8 CharC,
IN NODE Child
)
-/*++
-
-Routine Description:
-
- Create a new child for a given parent node.
-
-Arguments:
-
- Parent - the parent node
- CharC - the edge character
- Child - the child node
-
-Returns: (VOID)
-
---*/
{
NODE Node1;
NODE Node2;
@@ -608,24 +552,16 @@ Returns: (VOID)
mChildCount[Parent]++;
}
-STATIC
-VOID
-Split (
- NODE Old
- )
-/*++
-
-Routine Description:
-
+/**
Split a node.
-Arguments:
-
- Old - the node to split
-
-Returns: (VOID)
-
---*/
+ @param Old the node to split
+**/
+STATIC
+VOID
+Split (
+ NODE Old
+ )
{
NODE New;
NODE TempNode;
@@ -646,22 +582,14 @@ Returns: (VOID)
MakeChild (New, mText[mPos + mMatchLen], mPos);
}
-STATIC
-VOID
-InsertNode (
- VOID
- )
-/*++
-
-Routine Description:
-
+/**
Insert string info for current position into the String Info Log
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+InsertNode (
+ VOID
+ )
{
NODE NodeQ;
NODE NodeR;
@@ -778,23 +706,15 @@ Returns: (VOID)
}
-STATIC
-VOID
-DeleteNode (
- VOID
- )
-/*++
-
-Routine Description:
-
+/**
Delete outdated string info. (The Usage of PERC_FLAG
ensures a clean deletion)
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+DeleteNode (
+ VOID
+ )
{
NODE NodeQ;
NODE NodeR;
@@ -873,23 +793,15 @@ Returns: (VOID)
mAvail = NodeR;
}
-STATIC
-VOID
-GetNextMatch (
- VOID
- )
-/*++
-
-Routine Description:
-
+/**
Advance the current position (read in new data if needed).
Delete outdated string info. Find a match string for current position.
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+GetNextMatch (
+ VOID
+ )
{
INT32 Number;
@@ -906,25 +818,17 @@ Returns: (VOID)
InsertNode ();
}
-STATIC
-EFI_STATUS
-Encode (
- VOID
- )
-/*++
-
-Routine Description:
-
+/**
The main controlling routine for compression process.
-Arguments: (VOID)
-
-Returns:
-
- EFI_SUCCESS - The compression is successful
- EFI_OUT_0F_RESOURCES - Not enough memory for compression process
-
---*/
+ @retval EFI_SUCCESS The compression is successful
+ @retval EFI_OUT_0F_RESOURCES Not enough memory for compression process
+**/
+STATIC
+EFI_STATUS
+Encode (
+ VOID
+ )
{
EFI_STATUS Status;
INT32 LastMatchLen;
@@ -996,22 +900,14 @@ Arguments: (VOID)
return EFI_SUCCESS;
}
-STATIC
-VOID
-CountTFreq (
- VOID
- )
-/*++
-
-Routine Description:
-
+/**
Count the frequencies for the Extra Set
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+CountTFreq (
+ VOID
+ )
{
INT32 Index;
INT32 Index3;
@@ -1053,28 +949,20 @@ Returns: (VOID)
}
}
-STATIC
-VOID
-WritePTLen (
- IN INT32 Number,
- IN INT32 nbit,
- IN INT32 Special
- )
-/*++
-
-Routine Description:
-
+/**
Outputs the code length array for the Extra Set or the Position Set.
-Arguments:
-
- Number - the number of symbols
- nbit - the number of bits needed to represent 'n'
- Special - the special symbol that needs to be take care of
-
-Returns: (VOID)
-
---*/
+ @param Number the number of symbols
+ @param nbit the number of bits needed to represent 'n'
+ @param Special the special symbol that needs to be take care of
+**/
+STATIC
+VOID
+WritePTLen (
+ IN INT32 Number,
+ IN INT32 nbit,
+ IN INT32 Special
+ )
{
INT32 Index;
INT32 Index3;
@@ -1103,22 +991,14 @@ Returns: (VOID)
}
}
-STATIC
-VOID
-WriteCLen (
- VOID
- )
-/*++
-
-Routine Description:
-
+/**
Outputs the code length array for Char&Length Set
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
+**/
+STATIC
+VOID
+WriteCLen (
+ VOID
+ )
{
INT32 Index;
INT32 Index3;
@@ -1193,24 +1073,14 @@ EncodeP (
}
}
-STATIC
-VOID
-SendBlock (
- VOID
- )
-/*++
-
-Routine Description:
-
+/**
Huffman code the block and output it.
-
-Arguments:
- (VOID)
-
-Returns:
- (VOID)
-
---*/
+**/
+STATIC
+VOID
+SendBlock (
+ VOID
+ )
{
UINT32 Index;
UINT32 Index2;
@@ -1281,26 +1151,18 @@ Routine Description:
}
}
+/**
+ Outputs an Original Character or a Pointer
+
+ @param CharC The original character or the 'String Length' element of a Pointer
+ @param Pos The 'Position' field of a Pointer
+**/
STATIC
VOID
Output (
IN UINT32 CharC,
IN UINT32 Pos
)
-/*++
-
-Routine Description:
-
- Outputs an Original Character or a Pointer
-
-Arguments:
-
- CharC - The original character or the 'String Length' element of a Pointer
- Pos - The 'Position' field of a Pointer
-
-Returns: (VOID)
-
---*/
{
STATIC UINT32 CPos;
@@ -1399,26 +1261,18 @@ MakeCrcTable (
}
}
-STATIC
-VOID
-PutBits (
- IN INT32 Number,
- IN UINT32 Value
- )
-/*++
-
-Routine Description:
-
+/**
Outputs rightmost n bits of x
-
-Arguments:
-
- Number - the rightmost n bits of the data is used
- x - the data
-
-Returns: (VOID)
-
---*/
+
+ @param Number the rightmost n bits of the data is used
+ @param x the data
+**/
+STATIC
+VOID
+PutBits (
+ IN INT32 Number,
+ IN UINT32 Value
+ )
{
UINT8 Temp;
@@ -1439,28 +1293,20 @@ Returns: (VOID)
mSubBitBuf |= Value << (mBitCount -= Number);
}
-STATIC
-INT32
-FreadCrc (
- OUT UINT8 *Pointer,
- IN INT32 Number
- )
-/*++
-
-Routine Description:
-
+/**
Read in source data
-Arguments:
-
- Pointer - the buffer to hold the data
- Number - number of bytes to read
-
-Returns:
-
- number of bytes actually read
-
---*/
+ @param Pointer - the buffer to hold the data
+ @param Number - number of bytes to read
+
+ @return number of bytes actually read
+**/
+STATIC
+INT32
+FreadCrc (
+ OUT UINT8 *Pointer,
+ IN INT32 Number
+ )
{
INT32 Index;
@@ -1491,24 +1337,16 @@ InitPutBits (
mSubBitBuf = 0;
}
-STATIC
-VOID
-CountLen (
- IN INT32 Index
- )
-/*++
-
-Routine Description:
-
+/**
Count the number of each code length for a Huffman tree.
-Arguments:
-
- Index - the top node
-
-Returns: (VOID)
-
---*/
+ @param Index the top node
+**/
+STATIC
+VOID
+CountLen (
+ IN INT32 Index
+ )
{
STATIC INT32 Depth = 0;
@@ -1522,26 +1360,16 @@ Returns: (VOID)
}
}
-STATIC
-VOID
-MakeLen (
- IN INT32 Root
- )
-/*++
-
-Routine Description:
-
+/**
Create code length array for a Huffman tree
-Arguments:
-
- Root - the root of the tree
-
-Returns:
-
- VOID
-
---*/
+ @param Root the root of the tree
+**/
+STATIC
+VOID
+MakeLen (
+ IN INT32 Root
+ )
{
INT32 Index;
INT32 Index3;
@@ -1616,28 +1444,20 @@ DownHeap (
mHeap[Index] = (INT16) Index3;
}
-STATIC
-VOID
-MakeCode (
- IN INT32 Number,
- IN UINT8 Len[ ],
- OUT UINT16 Code[]
- )
-/*++
-
-Routine Description:
-
+/**
Assign code to each symbol based on the code length array
-Arguments:
-
- Number - number of symbols
- Len - the code length array
- Code - stores codes for each symbol
-
-Returns: (VOID)
-
---*/
+ @param Number number of symbols
+ @param Len the code length array
+ @param Code stores codes for each symbol
+**/
+STATIC
+VOID
+MakeCode (
+ IN INT32 Number,
+ IN UINT8 Len[ ],
+ OUT UINT16 Code[]
+ )
{
INT32 Index;
UINT16 Start[18];
@@ -1652,32 +1472,24 @@ Returns: (VOID)
}
}
-STATIC
-INT32
-MakeTree (
- IN INT32 NParm,
- IN UINT16 FreqParm[],
- OUT UINT8 LenParm[ ],
- OUT UINT16 CodeParm[]
- )
-/*++
-
-Routine Description:
-
+/**
Generates Huffman codes given a frequency distribution of symbols
-Arguments:
-
- NParm - number of symbols
- FreqParm - frequency of each symbol
- LenParm - code length for each symbol
- CodeParm - code for each symbol
-
-Returns:
-
- Root of the Huffman tree.
-
---*/
+ @param NParm number of symbols
+ @param FreqParm frequency of each symbol
+ @param LenParm code length for each symbol
+ @param CodeParm code for each symbol
+
+ @return Root of the Huffman tree.
+**/
+STATIC
+INT32
+MakeTree (
+ IN INT32 NParm,
+ IN UINT16 FreqParm[],
+ OUT UINT8 LenParm[ ],
+ OUT UINT16 CodeParm[]
+ )
{
INT32 Index;
INT32 Index2;
--
2.37.1 (Apple Git-137.1)
next prev parent reply other threads:[~2023-02-25 0:54 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-02-25 0:54 [PATCH 0/3] BaseTools: Fix doc block location and formatting; run uncrustify Rebecca Cran
2023-02-25 0:54 ` Rebecca Cran [this message]
2023-02-25 0:54 ` [PATCH 2/3] BaseTools: Replace duplicate __PcdSet prototype with __PcdGet Rebecca Cran
2023-03-23 17:06 ` Rebecca Cran
2023-03-24 4:55 ` 回复: " gaoliming
2023-02-25 0:54 ` [PATCH 3/3] BaseTools: Run Uncrustify over files in Source/C/Common Rebecca Cran
[not found] ` <1746EB2C4B4E3528.29542@groups.io>
2023-03-09 15:43 ` [edk2-devel] [PATCH 1/3] BaseTools: Source/C/Common: Fix doc block locations and convert to Doxygen Rebecca Cran
2023-03-10 2:57 ` 回复: [PATCH 0/3] BaseTools: Fix doc block location and formatting; run uncrustify gaoliming
2023-03-10 17:57 ` Rebecca Cran
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-list from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230225005431.12173-2-rebecca@bsdio.com \
--to=devel@edk2.groups.io \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox