From f97c2415d2a88f0cfee8af3e62ee106659efb78f Mon Sep 17 00:00:00 2001 From: ydong10 Date: Fri, 12 Nov 2010 08:00:23 +0000 Subject: [PATCH] Refine coding style. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@11049 6f19259b-4bc3-4df7-8a09-765794883524 --- PerformancePkg/Dp_App/Dp.inf | 3 + PerformancePkg/Dp_App/DpInternal.h | 333 +++++++++++++++++------------ 2 files changed, 196 insertions(+), 140 deletions(-) diff --git a/PerformancePkg/Dp_App/Dp.inf b/PerformancePkg/Dp_App/Dp.inf index aef7c07bac..84b2d5f749 100644 --- a/PerformancePkg/Dp_App/Dp.inf +++ b/PerformancePkg/Dp_App/Dp.inf @@ -29,7 +29,10 @@ [Sources] DpStrings.uni Dp.c + Dp.h + Literals.h Literals.c + DpInternal.h DpUtilities.c DpTrace.c DpProfile.c diff --git a/PerformancePkg/Dp_App/DpInternal.h b/PerformancePkg/Dp_App/DpInternal.h index 6562230209..974901203a 100644 --- a/PerformancePkg/Dp_App/DpInternal.h +++ b/PerformancePkg/Dp_App/DpInternal.h @@ -39,48 +39,58 @@ extern UINT32 const NumCum; ///@} -/** Calculate an event's duration in timer ticks. - * - * Given the count direction and the event's start and end timer values, - * calculate the duration of the event in timer ticks. - * - * @pre The global TimerInfo structure must have already been initialized - * before this function is called. - * - * @param[in,out] Measurement Pointer to a structure containing data for the current measurement. - * - * @return The 64-bit duration of the event. +/** + Calculate an event's duration in timer ticks. + + Given the count direction and the event's start and end timer values, + calculate the duration of the event in timer ticks. Information for + the current measurement is pointed to by the parameter. + + If the measurement's start time is 1, it indicates that the developer + is indicating that the measurement began at the release of reset. + The start time is adjusted to the timer's starting count before performing + the elapsed time calculation. + + The calculated duration, in ticks, is the absolute difference between + the measurement's ending and starting counts. + + @param Measurement Pointer to a MEASUREMENT_RECORD structure containing + data for the current measurement. + + @return The 64-bit duration of the event. **/ UINT64 GetDuration ( IN OUT MEASUREMENT_RECORD *Measurement ); -/** Determine whether the Measurement record is for an EFI Phase. - * - * The Token and Module members of the measurement record are checked. - * Module must be empty and Token must be one of SEC, PEI, DXE, or BDS. - * - * @param[in] Measurement A pointer to the Measurement record to test. - * - * @retval TRUE The measurement record is for an EFI Phase. - * @retval FALSE The measurement record is NOT for an EFI Phase. +/** + Determine whether the Measurement record is for an EFI Phase. + + The Token and Module members of the measurement record are checked. + Module must be empty and Token must be one of SEC, PEI, DXE, BDS, or SHELL. + + @param[in] Measurement A pointer to the Measurement record to test. + + @retval TRUE The measurement record is for an EFI Phase. + @retval FALSE The measurement record is NOT for an EFI Phase. **/ BOOLEAN IsPhase( IN MEASUREMENT_RECORD *Measurement ); -/** Get the file name portion of the Pdb File Name. - * - * The portion of the Pdb File Name between the last backslash and - * either a following period or the end of the string is converted - * to Unicode and copied into UnicodeBuffer. The name is truncated, - * if necessary, to ensure that UnicodeBuffer is not overrun. - * - * @param[in] PdbFileName Pdb file name. - * @param[out] UnicodeBuffer The resultant Unicode File Name. - * +/** + Get the file name portion of the Pdb File Name. + + The portion of the Pdb File Name between the last backslash and + either a following period or the end of the string is converted + to Unicode and copied into UnicodeBuffer. The name is truncated, + if necessary, to ensure that UnicodeBuffer is not overrun. + + @param[in] PdbFileName Pdb file name. + @param[out] UnicodeBuffer The resultant Unicode File Name. + **/ VOID GetShortPdbFileName ( @@ -88,40 +98,46 @@ GetShortPdbFileName ( OUT CHAR16 *UnicodeBuffer ); -/** Get a human readable name for an image handle. - * - * @param[in] Handle - * - * @post The resulting Unicode name string is stored in the - * mGaugeString global array. - * +/** + Get a human readable name for an image handle. + + @param[in] Handle + + @post The resulting Unicode name string is stored in the + mGaugeString global array. + **/ VOID GetNameFromHandle ( IN EFI_HANDLE Handle ); -/** Calculate the Duration in microseconds. - * - * Duration is multiplied by 1000, instead of Frequency being divided by 1000 - * in order to maintain precision. Since Duration is - * a 64-bit value, multiplying it by 1000 is unlikely to produce an overflow. - * - * @param[in] Duration The event duration in timer ticks. - * - * @return A 64-bit value which is the Elapsed time in microseconds. +/** + Calculate the Duration in microseconds. + + Duration is multiplied by 1000, instead of Frequency being divided by 1000 or + multiplying the result by 1000, in order to maintain precision. Since Duration is + a 64-bit value, multiplying it by 1000 is unlikely to produce an overflow. + + The time is calculated as (Duration * 1000) / Timer_Frequency. + + @param[in] Duration The event duration in timer ticks. + + @return A 64-bit value which is the Elapsed time in microseconds. **/ UINT64 DurationInMicroSeconds ( IN UINT64 Duration ); -/** Formatted Print using a Hii Token to reference the localized format string. - * - * @param[in] Token A HII token associated with a localized Unicode string. - * - * @return The number of characters converted by UnicodeVSPrint(). - * +/** + Formatted Print using a Hii Token to reference the localized format string. + + @param[in] Token A HII token associated with a localized Unicode string. + @param[in] ... The variable argument list. + + @return The number of characters converted by UnicodeVSPrint(). + **/ UINTN PrintToken ( @@ -129,52 +145,60 @@ PrintToken ( ... ); -/** Get index of Measurement Record's match in the CumData array. - * - * @param[in] Measurement A pointer to a Measurement Record to match against the CumData array. - * - * @retval <0 Token is not in the CumData array. - * @retval >=0 Return value is the index into CumData where Token is found. +/** + Get index of Measurement Record's match in the CumData array. + + If the Measurement's Token value matches a Token in one of the CumData + records, the index of the matching record is returned. The returned + index is a signed value so that negative values can indicate that + the Measurement didn't match any entry in the CumData array. + + @param[in] Measurement A pointer to a Measurement Record to match against the CumData array. + + @retval <0 Token is not in the CumData array. + @retval >=0 Return value is the index into CumData where Token is found. **/ INTN GetCumulativeItem( IN MEASUREMENT_RECORD *Measurement ); -/** Collect verbose statistics about the logged performance measurements. - * - * General Summary information for all Trace measurements is gathered and - * stored within the SummaryData structure. This information is both - * used internally by subsequent reporting functions, and displayed - * at the end of verbose reports. - * - * @pre The SummaryData and CumData structures must be initialized - * prior to calling this function. - * - * @post The SummaryData and CumData structures contain statistics for the - * current performance logs. +/** + Collect verbose statistics about the logged performance measurements. + + General Summary information for all Trace measurements is gathered and + stored within the SummaryData structure. This information is both + used internally by subsequent reporting functions, and displayed + at the end of verbose reports. + + @pre The SummaryData and CumData structures must be initialized + prior to calling this function. + + @post The SummaryData and CumData structures contain statistics for the + current performance logs. **/ VOID GatherStatistics( VOID ); -/** Gather and print ALL Trace Records. - * - * Displays all "interesting" Trace measurements in order. - * The number of records displayed is controlled by: - * - records with a duration less than mInterestThreshold microseconds are not displayed. - * - No more than Limit records are displayed. A Limit of zero will not limit the output. - * - If the ExcludeFlag is TRUE, records matching entries in the CumData array are not - * displayed. - * - * @pre The mInterestThreshold global variable is set to the shortest duration to be printed. - * The mGaugeString and mUnicodeToken global arrays are used for temporary string storage. - * They must not be in use by a calling function. - * - * @param[in] Limit The number of records to print. Zero is ALL. - * @param[in] ExcludeFlag TRUE to exclude individual Cumulative items from display. - * +/** + Gather and print ALL Trace Records. + + Displays all "interesting" Trace measurements in order.
+ The number of records displayed is controlled by: + - records with a duration less than mInterestThreshold microseconds are not displayed. + - No more than Limit records are displayed. A Limit of zero will not limit the output. + - If the ExcludeFlag is TRUE, records matching entries in the CumData array are not + displayed. + + @pre The mInterestThreshold global variable is set to the shortest duration to be printed. + The mGaugeString and mUnicodeToken global arrays are used for temporary string storage. + They must not be in use by a calling function. + + @param[in] Limit The number of records to print. Zero is ALL. + @param[in] ExcludeFlag TRUE to exclude individual Cumulative items from display. + **/ VOID DumpAllTrace( @@ -182,22 +206,23 @@ DumpAllTrace( IN BOOLEAN ExcludeFlag ); -/** Gather and print Raw Trace Records. - * - * All Trace measurements with a duration greater than or equal to - * mInterestThreshold are printed without interpretation. - * - * The number of records displayed is controlled by: - * - records with a duration less than mInterestThreshold microseconds are not displayed. - * - No more than Limit records are displayed. A Limit of zero will not limit the output. - * - If the ExcludeFlag is TRUE, records matching entries in the CumData array are not - * displayed. - * - * @pre The mInterestThreshold global variable is set to the shortest duration to be printed. - * - * @param[in] Limit The number of records to print. Zero is ALL. - * @param[in] ExcludeFlag TRUE to exclude individual Cumulative items from display. - * +/** + Gather and print Raw Trace Records. + + All Trace measurements with a duration greater than or equal to + mInterestThreshold are printed without interpretation. + + The number of records displayed is controlled by: + - records with a duration less than mInterestThreshold microseconds are not displayed. + - No more than Limit records are displayed. A Limit of zero will not limit the output. + - If the ExcludeFlag is TRUE, records matching entries in the CumData array are not + displayed. + + @pre The mInterestThreshold global variable is set to the shortest duration to be printed. + + @param[in] Limit The number of records to print. Zero is ALL. + @param[in] ExcludeFlag TRUE to exclude individual Cumulative items from display. + **/ VOID DumpRawTrace( @@ -205,10 +230,11 @@ DumpRawTrace( IN BOOLEAN ExcludeFlag ); -/** Gather and print Major Phase metrics. - * - * @param[in] Ticker The timer value for the END of Shell phase - * +/** + Gather and print Major Phase metrics. + + @param[in] Ticker The timer value for the END of Shell phase + **/ VOID ProcessPhases( @@ -216,11 +242,12 @@ ProcessPhases( ); -/** Gather and print Handle data. - * - * @param[in] ExcludeFlag TRUE if the -x command line flag given. Elides accumulated trace records. - * - * @return Status from a call to gBS->LocateHandle(). +/** + Gather and print Handle data. + + @param[in] ExcludeFlag TRUE to exclude individual Cumulative items from display. + + @return Status from a call to gBS->LocateHandle(). **/ EFI_STATUS ProcessHandles( @@ -228,48 +255,62 @@ ProcessHandles( ); -/** Gather and print PEIM data. - * - * Only prints complete PEIM records - * +/** + Gather and print PEIM data. + + Only prints complete PEIM records + **/ VOID ProcessPeims( VOID ); -/** Gather and print global data. - * - * Strips out incomplete or "Execution Phase" records - * Only prints records where Handle is NULL - * Increment TIndex for every record, even skipped ones, so that we have an - * indication of every measurement record taken. - * - * +/** + Gather and print global data. + + Strips out incomplete or "Execution Phase" records + Only prints records where Handle is NULL + Increment TIndex for every record, even skipped ones, so that we have an + indication of every measurement record taken. + **/ VOID ProcessGlobal( VOID ); -/** Gather and print cumulative data. - * - * Traverse the measurement records and: - * for each record with a Token listed in the CumData array, - * Update the instance count and the total, minimum, and maximum durations. - * Finally, print the gathered cumulative statistics. - * +/** + Gather and print cumulative data. + + Traverse the measurement records and:
+ For each record with a Token listed in the CumData array:
+ - Update the instance count and the total, minimum, and maximum durations. + Finally, print the gathered cumulative statistics. + **/ VOID ProcessCumulative( VOID ); -/** Gather and print ALL Profile Records. - * - * @param[in] Limit The number of records to print. Zero is ALL. - * @param[in] ExcludeFlag TRUE to exclude individual Cumulative items from display - * +/** + Gather and print ALL Profiling Records. + + Displays all "interesting" Profile measurements in order. + The number of records displayed is controlled by: + - records with a duration less than mInterestThreshold microseconds are not displayed. + - No more than Limit records are displayed. A Limit of zero will not limit the output. + - If the ExcludeFlag is TRUE, records matching entries in the CumData array are not + displayed. + + @pre The mInterestThreshold global variable is set to the shortest duration to be printed. + The mGaugeString and mUnicodeToken global arrays are used for temporary string storage. + They must not be in use by a calling function. + + @param[in] Limit The number of records to print. Zero is ALL. + @param[in] ExcludeFlag TRUE to exclude individual Cumulative items from display. + **/ VOID DumpAllProfile( @@ -277,11 +318,23 @@ DumpAllProfile( IN BOOLEAN ExcludeFlag ); -/** Gather and print Raw Profile Records. - * - * @param[in] Limit The number of records to print. - * @param[in] ExcludeFlag TRUE to exclude individual Cumulative items from display - * +/** + Gather and print Raw Profile Records. + + All Profile measurements with a duration greater than or equal to + mInterestThreshold are printed without interpretation. + + The number of records displayed is controlled by: + - records with a duration less than mInterestThreshold microseconds are not displayed. + - No more than Limit records are displayed. A Limit of zero will not limit the output. + - If the ExcludeFlag is TRUE, records matching entries in the CumData array are not + displayed. + + @pre The mInterestThreshold global variable is set to the shortest duration to be printed. + + @param[in] Limit The number of records to print. Zero is ALL. + @param[in] ExcludeFlag TRUE to exclude individual Cumulative items from display. + **/ VOID DumpRawProfile( -- 2.39.2