PerformancePkg/Dp_App/DpInternal.h

   1 /** @file
   2   * Declarations of objects defined internally to the Dp Application.
   3   *
   4   * Declarations of data and functions which are private to the Dp application.
   5   * This file should never be referenced by anything other than components of the
   6   * Dp application.  In addition to global data, function declarations for
   7   * DpUtilities.c, DpTrace.c, and DpProfile.c are included here.
   8   *
   9   * Copyright (c) 2009-2010, Intel Corporation. All rights reserved.<BR>
  10   * This program and the accompanying materials
  11   * are licensed and made available under the terms and conditions of the BSD License
  12   * which accompanies this distribution.  The full text of the license may be found at
  13   * http://opensource.org/licenses/bsd-license.php
  14   *
  15   * THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  16   * WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  17 **/
  18
  19 //
  20 /// Module-Global Variables
  21 /// @{
  22 extern EFI_HII_HANDLE     gHiiHandle;
  23 extern CHAR16             *mPrintTokenBuffer;
  24 extern CHAR16             mGaugeString[DXE_PERFORMANCE_STRING_SIZE];
  25 extern CHAR16             mUnicodeToken[PERF_TOKEN_LENGTH + 1];
  26 extern UINT64             mInterestThreshold;
  27
  28 extern PERF_SUMMARY_DATA  SummaryData;;    ///< Create the SummaryData structure and init. to ZERO.
  29
  30 /// Timer Specific Information.
  31 extern TIMER_INFO         TimerInfo;
  32
  33 /// Items for which to gather cumulative statistics.
  34 extern PERF_CUM_DATA      CumData[];
  35
  36 /// Number of items for which we are gathering cumulative statistics.
  37 extern UINT32 const       NumCum;
  38
  39 /// @}
  40
  41 /** Calculate an event's duration in timer ticks.
  42   *
  43   * Given the count direction and the event's start and end timer values,
  44   * calculate the duration of the event in timer ticks.
  45   *
  46   * @pre  The global TimerInfo structure must have already been initialized
  47   *       before this function is called.
  48   *
  49   * @param[in,out]    Measurement   Pointer to a structure containing data for the current measurement.
  50   *
  51   * @return       The 64-bit duration of the event.
  52 **/
  53 UINT64
  54 GetDuration (
  55   IN OUT MEASUREMENT_RECORD *Measurement
  56 );
  57
  58 /** Determine whether the Measurement record is for an EFI Phase.
  59   *
  60   * The Token and Module members of the measurement record are checked.
  61   * Module must be empty and Token must be one of SEC, PEI, DXE, or BDS.
  62   *
  63   * @param[in]  Measurement A pointer to the Measurement record to test.
  64   *
  65   * @retval     TRUE        The measurement record is for an EFI Phase.
  66   * @retval     FALSE       The measurement record is NOT for an EFI Phase.
  67 **/
  68 BOOLEAN
  69 IsPhase(
  70   IN MEASUREMENT_RECORD *Measurement
  71 );
  72
  73 /** Get the file name portion of the Pdb File Name.
  74   *
  75   * The portion of the Pdb File Name between the last backslash and
  76   * either a following period or the end of the string is converted
  77   * to Unicode and copied into UnicodeBuffer.  The name is truncated,
  78   * if necessary, to ensure that UnicodeBuffer is not overrun.
  79   *
  80   * @param[in]  PdbFileName     Pdb file name.
  81   * @param[out] UnicodeBuffer   The resultant Unicode File Name.
  82   *
  83 **/
  84 VOID
  85 GetShortPdbFileName (
  86   IN  CHAR8     *PdbFileName,
  87   OUT CHAR16    *UnicodeBuffer
  88 );
  89
  90 /** Get a human readable name for an image handle.
  91   *
  92   * @param[in]    Handle
  93   *
  94   * @post   The resulting Unicode name string is stored in the
  95   *         mGaugeString global array.
  96   *
  97 **/
  98 VOID
  99 GetNameFromHandle (
 100   IN EFI_HANDLE Handle
 101 );
 102
 103 /** Calculate the Duration in microseconds.
 104   *
 105   * Duration is multiplied by 1000, instead of Frequency being divided by 1000
 106   * in order to maintain precision.  Since Duration is
 107   * a 64-bit value, multiplying it by 1000 is unlikely to produce an overflow.
 108   *
 109   * @param[in] Duration   The event duration in timer ticks.
 110   *
 111   * @return   A 64-bit value which is the Elapsed time in microseconds.
 112 **/
 113 UINT64
 114 DurationInMicroSeconds (
 115   IN UINT64 Duration
 116 );
 117
 118 /** Formatted Print using a Hii Token to reference the localized format string.
 119   *
 120   * @param[in]  Token   A HII token associated with a localized Unicode string.
 121   *
 122   * @return             The number of characters converted by UnicodeVSPrint().
 123   *
 124 **/
 125 UINTN
 126 PrintToken (
 127   IN UINT16 Token,
 128   ...
 129 );
 130
 131 /** Get index of Measurement Record's match in the CumData array.
 132   *
 133   * @param[in]  Measurement A pointer to a Measurement Record to match against the CumData array.
 134   *
 135   * @retval     <0    Token is not in the CumData array.
 136   * @retval     >=0   Return value is the index into CumData where Token is found.
 137 **/
 138 INTN
 139 GetCumulativeItem(
 140   IN MEASUREMENT_RECORD *Measurement
 141 );
 142
 143 /** Collect verbose statistics about the logged performance measurements.
 144   *
 145   * General Summary information for all Trace measurements is gathered and
 146   * stored within the SummaryData structure.  This information is both
 147   * used internally by subsequent reporting functions, and displayed
 148   * at the end of verbose reports.
 149   *
 150   * @pre  The SummaryData and CumData structures must be initialized
 151   *       prior to calling this function.
 152   *
 153   * @post The SummaryData and CumData structures contain statistics for the
 154   *       current performance logs.
 155 **/
 156 VOID
 157 GatherStatistics(
 158   VOID
 159 );
 160
 161 /** Gather and print ALL Trace Records.
 162   *
 163   * Displays all "interesting" Trace measurements in order.
 164   * The number of records displayed is controlled by:
 165   *   - records with a duration less than mInterestThreshold microseconds are not displayed.
 166   *   - No more than Limit records are displayed.  A Limit of zero will not limit the output.
 167   *   - If the ExcludeFlag is TRUE, records matching entries in the CumData array are not
 168   *     displayed.
 169   *
 170   * @pre    The mInterestThreshold global variable is set to the shortest duration to be printed.
 171   *         The mGaugeString and mUnicodeToken global arrays are used for temporary string storage.
 172   *         They must not be in use by a calling function.
 173   *
 174   * @param[in]    Limit       The number of records to print.  Zero is ALL.
 175   * @param[in]    ExcludeFlag TRUE to exclude individual Cumulative items from display.
 176   *
 177 **/
 178 VOID
 179 DumpAllTrace(
 180   IN UINTN             Limit,
 181   IN BOOLEAN           ExcludeFlag
 182 );
 183
 184 /** Gather and print Raw Trace Records.
 185   *
 186   * All Trace measurements with a duration greater than or equal to
 187   * mInterestThreshold are printed without interpretation.
 188   *
 189   * The number of records displayed is controlled by:
 190   *   - records with a duration less than mInterestThreshold microseconds are not displayed.
 191   *   - No more than Limit records are displayed.  A Limit of zero will not limit the output.
 192   *   - If the ExcludeFlag is TRUE, records matching entries in the CumData array are not
 193   *     displayed.
 194   *
 195   * @pre    The mInterestThreshold global variable is set to the shortest duration to be printed.
 196   *
 197   * @param[in]    Limit       The number of records to print.  Zero is ALL.
 198   * @param[in]    ExcludeFlag TRUE to exclude individual Cumulative items from display.
 199   *
 200 **/
 201 VOID
 202 DumpRawTrace(
 203   IN UINTN          Limit,
 204   IN BOOLEAN        ExcludeFlag
 205 );
 206
 207 /** Gather and print Major Phase metrics.
 208   *
 209   * @param[in]    Ticker      The timer value for the END of Shell phase
 210   *
 211 **/
 212 VOID
 213 ProcessPhases(
 214   IN UINT64 Ticker
 215 );
 216
 217
 218 /** Gather and print Handle data.
 219   *
 220   * @param[in]    ExcludeFlag   TRUE if the -x command line flag given.  Elides accumulated trace records.
 221   *
 222   * @return       Status from a call to gBS->LocateHandle().
 223 **/
 224 EFI_STATUS
 225 ProcessHandles(
 226   IN BOOLEAN ExcludeFlag
 227 );
 228
 229
 230 /** Gather and print PEIM data.
 231   *
 232   * Only prints complete PEIM records
 233   *
 234 **/
 235 VOID
 236 ProcessPeims(
 237   VOID
 238 );
 239
 240 /** Gather and print global data.
 241   *
 242   * Strips out incomplete or "Execution Phase" records
 243   * Only prints records where Handle is NULL
 244   * Increment TIndex for every record, even skipped ones, so that we have an
 245   * indication of every measurement record taken.
 246   *
 247   *
 248 **/
 249 VOID
 250 ProcessGlobal(
 251   VOID
 252 );
 253
 254 /** Gather and print cumulative data.
 255   *
 256   * Traverse the measurement records and:
 257   * for each record with a Token listed in the CumData array,
 258   *   Update the instance count and the total, minimum, and maximum durations.
 259   * Finally, print the gathered cumulative statistics.
 260   *
 261 **/
 262 VOID
 263 ProcessCumulative(
 264   VOID
 265 );
 266
 267 /** Gather and print ALL Profile Records.
 268   *
 269   * @param[in]    Limit       The number of records to print.  Zero is ALL.
 270   * @param[in]    ExcludeFlag TRUE to exclude individual Cumulative items from display
 271   *
 272 **/
 273 VOID
 274 DumpAllProfile(
 275   IN UINTN          Limit,
 276   IN BOOLEAN        ExcludeFlag
 277 );
 278
 279 /** Gather and print Raw Profile Records.
 280   *
 281   * @param[in]    Limit       The number of records to print.
 282   * @param[in]    ExcludeFlag TRUE to exclude individual Cumulative items from display
 283   *
 284 **/
 285 VOID
 286 DumpRawProfile(
 287   IN UINTN          Limit,
 288   IN BOOLEAN        ExcludeFlag
 289 );