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