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