2 Base Performance Library which provides no service.
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
11 #include <Library/PerformanceLib.h>
12 #include <Library/DebugLib.h>
13 #include <Library/PcdLib.h>
16 Creates a record for the beginning of a performance measurement.
18 Creates a record that contains the Handle, Token, and Module.
19 If TimeStamp is not zero, then TimeStamp is added to the record as the start time.
20 If TimeStamp is zero, then this function reads the current time stamp
21 and adds that time stamp value to the record as the start time.
23 @param Handle The pointer to environment specific context used
24 to identify the component being measured.
25 @param Token The pointer to a Null-terminated ASCII string
26 that identifies the component being measured.
27 @param Module The pointer to a Null-terminated ASCII string
28 that identifies the module being measured.
29 @param TimeStamp 64-bit time stamp.
31 @retval RETURN_SUCCESS The start of the measurement was recorded.
32 @retval RETURN_OUT_OF_RESOURCES There are not enough resources to record the measurement.
33 @retval RETURN_DEVICE_ERROR A device error reading the time stamp.
38 StartPerformanceMeasurement (
39 IN CONST VOID
*Handle OPTIONAL
,
40 IN CONST CHAR8
*Token OPTIONAL
,
41 IN CONST CHAR8
*Module OPTIONAL
,
45 return RETURN_SUCCESS
;
49 Fills in the end time of a performance measurement.
51 Looks up the record that matches Handle, Token, and Module.
52 If the record can not be found then return RETURN_NOT_FOUND.
53 If the record is found and TimeStamp is not zero,
54 then TimeStamp is added to the record as the end time.
55 If the record is found and TimeStamp is zero, then this function reads
56 the current time stamp and adds that time stamp value to the record as the end time.
58 @param Handle The pointer to environment specific context used
59 to identify the component being measured.
60 @param Token The pointer to a Null-terminated ASCII string
61 that identifies the component being measured.
62 @param Module The pointer to a Null-terminated ASCII string
63 that identifies the module being measured.
64 @param TimeStamp 64-bit time stamp.
66 @retval RETURN_SUCCESS The end of the measurement was recorded.
67 @retval RETURN_NOT_FOUND The specified measurement record could not be found.
68 @retval RETURN_DEVICE_ERROR A device error reading the time stamp.
73 EndPerformanceMeasurement (
74 IN CONST VOID
*Handle OPTIONAL
,
75 IN CONST CHAR8
*Token OPTIONAL
,
76 IN CONST CHAR8
*Module OPTIONAL
,
80 return RETURN_SUCCESS
;
84 Attempts to retrieve a performance measurement log entry from the performance measurement log.
85 It can also retrieve the log created by StartPerformanceMeasurementEx and EndPerformanceMeasurementEx,
86 and then eliminate the Identifier.
88 Attempts to retrieve the performance log entry specified by LogEntryKey. If LogEntryKey is
89 zero on entry, then an attempt is made to retrieve the first entry from the performance log,
90 and the key for the second entry in the log is returned. If the performance log is empty,
91 then no entry is retrieved and zero is returned. If LogEntryKey is not zero, then the performance
92 log entry associated with LogEntryKey is retrieved, and the key for the next entry in the log is
93 returned. If LogEntryKey is the key for the last entry in the log, then the last log entry is
94 retrieved and an implementation specific non-zero key value that specifies the end of the performance
95 log is returned. If LogEntryKey is equal this implementation specific non-zero key value, then no entry
96 is retrieved and zero is returned. In the cases where a performance log entry can be returned,
97 the log entry is returned in Handle, Token, Module, StartTimeStamp, and EndTimeStamp.
98 If LogEntryKey is not a valid log entry key for the performance measurement log, then ASSERT().
99 If Handle is NULL, then ASSERT().
100 If Token is NULL, then ASSERT().
101 If Module is NULL, then ASSERT().
102 If StartTimeStamp is NULL, then ASSERT().
103 If EndTimeStamp is NULL, then ASSERT().
105 @param LogEntryKey On entry, the key of the performance measurement log entry to retrieve.
106 0, then the first performance measurement log entry is retrieved.
107 On exit, the key of the next performance lof entry entry.
108 @param Handle The pointer to environment specific context used to identify the component
110 @param Token The pointer to a Null-terminated ASCII string that identifies the component
112 @param Module The pointer to a Null-terminated ASCII string that identifies the module
114 @param StartTimeStamp The pointer to the 64-bit time stamp that was recorded when the measurement
116 @param EndTimeStamp The pointer to the 64-bit time stamp that was recorded when the measurement
119 @return The key for the next performance log entry (in general case).
124 GetPerformanceMeasurement (
125 IN UINTN LogEntryKey
,
126 OUT CONST VOID
**Handle
,
127 OUT CONST CHAR8
**Token
,
128 OUT CONST CHAR8
**Module
,
129 OUT UINT64
*StartTimeStamp
,
130 OUT UINT64
*EndTimeStamp
133 ASSERT (Handle
!= NULL
);
134 ASSERT (Token
!= NULL
);
135 ASSERT (Module
!= NULL
);
136 ASSERT (StartTimeStamp
!= NULL
);
137 ASSERT (EndTimeStamp
!= NULL
);
143 Creates a record for the beginning of a performance measurement.
145 Creates a record that contains the Handle, Token, Module and Identifier.
146 If TimeStamp is not zero, then TimeStamp is added to the record as the start time.
147 If TimeStamp is zero, then this function reads the current time stamp
148 and adds that time stamp value to the record as the start time.
150 @param Handle Pointer to environment specific context used
151 to identify the component being measured.
152 @param Token Pointer to a Null-terminated ASCII string
153 that identifies the component being measured.
154 @param Module Pointer to a Null-terminated ASCII string
155 that identifies the module being measured.
156 @param TimeStamp 64-bit time stamp.
157 @param Identifier 32-bit identifier. If the value is 0, the created record
158 is same as the one created by StartPerformanceMeasurement.
160 @retval RETURN_SUCCESS The start of the measurement was recorded.
161 @retval RETURN_OUT_OF_RESOURCES There are not enough resources to record the measurement.
162 @retval RETURN_DEVICE_ERROR A device error reading the time stamp.
167 StartPerformanceMeasurementEx (
168 IN CONST VOID
*Handle OPTIONAL
,
169 IN CONST CHAR8
*Token OPTIONAL
,
170 IN CONST CHAR8
*Module OPTIONAL
,
175 return RETURN_SUCCESS
;
179 Fills in the end time of a performance measurement.
181 Looks up the record that matches Handle, Token, Module and Identifier.
182 If the record can not be found then return RETURN_NOT_FOUND.
183 If the record is found and TimeStamp is not zero,
184 then TimeStamp is added to the record as the end time.
185 If the record is found and TimeStamp is zero, then this function reads
186 the current time stamp and adds that time stamp value to the record as the end time.
188 @param Handle Pointer to environment specific context used
189 to identify the component being measured.
190 @param Token Pointer to a Null-terminated ASCII string
191 that identifies the component being measured.
192 @param Module Pointer to a Null-terminated ASCII string
193 that identifies the module being measured.
194 @param TimeStamp 64-bit time stamp.
195 @param Identifier 32-bit identifier. If the value is 0, the found record
196 is same as the one found by EndPerformanceMeasurement.
198 @retval RETURN_SUCCESS The end of the measurement was recorded.
199 @retval RETURN_NOT_FOUND The specified measurement record could not be found.
200 @retval RETURN_DEVICE_ERROR A device error reading the time stamp.
205 EndPerformanceMeasurementEx (
206 IN CONST VOID
*Handle OPTIONAL
,
207 IN CONST CHAR8
*Token OPTIONAL
,
208 IN CONST CHAR8
*Module OPTIONAL
,
213 return RETURN_SUCCESS
;
217 Attempts to retrieve a performance measurement log entry from the performance measurement log.
218 It can also retrieve the log created by StartPerformanceMeasurement and EndPerformanceMeasurement,
219 and then assign the Identifier with 0.
221 Attempts to retrieve the performance log entry specified by LogEntryKey. If LogEntryKey is
222 zero on entry, then an attempt is made to retrieve the first entry from the performance log,
223 and the key for the second entry in the log is returned. If the performance log is empty,
224 then no entry is retrieved and zero is returned. If LogEntryKey is not zero, then the performance
225 log entry associated with LogEntryKey is retrieved, and the key for the next entry in the log is
226 returned. If LogEntryKey is the key for the last entry in the log, then the last log entry is
227 retrieved and an implementation specific non-zero key value that specifies the end of the performance
228 log is returned. If LogEntryKey is equal this implementation specific non-zero key value, then no entry
229 is retrieved and zero is returned. In the cases where a performance log entry can be returned,
230 the log entry is returned in Handle, Token, Module, StartTimeStamp, EndTimeStamp and Identifier.
231 If LogEntryKey is not a valid log entry key for the performance measurement log, then ASSERT().
232 If Handle is NULL, then ASSERT().
233 If Token is NULL, then ASSERT().
234 If Module is NULL, then ASSERT().
235 If StartTimeStamp is NULL, then ASSERT().
236 If EndTimeStamp is NULL, then ASSERT().
237 If Identifier is NULL, then ASSERT().
239 @param LogEntryKey On entry, the key of the performance measurement log entry to retrieve.
240 0, then the first performance measurement log entry is retrieved.
241 On exit, the key of the next performance lof entry entry.
242 @param Handle Pointer to environment specific context used to identify the component
244 @param Token Pointer to a Null-terminated ASCII string that identifies the component
246 @param Module Pointer to a Null-terminated ASCII string that identifies the module
248 @param StartTimeStamp Pointer to the 64-bit time stamp that was recorded when the measurement
250 @param EndTimeStamp Pointer to the 64-bit time stamp that was recorded when the measurement
252 @param Identifier Pointer to the 32-bit identifier that was recorded.
254 @return The key for the next performance log entry (in general case).
259 GetPerformanceMeasurementEx (
260 IN UINTN LogEntryKey
,
261 OUT CONST VOID
**Handle
,
262 OUT CONST CHAR8
**Token
,
263 OUT CONST CHAR8
**Module
,
264 OUT UINT64
*StartTimeStamp
,
265 OUT UINT64
*EndTimeStamp
,
266 OUT UINT32
*Identifier
269 ASSERT (Handle
!= NULL
);
270 ASSERT (Token
!= NULL
);
271 ASSERT (Module
!= NULL
);
272 ASSERT (StartTimeStamp
!= NULL
);
273 ASSERT (EndTimeStamp
!= NULL
);
274 ASSERT (Identifier
!= NULL
);
280 Returns TRUE if the performance measurement macros are enabled.
282 This function returns TRUE if the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
283 PcdPerformanceLibraryPropertyMask is set. Otherwise FALSE is returned.
285 @retval TRUE The PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
286 PcdPerformanceLibraryPropertyMask is set.
287 @retval FALSE The PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
288 PcdPerformanceLibraryPropertyMask is clear.
293 PerformanceMeasurementEnabled (
297 return (BOOLEAN
)((PcdGet8 (PcdPerformanceLibraryPropertyMask
) & PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED
) != 0);
301 Create performance record with event description and a timestamp.
303 @param CallerIdentifier - Image handle or pointer to caller ID GUID
304 @param Guid - Pointer to a GUID
305 @param String - Pointer to a string describing the measurement
306 @param Address - Pointer to a location in memory relevant to the measurement
307 @param Identifier - Performance identifier describing the type of measurement
309 @retval RETURN_SUCCESS - Successfully created performance record
310 @retval RETURN_OUT_OF_RESOURCES - Ran out of space to store the records
311 @retval RETURN_INVALID_PARAMETER - Invalid parameter passed to function - NULL
312 pointer or invalid PerfId
317 LogPerformanceMeasurement (
318 IN CONST VOID
*CallerIdentifier OPTIONAL
,
319 IN CONST VOID
*Guid OPTIONAL
,
320 IN CONST CHAR8
*String OPTIONAL
,
321 IN UINT64 Address OPTIONAL
,
325 return RETURN_SUCCESS
;
329 Check whether the specified performance measurement can be logged.
331 This function returns TRUE when the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set
332 and the Type disable bit in PcdPerformanceLibraryPropertyMask is not set.
334 @param Type - Type of the performance measurement entry.
336 @retval TRUE The performance measurement can be logged.
337 @retval FALSE The performance measurement can NOT be logged.
342 LogPerformanceMeasurementEnabled (
347 // When Performance measurement is enabled and the type is not filtered, the performance can be logged.
349 if (PerformanceMeasurementEnabled () && ((PcdGet8 (PcdPerformanceLibraryPropertyMask
) & Type
) == 0)) {