author | hgs |
Tue, 26 Oct 2010 16:20:32 +0300 | |
changeset 62 | 1c2bb2fc7c87 |
permissions | -rw-r--r-- |
/** * 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-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); #endif //OPENSYSTEMTRACE_TYPES_H