MCL/sf/os/kernelhwsrv: comparison kernel/eka/include/opensystemtrace

equal deleted inserted replaced

--1:000000000000
+:a41df078684a
+/**
+* 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 the License "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-specific structures and values to be used with the 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__
+// Includes BTrace API macros and category values
+#include <e32btrace.h>
+/**
+@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 TGroupId KMaxGroupId = 255; // 2^8 - 1
+/**
+* @deprecated Use TGroupId instead
+* @see TGroupId
+*/
+typedef TUint8  TClassification;
+/**
+* @deprecated Use KMaxGroupId instead
+* @see KMaxGroupId
+*/
+const 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 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.
+*
+* @deprecated
+*
+*/
+#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 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 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 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 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.
+*
+* @deprecated
+*
+*/
+#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.
+*
+* @deprecated
+*
+*/
+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.
+*
+* @deprecated
+*
+*/
+#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 = 254,
+/**
+* @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 = 129,
+/**
+* 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 = 130,
+/**
+* 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 = 131,
+/**
+* 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 = 132,
+/**
+* @deprecated Use TRACE_BORDER instead
+*/
+TRACE_API = TRACE_BORDER,
+/**
+* @deprecated Use TRACE_NORMAL or one of the other reserved Group IDs instead
+*/
+TRACE_IMPORTANT = 133,
+/**
+* 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 = 134,
+/**
+* Intended for tracing the state transitions of an application or service such as those
+* performed by a machine.
+*
+* This group ID can be used only indirectly via OstTraceState0() and OstTraceState1() macros.
+* Any direct use of the Group ID will result in compilation errors.
+*/
+TRACE_STATE  = 135,
+/**
+* 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 = 136,
+/**
+* @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 = 137,
+/**
+* @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 = 138,
+/**
+* Used to output data about the performance characteristics of the associated trace component
+* such as execution times.
+*
+* 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.
+*
+* This group ID can be used only indirectly via OstTraceEventStart0(),
+* OstTraceEventStart1() and OstTraceEventStop() macros.
+* Any direct use of the Group ID will result in compilation errors.
+*/
+TRACE_PERFORMANCE = 139,
+/**
+* May be used when adding temporary trace points during a debugging session to
+* distinguish them from existing instrumentation.
+*/
+TRACE_ADHOC = 140,
+/**
+* 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 = 141,
+/**
+	 * 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 = BTrace::ETest1,
+/**
+* The same as for TRACE_TESTING1
+*/
+TRACE_TESTING2 = BTrace::ETest2,
+/**
+	 * 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

changeset 0	a41df078684a
child 4	56f325a607ea