diff options
Diffstat (limited to 'BaseTools/Source/C')
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;
|