MdeModulePkg/Include/Guid/Performance.h

   1 /** @file
   2   This file defines performance-related definitions, including the format of:
   3   * performance GUID HOB.
   4   * performance protocol interfaces.
   5   * performance variables.
   6
   7 Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
   8 SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __PERFORMANCE_DATA_H__
  13 #define __PERFORMANCE_DATA_H__
  14
  15 #define PERFORMANCE_PROPERTY_REVISION 0x1
  16
  17 typedef struct {
  18   UINT32                Revision;
  19   UINT32                Reserved;
  20   UINT64                Frequency;
  21   UINT64                TimerStartValue;
  22   UINT64                TimerEndValue;
  23 } PERFORMANCE_PROPERTY;
  24
  25 //
  26 // PEI_PERFORMANCE_STRING_SIZE must be a multiple of 8.
  27 //
  28 #define PEI_PERFORMANCE_STRING_SIZE     8
  29 #define PEI_PERFORMANCE_STRING_LENGTH   (PEI_PERFORMANCE_STRING_SIZE - 1)
  30
  31 typedef struct {
  32   EFI_PHYSICAL_ADDRESS  Handle;
  33   CHAR8                 Token[PEI_PERFORMANCE_STRING_SIZE];   ///< Measured token string name.
  34   CHAR8                 Module[PEI_PERFORMANCE_STRING_SIZE];  ///< Module string name.
  35   UINT64                StartTimeStamp;                       ///< Start time point.
  36   UINT64                EndTimeStamp;                         ///< End time point.
  37 } PEI_PERFORMANCE_LOG_ENTRY;
  38
  39 //
  40 // The header must be aligned at 8 bytes.
  41 //
  42 typedef struct {
  43   UINT32                NumberOfEntries;  ///< The number of all performance log entries.
  44   UINT32                Reserved;
  45 } PEI_PERFORMANCE_LOG_HEADER;
  46
  47
  48 #define PERFORMANCE_PROTOCOL_GUID \
  49   { 0x76b6bdfa, 0x2acd, 0x4462, { 0x9E, 0x3F, 0xcb, 0x58, 0xC9, 0x69, 0xd9, 0x37 } }
  50
  51 #define PERFORMANCE_EX_PROTOCOL_GUID \
  52   { 0x1ea81bec, 0xf01a, 0x4d98, { 0xa2, 0x1,  0x4a, 0x61, 0xce, 0x2f, 0xc0, 0x22 } }
  53
  54 //
  55 // Forward reference for pure ANSI compatibility
  56 //
  57 typedef struct _PERFORMANCE_PROTOCOL PERFORMANCE_PROTOCOL;
  58 typedef struct _PERFORMANCE_EX_PROTOCOL PERFORMANCE_EX_PROTOCOL;
  59
  60 //
  61 // DXE_PERFORMANCE_STRING_SIZE must be a multiple of 8.
  62 //
  63 #define DXE_PERFORMANCE_STRING_SIZE     32
  64 #define DXE_PERFORMANCE_STRING_LENGTH   (DXE_PERFORMANCE_STRING_SIZE - 1)
  65
  66 //
  67 // The default guage entries number for DXE phase.
  68 //
  69 #define INIT_DXE_GAUGE_DATA_ENTRIES     800
  70
  71 typedef struct {
  72   EFI_PHYSICAL_ADDRESS  Handle;
  73   CHAR8                 Token[DXE_PERFORMANCE_STRING_SIZE];  ///< Measured token string name.
  74   CHAR8                 Module[DXE_PERFORMANCE_STRING_SIZE]; ///< Module string name.
  75   UINT64                StartTimeStamp;                      ///< Start time point.
  76   UINT64                EndTimeStamp;                        ///< End time point.
  77 } GAUGE_DATA_ENTRY;
  78
  79 typedef struct {
  80   EFI_PHYSICAL_ADDRESS  Handle;
  81   CHAR8                 Token[DXE_PERFORMANCE_STRING_SIZE];  ///< Measured token string name.
  82   CHAR8                 Module[DXE_PERFORMANCE_STRING_SIZE]; ///< Module string name.
  83   UINT64                StartTimeStamp;                      ///< Start time point.
  84   UINT64                EndTimeStamp;                        ///< End time point.
  85   UINT32                Identifier;                          ///< Identifier.
  86 } GAUGE_DATA_ENTRY_EX;
  87
  88 //
  89 // The header must be aligned at 8 bytes
  90 //
  91 typedef struct {
  92   UINT32                NumberOfEntries; ///< The number of all performance gauge entries.
  93   UINT32                Reserved;
  94 } GAUGE_DATA_HEADER;
  95
  96 //
  97 // SMM Performance Protocol definitions
  98 //
  99
 100 #define SMM_PERFORMANCE_PROTOCOL_GUID \
 101   { 0xf866226a, 0xeaa5, 0x4f5a, { 0xa9, 0xa,  0x6c, 0xfb, 0xa5, 0x7c, 0x58, 0x8e } }
 102
 103 #define SMM_PERFORMANCE_EX_PROTOCOL_GUID \
 104   { 0x931fc048, 0xc71d, 0x4455, { 0x89, 0x30, 0x47, 0x6,  0x30, 0xe3, 0xe,  0xe5 } }
 105
 106 //
 107 // SMM_PERFORMANCE_STRING_SIZE.
 108 //
 109 #define SMM_PERFORMANCE_STRING_SIZE     32
 110 #define SMM_PERFORMANCE_STRING_LENGTH   (SMM_PERFORMANCE_STRING_SIZE - 1)
 111
 112 //
 113 // The default guage entries number for SMM phase.
 114 //
 115 #define INIT_SMM_GAUGE_DATA_ENTRIES     200
 116
 117 typedef struct {
 118   UINTN             Function;
 119   EFI_STATUS        ReturnStatus;
 120   UINTN             NumberOfEntries;
 121   UINTN             LogEntryKey;
 122   GAUGE_DATA_ENTRY  *GaugeData;
 123 } SMM_PERF_COMMUNICATE;
 124
 125 typedef struct {
 126   UINTN                Function;
 127   EFI_STATUS           ReturnStatus;
 128   UINTN                NumberOfEntries;
 129   UINTN                LogEntryKey;
 130   GAUGE_DATA_ENTRY_EX  *GaugeDataEx;
 131 } SMM_PERF_COMMUNICATE_EX;
 132
 133 #define SMM_PERF_FUNCTION_GET_GAUGE_ENTRY_NUMBER          1
 134 #define SMM_PERF_FUNCTION_GET_GAUGE_DATA                  2
 135
 136 /**
 137   Adds a record at the end of the performance measurement log
 138   that records the start time of a performance measurement.
 139
 140   The added record contains the Handle, Token, and Module.
 141   The end time of the new record is not recorded, so it is set to zero.
 142   If TimeStamp is not zero, then TimeStamp is used to fill in the start time in the record.
 143   If TimeStamp is zero, the start time in the record is filled in with the value
 144   read from the current time stamp.
 145
 146   @param  Handle                  The pointer to environment specific context used
 147                                   to identify the component being measured.
 148   @param  Token                   The pointer to a Null-terminated ASCII string
 149                                   that identifies the component being measured.
 150   @param  Module                  The pointer to a Null-terminated ASCII string
 151                                   that identifies the module being measured.
 152   @param  TimeStamp               The 64-bit time stamp.
 153
 154   @retval EFI_SUCCESS             The data was read correctly from the device.
 155   @retval EFI_OUT_OF_RESOURCES    There are not enough resources to record the measurement.
 156
 157 **/
 158 typedef
 159 EFI_STATUS
 160 (EFIAPI * PERFORMANCE_START_GAUGE)(
 161   IN CONST VOID   *Handle,  OPTIONAL
 162   IN CONST CHAR8  *Token,   OPTIONAL
 163   IN CONST CHAR8  *Module,  OPTIONAL
 164   IN UINT64       TimeStamp
 165   );
 166
 167 /**
 168   Searches the performance measurement log from the beginning of the log
 169   for the first matching record that contains a zero end time and fills in a valid end time.
 170
 171   Searches the performance measurement log from the beginning of the log
 172   for the first record that matches Handle, Token, and Module, and has an end time value of zero.
 173   If the record can not be found then return EFI_NOT_FOUND.
 174   If the record is found and TimeStamp is not zero,
 175   then the end time in the record is filled in with the value specified by TimeStamp.
 176   If the record is found and TimeStamp is zero, then the end time in the matching record
 177   is filled in with the current time stamp value.
 178
 179   @param  Handle                  The pointer to environment specific context used
 180                                   to identify the component being measured.
 181   @param  Token                   The pointer to a Null-terminated ASCII string
 182                                   that identifies the component being measured.
 183   @param  Module                  The pointer to a Null-terminated ASCII string
 184                                   that identifies the module being measured.
 185   @param  TimeStamp               The 64-bit time stamp.
 186
 187   @retval EFI_SUCCESS             The end of  the measurement was recorded.
 188   @retval EFI_NOT_FOUND           The specified measurement record could not be found.
 189
 190 **/
 191 typedef
 192 EFI_STATUS
 193 (EFIAPI * PERFORMANCE_END_GAUGE)(
 194   IN CONST VOID   *Handle,  OPTIONAL
 195   IN CONST CHAR8  *Token,   OPTIONAL
 196   IN CONST CHAR8  *Module,  OPTIONAL
 197   IN UINT64       TimeStamp
 198   );
 199
 200 /**
 201   Retrieves a previously logged performance measurement.
 202   It can also retrieve the log created by StartGaugeEx and EndGaugeEx of PERFORMANCE_EX_PROTOCOL,
 203   and then eliminate the Identifier.
 204
 205   Retrieves the performance log entry from the performance log specified by LogEntryKey.
 206   If it stands for a valid entry, then EFI_SUCCESS is returned and
 207   GaugeDataEntry stores the pointer to that entry.
 208
 209   @param  LogEntryKey             The key for the previous performance measurement log entry.
 210                                   If 0, then the first performance measurement log entry is retrieved.
 211   @param  GaugeDataEntry          Out parameter for the indirect pointer to the gauge data entry specified by LogEntryKey.
 212
 213   @retval EFI_SUCCESS             The GuageDataEntry is successfully found based on LogEntryKey.
 214   @retval EFI_NOT_FOUND           There is no entry after the measurement referred to by LogEntryKey.
 215   @retval EFI_INVALID_PARAMETER   The LogEntryKey is not a valid entry, or GaugeDataEntry is NULL.
 216
 217 **/
 218 typedef
 219 EFI_STATUS
 220 (EFIAPI * PERFORMANCE_GET_GAUGE)(
 221   IN  UINTN               LogEntryKey,
 222   OUT GAUGE_DATA_ENTRY    **GaugeDataEntry
 223   );
 224
 225 /**
 226   Adds a record at the end of the performance measurement log
 227   that records the start time of a performance measurement.
 228
 229   The added record contains the Handle, Token, Module and Identifier.
 230   The end time of the new record is not recorded, so it is set to zero.
 231   If TimeStamp is not zero, then TimeStamp is used to fill in the start time in the record.
 232   If TimeStamp is zero, the start time in the record is filled in with the value
 233   read from the current time stamp.
 234
 235   @param  Handle                  The pointer to environment specific context used
 236                                   to identify the component being measured.
 237   @param  Token                   The pointer to a Null-terminated ASCII string
 238                                   that identifies the component being measured.
 239   @param  Module                  The pointer to a Null-terminated ASCII string
 240                                   that identifies the module being measured.
 241   @param  TimeStamp               The 64-bit time stamp.
 242   @param  Identifier              32-bit identifier. If the value is 0, the created record
 243                                   is same as the one created by StartGauge of PERFORMANCE_PROTOCOL.
 244
 245   @retval EFI_SUCCESS             The data was read correctly from the device.
 246   @retval EFI_OUT_OF_RESOURCES    There are not enough resources to record the measurement.
 247
 248 **/
 249 typedef
 250 EFI_STATUS
 251 (EFIAPI * PERFORMANCE_START_GAUGE_EX)(
 252   IN CONST VOID   *Handle,  OPTIONAL
 253   IN CONST CHAR8  *Token,   OPTIONAL
 254   IN CONST CHAR8  *Module,  OPTIONAL
 255   IN UINT64       TimeStamp,
 256   IN UINT32       Identifier
 257   );
 258
 259 /**
 260   Searches the performance measurement log from the beginning of the log
 261   for the first matching record that contains a zero end time and fills in a valid end time.
 262
 263   Searches the performance measurement log from the beginning of the log
 264   for the first record that matches Handle, Token, Module and Identifier, and has an end time value of zero.
 265   If the record can not be found then return EFI_NOT_FOUND.
 266   If the record is found and TimeStamp is not zero,
 267   then the end time in the record is filled in with the value specified by TimeStamp.
 268   If the record is found and TimeStamp is zero, then the end time in the matching record
 269   is filled in with the current time stamp value.
 270
 271   @param  Handle                  The pointer to environment specific context used
 272                                   to identify the component being measured.
 273   @param  Token                   The pointer to a Null-terminated ASCII string
 274                                   that identifies the component being measured.
 275   @param  Module                  The pointer to a Null-terminated ASCII string
 276                                   that identifies the module being measured.
 277   @param  TimeStamp               The 64-bit time stamp.
 278   @param  Identifier              32-bit identifier. If the value is 0, the found record
 279                                   is same as the one found by EndGauge of PERFORMANCE_PROTOCOL.
 280
 281   @retval EFI_SUCCESS             The end of  the measurement was recorded.
 282   @retval EFI_NOT_FOUND           The specified measurement record could not be found.
 283
 284 **/
 285 typedef
 286 EFI_STATUS
 287 (EFIAPI * PERFORMANCE_END_GAUGE_EX)(
 288   IN CONST VOID   *Handle,  OPTIONAL
 289   IN CONST CHAR8  *Token,   OPTIONAL
 290   IN CONST CHAR8  *Module,  OPTIONAL
 291   IN UINT64       TimeStamp,
 292   IN UINT32       Identifier
 293   );
 294
 295 /**
 296   Retrieves a previously logged performance measurement.
 297   It can also retrieve the log created by StartGauge and EndGauge of PERFORMANCE_PROTOCOL,
 298   and then assign the Identifier with 0.
 299
 300   Retrieves the performance log entry from the performance log specified by LogEntryKey.
 301   If it stands for a valid entry, then EFI_SUCCESS is returned and
 302   GaugeDataEntryEx stores the pointer to that entry.
 303
 304   @param  LogEntryKey             The key for the previous performance measurement log entry.
 305                                   If 0, then the first performance measurement log entry is retrieved.
 306   @param  GaugeDataEntryEx        Out parameter for the indirect pointer to the extented gauge data entry specified by LogEntryKey.
 307
 308   @retval EFI_SUCCESS             The GuageDataEntryEx is successfully found based on LogEntryKey.
 309   @retval EFI_NOT_FOUND           There is no entry after the measurement referred to by LogEntryKey.
 310   @retval EFI_INVALID_PARAMETER   The LogEntryKey is not a valid entry, or GaugeDataEntryEx is NULL.
 311
 312 **/
 313 typedef
 314 EFI_STATUS
 315 (EFIAPI * PERFORMANCE_GET_GAUGE_EX)(
 316   IN  UINTN                 LogEntryKey,
 317   OUT GAUGE_DATA_ENTRY_EX   **GaugeDataEntryEx
 318   );
 319
 320 struct _PERFORMANCE_PROTOCOL {
 321   PERFORMANCE_START_GAUGE             StartGauge;
 322   PERFORMANCE_END_GAUGE               EndGauge;
 323   PERFORMANCE_GET_GAUGE               GetGauge;
 324 };
 325
 326 struct _PERFORMANCE_EX_PROTOCOL {
 327   PERFORMANCE_START_GAUGE_EX          StartGaugeEx;
 328   PERFORMANCE_END_GAUGE_EX            EndGaugeEx;
 329   PERFORMANCE_GET_GAUGE_EX            GetGaugeEx;
 330 };
 331
 332 extern EFI_GUID gPerformanceProtocolGuid;
 333 extern EFI_GUID gSmmPerformanceProtocolGuid;
 334 extern EFI_GUID gPerformanceExProtocolGuid;
 335 extern EFI_GUID gSmmPerformanceExProtocolGuid;
 336
 337 #endif