MdePkg/Library/BasePerformanceLibNull/PerformanceLib.c

   1 /** @file
   2   Base Performance Library which provides no service.
   3
   4   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php.
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15
  16 #include <Base.h>
  17
  18
  19 #include <Library/PerformanceLib.h>
  20 #include <Library/DebugLib.h>
  21 #include <Library/PcdLib.h>
  22
  23 /**
  24   Creates a record for the beginning of a performance measurement.
  25
  26   Creates a record that contains the Handle, Token, and Module.
  27   If TimeStamp is not zero, then TimeStamp is added to the record as the start time.
  28   If TimeStamp is zero, then this function reads the current time stamp
  29   and adds that time stamp value to the record as the start time.
  30
  31   @param  Handle                  The pointer to environment specific context used
  32                                   to identify the component being measured.
  33   @param  Token                   The pointer to a Null-terminated ASCII string
  34                                   that identifies the component being measured.
  35   @param  Module                  The pointer to a Null-terminated ASCII string
  36                                   that identifies the module being measured.
  37   @param  TimeStamp               64-bit time stamp.
  38
  39   @retval RETURN_SUCCESS          The start of the measurement was recorded.
  40   @retval RETURN_OUT_OF_RESOURCES There are not enough resources to record the measurement.
  41   @retval RETURN_DEVICE_ERROR     A device error reading the time stamp.
  42
  43 **/
  44 RETURN_STATUS
  45 EFIAPI
  46 StartPerformanceMeasurement (
  47   IN CONST VOID   *Handle,  OPTIONAL
  48   IN CONST CHAR8  *Token,   OPTIONAL
  49   IN CONST CHAR8  *Module,  OPTIONAL
  50   IN UINT64       TimeStamp
  51   )
  52 {
  53   return RETURN_SUCCESS;
  54 }
  55
  56 /**
  57   Fills in the end time of a performance measurement.
  58
  59   Looks up the record that matches Handle, Token, and Module.
  60   If the record can not be found then return RETURN_NOT_FOUND.
  61   If the record is found and TimeStamp is not zero,
  62   then TimeStamp is added to the record as the end time.
  63   If the record is found and TimeStamp is zero, then this function reads
  64   the current time stamp and adds that time stamp value to the record as the end time.
  65
  66   @param  Handle                  The pointer to environment specific context used
  67                                   to identify the component being measured.
  68   @param  Token                   The pointer to a Null-terminated ASCII string
  69                                   that identifies the component being measured.
  70   @param  Module                  The pointer to a Null-terminated ASCII string
  71                                   that identifies the module being measured.
  72   @param  TimeStamp               64-bit time stamp.
  73
  74   @retval RETURN_SUCCESS          The end of the measurement was recorded.
  75   @retval RETURN_NOT_FOUND        The specified measurement record could not be found.
  76   @retval RETURN_DEVICE_ERROR     A device error reading the time stamp.
  77
  78 **/
  79 RETURN_STATUS
  80 EFIAPI
  81 EndPerformanceMeasurement (
  82   IN CONST VOID   *Handle,  OPTIONAL
  83   IN CONST CHAR8  *Token,   OPTIONAL
  84   IN CONST CHAR8  *Module,  OPTIONAL
  85   IN UINT64       TimeStamp
  86   )
  87 {
  88   return RETURN_SUCCESS;
  89 }
  90
  91 /**
  92   Attempts to retrieve a performance measurement log entry from the performance measurement log.
  93   It can also retrieve the log created by StartPerformanceMeasurementEx and EndPerformanceMeasurementEx,
  94   and then eliminate the Identifier.
  95
  96   Attempts to retrieve the performance log entry specified by LogEntryKey.  If LogEntryKey is
  97   zero on entry, then an attempt is made to retrieve the first entry from the performance log,
  98   and the key for the second entry in the log is returned.  If the performance log is empty,
  99   then no entry is retrieved and zero is returned.  If LogEntryKey is not zero, then the performance
 100   log entry associated with LogEntryKey is retrieved, and the key for the next entry in the log is
 101   returned.  If LogEntryKey is the key for the last entry in the log, then the last log entry is
 102   retrieved and an implementation specific non-zero key value that specifies the end of the performance
 103   log is returned.  If LogEntryKey is equal this implementation specific non-zero key value, then no entry
 104   is retrieved and zero is returned.  In the cases where a performance log entry can be returned,
 105   the log entry is returned in Handle, Token, Module, StartTimeStamp, and EndTimeStamp.
 106   If LogEntryKey is not a valid log entry key for the performance measurement log, then ASSERT().
 107   If Handle is NULL, then ASSERT().
 108   If Token is NULL, then ASSERT().
 109   If Module is NULL, then ASSERT().
 110   If StartTimeStamp is NULL, then ASSERT().
 111   If EndTimeStamp is NULL, then ASSERT().
 112
 113   @param  LogEntryKey             On entry, the key of the performance measurement log entry to retrieve.
 114                                   0, then the first performance measurement log entry is retrieved.
 115                                   On exit, the key of the next performance lof entry entry.
 116   @param  Handle                  The pointer to environment specific context used to identify the component
 117                                   being measured.
 118   @param  Token                   The pointer to a Null-terminated ASCII string that identifies the component
 119                                   being measured.
 120   @param  Module                  The pointer to a Null-terminated ASCII string that identifies the module
 121                                   being measured.
 122   @param  StartTimeStamp          The pointer to the 64-bit time stamp that was recorded when the measurement
 123                                   was started.
 124   @param  EndTimeStamp            The pointer to the 64-bit time stamp that was recorded when the measurement
 125                                   was ended.
 126
 127   @return The key for the next performance log entry (in general case).
 128
 129 **/
 130 UINTN
 131 EFIAPI
 132 GetPerformanceMeasurement (
 133   IN  UINTN       LogEntryKey,
 134   OUT CONST VOID  **Handle,
 135   OUT CONST CHAR8 **Token,
 136   OUT CONST CHAR8 **Module,
 137   OUT UINT64      *StartTimeStamp,
 138   OUT UINT64      *EndTimeStamp
 139   )
 140 {
 141   ASSERT (Handle != NULL);
 142   ASSERT (Token != NULL);
 143   ASSERT (Module != NULL);
 144   ASSERT (StartTimeStamp != NULL);
 145   ASSERT (EndTimeStamp != NULL);
 146
 147   return 0;
 148 }
 149
 150 /**
 151   Creates a record for the beginning of a performance measurement.
 152
 153   Creates a record that contains the Handle, Token, Module and Identifier.
 154   If TimeStamp is not zero, then TimeStamp is added to the record as the start time.
 155   If TimeStamp is zero, then this function reads the current time stamp
 156   and adds that time stamp value to the record as the start time.
 157
 158   @param  Handle                  Pointer to environment specific context used
 159                                   to identify the component being measured.
 160   @param  Token                   Pointer to a Null-terminated ASCII string
 161                                   that identifies the component being measured.
 162   @param  Module                  Pointer to a Null-terminated ASCII string
 163                                   that identifies the module being measured.
 164   @param  TimeStamp               64-bit time stamp.
 165   @param  Identifier              32-bit identifier. If the value is 0, the created record
 166                                   is same as the one created by StartPerformanceMeasurement.
 167
 168   @retval RETURN_SUCCESS          The start of the measurement was recorded.
 169   @retval RETURN_OUT_OF_RESOURCES There are not enough resources to record the measurement.
 170   @retval RETURN_DEVICE_ERROR     A device error reading the time stamp.
 171
 172 **/
 173 RETURN_STATUS
 174 EFIAPI
 175 StartPerformanceMeasurementEx (
 176   IN CONST VOID   *Handle,  OPTIONAL
 177   IN CONST CHAR8  *Token,   OPTIONAL
 178   IN CONST CHAR8  *Module,  OPTIONAL
 179   IN UINT64       TimeStamp,
 180   IN UINT32       Identifier
 181   )
 182 {
 183   return RETURN_SUCCESS;
 184 }
 185
 186 /**
 187   Fills in the end time of a performance measurement.
 188
 189   Looks up the record that matches Handle, Token, Module and Identifier.
 190   If the record can not be found then return RETURN_NOT_FOUND.
 191   If the record is found and TimeStamp is not zero,
 192   then TimeStamp is added to the record as the end time.
 193   If the record is found and TimeStamp is zero, then this function reads
 194   the current time stamp and adds that time stamp value to the record as the end time.
 195
 196   @param  Handle                  Pointer to environment specific context used
 197                                   to identify the component being measured.
 198   @param  Token                   Pointer to a Null-terminated ASCII string
 199                                   that identifies the component being measured.
 200   @param  Module                  Pointer to a Null-terminated ASCII string
 201                                   that identifies the module being measured.
 202   @param  TimeStamp               64-bit time stamp.
 203   @param  Identifier              32-bit identifier. If the value is 0, the found record
 204                                   is same as the one found by EndPerformanceMeasurement.
 205
 206   @retval RETURN_SUCCESS          The end of  the measurement was recorded.
 207   @retval RETURN_NOT_FOUND        The specified measurement record could not be found.
 208   @retval RETURN_DEVICE_ERROR     A device error reading the time stamp.
 209
 210 **/
 211 RETURN_STATUS
 212 EFIAPI
 213 EndPerformanceMeasurementEx (
 214   IN CONST VOID   *Handle,  OPTIONAL
 215   IN CONST CHAR8  *Token,   OPTIONAL
 216   IN CONST CHAR8  *Module,  OPTIONAL
 217   IN UINT64       TimeStamp,
 218   IN UINT32       Identifier
 219   )
 220 {
 221   return RETURN_SUCCESS;
 222 }
 223
 224 /**
 225   Attempts to retrieve a performance measurement log entry from the performance measurement log.
 226   It can also retrieve the log created by StartPerformanceMeasurement and EndPerformanceMeasurement,
 227   and then assign the Identifier with 0.
 228
 229   Attempts to retrieve the performance log entry specified by LogEntryKey.  If LogEntryKey is
 230   zero on entry, then an attempt is made to retrieve the first entry from the performance log,
 231   and the key for the second entry in the log is returned.  If the performance log is empty,
 232   then no entry is retrieved and zero is returned.  If LogEntryKey is not zero, then the performance
 233   log entry associated with LogEntryKey is retrieved, and the key for the next entry in the log is
 234   returned.  If LogEntryKey is the key for the last entry in the log, then the last log entry is
 235   retrieved and an implementation specific non-zero key value that specifies the end of the performance
 236   log is returned.  If LogEntryKey is equal this implementation specific non-zero key value, then no entry
 237   is retrieved and zero is returned.  In the cases where a performance log entry can be returned,
 238   the log entry is returned in Handle, Token, Module, StartTimeStamp, EndTimeStamp and Identifier.
 239   If LogEntryKey is not a valid log entry key for the performance measurement log, then ASSERT().
 240   If Handle is NULL, then ASSERT().
 241   If Token is NULL, then ASSERT().
 242   If Module is NULL, then ASSERT().
 243   If StartTimeStamp is NULL, then ASSERT().
 244   If EndTimeStamp is NULL, then ASSERT().
 245   If Identifier is NULL, then ASSERT().
 246
 247   @param  LogEntryKey             On entry, the key of the performance measurement log entry to retrieve.
 248                                   0, then the first performance measurement log entry is retrieved.
 249                                   On exit, the key of the next performance lof entry entry.
 250   @param  Handle                  Pointer to environment specific context used to identify the component
 251                                   being measured.
 252   @param  Token                   Pointer to a Null-terminated ASCII string that identifies the component
 253                                   being measured.
 254   @param  Module                  Pointer to a Null-terminated ASCII string that identifies the module
 255                                   being measured.
 256   @param  StartTimeStamp          Pointer to the 64-bit time stamp that was recorded when the measurement
 257                                   was started.
 258   @param  EndTimeStamp            Pointer to the 64-bit time stamp that was recorded when the measurement
 259                                   was ended.
 260   @param  Identifier              Pointer to the 32-bit identifier that was recorded.
 261
 262   @return The key for the next performance log entry (in general case).
 263
 264 **/
 265 UINTN
 266 EFIAPI
 267 GetPerformanceMeasurementEx (
 268   IN  UINTN       LogEntryKey,
 269   OUT CONST VOID  **Handle,
 270   OUT CONST CHAR8 **Token,
 271   OUT CONST CHAR8 **Module,
 272   OUT UINT64      *StartTimeStamp,
 273   OUT UINT64      *EndTimeStamp,
 274   OUT UINT32      *Identifier
 275   )
 276 {
 277   ASSERT (Handle != NULL);
 278   ASSERT (Token != NULL);
 279   ASSERT (Module != NULL);
 280   ASSERT (StartTimeStamp != NULL);
 281   ASSERT (EndTimeStamp != NULL);
 282   ASSERT (Identifier != NULL);
 283
 284   return 0;
 285 }
 286
 287 /**
 288   Returns TRUE if the performance measurement macros are enabled.
 289
 290   This function returns TRUE if the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
 291   PcdPerformanceLibraryPropertyMask is set.  Otherwise FALSE is returned.
 292
 293   @retval TRUE                    The PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
 294                                   PcdPerformanceLibraryPropertyMask is set.
 295   @retval FALSE                   The PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of
 296                                   PcdPerformanceLibraryPropertyMask is clear.
 297
 298 **/
 299 BOOLEAN
 300 EFIAPI
 301 PerformanceMeasurementEnabled (
 302   VOID
 303   )
 304 {
 305   return (BOOLEAN) ((PcdGet8(PcdPerformanceLibraryPropertyMask) & PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED) != 0);
 306 }
 307
 308 /**
 309   Create performance record with event description and a timestamp.
 310
 311   @param CallerIdentifier  - Image handle or pointer to caller ID GUID
 312   @param Guid              - Pointer to a GUID
 313   @param String            - Pointer to a string describing the measurement
 314   @param Address           - Pointer to a location in memory relevant to the measurement
 315   @param Identifier        - Performance identifier describing the type of measurement
 316
 317   @retval RETURN_SUCCESS           - Successfully created performance record
 318   @retval RETURN_OUT_OF_RESOURCES  - Ran out of space to store the records
 319   @retval RETURN_INVALID_PARAMETER - Invalid parameter passed to function - NULL
 320                                      pointer or invalid PerfId
 321
 322 **/
 323 RETURN_STATUS
 324 EFIAPI
 325 LogPerformanceMeasurement (
 326   IN CONST VOID   *CallerIdentifier,OPTIONAL
 327   IN CONST VOID   *Guid,    OPTIONAL
 328   IN CONST CHAR8  *String,  OPTIONAL
 329   IN UINT64       Address,  OPTIONAL
 330   IN UINT32       Identifier
 331   )
 332 {
 333   return RETURN_SUCCESS;
 334 }
 335
 336 /**
 337   Check whether the specified performance measurement can be logged.
 338
 339   This function returns TRUE when the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set
 340   and the Type disable bit in PcdPerformanceLibraryPropertyMask is not set.
 341
 342   @param Type        - Type of the performance measurement entry.
 343
 344   @retval TRUE         The performance measurement can be logged.
 345   @retval FALSE        The performance measurement can NOT be logged.
 346
 347 **/
 348 BOOLEAN
 349 EFIAPI
 350 LogPerformanceMeasurementEnabled (
 351   IN  CONST UINTN        Type
 352   )
 353 {
 354   //
 355   // When Performance measurement is enabled and the type is not filtered, the performance can be logged.
 356   //
 357   if (PerformanceMeasurementEnabled () && (PcdGet8(PcdPerformanceLibraryPropertyMask) & Type) == 0) {
 358     return TRUE;
 359   }
 360   return FALSE;
 361 }