MdeModulePkg/Library/DxeCorePerformanceLib/DxeCorePerformanceLib.c

   1 /** @file
   2   Performance library instance mainly used by DxeCore.
   3
   4   This library provides the performance measurement interfaces and initializes performance
   5   logging for DXE phase. It first initializes its private global data structure for
   6   performance logging and saves the performance GUIDed HOB passed from PEI phase.
   7   It initializes DXE phase performance logging by publishing the Performance and PerformanceEx Protocol,
   8   which are consumed by DxePerformanceLib to logging performance data in DXE phase.
   9
  10   This library is mainly used by DxeCore to start performance logging to ensure that
  11   Performance Protocol is installed at the very beginning of DXE phase.
  12
  13 Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>
  14 (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>
  15 This program and the accompanying materials
  16 are licensed and made available under the terms and conditions of the BSD License
  17 which accompanies this distribution.  The full text of the license may be found at
  18 http://opensource.org/licenses/bsd-license.php
  19
  20 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  21 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  22
  23 **/
  24
  25
  26 #include "DxeCorePerformanceLibInternal.h"
  27
  28
  29 //
  30 // The data structure to hold global performance data.
  31 //
  32 GAUGE_DATA_HEADER    *mGaugeData;
  33
  34 //
  35 // The current maximum number of logging entries. If current number of
  36 // entries exceeds this value, it will re-allocate a larger array and
  37 // migration the old data to the larger array.
  38 //
  39 UINT32               mMaxGaugeRecords;
  40
  41 //
  42 // The handle to install Performance Protocol instance.
  43 //
  44 EFI_HANDLE           mHandle = NULL;
  45
  46 //
  47 // Interfaces for Performance Protocol.
  48 //
  49 PERFORMANCE_PROTOCOL mPerformanceInterface = {
  50   StartGauge,
  51   EndGauge,
  52   GetGauge
  53   };
  54
  55 //
  56 // Interfaces for PerformanceEx Protocol.
  57 //
  58 PERFORMANCE_EX_PROTOCOL mPerformanceExInterface = {
  59   StartGaugeEx,
  60   EndGaugeEx,
  61   GetGaugeEx
  62   };
  63
  64 PERFORMANCE_PROPERTY  mPerformanceProperty;
  65
  66 /**
  67   Searches in the gauge array with keyword Handle, Token, Module and Identifier.
  68
  69   This internal function searches for the gauge entry in the gauge array.
  70   If there is an entry that exactly matches the given keywords
  71   and its end time stamp is zero, then the index of that gauge entry is returned;
  72   otherwise, the the number of gauge entries in the array is returned.
  73
  74   @param  Handle                  Pointer to environment specific context used
  75                                   to identify the component being measured.
  76   @param  Token                   Pointer to a Null-terminated ASCII string
  77                                   that identifies the component being measured.
  78   @param  Module                  Pointer to a Null-terminated ASCII string
  79                                   that identifies the module being measured.
  80   @param  Identifier              32-bit identifier.
  81
  82   @retval The index of gauge entry in the array.
  83
  84 **/
  85 UINT32
  86 InternalSearchForGaugeEntry (
  87   IN CONST VOID                 *Handle,  OPTIONAL
  88   IN CONST CHAR8                *Token,   OPTIONAL
  89   IN CONST CHAR8                *Module,   OPTIONAL
  90   IN UINT32                     Identifier
  91   )
  92 {
  93   UINT32                    Index;
  94   UINT32                    Index2;
  95   UINT32                    NumberOfEntries;
  96   GAUGE_DATA_ENTRY_EX       *GaugeEntryExArray;
  97
  98   if (Token == NULL) {
  99     Token = "";
 100   }
 101   if (Module == NULL) {
 102     Module = "";
 103   }
 104
 105   NumberOfEntries = mGaugeData->NumberOfEntries;
 106   GaugeEntryExArray = (GAUGE_DATA_ENTRY_EX *) (mGaugeData + 1);
 107
 108   Index2 = 0;
 109
 110   for (Index = 0; Index < NumberOfEntries; Index++) {
 111     Index2 = NumberOfEntries - 1 - Index;
 112     if (GaugeEntryExArray[Index2].EndTimeStamp == 0 &&
 113         (GaugeEntryExArray[Index2].Handle == (EFI_PHYSICAL_ADDRESS) (UINTN) Handle) &&
 114         AsciiStrnCmp (GaugeEntryExArray[Index2].Token, Token, DXE_PERFORMANCE_STRING_LENGTH) == 0 &&
 115         AsciiStrnCmp (GaugeEntryExArray[Index2].Module, Module, DXE_PERFORMANCE_STRING_LENGTH) == 0) {
 116       Index = Index2;
 117       break;
 118     }
 119   }
 120
 121   return Index;
 122 }
 123
 124 /**
 125   Adds a record at the end of the performance measurement log
 126   that records the start time of a performance measurement.
 127
 128   Adds a record to the end of the performance measurement log
 129   that contains the Handle, Token, Module and Identifier.
 130   The end time of the new record must be set to zero.
 131   If TimeStamp is not zero, then TimeStamp is used to fill in the start time in the record.
 132   If TimeStamp is zero, the start time in the record is filled in with the value
 133   read from the current time stamp.
 134
 135   @param  Handle                  Pointer to environment specific context used
 136                                   to identify the component being measured.
 137   @param  Token                   Pointer to a Null-terminated ASCII string
 138                                   that identifies the component being measured.
 139   @param  Module                  Pointer to a Null-terminated ASCII string
 140                                   that identifies the module being measured.
 141   @param  TimeStamp               64-bit time stamp.
 142   @param  Identifier              32-bit identifier. If the value is 0, the created record
 143                                   is same as the one created by StartGauge of PERFORMANCE_PROTOCOL.
 144
 145   @retval EFI_SUCCESS             The data was read correctly from the device.
 146   @retval EFI_OUT_OF_RESOURCES    There are not enough resources to record the measurement.
 147
 148 **/
 149 EFI_STATUS
 150 EFIAPI
 151 StartGaugeEx (
 152   IN CONST VOID   *Handle,  OPTIONAL
 153   IN CONST CHAR8  *Token,   OPTIONAL
 154   IN CONST CHAR8  *Module,  OPTIONAL
 155   IN UINT64       TimeStamp,
 156   IN UINT32       Identifier
 157   )
 158 {
 159   GAUGE_DATA_ENTRY_EX       *GaugeEntryExArray;
 160   UINTN                     GaugeDataSize;
 161   GAUGE_DATA_HEADER         *NewGaugeData;
 162   UINTN                     OldGaugeDataSize;
 163   GAUGE_DATA_HEADER         *OldGaugeData;
 164   UINT32                    Index;
 165
 166   Index = mGaugeData->NumberOfEntries;
 167   if (Index >= mMaxGaugeRecords) {
 168     //
 169     // Try to enlarge the scale of gauge array.
 170     //
 171     OldGaugeData      = mGaugeData;
 172     OldGaugeDataSize  = sizeof (GAUGE_DATA_HEADER) + sizeof (GAUGE_DATA_ENTRY_EX) * mMaxGaugeRecords;
 173
 174     GaugeDataSize     = sizeof (GAUGE_DATA_HEADER) + sizeof (GAUGE_DATA_ENTRY_EX) * mMaxGaugeRecords * 2;
 175
 176     NewGaugeData = AllocateZeroPool (GaugeDataSize);
 177     if (NewGaugeData == NULL) {
 178       return EFI_OUT_OF_RESOURCES;
 179     }
 180
 181     mGaugeData = NewGaugeData;
 182     mMaxGaugeRecords *= 2;
 183
 184     //
 185     // Initialize new data array and migrate old data one.
 186     //
 187     mGaugeData = CopyMem (mGaugeData, OldGaugeData, OldGaugeDataSize);
 188
 189     FreePool (OldGaugeData);
 190   }
 191
 192   GaugeEntryExArray               = (GAUGE_DATA_ENTRY_EX *) (mGaugeData + 1);
 193   GaugeEntryExArray[Index].Handle = (EFI_PHYSICAL_ADDRESS) (UINTN) Handle;
 194
 195   if (Token != NULL) {
 196     AsciiStrnCpyS (GaugeEntryExArray[Index].Token, DXE_PERFORMANCE_STRING_SIZE, Token, DXE_PERFORMANCE_STRING_LENGTH);
 197   }
 198   if (Module != NULL) {
 199     AsciiStrnCpyS (GaugeEntryExArray[Index].Module, DXE_PERFORMANCE_STRING_SIZE, Module, DXE_PERFORMANCE_STRING_LENGTH);
 200   }
 201
 202   GaugeEntryExArray[Index].EndTimeStamp = 0;
 203   GaugeEntryExArray[Index].Identifier = Identifier;
 204
 205   if (TimeStamp == 0) {
 206     TimeStamp = GetPerformanceCounter ();
 207   }
 208   GaugeEntryExArray[Index].StartTimeStamp = TimeStamp;
 209
 210   mGaugeData->NumberOfEntries++;
 211
 212   return EFI_SUCCESS;
 213 }
 214
 215 /**
 216   Searches the performance measurement log from the beginning of the log
 217   for the first matching record that contains a zero end time and fills in a valid end time.
 218
 219   Searches the performance measurement log from the beginning of the log
 220   for the first record that matches Handle, Token and Module and has an end time value of zero.
 221   If the record can not be found then return EFI_NOT_FOUND.
 222   If the record is found and TimeStamp is not zero,
 223   then the end time in the record is filled in with the value specified by TimeStamp.
 224   If the record is found and TimeStamp is zero, then the end time in the matching record
 225   is filled in with the current time stamp value.
 226
 227   @param  Handle                  Pointer to environment specific context used
 228                                   to identify the component being measured.
 229   @param  Token                   Pointer to a Null-terminated ASCII string
 230                                   that identifies the component being measured.
 231   @param  Module                  Pointer to a Null-terminated ASCII string
 232                                   that identifies the module being measured.
 233   @param  TimeStamp               64-bit time stamp.
 234   @param  Identifier              32-bit identifier. If the value is 0, the found record
 235                                   is same as the one found by EndGauge of PERFORMANCE_PROTOCOL.
 236
 237   @retval EFI_SUCCESS             The end of  the measurement was recorded.
 238   @retval EFI_NOT_FOUND           The specified measurement record could not be found.
 239
 240 **/
 241 EFI_STATUS
 242 EFIAPI
 243 EndGaugeEx (
 244   IN CONST VOID   *Handle,  OPTIONAL
 245   IN CONST CHAR8  *Token,   OPTIONAL
 246   IN CONST CHAR8  *Module,  OPTIONAL
 247   IN UINT64       TimeStamp,
 248   IN UINT32       Identifier
 249   )
 250 {
 251   GAUGE_DATA_ENTRY_EX *GaugeEntryExArray;
 252   UINT32              Index;
 253
 254   if (TimeStamp == 0) {
 255     TimeStamp = GetPerformanceCounter ();
 256   }
 257
 258   Index = InternalSearchForGaugeEntry (Handle, Token, Module, Identifier);
 259   if (Index >= mGaugeData->NumberOfEntries) {
 260     return EFI_NOT_FOUND;
 261   }
 262   GaugeEntryExArray = (GAUGE_DATA_ENTRY_EX *) (mGaugeData + 1);
 263   GaugeEntryExArray[Index].EndTimeStamp = TimeStamp;
 264
 265   return EFI_SUCCESS;
 266 }
 267
 268 /**
 269   Retrieves a previously logged performance measurement.
 270   It can also retrieve the log created by StartGauge and EndGauge of PERFORMANCE_PROTOCOL,
 271   and then assign the Identifier with 0.
 272
 273   Retrieves the performance log entry from the performance log specified by LogEntryKey.
 274   If it stands for a valid entry, then EFI_SUCCESS is returned and
 275   GaugeDataEntryEx stores the pointer to that entry.
 276
 277   @param  LogEntryKey             The key for the previous performance measurement log entry.
 278                                   If 0, then the first performance measurement log entry is retrieved.
 279   @param  GaugeDataEntryEx        The indirect pointer to the extended gauge data entry specified by LogEntryKey
 280                                   if the retrieval is successful.
 281
 282   @retval EFI_SUCCESS             The GuageDataEntryEx is successfully found based on LogEntryKey.
 283   @retval EFI_NOT_FOUND           The LogEntryKey is the last entry (equals to the total entry number).
 284   @retval EFI_INVALIDE_PARAMETER  The LogEntryKey is not a valid entry (greater than the total entry number).
 285   @retval EFI_INVALIDE_PARAMETER  GaugeDataEntryEx is NULL.
 286
 287 **/
 288 EFI_STATUS
 289 EFIAPI
 290 GetGaugeEx (
 291   IN  UINTN                 LogEntryKey,
 292   OUT GAUGE_DATA_ENTRY_EX   **GaugeDataEntryEx
 293   )
 294 {
 295   UINTN               NumberOfEntries;
 296   GAUGE_DATA_ENTRY_EX *GaugeEntryExArray;
 297
 298   NumberOfEntries = (UINTN) (mGaugeData->NumberOfEntries);
 299   if (LogEntryKey > NumberOfEntries) {
 300     return EFI_INVALID_PARAMETER;
 301   }
 302   if (LogEntryKey == NumberOfEntries) {
 303     return EFI_NOT_FOUND;
 304   }
 305
 306   GaugeEntryExArray = (GAUGE_DATA_ENTRY_EX *) (mGaugeData + 1);
 307
 308   if (GaugeDataEntryEx == NULL) {
 309     return EFI_INVALID_PARAMETER;
 310   }
 311   *GaugeDataEntryEx = &GaugeEntryExArray[LogEntryKey];
 312
 313   return EFI_SUCCESS;
 314 }
 315
 316 /**
 317   Adds a record at the end of the performance measurement log
 318   that records the start time of a performance measurement.
 319
 320   Adds a record to the end of the performance measurement log
 321   that contains the Handle, Token, and Module.
 322   The end time of the new record must be set to zero.
 323   If TimeStamp is not zero, then TimeStamp is used to fill in the start time in the record.
 324   If TimeStamp is zero, the start time in the record is filled in with the value
 325   read from the current time stamp.
 326
 327   @param  Handle                  Pointer to environment specific context used
 328                                   to identify the component being measured.
 329   @param  Token                   Pointer to a Null-terminated ASCII string
 330                                   that identifies the component being measured.
 331   @param  Module                  Pointer to a Null-terminated ASCII string
 332                                   that identifies the module being measured.
 333   @param  TimeStamp               64-bit time stamp.
 334
 335   @retval EFI_SUCCESS             The data was read correctly from the device.
 336   @retval EFI_OUT_OF_RESOURCES    There are not enough resources to record the measurement.
 337
 338 **/
 339 EFI_STATUS
 340 EFIAPI
 341 StartGauge (
 342   IN CONST VOID   *Handle,  OPTIONAL
 343   IN CONST CHAR8  *Token,   OPTIONAL
 344   IN CONST CHAR8  *Module,  OPTIONAL
 345   IN UINT64       TimeStamp
 346   )
 347 {
 348   return StartGaugeEx (Handle, Token, Module, TimeStamp, 0);
 349 }
 350
 351 /**
 352   Searches the performance measurement log from the beginning of the log
 353   for the first matching record that contains a zero end time and fills in a valid end time.
 354
 355   Searches the performance measurement log from the beginning of the log
 356   for the first record that matches Handle, Token, and Module and has an end time value of zero.
 357   If the record can not be found then return EFI_NOT_FOUND.
 358   If the record is found and TimeStamp is not zero,
 359   then the end time in the record is filled in with the value specified by TimeStamp.
 360   If the record is found and TimeStamp is zero, then the end time in the matching record
 361   is filled in with the current time stamp value.
 362
 363   @param  Handle                  Pointer to environment specific context used
 364                                   to identify the component being measured.
 365   @param  Token                   Pointer to a Null-terminated ASCII string
 366                                   that identifies the component being measured.
 367   @param  Module                  Pointer to a Null-terminated ASCII string
 368                                   that identifies the module being measured.
 369   @param  TimeStamp               64-bit time stamp.
 370
 371   @retval EFI_SUCCESS             The end of  the measurement was recorded.
 372   @retval EFI_NOT_FOUND           The specified measurement record could not be found.
 373
 374 **/
 375 EFI_STATUS
 376 EFIAPI
 377 EndGauge (
 378   IN CONST VOID   *Handle,  OPTIONAL
 379   IN CONST CHAR8  *Token,   OPTIONAL
 380   IN CONST CHAR8  *Module,  OPTIONAL
 381   IN UINT64       TimeStamp
 382   )
 383 {
 384   return EndGaugeEx (Handle, Token, Module, TimeStamp, 0);
 385 }
 386
 387 /**
 388   Retrieves a previously logged performance measurement.
 389   It can also retrieve the log created by StartGaugeEx and EndGaugeEx of PERFORMANCE_EX_PROTOCOL,
 390   and then eliminate the Identifier.
 391
 392   Retrieves the performance log entry from the performance log specified by LogEntryKey.
 393   If it stands for a valid entry, then EFI_SUCCESS is returned and
 394   GaugeDataEntry stores the pointer to that entry.
 395
 396   @param  LogEntryKey             The key for the previous performance measurement log entry.
 397                                   If 0, then the first performance measurement log entry is retrieved.
 398   @param  GaugeDataEntry          The indirect pointer to the gauge data entry specified by LogEntryKey
 399                                   if the retrieval is successful.
 400
 401   @retval EFI_SUCCESS             The GuageDataEntry is successfully found based on LogEntryKey.
 402   @retval EFI_NOT_FOUND           The LogEntryKey is the last entry (equals to the total entry number).
 403   @retval EFI_INVALIDE_PARAMETER  The LogEntryKey is not a valid entry (greater than the total entry number).
 404   @retval EFI_INVALIDE_PARAMETER  GaugeDataEntry is NULL.
 405
 406 **/
 407 EFI_STATUS
 408 EFIAPI
 409 GetGauge (
 410   IN  UINTN               LogEntryKey,
 411   OUT GAUGE_DATA_ENTRY    **GaugeDataEntry
 412   )
 413 {
 414   EFI_STATUS          Status;
 415   GAUGE_DATA_ENTRY_EX *GaugeEntryEx;
 416
 417   GaugeEntryEx = NULL;
 418
 419   Status = GetGaugeEx (LogEntryKey, &GaugeEntryEx);
 420   if (EFI_ERROR (Status)) {
 421     return Status;
 422   }
 423
 424   if (GaugeDataEntry == NULL) {
 425     return EFI_INVALID_PARAMETER;
 426   }
 427
 428   *GaugeDataEntry = (GAUGE_DATA_ENTRY *) GaugeEntryEx;
 429
 430   return EFI_SUCCESS;
 431 }
 432
 433 /**
 434   Dumps all the PEI performance log to DXE performance gauge array.
 435
 436   This internal function dumps all the PEI performance log to the DXE performance gauge array.
 437   It retrieves the optional GUID HOB for PEI performance and then saves the performance data
 438   to DXE performance data structures.
 439
 440 **/
 441 VOID
 442 InternalGetPeiPerformance (
 443   VOID
 444   )
 445 {
 446   EFI_HOB_GUID_TYPE                 *GuidHob;
 447   PEI_PERFORMANCE_LOG_HEADER        *LogHob;
 448   PEI_PERFORMANCE_LOG_ENTRY         *LogEntryArray;
 449   UINT32                            *LogIdArray;
 450   GAUGE_DATA_ENTRY_EX               *GaugeEntryExArray;
 451   UINT32                            Index;
 452   UINT32                            NumberOfEntries;
 453
 454   NumberOfEntries = 0;
 455   GaugeEntryExArray = (GAUGE_DATA_ENTRY_EX *) (mGaugeData + 1);
 456
 457   //
 458   // Dump PEI Log Entries to DXE Guage Data structure.
 459   //
 460   GuidHob = GetFirstGuidHob (&gPerformanceProtocolGuid);
 461   if (GuidHob != NULL) {
 462     LogHob          = GET_GUID_HOB_DATA (GuidHob);
 463     LogEntryArray   = (PEI_PERFORMANCE_LOG_ENTRY *) (LogHob + 1);
 464
 465     NumberOfEntries = LogHob->NumberOfEntries;
 466     for (Index = 0; Index < NumberOfEntries; Index++) {
 467       GaugeEntryExArray[Index].Handle         = LogEntryArray[Index].Handle;
 468       AsciiStrCpyS (GaugeEntryExArray[Index].Token,  DXE_PERFORMANCE_STRING_SIZE, LogEntryArray[Index].Token);
 469       AsciiStrCpyS (GaugeEntryExArray[Index].Module, DXE_PERFORMANCE_STRING_SIZE, LogEntryArray[Index].Module);
 470       GaugeEntryExArray[Index].StartTimeStamp = LogEntryArray[Index].StartTimeStamp;
 471       GaugeEntryExArray[Index].EndTimeStamp   = LogEntryArray[Index].EndTimeStamp;
 472       GaugeEntryExArray[Index].Identifier     = 0;
 473     }
 474
 475     GuidHob = GetFirstGuidHob (&gPerformanceExProtocolGuid);
 476     if (GuidHob != NULL) {
 477       LogIdArray    = GET_GUID_HOB_DATA (GuidHob);
 478       for (Index = 0; Index < NumberOfEntries; Index++) {
 479         GaugeEntryExArray[Index].Identifier   = LogIdArray[Index];
 480       }
 481     }
 482   }
 483   mGaugeData->NumberOfEntries = NumberOfEntries;
 484 }
 485
 486 /**
 487   The constructor function initializes Performance infrastructure for DXE phase.
 488
 489   The constructor function publishes Performance and PerformanceEx protocol, allocates memory to log DXE performance
 490   and merges PEI performance data to DXE performance log.
 491   It will ASSERT() if one of these operations fails and it will always return EFI_SUCCESS.
 492
 493   @param  ImageHandle   The firmware allocated handle for the EFI image.
 494   @param  SystemTable   A pointer to the EFI System Table.
 495
 496   @retval EFI_SUCCESS   The constructor always returns EFI_SUCCESS.
 497
 498 **/
 499 EFI_STATUS
 500 EFIAPI
 501 DxeCorePerformanceLibConstructor (
 502   IN EFI_HANDLE        ImageHandle,
 503   IN EFI_SYSTEM_TABLE  *SystemTable
 504   )
 505 {
 506   EFI_STATUS                Status;
 507   PERFORMANCE_PROPERTY      *PerformanceProperty;
 508
 509
 510   if (!PerformanceMeasurementEnabled ()) {
 511     //
 512     // Do not initialize performance infrastructure if not required.
 513     //
 514     return EFI_SUCCESS;
 515   }
 516   //
 517   // Install the protocol interfaces.
 518   //
 519   Status = gBS->InstallMultipleProtocolInterfaces (
 520                   &mHandle,
 521                   &gPerformanceProtocolGuid,
 522                   &mPerformanceInterface,
 523                   &gPerformanceExProtocolGuid,
 524                   &mPerformanceExInterface,
 525                   NULL
 526                   );
 527   ASSERT_EFI_ERROR (Status);
 528
 529   mMaxGaugeRecords = INIT_DXE_GAUGE_DATA_ENTRIES + (UINT16) (PcdGet16 (PcdMaxPeiPerformanceLogEntries16) != 0 ?
 530                                                              PcdGet16 (PcdMaxPeiPerformanceLogEntries16) :
 531                                                              PcdGet8 (PcdMaxPeiPerformanceLogEntries));
 532
 533   mGaugeData = AllocateZeroPool (sizeof (GAUGE_DATA_HEADER) + (sizeof (GAUGE_DATA_ENTRY_EX) * mMaxGaugeRecords));
 534   ASSERT (mGaugeData != NULL);
 535
 536   InternalGetPeiPerformance ();
 537
 538   Status = EfiGetSystemConfigurationTable (&gPerformanceProtocolGuid, (VOID **) &PerformanceProperty);
 539   if (EFI_ERROR (Status)) {
 540     //
 541     // Install configuration table for performance property.
 542     //
 543     mPerformanceProperty.Revision  = PERFORMANCE_PROPERTY_REVISION;
 544     mPerformanceProperty.Reserved  = 0;
 545     mPerformanceProperty.Frequency = GetPerformanceCounterProperties (
 546                                        &mPerformanceProperty.TimerStartValue,
 547                                        &mPerformanceProperty.TimerEndValue
 548                                        );
 549     Status = gBS->InstallConfigurationTable (&gPerformanceProtocolGuid, &mPerformanceProperty);
 550     ASSERT_EFI_ERROR (Status);
 551   }
 552
 553   return EFI_SUCCESS;
 554 }
 555
 556 /**
 557   Adds a record at the end of the performance measurement log
 558   that records the start time of a performance measurement.
 559
 560   Adds a record to the end of the performance measurement log
 561   that contains the Handle, Token, Module and Identifier.
 562   The end time of the new record must be set to zero.
 563   If TimeStamp is not zero, then TimeStamp is used to fill in the start time in the record.
 564   If TimeStamp is zero, the start time in the record is filled in with the value
 565   read from the current time stamp.
 566
 567   @param  Handle                  Pointer to environment specific context used
 568                                   to identify the component being measured.
 569   @param  Token                   Pointer to a Null-terminated ASCII string
 570                                   that identifies the component being measured.
 571   @param  Module                  Pointer to a Null-terminated ASCII string
 572                                   that identifies the module being measured.
 573   @param  TimeStamp               64-bit time stamp.
 574   @param  Identifier              32-bit identifier. If the value is 0, the created record
 575                                   is same as the one created by StartPerformanceMeasurement.
 576
 577   @retval RETURN_SUCCESS          The start of the measurement was recorded.
 578   @retval RETURN_OUT_OF_RESOURCES There are not enough resources to record the measurement.
 579
 580 **/
 581 RETURN_STATUS
 582 EFIAPI
 583 StartPerformanceMeasurementEx (
 584   IN CONST VOID   *Handle,  OPTIONAL
 585   IN CONST CHAR8  *Token,   OPTIONAL
 586   IN CONST CHAR8  *Module,  OPTIONAL
 587   IN UINT64       TimeStamp,
 588   IN UINT32       Identifier
 589   )
 590 {
 591   return (RETURN_STATUS) StartGaugeEx (Handle, Token, Module, TimeStamp, Identifier);
 592 }
 593
 594 /**
 595   Searches the performance measurement log from the beginning of the log
 596   for the first matching record that contains a zero end time and fills in a valid end time.
 597
 598   Searches the performance measurement log from the beginning of the log
 599   for the first record that matches Handle, Token and Module and has an end time value of zero.
 600   If the record can not be found then return RETURN_NOT_FOUND.
 601   If the record is found and TimeStamp is not zero,
 602   then the end time in the record is filled in with the value specified by TimeStamp.
 603   If the record is found and TimeStamp is zero, then the end time in the matching record
 604   is filled in with the current time stamp value.
 605
 606   @param  Handle                  Pointer to environment specific context used
 607                                   to identify the component being measured.
 608   @param  Token                   Pointer to a Null-terminated ASCII string
 609                                   that identifies the component being measured.
 610   @param  Module                  Pointer to a Null-terminated ASCII string
 611                                   that identifies the module being measured.
 612   @param  TimeStamp               64-bit time stamp.
 613   @param  Identifier              32-bit identifier. If the value is 0, the found record
 614                                   is same as the one found by EndPerformanceMeasurement.
 615
 616   @retval RETURN_SUCCESS          The end of  the measurement was recorded.
 617   @retval RETURN_NOT_FOUND        The specified measurement record could not be found.
 618
 619 **/
 620 RETURN_STATUS
 621 EFIAPI
 622 EndPerformanceMeasurementEx (
 623   IN CONST VOID   *Handle,  OPTIONAL
 624   IN CONST CHAR8  *Token,   OPTIONAL
 625   IN CONST CHAR8  *Module,  OPTIONAL
 626   IN UINT64       TimeStamp,
 627   IN UINT32       Identifier
 628   )
 629 {
 630   return (RETURN_STATUS) EndGaugeEx (Handle, Token, Module, TimeStamp, Identifier);
 631 }
 632
 633 /**
 634   Attempts to retrieve a performance measurement log entry from the performance measurement log.
 635   It can also retrieve the log created by StartPerformanceMeasurement and EndPerformanceMeasurement,
 636   and then assign the Identifier with 0.
 637
 638   Attempts to retrieve the performance log entry specified by LogEntryKey.  If LogEntryKey is
 639   zero on entry, then an attempt is made to retrieve the first entry from the performance log,
 640   and the key for the second entry in the log is returned.  If the performance log is empty,
 641   then no entry is retrieved and zero is returned.  If LogEntryKey is not zero, then the performance
 642   log entry associated with LogEntryKey is retrieved, and the key for the next entry in the log is
 643   returned.  If LogEntryKey is the key for the last entry in the log, then the last log entry is
 644   retrieved and an implementation specific non-zero key value that specifies the end of the performance
 645   log is returned.  If LogEntryKey is equal this implementation specific non-zero key value, then no entry
 646   is retrieved and zero is returned.  In the cases where a performance log entry can be returned,
 647   the log entry is returned in Handle, Token, Module, StartTimeStamp, EndTimeStamp and Identifier.
 648   If LogEntryKey is not a valid log entry key for the performance measurement log, then ASSERT().
 649   If Handle is NULL, then ASSERT().
 650   If Token is NULL, then ASSERT().
 651   If Module is NULL, then ASSERT().
 652   If StartTimeStamp is NULL, then ASSERT().
 653   If EndTimeStamp is NULL, then ASSERT().
 654   If Identifier is NULL, then ASSERT().
 655
 656   @param  LogEntryKey             On entry, the key of the performance measurement log entry to retrieve.
 657                                   0, then the first performance measurement log entry is retrieved.
 658                                   On exit, the key of the next performance log entry.
 659   @param  Handle                  Pointer to environment specific context used to identify the component
 660                                   being measured.
 661   @param  Token                   Pointer to a Null-terminated ASCII string that identifies the component
 662                                   being measured.
 663   @param  Module                  Pointer to a Null-terminated ASCII string that identifies the module
 664                                   being measured.
 665   @param  StartTimeStamp          Pointer to the 64-bit time stamp that was recorded when the measurement
 666                                   was started.
 667   @param  EndTimeStamp            Pointer to the 64-bit time stamp that was recorded when the measurement
 668                                   was ended.
 669   @param  Identifier              Pointer to the 32-bit identifier that was recorded.
 670
 671   @return The key for the next performance log entry (in general case).
 672
 673 **/
 674 UINTN
 675 EFIAPI
 676 GetPerformanceMeasurementEx (
 677   IN  UINTN       LogEntryKey,
 678   OUT CONST VOID  **Handle,
 679   OUT CONST CHAR8 **Token,
 680   OUT CONST CHAR8 **Module,
 681   OUT UINT64      *StartTimeStamp,
 682   OUT UINT64      *EndTimeStamp,
 683   OUT UINT32      *Identifier
 684   )
 685 {
 686   EFI_STATUS           Status;
 687   GAUGE_DATA_ENTRY_EX  *GaugeData;
 688
 689   GaugeData = NULL;
 690
 691   ASSERT (Handle != NULL);
 692   ASSERT (Token != NULL);
 693   ASSERT (Module != NULL);
 694   ASSERT (StartTimeStamp != NULL);
 695   ASSERT (EndTimeStamp != NULL);
 696   ASSERT (Identifier != NULL);
 697
 698   Status = GetGaugeEx (LogEntryKey++, &GaugeData);
 699
 700   //
 701   // Make sure that LogEntryKey is a valid log entry key,
 702   //
 703   ASSERT (Status != EFI_INVALID_PARAMETER);
 704
 705   if (EFI_ERROR (Status)) {
 706     //
 707     // The LogEntryKey is the last entry (equals to the total entry number).
 708     //
 709     return 0;
 710   }
 711
 712   ASSERT (GaugeData != NULL);
 713
 714   *Handle         = (VOID *) (UINTN) GaugeData->Handle;
 715   *Token          = GaugeData->Token;
 716   *Module         = GaugeData->Module;
 717   *StartTimeStamp = GaugeData->StartTimeStamp;
 718   *EndTimeStamp   = GaugeData->EndTimeStamp;
 719   *Identifier     = GaugeData->Identifier;
 720
 721   return LogEntryKey;
 722 }
 723
 724 /**
 725   Adds a record at the end of the performance measurement log
 726   that records the start time of a performance measurement.
 727
 728   Adds a record to the end of the performance measurement log
 729   that contains the Handle, Token, and Module.
 730   The end time of the new record must be set to zero.
 731   If TimeStamp is not zero, then TimeStamp is used to fill in the start time in the record.
 732   If TimeStamp is zero, the start time in the record is filled in with the value
 733   read from the current time stamp.
 734
 735   @param  Handle                  Pointer to environment specific context used
 736                                   to identify the component being measured.
 737   @param  Token                   Pointer to a Null-terminated ASCII string
 738                                   that identifies the component being measured.
 739   @param  Module                  Pointer to a Null-terminated ASCII string
 740                                   that identifies the module being measured.
 741   @param  TimeStamp               64-bit time stamp.
 742
 743   @retval RETURN_SUCCESS          The start of the measurement was recorded.
 744   @retval RETURN_OUT_OF_RESOURCES There are not enough resources to record the measurement.
 745
 746 **/
 747 RETURN_STATUS
 748 EFIAPI
 749 StartPerformanceMeasurement (
 750   IN CONST VOID   *Handle,  OPTIONAL
 751   IN CONST CHAR8  *Token,   OPTIONAL
 752   IN CONST CHAR8  *Module,  OPTIONAL
 753   IN UINT64       TimeStamp
 754   )
 755 {
 756   return StartPerformanceMeasurementEx (Handle, Token, Module, TimeStamp, 0);
 757 }
 758
 759 /**
 760   Searches the performance measurement log from the beginning of the log
 761   for the first matching record that contains a zero end time and fills in a valid end time.
 762
 763   Searches the performance measurement log from the beginning of the log
 764   for the first record that matches Handle, Token, and Module and has an end time value of zero.
 765   If the record can not be found then return RETURN_NOT_FOUND.
 766   If the record is found and TimeStamp is not zero,
 767   then the end time in the record is filled in with the value specified by TimeStamp.
 768   If the record is found and TimeStamp is zero, then the end time in the matching record
 769   is filled in with the current time stamp value.
 770
 771   @param  Handle                  Pointer to environment specific context used
 772                                   to identify the component being measured.
 773   @param  Token                   Pointer to a Null-terminated ASCII string
 774                                   that identifies the component being measured.
 775   @param  Module                  Pointer to a Null-terminated ASCII string
 776                                   that identifies the module being measured.
 777   @param  TimeStamp               64-bit time stamp.
 778
 779   @retval RETURN_SUCCESS          The end of  the measurement was recorded.
 780   @retval RETURN_NOT_FOUND        The specified measurement record could not be found.
 781
 782 **/
 783 RETURN_STATUS
 784 EFIAPI
 785 EndPerformanceMeasurement (
 786   IN CONST VOID   *Handle,  OPTIONAL
 787   IN CONST CHAR8  *Token,   OPTIONAL
 788   IN CONST CHAR8  *Module,  OPTIONAL
 789   IN UINT64       TimeStamp
 790   )
 791 {
 792   return EndPerformanceMeasurementEx (Handle, Token, Module, TimeStamp, 0);
 793 }
 794
 795 /**
 796   Attempts to retrieve a performance measurement log entry from the performance measurement log.
 797   It can also retrieve the log created by StartPerformanceMeasurementEx and EndPerformanceMeasurementEx,
 798   and then eliminate the Identifier.
 799
 800   Attempts to retrieve the performance log entry specified by LogEntryKey.  If LogEntryKey is
 801   zero on entry, then an attempt is made to retrieve the first entry from the performance log,
 802   and the key for the second entry in the log is returned.  If the performance log is empty,
 803   then no entry is retrieved and zero is returned.  If LogEntryKey is not zero, then the performance
 804   log entry associated with LogEntryKey is retrieved, and the key for the next entry in the log is
 805   returned.  If LogEntryKey is the key for the last entry in the log, then the last log entry is
 806   retrieved and an implementation specific non-zero key value that specifies the end of the performance
 807   log is returned.  If LogEntryKey is equal this implementation specific non-zero key value, then no entry
 808   is retrieved and zero is returned.  In the cases where a performance log entry can be returned,
 809   the log entry is returned in Handle, Token, Module, StartTimeStamp, and EndTimeStamp.
 810   If LogEntryKey is not a valid log entry key for the performance measurement log, then ASSERT().
 811   If Handle is NULL, then ASSERT().
 812   If Token is NULL, then ASSERT().
 813   If Module is NULL, then ASSERT().
 814   If StartTimeStamp is NULL, then ASSERT().
 815   If EndTimeStamp is NULL, then ASSERT().
 816
 817   @param  LogEntryKey             On entry, the key of the performance measurement log entry to retrieve.
 818                                   0, then the first performance measurement log entry is retrieved.
 819                                   On exit, the key of the next performance log entry.
 820   @param  Handle                  Pointer to environment specific context used to identify the component
 821                                   being measured.
 822   @param  Token                   Pointer to a Null-terminated ASCII string that identifies the component
 823                                   being measured.
 824   @param  Module                  Pointer to a Null-terminated ASCII string that identifies the module
 825                                   being measured.
 826   @param  StartTimeStamp          Pointer to the 64-bit time stamp that was recorded when the measurement
 827                                   was started.
 828   @param  EndTimeStamp            Pointer to the 64-bit time stamp that was recorded when the measurement
 829                                   was ended.
 830
 831   @return The key for the next performance log entry (in general case).
 832
 833 **/
 834 UINTN
 835 EFIAPI
 836 GetPerformanceMeasurement (
 837   IN  UINTN       LogEntryKey,
 838   OUT CONST VOID  **Handle,
 839   OUT CONST CHAR8 **Token,
 840   OUT CONST CHAR8 **Module,
 841   OUT UINT64      *StartTimeStamp,
 842   OUT UINT64      *EndTimeStamp
 843   )
 844 {
 845   UINT32 Identifier;
 846   return GetPerformanceMeasurementEx (LogEntryKey, Handle, Token, Module, StartTimeStamp, EndTimeStamp, &Identifier);
 847 }
 848
 849 /**
 850   Returns TRUE if the performance measurement macros are enabled.
 851
 852   This function returns TRUE if the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
 853   PcdPerformanceLibraryPropertyMask is set.  Otherwise FALSE is returned.
 854
 855   @retval TRUE                    The PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
 856                                   PcdPerformanceLibraryPropertyMask is set.
 857   @retval FALSE                   The PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
 858                                   PcdPerformanceLibraryPropertyMask is clear.
 859
 860 **/
 861 BOOLEAN
 862 EFIAPI
 863 PerformanceMeasurementEnabled (
 864   VOID
 865   )
 866 {
 867   return (BOOLEAN) ((PcdGet8(PcdPerformanceLibraryPropertyMask) & PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED) != 0);
 868 }