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 - 2018, Intel Corporation. All rights reserved.<BR>
  10 SPDX-License-Identifier: BSD-2-Clause-Patent
  11
  12 **/
  13
  14
  15 #include <PiDxe.h>
  16
  17 #include <Guid/PerformanceMeasurement.h>
  18
  19 #include <Library/PerformanceLib.h>
  20 #include <Library/DebugLib.h>
  21 #include <Library/UefiBootServicesTableLib.h>
  22 #include <Library/PcdLib.h>
  23
  24 //
  25 // The cached Performance Protocol and PerformanceEx Protocol interface.
  26 //
  27 EDKII_PERFORMANCE_MEASUREMENT_PROTOCOL      *mPerformanceMeasurement = NULL;
  28
  29 /**
  30   The function caches the pointers to PerformanceEx protocol and Performance Protocol.
  31
  32   The function locates PerformanceEx protocol and Performance Protocol from protocol database.
  33
  34   @retval EFI_SUCCESS     PerformanceEx protocol or Performance Protocol is successfully located.
  35   @retval EFI_NOT_FOUND   Both PerformanceEx protocol and Performance Protocol are not located to log performance.
  36
  37 **/
  38 EFI_STATUS
  39 GetPerformanceMeasurementProtocol (
  40   VOID
  41   )
  42 {
  43   EFI_STATUS                Status;
  44   EDKII_PERFORMANCE_MEASUREMENT_PROTOCOL   *PerformanceMeasurement;
  45
  46   if (mPerformanceMeasurement != NULL) {
  47     return EFI_SUCCESS;
  48   }
  49
  50   Status = gBS->LocateProtocol (&gEdkiiPerformanceMeasurementProtocolGuid, NULL, (VOID **) &PerformanceMeasurement);
  51   if (!EFI_ERROR (Status)) {
  52     ASSERT (PerformanceMeasurement != NULL);
  53     //
  54     // Cache PerformanceMeasurement Protocol.
  55     //
  56     mPerformanceMeasurement = PerformanceMeasurement;
  57     return EFI_SUCCESS;
  58   }
  59
  60   return EFI_NOT_FOUND;
  61 }
  62
  63 /**
  64   Creates a record for the beginning of a performance measurement.
  65
  66   Creates a record that contains the Handle, Token, Module and Identifier.
  67   If TimeStamp is not zero, then TimeStamp is added to the record as the start time.
  68   If TimeStamp is zero, then this function reads the current time stamp
  69   and adds that time stamp value to the record as the start time.
  70
  71   @param  Handle                  Pointer to environment specific context used
  72                                   to identify the component being measured.
  73   @param  Token                   Pointer to a Null-terminated ASCII string
  74                                   that identifies the component being measured.
  75   @param  Module                  Pointer to a Null-terminated ASCII string
  76                                   that identifies the module being measured.
  77   @param  TimeStamp               64-bit time stamp.
  78   @param  Identifier              32-bit identifier. If the value is 0, the created record
  79                                   is same as the one created by StartPerformanceMeasurement.
  80
  81   @retval RETURN_SUCCESS          The start of the measurement was recorded.
  82   @retval RETURN_OUT_OF_RESOURCES There are not enough resources to record the measurement.
  83
  84 **/
  85 RETURN_STATUS
  86 EFIAPI
  87 StartPerformanceMeasurementEx (
  88   IN CONST VOID   *Handle,  OPTIONAL
  89   IN CONST CHAR8  *Token,   OPTIONAL
  90   IN CONST CHAR8  *Module,  OPTIONAL
  91   IN UINT64       TimeStamp,
  92   IN UINT32       Identifier
  93   )
  94 {
  95   EFI_STATUS    Status;
  96   CONST CHAR8*  String;
  97
  98   Status = GetPerformanceMeasurementProtocol ();
  99   if (EFI_ERROR (Status)) {
 100     return RETURN_NOT_FOUND;
 101   }
 102
 103   if (Token != NULL) {
 104     String = Token;
 105   } else if (Module != NULL) {
 106     String = Module;
 107   } else {
 108     String = NULL;
 109   }
 110
 111   if (mPerformanceMeasurement != NULL) {
 112     Status = mPerformanceMeasurement->CreatePerformanceMeasurement (Handle, NULL, String, TimeStamp, 0, Identifier, PerfStartEntry);
 113   } else {
 114     ASSERT (FALSE);
 115   }
 116
 117   return (RETURN_STATUS) Status;
 118 }
 119
 120 /**
 121   Fills in the end time of a performance measurement.
 122
 123   Looks up the record that matches Handle, Token and Module.
 124   If the record can not be found then return RETURN_NOT_FOUND.
 125   If the record is found and TimeStamp is not zero,
 126   then TimeStamp is added to the record as the end time.
 127   If the record is found and TimeStamp is zero, then this function reads
 128   the current time stamp and adds that time stamp value to the record as the end time.
 129
 130   @param  Handle                  Pointer to environment specific context used
 131                                   to identify the component being measured.
 132   @param  Token                   Pointer to a Null-terminated ASCII string
 133                                   that identifies the component being measured.
 134   @param  Module                  Pointer to a Null-terminated ASCII string
 135                                   that identifies the module being measured.
 136   @param  TimeStamp               64-bit time stamp.
 137   @param  Identifier              32-bit identifier. If the value is 0, the found record
 138                                   is same as the one found by EndPerformanceMeasurement.
 139
 140   @retval RETURN_SUCCESS          The end of  the measurement was recorded.
 141   @retval RETURN_NOT_FOUND        The specified measurement record could not be found.
 142
 143 **/
 144 RETURN_STATUS
 145 EFIAPI
 146 EndPerformanceMeasurementEx (
 147   IN CONST VOID   *Handle,  OPTIONAL
 148   IN CONST CHAR8  *Token,   OPTIONAL
 149   IN CONST CHAR8  *Module,  OPTIONAL
 150   IN UINT64       TimeStamp,
 151   IN UINT32       Identifier
 152   )
 153 {
 154   EFI_STATUS    Status;
 155   CONST CHAR8*  String;
 156
 157   Status = GetPerformanceMeasurementProtocol ();
 158   if (EFI_ERROR (Status)) {
 159     return RETURN_NOT_FOUND;
 160   }
 161
 162   if (Token != NULL) {
 163     String = Token;
 164   } else if (Module != NULL) {
 165     String = Module;
 166   } else {
 167     String = NULL;
 168   }
 169
 170   if (mPerformanceMeasurement != NULL) {
 171     Status = mPerformanceMeasurement->CreatePerformanceMeasurement (Handle, NULL, String, TimeStamp, 0, Identifier, PerfEndEntry);
 172   } else {
 173     ASSERT (FALSE);
 174   }
 175
 176   return (RETURN_STATUS) Status;
 177 }
 178
 179 /**
 180   Attempts to retrieve a performance measurement log entry from the performance measurement log.
 181   It can also retrieve the log created by StartPerformanceMeasurement and EndPerformanceMeasurement,
 182   and then assign the Identifier with 0.
 183
 184   Attempts to retrieve the performance log entry specified by LogEntryKey.  If LogEntryKey is
 185   zero on entry, then an attempt is made to retrieve the first entry from the performance log,
 186   and the key for the second entry in the log is returned.  If the performance log is empty,
 187   then no entry is retrieved and zero is returned.  If LogEntryKey is not zero, then the performance
 188   log entry associated with LogEntryKey is retrieved, and the key for the next entry in the log is
 189   returned.  If LogEntryKey is the key for the last entry in the log, then the last log entry is
 190   retrieved and an implementation specific non-zero key value that specifies the end of the performance
 191   log is returned.  If LogEntryKey is equal this implementation specific non-zero key value, then no entry
 192   is retrieved and zero is returned.  In the cases where a performance log entry can be returned,
 193   the log entry is returned in Handle, Token, Module, StartTimeStamp, EndTimeStamp and Identifier.
 194   If LogEntryKey is not a valid log entry key for the performance measurement log, then ASSERT().
 195   If Handle is NULL, then ASSERT().
 196   If Token is NULL, then ASSERT().
 197   If Module is NULL, then ASSERT().
 198   If StartTimeStamp is NULL, then ASSERT().
 199   If EndTimeStamp is NULL, then ASSERT().
 200   If Identifier is NULL, then ASSERT().
 201
 202   @param  LogEntryKey             On entry, the key of the performance measurement log entry to retrieve.
 203                                   0, then the first performance measurement log entry is retrieved.
 204                                   On exit, the key of the next performance log entry.
 205   @param  Handle                  Pointer to environment specific context used to identify the component
 206                                   being measured.
 207   @param  Token                   Pointer to a Null-terminated ASCII string that identifies the component
 208                                   being measured.
 209   @param  Module                  Pointer to a Null-terminated ASCII string that identifies the module
 210                                   being measured.
 211   @param  StartTimeStamp          Pointer to the 64-bit time stamp that was recorded when the measurement
 212                                   was started.
 213   @param  EndTimeStamp            Pointer to the 64-bit time stamp that was recorded when the measurement
 214                                   was ended.
 215   @param  Identifier              Pointer to the 32-bit identifier that was recorded.
 216
 217   @return The key for the next performance log entry (in general case).
 218
 219 **/
 220 UINTN
 221 EFIAPI
 222 GetPerformanceMeasurementEx (
 223   IN  UINTN       LogEntryKey,
 224   OUT CONST VOID  **Handle,
 225   OUT CONST CHAR8 **Token,
 226   OUT CONST CHAR8 **Module,
 227   OUT UINT64      *StartTimeStamp,
 228   OUT UINT64      *EndTimeStamp,
 229   OUT UINT32      *Identifier
 230   )
 231 {
 232   return 0;
 233
 234 }
 235
 236 /**
 237   Creates a record for the beginning of a performance measurement.
 238
 239   Creates a record that contains the Handle, Token, and Module.
 240   If TimeStamp is not zero, then TimeStamp is added to the record as the start time.
 241   If TimeStamp is zero, then this function reads the current time stamp
 242   and adds that time stamp value to the record as the start time.
 243
 244   @param  Handle                  Pointer to environment specific context used
 245                                   to identify the component being measured.
 246   @param  Token                   Pointer to a Null-terminated ASCII string
 247                                   that identifies the component being measured.
 248   @param  Module                  Pointer to a Null-terminated ASCII string
 249                                   that identifies the module being measured.
 250   @param  TimeStamp               64-bit time stamp.
 251
 252   @retval RETURN_SUCCESS          The start of the measurement was recorded.
 253   @retval RETURN_OUT_OF_RESOURCES There are not enough resources to record the measurement.
 254
 255 **/
 256 RETURN_STATUS
 257 EFIAPI
 258 StartPerformanceMeasurement (
 259   IN CONST VOID   *Handle,  OPTIONAL
 260   IN CONST CHAR8  *Token,   OPTIONAL
 261   IN CONST CHAR8  *Module,  OPTIONAL
 262   IN UINT64       TimeStamp
 263   )
 264 {
 265   return StartPerformanceMeasurementEx (Handle, Token, Module, TimeStamp, 0);
 266 }
 267
 268 /**
 269   Fills in the end time of a performance measurement.
 270
 271   Looks up the record that matches Handle, Token, and Module.
 272   If the record can not be found then return RETURN_NOT_FOUND.
 273   If the record is found and TimeStamp is not zero,
 274   then TimeStamp is added to the record as the end time.
 275   If the record is found and TimeStamp is zero, then this function reads
 276   the current time stamp and adds that time stamp value to the record as the end time.
 277
 278   @param  Handle                  Pointer to environment specific context used
 279                                   to identify the component being measured.
 280   @param  Token                   Pointer to a Null-terminated ASCII string
 281                                   that identifies the component being measured.
 282   @param  Module                  Pointer to a Null-terminated ASCII string
 283                                   that identifies the module being measured.
 284   @param  TimeStamp               64-bit time stamp.
 285
 286   @retval RETURN_SUCCESS          The end of  the measurement was recorded.
 287   @retval RETURN_NOT_FOUND        The specified measurement record could not be found.
 288
 289 **/
 290 RETURN_STATUS
 291 EFIAPI
 292 EndPerformanceMeasurement (
 293   IN CONST VOID   *Handle,  OPTIONAL
 294   IN CONST CHAR8  *Token,   OPTIONAL
 295   IN CONST CHAR8  *Module,  OPTIONAL
 296   IN UINT64       TimeStamp
 297   )
 298 {
 299   return EndPerformanceMeasurementEx (Handle, Token, Module, TimeStamp, 0);
 300 }
 301
 302 /**
 303   Attempts to retrieve a performance measurement log entry from the performance measurement log.
 304   It can also retrieve the log created by StartPerformanceMeasurementEx and EndPerformanceMeasurementEx,
 305   and then eliminate the Identifier.
 306
 307   Attempts to retrieve the performance log entry specified by LogEntryKey.  If LogEntryKey is
 308   zero on entry, then an attempt is made to retrieve the first entry from the performance log,
 309   and the key for the second entry in the log is returned.  If the performance log is empty,
 310   then no entry is retrieved and zero is returned.  If LogEntryKey is not zero, then the performance
 311   log entry associated with LogEntryKey is retrieved, and the key for the next entry in the log is
 312   returned.  If LogEntryKey is the key for the last entry in the log, then the last log entry is
 313   retrieved and an implementation specific non-zero key value that specifies the end of the performance
 314   log is returned.  If LogEntryKey is equal this implementation specific non-zero key value, then no entry
 315   is retrieved and zero is returned.  In the cases where a performance log entry can be returned,
 316   the log entry is returned in Handle, Token, Module, StartTimeStamp, and EndTimeStamp.
 317   If LogEntryKey is not a valid log entry key for the performance measurement log, then ASSERT().
 318   If Handle is NULL, then ASSERT().
 319   If Token is NULL, then ASSERT().
 320   If Module is NULL, then ASSERT().
 321   If StartTimeStamp is NULL, then ASSERT().
 322   If EndTimeStamp is NULL, then ASSERT().
 323
 324   @param  LogEntryKey             On entry, the key of the performance measurement log entry to retrieve.
 325                                   0, then the first performance measurement log entry is retrieved.
 326                                   On exit, the key of the next performance log entry.
 327   @param  Handle                  Pointer to environment specific context used to identify the component
 328                                   being measured.
 329   @param  Token                   Pointer to a Null-terminated ASCII string that identifies the component
 330                                   being measured.
 331   @param  Module                  Pointer to a Null-terminated ASCII string that identifies the module
 332                                   being measured.
 333   @param  StartTimeStamp          Pointer to the 64-bit time stamp that was recorded when the measurement
 334                                   was started.
 335   @param  EndTimeStamp            Pointer to the 64-bit time stamp that was recorded when the measurement
 336                                   was ended.
 337
 338   @return The key for the next performance log entry (in general case).
 339
 340 **/
 341 UINTN
 342 EFIAPI
 343 GetPerformanceMeasurement (
 344   IN  UINTN       LogEntryKey,
 345   OUT CONST VOID  **Handle,
 346   OUT CONST CHAR8 **Token,
 347   OUT CONST CHAR8 **Module,
 348   OUT UINT64      *StartTimeStamp,
 349   OUT UINT64      *EndTimeStamp
 350   )
 351 {
 352   return 0;
 353 }
 354
 355 /**
 356   Returns TRUE if the performance measurement macros are enabled.
 357
 358   This function returns TRUE if the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
 359   PcdPerformanceLibraryPropertyMask is set.  Otherwise FALSE is returned.
 360
 361   @retval TRUE                    The PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
 362                                   PcdPerformanceLibraryPropertyMask is set.
 363   @retval FALSE                   The PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
 364                                   PcdPerformanceLibraryPropertyMask is clear.
 365
 366 **/
 367 BOOLEAN
 368 EFIAPI
 369 PerformanceMeasurementEnabled (
 370   VOID
 371   )
 372 {
 373   return (BOOLEAN) ((PcdGet8(PcdPerformanceLibraryPropertyMask) & PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED) != 0);
 374 }
 375
 376 /**
 377   Create performance record with event description and a timestamp.
 378
 379   @param CallerIdentifier  - Image handle or pointer to caller ID GUID
 380   @param Guid              - Pointer to a GUID
 381   @param String            - Pointer to a string describing the measurement
 382   @param Address           - Pointer to a location in memory relevant to the measurement
 383   @param Identifier        - Performance identifier describing the type of measurement
 384
 385   @retval RETURN_SUCCESS           - Successfully created performance record
 386   @retval RETURN_OUT_OF_RESOURCES  - Ran out of space to store the records
 387   @retval RETURN_INVALID_PARAMETER - Invalid parameter passed to function - NULL
 388                                      pointer or invalid PerfId
 389
 390 **/
 391 RETURN_STATUS
 392 EFIAPI
 393 LogPerformanceMeasurement (
 394   IN CONST VOID   *CallerIdentifier,
 395   IN CONST VOID   *Guid,    OPTIONAL
 396   IN CONST CHAR8  *String,  OPTIONAL
 397   IN  UINT64       Address, OPTIONAL
 398   IN UINT32       Identifier
 399   )
 400 {
 401   EFI_STATUS  Status;
 402
 403   Status = GetPerformanceMeasurementProtocol ();
 404   if (EFI_ERROR (Status)) {
 405     return RETURN_OUT_OF_RESOURCES;
 406   }
 407
 408   if (mPerformanceMeasurement != NULL) {
 409     Status = mPerformanceMeasurement->CreatePerformanceMeasurement (CallerIdentifier, Guid, String, 0, Address, Identifier, PerfEntry);
 410   } else {
 411     ASSERT (FALSE);
 412   }
 413
 414   return (RETURN_STATUS) Status;
 415 }
 416
 417 /**
 418   Check whether the specified performance measurement can be logged.
 419
 420   This function returns TRUE when the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set
 421   and the Type disable bit in PcdPerformanceLibraryPropertyMask is not set.
 422
 423   @param Type        - Type of the performance measurement entry.
 424
 425   @retval TRUE         The performance measurement can be logged.
 426   @retval FALSE        The performance measurement can NOT be logged.
 427
 428 **/
 429 BOOLEAN
 430 EFIAPI
 431 LogPerformanceMeasurementEnabled (
 432   IN  CONST UINTN        Type
 433   )
 434 {
 435   //
 436   // When Performance measurement is enabled and the type is not filtered, the performance can be logged.
 437   //
 438   if (PerformanceMeasurementEnabled () && (PcdGet8(PcdPerformanceLibraryPropertyMask) & Type) == 0) {
 439     return TRUE;
 440   }
 441   return FALSE;
 442 }