--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/tracefw/tracecompiler/test/testdata/test_opensystemtrace_types.h Tue Aug 31 16:45:49 2010 +0300
@@ -0,0 +1,532 @@
+/**
+* Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description:
+* Trace API
+*
+*/
+
+
+
+/**
+ @file
+ @publishedPartner
+ @prototype
+*/
+
+
+#ifndef OPENSYSTEMTRACE_TYPES_H
+#define OPENSYSTEMTRACE_TYPES_H
+
+#ifdef __KERNEL_MODE__
+#include <kernel.h>
+#else //__KERNEL_MODE__
+#include <e32std.h>
+#endif //__KERNEL_MODE__
+
+
+/**
+@file
+@publishedPartner
+@prototype
+*/
+
+
+/**
+ * Every trace point must be statically assigned a group ID. This is
+ * essentially a “label” that allows identification of the intended use of
+ * the trace packets generated by the trace point. The Group ID will either
+ * reflect a system wide Tracing use cases, such as identifying why a panic
+ * occurred, or is assigned a meaning specific to a component, such as the
+ * heap trace output from the kernel. In essence the Group ID is a way of
+ * indicating that trace points / packets are related in some way.
+ * @see TGroupIdRange for more information.
+ */
+typedef TUint8 TGroupId;
+
+/**
+ * The maximum possible value for TGroupId
+ */
+const static TGroupId KMaxGroupId = 255; // 2^8 - 1
+
+/**
+ * @deprecated Use TGroupId instead
+ * @see TGroupId
+ */
+typedef TUint8 TClassification;
+
+/**
+ * @deprecated Use KMaxGroupId instead
+ * @see KMaxGroupId
+ */
+const static TClassification KMaxClassification = KMaxGroupId;
+
+/**
+ * Each trace point must be statically assigned a ComponentId to indicate the
+ * module in which the trace point is defined. It should always be the UID3
+ * of the binary containing the trace point associated with the component ID.
+
+ * The ComponentId and Group ID attributes of a trace point are independent.
+ */
+typedef TUint32 TComponentId;
+
+/**
+ * The maximum possible value for TComponentId
+ */
+const static TComponentId KMaxComponentId = 0xFFFFFFFF; // 2^32 - 1, or 4294967295 - 1
+
+/**
+ * The EXECUTABLE_DEFAULT_COMPONENTID can be used to define your own default
+ * specific ComponentId. This is done by defining the macro to be your new
+ * default value.
+ */
+#ifdef EXECUTABLE_DEFAULT_COMPONENTID
+#define FW_DEFAULT_COMPONENTID EXECUTABLE_DEFAULT_COMPONENTID
+#else
+#define FW_DEFAULT_COMPONENTID TTraceContext::DefaultComponentId()
+#endif
+
+/**
+ * Trace IDs have two functions in a trace packet:
+ *
+ * 1. They identify the individual trace point that created the trace packet.
+ * 2. They specify the format of the trace packet payload.
+ *
+ * This only works if the Trace ID value is unique for a given Group ID and
+ * Component ID, if present, and should be statically assigned during development
+ * when a trace point is created.
+ *
+ * The meaning of a TraceId is specific to the ComponentId and Group ID of the
+ * associated trace point.
+ */
+typedef TUint16 TTraceId;
+
+/**
+ * The maximum possible value for TTraceId
+ */
+const static TTraceId KMaxTraceId = 65535; // 2^16 - 1
+
+/**
+ * Used in packets produced by the Print and Printf functions.
+ *
+ * Note that this format should not be used on the
+ * device by clients of OST. This symbol is only marked
+ * as published to partners to give host side tools access to
+ * it.
+ *
+ * @deprecated No replacement is provided as this symbol is no
+ * longer needed as a result of the alignment of trace attributes
+ * in OSTv2.
+ * @see TTraceId
+ */
+const static TTraceId KFormatPrintf = 0;
+
+/**
+ * Used in packets produced by the Print and Printf functions
+ * for unicode descriptors.
+ *
+ * Note that this format should not be used on the
+ * device by clients of OST. This symbol is only marked
+ * as published to partners to give host side tools access to
+ * it.
+ *
+ * @deprecated No replacement is provided as this symbol is no
+ * longer needed as a result of the alignment of trace attributes
+ * in OSTv2.
+ * @see TTraceId
+ */
+const static TTraceId KFormatPrintfUnicode = 1;
+
+/**
+ * This value was used by UTFv2 clients to specify the start of
+ * the range of enums used to define their format ids. This is
+ * no longer necessary as in OSTv2 clients are allowed to use the
+ * whole range without exception.
+ *
+ * @deprecated No replacement is provided as this symbol is no
+ * longer needed as a result of the alignment of trace attributes
+ * in OSTv2.
+ * @see TTraceId
+ */
+const static TTraceId KInitialClientFormat = 512;
+
+/**
+ * Include the thread identification into the trace packet at run-time.
+ * The thread identification is used as an identifier to resolve
+ * thread and process names in conjunction with
+ * Group ID EThreadIdentification = 3.
+ */
+enum THasThreadIdentification
+ {
+ /** Do add the thread identification to the trace packet */
+ EAddThreadIdentification = ETrue,
+ /** Don't add the thread identification */
+ ENoThreadIdentification = EFalse
+ };
+
+
+/**
+ * The EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION can be used to
+ * define the default setting for adding or not adding the thread
+ * identification in a trace packet. This is done by defining
+ * the macro to be your new default value.
+ */
+#ifdef EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION
+#define FW_DEFAULT_HAS_THREAD_IDENTIFICATION EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION
+#else
+#define FW_DEFAULT_HAS_THREAD_IDENTIFICATION EAddThreadIdentification
+#endif
+
+
+/**
+ * Add the program counter into the trace packet at run-time.
+ * The program counter is used to indicate where the CPU is in the
+ * instruction sequence. This can be used to locate the line of code
+ * or routine the trace was sent from.
+ */
+enum THasProgramCounter
+ {
+ /** Do add the program counter to the trace packet. */
+ EAddProgramCounter = ETrue,
+ /** Don't add the program counter */
+ ENoProgramCounter = EFalse
+ };
+
+
+/**
+ * The EXECUTABLE_DEFAULT_HAS_PC can be used to
+ * define the default setting for adding or not adding the
+ * program counter in a trace packet. This is done by defining
+ * the macro to be your new default value.
+ */
+#ifdef EXECUTABLE_DEFAULT_HAS_PC
+#define FW_DEFAULT_HAS_PC EXECUTABLE_DEFAULT_HAS_PC
+#else
+#define FW_DEFAULT_HAS_PC ENoProgramCounter
+#endif
+
+/**
+ * The division of the Group IDs into different ranges aims to manage the
+ * contention for the namespace.
+ *
+ * It is recommended that all developers use the Reserved range as far as possible.
+ *
+ * @see TGroupId
+ */
+enum TGroupIdRange
+ {
+ /**
+ * The Group IDs in the Reserved range should be used by the majority of trace
+ * points. This range of Group IDs are intended to identify which of the
+ * most common trace use-cases a trace point is contributing to. They are unique
+ * across the system.
+ *
+ * The Group IDs in this series are defined solely by the Symbian Foundation but are
+ * intended for use by any software on a device.
+ *
+ * These Group IDs should only be enabled at run-time if the filtering on
+ * ComponentIds functionality is also enabled. This is to avoid accidentally causing
+ * trace live-locks from occurring when just the Group IDs is enabled. This could
+ * happen because trace points in components involved in the current trace output
+ * path might also be assigned these Group IDs. Filtering on ComponentIds means
+ * that those trace points can be activated only when it’s known to be safe to do
+ * so and not accidentally enabled with a Group IDs.
+ *
+ * @see TGroupIdReserved
+ */
+ EOstReservedRangeFirst = 0,
+
+ /**
+ * @see EOstReservedRangeFirst
+ */
+ EOstReservedRangeLast = 221,
+
+ /**
+ * The meaning of Group IDs in this range are defined on a per-component basis.
+ * They are to be unique within a component.
+ */
+ EUserDefinedRangeFirst = 222,
+
+ /**
+ * @see EUserDefinedRangeFirst
+ */
+ EUserDefinedRangeLast = 253,
+
+ /**
+ * Only for use on the device by test code.
+ *
+ * Trace points with these Group IDs should not be released as part of a
+ * production device.
+ */
+ ETestingRangeFirst = 154,
+
+ /**
+ * @see ETestingRangeFirst
+ */
+ ETestingRangeLast = KMaxGroupId
+ };
+
+/**
+ * The Group IDs in the Reserved range should be used by the majority of
+ * trace points. This range of Group IDs are intended to identify which
+ * of the most common trace use-cases a trace point is contributing to.
+ *
+ * @see TGroupId
+ * @see TGroupIdRange
+ * @see EOstReservedRangeFirst
+ */
+enum TGroupIdReserved
+ {
+ /**
+ * Used when a fatal error, such as a panic, has occurred or when providing information
+ * on the execution state immediately before the decision to panic.
+ *
+ * A trace point with this Group ID should be used when a fatal condition is detected
+ * which will result in the flow of execution being halted in the thread associated with
+ * the trace point.
+ *
+ * Can also provide information describing where a panic has been dealt with.
+ *
+ * Trace points using this Group ID should be present in a release device.
+ */
+ TRACE_FATAL = 149,
+
+ /**
+ * Used when an error has occurred which means that the current operation cannot continue
+ * but is not sufficiently serious to cause a fatal error. These trace packets should
+ * contain not just the error code but any relevant information about the execution state
+ * when the error occurred.
+ *
+ * To be used for all types of error including include situations where the errors are
+ * returned from a function or via a leave.
+ *
+ * This Group ID also provides information describing where an error has been handled.
+ */
+ TRACE_ERROR=150,
+
+ /**
+ * Used when something unexpected or unusual has occurred that does not stop the
+ * current operation from happening but may result in unintended side effects or
+ * actual errors later on.
+ */
+ TRACE_WARNING = 151,
+
+ /**
+ * Used to describe activity at the edges of a trace component.
+ *
+ * Includes data about exported or published functions defined by a trace component as
+ * well as calls out of the component to get significant information. Exactly what
+ * is significant depends on the trace component in question. For instance, reading in a
+ * setting from an INI file would be significant but calling RArray::Count() would not be.
+ *
+ * The information in this Group ID should be enough to allow someone unfamiliar with the
+ * trace component to get a high level understanding of what functionality it has executed.
+ */
+ TRACE_BORDER = 152,
+
+ /**
+ * @deprecated Use TRACE_BORDER instead
+ */
+ TRACE_API = TRACE_BORDER,
+
+ /**
+ * @deprecated Use TRACE_NORMAL or one of the other reserved Group IDs instead
+ */
+ TRACE_IMPORTANT = 153,
+
+ /**
+ * Used to described the normal activity within a trace component that might be of interest
+ * to people who use the component.
+ *
+ * The information in this Group ID should be enough to allow someone unfamiliar with the
+ * trace component to start to understand why a component is behaving the way it is perhaps
+ * to help with diagnosing problems with the way the component is being used.
+ */
+ TRACE_NORMAL = 154,
+
+ /**
+ * Intended for tracing the state transitions of an application or service such as those
+ * performed by a machine.
+ *
+ * Trace packets using this Group ID should contain the name of the
+ * changed state variable and the new value.
+ */
+ TRACE_STATE = 155,
+
+ /**
+ * Used to provide detailed information about the normal activity of a trace component
+ * to help a developer, who is familiar with the component, to understand what it is doing.
+ */
+ TRACE_INTERNALS = 156,
+
+ /**
+ * @deprecated Use TRACE_INTERNALS instead
+ */
+ TRACE_DETAILED = TRACE_INTERNALS,
+
+ /**
+ * Used when there is a need to output large amounts of data through individual trace
+ * points that would likely cause significant intrusion if included under one of the
+ * other Group IDs.
+ *
+ * This Group ID is intended to be used in conjunction with the TRACE_INTERNALS
+ * Group ID to provide more details when debugging a specific trace component.
+ */
+ TRACE_DUMP = 157,
+
+ /**
+ * @deprecated Use TRACE_DUMP instead
+ */
+ TRACE_DEBUG = TRACE_DUMP,
+
+ /**
+ * Used to provide comprehensive information on what paths the execution takes within
+ * functions.
+ *
+ * This Group ID is intended mainly to be used by tools that add temporary instrumentation
+ * points specifically to output this data.
+ */
+ TRACE_FLOW = 158,
+
+ /**
+ * Used to output data about the execution time, memory usage, disk usage, power
+ * utilisation and any other performance characteristics of the associated trace
+ * component.
+ *
+ * This data may need to be processed before it can provide effective metrics. E.g.
+ * the time between two timestamps might need to be computed.
+ *
+ * Intended only to be used to output a small amount of data to ensure that it
+ * creates the smallest possible intrusion since otherwise the act of tracing would
+ * devalue the information it is intended to provide.
+ */
+ TRACE_PERFORMANCE = 159,
+
+ /**
+ * May be used when adding temporary trace points during a debugging session to
+ * distinguish them from existing instrumentation.
+ */
+ TRACE_ADHOC = 160,
+
+ /**
+ * This Group ID is reserved for future use to allow the Group ID range to be expanded
+ * to cover more than current 256 different values.
+ *
+ * If trace is output on this Group ID at some point in the future then this indicates
+ * that another mechanism (yet to be decided) will be used to indicate the actual
+ * Group ID for the trace.
+ */
+ TRACE_EXTENSION = 161,
+
+ /**
+ * Not intended to be used by code including this header.
+ *
+ * Provided to allow the following compile time assert (should NOT be used):
+ * EGroupIdReservedHighWaterMark <= EOstReservedRangeLast + 1
+ *
+ */
+ EGroupIdReservedHighWaterMark
+ } ;
+
+// Check high water mark for the reserved Group ID range
+__ASSERT_COMPILE(EGroupIdReservedHighWaterMark <= EOstReservedRangeLast + 1);
+
+/**
+ * @see TGroupId
+ * @see ETestingRangeFirst
+ * @test
+ */
+enum TGroupIdTesting
+ {
+ /**
+ * This Group ID may be used for testing purposes and is not intended to be used in
+ * production code.
+ */
+ TRACE_TESTING1 = ETestingRangeFirst,
+
+ /**
+ * The same as for TRACE_TESTING1
+ */
+ TRACE_TESTING2 = 155,
+
+ /**
+ * Not intended to be used by code including this header.
+ *
+ * Provided to allow the following compile time assert (should NOT be used):
+ * EGroupIdTestingHighWaterMark <= ETestingRangeLast + 1
+ *
+ */
+ EGroupIdTestingHighWaterMark
+ };
+
+// Check high water marks for the testing Group ID range
+__ASSERT_COMPILE(EGroupIdTestingHighWaterMark <= ETestingRangeLast + 1);
+
+/**
+ * @deprecated Use enumerations from TGroupIdReserved instead
+ * @see TGroupId
+ * @see TGroupIdRange
+ * @see EOstReservedRangeFirst
+ */
+enum TClassificationAll
+ {
+ EPanic = TRACE_FATAL,
+ EError = TRACE_ERROR,
+ EWarning = TRACE_WARNING,
+ EBorder = TRACE_BORDER,
+ EState = TRACE_STATE,
+ EInternals = TRACE_INTERNALS,
+ EDump = TRACE_DUMP,
+ EFlow = TRACE_FLOW,
+ ESystemCharacteristicMetrics = TRACE_PERFORMANCE,
+ EAdhoc = TRACE_ADHOC,
+ EClassificationAllHighWaterMark
+ };
+
+// Check high water mark for the 'All' classification range
+__ASSERT_COMPILE(EClassificationAllHighWaterMark <= EOstReservedRangeLast + 1);
+
+/**
+ * @deprecated Use enumerations from TGroupIdReserved instead
+ * @see TGroupId
+ * @see TGroupIdRange
+ * @see EOstReservedRangeFirst
+ */
+enum TClassificationSymbianTwo
+ {
+ EClassificationExtension = TRACE_EXTENSION,
+ EClassificationSymbianTwoHighWaterMark
+ };
+
+// Check high water marks for the Symbian Two classification range
+__ASSERT_COMPILE(EClassificationSymbianTwoHighWaterMark <= EOstReservedRangeLast + 1);
+
+/**
+ * @deprecated Use enumerations from TGroupIdTesting instead
+ * @see TGroupId
+ * @see TGroupIdRange
+ * @see ETestingRangeFirst
+ * @test
+ */
+enum TClassificationTesting
+ {
+ ETesting1 = TRACE_TESTING1,
+ ETesting2 = TRACE_TESTING2,
+ EClassificationTestingHighWaterMark,
+ };
+
+// Check high water marks for classification ranges
+__ASSERT_COMPILE(EClassificationTestingHighWaterMark <= ETestingRangeLast + 1);
+
+
+#endif //OPENSYSTEMTRACE_TYPES_H