|
1 /** |
|
2 * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * Trace API |
|
16 * |
|
17 */ |
|
18 |
|
19 |
|
20 |
|
21 /** |
|
22 @file |
|
23 @publishedPartner |
|
24 @prototype |
|
25 */ |
|
26 |
|
27 |
|
28 #ifndef OPENSYSTEMTRACE_TYPES_H |
|
29 #define OPENSYSTEMTRACE_TYPES_H |
|
30 |
|
31 #ifdef __KERNEL_MODE__ |
|
32 #include <kernel.h> |
|
33 #else //__KERNEL_MODE__ |
|
34 #include <e32std.h> |
|
35 #endif //__KERNEL_MODE__ |
|
36 |
|
37 |
|
38 /** |
|
39 @file |
|
40 @publishedPartner |
|
41 @prototype |
|
42 */ |
|
43 |
|
44 |
|
45 /** |
|
46 * Every trace point must be statically assigned a group ID. This is |
|
47 * essentially a “label” that allows identification of the intended use of |
|
48 * the trace packets generated by the trace point. The Group ID will either |
|
49 * reflect a system wide Tracing use cases, such as identifying why a panic |
|
50 * occurred, or is assigned a meaning specific to a component, such as the |
|
51 * heap trace output from the kernel. In essence the Group ID is a way of |
|
52 * indicating that trace points / packets are related in some way. |
|
53 * @see TGroupIdRange for more information. |
|
54 */ |
|
55 typedef TUint8 TGroupId; |
|
56 |
|
57 /** |
|
58 * The maximum possible value for TGroupId |
|
59 */ |
|
60 const static TGroupId KMaxGroupId = 255; // 2^8 - 1 |
|
61 |
|
62 /** |
|
63 * @deprecated Use TGroupId instead |
|
64 * @see TGroupId |
|
65 */ |
|
66 typedef TUint8 TClassification; |
|
67 |
|
68 /** |
|
69 * @deprecated Use KMaxGroupId instead |
|
70 * @see KMaxGroupId |
|
71 */ |
|
72 const static TClassification KMaxClassification = KMaxGroupId; |
|
73 |
|
74 /** |
|
75 * Each trace point must be statically assigned a ComponentId to indicate the |
|
76 * module in which the trace point is defined. It should always be the UID3 |
|
77 * of the binary containing the trace point associated with the component ID. |
|
78 |
|
79 * The ComponentId and Group ID attributes of a trace point are independent. |
|
80 */ |
|
81 typedef TUint32 TComponentId; |
|
82 |
|
83 /** |
|
84 * The maximum possible value for TComponentId |
|
85 */ |
|
86 const static TComponentId KMaxComponentId = 0xFFFFFFFF; // 2^32 - 1, or 4294967295 - 1 |
|
87 |
|
88 /** |
|
89 * The EXECUTABLE_DEFAULT_COMPONENTID can be used to define your own default |
|
90 * specific ComponentId. This is done by defining the macro to be your new |
|
91 * default value. |
|
92 */ |
|
93 #ifdef EXECUTABLE_DEFAULT_COMPONENTID |
|
94 #define FW_DEFAULT_COMPONENTID EXECUTABLE_DEFAULT_COMPONENTID |
|
95 #else |
|
96 #define FW_DEFAULT_COMPONENTID TTraceContext::DefaultComponentId() |
|
97 #endif |
|
98 |
|
99 /** |
|
100 * Trace IDs have two functions in a trace packet: |
|
101 * |
|
102 * 1. They identify the individual trace point that created the trace packet. |
|
103 * 2. They specify the format of the trace packet payload. |
|
104 * |
|
105 * This only works if the Trace ID value is unique for a given Group ID and |
|
106 * Component ID, if present, and should be statically assigned during development |
|
107 * when a trace point is created. |
|
108 * |
|
109 * The meaning of a TraceId is specific to the ComponentId and Group ID of the |
|
110 * associated trace point. |
|
111 */ |
|
112 typedef TUint16 TTraceId; |
|
113 |
|
114 /** |
|
115 * The maximum possible value for TTraceId |
|
116 */ |
|
117 const static TTraceId KMaxTraceId = 65535; // 2^16 - 1 |
|
118 |
|
119 /** |
|
120 * Used in packets produced by the Print and Printf functions. |
|
121 * |
|
122 * Note that this format should not be used on the |
|
123 * device by clients of OST. This symbol is only marked |
|
124 * as published to partners to give host side tools access to |
|
125 * it. |
|
126 * |
|
127 * @deprecated No replacement is provided as this symbol is no |
|
128 * longer needed as a result of the alignment of trace attributes |
|
129 * in OSTv2. |
|
130 * @see TTraceId |
|
131 */ |
|
132 const static TTraceId KFormatPrintf = 0; |
|
133 |
|
134 /** |
|
135 * Used in packets produced by the Print and Printf functions |
|
136 * for unicode descriptors. |
|
137 * |
|
138 * Note that this format should not be used on the |
|
139 * device by clients of OST. This symbol is only marked |
|
140 * as published to partners to give host side tools access to |
|
141 * it. |
|
142 * |
|
143 * @deprecated No replacement is provided as this symbol is no |
|
144 * longer needed as a result of the alignment of trace attributes |
|
145 * in OSTv2. |
|
146 * @see TTraceId |
|
147 */ |
|
148 const static TTraceId KFormatPrintfUnicode = 1; |
|
149 |
|
150 /** |
|
151 * This value was used by UTFv2 clients to specify the start of |
|
152 * the range of enums used to define their format ids. This is |
|
153 * no longer necessary as in OSTv2 clients are allowed to use the |
|
154 * whole range without exception. |
|
155 * |
|
156 * @deprecated No replacement is provided as this symbol is no |
|
157 * longer needed as a result of the alignment of trace attributes |
|
158 * in OSTv2. |
|
159 * @see TTraceId |
|
160 */ |
|
161 const static TTraceId KInitialClientFormat = 512; |
|
162 |
|
163 /** |
|
164 * Include the thread identification into the trace packet at run-time. |
|
165 * The thread identification is used as an identifier to resolve |
|
166 * thread and process names in conjunction with |
|
167 * Group ID EThreadIdentification = 3. |
|
168 */ |
|
169 enum THasThreadIdentification |
|
170 { |
|
171 /** Do add the thread identification to the trace packet */ |
|
172 EAddThreadIdentification = ETrue, |
|
173 /** Don't add the thread identification */ |
|
174 ENoThreadIdentification = EFalse |
|
175 }; |
|
176 |
|
177 |
|
178 /** |
|
179 * The EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION can be used to |
|
180 * define the default setting for adding or not adding the thread |
|
181 * identification in a trace packet. This is done by defining |
|
182 * the macro to be your new default value. |
|
183 */ |
|
184 #ifdef EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION |
|
185 #define FW_DEFAULT_HAS_THREAD_IDENTIFICATION EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION |
|
186 #else |
|
187 #define FW_DEFAULT_HAS_THREAD_IDENTIFICATION EAddThreadIdentification |
|
188 #endif |
|
189 |
|
190 |
|
191 /** |
|
192 * Add the program counter into the trace packet at run-time. |
|
193 * The program counter is used to indicate where the CPU is in the |
|
194 * instruction sequence. This can be used to locate the line of code |
|
195 * or routine the trace was sent from. |
|
196 */ |
|
197 enum THasProgramCounter |
|
198 { |
|
199 /** Do add the program counter to the trace packet. */ |
|
200 EAddProgramCounter = ETrue, |
|
201 /** Don't add the program counter */ |
|
202 ENoProgramCounter = EFalse |
|
203 }; |
|
204 |
|
205 |
|
206 /** |
|
207 * The EXECUTABLE_DEFAULT_HAS_PC can be used to |
|
208 * define the default setting for adding or not adding the |
|
209 * program counter in a trace packet. This is done by defining |
|
210 * the macro to be your new default value. |
|
211 */ |
|
212 #ifdef EXECUTABLE_DEFAULT_HAS_PC |
|
213 #define FW_DEFAULT_HAS_PC EXECUTABLE_DEFAULT_HAS_PC |
|
214 #else |
|
215 #define FW_DEFAULT_HAS_PC ENoProgramCounter |
|
216 #endif |
|
217 |
|
218 /** |
|
219 * The division of the Group IDs into different ranges aims to manage the |
|
220 * contention for the namespace. |
|
221 * |
|
222 * It is recommended that all developers use the Reserved range as far as possible. |
|
223 * |
|
224 * @see TGroupId |
|
225 */ |
|
226 enum TGroupIdRange |
|
227 { |
|
228 /** |
|
229 * The Group IDs in the Reserved range should be used by the majority of trace |
|
230 * points. This range of Group IDs are intended to identify which of the |
|
231 * most common trace use-cases a trace point is contributing to. They are unique |
|
232 * across the system. |
|
233 * |
|
234 * The Group IDs in this series are defined solely by the Symbian Foundation but are |
|
235 * intended for use by any software on a device. |
|
236 * |
|
237 * These Group IDs should only be enabled at run-time if the filtering on |
|
238 * ComponentIds functionality is also enabled. This is to avoid accidentally causing |
|
239 * trace live-locks from occurring when just the Group IDs is enabled. This could |
|
240 * happen because trace points in components involved in the current trace output |
|
241 * path might also be assigned these Group IDs. Filtering on ComponentIds means |
|
242 * that those trace points can be activated only when it’s known to be safe to do |
|
243 * so and not accidentally enabled with a Group IDs. |
|
244 * |
|
245 * @see TGroupIdReserved |
|
246 */ |
|
247 EOstReservedRangeFirst = 0, |
|
248 |
|
249 /** |
|
250 * @see EOstReservedRangeFirst |
|
251 */ |
|
252 EOstReservedRangeLast = 221, |
|
253 |
|
254 /** |
|
255 * The meaning of Group IDs in this range are defined on a per-component basis. |
|
256 * They are to be unique within a component. |
|
257 */ |
|
258 EUserDefinedRangeFirst = 222, |
|
259 |
|
260 /** |
|
261 * @see EUserDefinedRangeFirst |
|
262 */ |
|
263 EUserDefinedRangeLast = 253, |
|
264 |
|
265 /** |
|
266 * Only for use on the device by test code. |
|
267 * |
|
268 * Trace points with these Group IDs should not be released as part of a |
|
269 * production device. |
|
270 */ |
|
271 ETestingRangeFirst = 154, |
|
272 |
|
273 /** |
|
274 * @see ETestingRangeFirst |
|
275 */ |
|
276 ETestingRangeLast = KMaxGroupId |
|
277 }; |
|
278 |
|
279 /** |
|
280 * The Group IDs in the Reserved range should be used by the majority of |
|
281 * trace points. This range of Group IDs are intended to identify which |
|
282 * of the most common trace use-cases a trace point is contributing to. |
|
283 * |
|
284 * @see TGroupId |
|
285 * @see TGroupIdRange |
|
286 * @see EOstReservedRangeFirst |
|
287 */ |
|
288 enum TGroupIdReserved |
|
289 { |
|
290 /** |
|
291 * Used when a fatal error, such as a panic, has occurred or when providing information |
|
292 * on the execution state immediately before the decision to panic. |
|
293 * |
|
294 * A trace point with this Group ID should be used when a fatal condition is detected |
|
295 * which will result in the flow of execution being halted in the thread associated with |
|
296 * the trace point. |
|
297 * |
|
298 * Can also provide information describing where a panic has been dealt with. |
|
299 * |
|
300 * Trace points using this Group ID should be present in a release device. |
|
301 */ |
|
302 TRACE_FATAL = 149, |
|
303 |
|
304 /** |
|
305 * Used when an error has occurred which means that the current operation cannot continue |
|
306 * but is not sufficiently serious to cause a fatal error. These trace packets should |
|
307 * contain not just the error code but any relevant information about the execution state |
|
308 * when the error occurred. |
|
309 * |
|
310 * To be used for all types of error including include situations where the errors are |
|
311 * returned from a function or via a leave. |
|
312 * |
|
313 * This Group ID also provides information describing where an error has been handled. |
|
314 */ |
|
315 TRACE_ERROR=150, |
|
316 |
|
317 /** |
|
318 * Used when something unexpected or unusual has occurred that does not stop the |
|
319 * current operation from happening but may result in unintended side effects or |
|
320 * actual errors later on. |
|
321 */ |
|
322 TRACE_WARNING = 151, |
|
323 |
|
324 /** |
|
325 * Used to describe activity at the edges of a trace component. |
|
326 * |
|
327 * Includes data about exported or published functions defined by a trace component as |
|
328 * well as calls out of the component to get significant information. Exactly what |
|
329 * is significant depends on the trace component in question. For instance, reading in a |
|
330 * setting from an INI file would be significant but calling RArray::Count() would not be. |
|
331 * |
|
332 * The information in this Group ID should be enough to allow someone unfamiliar with the |
|
333 * trace component to get a high level understanding of what functionality it has executed. |
|
334 */ |
|
335 TRACE_BORDER = 152, |
|
336 |
|
337 /** |
|
338 * @deprecated Use TRACE_BORDER instead |
|
339 */ |
|
340 TRACE_API = TRACE_BORDER, |
|
341 |
|
342 /** |
|
343 * @deprecated Use TRACE_NORMAL or one of the other reserved Group IDs instead |
|
344 */ |
|
345 TRACE_IMPORTANT = 153, |
|
346 |
|
347 /** |
|
348 * Used to described the normal activity within a trace component that might be of interest |
|
349 * to people who use the component. |
|
350 * |
|
351 * The information in this Group ID should be enough to allow someone unfamiliar with the |
|
352 * trace component to start to understand why a component is behaving the way it is perhaps |
|
353 * to help with diagnosing problems with the way the component is being used. |
|
354 */ |
|
355 TRACE_NORMAL = 154, |
|
356 |
|
357 /** |
|
358 * Intended for tracing the state transitions of an application or service such as those |
|
359 * performed by a machine. |
|
360 * |
|
361 * Trace packets using this Group ID should contain the name of the |
|
362 * changed state variable and the new value. |
|
363 */ |
|
364 TRACE_STATE = 155, |
|
365 |
|
366 /** |
|
367 * Used to provide detailed information about the normal activity of a trace component |
|
368 * to help a developer, who is familiar with the component, to understand what it is doing. |
|
369 */ |
|
370 TRACE_INTERNALS = 156, |
|
371 |
|
372 /** |
|
373 * @deprecated Use TRACE_INTERNALS instead |
|
374 */ |
|
375 TRACE_DETAILED = TRACE_INTERNALS, |
|
376 |
|
377 /** |
|
378 * Used when there is a need to output large amounts of data through individual trace |
|
379 * points that would likely cause significant intrusion if included under one of the |
|
380 * other Group IDs. |
|
381 * |
|
382 * This Group ID is intended to be used in conjunction with the TRACE_INTERNALS |
|
383 * Group ID to provide more details when debugging a specific trace component. |
|
384 */ |
|
385 TRACE_DUMP = 157, |
|
386 |
|
387 /** |
|
388 * @deprecated Use TRACE_DUMP instead |
|
389 */ |
|
390 TRACE_DEBUG = TRACE_DUMP, |
|
391 |
|
392 /** |
|
393 * Used to provide comprehensive information on what paths the execution takes within |
|
394 * functions. |
|
395 * |
|
396 * This Group ID is intended mainly to be used by tools that add temporary instrumentation |
|
397 * points specifically to output this data. |
|
398 */ |
|
399 TRACE_FLOW = 158, |
|
400 |
|
401 /** |
|
402 * Used to output data about the execution time, memory usage, disk usage, power |
|
403 * utilisation and any other performance characteristics of the associated trace |
|
404 * component. |
|
405 * |
|
406 * This data may need to be processed before it can provide effective metrics. E.g. |
|
407 * the time between two timestamps might need to be computed. |
|
408 * |
|
409 * Intended only to be used to output a small amount of data to ensure that it |
|
410 * creates the smallest possible intrusion since otherwise the act of tracing would |
|
411 * devalue the information it is intended to provide. |
|
412 */ |
|
413 TRACE_PERFORMANCE = 159, |
|
414 |
|
415 /** |
|
416 * May be used when adding temporary trace points during a debugging session to |
|
417 * distinguish them from existing instrumentation. |
|
418 */ |
|
419 TRACE_ADHOC = 160, |
|
420 |
|
421 /** |
|
422 * This Group ID is reserved for future use to allow the Group ID range to be expanded |
|
423 * to cover more than current 256 different values. |
|
424 * |
|
425 * If trace is output on this Group ID at some point in the future then this indicates |
|
426 * that another mechanism (yet to be decided) will be used to indicate the actual |
|
427 * Group ID for the trace. |
|
428 */ |
|
429 TRACE_EXTENSION = 161, |
|
430 |
|
431 /** |
|
432 * Not intended to be used by code including this header. |
|
433 * |
|
434 * Provided to allow the following compile time assert (should NOT be used): |
|
435 * EGroupIdReservedHighWaterMark <= EOstReservedRangeLast + 1 |
|
436 * |
|
437 */ |
|
438 EGroupIdReservedHighWaterMark |
|
439 } ; |
|
440 |
|
441 // Check high water mark for the reserved Group ID range |
|
442 __ASSERT_COMPILE(EGroupIdReservedHighWaterMark <= EOstReservedRangeLast + 1); |
|
443 |
|
444 /** |
|
445 * @see TGroupId |
|
446 * @see ETestingRangeFirst |
|
447 * @test |
|
448 */ |
|
449 enum TGroupIdTesting |
|
450 { |
|
451 /** |
|
452 * This Group ID may be used for testing purposes and is not intended to be used in |
|
453 * production code. |
|
454 */ |
|
455 TRACE_TESTING1 = ETestingRangeFirst, |
|
456 |
|
457 /** |
|
458 * The same as for TRACE_TESTING1 |
|
459 */ |
|
460 TRACE_TESTING2 = 155, |
|
461 |
|
462 /** |
|
463 * Not intended to be used by code including this header. |
|
464 * |
|
465 * Provided to allow the following compile time assert (should NOT be used): |
|
466 * EGroupIdTestingHighWaterMark <= ETestingRangeLast + 1 |
|
467 * |
|
468 */ |
|
469 EGroupIdTestingHighWaterMark |
|
470 }; |
|
471 |
|
472 // Check high water marks for the testing Group ID range |
|
473 __ASSERT_COMPILE(EGroupIdTestingHighWaterMark <= ETestingRangeLast + 1); |
|
474 |
|
475 /** |
|
476 * @deprecated Use enumerations from TGroupIdReserved instead |
|
477 * @see TGroupId |
|
478 * @see TGroupIdRange |
|
479 * @see EOstReservedRangeFirst |
|
480 */ |
|
481 enum TClassificationAll |
|
482 { |
|
483 EPanic = TRACE_FATAL, |
|
484 EError = TRACE_ERROR, |
|
485 EWarning = TRACE_WARNING, |
|
486 EBorder = TRACE_BORDER, |
|
487 EState = TRACE_STATE, |
|
488 EInternals = TRACE_INTERNALS, |
|
489 EDump = TRACE_DUMP, |
|
490 EFlow = TRACE_FLOW, |
|
491 ESystemCharacteristicMetrics = TRACE_PERFORMANCE, |
|
492 EAdhoc = TRACE_ADHOC, |
|
493 EClassificationAllHighWaterMark |
|
494 }; |
|
495 |
|
496 // Check high water mark for the 'All' classification range |
|
497 __ASSERT_COMPILE(EClassificationAllHighWaterMark <= EOstReservedRangeLast + 1); |
|
498 |
|
499 /** |
|
500 * @deprecated Use enumerations from TGroupIdReserved instead |
|
501 * @see TGroupId |
|
502 * @see TGroupIdRange |
|
503 * @see EOstReservedRangeFirst |
|
504 */ |
|
505 enum TClassificationSymbianTwo |
|
506 { |
|
507 EClassificationExtension = TRACE_EXTENSION, |
|
508 EClassificationSymbianTwoHighWaterMark |
|
509 }; |
|
510 |
|
511 // Check high water marks for the Symbian Two classification range |
|
512 __ASSERT_COMPILE(EClassificationSymbianTwoHighWaterMark <= EOstReservedRangeLast + 1); |
|
513 |
|
514 /** |
|
515 * @deprecated Use enumerations from TGroupIdTesting instead |
|
516 * @see TGroupId |
|
517 * @see TGroupIdRange |
|
518 * @see ETestingRangeFirst |
|
519 * @test |
|
520 */ |
|
521 enum TClassificationTesting |
|
522 { |
|
523 ETesting1 = TRACE_TESTING1, |
|
524 ETesting2 = TRACE_TESTING2, |
|
525 EClassificationTestingHighWaterMark, |
|
526 }; |
|
527 |
|
528 // Check high water marks for classification ranges |
|
529 __ASSERT_COMPILE(EClassificationTestingHighWaterMark <= ETestingRangeLast + 1); |
|
530 |
|
531 |
|
532 #endif //OPENSYSTEMTRACE_TYPES_H |