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