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 -/*++ - -Routine Description: +/** Tiano compression routine. - ---*/ +**/ EFI_STATUS TianoCompress ( IN UINT8 *SrcBuffer, @@ -31,13 +28,9 @@ TianoCompress ( ) ; -/*++ - -Routine Description: - +/** Efi compression routine. - ---*/ +**/ EFI_STATUS EfiCompress ( IN UINT8 *SrcBuffer, @@ -47,29 +40,21 @@ EfiCompress ( ) ; -/*++ - -Routine Description: - +/** The compression routine. -Arguments: + @param SrcBuffer The buffer storing the source data + @param SrcSize The size of source data + @param DstBuffer The buffer to store the compressed data + @param DstSize On input, the size of DstBuffer; On output, + the size of the actual compressed data. - SrcBuffer - The buffer storing the source data - SrcSize - The size of source data - DstBuffer - The buffer to store the compressed data - DstSize - On input, the size of DstBuffer; On output, - the size of the actual compressed data. - -Returns: - - EFI_BUFFER_TOO_SMALL - The DstBuffer is too small. In this case, + @retval EFI_BUFFER_TOO_SMALL The DstBuffer is too small. In this case, DstSize contains the size needed. - EFI_SUCCESS - Compression is successful. - EFI_OUT_OF_RESOURCES - No resource to complete function. - EFI_INVALID_PARAMETER - Parameter supplied is wrong. - ---*/ + @retval EFI_SUCCESS Compression is successful. + @retval EFI_OUT_OF_RESOURCES No resource to complete function. + @retval EFI_INVALID_PARAMETER Parameter supplied is wrong. +**/ typedef EFI_STATUS (*COMPRESS_FUNCTION) ( diff --git a/BaseTools/Source/C/Common/Crc32.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 +/** + 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 -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 ); + /** + The implementation Tiano Decompress GetInfo(). -Routine Description: - - The implementation of Efi Decompress(). - -Arguments: - - Source - The source buffer containing the compressed data. - SrcSize - The size of source buffer - Destination - The destination buffer to store the decompressed data - DstSize - The size of destination buffer. - Scratch - The buffer used internally by the decompress routine. This buffer is needed to store intermediate data. - ScratchSize - The size of scratch buffer. - -Returns: - - EFI_SUCCESS - Decompression is successful - EFI_INVALID_PARAMETER - The source data is corrupted + @param Source The source buffer containing the compressed data. + @param SrcSize The size of source buffer + @param 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 ); + /** + The implementation of Tiano Decompress(). -Routine Description: - - The implementation Tiano Decompress GetInfo(). - -Arguments: - - Source - The source buffer containing the compressed data. - SrcSize - The size of source buffer - DstSize - The size of destination buffer. - ScratchSize - The size of scratch buffer. - -Returns: - - EFI_SUCCESS - The size of destination buffer and the size of scratch buffer are successfully retrieved. - EFI_INVALID_PARAMETER - The source data is corrupted + @param Source The source buffer containing the compressed data. + @param SrcSize The size of source buffer + @param 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,6 +36,50 @@ PrintLimitExceeded ( VOID ); +/** + Prints an error message. + + All arguments are optional, though the printed message may be useless if + at least something valid is not specified. + + @note: + We print the following (similar to the Warn() and Debug() + W + Typical error/warning message format: + + 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. + + @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. + + @param MessageCode an application-specific error code that can be referenced in + other documentation. + + @param Text the text in question, typically used by parsers. + + @param MsgFmt the format string for the error message. Can contain formatting + controls for use with the varargs. +**/ VOID Error ( CHAR8 *FileName, @@ -45,56 +89,6 @@ Error ( 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 - 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 - 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 - other documentation. - - Text - the text in question, typically used by parsers. - - 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:" ---*/ { 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,6 +317,42 @@ Returns: va_end (List); } +/** + Worker routine for all the utility printing services. Prints the message in + a format that Visual Studio will find when scanning build outputs for + errors or warnings. + + @note: + If FileName == NULL then this utility will use the string passed into SetUtilityName(). + + LineNumber is only used if the caller is a parser, in which case FileName refers to the + file being parsed. + + Text and MsgFmt are both optional, though it would be of little use calling this function with + them both NULL. + + Output will typically be of the form: + () : : : + + Parser (LineNumber != 0) + VfrCompile.cpp(330) : error E2660: AddVfrDataStructField : function does not take 2 parameters + Generic utility (LineNumber == 0) + UtilityName : error E1234 : Text string : MsgFmt string and args + + @param Type "warning" or "error" string to insert into the message to be + printed. The first character of this string (converted to uppercase) + is used to precede the MessageCode value in the output string. + @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. + @param List the variable list. +**/ VOID PrintMessage ( CHAR8 *Type, @@ -368,54 +363,6 @@ PrintMessage ( 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. - - 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 - part of the message to print - - MsgFmt - the format string for the message. Can contain formatting - controls for use with varargs. - List - the variable list. - -Returns: - None. - -Notes: - If FileName == NULL then this utility will use the string passed into SetUtilityName(). - - LineNumber is only used if the caller is a parser, in which case FileName refers to the - file being parsed. - - Text and MsgFmt are both optional, though it would be of little use calling this function with - them both NULL. - - Output will typically be of the form: - () : : : - - Parser (LineNumber != 0) - VfrCompile.cpp(330) : error E2660: AddVfrDataStructField : function does not take 2 parameters - Generic utility (LineNumber == 0) - UtilityName : error E1234 : Text string : MsgFmt string and args - ---*/ { 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; } +/** + Clears out all files from the Fv buffer in memory + @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 + + @retval 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 - DestinationFv == NULL - invalid parameter - *DestinationFv == NULL - memory will be allocated - *DestinationFv != NULL - this address will be the destination - -Returns: - - EFI_SUCCESS - ---*/ { 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: + @param Fv Source and destination firmware volume. + Note: The original firmware volume buffer is freed! - Fv - Source and destination firmware volume. - Note: The original firmware volume buffer is freed! + @param Size The minimum size that the firmware volume is to be extended by. + The FV may be extended more than this size. - 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: + @param Fv Firmware volume. - 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 // + +/** + This initializes the FV lib with a pointer to the FV and length. It does not + verify the FV in any way. + + @param Fv Buffer containing the FV. + @param FvLength Length of the FV + + @retval EFI_SUCCESS Function Completed successfully. + @retval EFI_INVALID_PARAMETER A required parameter was NULL. +**/ EFI_STATUS InitializeFvLib ( IN VOID *Fv, IN UINT32 FvLength ) -/*++ - -Routine Description: - - This initializes the FV lib with a pointer to the FV and length. It does not - verify the FV in any way. - -Arguments: - - Fv Buffer containing the FV. - FvLength Length of the FV - -Returns: - - EFI_SUCCESS Function Completed successfully. - EFI_INVALID_PARAMETER A required parameter was NULL. - ---*/ { // // Verify input arguments @@ -59,29 +52,21 @@ 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; } +/** + 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. + + @param CurrentFile Pointer to the current file, must be within the current FV. + @param NextFile Pointer to the next file in the FV. + + @retval EFI_SUCCESS Function completed successfully. + @retval EFI_INVALID_PARAMETER A required parameter was NULL or is out of range. + @retval EFI_ABORTED The library needs to be initialized. +**/ EFI_STATUS GetNextFile ( IN EFI_FFS_FILE_HEADER *CurrentFile, OUT EFI_FFS_FILE_HEADER **NextFile ) -/*++ - -Routine Description: - - This function returns the next file. If the current file is NULL, it returns - the first file in the FV. If the function returns EFI_SUCCESS and the file - pointer is NULL, then there are no more files in the FV. - -Arguments: - - CurrentFile Pointer to the current file, must be within the current FV. - NextFile Pointer to the next file in the FV. - -Returns: - - EFI_SUCCESS Function completed successfully. - EFI_INVALID_PARAMETER A required parameter was NULL or is out of range. - EFI_ABORTED The library needs to be initialized. - ---*/ { 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 // + +/** + Verify the current pointer points to a valid FV header. + + @param FvHeader Pointer to an alleged FV file. + + @retval EFI_SUCCESS The FV header is valid. + @retval EFI_VOLUME_CORRUPTED The FV header is not valid. + @retval EFI_INVALID_PARAMETER A required parameter was NULL. + @retval EFI_ABORTED Operation aborted. +**/ EFI_STATUS VerifyFv ( IN EFI_FIRMWARE_VOLUME_HEADER *FvHeader ) -/*++ - -Routine Description: - - Verify the current pointer points to a valid FV header. - -Arguments: - - FvHeader Pointer to an alleged FV file. - -Returns: - - EFI_SUCCESS The FV header is valid. - EFI_VOLUME_CORRUPTED The FV header is not valid. - EFI_INVALID_PARAMETER A required parameter was NULL. - EFI_ABORTED Operation aborted. - ---*/ { UINT16 Checksum; @@ -612,28 +553,20 @@ 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; } +/** + This function returns with the FV erase polarity. If the erase polarity + for a bit is 1, the function return TRUE. + + @param ErasePolarity A pointer to the erase polarity. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER One of the input parameters was invalid. + @retval EFI_ABORTED Operation aborted. +**/ EFI_STATUS GetErasePolarity ( OUT BOOLEAN *ErasePolarity ) -/*++ - -Routine Description: - - This function returns with the FV erase polarity. If the erase polarity - for a bit is 1, the function return TRUE. - -Arguments: - - ErasePolarity A pointer to the erase polarity. - -Returns: - - EFI_SUCCESS The function completed successfully. - EFI_INVALID_PARAMETER One of the input parameters was invalid. - EFI_ABORTED Operation aborted. - ---*/ { 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 // +/** + This opens a file, reads it into memory and returns a memory file + object. + + @param InputFile Memory file image. + @param OutputMemoryFile Handle to memory file + + @return EFI_STATUS + OutputMemoryFile is valid if !EFI_ERROR +**/ 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: - - EFI_STATUS - OutputMemoryFile is valid if !EFI_ERROR - ---*/ { 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: + @param InputMemoryFile Handle to memory file - InputMemoryFile Handle to memory file - -Returns: - - NULL if error or EOF - NULL character termincated string otherwise (MUST BE FREED BY CALLER) - ---*/ + @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 // +/** + This opens a file, reads it into memory and returns a memory file + object. + + @param InputFile Memory file image. + @param OutputMemoryFile Handle to memory file + + @return EFI_STATUS + OutputMemoryFile is valid if !EFI_ERROR +**/ EFI_STATUS GetMemoryFile ( IN CHAR8 *InputFileName, OUT EFI_HANDLE *OutputMemoryFile ) ; + /** + Frees all memory associated with the input memory file. -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: - - EFI_STATUS - OutputMemoryFile is valid if !EFI_ERROR + @param InputMemoryFile Handle to memory file + @return EFI_STATUS **/ - - EFI_STATUS FreeMemoryFile ( IN EFI_HANDLE InputMemoryFile ) ; + /** - -Routine Description: - - Frees all memory associated with the input memory file. - -Arguments: - - InputMemoryFile Handle to memory file - -Returns: - - EFI_STATUS - -**/ - - -CHAR8 * -ReadMemoryFileLine ( - IN EFI_HANDLE InputMemoryFile - ) -; -/** - -Routine Description: - This function reads a line from the memory file. The newline characters are stripped and a null terminated string is returned. If the string pointer returned is non-NULL, then the caller must free the memory associated with this string. -Arguments: - - InputMemoryFile Handle to memory file - -Returns: - - NULL if error or EOF - NULL character termincated string otherwise (MUST BE FREED BY CALLER) + @param InputMemoryFile Handle to memory file + @retval NULL if error or EOF + @retval NULL character termincated string otherwise (MUST BE FREED BY CALLER) **/ +CHAR8 * +ReadMemoryFileLine ( + IN EFI_HANDLE InputMemoryFile + ) +; #endif diff --git a/BaseTools/Source/C/Common/MyAlloc.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: + @param FilePath Path name of file to get the parent directory for. - FilePath Path name of file to get the parent directory for. + @return NULL if error +**/ +CHAR8* +OsPathDirName ( + IN CHAR8 *FilePath + ) -Returns: - - NULL if error - ---*/ { CHAR8 *Return; CHAR8 *Pos; @@ -97,14 +91,8 @@ 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: + @param Path Path name of file to normalize - 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: + @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 - -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: - - OldPath Path name of replace the final segment - Peer The new path name to concatenate to become the peer path - -Returns: - - A CHAR8* string, which must be freed by the caller + @param OldPath Path name of replace the final segment + @param Peer The new path name to concatenate to become the peer path + @return A CHAR8* string, which must be freed by the caller **/ +CHAR8* +OsPathPeerFilePath ( + IN CHAR8 *OldPath, + IN CHAR8 *Peer + ) +; +/** + 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 - -**/ - #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: + @param InputFile Memory file image. - 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 // +/** + This function parses the tools_def.txt file. It returns a + EFI_HANDLE object which can be used for the other library + functions and should be passed to FreeParsedToolsDefHandle + to free resources when the tools_def.txt information is no + longer needed. + + @param InputFile Path name of file to read + + @retval NULL if error parsing + @retval A non-NULL EFI_HANDLE otherwise +**/ EFI_HANDLE ParseGuidedSectionToolsFile ( IN CHAR8 *InputFile ) ; + /** - -Routine Description: - This function parses the tools_def.txt file. It returns a EFI_HANDLE object which can be used for the other library functions and should be passed to FreeParsedToolsDefHandle to free resources when the tools_def.txt information is no longer needed. -Arguments: - - InputFile Path name of file to read - -Returns: - - NULL if error parsing - A non-NULL EFI_HANDLE otherwise + @param InputFile Memory file image. + @retval NULL if error parsing + @retval A non-NULL EFI_HANDLE otherwise **/ - - EFI_HANDLE ParseGuidedSectionToolsMemoryFile ( IN EFI_HANDLE InputFile ) ; + /** + This function looks up the appropriate tool to use for extracting + a GUID defined FV section. -Routine Description: - - This function parses the tools_def.txt file. It returns a - EFI_HANDLE object which can be used for the other library - functions and should be passed to FreeParsedToolsDefHandle - to free resources when the tools_def.txt information is no - longer needed. - -Arguments: - - InputFile Memory file image. - -Returns: - - NULL if error parsing - A non-NULL EFI_HANDLE otherwise + @param ParsedGuidedSectionToolsHandle A parsed GUID section tools handle. + @param SectionGuid The GUID for the section. + @retval NULL if no tool is found or there is another error + @retval Non-NULL The tool to use to access the section contents. (The caller + must free the memory associated with this string.) **/ - CHAR8* LookupGuidedSectionToolPath ( IN EFI_HANDLE ParsedGuidedSectionToolsHandle, IN EFI_GUID *SectionGuid ) ; + /** + Frees resources that were allocated by ParseGuidedSectionToolsFile. + After freeing these resources, the information that was parsed + is no longer accessible. -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.) + @param ParsedToolDefHandle Handle returned from ParseGuidedSectionToolsFile + @return EFI_STATUS **/ - EFI_STATUS FreeParsedGuidedSectionToolsHandle ( IN EFI_HANDLE ParsedGuidedSectionToolsHandle ) ; -/** - -Routine Description: - - Frees resources that were allocated by ParseGuidedSectionToolsFile. - After freeing these resources, the information that was parsed - is no longer accessible. - -Arguments: - - ParsedToolDefHandle Handle returned from ParseGuidedSectionToolsFile - -Returns: - - EFI_STATUS - -**/ #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: + @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: - - NULL if error or EOF - InputBuffer otherwise - ---*/ { 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; } +/** + 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. + + @param AsciiString The string to convert. + @param IsHex Force the string to be treated as a hex number. + @param ReturnValue The return value. + + @retval EFI_SUCCESS Number successfully converted. + @retval EFI_ABORTED Invalid character encountered. +**/ EFI_STATUS AsciiStringToUint64 ( IN CONST CHAR8 *AsciiString, IN BOOLEAN IsHex, OUT UINT64 *ReturnValue ) -/*++ - -Routine Description: - - Converts a null terminated ascii string that represents a number into a - UINT64 value. A hex number may be preceded by a 0x, but may not be - succeeded by an h. A number without 0x or 0X is considered to be base 10 - unless the IsHex input is true. - -Arguments: - - AsciiString The string to convert. - IsHex Force the string to be treated as a hex number. - ReturnValue The return value. - -Returns: - - EFI_SUCCESS Number successfully converted. - EFI_ABORTED Invalid character encountered. - ---*/ { 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; } +/** + This function parses a stream file from the beginning to find a section. + The section string may be anywhere within a line. + // BUGBUG: This is obsolete once genmake goes away... + + @param InputFile Stream pointer. + @param Section Section to search for + + @retval FALSE if error or EOF + @retval TRUE if section found +**/ BOOLEAN FindSectionInStream ( IN FILE *InputFile, IN CHAR8 *Section ) -/*++ - -Routine Description: - - This function parses a stream file from the beginning to find a section. - The section string may be anywhere within a line. - // BUGBUG: This is obsolete once genmake goes away... - -Arguments: - - InputFile Stream pointer. - Section Section to search for - -Returns: - - FALSE if error or EOF - TRUE if section found - ---*/ { CHAR8 InputBuffer[MAX_LONG_FILE_PATH]; CHAR8 *CurrentToken; diff --git a/BaseTools/Source/C/Common/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,6 +20,22 @@ extern "C" { // // Functions declarations // + +/** + 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 + to and including the first newline character, to the end of the stream, or + until the number of characters read is equal to MaxLength - 1, whichever + comes first. The newline character, if read, is replaced with a \0. + + @param InputFile Memory file image. + @param InputBuffer Buffer to read into, must be MaxLength size. + @param MaxLength The maximum size of the input buffer. + + @retval NULL if error or EOF + @retval InputBuffer otherwise +**/ CHAR8 * ReadLine ( IN MEMORY_FILE *InputFile, @@ -28,29 +44,16 @@ ReadLine ( ) ; -/*++ +/** + This function parses a file from the beginning to find a section. + The section string may be anywhere within a line. -Routine Description: + @param InputFile Memory file image. + @param Section Section to search for - 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 - to and including the first newline character, to the end of the stream, or - 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: - - NULL if error or EOF - InputBuffer otherwise - ---*/ + @retval FALSE if error or EOF + @retval TRUE if section found +**/ BOOLEAN FindSection ( IN MEMORY_FILE *InputFile, @@ -58,24 +61,21 @@ FindSection ( ) ; -/*++ +/** + Finds a token value given the section and token to search for. -Routine Description: + @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. - 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 - ---*/ + @retval EFI_SUCCESS Value found. + @retval EFI_ABORTED Format error detected in INF file. + @retval EFI_INVALID_PARAMETER Input argument was null. + @retval EFI_LOAD_ERROR Error reading from the file. + @retval EFI_NOT_FOUND Section/Token/Value not found. +**/ EFI_STATUS FindToken ( IN MEMORY_FILE *InputFile, @@ -86,29 +86,16 @@ FindToken ( ) ; -/*++ +/** + Converts a string to an EFI_GUID. The string must be in the + xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx format. -Routine Description: + @param GuidBuffer pointer to destination Guid + @param AsciiGuidBuffer pointer to ascii string - Finds a token value given the section and token to search for. - -Arguments: - - InputFile Memory file image. - Section The section to search for, a string within []. - Token The token to search for, e.g. EFI_PEIM_RECOVERY, followed by an = in the INF file. - Instance The instance of the token to search for. Zero is the first instance. - Value The string that holds the value following the =. Must be MAX_LONG_FILE_PATH in size. - -Returns: - - EFI_SUCCESS Value found. - EFI_ABORTED Format error detected in INF file. - EFI_INVALID_PARAMETER Input argument was null. - EFI_LOAD_ERROR Error reading from the file. - EFI_NOT_FOUND Section/Token/Value not found. - ---*/ + @retval EFI_ABORTED Could not convert the string + @retval EFI_SUCCESS The string was successfully converted +**/ EFI_STATUS StringToGuid ( IN CHAR8 *AsciiGuidBuffer, @@ -116,24 +103,19 @@ StringToGuid ( ) ; -/*++ +/** + 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. -Routine Description: + @param AsciiString The string to convert. + @param IsHex Force the string to be treated as a hex number. + @param ReturnValue The return value. - Converts a string to an EFI_GUID. The string must be in the - xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx format. - -Arguments: - - GuidBuffer - pointer to destination Guid - AsciiGuidBuffer - pointer to ascii string - -Returns: - - EFI_ABORTED Could not convert the string - EFI_SUCCESS The string was successfully converted - ---*/ + @retval EFI_SUCCESS Number successfully converted. + @retval EFI_ABORTED Invalid character encountered. +**/ EFI_STATUS AsciiStringToUint64 ( IN CONST CHAR8 *AsciiString, @@ -142,27 +124,15 @@ AsciiStringToUint64 ( ) ; -/*++ +/** + This function reads a line, stripping any comments. -Routine Description: + @param InputFile Stream pointer. + @param InputBuffer Buffer to read into, must be MAX_LONG_FILE_PATH size. - Converts a null terminated ascii string that represents a number into a - UINT64 value. A hex number may be preceded by a 0x, but may not be - succeeded by an h. A number without 0x or 0X is considered to be base 10 - unless the IsHex input is true. - -Arguments: - - AsciiString The string to convert. - IsHex Force the string to be treated as a hex number. - ReturnValue The return value. - -Returns: - - EFI_SUCCESS Number successfully converted. - EFI_ABORTED Invalid character encountered. - ---*/ + @retval NULL if error or EOF + @retval InputBuffer otherwise +**/ CHAR8 * ReadLineInStream ( IN FILE *InputFile, @@ -170,23 +140,16 @@ ReadLineInStream ( ) ; -/*++ +/** + This function parses a stream file from the beginning to find a section. + The section string may be anywhere within a line. -Routine Description: + @param InputFile Stream pointer. + @param Section Section to search for - This function reads a line, stripping any comments. - -Arguments: - - InputFile Stream pointer. - InputBuffer Buffer to read into, must be MAX_LONG_FILE_PATH size. - -Returns: - - NULL if error or EOF - InputBuffer otherwise - ---*/ + @retval FALSE if error or EOF + @retval TRUE if section found +**/ BOOLEAN FindSectionInStream ( IN FILE *InputFile, @@ -194,25 +157,6 @@ FindSectionInStream ( ) ; -/*++ - -Routine Description: - - This function parses a stream file from the beginning to find a section. - The section string may be anywhere within a line. - -Arguments: - - InputFile Stream pointer. - Section Section to search for - -Returns: - - FALSE if error or EOF - TRUE if section found - ---*/ - #ifdef __cplusplus } #endif diff --git a/BaseTools/Source/C/Common/PcdValueCommon.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 -o \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,101 +24,81 @@ SPDX-License-Identifier: BSD-2-Clause-Patent #define __STATIC_ASSERT _Static_assert #endif +/** + Main function updates PCD values. It is auto generated by Build +**/ VOID PcdEntryPoint ( VOID ) -/*++ -Routine Description: - - Main function updates PCD values. It is auto generated by Build - -Arguments: - - None - -Returns: - None ---*/ ; +/** + Main function updates PCD values. + + @param argc Number of command line parameters. + @param argv Array of pointers to parameter strings. + + @retval EXIT_SUCCESS +**/ int PcdValueMain ( int argc, char *argv[] ) -/*++ - -Routine Description: - - Main function updates PCD values. - -Arguments: - - argc Number of command line parameters. - argv Array of pointers to parameter strings. - -Returns: - EXIT_SUCCESS ---*/ ; -VOID -__PcdSet ( - CHAR8 *SkuName OPTIONAL, - CHAR8 *DefaultValueName OPTIONAL, - CHAR8 *TokenSpaceGuidName, - CHAR8 *TokenName, - UINT64 Value - ) -/*++ - -Routine Description: - - Get PCD value - -Arguments: - - SkuName SkuName String - DefaultValueName DefaultValueName String - TokenSpaceGuidName TokenSpaceGuidName String - TokenName TokenName String - -Returns: - - PCD value ---*/ -; - -VOID -__PcdSet ( - CHAR8 *SkuName OPTIONAL, - CHAR8 *DefaultValueName OPTIONAL, - CHAR8 *TokenSpaceGuidName, - CHAR8 *TokenName, - UINT64 Value - ) -/*++ - -Routine Description: - +/** Set PCD value -Arguments: - - SkuName SkuName String - DefaultValueName DefaultValueName String - TokenSpaceGuidName TokenSpaceGuidName String - TokenName TokenName String - Value PCD value to be set - -Returns: - - None ---*/ + @param SkuName SkuName String + @param DefaultValueName DefaultValueName String + @param TokenSpaceGuidName TokenSpaceGuidName String + @param TokenName TokenName String + @param Value PCD value to be set +**/ +VOID +__PcdSet ( + CHAR8 *SkuName OPTIONAL, + CHAR8 *DefaultValueName OPTIONAL, + CHAR8 *TokenSpaceGuidName, + CHAR8 *TokenName, + UINT64 Value + ) ; +/** + Get 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, + CHAR8 *DefaultValueName OPTIONAL, + CHAR8 *TokenSpaceGuidName, + CHAR8 *TokenName, + UINT64 Value + ) +; + +/** + Get PCD value buffer + + @param SkuName SkuName String + @param DefaultValueName DefaultValueName String + @param TokenSpaceGuidName TokenSpaceGuidName String + @param TokenName TokenName String + @param Size Size of PCD value buffer + + @return PCD value buffer +**/ VOID * __PcdGetPtr ( CHAR8 *SkuName OPTIONAL, @@ -127,26 +107,18 @@ __PcdGetPtr ( CHAR8 *TokenName, UINT32 *Size ) -/*++ - -Routine Description: - - Get PCD value buffer - -Arguments: - - SkuName SkuName String - DefaultValueName DefaultValueName String - TokenSpaceGuidName TokenSpaceGuidName String - TokenName TokenName String - Size Size of PCD value buffer - -Returns: - - PCD value buffer ---*/ ; +/** + Set PCD value buffer + + @param SkuName SkuName String + @param DefaultValueName DefaultValueName String + @param TokenSpaceGuidName TokenSpaceGuidName String + @param TokenName TokenName String + @param Size Size of PCD value + @param Value Pointer to the updated PCD value buffer +**/ VOID __PcdSetPtr ( CHAR8 *SkuName OPTIONAL, @@ -156,25 +128,6 @@ __PcdSetPtr ( UINT32 Size, UINT8 *Value ) -/*++ - -Routine Description: - - Set PCD value buffer - -Arguments: - - SkuName SkuName String - DefaultValueName DefaultValueName String - TokenSpaceGuidName TokenSpaceGuidName String - TokenName TokenName String - Size Size of PCD value - Value Pointer to the updated PCD value buffer - -Returns: - - None ---*/ ; #define PcdGet(A, B, C, D) __PcdGet(#A, #B, #C, #D) diff --git a/BaseTools/Source/C/Common/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: + @param Reloc Pointer to the relocation record + @param Fixup Pointer to the address to fix up + @param FixupData Pointer to a buffer to log the fixups + @param Adjust The offset to adjust the fixup - Reloc - Pointer to the relocation record - - Fixup - Pointer to the address to fix up - - FixupData - Pointer to a buffer to log the fixups - - Adjust - The offset to adjust the fixup - -Returns: - - Status code - ---*/ + @return Status code +**/ RETURN_STATUS PeCoffLoaderRelocateRiscVImage ( IN UINT16 *Reloc, diff --git a/BaseTools/Source/C/Common/SimpleFileParsing.c b/BaseTools/Source/C/Common/SimpleFileParsing.c index 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; } +/** + Return the name of the file we're parsing. Used + for error reporting purposes. + + @return A pointer to the file name. Null if no file is being + processed. +**/ 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 - processed. - ---*/ { 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; } +/** + Check to see if the specified token is found at + the current position in the input file. + + @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. + + 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 ) -/*++ - -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 - -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. - ---*/ { UINTN Len; SkipWhiteSpace (&mGlobals.SourceFile); @@ -286,28 +252,23 @@ Notes: return FALSE; } +/** + Check to see if the specified keyword is found at + the current position in the input file. + + @note: + 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 ) -/*++ - -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 - -Notes: - A keyword is defined as a "special" string that has a non-alphanumeric - character following it. - ---*/ { 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; } +/** + Check the token at the current file position for a numeric value. + May be either decimal or hex. + + @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 ) -/*++ - -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 - ---*/ { 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 ) ; + /** + Remove all comments, leading and trailing whitespace from the string. -Routine Description: - - Allocates a new string and copies 'String' to clone it - -Arguments: - - String The string to clone - -Returns: - - CHAR8* - NULL if there are not enough resources + @param String The string to 'strip' + @return EFI_STATUS **/ - - EFI_STATUS StripInfDscStringInPlace ( IN CHAR8 *String ) ; + /** + Creates and returns a 'split' STRING_LIST by splitting the string + on whitespace boundaries. -Routine Description: - - Remove all comments, leading and trailing whitespace from the string. - -Arguments: - - String The string to 'strip' - -Returns: - - EFI_STATUS + @param String The string to 'split' + @return EFI_STATUS **/ - - STRING_LIST* SplitStringByWhitespace ( IN CHAR8 *String ) ; + /** + Creates a new STRING_LIST with 0 strings. -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 - + @return STRING_LIST* - Null if there is not enough resources to create the object. **/ - - STRING_LIST* NewStringList ( ) ; + + /** + Adds String to StringList. A new copy of String is made before it is + added to StringList. -Routine Description: - - Creates a new STRING_LIST with 0 strings. - -Returns: - - STRING_LIST* - Null if there is not enough resources to create the object. - + @return EFI_STATUS **/ - - EFI_STATUS AppendCopyOfStringToList ( IN OUT STRING_LIST **StringList, IN CHAR8 *String ) ; + /** + Removes the last string from StringList and frees the memory associated + with it. -Routine Description: - - Adds String to StringList. A new copy of String is made before it is - added to StringList. - -Returns: - - EFI_STATUS + @param StringList The string list to remove the string from + @return EFI_STATUS **/ - - EFI_STATUS RemoveLastStringFromList ( IN STRING_LIST *StringList ) ; + + /** + Allocates a STRING_LIST structure that can store StringCount strings. -Routine Description: - - Removes the last string from StringList and frees the memory associated - with it. - -Arguments: - - StringList The string list to remove the string from - -Returns: - - EFI_STATUS + @param StringCount The number of strings that need to be stored + @return EFI_STATUS **/ - - STRING_LIST* AllocateStringListStruct ( IN UINTN StringCount ) ; + + /** + Frees all memory associated with StringList. -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 + @param StringList The string list to free + @return EFI_STATUS **/ - - VOID FreeStringList ( IN STRING_LIST *StringList ) ; + + /** + Generates a string that represents the STRING_LIST -Routine Description: - - Frees all memory associated with StringList. - -Arguments: - - StringList The string list to free - -Returns: - - 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 ) ; + + /** + Prints out the string list -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. - + @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;