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