1 /** @file 2 Provides services to log the execution times and retrieve them later. 3 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 9 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. 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 **/ 44 RETURN_STATUS 45 EFIAPI 46 StartPerformanceMeasurement ( 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 **/ 76 RETURN_STATUS 77 EFIAPI 78 EndPerformanceMeasurement ( 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 **/ 124 UINTN 125 EFIAPI 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 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 **/ 158 RETURN_STATUS 159 EFIAPI 160 StartPerformanceMeasurementEx ( 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 **/ 193 RETURN_STATUS 194 EFIAPI 195 EndPerformanceMeasurementEx ( 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 **/ 244 UINTN 245 EFIAPI 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 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 **/ 268 BOOLEAN 269 EFIAPI 270 PerformanceMeasurementEnabled ( 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