1 /** @file
2   Base Performance Library which provides no service.
3 
4   Copyright (c) 2006 - 2012, 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
StartPerformanceMeasurement(IN CONST VOID * Handle,OPTIONAL IN CONST CHAR8 * Token,OPTIONAL IN CONST CHAR8 * Module,OPTIONAL IN UINT64 TimeStamp)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
EndPerformanceMeasurement(IN CONST VOID * Handle,OPTIONAL IN CONST CHAR8 * Token,OPTIONAL IN CONST CHAR8 * Module,OPTIONAL IN UINT64 TimeStamp)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
GetPerformanceMeasurement(IN UINTN LogEntryKey,OUT CONST VOID ** Handle,OUT CONST CHAR8 ** Token,OUT CONST CHAR8 ** Module,OUT UINT64 * StartTimeStamp,OUT UINT64 * EndTimeStamp)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
StartPerformanceMeasurementEx(IN CONST VOID * Handle,OPTIONAL IN CONST CHAR8 * Token,OPTIONAL IN CONST CHAR8 * Module,OPTIONAL IN UINT64 TimeStamp,IN UINT32 Identifier)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
EndPerformanceMeasurementEx(IN CONST VOID * Handle,OPTIONAL IN CONST CHAR8 * Token,OPTIONAL IN CONST CHAR8 * Module,OPTIONAL IN UINT64 TimeStamp,IN UINT32 Identifier)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
GetPerformanceMeasurementEx(IN UINTN LogEntryKey,OUT CONST VOID ** Handle,OUT CONST CHAR8 ** Token,OUT CONST CHAR8 ** Module,OUT UINT64 * StartTimeStamp,OUT UINT64 * EndTimeStamp,OUT UINT32 * Identifier)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
PerformanceMeasurementEnabled(VOID)301 PerformanceMeasurementEnabled (
302   VOID
303   )
304 {
305   return (BOOLEAN) ((PcdGet8(PcdPerformanceLibraryPropertyMask) & PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED) != 0);
306 }
307