|
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 the License "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 * WARNING: This file contains some APIs which are internal and are subject |
|
18 * to change without notice. Such APIs should therefore not be used |
|
19 * outside the Kernel and Hardware Services package. |
|
20 */ |
|
21 |
|
22 |
|
23 |
|
24 /** |
|
25 @file |
|
26 @publishedPartner |
|
27 @prototype |
|
28 */ |
|
29 |
|
30 |
|
31 #ifndef E32UTRACE_BASIC_TYPES_H |
|
32 #define E32UTRACE_BASIC_TYPES_H |
|
33 |
|
34 #ifdef __KERNEL_MODE__ |
|
35 #include <kernel/kernel.h> |
|
36 #else //__KERNEL_MODE__ |
|
37 #include <e32std.h> |
|
38 #endif //__KERNEL_MODE__ |
|
39 |
|
40 |
|
41 /** |
|
42 @file |
|
43 @publishedPartner |
|
44 @prototype |
|
45 */ |
|
46 |
|
47 namespace UTF |
|
48 { |
|
49 |
|
50 /** |
|
51 * Every trace point must be statically assigned a classification. This is |
|
52 * essentially a “label” that allows identification of the intended use of |
|
53 * the trace packets generated by the trace point. The classification either |
|
54 * reflects a system-wide Tracing use-case, such as highlighting reasons why |
|
55 * a Panic occurred, or is assigned to trace points in performance critical |
|
56 * software such as the kernel or other key services. |
|
57 * @see TClassificationRange for more information. |
|
58 */ |
|
59 typedef TUint8 TClassification; |
|
60 |
|
61 /** |
|
62 * The maximum possible value for TClassification |
|
63 */ |
|
64 const static TClassification KMaxClassification = 255; // 2^8 - 1 |
|
65 |
|
66 /** |
|
67 * Each trace point must be statically assigned a ModuleUid to indicate the |
|
68 * module in which the trace point is defined. It is recommended that this |
|
69 * value is the UID3 of the associated binary file. |
|
70 * |
|
71 * The ModuleUid and Classification attributes of a trace point are independent. |
|
72 */ |
|
73 typedef TUint32 TModuleUid; |
|
74 |
|
75 /** |
|
76 * The maximum possible value for TModuleUid |
|
77 */ |
|
78 const static TModuleUid KMaxModuleUid = 0xFFFFFFFF; // 2^32 - 1, or 4294967295 - 1 |
|
79 |
|
80 /** |
|
81 * The EXECUTABLE_DEFAULT_MODULEUID can be used to define your own default |
|
82 * specific ModuleUid. This is done by defining the macro to be your new |
|
83 * default value. |
|
84 */ |
|
85 #ifdef EXECUTABLE_DEFAULT_MODULEUID |
|
86 #define FW_DEFAULT_MODULEUID EXECUTABLE_DEFAULT_MODULEUID |
|
87 #else |
|
88 #define FW_DEFAULT_MODULEUID TTraceContext::DefaultModuleUid() |
|
89 #endif |
|
90 |
|
91 /** |
|
92 * This is a numerical value statically assigned to a trace point which will be used |
|
93 * on the host to look-up the format of the associated trace packets. |
|
94 * |
|
95 * The meaning of a FormatId is specific to the ModuleUid and Category of the |
|
96 * associated trace point. |
|
97 */ |
|
98 typedef TUint16 TFormatId; |
|
99 |
|
100 /** |
|
101 * The maximum possible value for TFormatId |
|
102 */ |
|
103 const static TFormatId KMaxFormatId = 65535; // 2^16 - 1 |
|
104 |
|
105 /** |
|
106 * TFormatId used in packets produced by the Print and Printf |
|
107 * functions. |
|
108 * |
|
109 * Note that this format should not be used on the |
|
110 * device by clients of UTrace. This symbol is only marked |
|
111 * as published to partners to give host side tools access to |
|
112 * it. |
|
113 * |
|
114 * @see TFormatId |
|
115 */ |
|
116 const static TFormatId KFormatPrintf = 0; |
|
117 |
|
118 /** |
|
119 * TFormatId used in packets produced by the Print and Printf |
|
120 * functions for unicode descriptors. |
|
121 * |
|
122 * Note that this format should not be used on the |
|
123 * device by clients of UTrace. This symbol is only marked |
|
124 * as published to partners to give host side tools access to |
|
125 * it. |
|
126 * |
|
127 * @see TFormatId |
|
128 */ |
|
129 const static TFormatId KFormatPrintfUnicode = 1; |
|
130 |
|
131 /** |
|
132 * This value is intended to be used by clients to specify the |
|
133 * start of the range of enums used to define their format ids. |
|
134 * |
|
135 * Any values between 0 up to this should not be used directly |
|
136 * by clients of UTrace on the device. |
|
137 * |
|
138 * @see TFormatId |
|
139 */ |
|
140 const static TFormatId KInitialClientFormat = 512; |
|
141 |
|
142 /** |
|
143 * Include the thread identification into the trace packet at run-time. |
|
144 * The thread identification is used as an identifier to resolve |
|
145 * thread and process names in conjunction with |
|
146 * classificiation EThreadIdentification = 3. |
|
147 */ |
|
148 enum THasThreadIdentification |
|
149 { |
|
150 /**Do add the thread identification to the trace packet*/ |
|
151 EAddThreadIdentification = ETrue, |
|
152 /**Don't add the thread identification*/ |
|
153 ENoThreadIdentification = EFalse |
|
154 }; |
|
155 |
|
156 |
|
157 /** |
|
158 * The EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION can be used to |
|
159 * define the default setting for adding or not adding the thread |
|
160 * identification in a trace packet. This is done by defining |
|
161 * the macro to be your new default value. |
|
162 */ |
|
163 #ifdef EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION |
|
164 #define FW_DEFAULT_HAS_THREAD_IDENTIFICATION EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION |
|
165 #else |
|
166 #define FW_DEFAULT_HAS_THREAD_IDENTIFICATION EAddThreadIdentification |
|
167 #endif |
|
168 |
|
169 |
|
170 /** |
|
171 * Add the program counter into the trace packet at run-time. |
|
172 * The program counter is used to indicate where the CPU is in the |
|
173 * instruction sequence. This can be used to locate the line of code |
|
174 * or routine the trace was sent from. |
|
175 */ |
|
176 enum THasProgramCounter |
|
177 { |
|
178 /**Do add the program counter to the trace packet.*/ |
|
179 EAddProgramCounter = ETrue, |
|
180 /**Don't add the program counter*/ |
|
181 ENoProgramCounter = EFalse |
|
182 }; |
|
183 |
|
184 |
|
185 /** |
|
186 * The EXECUTABLE_DEFAULT_HAS_PC can be used to |
|
187 * define the default setting for adding or not adding the |
|
188 * program counter in a trace packet. This is done by defining |
|
189 * the macro to be your new default value. |
|
190 */ |
|
191 #ifdef EXECUTABLE_DEFAULT_HAS_PC |
|
192 #define FW_DEFAULT_HAS_PC EXECUTABLE_DEFAULT_HAS_PC |
|
193 #else |
|
194 #define FW_DEFAULT_HAS_PC ENoProgramCounter |
|
195 #endif |
|
196 |
|
197 |
|
198 /** |
|
199 * The Classifications in the All range should be used by the majority of |
|
200 * trace points. This range of Classifications are intended to identify which |
|
201 * of the most common trace use-cases a trace point is contributing to. |
|
202 * The Classifications in this series are defined solely by Symbian but are |
|
203 * intended for use by any software on a device. |
|
204 * |
|
205 * @see TClassification |
|
206 * @see TClassificationRange |
|
207 * @see EAllRangeFirst |
|
208 */ |
|
209 enum TClassificationAll |
|
210 { |
|
211 /** |
|
212 * Used when a panic has occurred or when providing information on the execution |
|
213 * state that lead to the decision to panic. |
|
214 * |
|
215 * A trace point with this Classification indicates a fatal condition is about to |
|
216 * occur which will halt the flow of program execution in the current thread. |
|
217 * |
|
218 * This Classification also provides information describing where a panic has been |
|
219 * dealt with. |
|
220 * |
|
221 * EPanic = EAllRangeFirst |
|
222 */ |
|
223 EPanic = 192, |
|
224 |
|
225 /** |
|
226 * Used when an error has occurred that means the current operation cannot continue |
|
227 * but isn’t sufficiently serious to cause a Panic. The trace points could contain |
|
228 * not just the error code but any relevant information about the execution state |
|
229 * when the error occurred. |
|
230 * |
|
231 * To be used for all types of error and includes situations where the errors are |
|
232 * returned from a function or in a Leave. |
|
233 * |
|
234 * This Classification also provides information describing where an error has been |
|
235 * dealt with. |
|
236 */ |
|
237 EError = 193, |
|
238 |
|
239 /** |
|
240 * Used when something unexpected or unusual has occurred that does not stop the |
|
241 * current operation from happening but may result in unintended side effects or |
|
242 * actual errors later on. |
|
243 */ |
|
244 EWarning = 194, |
|
245 |
|
246 /** |
|
247 * Used to detail normal activity at the edges of a module. Does not include errors |
|
248 * or warnings as these are covered in other Classifications. |
|
249 * |
|
250 * Includes data about exported or published functions defined by module as well as |
|
251 * calls out of the module to get significant information. Exactly what is significant |
|
252 * is for the module owner to decide. For example, getting the contents of an .ini file to |
|
253 * determine which configuration to use might be significant but calling RArray::Count() |
|
254 * would not be. |
|
255 * |
|
256 * The information in this Classification should be enough to allow someone unfamiliar |
|
257 * with the trace module to get a high level understanding of what functionality it has |
|
258 * executed. |
|
259 */ |
|
260 EBorder = 195, |
|
261 |
|
262 /** |
|
263 * Intended for tracing the state transitions of an application or service such as those |
|
264 * performed by a machine. |
|
265 * |
|
266 * Trace packet’s using this Classification should contain the name of the |
|
267 * changed state variable and the new value. |
|
268 */ |
|
269 EState = 196, |
|
270 |
|
271 /** |
|
272 * Used to provide detailed information about the normal activity of a module |
|
273 * to help a developer, who is familiar with the module, to understand what it is doing. |
|
274 * |
|
275 * Does not include errors or warnings as those are covered in other Classifications. |
|
276 */ |
|
277 EInternals = 197, |
|
278 |
|
279 /** |
|
280 * Used when there is a need to output large amounts of data through individual trace |
|
281 * points that would likely cause significant intrusion if included under one of the |
|
282 * other Classifications. |
|
283 * |
|
284 * This Classification in intended to be used in conjunction with the Internals |
|
285 * Classification to provide more details when debugging a specific module. |
|
286 */ |
|
287 EDump = 198, |
|
288 |
|
289 /** |
|
290 * Used to provide comprehensive information on what paths the execution takes within |
|
291 * functions. |
|
292 * |
|
293 * This Classification is intended only to be assigned by tools that add temporary |
|
294 * instrumentation points specifically to output this data. |
|
295 */ |
|
296 EFlow = 199, |
|
297 |
|
298 /** |
|
299 * Used to output data about the execution time, memory usage, disk usage, power |
|
300 * utilisation and other system characteristics of the trace module. |
|
301 * |
|
302 * This data may need to be processed before it can provide affective metrics. E.g. |
|
303 * the time between two timestamps might need to be computed. |
|
304 * |
|
305 * Intended only to be used to output system characteristic data that requires the |
|
306 * smallest possible intrusion. |
|
307 */ |
|
308 ESystemCharacteristicMetrics = 200, |
|
309 |
|
310 /** |
|
311 * Can be used when adding ad-hoc / temporary trace points if there’s a need to |
|
312 * distinguish it from existing trace. |
|
313 */ |
|
314 EAdhoc = 201, |
|
315 |
|
316 /** |
|
317 * Provided to allow the following compile time assert: |
|
318 * EClassificationAllHighWaterMark <= EAllRangeLast + 1 |
|
319 * |
|
320 * @internalComponent |
|
321 */ |
|
322 EClassificationAllHighWaterMark, |
|
323 }; |
|
324 |
|
325 |
|
326 /** |
|
327 * The division of the Classifications into different ranges aims to manage the |
|
328 * contention for the namespace. |
|
329 * The stakeholders considered for the namespace are: |
|
330 * - Software vendors who own trace points in a base-port, whether a hardware |
|
331 * manufacturer or their suppliers. |
|
332 * - Software vendors who own trace points in the UI layer, whether a phone |
|
333 * manufacturer or their suppliers. |
|
334 * - ISVs who own trace points in source code installed on a device after it has been |
|
335 * released. |
|
336 * - Symbian as the owner of all trace points in Symbian OS. |
|
337 * |
|
338 * It is recommended that all stakeholders use the All range as far as possible. |
|
339 * It is also strongly recommended that software provided by one stakeholder does |
|
340 * not use any Classifications from a range provided specifically for another |
|
341 * stakeholder. |
|
342 * |
|
343 * @see TClassification |
|
344 */ |
|
345 enum TClassificationRange |
|
346 { |
|
347 /** |
|
348 * The Symbian One range is only for use on the device by Symbian. |
|
349 * |
|
350 * @see epoc32\include\e32btrace.h |
|
351 * |
|
352 * This range is defined and used by Symbian only. |
|
353 */ |
|
354 ESymbianOneRangeFirst = 0, |
|
355 |
|
356 /** |
|
357 * @see ESymbianOneRangeFirst |
|
358 */ |
|
359 ESymbianOneRangeLast = 127, |
|
360 |
|
361 /** |
|
362 * The Base Port range is only for use on the device by code provided solely as |
|
363 * part of a base-port. |
|
364 * |
|
365 * It is expected that the owner of each base-port will manage the use of trace |
|
366 * points by all the software vendors contributing to their base-port to prevent |
|
367 * conflicts. |
|
368 * |
|
369 * This range may only be defined and used by device manufacturers. |
|
370 */ |
|
371 EBasePortRangeFirst = 128, |
|
372 |
|
373 /** |
|
374 * @see EBasePortRangeFirst |
|
375 */ |
|
376 EBasePortRangeLast = 159, |
|
377 |
|
378 /** |
|
379 * The UI Layer range is only for use on the device by code provided as part of |
|
380 * the UI Layer. This includes all software needed to create a device |
|
381 * that is not part of Symbian OS or the base-port. |
|
382 * |
|
383 * It is expected that the owner of each UI layer will prevent collisions between |
|
384 * trace points provided by all the software vendors contributing software to the |
|
385 * UI layer. |
|
386 * |
|
387 * This range may only be defined and used by device manufacturers. |
|
388 */ |
|
389 EUiLayerRangeFirst = 160, |
|
390 |
|
391 /** |
|
392 * @see EUiLayerRangeFirst |
|
393 */ |
|
394 EUiLayerRangeLast = 191, |
|
395 |
|
396 /** |
|
397 * The Classifications in the All range should be used by the majority of trace |
|
398 * points. This range of Classifications are intended to identify which of the |
|
399 * most common trace use-cases a trace point is contributing to. |
|
400 * |
|
401 * The Classifications in this series are defined solely by Symbian but are |
|
402 * intended for use by any software on a device. No software vendor other than |
|
403 * Symbian should define Classifications in this range. |
|
404 * |
|
405 * When assigning one of these Classifications to a trace point you should |
|
406 * also assign a ModuleUid to allow your trace points to be differentiated from |
|
407 * other uses of the Classification in the system. |
|
408 * |
|
409 * These Classifications should only be enabled at run-time if the filtering on |
|
410 * ModuleUids functionality is also enabled. This is to avoid accidentally causing |
|
411 * trace live-locks from occurring when the Classification is enabled. This could |
|
412 * happen because trace points in components involved in the current trace output |
|
413 * path might also be assigned these Classifications. Filtering on ModuleUids means |
|
414 * that those trace points can be activated only when it’s known to be safe to do |
|
415 * so and not accidentally enabled with a Classification. |
|
416 * |
|
417 * This range is definded by Symbian and may be used by anyone. |
|
418 * |
|
419 * @see TAllClassification |
|
420 */ |
|
421 EAllRangeFirst = 192, |
|
422 |
|
423 /** |
|
424 * @see EAllRangeFirst |
|
425 */ |
|
426 EAllRangeLast = 221, |
|
427 |
|
428 /** |
|
429 * This range may only be used and defined by Symbian. |
|
430 */ |
|
431 ESymbianTwoRangeFirst = 222, |
|
432 |
|
433 /** |
|
434 * @see ESymbianTwoRangeFirst |
|
435 */ |
|
436 ESymbianTwoRangeLast = 245, |
|
437 |
|
438 /** |
|
439 * The ISV range is only for use on the device by ISVs providing software that is |
|
440 * installed on a device after it has been released and is not part of the base-port, |
|
441 * Symbian OS or the UI Layer. |
|
442 * |
|
443 * This range is only intended to provide enough Classifications for a single ISV |
|
444 * application. Clashes that occur between different applications should be |
|
445 * resolved by uninstalling one or other of them. |
|
446 * |
|
447 * This range is defined and used by 3rd party developers. |
|
448 */ |
|
449 EIsvRangeFirst = 246, |
|
450 |
|
451 /** |
|
452 * @see EIsvRangeFirst |
|
453 */ |
|
454 EIsvRangeLast = 253, |
|
455 |
|
456 /** |
|
457 * Only for use on the device by test code. |
|
458 * |
|
459 * Trace points with these Classifications should not be released as part of a |
|
460 * production device. |
|
461 */ |
|
462 ETestingRangeFirst = 254, |
|
463 |
|
464 /** |
|
465 * @see ETestingRangeFirst |
|
466 */ |
|
467 ETestingRangeLast = KMaxClassification, |
|
468 }; |
|
469 |
|
470 // Check high water mark for classification ranges for TClassificationAll |
|
471 __ASSERT_COMPILE(EClassificationAllHighWaterMark <= EAllRangeLast + 1); |
|
472 |
|
473 |
|
474 |
|
475 /** |
|
476 * @see TClassification |
|
477 * @see ESymbianTwoRangeFirst |
|
478 * @internalComponent |
|
479 */ |
|
480 enum TClassificationSymbianTwo |
|
481 { |
|
482 /** |
|
483 * This classification is reserved for future use to allow the classification range |
|
484 * to be expanded to cover more than current 256 different values. |
|
485 * |
|
486 * If trace is output on this Classification at some point in the future then this |
|
487 * indicates another mechanism (to be decided) will be used to indicate the actual |
|
488 * Classification for the trace. |
|
489 * |
|
490 * EClassificationExtension = 222 |
|
491 */ |
|
492 EClassificationExtension = ESymbianTwoRangeFirst, |
|
493 |
|
494 /** |
|
495 * Provided to allow the following compile time assert: |
|
496 * EClassificationSymbianTwoHighWaterMark <= ESymbianTwoRangeLast + 1 |
|
497 * |
|
498 * @internalComponent |
|
499 */ |
|
500 EClassificationSymbianTwoHighWaterMark, |
|
501 }; |
|
502 // Check high water marks for classification ranges |
|
503 __ASSERT_COMPILE(EClassificationSymbianTwoHighWaterMark <= ESymbianTwoRangeLast + 1); |
|
504 |
|
505 /** |
|
506 * @see TClassification |
|
507 * @see ETestingRangeFirst |
|
508 * @test |
|
509 */ |
|
510 enum TClassificationTesting |
|
511 { |
|
512 /** |
|
513 * Only for use on the device by test code. |
|
514 * |
|
515 * Trace points with this Classification should not be released as part of a |
|
516 * production device. |
|
517 * |
|
518 * ETesting1 = 254 |
|
519 */ |
|
520 ETesting1 = ETestingRangeFirst, |
|
521 |
|
522 /** |
|
523 * @see ETesting1 |
|
524 */ |
|
525 ETesting2 = 255, |
|
526 |
|
527 /** |
|
528 * Provided to allow the following compile time assert: |
|
529 * EClassificationTestingHighWaterMark <= ETestingRangeLast + 1 |
|
530 * |
|
531 * @internalComponent |
|
532 */ |
|
533 EClassificationTestingHighWaterMark, |
|
534 }; |
|
535 |
|
536 // Check high water marks for classification ranges |
|
537 __ASSERT_COMPILE(EClassificationTestingHighWaterMark <= ETestingRangeLast + 1); |
|
538 |
|
539 |
|
540 } //end of UTF namespace |
|
541 |
|
542 #endif //E32UTRACE_BASIC_TYPES_H |
|
543 |