MdeModulePkg/Library/DxePerformanceLib/DxePerformanceLib.c

   1 /** @file
   2   Performance Library
   3
   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.
   8
   9   Copyright (c) 2006 - 2016, 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
  14
  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.
  17
  18 **/
  19
  20
  21 #include <PiDxe.h>
  22
  23 #include <Guid/PerformanceMeasurement.h>
  24
  25 #include <Library/PerformanceLib.h>
  26 #include <Library/DebugLib.h>
  27 #include <Library/UefiBootServicesTableLib.h>
  28 #include <Library/PcdLib.h>
  29
  30 //
  31 // The cached Performance Protocol and PerformanceEx Protocol interface.
  32 //
  33 EDKII_PERFORMANCE_MEASUREMENT_PROTOCOL      *mPerformanceMeasurement = NULL;
  34
  35 /**
  36   The function caches the pointers to PerformanceEx protocol and Performance Protocol.
  37
  38   The function locates PerformanceEx protocol and Performance Protocol from protocol database.
  39
  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.
  42
  43 **/
  44 EFI_STATUS
  45 GetPerformanceMeasurementProtocol (
  46   VOID
  47   )
  48 {
  49   EFI_STATUS                Status;
  50   EDKII_PERFORMANCE_MEASUREMENT_PROTOCOL   *PerformanceMeasurement;
  51
  52   if (mPerformanceMeasurement != NULL) {
  53     return EFI_SUCCESS;
  54   }
  55
  56   Status = gBS->LocateProtocol (&gEdkiiPerformanceMeasurementProtocolGuid, NULL, (VOID **) &PerformanceMeasurement);
  57   if (!EFI_ERROR (Status)) {
  58     ASSERT (PerformanceMeasurement != NULL);
  59     //
  60     // Cache PerformanceMeasurement Protocol.
  61     //
  62     mPerformanceMeasurement = PerformanceMeasurement;
  63     return EFI_SUCCESS;
  64   }
  65
  66   return EFI_NOT_FOUND;
  67 }
  68
  69 /**
  70   Creates a record for the beginning of a performance measurement.
  71
  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.
  76
  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.
  86
  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.
  89
  90 **/
  91 RETURN_STATUS
  92 EFIAPI
  93 StartPerformanceMeasurementEx (
  94   IN CONST VOID   *Handle,  OPTIONAL
  95   IN CONST CHAR8  *Token,   OPTIONAL
  96   IN CONST CHAR8  *Module,  OPTIONAL
  97   IN UINT64       TimeStamp,
  98   IN UINT32       Identifier
  99   )
 100 {
 101   EFI_STATUS    Status;
 102   CONST CHAR8*  String;
 103
 104   Status = GetPerformanceMeasurementProtocol ();
 105   if (EFI_ERROR (Status)) {
 106     return RETURN_NOT_FOUND;
 107   }
 108
 109   if (Token != NULL) {
 110     String = Token;
 111   } else if (Module != NULL) {
 112     String = Module;
 113   } else {
 114     String = NULL;
 115   }
 116
 117   if (mPerformanceMeasurement != NULL) {
 118     Status = mPerformanceMeasurement->CreatePerformanceMeasurement (Handle, NULL, String, TimeStamp, 0, Identifier, PerfStartEntry);
 119   } else {
 120     ASSERT (FALSE);
 121   }
 122
 123   return (RETURN_STATUS) Status;
 124 }
 125
 126 /**
 127   Fills in the end time of a performance measurement.
 128
 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.
 135
 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.
 145
 146   @retval RETURN_SUCCESS          The end of  the measurement was recorded.
 147   @retval RETURN_NOT_FOUND        The specified measurement record could not be found.
 148
 149 **/
 150 RETURN_STATUS
 151 EFIAPI
 152 EndPerformanceMeasurementEx (
 153   IN CONST VOID   *Handle,  OPTIONAL
 154   IN CONST CHAR8  *Token,   OPTIONAL
 155   IN CONST CHAR8  *Module,  OPTIONAL
 156   IN UINT64       TimeStamp,
 157   IN UINT32       Identifier
 158   )
 159 {
 160   EFI_STATUS    Status;
 161   CONST CHAR8*  String;
 162
 163   Status = GetPerformanceMeasurementProtocol ();
 164   if (EFI_ERROR (Status)) {
 165     return RETURN_NOT_FOUND;
 166   }
 167
 168   if (Token != NULL) {
 169     String = Token;
 170   } else if (Module != NULL) {
 171     String = Module;
 172   } else {
 173     String = NULL;
 174   }
 175
 176   if (mPerformanceMeasurement != NULL) {
 177     Status = mPerformanceMeasurement->CreatePerformanceMeasurement (Handle, NULL, String, TimeStamp, 0, Identifier, PerfEndEntry);
 178   } else {
 179     ASSERT (FALSE);
 180   }
 181
 182   return (RETURN_STATUS) Status;
 183 }
 184
 185 /**
 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.
 189
 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().
 207
 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
 212                                   being measured.
 213   @param  Token                   Pointer to a Null-terminated ASCII string that identifies the component
 214                                   being measured.
 215   @param  Module                  Pointer to a Null-terminated ASCII string that identifies the module
 216                                   being measured.
 217   @param  StartTimeStamp          Pointer to the 64-bit time stamp that was recorded when the measurement
 218                                   was started.
 219   @param  EndTimeStamp            Pointer to the 64-bit time stamp that was recorded when the measurement
 220                                   was ended.
 221   @param  Identifier              Pointer to the 32-bit identifier that was recorded.
 222
 223   @return The key for the next performance log entry (in general case).
 224
 225 **/
 226 UINTN
 227 EFIAPI
 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
 236   )
 237 {
 238   return 0;
 239
 240 }
 241
 242 /**
 243   Creates a record for the beginning of a performance measurement.
 244
 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.
 249
 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.
 257
 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.
 260
 261 **/
 262 RETURN_STATUS
 263 EFIAPI
 264 StartPerformanceMeasurement (
 265   IN CONST VOID   *Handle,  OPTIONAL
 266   IN CONST CHAR8  *Token,   OPTIONAL
 267   IN CONST CHAR8  *Module,  OPTIONAL
 268   IN UINT64       TimeStamp
 269   )
 270 {
 271   return StartPerformanceMeasurementEx (Handle, Token, Module, TimeStamp, 0);
 272 }
 273
 274 /**
 275   Fills in the end time of a performance measurement.
 276
 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.
 283
 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.
 291
 292   @retval RETURN_SUCCESS          The end of  the measurement was recorded.
 293   @retval RETURN_NOT_FOUND        The specified measurement record could not be found.
 294
 295 **/
 296 RETURN_STATUS
 297 EFIAPI
 298 EndPerformanceMeasurement (
 299   IN CONST VOID   *Handle,  OPTIONAL
 300   IN CONST CHAR8  *Token,   OPTIONAL
 301   IN CONST CHAR8  *Module,  OPTIONAL
 302   IN UINT64       TimeStamp
 303   )
 304 {
 305   return EndPerformanceMeasurementEx (Handle, Token, Module, TimeStamp, 0);
 306 }
 307
 308 /**
 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.
 312
 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().
 329
 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
 334                                   being measured.
 335   @param  Token                   Pointer to a Null-terminated ASCII string that identifies the component
 336                                   being measured.
 337   @param  Module                  Pointer to a Null-terminated ASCII string that identifies the module
 338                                   being measured.
 339   @param  StartTimeStamp          Pointer to the 64-bit time stamp that was recorded when the measurement
 340                                   was started.
 341   @param  EndTimeStamp            Pointer to the 64-bit time stamp that was recorded when the measurement
 342                                   was ended.
 343
 344   @return The key for the next performance log entry (in general case).
 345
 346 **/
 347 UINTN
 348 EFIAPI
 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
 356   )
 357 {
 358   return 0;
 359 }
 360
 361 /**
 362   Returns TRUE if the performance measurement macros are enabled.
 363
 364   This function returns TRUE if the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
 365   PcdPerformanceLibraryPropertyMask is set.  Otherwise FALSE is returned.
 366
 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.
 371
 372 **/
 373 BOOLEAN
 374 EFIAPI
 375 PerformanceMeasurementEnabled (
 376   VOID
 377   )
 378 {
 379   return (BOOLEAN) ((PcdGet8(PcdPerformanceLibraryPropertyMask) & PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED) != 0);
 380 }