Libraries and utilities for instrumenting regions of code and measuring their perform...
[mirror_edk2.git] / 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 );