]>
git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Library/PerformanceLib.h
2 Provides services to log the execution times and retrieve them later.
4 Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 #ifndef __PERFORMANCE_LIB_H__
16 #define __PERFORMANCE_LIB_H__
19 /// Performance library propery mask bits
21 #define PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED 0x00000001
24 Creates a record for the beginning of a performance measurement.
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.
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.
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.
46 StartPerformanceMeasurement (
47 IN CONST VOID
*Handle
, OPTIONAL
48 IN CONST CHAR8
*Token
, OPTIONAL
49 IN CONST CHAR8
*Module
, OPTIONAL
54 Fills in the end time of a performance measurement.
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.
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.
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.
78 EndPerformanceMeasurement (
79 IN CONST VOID
*Handle
, OPTIONAL
80 IN CONST CHAR8
*Token
, OPTIONAL
81 IN CONST CHAR8
*Module
, OPTIONAL
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.
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().
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
112 @param Token Pointer to a Null-terminated ASCII string that identifies the component
114 @param Module Pointer to a Null-terminated ASCII string that identifies the module
116 @param StartTimeStamp Pointer to the 64-bit time stamp that was recorded when the measurement
118 @param EndTimeStamp Pointer to the 64-bit time stamp that was recorded when the measurement
121 @return The key for the next performance log entry (in general case).
126 GetPerformanceMeasurement (
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
136 Creates a record for the beginning of a performance measurement.
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.
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.
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.
160 StartPerformanceMeasurementEx (
161 IN CONST VOID
*Handle
, OPTIONAL
162 IN CONST CHAR8
*Token
, OPTIONAL
163 IN CONST CHAR8
*Module
, OPTIONAL
169 Fills in the end time of a performance measurement.
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.
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.
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.
195 EndPerformanceMeasurementEx (
196 IN CONST VOID
*Handle
, OPTIONAL
197 IN CONST CHAR8
*Token
, OPTIONAL
198 IN CONST CHAR8
*Module
, OPTIONAL
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.
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().
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
231 @param Token Pointer to a Null-terminated ASCII string that identifies the component
233 @param Module Pointer to a Null-terminated ASCII string that identifies the module
235 @param StartTimeStamp Pointer to the 64-bit time stamp that was recorded when the measurement
237 @param EndTimeStamp Pointer to the 64-bit time stamp that was recorded when the measurement
239 @param Identifier Pointer to the 32-bit identifier that was recorded.
241 @return The key for the next performance log entry (in general case).
246 GetPerformanceMeasurementEx (
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
257 Returns TRUE if the performance measurement macros are enabled.
259 This function returns TRUE if the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
260 PcdPerformanceLibraryPropertyMask is set. Otherwise FALSE is returned.
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.
270 PerformanceMeasurementEnabled (
275 Macro that calls EndPerformanceMeasurement().
277 If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set,
278 then EndPerformanceMeasurement() is called.
281 #define PERF_END(Handle, Token, Module, TimeStamp) \
283 if (PerformanceMeasurementEnabled ()) { \
284 EndPerformanceMeasurement (Handle, Token, Module, TimeStamp); \
289 Macro that calls StartPerformanceMeasurement().
291 If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set,
292 then StartPerformanceMeasurement() is called.
295 #define PERF_START(Handle, Token, Module, TimeStamp) \
297 if (PerformanceMeasurementEnabled ()) { \
298 StartPerformanceMeasurement (Handle, Token, Module, TimeStamp); \
303 Macro that calls EndPerformanceMeasurementEx().
305 If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set,
306 then EndPerformanceMeasurementEx() is called.
309 #define PERF_END_EX(Handle, Token, Module, TimeStamp, Identifier) \
311 if (PerformanceMeasurementEnabled ()) { \
312 EndPerformanceMeasurementEx (Handle, Token, Module, TimeStamp, Identifier); \
317 Macro that calls StartPerformanceMeasurementEx().
319 If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set,
320 then StartPerformanceMeasurementEx() is called.
323 #define PERF_START_EX(Handle, Token, Module, TimeStamp, Identifier) \
325 if (PerformanceMeasurementEnabled ()) { \
326 StartPerformanceMeasurementEx (Handle, Token, Module, TimeStamp, Identifier); \
331 Macro that marks the beginning of performance measurement source code.
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.
338 #define PERF_CODE_BEGIN() do { if (PerformanceMeasurementEnabled ()) { UINT8 __PerformanceCodeLocal
341 Macro that marks the end of performance measurement source code.
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.
348 #define PERF_CODE_END() __PerformanceCodeLocal = 0; __PerformanceCodeLocal++; } } while (FALSE)
351 Macro that declares a section of performance measurement source code.
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.
357 @param Expression Performance measurement source code to include in a module.
360 #define PERF_CODE(Expression) \
361 PERF_CODE_BEGIN (); \