audk/PerformancePkg/Dp_App/DpInternal.h

290 lines
8.9 KiB
C

/** @file
* Declarations of objects defined internally to the Dp Application.
*
* Declarations of data and functions which are private to the Dp application.
* This file should never be referenced by anything other than components of the
* Dp application. In addition to global data, function declarations for
* DpUtilities.c, DpTrace.c, and DpProfile.c are included here.
*
* Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR>
* This program and the accompanying materials
* are licensed and made available under the terms and conditions of the BSD License
* which accompanies this distribution. The full text of the license may be found at
* http://opensource.org/licenses/bsd-license.php
*
* THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
* WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
//
/// Module-Global Variables
/// @{
extern EFI_HII_HANDLE gHiiHandle;
extern CHAR16 *mPrintTokenBuffer;
extern CHAR16 mGaugeString[DXE_PERFORMANCE_STRING_SIZE];
extern CHAR16 mUnicodeToken[PERF_TOKEN_LENGTH + 1];
extern UINT64 mInterestThreshold;
extern PERF_SUMMARY_DATA SummaryData;; ///< Create the SummaryData structure and init. to ZERO.
/// Timer Specific Information.
extern TIMER_INFO TimerInfo;
/// Items for which to gather cumulative statistics.
extern PERF_CUM_DATA CumData[];
/// Number of items for which we are gathering cumulative statistics.
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.
**/
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.
**/
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.
*
**/
VOID
GetShortPdbFileName (
IN CHAR8 *PdbFileName,
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.
*
**/
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.
**/
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().
*
**/
UINTN
PrintToken (
IN UINT16 Token,
...
);
/** 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.
**/
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.
**/
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.
*
**/
VOID
DumpAllTrace(
IN UINTN Limit,
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.
*
**/
VOID
DumpRawTrace(
IN UINTN Limit,
IN BOOLEAN ExcludeFlag
);
/** Gather and print Major Phase metrics.
*
* @param[in] Ticker The timer value for the END of Shell phase
*
**/
VOID
ProcessPhases(
IN UINT64 Ticker
);
/** 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().
**/
EFI_STATUS
ProcessHandles(
IN BOOLEAN ExcludeFlag
);
/** 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.
*
*
**/
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.
*
**/
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
*
**/
VOID
DumpAllProfile(
IN UINTN Limit,
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
*
**/
VOID
DumpRawProfile(
IN UINTN Limit,
IN BOOLEAN ExcludeFlag
);