1/** @file
2  Provides services to log the execution times and retrieve them later.
3
4Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>
5This program and the accompanying materials
6are licensed and made available under the terms and conditions of the BSD License
7which accompanies this distribution.  The full text of the license may be found at
8http://opensource.org/licenses/bsd-license.php
9
10THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13**/
14
15#ifndef __PERFORMANCE_LIB_H__
16#define __PERFORMANCE_LIB_H__
17
18///
19/// Performance library propery mask bits
20///
21#define PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED  0x00000001
22
23/**
24  Creates a record for the beginning of a performance measurement.
25
26  Creates a record that contains the Handle, Token, and Module.
27  If TimeStamp is not zero, then TimeStamp is added to the record as the start time.
28  If TimeStamp is zero, then this function reads the current time stamp
29  and adds that time stamp value to the record as the start time.
30
31  @param  Handle                  Pointer to environment specific context used
32                                  to identify the component being measured.
33  @param  Token                   Pointer to a Null-terminated ASCII string
34                                  that identifies the component being measured.
35  @param  Module                  Pointer to a Null-terminated ASCII string
36                                  that identifies the module being measured.
37  @param  TimeStamp               64-bit time stamp.
38
39  @retval RETURN_SUCCESS          The start of the measurement was recorded.
40  @retval RETURN_OUT_OF_RESOURCES There are not enough resources to record the measurement.
41  @retval RETURN_DEVICE_ERROR     A device error reading the time stamp.
42
43**/
44RETURN_STATUS
45EFIAPI
46StartPerformanceMeasurement (
47  IN CONST VOID   *Handle,  OPTIONAL
48  IN CONST CHAR8  *Token,   OPTIONAL
49  IN CONST CHAR8  *Module,  OPTIONAL
50  IN UINT64       TimeStamp
51  );
52
53/**
54  Fills in the end time of a performance measurement.
55
56  Looks up the record that matches Handle, Token, and Module.
57  If the record can not be found then return RETURN_NOT_FOUND.
58  If the record is found and TimeStamp is not zero,
59  then TimeStamp is added to the record as the end time.
60  If the record is found and TimeStamp is zero, then this function reads
61  the current time stamp and adds that time stamp value to the record as the end time.
62
63  @param  Handle                  Pointer to environment specific context used
64                                  to identify the component being measured.
65  @param  Token                   Pointer to a Null-terminated ASCII string
66                                  that identifies the component being measured.
67  @param  Module                  Pointer to a Null-terminated ASCII string
68                                  that identifies the module being measured.
69  @param  TimeStamp               64-bit time stamp.
70
71  @retval RETURN_SUCCESS          The end of  the measurement was recorded.
72  @retval RETURN_NOT_FOUND        The specified measurement record could not be found.
73  @retval RETURN_DEVICE_ERROR     A device error reading the time stamp.
74
75**/
76RETURN_STATUS
77EFIAPI
78EndPerformanceMeasurement (
79  IN CONST VOID   *Handle,  OPTIONAL
80  IN CONST CHAR8  *Token,   OPTIONAL
81  IN CONST CHAR8  *Module,  OPTIONAL
82  IN UINT64       TimeStamp
83  );
84
85/**
86  Attempts to retrieve a performance measurement log entry from the performance measurement log.
87  It can also retrieve the log created by StartPerformanceMeasurementEx and EndPerformanceMeasurementEx,
88  and then eliminate the Identifier.
89
90  Attempts to retrieve the performance log entry specified by LogEntryKey.  If LogEntryKey is
91  zero on entry, then an attempt is made to retrieve the first entry from the performance log,
92  and the key for the second entry in the log is returned.  If the performance log is empty,
93  then no entry is retrieved and zero is returned.  If LogEntryKey is not zero, then the performance
94  log entry associated with LogEntryKey is retrieved, and the key for the next entry in the log is
95  returned.  If LogEntryKey is the key for the last entry in the log, then the last log entry is
96  retrieved and an implementation specific non-zero key value that specifies the end of the performance
97  log is returned.  If LogEntryKey is equal this implementation specific non-zero key value, then no entry
98  is retrieved and zero is returned.  In the cases where a performance log entry can be returned,
99  the log entry is returned in Handle, Token, Module, StartTimeStamp, and EndTimeStamp.
100  If LogEntryKey is not a valid log entry key for the performance measurement log, then ASSERT().
101  If Handle is NULL, then ASSERT().
102  If Token is NULL, then ASSERT().
103  If Module is NULL, then ASSERT().
104  If StartTimeStamp is NULL, then ASSERT().
105  If EndTimeStamp is NULL, then ASSERT().
106
107  @param  LogEntryKey             On entry, the key of the performance measurement log entry to retrieve.
108                                  0, then the first performance measurement log entry is retrieved.
109                                  On exit, the key of the next performance lof entry entry.
110  @param  Handle                  Pointer to environment specific context used to identify the component
111                                  being measured.
112  @param  Token                   Pointer to a Null-terminated ASCII string that identifies the component
113                                  being measured.
114  @param  Module                  Pointer to a Null-terminated ASCII string that identifies the module
115                                  being measured.
116  @param  StartTimeStamp          Pointer to the 64-bit time stamp that was recorded when the measurement
117                                  was started.
118  @param  EndTimeStamp            Pointer to the 64-bit time stamp that was recorded when the measurement
119                                  was ended.
120
121  @return The key for the next performance log entry (in general case).
122
123**/
124UINTN
125EFIAPI
126GetPerformanceMeasurement (
127  IN  UINTN       LogEntryKey,
128  OUT CONST VOID  **Handle,
129  OUT CONST CHAR8 **Token,
130  OUT CONST CHAR8 **Module,
131  OUT UINT64      *StartTimeStamp,
132  OUT UINT64      *EndTimeStamp
133  );
134
135/**
136  Creates a record for the beginning of a performance measurement.
137
138  Creates a record that contains the Handle, Token, Module and Identifier.
139  If TimeStamp is not zero, then TimeStamp is added to the record as the start time.
140  If TimeStamp is zero, then this function reads the current time stamp
141  and adds that time stamp value to the record as the start time.
142
143  @param  Handle                  Pointer to environment specific context used
144                                  to identify the component being measured.
145  @param  Token                   Pointer to a Null-terminated ASCII string
146                                  that identifies the component being measured.
147  @param  Module                  Pointer to a Null-terminated ASCII string
148                                  that identifies the module being measured.
149  @param  TimeStamp               64-bit time stamp.
150  @param  Identifier              32-bit identifier. If the value is 0, the created record
151                                  is same as the one created by StartPerformanceMeasurement.
152
153  @retval RETURN_SUCCESS          The start of the measurement was recorded.
154  @retval RETURN_OUT_OF_RESOURCES There are not enough resources to record the measurement.
155  @retval RETURN_DEVICE_ERROR     A device error reading the time stamp.
156
157**/
158RETURN_STATUS
159EFIAPI
160StartPerformanceMeasurementEx (
161  IN CONST VOID   *Handle,  OPTIONAL
162  IN CONST CHAR8  *Token,   OPTIONAL
163  IN CONST CHAR8  *Module,  OPTIONAL
164  IN UINT64       TimeStamp,
165  IN UINT32       Identifier
166  );
167
168/**
169  Fills in the end time of a performance measurement.
170
171  Looks up the record that matches Handle, Token, Module and Identifier.
172  If the record can not be found then return RETURN_NOT_FOUND.
173  If the record is found and TimeStamp is not zero,
174  then TimeStamp is added to the record as the end time.
175  If the record is found and TimeStamp is zero, then this function reads
176  the current time stamp and adds that time stamp value to the record as the end time.
177
178  @param  Handle                  Pointer to environment specific context used
179                                  to identify the component being measured.
180  @param  Token                   Pointer to a Null-terminated ASCII string
181                                  that identifies the component being measured.
182  @param  Module                  Pointer to a Null-terminated ASCII string
183                                  that identifies the module being measured.
184  @param  TimeStamp               64-bit time stamp.
185  @param  Identifier              32-bit identifier. If the value is 0, the found record
186                                  is same as the one found by EndPerformanceMeasurement.
187
188  @retval RETURN_SUCCESS          The end of  the measurement was recorded.
189  @retval RETURN_NOT_FOUND        The specified measurement record could not be found.
190  @retval RETURN_DEVICE_ERROR     A device error reading the time stamp.
191
192**/
193RETURN_STATUS
194EFIAPI
195EndPerformanceMeasurementEx (
196  IN CONST VOID   *Handle,  OPTIONAL
197  IN CONST CHAR8  *Token,   OPTIONAL
198  IN CONST CHAR8  *Module,  OPTIONAL
199  IN UINT64       TimeStamp,
200  IN UINT32       Identifier
201  );
202
203/**
204  Attempts to retrieve a performance measurement log entry from the performance measurement log.
205  It can also retrieve the log created by StartPerformanceMeasurement and EndPerformanceMeasurement,
206  and then assign the Identifier with 0.
207
208  Attempts to retrieve the performance log entry specified by LogEntryKey.  If LogEntryKey is
209  zero on entry, then an attempt is made to retrieve the first entry from the performance log,
210  and the key for the second entry in the log is returned.  If the performance log is empty,
211  then no entry is retrieved and zero is returned.  If LogEntryKey is not zero, then the performance
212  log entry associated with LogEntryKey is retrieved, and the key for the next entry in the log is
213  returned.  If LogEntryKey is the key for the last entry in the log, then the last log entry is
214  retrieved and an implementation specific non-zero key value that specifies the end of the performance
215  log is returned.  If LogEntryKey is equal this implementation specific non-zero key value, then no entry
216  is retrieved and zero is returned.  In the cases where a performance log entry can be returned,
217  the log entry is returned in Handle, Token, Module, StartTimeStamp, EndTimeStamp and Identifier.
218  If LogEntryKey is not a valid log entry key for the performance measurement log, then ASSERT().
219  If Handle is NULL, then ASSERT().
220  If Token is NULL, then ASSERT().
221  If Module is NULL, then ASSERT().
222  If StartTimeStamp is NULL, then ASSERT().
223  If EndTimeStamp is NULL, then ASSERT().
224  If Identifier is NULL, then ASSERT().
225
226  @param  LogEntryKey             On entry, the key of the performance measurement log entry to retrieve.
227                                  0, then the first performance measurement log entry is retrieved.
228                                  On exit, the key of the next performance of entry entry.
229  @param  Handle                  Pointer to environment specific context used to identify the component
230                                  being measured.
231  @param  Token                   Pointer to a Null-terminated ASCII string that identifies the component
232                                  being measured.
233  @param  Module                  Pointer to a Null-terminated ASCII string that identifies the module
234                                  being measured.
235  @param  StartTimeStamp          Pointer to the 64-bit time stamp that was recorded when the measurement
236                                  was started.
237  @param  EndTimeStamp            Pointer to the 64-bit time stamp that was recorded when the measurement
238                                  was ended.
239  @param  Identifier              Pointer to the 32-bit identifier that was recorded.
240
241  @return The key for the next performance log entry (in general case).
242
243**/
244UINTN
245EFIAPI
246GetPerformanceMeasurementEx (
247  IN  UINTN       LogEntryKey,
248  OUT CONST VOID  **Handle,
249  OUT CONST CHAR8 **Token,
250  OUT CONST CHAR8 **Module,
251  OUT UINT64      *StartTimeStamp,
252  OUT UINT64      *EndTimeStamp,
253  OUT UINT32      *Identifier
254  );
255
256/**
257  Returns TRUE if the performance measurement macros are enabled.
258
259  This function returns TRUE if the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
260  PcdPerformanceLibraryPropertyMask is set.  Otherwise FALSE is returned.
261
262  @retval TRUE                    The PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
263                                  PcdPerformanceLibraryPropertyMask is set.
264  @retval FALSE                   The PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
265                                  PcdPerformanceLibraryPropertyMask is clear.
266
267**/
268BOOLEAN
269EFIAPI
270PerformanceMeasurementEnabled (
271  VOID
272  );
273
274/**
275  Macro that calls EndPerformanceMeasurement().
276
277  If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set,
278  then EndPerformanceMeasurement() is called.
279
280**/
281#define PERF_END(Handle, Token, Module, TimeStamp)                    \
282  do {                                                                \
283    if (PerformanceMeasurementEnabled ()) {                           \
284      EndPerformanceMeasurement (Handle, Token, Module, TimeStamp);   \
285    }                                                                 \
286  } while (FALSE)
287
288/**
289  Macro that calls StartPerformanceMeasurement().
290
291  If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set,
292  then StartPerformanceMeasurement() is called.
293
294**/
295#define PERF_START(Handle, Token, Module, TimeStamp)                  \
296  do {                                                                \
297    if (PerformanceMeasurementEnabled ()) {                           \
298      StartPerformanceMeasurement (Handle, Token, Module, TimeStamp); \
299    }                                                                 \
300  } while (FALSE)
301
302/**
303  Macro that calls EndPerformanceMeasurementEx().
304
305  If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set,
306  then EndPerformanceMeasurementEx() is called.
307
308**/
309#define PERF_END_EX(Handle, Token, Module, TimeStamp, Identifier)                   \
310  do {                                                                              \
311    if (PerformanceMeasurementEnabled ()) {                                         \
312      EndPerformanceMeasurementEx (Handle, Token, Module, TimeStamp, Identifier);   \
313    }                                                                               \
314  } while (FALSE)
315
316/**
317  Macro that calls StartPerformanceMeasurementEx().
318
319  If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set,
320  then StartPerformanceMeasurementEx() is called.
321
322**/
323#define PERF_START_EX(Handle, Token, Module, TimeStamp, Identifier)                 \
324  do {                                                                              \
325    if (PerformanceMeasurementEnabled ()) {                                         \
326      StartPerformanceMeasurementEx (Handle, Token, Module, TimeStamp, Identifier); \
327    }                                                                               \
328  } while (FALSE)
329
330/**
331  Macro that marks the beginning of performance measurement source code.
332
333  If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set,
334  then this macro marks the beginning of source code that is included in a module.
335  Otherwise, the source lines between PERF_CODE_BEGIN() and PERF_CODE_END() are not included in a module.
336
337**/
338#define PERF_CODE_BEGIN()  do { if (PerformanceMeasurementEnabled ()) { UINT8  __PerformanceCodeLocal
339
340/**
341  Macro that marks the end of performance measurement source code.
342
343  If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set,
344  then this macro marks the end of source code that is included in a module.
345  Otherwise, the source lines between PERF_CODE_BEGIN() and PERF_CODE_END() are not included in a module.
346
347**/
348#define PERF_CODE_END()    __PerformanceCodeLocal = 0; __PerformanceCodeLocal++; } } while (FALSE)
349
350/**
351  Macro that declares a section of performance measurement source code.
352
353  If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set,
354  then the source code specified by Expression is included in a module.
355  Otherwise, the source specified by Expression is not included in a module.
356
357  @param  Expression              Performance measurement source code to include in a module.
358
359**/
360#define PERF_CODE(Expression)  \
361  PERF_CODE_BEGIN ();          \
362  Expression                   \
363  PERF_CODE_END ()
364
365
366#endif
367