[mirror_edk2.git] / PerformancePkg / Dp_App / DpInternal.h

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