/**

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

*

* WARNING: This file contains some APIs which are internal and are subject

*          to change without notice. Such APIs should therefore not be used

*          outside the Kernel and Hardware Services package.

*/

/**

 @file

 @publishedPartner

 @prototype

*/

#ifndef E32UTRACE_BASIC_TYPES_H

#define E32UTRACE_BASIC_TYPES_H

#ifdef __KERNEL_MODE__

#include <kernel/kernel.h>

#else //__KERNEL_MODE__

#include <e32std.h>

#endif //__KERNEL_MODE__

/**

@file

@publishedPartner

@prototype

*/

namespace UTF

{

/**

 * Every trace point must be statically assigned a classification. This is

 * essentially a “label” that allows identification of the intended use of

 * the trace packets generated by the trace point. The classification either

 * reflects a system-wide Tracing use-case, such as highlighting reasons why

 * a Panic occurred, or is assigned to trace points in performance critical

 * software such as the kernel or other key services.

 * @see TClassificationRange for more information.

 */

typedef TUint8  TClassification;

/**

 * The maximum possible value for TClassification

 */

const static TClassification KMaxClassification = 255; // 2^8 - 1

/**

 * Each trace point must be statically assigned a ModuleUid to indicate the

 * module in which the trace point is defined. It is recommended that this

 * value is the UID3 of the associated binary file.

 *

 * The ModuleUid and Classification attributes of a trace point are independent.

 */

typedef TUint32 TModuleUid;

/**

 * The maximum possible value for TModuleUid

 */

const static TModuleUid KMaxModuleUid = 0xFFFFFFFF; // 2^32 - 1, or 4294967295 - 1

/**

 * The EXECUTABLE_DEFAULT_MODULEUID can be used to define your own default

 * specific ModuleUid. This is done by defining the macro to be your new

 * default value.

 */

#ifdef EXECUTABLE_DEFAULT_MODULEUID

#define FW_DEFAULT_MODULEUID EXECUTABLE_DEFAULT_MODULEUID

#else

#define FW_DEFAULT_MODULEUID TTraceContext::DefaultModuleUid()

#endif

/**

 * This is a numerical value statically assigned to a trace point which will be used

 * on the host to look-up the format of the associated trace packets.

 *

 * The meaning of a FormatId is specific to the ModuleUid and Category of the

 * associated trace point.

 */

typedef TUint16 TFormatId;

/**

 * The maximum possible value for TFormatId

 */

const static TFormatId KMaxFormatId = 65535; // 2^16 - 1

/**

 * TFormatId used in packets produced by the Print and Printf

 * functions.

 *

 * Note that this format should not be used on the

 * device by clients of UTrace. This symbol is only marked

 * as published to partners to give host side tools access to

 * it.

 *

 * @see TFormatId

 */

const static TFormatId KFormatPrintf = 0;

/**

 * TFormatId 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 UTrace. This symbol is only marked

 * as published to partners to give host side tools access to

 * it.

 *

 * @see TFormatId

 */

const static TFormatId KFormatPrintfUnicode = 1;

/**

 * This value is intended to be used by clients to specify the

 * start of the range of enums used to define their format ids.

 *

 * Any values between 0 up to this should not be used directly

 * by clients of UTrace on the device.

 *

 * @see TFormatId

 */

const static TFormatId 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

 * classificiation 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 Classifications in the All range should be used by the majority of

 * trace points. This range of Classifications are intended to identify which

 * of the most common trace use-cases a trace point is contributing to.

 * The Classifications in this series are defined solely by Symbian but are

 * intended for use by any software on a device.

 *

 * @see TClassification

 * @see TClassificationRange

 * @see EAllRangeFirst

 */

enum TClassificationAll

	{

	/**

	 * Used when a panic has occurred or when providing information on the execution

	 * state that lead to the decision to panic.

	 *

	 * A trace point with this Classification indicates a fatal condition is about to

     * occur which will halt the flow of program execution in the current thread.

	 *

	 * This Classification also provides information describing where a panic has been

	 * dealt with.

	 *

	 * EPanic = EAllRangeFirst

	 */

	EPanic = 192,

	/**

	 * Used when an error has occurred that means the current operation cannot continue

	 * but isn’t sufficiently serious to cause a Panic. The trace points could 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 and includes situations where the errors are

	 * returned from a function or in a Leave.

	 *

	 * This Classification also provides information describing where an error has been

	 * dealt with.

	 */

