Refine coding style.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@11049 6f19259b-4bc3-4df7-8a09-765794883524

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.<BR>

+  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:<BR>

+  For each record with a Token listed in the CumData array:<BR>

+     - 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(