/**

* 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);

#endif //OPENSYSTEMTRACE_TYPES_H