	EError = 193,

	/**

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

	 */

	EWarning = 194,

	/**

	 * Used to detail normal activity at the edges of a module. Does not include errors

	 * or warnings as these are covered in other Classifications.

	 *

	 * Includes data about exported or published functions defined by module as well as

     * calls out of the module to get significant information. Exactly what is significant

     * is for the module owner to decide. For example, getting the contents of an .ini file to

     * determine which configuration to use might be significant but calling RArray::Count()

     * would not be.

	 *

	 * The information in this Classification should be enough to allow someone unfamiliar

	 * with the trace module to get a high level understanding of what functionality it has

	 * executed.

	 */

	EBorder = 195,

	/**

	 * Intended for tracing the state transitions of an application or service such as those

	 * performed by a machine.

	 *

	 * Trace packet’s using this Classification should contain the name of the

	 * changed state variable and the new value.

	 */

	EState = 196,

	/**

	 * Used to provide detailed information about the normal activity of a module

	 * to help a developer, who is familiar with the module, to understand what it is doing.

	 *

	 * Does not include errors or warnings as those are covered in other Classifications.

	 */

	EInternals = 197,

	/**

	 * 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 Classifications.

	 *

	 * This Classification in intended to be used in conjunction with the Internals

	 * Classification to provide more details when debugging a specific module.

	 */

	EDump = 198,

	/**

	 * Used to provide comprehensive information on what paths the execution takes within

	 * functions.

	 *

	 * This Classification is intended only to be assigned by tools that add temporary

	 * instrumentation points specifically to output this data.

	 */

	EFlow = 199,

	/**

	 * Used to output data about the execution time, memory usage, disk usage, power

	 * utilisation and other system characteristics of the trace module.

	 *

	 * This data may need to be processed before it can provide affective metrics. E.g.

	 * the time between two timestamps might need to be computed.

	 *

	 * Intended only to be used to output system characteristic data that requires the

	 * smallest possible intrusion.

	 */

	ESystemCharacteristicMetrics = 200,

	/**

	 * Can be used when adding ad-hoc / temporary trace points if there’s a need to

	 * distinguish it from existing trace.

	 */

	EAdhoc = 201,

	/**

	 * Provided to allow the following compile time assert:

	 * EClassificationAllHighWaterMark <= EAllRangeLast + 1

	 *

	 * @internalComponent

	 */

	EClassificationAllHighWaterMark,

	};

/**

 * The division of the Classifications into different ranges aims to manage the

 * contention for the namespace.

 * The stakeholders considered for the namespace are:

 * - Software vendors who own trace points in a base-port, whether a hardware

 *   manufacturer or their suppliers.

 * - Software vendors who own trace points in the UI layer, whether a phone

 *   manufacturer or their suppliers.

 * - ISVs who own trace points in source code installed on a device after it has been

 *   released.

 * - Symbian as the owner of all trace points in Symbian OS.

 *

 * It is recommended that all stakeholders use the All range as far as possible.

 * It is also strongly recommended that software provided by one stakeholder does

 * not use any Classifications from a range provided specifically for another

 * stakeholder.

 *

 * @see TClassification

 */

enum TClassificationRange

	{

	/**

	 * The Symbian One range is only for use on the device by Symbian.

	 *

	 * @see epoc32\include\e32btrace.h

	 *

	 * This range is defined and used by Symbian only.

	 */

	ESymbianOneRangeFirst = 0,

	/**

	 * @see ESymbianOneRangeFirst

	 */

	ESymbianOneRangeLast = 127,

	/**

	 * The Base Port range is only for use on the device by code provided solely as

	 * part of a base-port.

	 *

	 * It is expected that the owner of each base-port will manage the use of trace

	 * points by all the software vendors contributing to their base-port to prevent

	 * conflicts.

	 *

	 * This range may only be defined and used by device manufacturers.

	 */

	EBasePortRangeFirst = 128,

	/**

	 * @see EBasePortRangeFirst

	 */

	EBasePortRangeLast = 159,

