MdeModulePkg/Include/Guid/Performance.h

   1 /** @file
   2   This file defines performance related definitions: the format of performance
   3   GUID HOB, performance protocol interfaces and performance variable format.
   4
   5 Copyright (c) 2009, Intel Corporation. <BR>
   6 All rights reserved. This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef __PERFORMANCE_DATA_H__
  17 #define __PERFORMANCE_DATA_H__
  18
  19 //
  20 // PEI_PERFORMANCE_STRING_SIZE must be a multiple of 8.
  21 //
  22 #define PEI_PERFORMANCE_STRING_SIZE     8
  23 #define PEI_PERFORMANCE_STRING_LENGTH   (PEI_PERFORMANCE_STRING_SIZE - 1)
  24
  25 typedef struct {
  26   EFI_PHYSICAL_ADDRESS  Handle;
  27   CHAR8                 Token[PEI_PERFORMANCE_STRING_SIZE];   ///> Measured token string name
  28   CHAR8                 Module[PEI_PERFORMANCE_STRING_SIZE];  ///> Module string name
  29   UINT64                StartTimeStamp;                       ///> Start time point
  30   UINT64                EndTimeStamp;                         ///> End time point
  31 } PEI_PERFORMANCE_LOG_ENTRY;
  32
  33 //
  34 // The header must be aligned at 8 bytes.
  35 //
  36 typedef struct {
  37   UINT32                NumberOfEntries;  ///> The number of all performance log entries
  38   UINT32                Reserved;
  39 } PEI_PERFORMANCE_LOG_HEADER;
  40
  41
  42 //
  43 // The data structure for performance data in ACPI memory.
  44 //
  45 #define PERFORMANCE_SIGNATURE   SIGNATURE_32 ('P', 'e', 'r', 'f')
  46 #define PERF_TOKEN_SIZE         28
  47 #define PERF_TOKEN_LENGTH       (PERF_TOKEN_SIZE - 1)
  48 #define PERF_PEI_ENTRY_MAX_NUM  50
  49
  50 typedef struct {
  51   CHAR8   Token[PERF_TOKEN_SIZE];
  52   UINT32  Duration;
  53 } PERF_DATA;
  54
  55 typedef struct {
  56   UINT64        BootToOs;
  57   UINT64        S3Resume;
  58   UINT32        S3EntryNum;
  59   PERF_DATA     S3Entry[PERF_PEI_ENTRY_MAX_NUM];
  60   UINT64        CpuFreq;
  61   UINT64        BDSRaw;
  62   UINT32        Count;
  63   UINT32        Signiture;
  64 } PERF_HEADER;
  65
  66 #define PERFORMANCE_PROTOCOL_GUID \
  67   { 0x76b6bdfa, 0x2acd, 0x4462, {0x9E, 0x3F, 0xcb, 0x58, 0xC9, 0x69, 0xd9, 0x37 } }
  68
  69 //
  70 // Forward reference for pure ANSI compatibility
  71 //
  72 typedef struct _PERFORMANCE_PROTOCOL PERFORMANCE_PROTOCOL;
  73
  74 //
  75 // DXE_PERFORMANCE_STRING_SIZE must be a multiple of 8.
  76 //
  77 #define DXE_PERFORMANCE_STRING_SIZE     32
  78 #define DXE_PERFORMANCE_STRING_LENGTH   (DXE_PERFORMANCE_STRING_SIZE - 1)
  79
  80 //
  81 // The default guage entries number for DXE phase.
  82 //
  83 #define INIT_DXE_GAUGE_DATA_ENTRIES     800
  84
  85 typedef struct {
  86   EFI_PHYSICAL_ADDRESS  Handle;
  87   CHAR8                 Token[DXE_PERFORMANCE_STRING_SIZE];  ///> Measured token string name
  88   CHAR8                 Module[DXE_PERFORMANCE_STRING_SIZE]; ///> Module string name
  89   UINT64                StartTimeStamp;                      ///> Start time point
  90   UINT64                EndTimeStamp;                        ///> End time point
  91 } GAUGE_DATA_ENTRY;
  92
  93 //
  94 // The header must be aligned at 8 bytes
  95 //
  96 typedef struct {
  97   UINT32                NumberOfEntries; ///> The number of all performance guage entries
  98   UINT32                Reserved;
  99 } GAUGE_DATA_HEADER;
 100
 101 /**
 102   Adds a record at the end of the performance measurement log
 103   that records the start time of a performance measurement.
 104
 105   Adds a record to the end of the performance measurement log
 106   that contains the Handle, Token, and Module.
 107   The end time of the new record must be set to zero.
 108   If TimeStamp is not zero, then TimeStamp is used to fill in the start time in the record.
 109   If TimeStamp is zero, the start time in the record is filled in with the value
 110   read from the current time stamp.
 111
 112   @param  Handle                  Pointer to environment specific context used
 113                                   to identify the component being measured.
 114   @param  Token                   Pointer to a Null-terminated ASCII string
 115                                   that identifies the component being measured.
 116   @param  Module                  Pointer to a Null-terminated ASCII string
 117                                   that identifies the module being measured.
 118   @param  TimeStamp               64-bit time stamp.
 119
 120   @retval EFI_SUCCESS             The data was read correctly from the device.
 121   @retval EFI_OUT_OF_RESOURCES    There are not enough resources to record the measurement.
 122
 123 **/
 124 typedef
 125 EFI_STATUS
 126 (EFIAPI * PERFORMANCE_START_GAUGE)(
 127   IN CONST VOID   *Handle,  OPTIONAL
 128   IN CONST CHAR8  *Token,   OPTIONAL
 129   IN CONST CHAR8  *Module,  OPTIONAL
 130   IN UINT64       TimeStamp
 131   );
 132
 133 /**
 134   Searches the performance measurement log from the beginning of the log
 135   for the first matching record that contains a zero end time and fills in a valid end time.
 136
 137   Searches the performance measurement log from the beginning of the log
 138   for the first record that matches Handle, Token, and Module and has an end time value of zero.
 139   If the record can not be found then return EFI_NOT_FOUND.
 140   If the record is found and TimeStamp is not zero,
 141   then the end time in the record is filled in with the value specified by TimeStamp.
 142   If the record is found and TimeStamp is zero, then the end time in the matching record
 143   is filled in with the current time stamp value.
 144
 145   @param  Handle                  Pointer to environment specific context used
 146                                   to identify the component being measured.
 147   @param  Token                   Pointer to a Null-terminated ASCII string
 148                                   that identifies the component being measured.
 149   @param  Module                  Pointer to a Null-terminated ASCII string
 150                                   that identifies the module being measured.
 151   @param  TimeStamp               64-bit time stamp.
 152
 153   @retval EFI_SUCCESS             The end of  the measurement was recorded.
 154   @retval EFI_NOT_FOUND           The specified measurement record could not be found.
 155
 156 **/
 157 typedef
 158 EFI_STATUS
 159 (EFIAPI * PERFORMANCE_END_GAUGE)(
 160   IN CONST VOID   *Handle,  OPTIONAL
 161   IN CONST CHAR8  *Token,   OPTIONAL
 162   IN CONST CHAR8  *Module,  OPTIONAL
 163   IN UINT64       TimeStamp
 164   );
 165
 166 /**
 167   Retrieves a previously logged performance measurement.
 168
 169   Retrieves the performance log entry from the performance log specified by LogEntryKey.
 170   If it stands for a valid entry, then EFI_SUCCESS is returned and
 171   GaugeDataEntry stores the pointer to that entry.
 172
 173   @param  LogEntryKey             The key for the previous performance measurement log entry.
 174                                   If 0, then the first performance measurement log entry is retrieved.
 175   @param  GaugeDataEntry          The indirect pointer to the gauge data entry specified by LogEntryKey
 176                                   if the retrieval is successful.
 177
 178   @retval EFI_SUCCESS             The GuageDataEntry is successfully found based on LogEntryKey.
 179   @retval EFI_NOT_FOUND           The LogEntryKey is the last entry (equals to the total entry number).
 180   @retval EFI_INVALIDE_PARAMETER  The LogEntryKey is not a valid entry (greater than the total entry number).
 181   @retval EFI_INVALIDE_PARAMETER  GaugeDataEntry is NULL.
 182
 183 **/
 184 typedef
 185 EFI_STATUS
 186 (EFIAPI * PERFORMANCE_GET_GAUGE)(
 187   IN  UINTN               LogEntryKey,
 188   OUT GAUGE_DATA_ENTRY    **GaugeDataEntry
 189   );
 190
 191 struct _PERFORMANCE_PROTOCOL {
 192   PERFORMANCE_START_GAUGE             StartGauge;
 193   PERFORMANCE_END_GAUGE               EndGauge;
 194   PERFORMANCE_GET_GAUGE               GetGauge;
 195 };
 196
 197 extern EFI_GUID gPerformanceProtocolGuid;
 198
 199 #endif