MdePkg/Include/Library/PerformanceLib.h

   1 /** @file
   2   Provides services to log the execution times and retrieve them later.
   3
   4 Copyright (c) 2006 - 2016, 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 and Module.
 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