/**
* 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