/** @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
);