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