From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from out5-smtp.messagingengine.com (out5-smtp.messagingengine.com [66.111.4.29]) by mx.groups.io with SMTP id smtpd.web11.16752.1678376600553947325 for ; Thu, 09 Mar 2023 07:43:21 -0800 Authentication-Results: mx.groups.io; dkim=fail reason="signature has expired" header.i=@bsdio.com header.s=fm2 header.b=EEHvCDik; spf=pass (domain: bsdio.com, ip: 66.111.4.29, mailfrom: rebecca@bsdio.com) Received: from compute4.internal (compute4.nyi.internal [10.202.2.44]) by mailout.nyi.internal (Postfix) with ESMTP id D46FB5C016A; Thu, 9 Mar 2023 10:43:19 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute4.internal (MEProxy); Thu, 09 Mar 2023 10:43:19 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bsdio.com; h=cc :content-transfer-encoding:content-type:content-type:date:date :from:from:in-reply-to:in-reply-to:message-id:mime-version :references:reply-to:sender:subject:subject:to:to; s=fm2; t= 1678376599; x=1678462999; bh=97n2kRvrM/HL1nbG+dumF0eDp7AgIY3vYAx n8i5JckU=; b=EEHvCDik9Wkwui1TzIpMvpUe/06rsLwlT1bg4TESW9I4OoaubwP 9yc32LtLQSly3fOC2oeJBiWjg840Mk8cv6whloE1rhJNJ2q+lkumoHc71y8jkuIf CUA4Aq18uPZ2dffzM8bmQAS4dQJZMRBIVdBIx32XJMvgfBM40Kr7Ng8qRahjU7ur eUVj+E7WZKCSriobITG+p8/7XjgwYiAmaI2igdCuI8OgzwyYwJkQ6pJ+VvJipe2R BGhbktaFgzh94wtAtxyWUjwFmtLZsIlZkCtnuQauhb4ZdW/aOUeBNiCd0Osp5RaL lIWTeFBhSeg4fI3PW6WDqDXu+PS2PvAHVuw== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :content-type:date:date:feedback-id:feedback-id:from:from :in-reply-to:in-reply-to:message-id:mime-version:references :reply-to:sender:subject:subject:to:to:x-me-proxy:x-me-proxy :x-me-sender:x-me-sender:x-sasl-enc; s=fm1; t=1678376599; x= 1678462999; bh=97n2kRvrM/HL1nbG+dumF0eDp7AgIY3vYAxn8i5JckU=; b=X GpIgmqtR7mISOPyQC8ZbQN+NfI2GfOo3H91nQVZNSEgXRQ3i0zLmDrM/rLa4iPH9 8BwQifGeQ2GX1LU4Ypg/TTjzKCk6Hik2hTRzymegI1J6kVSkSZsJU1YnWx9YRRV6 Xs5cgxfqiO+q50z6ZtEDYAC6lWuN4sqAHnNZNVarColC1zKDuVgvMvh+ZwfJH1RS +Std0RkhFILI1DPmIX5CCl4y6wvsIxhtXWUhU0dmiivW6tiORSu0dm/iRDmMmVer S90xCrUkMfQ661MOaj2SkeUQkadY2iGaY7s+tRjbVtgsK6Sg9tAzb21fQU3NLiS8 EwdaNC9KL9t4vCU12gUAQ== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvhedrvdduiedgjeekucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhepkfffgggfuffvfhfhjggtgfesthejredttdefjeenucfhrhhomheptfgvsggv tggtrgcuvehrrghnuceorhgvsggvtggtrgessghsughiohdrtghomheqnecuggftrfgrth htvghrnhepleduvedtledtvedvuedugeeuudeiiedtueduvdffueekfeejffduvdetjeev ffdvnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomheprh gvsggvtggtrgessghsughiohdrtghomh X-ME-Proxy: Feedback-ID: i5b994698:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Thu, 9 Mar 2023 10:43:18 -0500 (EST) Message-ID: <7c8d1eda-f30d-f1ee-dedf-aaf19d6b6dd1@bsdio.com> Date: Thu, 9 Mar 2023 08:43:16 -0700 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:102.0) Gecko/20100101 Thunderbird/102.8.0 Subject: Re: [edk2-devel] [PATCH 1/3] BaseTools: Source/C/Common: Fix doc block locations and convert to Doxygen To: devel@edk2.groups.io, Bob Feng , Liming Gao , Yuwei Chen References: <20230225005431.12173-1-rebecca@bsdio.com> <1746EB2C4B4E3528.29542@groups.io> From: "Rebecca Cran" In-Reply-To: <1746EB2C4B4E3528.29542@groups.io> Content-Language: en-US Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit 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 > --- > 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 > -/*++ > - > -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 > > +/** > + 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 > > -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: > + () : : : > + > + 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: > - () : : : > - > - 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 -o \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;