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