diff options
| author | Rebecca Cran <rebecca@bsdio.com> | 2023-02-19 23:21:43 -0700 |
|---|---|---|
| committer | mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> | 2023-03-24 14:52:14 +0000 |
| commit | b4e2cf092a2179ff693e24b12281ee99d230e031 (patch) | |
| tree | 5d1f9f07c1b3996ee4012c0f7572bb2a6c8362d9 /BaseTools | |
| parent | cf6a0a52b07195ba278e48b89cfb7ddbad332ab1 (diff) | |
| download | edk2-b4e2cf092a2179ff693e24b12281ee99d230e031.tar.gz edk2-b4e2cf092a2179ff693e24b12281ee99d230e031.tar.bz2 edk2-b4e2cf092a2179ff693e24b12281ee99d230e031.zip | |
BaseTools: Source/C/Common: Fix doc block locations and convert to Doxygen
Move the documentation blocks from between the parameter list and function
body to above the function.
Convert all the documentation blocks to Doxygen format.
Signed-off-by: Rebecca Cran <rebecca@bsdio.com>
Reviewed-by: Liming Gao <gaoliming@byosoft.com.cn>
Diffstat (limited to 'BaseTools')
29 files changed, 2072 insertions, 4065 deletions
diff --git a/BaseTools/Source/C/Common/BasePeCoff.c b/BaseTools/Source/C/Common/BasePeCoff.c index 30400d1341..b8bfb7b58b 100644 --- a/BaseTools/Source/C/Common/BasePeCoff.c +++ b/BaseTools/Source/C/Common/BasePeCoff.c @@ -77,6 +77,16 @@ PeCoffLoaderRelocateLoongArch64Image ( IN UINT64 Adjust
);
+/**
+ Retrieves the PE or TE Header from a PE/COFF or TE image
+
+ @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
+
+ @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 (
@@ -84,26 +94,6 @@ PeCoffLoaderGetPeHeader ( 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:
-
- 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,
- Otherwise, the error status from reading the PE/COFF or TE image using the ImageRead function.
-
---*/
{
RETURN_STATUS Status;
EFI_IMAGE_DOS_HEADER DosHdr;
@@ -150,6 +140,17 @@ Returns: 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 @@ Returns: 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 @@ Returns: return RETURN_SUCCESS;
}
+/**
+ Converts an image address to the loaded address
+
+ @param ImageContext The context of the image being loaded
+ @param Address The address to be converted to the loaded 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
)
-/*++
-
-Routine Description:
-
- Converts an image address to the loaded address
-
-Arguments:
-
- 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
-
---*/
{
if (Address >= ImageContext->ImageSize) {
ImageContext->ImageError = IMAGE_ERROR_INVALID_IMAGE_ADDRESS;
@@ -571,30 +537,22 @@ Returns: return (UINT8 *) ((UINTN) ImageContext->ImageAddress + Address);
}
+/**
+ Relocates a PE/COFF image in memory
+
+ @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
)
-/*++
-
-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
-
---*/
{
RETURN_STATUS Status;
EFI_IMAGE_OPTIONAL_HEADER_UNION *PeHdr;
@@ -853,31 +811,23 @@ Returns: return RETURN_SUCCESS;
}
+/**
+ Loads a PE/COFF image into memory
+
+ @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
)
-/*++
-
-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
-
---*/
{
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 7fb4ab764f..b2cde6d481 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)
+/**
+ Set Buffer to zero for Size bytes.
+
+ @param Buffer Memory to set.
+ @param Size Number of bytes to set
+**/
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
-
---*/
{
INT8 *Ptr;
@@ -57,31 +46,19 @@ Returns: }
}
+/**
+ Copy Length bytes from Source to Destination.
+
+ @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
)
-/*++
-
-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
-
---*/
{
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 @@ Returns: 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 @@ Returns: 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 @@ Returns: 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 @@ Returns: return Sum;
}
+/**
+ This function calculates the value needed for a valid UINT16 checksum
+
+ @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
)
-/*++
-
-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.
-
---*/
{
return (UINT16) (0x10000 - CalculateSum16 (Buffer, Size));
}
+/**
+ This function calculates the UINT16 sum for the requested region.
+
+ @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
)
-/*++
-
-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
-
---*/
{
UINTN Index;
UINT16 Sum;
@@ -444,26 +365,18 @@ Returns: 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 @@ Returns: 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__
//
@@ -2188,4 +2088,3 @@ SplitStr ( *List = Str;
return ReturnStr;
}
-
diff --git a/BaseTools/Source/C/Common/CommonLib.h b/BaseTools/Source/C/Common/CommonLib.h index 0f05d88db2..a841029c2a 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 @@ Returns: 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 40255a9665..499e183c2b 100644 --- a/BaseTools/Source/C/Common/Compress.h +++ b/BaseTools/Source/C/Common/Compress.h @@ -15,13 +15,10 @@ SPDX-License-Identifier: BSD-2-Clause-Patent #include "CommonLib.h"
#include <Common/UefiBaseTypes.h>
-/*++
-
-Routine Description:
+/**
Tiano compression routine.
-
---*/
+**/
EFI_STATUS
TianoCompress (
IN UINT8 *SrcBuffer,
@@ -31,13 +28,9 @@ TianoCompress ( )
;
-/*++
-
-Routine Description:
-
+/**
Efi compression routine.
-
---*/
+**/
EFI_STATUS
EfiCompress (
IN UINT8 *SrcBuffer,
@@ -47,29 +40,21 @@ EfiCompress ( )
;
-/*++
-
-Routine Description:
-
+/**
The compression routine.
-Arguments:
-
- 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.
+ @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.
-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.c b/BaseTools/Source/C/Common/Crc32.c index 7281d5f0e9..00cae94898 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/Crc32.h b/BaseTools/Source/C/Common/Crc32.h index 61f99b96b5..3f6b5b35fc 100644 --- a/BaseTools/Source/C/Common/Crc32.h +++ b/BaseTools/Source/C/Common/Crc32.h @@ -11,31 +11,23 @@ SPDX-License-Identifier: BSD-2-Clause-Patent #include <Common/UefiBaseTypes.h>
+/**
+ The CalculateCrc32 routine.
+
+ @param Data The buffer containing the data to be processed
+ @param DataSize The size of data to be processed
+ @param CrcOut A pointer to the caller allocated UINT32 that on
+ contains the CRC32 checksum of Data
+
+ @retval EFI_SUCCESS - Calculation is successful.
+ @retval EFI_INVALID_PARAMETER - Data / CrcOut = NULL, or DataSize = 0
+**/
EFI_STATUS
CalculateCrc32 (
IN UINT8 *Data,
IN UINTN DataSize,
IN OUT UINT32 *CrcOut
)
-/*++
-
-Routine Description:
-
- The CalculateCrc32 routine.
-
-Arguments:
-
- Data - The buffer containing the data to be processed
- DataSize - The size of data to be processed
- CrcOut - A pointer to the caller allocated UINT32 that on
- contains the CRC32 checksum of Data
-
-Returns:
-
- EFI_SUCCESS - Calculation is successful.
- EFI_INVALID_PARAMETER - Data / CrcOut = NULL, or DataSize = 0
-
---*/
;
#endif
diff --git a/BaseTools/Source/C/Common/Decompress.c b/BaseTools/Source/C/Common/Decompress.c index d85098f131..a0f54c0834 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;
+/**
+ Shift mBitBuf NumOfBits left. Read in NumOfBits of bits from source.
+
+ @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
)
-/*++
-
-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)
-
---*/
{
Sd->mBitBuf = (UINT32) (((UINT64)Sd->mBitBuf) << NumOfBits);
@@ -112,30 +104,22 @@ Returns: (VOID) Sd->mBitBuf |= Sd->mSubBitBuf >> Sd->mBitCount;
}
+/**
+ Get NumOfBits of bits out from mBitBuf. Fill mBitBuf with subsequent
+ NumOfBits of bits from source. Returns NumOfBits of 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
)
-/*++
-
-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.
-
---*/
{
UINT32 OutBits;
@@ -146,6 +130,18 @@ Returns: 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 @@ Returns: 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 @@ Returns: 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 @@ Returns: return MakeTable (Sd, nn, Sd->mPTLen, 8, Sd->mPTTable);
}
+/**
+ Reads code lengths for Char&Len Set.
+
+ @param Sd the global scratch data
+**/
STATIC
VOID
ReadCLen (
SCRATCH_DATA *Sd
)
-/*++
-
-Routine Description:
-
- Reads code lengths for Char&Len Set.
-
-Arguments:
-
- Sd - the global scratch data
-
-Returns: (VOID)
-
---*/
{
UINT16 Number;
UINT16 CharC;
@@ -526,26 +478,18 @@ Returns: (VOID) return ;
}
+/**
+ Decode a character/length value.
+
+ @param Sd The global scratch data.
+
+ @return The value decoded.
+**/
STATIC
UINT16
DecodeC (
SCRATCH_DATA *Sd
)
-/*++
-
-Routine Description:
-
- Decode a character/length value.
-
-Arguments:
-
- Sd - The global scratch data.
-
-Returns:
-
- The value decoded.
-
---*/
{
UINT16 Index2;
UINT32 Mask;
@@ -592,24 +536,16 @@ Returns: return Index2;
}
+/**
+ Decode the source data and put the resulting data into the destination buffer.
+
+ @param Sd The global scratch data
+ **/
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)
-
- --*/
{
UINT16 BytesRemain;
UINT32 DataIdx;
@@ -669,6 +605,17 @@ Returns: (VOID) return ;
}
+/**
+ The implementation of EFI_DECOMPRESS_PROTOCOL.GetInfo().
+
+ @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,
@@ -676,25 +623,6 @@ GetInfo ( 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
-
---*/
{
UINT8 *Src;
UINT32 CompSize;
@@ -716,6 +644,19 @@ Returns: return EFI_SUCCESS;
}
+/**
+ The implementation Efi and Tiano Decompress().
+
+ @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
Decompress (
IN VOID *Source,
@@ -725,27 +666,6 @@ Decompress ( IN OUT VOID *Scratch,
IN UINT32 ScratchSize
)
-/*++
-
-Routine Description:
-
- The implementation Efi and 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
-
---*/
{
UINT32 Index;
UINT32 CompSize;
@@ -811,6 +731,17 @@ Returns: return Status;
}
+/**
+ The implementation Efi Decompress GetInfo().
+
+ @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
EfiGetInfo (
IN VOID *Source,
@@ -818,29 +749,21 @@ EfiGetInfo ( 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);
}
+/**
+ The implementation Tiano Decompress GetInfo().
+
+ @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 (
IN VOID *Source,
@@ -848,29 +771,23 @@ TianoGetInfo ( OUT UINT32 *DstSize,
OUT 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
-
---*/
{
return GetInfo (Source, SrcSize, DstSize, ScratchSize);
}
+/**
+ The implementation of Efi Decompress().
+
+ @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
EfiDecompress (
IN VOID *Source,
@@ -880,32 +797,24 @@ EfiDecompress ( IN OUT VOID *Scratch,
IN 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
-
---*/
{
mPbit = EFIPBIT;
return Decompress (Source, SrcSize, Destination, DstSize, Scratch, ScratchSize);
}
+/**
+ The implementation of Tiano Decompress().
+
+ @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,
@@ -915,27 +824,6 @@ TianoDecompress ( IN OUT VOID *Scratch,
IN 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
-
---*/
{
mPbit = MAXPBIT;
return Decompress (Source, SrcSize, Destination, DstSize, Scratch, ScratchSize);
diff --git a/BaseTools/Source/C/Common/Decompress.h b/BaseTools/Source/C/Common/Decompress.h index 983a27d8fc..00a1e31b8c 100644 --- a/BaseTools/Source/C/Common/Decompress.h +++ b/BaseTools/Source/C/Common/Decompress.h @@ -11,13 +11,6 @@ SPDX-License-Identifier: BSD-2-Clause-Patent #include <Common/UefiBaseTypes.h>
-EFI_STATUS
-EfiGetInfo (
- IN VOID *Source,
- IN UINT32 SrcSize,
- OUT UINT32 *DstSize,
- OUT UINT32 *ScratchSize
- );
/**
Routine Description:
@@ -37,7 +30,27 @@ Returns: EFI_INVALID_PARAMETER - The source data is corrupted
**/
+EFI_STATUS
+EfiGetInfo (
+ IN VOID *Source,
+ IN UINT32 SrcSize,
+ OUT UINT32 *DstSize,
+ OUT UINT32 *ScratchSize
+ );
+
+/**
+ The implementation of Efi Decompress().
+
+ @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
EfiDecompress (
IN VOID *Source,
@@ -47,28 +60,18 @@ EfiDecompress ( IN OUT VOID *Scratch,
IN 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:
+/**
+ The implementation Tiano Decompress GetInfo().
- 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 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 (
IN VOID *Source,
@@ -76,26 +79,20 @@ TianoGetInfo ( OUT UINT32 *DstSize,
OUT 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:
+/**
+ The implementation of Tiano Decompress().
- 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 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,
@@ -105,27 +102,6 @@ TianoDecompress ( IN OUT VOID *Scratch,
IN 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
-
-**/
typedef
EFI_STATUS
diff --git a/BaseTools/Source/C/Common/EfiCompress.c b/BaseTools/Source/C/Common/EfiCompress.c index db5ebe3157..0db958b853 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 @@ Returns: }
+/**
+ Put a dword to output stream
+
+ @param Data the dword to put
+**/
STATIC
VOID
PutDword(
IN UINT32 Data
)
-/*++
-
-Routine Description:
-
- Put a dword to output stream
-
-Arguments:
-
- Data - the dword to put
-
-Returns: (VOID)
-
---*/
{
if (mDst < mDstUpperLimit) {
*mDst++ = (UINT8)(((UINT8)(Data )) & 0xff);
@@ -381,23 +366,15 @@ Returns: (VOID) }
}
+/**
+ Allocate memory spaces for data structures used in compression process
+
+ @retval EFI_SUCCESS Memory is allocated successfully
+ @retva; EFI_OUT_OF_RESOURCES Allocation fails
+**/
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
-
---*/
{
UINT32 i;
@@ -432,19 +409,11 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Called when compression is completed to free memory previously allocated.
+**/
VOID
FreeMemory ()
-/*++
-
-Routine Description:
-
- Called when compression is completed to free memory previously allocated.
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
{
if (mText) {
free (mText);
@@ -481,21 +450,12 @@ Returns: (VOID) return;
}
-
+/**
+ Initialize String Info Log data structures
+**/
STATIC
VOID
InitSlide ()
-/*++
-
-Routine Description:
-
- Initialize String Info Log data structures
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
{
NODE i;
@@ -517,29 +477,20 @@ Returns: (VOID) }
}
+/**
+ Find child node given the parent node and the edge character
+
+ @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
)
-/*++
-
-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)
-
---*/
{
NODE r;
@@ -552,6 +503,13 @@ Returns: return r;
}
+/**
+ Create a new child for a given parent node.
+
+ @param q the parent node
+ @param c the edge character
+ @param r the child node
+**/
STATIC
VOID
MakeChild (
@@ -559,21 +517,6 @@ MakeChild ( 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)
-
---*/
{
NODE h, t;
@@ -587,24 +530,16 @@ Returns: (VOID) mChildCount[q]++;
}
+/**
+ Split a node.
+
+ @param Old the node to split
+**/
STATIC
VOID
Split (
NODE Old
)
-/*++
-
-Routine Description:
-
- Split a node.
-
-Arguments:
-
- Old - the node to split
-
-Returns: (VOID)
-
---*/
{
NODE New, t;
@@ -624,20 +559,12 @@ Returns: (VOID) MakeChild(New, mText[mPos + mMatchLen], mPos);
}
+/**
+ Insert string info for current position into the String Info Log
+**/
STATIC
VOID
InsertNode ()
-/*++
-
-Routine Description:
-
- Insert string info for current position into the String Info Log
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
{
NODE q, r, j, t;
UINT8 c, *t1, *t2;
@@ -739,21 +666,13 @@ Returns: (VOID) }
+/**
+ Delete outdated string info. (The Usage of PERC_FLAG
+ ensures a clean deletion)
+**/
STATIC
VOID
DeleteNode ()
-/*++
-
-Routine Description:
-
- Delete outdated string info. (The Usage of PERC_FLAG
- ensures a clean deletion)
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
{
NODE q, r, s, t, u;
@@ -813,21 +732,13 @@ Returns: (VOID) mAvail = r;
}
+/**
+ Advance the current position (read in new data if needed).
+ Delete outdated string info. Find a match string for current position.
+**/
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)
-
---*/
{
INT32 n;
@@ -842,23 +753,15 @@ Returns: (VOID) InsertNode();
}
+/**
+ The main controlling routine 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 ()
-/*++
-
-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
-
---*/
{
EFI_STATUS Status;
INT32 LastMatchLen;
@@ -920,20 +823,12 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Count the frequencies for the Extra Set
+**/
STATIC
VOID
CountTFreq ()
-/*++
-
-Routine Description:
-
- Count the frequencies for the Extra Set
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
{
INT32 i, k, n, Count;
@@ -969,6 +864,13 @@ Returns: (VOID) }
}
+/**
+ Outputs the code length array for the Extra Set or the Position Set.
+
+ @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 (
@@ -976,21 +878,6 @@ WritePTLen ( 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)
-
---*/
{
INT32 i, k;
@@ -1015,20 +902,12 @@ Returns: (VOID) }
}
+/**
+ Outputs the code length array for Char&Length Set
+**/
STATIC
VOID
WriteCLen ()
-/*++
-
-Routine Description:
-
- Outputs the code length array for Char&Length Set
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
{
INT32 i, k, n, Count;
@@ -1096,20 +975,12 @@ EncodeP ( }
}
+/**
+ Huffman code the block and output it.
+**/
STATIC
VOID
SendBlock ()
-/*++
-
-Routine Description:
-
- Huffman code the block and output it.
-
-Argument: (VOID)
-
-Returns: (VOID)
-
---*/
{
UINT32 i, k, Flags, Root, Pos, Size;
Flags = 0;
@@ -1164,27 +1035,18 @@ Returns: (VOID) }
}
+/**
+ Outputs an Original Character or a Pointer
+ @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
)
-/*++
-
-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)
-
---*/
{
STATIC UINT32 CPos;
@@ -1263,26 +1125,18 @@ MakeCrcTable () }
}
+/**
+ Outputs rightmost n bits of x
+
+ @param n the rightmost n bits of the data is used
+ @param x the data
+**/
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)
-
---*/
{
UINT8 Temp;
@@ -1311,28 +1165,20 @@ Returns: (VOID) }
}
+/**
+ Read in source data
+
+ @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
)
-/*++
-
-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
-
---*/
{
INT32 i;
@@ -1358,24 +1204,16 @@ InitPutBits () mSubBitBuf = 0;
}
+/**
+ Count the number of each code length for a Huffman tree.
+
+ @param i the top node
+**/
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)
-
---*/
{
STATIC INT32 Depth = 0;
@@ -1389,22 +1227,16 @@ Returns: (VOID) }
}
+/**
+ Create code length array for a Huffman tree
+
+ @param Root the root of the tree
+**/
STATIC
VOID
MakeLen (
IN INT32 Root
)
-/*++
-
-Routine Description:
-
- Create code length array for a Huffman tree
-
-Arguments:
-
- Root - the root of the tree
-
---*/
{
INT32 i, k;
UINT32 Cum;
@@ -1468,6 +1300,13 @@ DownHeap ( mHeap[i] = (INT16)k;
}
+/**
+ Assign code to each symbol based on the code length array
+
+ @param n number of symbols
+ @param Len the code length array
+ @param Code stores codes for each symbol
+**/
STATIC
VOID
MakeCode (
@@ -1475,21 +1314,6 @@ MakeCode ( 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)
-
---*/
{
INT32 i;
UINT16 Start[18];
@@ -1503,6 +1327,16 @@ Returns: (VOID) }
}
+/**
+ Generates Huffman codes given a frequency distribution of symbols
+
+ @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 (
@@ -1511,24 +1345,6 @@ MakeTree ( 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.
-
---*/
{
INT32 i, j, k, Avail;
diff --git a/BaseTools/Source/C/Common/EfiUtilityMsgs.c b/BaseTools/Source/C/Common/EfiUtilityMsgs.c index f8d2a40be1..faf354064c 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.
- FileName - name of the file or application. If not specified, then the
+ @note:
+ 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:"
+
+ @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,6 +121,14 @@ Notes: va_end (List);
}
+/**
+ Print a parser error, using the source file name and line number
+ set by a previous call to SetParserPosition().
+
+ @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,
@@ -134,21 +136,6 @@ ParserError ( 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
-
---*/
{
va_list List;
//
@@ -181,6 +168,14 @@ Returns: 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,6 +221,19 @@ Returns: // }
}
+/**
+ Print a warning message.
+
+ @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,
@@ -250,30 +243,6 @@ Warning ( 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.
-
---*/
{
va_list List;
@@ -313,6 +282,18 @@ Returns: 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 @@ Returns: 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.
-Arguments:
- 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.
+ @note:
+ If FileName == NULL then this utility will use the string passed into SetUtilityName().
- FileName - name of the file where the warning was detected, or the name
- of the application that detected the warning
+ LineNumber is only used if the caller is a parser, in which case FileName refers to the
+ file being parsed.
- LineNumber - the line number where the warning was detected (parsers).
- 0 should be specified if the utility is not a parser.
+ Text and MsgFmt are both optional, though it would be of little use calling this function with
+ them both NULL.
- MessageCode - an application-specific warning code that can be referenced in
- other documentation.
+ Output will typically be of the form:
+ <FileName>(<LineNumber>) : <Type> <Type[0]><MessageCode>: <Text> : <MsgFmt>
- Text - part of the message to print
+ 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
- MsgFmt - the format string for the message. Can contain formatting
+ @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.
+ @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 part of the message to print
+ @param MsgFmt the format string for the message. Can contain formatting
controls for use with varargs.
- List - the variable list.
-
-Returns:
- None.
-
-Notes:
- If FileName == NULL then this utility will use the string passed into SetUtilityName().
-
- LineNumber is only used if the caller is a parser, in which case FileName refers to the
- file being parsed.
-
- Text and MsgFmt are both optional, though it would be of little use calling this function with
- them both NULL.
-
- Output will typically be of the form:
- <FileName>(<LineNumber>) : <Type> <Type[0]><MessageCode>: <Text> : <MsgFmt>
-
- Parser (LineNumber != 0)
- VfrCompile.cpp(330) : error E2660: AddVfrDataStructField : function does not take 2 parameters
- Generic utility (LineNumber == 0)
- UtilityName : error E1234 : Text string : MsgFmt string and args
-
---*/
+ @param List the variable list.
+**/
+VOID
+PrintMessage (
+ CHAR8 *Type,
+ CHAR8 *FileName,
+ UINT32 LineNumber,
+ UINT32 MessageCode,
+ CHAR8 *Text,
+ CHAR8 *MsgFmt,
+ va_list List
+ )
{
CHAR8 Line[MAX_LINE_LEN];
CHAR8 Line2[MAX_LINE_LEN];
@@ -523,24 +470,19 @@ Notes: }
+/**
+ Print message into stdout.
+
+ @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
)
-/*++
-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.
---*/
{
CHAR8 Line[MAX_LINE_LEN];
//
@@ -552,51 +494,37 @@ Returns: }
}
+/**
+ 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 @@ Returns: }
}
-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;
}
+/**
+ Set the printing message Level. This is used by the PrintMsg() function
+ to determine when/if a message should be printed.
+
+ @param LogLevel 0~50 to specify the different level message.
+**/
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
-
---*/
{
mPrintLogLevel = LogLevel;
}
+/**
+ Print a verbose level message.
+
+ @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,
...
)
-/*++
-
-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
-
---*/
{
va_list List;
//
@@ -690,25 +597,18 @@ Returns: va_end (List);
}
+/**
+ Print a default level message.
+
+ @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,
...
)
-/*++
-
-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
-
---*/
{
va_list List;
//
@@ -723,25 +623,18 @@ Returns: va_end (List);
}
+/**
+ Print a key level message.
+
+ @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,
...
)
-/*++
-
-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
-
---*/
{
va_list List;
//
@@ -756,28 +649,21 @@ Returns: 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 ace26eb71c..40e068c303 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 @@ Returns: 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 @@ Returns: 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 @@ Returns: 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 @@ Returns: 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 @@ Returns: return 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!
+ @param 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.
+ @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
+FvBufExtend (
+ IN VOID **Fv,
+ IN UINTN Size
+ )
{
EFI_STATUS Status;
UINTN OldSize;
@@ -469,27 +416,17 @@ Returns: }
+/**
+ 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 @@ Returns: 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 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Adds a new FFS file
+
+ @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
)
-/*++
-
-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
-
---*/
{
EFI_FIRMWARE_VOLUME_HEADER *hdr = (EFI_FIRMWARE_VOLUME_HEADER*)Fv;
@@ -652,32 +570,23 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Adds a new FFS file. Extends the firmware volume if needed.
+
+ @param Fv Source and destination firmware volume.
+ Note: If the FV is extended, then 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
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
- 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;
EFI_FFS_FILE_HEADER* NewFile;
@@ -706,29 +615,20 @@ Returns: return Status;
}
+/**
+ Adds a new FFS VFT (Volume Top File) file. In other words, adds the
+ file to the end of the firmware volume.
+
+ @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
)
-/*++
-
-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
-
---*/
{
EFI_STATUS Status;
@@ -811,52 +711,35 @@ Returns: 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);
}
+/**
+ Get the FFS file size.
+
+ @param Ffs Pointer to FFS header
+
+ @return UINT32
+**/
UINT32
FvBufGetFfsFileSize (
IN EFI_FFS_FILE_HEADER *Ffs
)
-/*++
-
-Routine Description:
-
- Get the FFS file size.
-
-Arguments:
-
- Ffs - Pointer to FFS header
-
-Returns:
-
- UINT32
-
---*/
{
if (Ffs == NULL) {
return 0;
@@ -867,25 +750,17 @@ Returns: return FvBufExpand3ByteSize(Ffs->Size);
}
+/**
+ Get the FFS header size.
+
+ @param Ffs Pointer to FFS header
+
+ @return UINT32
+**/
UINT32
FvBufGetFfsHeaderSize (
IN EFI_FFS_FILE_HEADER *Ffs
)
-/*++
-
-Routine Description:
-
- Get the FFS header size.
-
-Arguments:
-
- Ffs - Pointer to FFS header
-
-Returns:
-
- UINT32
-
---*/
{
if (Ffs == NULL) {
return 0;
@@ -896,60 +771,44 @@ Returns: 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];
}
+/**
+ Iterates through the files contained within the firmware volume
+
+ @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
+
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+ @retval EFI_VOLUME_CORRUPTED
+**/
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
- File == NULL - invalid parameter
- otherwise - *File will be update to the location of the file
-
-Returns:
-
- EFI_SUCCESS
- EFI_NOT_FOUND
- EFI_VOLUME_CORRUPTED
-
---*/
{
EFI_FIRMWARE_VOLUME_HEADER *hdr = (EFI_FIRMWARE_VOLUME_HEADER*)Fv;
@@ -1028,35 +887,26 @@ Returns: return EFI_NOT_FOUND;
}
+/**
+ Searches the Fv for a file by its name
+ @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
+
+ @retval EFI_SUCCESS
+ @retval EFI_NOT_FOUND
+ @retval EFI_VOLUME_CORRUPTED
+**/
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
- 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
-
---*/
{
EFI_STATUS Status;
UINTN Key;
@@ -1080,35 +930,26 @@ Returns: return EFI_NOT_FOUND;
}
+/**
+ Searches the Fv for a file by its type
+
+ @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
+ @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
)
-/*++
-
-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
- (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
-
---*/
{
EFI_STATUS Status;
UINTN Key;
@@ -1132,34 +973,25 @@ Returns: 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 @@ Returns: }
+/**
+ 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 @@ Returns: 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 @@ Returns: }
+/**
+ 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 @@ Returns: 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 @@ Returns: return EFI_NOT_FOUND;
}
-
-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.
+ @param Fv Firmware volume.
-Returns:
-
- EFI_SUCCESS
-
---*/
+ @retval EFI_SUCCESS
+**/
+EFI_STATUS
+FvBufShrinkWrap (
+ IN VOID *Fv
+ )
{
EFI_STATUS Status;
UINTN OldSize;
@@ -1569,32 +1356,23 @@ Returns: }
+/**
+ 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 @@ Returns: return EFI_SUCCESS;
}
+/**
+ This function calculates the UINT16 sum for the requested region.
+
+ @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
)
-/*++
-
-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
-
---*/
{
UINTN Index;
UINT16 Sum;
@@ -1679,56 +1449,38 @@ Returns: return (UINT16) Sum;
}
+/**
+ This function calculates the value needed for a valid UINT16 checksum
+
+ @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
)
-/*++
-
-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.
-
---*/
{
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 @@ Return: return Sum;
}
+/**
+ 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.
+**/
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.
-
---*/
{
return (UINT8)(0x100 - FvBufCalculateSum8 (Buffer, Size));
}
diff --git a/BaseTools/Source/C/Common/FvLib.c b/BaseTools/Source/C/Common/FvLib.c index 82dc557bb7..37631f470f 100644 --- a/BaseTools/Source/C/Common/FvLib.c +++ b/BaseTools/Source/C/Common/FvLib.c @@ -22,29 +22,22 @@ UINT32 mFvLength = 0; //
// External function implementations
//
-EFI_STATUS
-InitializeFvLib (
- IN VOID *Fv,
- IN UINT32 FvLength
- )
-/*++
-
-Routine Description:
+/**
This initializes the FV lib with a pointer to the FV and length. It does not
verify the FV in any way.
-Arguments:
+ @param Fv Buffer containing the FV.
+ @param FvLength Length of the FV
- Fv Buffer containing the FV.
- FvLength Length of the FV
-
-Returns:
-
- EFI_SUCCESS Function Completed successfully.
- EFI_INVALID_PARAMETER A required parameter was NULL.
-
---*/
+ @retval EFI_SUCCESS Function Completed successfully.
+ @retval EFI_INVALID_PARAMETER A required parameter was NULL.
+**/
+EFI_STATUS
+InitializeFvLib (
+ IN VOID *Fv,
+ IN UINT32 FvLength
+ )
{
//
// Verify input arguments
@@ -59,29 +52,21 @@ Returns: return EFI_SUCCESS;
}
+/**
+ This function returns a pointer to the current FV and the size.
+
+ @param FvHeader Pointer to the FV buffer.
+ @param FvLength Length of the FV
+
+ @retval EFI_SUCCESS Function Completed successfully.
+ @retval EFI_INVALID_PARAMETER A required parameter was NULL.
+ @retvalEFI_ABORTED The library needs to be initialized.
+**/
EFI_STATUS
GetFvHeader (
OUT EFI_FIRMWARE_VOLUME_HEADER **FvHeader,
OUT UINT32 *FvLength
)
-/*++
-
-Routine Description:
-
- This function returns a pointer to the current FV and the size.
-
-Arguments:
-
- FvHeader Pointer to the FV buffer.
- FvLength Length of the FV
-
-Returns:
-
- EFI_SUCCESS Function Completed successfully.
- EFI_INVALID_PARAMETER A required parameter was NULL.
- EFI_ABORTED The library needs to be initialized.
-
---*/
{
//
// Verify library has been initialized.
@@ -101,31 +86,23 @@ Returns: return EFI_SUCCESS;
}
-EFI_STATUS
-GetNextFile (
- IN EFI_FFS_FILE_HEADER *CurrentFile,
- OUT EFI_FFS_FILE_HEADER **NextFile
- )
-/*++
-
-Routine Description:
-
+/**
This function returns the next file. If the current file is NULL, it returns
the first file in the FV. If the function returns EFI_SUCCESS and the file
pointer is NULL, then there are no more files in the FV.
-Arguments:
-
- CurrentFile Pointer to the current file, must be within the current FV.
- NextFile Pointer to the next file in the FV.
-
-Returns:
+ @param CurrentFile Pointer to the current file, must be within the current FV.
+ @param NextFile Pointer to the next file in the FV.
- EFI_SUCCESS Function completed successfully.
- EFI_INVALID_PARAMETER A required parameter was NULL or is out of range.
- EFI_ABORTED The library needs to be initialized.
-
---*/
+ @retval EFI_SUCCESS Function completed successfully.
+ @retval EFI_INVALID_PARAMETER A required parameter was NULL or is out of range.
+ @retval EFI_ABORTED The library needs to be initialized.
+**/
+EFI_STATUS
+GetNextFile (
+ IN EFI_FFS_FILE_HEADER *CurrentFile,
+ OUT EFI_FFS_FILE_HEADER **NextFile
+ )
{
EFI_STATUS Status;
@@ -214,29 +191,21 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Find a file by name. The function will return NULL if the file is not found.
+
+ @param FileName The GUID file name of the file to search for.
+ @param File Return pointer. In the case of an error, contents are undefined.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_ABORTED An error was encountered.
+ @retval EFI_INVALID_PARAMETER One of the parameters was NULL.
+**/
EFI_STATUS
GetFileByName (
IN EFI_GUID *FileName,
OUT EFI_FFS_FILE_HEADER **File
)
-/*++
-
-Routine Description:
-
- Find a file by name. The function will return NULL if the file is not found.
-
-Arguments:
-
- FileName The GUID file name of the file to search for.
- File Return pointer. In the case of an error, contents are undefined.
-
-Returns:
-
- EFI_SUCCESS The function completed successfully.
- EFI_ABORTED An error was encountered.
- EFI_INVALID_PARAMETER One of the parameters was NULL.
-
---*/
{
EFI_FFS_FILE_HEADER *CurrentFile;
EFI_STATUS Status;
@@ -295,33 +264,25 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Find a file by type and instance. An instance of 1 is the first instance.
+ The function will return NULL if a matching file cannot be found.
+ File type EFI_FV_FILETYPE_ALL means any file type is valid.
+
+ @param FileType Type of file to search for.
+ @param Instance Instance of the file type to return.
+ @param File Return pointer. In the case of an error, contents are undefined.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_ABORTED An error was encountered.
+ @retval EFI_INVALID_PARAMETER One of the parameters was NULL.
+**/
EFI_STATUS
GetFileByType (
IN EFI_FV_FILETYPE FileType,
IN UINTN Instance,
OUT EFI_FFS_FILE_HEADER **File
)
-/*++
-
-Routine Description:
-
- Find a file by type and instance. An instance of 1 is the first instance.
- The function will return NULL if a matching file cannot be found.
- File type EFI_FV_FILETYPE_ALL means any file type is valid.
-
-Arguments:
-
- FileType Type of file to search for.
- Instance Instance of the file type to return.
- File Return pointer. In the case of an error, contents are undefined.
-
-Returns:
-
- EFI_SUCCESS The function completed successfully.
- EFI_ABORTED An error was encountered.
- EFI_INVALID_PARAMETER One of the parameters was NULL.
-
---*/
{
EFI_FFS_FILE_HEADER *CurrentFile;
EFI_STATUS Status;
@@ -383,6 +344,23 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Helper function to search a sequence of sections from the section pointed
+ by FirstSection to SearchEnd for the Instance-th section of type SectionType.
+ The current counter is saved in StartIndex and when the section is found, it's
+ saved in Section. GUID-defined sections, if special processing is not required,
+ are searched recursively in a depth-first manner.
+
+ @param FirstSection The first section to start searching from.
+ @param SearchEnd The end address to stop search.
+ @param SectionType The type of section to search.
+ @param StartIndex The current counter is saved.
+ @param Instance The requested n-th section number.
+ @param Section The found section returned.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_NOT_FOUND The section is not found.
+**/
EFI_STATUS
SearchSectionByType (
IN EFI_FILE_SECTION_POINTER FirstSection,
@@ -392,30 +370,6 @@ SearchSectionByType ( IN UINTN Instance,
OUT EFI_FILE_SECTION_POINTER *Section
)
-/*++
-
-Routine Description:
-
- Helper function to search a sequence of sections from the section pointed
- by FirstSection to SearchEnd for the Instance-th section of type SectionType.
- The current counter is saved in StartIndex and when the section is found, it's
- saved in Section. GUID-defined sections, if special processing is not required,
- are searched recursively in a depth-first manner.
-
-Arguments:
-
- FirstSection The first section to start searching from.
- SearchEnd The end address to stop search.
- SectionType The type of section to search.
- StartIndex The current counter is saved.
- Instance The requested n-th section number.
- Section The found section returned.
-
-Returns:
-
- EFI_SUCCESS The function completed successfully.
- EFI_NOT_FOUND The section is not found.
---*/
{
EFI_FILE_SECTION_POINTER CurrentSection;
EFI_FILE_SECTION_POINTER InnerSection;
@@ -479,6 +433,22 @@ Returns: return EFI_NOT_FOUND;
}
+/**
+ Find a section in a file by type and instance. An instance of 1 is the first
+ instance. The function will return NULL if a matching section cannot be found.
+ GUID-defined sections, if special processing is not needed, are handled in a
+ depth-first manner.
+
+ @param File The file to search.
+ @param SectionType Type of file to search for.
+ @param Instance Instance of the section to return.
+ @param Section Return pointer. In the case of an error, contents are undefined.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_ABORTED An error was encountered.
+ @retval EFI_INVALID_PARAMETER One of the parameters was NULL.
+ @retval EFI_NOT_FOUND No found.
+**/
EFI_STATUS
GetSectionByType (
IN EFI_FFS_FILE_HEADER *File,
@@ -486,29 +456,6 @@ GetSectionByType ( IN UINTN Instance,
OUT EFI_FILE_SECTION_POINTER *Section
)
-/*++
-
-Routine Description:
-
- Find a section in a file by type and instance. An instance of 1 is the first
- instance. The function will return NULL if a matching section cannot be found.
- GUID-defined sections, if special processing is not needed, are handled in a
- depth-first manner.
-
-Arguments:
-
- File The file to search.
- SectionType Type of file to search for.
- Instance Instance of the section to return.
- Section Return pointer. In the case of an error, contents are undefined.
-
-Returns:
-
- EFI_SUCCESS The function completed successfully.
- EFI_ABORTED An error was encountered.
- EFI_INVALID_PARAMETER One of the parameters was NULL.
- EFI_NOT_FOUND No found.
---*/
{
EFI_FILE_SECTION_POINTER CurrentSection;
EFI_STATUS Status;
@@ -560,31 +507,25 @@ Returns: return EFI_NOT_FOUND;
}
}
+
//
// will not parse compressed sections
//
-EFI_STATUS
-VerifyFv (
- IN EFI_FIRMWARE_VOLUME_HEADER *FvHeader
- )
-/*++
-
-Routine Description:
+/**
Verify the current pointer points to a valid FV header.
-Arguments:
-
- FvHeader Pointer to an alleged FV file.
-
-Returns:
-
- EFI_SUCCESS The FV header is valid.
- EFI_VOLUME_CORRUPTED The FV header is not valid.
- EFI_INVALID_PARAMETER A required parameter was NULL.
- EFI_ABORTED Operation aborted.
+ @param FvHeader Pointer to an alleged FV file.
---*/
+ @retval EFI_SUCCESS The FV header is valid.
+ @retval EFI_VOLUME_CORRUPTED The FV header is not valid.
+ @retval EFI_INVALID_PARAMETER A required parameter was NULL.
+ @retval EFI_ABORTED Operation aborted.
+**/
+EFI_STATUS
+VerifyFv (
+ IN EFI_FIRMWARE_VOLUME_HEADER *FvHeader
+ )
{
UINT16 Checksum;
@@ -612,28 +553,20 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Verify the current pointer points to a FFS file header.
+
+ @param FfsHeader Pointer to an alleged FFS file.
+
+ @retval EFI_SUCCESS The Ffs header is valid.
+ @retval EFI_NOT_FOUND This "file" is the beginning of free space.
+ @retval EFI_VOLUME_CORRUPTED The Ffs header is not valid.
+ @retval EFI_ABORTED The erase polarity is not known.
+**/
EFI_STATUS
VerifyFfsFile (
IN EFI_FFS_FILE_HEADER *FfsHeader
)
-/*++
-
-Routine Description:
-
- Verify the current pointer points to a FFS file header.
-
-Arguments:
-
- FfsHeader Pointer to an alleged FFS file.
-
-Returns:
-
- EFI_SUCCESS The Ffs header is valid.
- EFI_NOT_FOUND This "file" is the beginning of free space.
- EFI_VOLUME_CORRUPTED The Ffs header is not valid.
- EFI_ABORTED The erase polarity is not known.
-
---*/
{
BOOLEAN ErasePolarity;
EFI_STATUS Status;
@@ -754,25 +687,17 @@ GetSectionHeaderLength( return sizeof(EFI_COMMON_SECTION_HEADER);
}
+/**
+ Get FFS file length including FFS header.
+
+ @param FfsHeader Pointer to EFI_FFS_FILE_HEADER.
+
+ @return UINT32 Length of FFS file header.
+**/
UINT32
GetFfsFileLength (
EFI_FFS_FILE_HEADER *FfsHeader
)
-/*++
-
-Routine Description:
-
- Get FFS file length including FFS header.
-
-Arguments:
-
- FfsHeader Pointer to EFI_FFS_FILE_HEADER.
-
-Returns:
-
- UINT32 Length of FFS file header.
-
---*/
{
if (FfsHeader == NULL) {
return 0;
@@ -800,25 +725,17 @@ GetSectionFileLength ( return Length;
}
+/**
+ Converts a three byte length value into a UINT32.
+
+ @param ThreeByteLength Pointer to the first of the 3 byte length.
+
+ @return UINT32 Size of the section
+**/
UINT32
GetLength (
UINT8 *ThreeByteLength
)
-/*++
-
-Routine Description:
-
- Converts a three byte length value into a UINT32.
-
-Arguments:
-
- ThreeByteLength Pointer to the first of the 3 byte length.
-
-Returns:
-
- UINT32 Size of the section
-
---*/
{
UINT32 Length;
@@ -832,28 +749,20 @@ Returns: return Length;
}
-EFI_STATUS
-GetErasePolarity (
- OUT BOOLEAN *ErasePolarity
- )
-/*++
-
-Routine Description:
-
+/**
This function returns with the FV erase polarity. If the erase polarity
for a bit is 1, the function return TRUE.
-Arguments:
-
- ErasePolarity A pointer to the erase polarity.
-
-Returns:
+ @param ErasePolarity A pointer to the erase polarity.
- EFI_SUCCESS The function completed successfully.
- EFI_INVALID_PARAMETER One of the input parameters was invalid.
- EFI_ABORTED Operation aborted.
-
---*/
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER One of the input parameters was invalid.
+ @retval EFI_ABORTED Operation aborted.
+**/
+EFI_STATUS
+GetErasePolarity (
+ OUT BOOLEAN *ErasePolarity
+ )
{
EFI_STATUS Status;
@@ -886,28 +795,20 @@ Returns: return EFI_SUCCESS;
}
+/**
+ This function returns a the highest state bit in the FFS that is set.
+ It in no way validate the FFS file.
+
+ @param ErasePolarity The erase polarity for the file state bits.
+ @param FfsHeader Pointer to a FFS file.
+
+ @retval UINT8 The hightest set state of the file.
+**/
UINT8
GetFileState (
IN BOOLEAN ErasePolarity,
IN EFI_FFS_FILE_HEADER *FfsHeader
)
-/*++
-
-Routine Description:
-
- This function returns a the highest state bit in the FFS that is set.
- It in no way validate the FFS file.
-
-Arguments:
-
- ErasePolarity The erase polarity for the file state bits.
- FfsHeader Pointer to a FFS file.
-
-Returns:
-
- UINT8 The hightest set state of the file.
-
---*/
{
UINT8 FileState;
UINT8 HighestBit;
diff --git a/BaseTools/Source/C/Common/MemoryFile.c b/BaseTools/Source/C/Common/MemoryFile.c index 8154a3c990..4748132683 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:
-
- InputFile Memory file image.
- OutputMemoryFile Handle to memory file
-
-Returns:
+ @param InputFile Memory file image.
+ @param OutputMemoryFile Handle to memory file
- 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 @@ Returns: return EFI_SUCCESS;
}
+/**
+ 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
-
---*/
{
MEMORY_FILE *MemoryFile;
@@ -118,31 +101,22 @@ Returns: 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/MemoryFile.h b/BaseTools/Source/C/Common/MemoryFile.h index 58fc8bb224..c84848cf15 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:
-
- InputFile Memory file image.
- OutputMemoryFile Handle to memory file
+ @param InputFile Memory file image.
+ @param OutputMemoryFile Handle to memory file
-Returns:
-
- EFI_STATUS
+ @return EFI_STATUS
OutputMemoryFile is valid if !EFI_ERROR
-
**/
-
-
EFI_STATUS
-FreeMemoryFile (
- IN EFI_HANDLE InputMemoryFile
+GetMemoryFile (
+ IN CHAR8 *InputFileName,
+ OUT EFI_HANDLE *OutputMemoryFile
)
;
-/**
-
-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
**/
-
-
-CHAR8 *
-ReadMemoryFileLine (
- IN EFI_HANDLE InputMemoryFile
+EFI_STATUS
+FreeMemoryFile (
+ 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.c b/BaseTools/Source/C/Common/MyAlloc.c index d104795d46..17ff5cfbbd 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/MyAlloc.h b/BaseTools/Source/C/Common/MyAlloc.h index aff29d05ab..de3323d30d 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.c b/BaseTools/Source/C/Common/OsPath.c index 35ca54761f..9901f686c9 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:
-
- FilePath Path name of file to get the parent directory for.
-
-Returns:
+ @param FilePath Path name of file to get the parent directory for.
- NULL if error
+ @return NULL if error
+**/
+CHAR8*
+OsPathDirName (
+ IN CHAR8 *FilePath
+ )
---*/
{
CHAR8 *Return;
CHAR8 *Pos;
@@ -97,14 +91,8 @@ Returns: //
// 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
+ @param Path Path name of file to normalize
-Returns:
-
- The string is altered in place.
-
---*/
+ @return The string is altered in place.
+**/
+VOID
+OsPathNormPathInPlace (
+ IN CHAR8 *Path
+ )
{
CHAR8 *Pos;
INTN Offset;
@@ -200,16 +187,7 @@ Returns: }
#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
+ @param OldPath Path name of replace the final segment
+ @param Peer The new path name to concatenate to become the peer path
-Returns:
-
- A CHAR8* string, which must be freed by the caller
-
---*/
+ @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 @@ Returns: 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/OsPath.h b/BaseTools/Source/C/Common/OsPath.h index 1868103e7f..b1881c4a1e 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.c b/BaseTools/Source/C/Common/ParseGuidedSectionTools.c index a34581ecb6..e1e9a97e7b 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
//
-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:
+ @param InputFile Path name of file to read
- InputFile Path name of file to read
-
-Returns:
-
- NULL if error parsing
- A non-NULL EFI_HANDLE otherwise
-
---*/
+ @retval NULL if error parsing
+ @retval A non-NULL EFI_HANDLE otherwise
+**/
+EFI_HANDLE
+ParseGuidedSectionToolsFile (
+ IN CHAR8 *InputFile
+ )
{
EFI_STATUS Status;
EFI_HANDLE MemoryFile;
@@ -74,31 +66,22 @@ Returns: return ParsedGuidedSectionTools;
}
-
-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.
+ @param InputFile Memory file image.
-Returns:
-
- NULL if error or EOF
- InputBuffer otherwise
-
---*/
+ @retval NULL if error or EOF
+ @retval InputBuffer otherwise
+**/
+EFI_HANDLE
+ParseGuidedSectionToolsMemoryFile (
+ IN EFI_HANDLE InputFile
+ )
{
EFI_STATUS Status;
CHAR8 *NextLine;
@@ -160,31 +143,22 @@ Returns: 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/ParseGuidedSectionTools.h b/BaseTools/Source/C/Common/ParseGuidedSectionTools.h index 2714b8ce82..2180bbd074 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
//
-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 Path name of file to read
+ @retval NULL if error parsing
+ @retval A non-NULL EFI_HANDLE otherwise
**/
-
-
EFI_HANDLE
-ParseGuidedSectionToolsMemoryFile (
- IN EFI_HANDLE InputFile
+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 Memory file image.
-
-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
**/
-
-CHAR8*
-LookupGuidedSectionToolPath (
- IN EFI_HANDLE ParsedGuidedSectionToolsHandle,
- IN EFI_GUID *SectionGuid
+EFI_HANDLE
+ParseGuidedSectionToolsMemoryFile (
+ IN EFI_HANDLE InputFile
)
;
-/**
-
-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:
+ @param ParsedGuidedSectionToolsHandle A parsed GUID section tools handle.
+ @param SectionGuid The GUID for the section.
- NULL - if no tool is found or there is another error
- Non-NULL - The tool to use to access the section contents. (The caller
+ @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.)
-
**/
-
-EFI_STATUS
-FreeParsedGuidedSectionToolsHandle (
- IN EFI_HANDLE ParsedGuidedSectionToolsHandle
+CHAR8*
+LookupGuidedSectionToolPath (
+ IN EFI_HANDLE ParsedGuidedSectionToolsHandle,
+ IN EFI_GUID *SectionGuid
)
;
-/**
-
-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.c b/BaseTools/Source/C/Common/ParseInf.c index 5ef8f1306d..63da3d647c 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:
-
- InputFile Memory file image.
- InputBuffer Buffer to read into, must be MaxLength size.
- MaxLength The maximum size of the input buffer.
-
-Returns:
+ @param InputFile Memory file image.
+ @param InputBuffer Buffer to read into, must be MaxLength size.
+ @param MaxLength The maximum size of the input buffer.
- NULL if error or EOF
- InputBuffer otherwise
+ @retval NULL if error or EOF
+ @retval InputBuffer otherwise
+**/
+CHAR8 *
+ReadLine (
+ IN MEMORY_FILE *InputFile,
+ IN OUT CHAR8 *InputBuffer,
+ IN UINTN MaxLength
+ )
---*/
{
CHAR8 *CharPtr;
CHAR8 *EndOfLine;
@@ -129,29 +122,21 @@ Returns: 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 @@ Returns: 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 @@ Returns: 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 @@ Returns: 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.
+ @param AsciiString The string to convert.
+ @param IsHex Force the string to be treated as a hex number.
+ @param ReturnValue The return value.
-Returns:
-
- EFI_SUCCESS Number successfully converted.
- EFI_ABORTED Invalid character encountered.
-
---*/
+ @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 @@ Returns: 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 @@ Returns: return InputBuffer;
}
-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
+ @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
+ )
{
CHAR8 InputBuffer[MAX_LONG_FILE_PATH];
CHAR8 *CurrentToken;
diff --git a/BaseTools/Source/C/Common/ParseInf.h b/BaseTools/Source/C/Common/ParseInf.h index 596cb3aa3b..a0881a5c9e 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 ( )
;
-/*++
-
-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:
+/**
+ Converts a string to an EFI_GUID. The string must be in the
+ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx format.
- 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.
+ @param GuidBuffer pointer to destination Guid
+ @param AsciiGuidBuffer pointer to ascii string
---*/
+ @retval EFI_ABORTED Could not convert the string
+ @retval EFI_SUCCESS The string was successfully converted
+**/
EFI_STATUS
StringToGuid (
IN CHAR8 *AsciiGuidBuffer,
@@ -116,24 +103,19 @@ 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:
+/**
+ 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.
- EFI_ABORTED Could not convert the string
- EFI_SUCCESS The string was successfully converted
+ @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,
@@ -142,27 +124,15 @@ AsciiStringToUint64 ( )
;
-/*++
-
-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:
+/**
+ 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 ( )
;
-/*++
-
-Routine Description:
-
- 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:
+/**
+ This function parses a stream 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 Stream pointer.
+ @param Section Section to search for
---*/
+ @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.c b/BaseTools/Source/C/Common/PcdValueCommon.c index 98023e8786..f17a357b7c 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,6 +101,16 @@ Returns: }
}
+/**
+ Get PCD index in Pcd database
+
+ @param SkuName SkuName String
+ @param DefaultValueName DefaultValueName String
+ @param TokenSpaceGuidName TokenSpaceGuidName String
+ @param TokenName TokenName String
+
+ @return Index of PCD in Pcd database
+**/
int
STATIC
LookupPcdIndex (
@@ -117,23 +119,6 @@ LookupPcdIndex ( CHAR8 *TokenSpaceGuidName,
CHAR8 *TokenName
)
-/*++
-
-Routine Description:
-
- Get PCD index in Pcd database
-
-Arguments:
-
- SkuName SkuName String
- DefaultValueName DefaultValueName String
- TokenSpaceGuidName TokenSpaceGuidName String
- TokenName TokenName String
-
-Returns:
-
- Index of PCD in Pcd database
---*/
{
UINT32 Index;
@@ -161,6 +146,16 @@ Returns: 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 @@ Returns: 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 @@ Returns: }
}
+/**
+ 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 @@ Returns: 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 @@ Returns: }
}
+/**
+ 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 @@ Returns: 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 @@ Returns: }
}
+/**
+ 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 @@ Returns: }
}
+/**
+ Displays the utility usage syntax to STDOUT
+**/
VOID
STATIC
Usage (
VOID
)
-/*++
-
-Routine Description:
-
- Displays the utility usage syntax to STDOUT
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
{
fprintf (stdout, "Usage: -i <input_file> -o <output_file>\n\n");
fprintf (stdout, "optional arguments:\n");
@@ -635,6 +549,14 @@ Returns: 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 @@ Returns: }
}
+/**
+ 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/PcdValueCommon.h b/BaseTools/Source/C/Common/PcdValueCommon.h index 1652bd5430..02ef803be4 100644 --- a/BaseTools/Source/C/Common/PcdValueCommon.h +++ b/BaseTools/Source/C/Common/PcdValueCommon.h @@ -24,46 +24,40 @@ 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:
+/**
+ Main function updates PCD values.
- None
-
-Returns:
- None
---*/
-;
+ @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
---*/
;
+/**
+ 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,
@@ -72,25 +66,18 @@ __PcdSet ( 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
---*/
-;
+ @param SkuName SkuName String
+ @param DefaultValueName DefaultValueName String
+ @param TokenSpaceGuidName TokenSpaceGuidName String
+ @param TokenName TokenName String
+ @return PCD value
+**/
VOID
__PcdSet (
CHAR8 *SkuName OPTIONAL,
@@ -99,26 +86,19 @@ __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:
+/**
+ Get PCD value buffer
- None
---*/
-;
+ @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/PeCoffLoaderEx.c b/BaseTools/Source/C/Common/PeCoffLoaderEx.c index 2cc428d733..181192035e 100644 --- a/BaseTools/Source/C/Common/PeCoffLoaderEx.c +++ b/BaseTools/Source/C/Common/PeCoffLoaderEx.c @@ -65,6 +65,16 @@ SPDX-License-Identifier: BSD-2-Clause-Patent UINT32 *RiscVHi20Fixup = NULL;
+/**
+ Performs an IA-32 specific relocation fixup
+
+ @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,
@@ -72,52 +82,20 @@ PeCoffLoaderRelocateIa32Image ( 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
-
---*/
{
return RETURN_UNSUPPORTED;
}
-/*++
-
-Routine Description:
-
+/**
Performs an RISC-V specific relocation fixup
-Arguments:
-
- Reloc - Pointer to the relocation record
+ @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
- 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 eb6abea1be..382cd406cb 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;
}
+/**
+ Return the line number of the file we're parsing. Used
+ for error reporting purposes.
+
+ @return The line number, or 0 if no file is being processed
+**/
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 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 @@ Returns: 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 @@ Returns: 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
-
-Returns:
- TRUE - the token is next
- FALSE - the token is not next
+ @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.
-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.
- The file pointer is advanced past the token in the input file.
+ @param Str the token to look for
---*/
+ @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 @@ Notes: 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
-
-Returns:
- TRUE - the keyword is next
- FALSE - the keyword is not next
+ @note:
+ A keyword is defined as a "special" string that has a non-alphanumeric
+ character following it.
-Notes:
- A keyword is defined as a "special" string that has a non-alphanumeric
- character following it.
+ @param Str keyword to look for
---*/
+ @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 @@ Notes: 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 @@ Notes: 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
-
-Returns:
- FALSE - current token is not a number
- TRUE - current token is a number
+ @param Value pointer where to store the value
---*/
+ @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 @@ Returns: }
}
+/**
+ Close the file being parsed.
+
+ @retval STATUS_SUCCESS the file was closed
+ @retval STATUS_ERROR no file is currently open
+**/
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
-
---*/
{
if (mGlobals.SourceFile.FileBuffer != NULL) {
free (mGlobals.SourceFile.FileBuffer);
@@ -588,28 +527,20 @@ Returns: return STATUS_ERROR;
}
+/**
+ Given a source file, open the file and parse it
+
+ @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
)
-/*++
-
-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.
-
---*/
{
STATIC UINTN NestDepth = 0;
CHAR8 FoundFileName[MAX_PATH];
@@ -657,27 +588,19 @@ Finish: return Status;
}
+/**
+ Given a source file that's been opened, read the contents into an internal
+ buffer and pre-process it to remove comments.
+
+ @param SourceFile structure containing info on the file to process
+
+ @return Standard 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.
-
---*/
{
//
// Get the file size, and then read the entire thing into memory.
@@ -706,24 +629,17 @@ Returns: return STATUS_SUCCESS;
}
+/**
+ 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.
+
+ @param SourceFile structure that we use to keep track of an input file.
+**/
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.
-
---*/
{
BOOLEAN InComment;
BOOLEAN SlashSlashComment;
@@ -812,26 +728,21 @@ Returns: }
}
+/**
+ 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 @@ Returns: return FALSE;
}
+/**
+ Return TRUE of FALSE to indicate whether or not we've reached the end of the
+ file we're parsing.
+
+ @retval TRUE EOF reached
+ @retval FALSE otherwise
+**/
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
-
---*/
{
SkipWhiteSpace (&mGlobals.SourceFile);
return EndOfFile (&mGlobals.SourceFile);
@@ -1112,27 +1016,22 @@ SkipWhiteSpace ( return Count;
}
+/**
+ 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.
+
+ @param Buffer pointer to first (possibly not null-terminated) string
+ @param Str pointer to null-terminated string to compare to Buffer
+
+ @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
)
-/*++
-
-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
-
-Returns:
- Number of bytes matched if exact match
- 0 if Buffer does not start with 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 50573fdf09..53e44365e9 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
//
+/**
+ Allocates a new string and copies 'String' to clone it
+
+ @param String The string to clone
+
+ @return CHAR8* - NULL if there are not enough resources
+**/
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
-
---*/
{
CHAR8* NewString;
@@ -44,26 +36,17 @@ Returns: return NewString;
}
+/**
+ Remove all comments, leading and trailing whitespace from the string.
+
+ @param String The string to 'strip'
+ @return EFI_STATUS
+**/
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
-
---*/
{
CHAR8 *Pos;
@@ -110,27 +93,18 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Creates and returns a 'split' STRING_LIST by splitting the string
+ on whitespace boundaries.
+ @param String The string to 'split'
+
+ @return EFI_STATUS
+**/
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
-
---*/
{
CHAR8 *Pos;
CHAR8 *EndOfSubString;
@@ -172,21 +146,14 @@ Returns: return Output;
}
+/**
+ Creates a new STRING_LIST with 0 strings.
+ @return STRING_LIST* - Null if there is not enough resources to create the object.
+**/
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.
-
---*/
{
STRING_LIST *NewList;
NewList = AllocateStringListStruct (0);
@@ -196,24 +163,17 @@ Returns: return NewList;
}
+/**
+ Adds String to StringList. A new copy of String is made before it is
+ added to StringList.
+ @return EFI_STATUS
+**/
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
-
---*/
{
STRING_LIST *OldList;
STRING_LIST *NewList;
@@ -245,27 +205,18 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Removes the last string from StringList and frees the memory associated
+ with it.
+ @param StringList The string list to remove the string from
+
+ @return EFI_STATUS
+**/
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
-
---*/
{
if (StringList->Count == 0) {
return EFI_INVALID_PARAMETER;
@@ -276,49 +227,30 @@ Returns: 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]));
}
+/**
+ Frees all memory associated with StringList.
+ @param StringList The string list to free
+**/
VOID
FreeStringList (
IN STRING_LIST *StringList
)
-/*++
-
-Routine Description:
-
- Frees all memory associated with StringList.
-
-Arguments:
-
- StringList The string list to free
-
-Returns:
-
- VOID
---*/
{
while (StringList->Count > 0) {
RemoveLastStringFromList (StringList);
@@ -327,27 +259,18 @@ Returns: free (StringList);
}
+/**
+ Generates a string that represents the STRING_LIST
+ @param StringList The string list to convert to a string
+
+ @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
)
-/*++
-
-Routine Description:
-
- Generates a string that represents the STRING_LIST
-
-Arguments:
-
- StringList The string list to convert to a string
-
-Returns:
-
- CHAR8* - The string list represented with a single string. The returned
- string must be freed by the caller.
-
---*/
{
UINTN Count;
UINTN Length;
@@ -381,26 +304,17 @@ Returns: return NewString;
}
+/**
+ Prints out the string list
+
+ @param StringList The string list to print
+ @return EFI_STATUS
+**/
VOID
PrintStringList (
IN STRING_LIST *StringList
)
-/*++
-
-Routine Description:
-
- Prints out the string list
-
-Arguments:
-
- StringList The string list to print
-
-Returns:
-
- EFI_STATUS
-
---*/
{
CHAR8* String;
String = StringListToString (StringList);
diff --git a/BaseTools/Source/C/Common/StringFuncs.h b/BaseTools/Source/C/Common/StringFuncs.h index 8fc616de80..23dce27244 100644 --- a/BaseTools/Source/C/Common/StringFuncs.h +++ b/BaseTools/Source/C/Common/StringFuncs.h @@ -29,216 +29,139 @@ typedef struct { // Functions declarations
//
+/**
+ Allocates a new string and copies 'String' to clone it
+
+ @param String The string to clone
+
+ @return CHAR8* - NULL if there are not enough resources
+**/
CHAR8*
CloneString (
IN CHAR8 *String
)
;
-/**
-
-Routine Description:
- Allocates a new string and copies 'String' to clone it
-
-Arguments:
-
- String The string to clone
-
-Returns:
+/**
+ Remove all comments, leading and trailing whitespace from the string.
- CHAR8* - NULL if there are not enough resources
+ @param String The string to 'strip'
+ @return EFI_STATUS
**/
-
-
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:
+/**
+ Creates and returns a 'split' STRING_LIST by splitting the string
+ on whitespace boundaries.
- EFI_STATUS
+ @param String The string to 'split'
+ @return EFI_STATUS
**/
-
-
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
+/**
+ Creates a new STRING_LIST with 0 strings.
+ @return STRING_LIST* - Null if there is not enough resources to create the object.
**/
-
-
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.
+/**
+ Adds String to StringList. A new copy of String is made before it is
+ added to StringList.
+ @return EFI_STATUS
**/
-
-
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:
+/**
+ Removes the last string from StringList and frees the memory associated
+ with it.
- EFI_STATUS
+ @param StringList The string list to remove the string from
+ @return EFI_STATUS
**/
-
-
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:
+/**
+ Allocates a STRING_LIST structure that can store StringCount strings.
- EFI_STATUS
+ @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:
+/**
+ Frees all memory associated with StringList.
- EFI_STATUS
+ @param StringList The string list to free
+ @return EFI_STATUS
**/
-
-
VOID
FreeStringList (
IN STRING_LIST *StringList
)
;
-/**
-
-Routine Description:
- Frees all memory associated with StringList.
-
-Arguments:
- StringList The string list to free
-
-Returns:
+/**
+ Generates a string that represents the STRING_LIST
- EFI_STATUS
+ @param StringList The string list to convert to a string
+ @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
)
;
-/**
-
-Routine Description:
-
- Generates a string that represents the STRING_LIST
-
-Arguments:
- StringList The string list to convert to a string
-Returns:
-
- CHAR8* - The string list represented with a single string. The returned
- string must be freed by the caller.
+/**
+ Prints out the string list
+ @param StringList The string list to print
**/
-
-
VOID
PrintStringList (
IN STRING_LIST *StringList
)
;
-/**
-Routine Description:
-
- Prints out the string list
-
-Arguments:
-
- StringList The string list to print
-
-**/
#endif
diff --git a/BaseTools/Source/C/Common/TianoCompress.c b/BaseTools/Source/C/Common/TianoCompress.c index 030cdca025..6d23259720 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 @@ Returns: }
+/**
+ Put a dword to output stream
+
+ @param Data the dword to put
+**/
STATIC
VOID
PutDword (
IN UINT32 Data
)
-/*++
-
-Routine Description:
-
- Put a dword to output stream
-
-Arguments:
-
- Data - the dword to put
-
-Returns: (VOID)
-
---*/
{
if (mDst < mDstUpperLimit) {
*mDst++ = (UINT8) (((UINT8) (Data)) & 0xff);
@@ -387,26 +372,17 @@ Returns: (VOID) }
}
+/**
+ Allocate memory spaces for data structures used in compression process
+
+ @retval EFI_SUCCESS Memory is allocated successfully
+ @retval EFI_OUT_OF_RESOURCES Allocation fails
+**/
STATIC
EFI_STATUS
AllocateMemory (
VOID
)
-/*++
-
-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
-
---*/
{
UINT32 Index;
@@ -445,21 +421,13 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Called when compression is completed to free memory previously allocated.
+**/
VOID
FreeMemory (
VOID
)
-/*++
-
-Routine Description:
-
- Called when compression is completed to free memory previously allocated.
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
{
if (mText != NULL) {
free (mText);
@@ -496,22 +464,14 @@ Returns: (VOID) return ;
}
+/**
+ Initialize String Info Log data structures
+**/
STATIC
VOID
InitSlide (
VOID
)
-/*++
-
-Routine Description:
-
- Initialize String Info Log data structures
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
{
NODE Index;
@@ -535,28 +495,20 @@ Returns: (VOID) }
}
+/**
+ Find child node given the parent node and the edge character
+
+ @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
)
-/*++
-
-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)
-
---*/
{
NODE NodeR;
@@ -572,6 +524,13 @@ Returns: 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]++;
}
+/**
+ Split a node.
+
+ @param Old the node to split
+**/
STATIC
VOID
Split (
NODE Old
)
-/*++
-
-Routine Description:
-
- Split a node.
-
-Arguments:
-
- Old - the node to split
-
-Returns: (VOID)
-
---*/
{
NODE New;
NODE TempNode;
@@ -646,22 +582,14 @@ Returns: (VOID) MakeChild (New, mText[mPos + mMatchLen], mPos);
}
+/**
+ Insert string info for current position into the String Info Log
+**/
STATIC
VOID
InsertNode (
VOID
)
-/*++
-
-Routine Description:
-
- Insert string info for current position into the String Info Log
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
{
NODE NodeQ;
NODE NodeR;
@@ -778,23 +706,15 @@ Returns: (VOID) }
+/**
+ Delete outdated string info. (The Usage of PERC_FLAG
+ ensures a clean deletion)
+**/
STATIC
VOID
DeleteNode (
VOID
)
-/*++
-
-Routine Description:
-
- Delete outdated string info. (The Usage of PERC_FLAG
- ensures a clean deletion)
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
{
NODE NodeQ;
NODE NodeR;
@@ -873,23 +793,15 @@ Returns: (VOID) mAvail = NodeR;
}
+/**
+ Advance the current position (read in new data if needed).
+ Delete outdated string info. Find a match string for current position.
+**/
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)
-
---*/
{
INT32 Number;
@@ -906,25 +818,17 @@ Returns: (VOID) InsertNode ();
}
+/**
+ The main controlling routine 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
)
-/*++
-
-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
-
---*/
{
EFI_STATUS Status;
INT32 LastMatchLen;
@@ -996,22 +900,14 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Count the frequencies for the Extra Set
+**/
STATIC
VOID
CountTFreq (
VOID
)
-/*++
-
-Routine Description:
-
- Count the frequencies for the Extra Set
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
{
INT32 Index;
INT32 Index3;
@@ -1053,6 +949,13 @@ Returns: (VOID) }
}
+/**
+ Outputs the code length array for the Extra Set or the Position Set.
+
+ @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 (
@@ -1060,21 +963,6 @@ WritePTLen ( 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)
-
---*/
{
INT32 Index;
INT32 Index3;
@@ -1103,22 +991,14 @@ Returns: (VOID) }
}
+/**
+ Outputs the code length array for Char&Length Set
+**/
STATIC
VOID
WriteCLen (
VOID
)
-/*++
-
-Routine Description:
-
- Outputs the code length array for Char&Length Set
-
-Arguments: (VOID)
-
-Returns: (VOID)
-
---*/
{
INT32 Index;
INT32 Index3;
@@ -1193,24 +1073,14 @@ EncodeP ( }
}
+/**
+ Huffman code the block and output it.
+**/
STATIC
VOID
SendBlock (
VOID
)
-/*++
-
-Routine Description:
-
- Huffman code the block and output it.
-
-Arguments:
- (VOID)
-
-Returns:
- (VOID)
-
---*/
{
UINT32 Index;
UINT32 Index2;
@@ -1281,26 +1151,18 @@ Returns: }
}
+/**
+ 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 ( }
}
+/**
+ Outputs rightmost n bits of x
+
+ @param Number the rightmost n bits of the data is used
+ @param x the data
+**/
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)
-
---*/
{
UINT8 Temp;
@@ -1439,28 +1293,20 @@ Returns: (VOID) mSubBitBuf |= Value << (mBitCount -= Number);
}
+/**
+ Read in source data
+
+ @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
)
-/*++
-
-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
-
---*/
{
INT32 Index;
@@ -1491,24 +1337,16 @@ InitPutBits ( mSubBitBuf = 0;
}
+/**
+ Count the number of each code length for a Huffman tree.
+
+ @param Index the top node
+**/
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)
-
---*/
{
STATIC INT32 Depth = 0;
@@ -1522,26 +1360,16 @@ Returns: (VOID) }
}
+/**
+ Create code length array for a Huffman tree
+
+ @param Root the root of the tree
+**/
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
-
---*/
{
INT32 Index;
INT32 Index3;
@@ -1616,6 +1444,13 @@ DownHeap ( mHeap[Index] = (INT16) Index3;
}
+/**
+ Assign code to each symbol based on the code length array
+
+ @param Number number of symbols
+ @param Len the code length array
+ @param Code stores codes for each symbol
+**/
STATIC
VOID
MakeCode (
@@ -1623,21 +1458,6 @@ MakeCode ( 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)
-
---*/
{
INT32 Index;
UINT16 Start[18];
@@ -1652,6 +1472,16 @@ Returns: (VOID) }
}
+/**
+ Generates Huffman codes given a frequency distribution of symbols
+
+ @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 (
@@ -1660,24 +1490,6 @@ MakeTree ( 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.
-
---*/
{
INT32 Index;
INT32 Index2;
|