[edk2-devel] [PATCH 1/3] BaseTools: Source/C/Common: Fix doc block locations and convert to Doxygen
Rebecca Cran
rebecca at bsdio.com
Thu Mar 9 15:43:16 UTC 2023
Could I get some reviews of this please?
Patch 3/3 can be dropped since Uncrustify doesn't run on BaseTools.
--
Rebecca Cran
On 2/24/23 5:54 PM, Rebecca Cran wrote:
> 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 at 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;
-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#100955): https://edk2.groups.io/g/devel/message/100955
Mute This Topic: https://groups.io/mt/97498547/1813853
Group Owner: devel+owner at edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [edk2-devel-archive at redhat.com]
-=-=-=-=-=-=-=-=-=-=-=-
More information about the edk2-devel-archive
mailing list