4 This library instance provides infrastructure for DXE phase drivers to log performance
5 data. It consumes PerformanceEx or Performance Protocol published by DxeCorePerformanceLib
6 to log performance data. If both PerformanceEx and Performance Protocol is not available, it does not log any
7 performance information.
9 Copyright (c) 2006 - 2018, 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
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.
23 #include <Guid/PerformanceMeasurement.h>
25 #include <Library/PerformanceLib.h>
26 #include <Library/DebugLib.h>
27 #include <Library/UefiBootServicesTableLib.h>
28 #include <Library/PcdLib.h>
31 // The cached Performance Protocol and PerformanceEx Protocol interface.
33 EDKII_PERFORMANCE_MEASUREMENT_PROTOCOL
*mPerformanceMeasurement
= NULL
;
36 The function caches the pointers to PerformanceEx protocol and Performance Protocol.
38 The function locates PerformanceEx protocol and Performance Protocol from protocol database.
40 @retval EFI_SUCCESS PerformanceEx protocol or Performance Protocol is successfully located.
41 @retval EFI_NOT_FOUND Both PerformanceEx protocol and Performance Protocol are not located to log performance.
45 GetPerformanceMeasurementProtocol (
50 EDKII_PERFORMANCE_MEASUREMENT_PROTOCOL
*PerformanceMeasurement
;
52 if (mPerformanceMeasurement
!= NULL
) {
56 Status
= gBS
->LocateProtocol (&gEdkiiPerformanceMeasurementProtocolGuid
, NULL
, (VOID
**) &PerformanceMeasurement
);
57 if (!EFI_ERROR (Status
)) {
58 ASSERT (PerformanceMeasurement
!= NULL
);
60 // Cache PerformanceMeasurement Protocol.
62 mPerformanceMeasurement
= PerformanceMeasurement
;
70 Creates a record for the beginning of a performance measurement.
72 Creates a record that contains the Handle, Token, Module and Identifier.
73 If TimeStamp is not zero, then TimeStamp is added to the record as the start time.
74 If TimeStamp is zero, then this function reads the current time stamp
75 and adds that time stamp value to the record as the start time.
77 @param Handle Pointer to environment specific context used
78 to identify the component being measured.
79 @param Token Pointer to a Null-terminated ASCII string
80 that identifies the component being measured.
81 @param Module Pointer to a Null-terminated ASCII string
82 that identifies the module being measured.
83 @param TimeStamp 64-bit time stamp.
84 @param Identifier 32-bit identifier. If the value is 0, the created record
85 is same as the one created by StartPerformanceMeasurement.
87 @retval RETURN_SUCCESS The start of the measurement was recorded.
88 @retval RETURN_OUT_OF_RESOURCES There are not enough resources to record the measurement.
93 StartPerformanceMeasurementEx (
94 IN CONST VOID
*Handle
, OPTIONAL
95 IN CONST CHAR8
*Token
, OPTIONAL
96 IN CONST CHAR8
*Module
, OPTIONAL
104 Status
= GetPerformanceMeasurementProtocol ();
105 if (EFI_ERROR (Status
)) {
106 return RETURN_NOT_FOUND
;
111 } else if (Module
!= NULL
) {
117 if (mPerformanceMeasurement
!= NULL
) {
118 Status
= mPerformanceMeasurement
->CreatePerformanceMeasurement (Handle
, NULL
, String
, TimeStamp
, 0, Identifier
, PerfStartEntry
);
123 return (RETURN_STATUS
) Status
;
127 Fills in the end time of a performance measurement.
129 Looks up the record that matches Handle, Token and Module.
130 If the record can not be found then return RETURN_NOT_FOUND.
131 If the record is found and TimeStamp is not zero,
132 then TimeStamp is added to the record as the end time.
133 If the record is found and TimeStamp is zero, then this function reads
134 the current time stamp and adds that time stamp value to the record as the end time.
136 @param Handle Pointer to environment specific context used
137 to identify the component being measured.
138 @param Token Pointer to a Null-terminated ASCII string
139 that identifies the component being measured.
140 @param Module Pointer to a Null-terminated ASCII string
141 that identifies the module being measured.
142 @param TimeStamp 64-bit time stamp.
143 @param Identifier 32-bit identifier. If the value is 0, the found record
144 is same as the one found by EndPerformanceMeasurement.
146 @retval RETURN_SUCCESS The end of the measurement was recorded.
147 @retval RETURN_NOT_FOUND The specified measurement record could not be found.
152 EndPerformanceMeasurementEx (
153 IN CONST VOID
*Handle
, OPTIONAL
154 IN CONST CHAR8
*Token
, OPTIONAL
155 IN CONST CHAR8
*Module
, OPTIONAL
163 Status
= GetPerformanceMeasurementProtocol ();
164 if (EFI_ERROR (Status
)) {
165 return RETURN_NOT_FOUND
;
170 } else if (Module
!= NULL
) {
176 if (mPerformanceMeasurement
!= NULL
) {
177 Status
= mPerformanceMeasurement
->CreatePerformanceMeasurement (Handle
, NULL
, String
, TimeStamp
, 0, Identifier
, PerfEndEntry
);
182 return (RETURN_STATUS
) Status
;
186 Attempts to retrieve a performance measurement log entry from the performance measurement log.
187 It can also retrieve the log created by StartPerformanceMeasurement and EndPerformanceMeasurement,
188 and then assign the Identifier with 0.
190 Attempts to retrieve the performance log entry specified by LogEntryKey. If LogEntryKey is
191 zero on entry, then an attempt is made to retrieve the first entry from the performance log,
192 and the key for the second entry in the log is returned. If the performance log is empty,
193 then no entry is retrieved and zero is returned. If LogEntryKey is not zero, then the performance
194 log entry associated with LogEntryKey is retrieved, and the key for the next entry in the log is
195 returned. If LogEntryKey is the key for the last entry in the log, then the last log entry is
196 retrieved and an implementation specific non-zero key value that specifies the end of the performance
197 log is returned. If LogEntryKey is equal this implementation specific non-zero key value, then no entry
198 is retrieved and zero is returned. In the cases where a performance log entry can be returned,
199 the log entry is returned in Handle, Token, Module, StartTimeStamp, EndTimeStamp and Identifier.
200 If LogEntryKey is not a valid log entry key for the performance measurement log, then ASSERT().
201 If Handle is NULL, then ASSERT().
202 If Token is NULL, then ASSERT().
203 If Module is NULL, then ASSERT().
204 If StartTimeStamp is NULL, then ASSERT().
205 If EndTimeStamp is NULL, then ASSERT().
206 If Identifier is NULL, then ASSERT().
208 @param LogEntryKey On entry, the key of the performance measurement log entry to retrieve.
209 0, then the first performance measurement log entry is retrieved.
210 On exit, the key of the next performance log entry.
211 @param Handle Pointer to environment specific context used to identify the component
213 @param Token Pointer to a Null-terminated ASCII string that identifies the component
215 @param Module Pointer to a Null-terminated ASCII string that identifies the module
217 @param StartTimeStamp Pointer to the 64-bit time stamp that was recorded when the measurement
219 @param EndTimeStamp Pointer to the 64-bit time stamp that was recorded when the measurement
221 @param Identifier Pointer to the 32-bit identifier that was recorded.
223 @return The key for the next performance log entry (in general case).
228 GetPerformanceMeasurementEx (
229 IN UINTN LogEntryKey
,
230 OUT CONST VOID
**Handle
,
231 OUT CONST CHAR8
**Token
,
232 OUT CONST CHAR8
**Module
,
233 OUT UINT64
*StartTimeStamp
,
234 OUT UINT64
*EndTimeStamp
,
235 OUT UINT32
*Identifier
243 Creates a record for the beginning of a performance measurement.
245 Creates a record that contains the Handle, Token, and Module.
246 If TimeStamp is not zero, then TimeStamp is added to the record as the start time.
247 If TimeStamp is zero, then this function reads the current time stamp
248 and adds that time stamp value to the record as the start time.
250 @param Handle Pointer to environment specific context used
251 to identify the component being measured.
252 @param Token Pointer to a Null-terminated ASCII string
253 that identifies the component being measured.
254 @param Module Pointer to a Null-terminated ASCII string
255 that identifies the module being measured.
256 @param TimeStamp 64-bit time stamp.
258 @retval RETURN_SUCCESS The start of the measurement was recorded.
259 @retval RETURN_OUT_OF_RESOURCES There are not enough resources to record the measurement.
264 StartPerformanceMeasurement (
265 IN CONST VOID
*Handle
, OPTIONAL
266 IN CONST CHAR8
*Token
, OPTIONAL
267 IN CONST CHAR8
*Module
, OPTIONAL
271 return StartPerformanceMeasurementEx (Handle
, Token
, Module
, TimeStamp
, 0);
275 Fills in the end time of a performance measurement.
277 Looks up the record that matches Handle, Token, and Module.
278 If the record can not be found then return RETURN_NOT_FOUND.
279 If the record is found and TimeStamp is not zero,
280 then TimeStamp is added to the record as the end time.
281 If the record is found and TimeStamp is zero, then this function reads
282 the current time stamp and adds that time stamp value to the record as the end time.
284 @param Handle Pointer to environment specific context used
285 to identify the component being measured.
286 @param Token Pointer to a Null-terminated ASCII string
287 that identifies the component being measured.
288 @param Module Pointer to a Null-terminated ASCII string
289 that identifies the module being measured.
290 @param TimeStamp 64-bit time stamp.
292 @retval RETURN_SUCCESS The end of the measurement was recorded.
293 @retval RETURN_NOT_FOUND The specified measurement record could not be found.
298 EndPerformanceMeasurement (
299 IN CONST VOID
*Handle
, OPTIONAL
300 IN CONST CHAR8
*Token
, OPTIONAL
301 IN CONST CHAR8
*Module
, OPTIONAL
305 return EndPerformanceMeasurementEx (Handle
, Token
, Module
, TimeStamp
, 0);
309 Attempts to retrieve a performance measurement log entry from the performance measurement log.
310 It can also retrieve the log created by StartPerformanceMeasurementEx and EndPerformanceMeasurementEx,
311 and then eliminate the Identifier.
313 Attempts to retrieve the performance log entry specified by LogEntryKey. If LogEntryKey is
314 zero on entry, then an attempt is made to retrieve the first entry from the performance log,
315 and the key for the second entry in the log is returned. If the performance log is empty,
316 then no entry is retrieved and zero is returned. If LogEntryKey is not zero, then the performance
317 log entry associated with LogEntryKey is retrieved, and the key for the next entry in the log is
318 returned. If LogEntryKey is the key for the last entry in the log, then the last log entry is
319 retrieved and an implementation specific non-zero key value that specifies the end of the performance
320 log is returned. If LogEntryKey is equal this implementation specific non-zero key value, then no entry
321 is retrieved and zero is returned. In the cases where a performance log entry can be returned,
322 the log entry is returned in Handle, Token, Module, StartTimeStamp, and EndTimeStamp.
323 If LogEntryKey is not a valid log entry key for the performance measurement log, then ASSERT().
324 If Handle is NULL, then ASSERT().
325 If Token is NULL, then ASSERT().
326 If Module is NULL, then ASSERT().
327 If StartTimeStamp is NULL, then ASSERT().
328 If EndTimeStamp is NULL, then ASSERT().
330 @param LogEntryKey On entry, the key of the performance measurement log entry to retrieve.
331 0, then the first performance measurement log entry is retrieved.
332 On exit, the key of the next performance log entry.
333 @param Handle Pointer to environment specific context used to identify the component
335 @param Token Pointer to a Null-terminated ASCII string that identifies the component
337 @param Module Pointer to a Null-terminated ASCII string that identifies the module
339 @param StartTimeStamp Pointer to the 64-bit time stamp that was recorded when the measurement
341 @param EndTimeStamp Pointer to the 64-bit time stamp that was recorded when the measurement
344 @return The key for the next performance log entry (in general case).
349 GetPerformanceMeasurement (
350 IN UINTN LogEntryKey
,
351 OUT CONST VOID
**Handle
,
352 OUT CONST CHAR8
**Token
,
353 OUT CONST CHAR8
**Module
,
354 OUT UINT64
*StartTimeStamp
,
355 OUT UINT64
*EndTimeStamp
362 Returns TRUE if the performance measurement macros are enabled.
364 This function returns TRUE if the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
365 PcdPerformanceLibraryPropertyMask is set. Otherwise FALSE is returned.
367 @retval TRUE The PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
368 PcdPerformanceLibraryPropertyMask is set.
369 @retval FALSE The PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
370 PcdPerformanceLibraryPropertyMask is clear.
375 PerformanceMeasurementEnabled (
379 return (BOOLEAN
) ((PcdGet8(PcdPerformanceLibraryPropertyMask
) & PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED
) != 0);
383 Create performance record with event description and a timestamp.
385 @param CallerIdentifier - Image handle or pointer to caller ID GUID
386 @param Guid - Pointer to a GUID
387 @param String - Pointer to a string describing the measurement
388 @param Address - Pointer to a location in memory relevant to the measurement
389 @param Identifier - Performance identifier describing the type of measurement
391 @retval RETURN_SUCCESS - Successfully created performance record
392 @retval RETURN_OUT_OF_RESOURCES - Ran out of space to store the records
393 @retval RETURN_INVALID_PARAMETER - Invalid parameter passed to function - NULL
394 pointer or invalid PerfId
399 LogPerformanceMeasurement (
400 IN CONST VOID
*CallerIdentifier
,
401 IN CONST VOID
*Guid
, OPTIONAL
402 IN CONST CHAR8
*String
, OPTIONAL
403 IN UINT64 Address
, OPTIONAL
409 Status
= GetPerformanceMeasurementProtocol ();
410 if (EFI_ERROR (Status
)) {
411 return RETURN_OUT_OF_RESOURCES
;
414 if (mPerformanceMeasurement
!= NULL
) {
415 Status
= mPerformanceMeasurement
->CreatePerformanceMeasurement (CallerIdentifier
, Guid
, String
, 0, Address
, Identifier
, PerfEntry
);
420 return (RETURN_STATUS
) Status
;
424 Check whether the specified performance measurement can be logged.
426 This function returns TRUE when the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set
427 and the Type disable bit in PcdPerformanceLibraryPropertyMask is not set.
429 @param Type - Type of the performance measurement entry.
431 @retval TRUE The performance measurement can be logged.
432 @retval FALSE The performance measurement can NOT be logged.
437 LogPerformanceMeasurementEnabled (
442 // When Performance measurement is enabled and the type is not filtered, the performance can be logged.
444 if (PerformanceMeasurementEnabled () && (PcdGet8(PcdPerformanceLibraryPropertyMask
) & Type
) == 0) {