	/**

	 * The UI Layer range is only for use on the device by code provided as part of

	 * the UI Layer. This includes all software needed to create a device

	 * that is not part of Symbian OS or the base-port.

	 *

	 * It is expected that the owner of each UI layer will prevent collisions between

	 * trace points provided by all the software vendors contributing software to the

     * UI layer.

	 *

	 * This range may only be defined and used by device manufacturers.

	 */

	EUiLayerRangeFirst = 160,

	/**

	 * @see EUiLayerRangeFirst

	 */

	EUiLayerRangeLast = 191,

	/**

	 * The Classifications in the All range should be used by the majority of trace

	 * points. This range of Classifications are intended to identify which of the

	 * most common trace use-cases a trace point is contributing to.

	 *

	 * The Classifications in this series are defined solely by Symbian but are

	 * intended for use by any software on a device. No software vendor other than

	 * Symbian should define Classifications in this range.

	 *

	 * When assigning one of these Classifications to a trace point you should

	 * also assign a ModuleUid to allow your trace points to be differentiated from

	 * other uses of the Classification in the system.

	 *

	 * These Classifications should only be enabled at run-time if the filtering on

	 * ModuleUids functionality is also enabled. This is to avoid accidentally causing

     * trace live-locks from occurring when the Classification is enabled. This could

     * happen because trace points in components involved in the current trace output

     * path might also be assigned these Classifications. Filtering on ModuleUids 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 Classification.

	 *

	 * This range is definded by Symbian and may be used by anyone.

	 *

	 * @see TAllClassification

	 */

	EAllRangeFirst = 192,

	/**

	 * @see EAllRangeFirst

	 */

	EAllRangeLast = 221,

	/**

	 * This range may only be used and defined by Symbian.

	 */

	ESymbianTwoRangeFirst = 222,

	/**

	 * @see ESymbianTwoRangeFirst

	 */

	ESymbianTwoRangeLast = 245,

	/**

	 * The ISV range is only for use on the device by ISVs providing software that is

	 * installed on a device after it has been released and is not part of the base-port,

     * Symbian OS or the UI Layer.

	 *

	 * This range is only intended to provide enough Classifications for a single ISV

	 * application. Clashes that occur between different applications should be

	 * resolved by uninstalling one or other of them.

	 *

	 * This range is defined and used by 3rd party developers.

	 */

	EIsvRangeFirst = 246,

	/**

	 * @see EIsvRangeFirst

	 */

	EIsvRangeLast = 253,

	/**

	 * Only for use on the device by test code.

	 *

	 * Trace points with these Classifications should not be released as part of a

	 * production device.

	 */

	ETestingRangeFirst = 254,

	/**

	 * @see ETestingRangeFirst

	 */

	ETestingRangeLast = KMaxClassification,

	};

// Check high water mark for classification ranges for TClassificationAll

__ASSERT_COMPILE(EClassificationAllHighWaterMark <= EAllRangeLast + 1);

/**

 * @see TClassification

 * @see ESymbianTwoRangeFirst

 * @internalComponent

 */

enum TClassificationSymbianTwo

	{

	/**

	 * This classification is reserved for future use to allow the classification range

	 * to be expanded to cover more than current 256 different values.

	 *

	 * If trace is output on this Classification at some point in the future then this

	 * indicates another mechanism (to be decided) will be used to indicate the actual

	 * Classification for the trace.

	 *

	 * EClassificationExtension = 222

	 */

	EClassificationExtension = ESymbianTwoRangeFirst,

	/**

	 * Provided to allow the following compile time assert:

	 * EClassificationSymbianTwoHighWaterMark <= ESymbianTwoRangeLast + 1

	 *

	 * @internalComponent

	 */

	EClassificationSymbianTwoHighWaterMark,

	};

// Check high water marks for classification ranges

__ASSERT_COMPILE(EClassificationSymbianTwoHighWaterMark <= ESymbianTwoRangeLast + 1);

/**

 * @see TClassification

 * @see ETestingRangeFirst

 * @test

 */

enum TClassificationTesting

	{

	/**

	 * Only for use on the device by test code.

	 *

	 * Trace points with this Classification should not be released as part of a

	 * production device.

	 *

	 * ETesting1 = 254

	 */

	ETesting1 = ETestingRangeFirst,

	/**

	 * @see ETesting1

	 */

	ETesting2 = 255,

	/**

	 * Provided to allow the following compile time assert: