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

//

#ifndef OPENSYSTEMTRACEV2_H

#define OPENSYSTEMTRACEV2_H

#include <opensystemtrace_types.h>

/**

This macro defines the version of the Open System Trace instrumentation API.

*/

#define OST_INSTRUMENTATION_API_VERSION 2.1.0

/**

Methods for tracing from user side.

These methods are used to output trace packets.

Each trace packet consists of attributes and the user defined payload.

In order to output trace packets, tracing needs to be

included and enabled at compile time in the executable,

as well as be filtered at run-time.

Note:

OSTv2 does not enforce any security. It is the developer's responsibility

to ensure that trace packets do not contain any sensitive information that

may undermine platform security.

@file

@publishedPartner

@prototype

*/

/**

Class used to encapsulate the context of a trace point.

For more information about the attributes please @see opensystemtrace_types.h.

The attributes in @see TTraceContext are used to identify and filter the trace packet.

@see opensystemtrace.mmh

@see RUlogger for information on how to filter at run-time

@deprecated

*/

NONSHARABLE_CLASS(TTraceContext)

    {

public:

    inline TTraceContext(const TGroupId aGroupId);

    inline TTraceContext(const TGroupId aGroupId, const THasThreadIdentification aHasThreadIdentification, const THasProgramCounter aHasProgramCounter);

    inline TTraceContext(const TComponentId aComponentId, const TGroupId aGroupId);

    inline TTraceContext(const TComponentId aComponentId, const TGroupId aGroupId, const THasThreadIdentification aHasThreadIdentification, const THasProgramCounter aHasProgramCounter);

    IMPORT_C TComponentId               ComponentId() const;

    IMPORT_C TClassification            Classification() const;

    IMPORT_C TGroupId                   GroupId() const;

    IMPORT_C THasThreadIdentification   HasThreadIdentification() const;

    IMPORT_C THasProgramCounter         HasProgramCounter() const;

    IMPORT_C static TComponentId        DefaultComponentId();

private:

    inline TTraceContext(){};

private:

    TComponentId                iComponentId;               ///<@see TComponentId

    TGroupId                    iGroupId;                   ///<@see TGroupId

    THasThreadIdentification    iHasThreadIdentification;   ///<@see THasThreadIdentification

    THasProgramCounter          iHasProgramCounter;         ///<@see THasProgramCounter

    TUint32                     iReserved1;                 //Reserved for future use

    TUint32                     iReserved2;                 //Reserved for future use

    };

	IMPORT_C TBool OstPrint(const TTraceContext& aContext, const TDesC8& aDes);

    IMPORT_C TBool OstPrintf(const TTraceContext& aContext, const char* aFmt, ...);

    IMPORT_C TBool OstPrintf(const TTraceContext& aContext, TRefByValue<const TDesC8> aFmt,...);

    #ifndef  __KERNEL_MODE__

    IMPORT_C TBool OstPrint(const TTraceContext& aContext, const TDesC16& aDes);

    IMPORT_C TBool OstPrintf(const TTraceContext& aContext, TRefByValue<const TDesC16> aFmt,...);

    #endif //__KERNEL_MODE__

    IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId);

    IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TUint8 aData);

    IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TUint16 aData);

    IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TUint32 aData);

    IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TUint32 aData1, const TUint32 aData2);

    IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TDesC8& aData);

    #ifndef __KERNEL_MODE__

    IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TDesC16& aData);

    #endif

    template<typename T>

    static inline TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const T& aData);

    IMPORT_C TBool OstTrace(const TTraceContext& aContext, const TTraceId aTraceId, const TAny* aData, const TInt aDataSize);

    IMPORT_C TBool IsTraceActive(const TTraceContext& aContext);

/**

The following trace APIs require a TraceCompiler to be present in the build system. 

This TraceCompiler is used to generate additional information for each trace point 

in order for traces to be generated at runtime.

*/

#include <opensystemtrace.inl>

// Macros

/**

Preprocessor category for all traces off.

This should not be used from traces

*/

#define OST_TRACE_CATEGORY_NONE 0x00000000

/**

Preprocessor category for traces that should be compiled

into all builds including UREL. As a result these traces

will end up in production images used by consumers.

*/

#define OST_TRACE_CATEGORY_PRODUCTION 0x00000001

/**

Preprocessor category for RnD traces

*/

#define OST_TRACE_CATEGORY_RND 0x00000002

/**

Preprocessor category for performance measurement traces

*/

#define OST_TRACE_CATEGORY_PERFORMANCE_MEASUREMENT 0x00000004

/**

Preprocessor category for traces that by default should only 

be compiled into UDEB builds.

*/

#define OST_TRACE_CATEGORY_DEBUG 0x00000008

/**

Preprocessor level for all traces on.

This should not be used from traces

*/

#define OST_TRACE_CATEGORY_ALL 0xFFFFFFFF

/**

A flag, which specifies if the compiler has been run for the component

*/

#if defined( OST_TRACE_COMPILER_IN_USE )

/**

The default preprocessor categories are defined here.

A component may override this by defining

OST_TRACE_CATEGORY before including this file

The RND category is defined for UREL and UDEB to 

preserve source compatibility.

*/

#ifndef OST_TRACE_CATEGORY

#ifdef _DEBUG

#define OST_TRACE_CATEGORY (OST_TRACE_CATEGORY_RND | \

                            OST_TRACE_CATEGORY_PRODUCTION | \

                            OST_TRACE_CATEGORY_DEBUG)

#else // _DEBUG

#define OST_TRACE_CATEGORY (OST_TRACE_CATEGORY_RND | \

                            OST_TRACE_CATEGORY_PRODUCTION)

#endif // _DEBUG

#endif // OST_TRACE_CATEGORY

/**

Trace with no parameters

@param aCategory Preprocessor category for the trace

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

*/

#define OstTraceDef0( aCategory, aGroupName, aTraceName, aTraceText ) \

    do {if ( aCategory & OST_TRACE_CATEGORY ) \

    BTraceFilteredContext8( EXTRACT_GROUP_ID(aTraceName), \

                        EOstTrace, \

                        KOstTraceComponentID, \

                        aTraceName );} while (0)

/**

Trace with one 32-bit parameter

@param aCategory Preprocessor category for the trace

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aParam The 32-bit value to be traced

*/

#define OstTraceDef1( aCategory, aGroupName, aTraceName, aTraceText, aParam ) \

    do {if ( aCategory & OST_TRACE_CATEGORY ) \

    BTraceFilteredContext12( EXTRACT_GROUP_ID(aTraceName), \

                         EOstTrace, \

                         KOstTraceComponentID, \

                         aTraceName, \

                         aParam );} while (0)

/**

Trace with more than 32 bits of data

@param aCategory Preprocessor category for the trace

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aPtr Pointer to the data to be traced

@param aLength Length of the data to be traced

*/

#define OstTraceDefData( aCategory, aGroupName, aTraceName, aTraceText, aPtr, aLength ) \

    do {if ( aCategory & OST_TRACE_CATEGORY ) \

        OstSendNBytes( EXTRACT_GROUP_ID(aTraceName), \

                       EOstTrace, \

                       KOstTraceComponentID, \

                       aTraceName, \

                       aPtr, \

                       aLength );} while (0)

/**

Trace with one parameter that is not 32-bit integer. This calls OstTraceGen1,

which is generated by the trace compiler. The generated function will pack the

parameter into a stack-allocated buffer and call OstTraceData with the buffer.

@param aCategory Preprocessor category for the trace

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aParam The parameter to be traced

*/

#define OstTraceDefExt1( aCategory, aGroupName, aTraceName, aTraceText, aParam ) \

    do {if ( aCategory & OST_TRACE_CATEGORY ) \

        OstTraceGen1( aTraceName, aParam );} while (0)

/**

Trace with two parameters. This calls OstTraceGen2, which is generated by trace compiler.

The generated function will pack the parameters into a stack-allocated buffer and

call OstTraceData with the buffer.

@param aCategory Preprocessor category for the trace

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aParam1 The first parameter to be traced

@param aParam2 The second parameter to be traced

*/

#define OstTraceDefExt2( aCategory, aGroupName, aTraceName, aTraceText, aParam1, aParam2 ) \

    do {if ( aCategory & OST_TRACE_CATEGORY ) \

        OstTraceGen2( aTraceName, aParam1, aParam2 );} while (0)

/**

Trace with three parameters. This calls OstTraceGen3, which is generated by trace compiler.

The generated function will pack the parameters into a stack-allocated buffer and

call OstTraceData with the buffer.

@param aCategory Preprocessor category for the trace

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aParam1 The first parameter to be traced

@param aParam2 The second parameter to be traced

@param aParam3 The third parameter to be traced

*/

#define OstTraceDefExt3( aCategory, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3 ) \

    do {if ( aCategory & OST_TRACE_CATEGORY ) \

        OstTraceGen3( aTraceName, aParam1, aParam2, aParam3 );} while (0)

/**

Trace with four parameters. This calls OstTraceGen4, which is generated by trace compiler.

The generated function will pack the parameters into a stack-allocated buffer and

call OstTraceData with the buffer.

@param aCategory Preprocessor category for the trace

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aParam1 The first parameter to be traced

@param aParam2 The second parameter to be traced

@param aParam3 The third parameter to be traced

@param aParam4 The fourth parameter to be traced

*/

#define OstTraceDefExt4( aCategory, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4 ) \

    do {if ( aCategory & OST_TRACE_CATEGORY ) \

        OstTraceGen4( aTraceName, aParam1, aParam2, aParam3, aParam4 );} while (0)

/**

Trace with five parameters. This calls OstTraceGen5, which is generated by trace compiler.

The generated function will pack the parameters into a stack-allocated buffer and

call OstTraceData with the buffer.

@param aCategory Preprocessor category for the trace

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aParam1 The first parameter to be traced

@param aParam2 The second parameter to be traced

@param aParam3 The third parameter to be traced

@param aParam4 The fourth parameter to be traced

@param aParam5 The fifth parameter to be traced

*/

#define OstTraceDefExt5( aCategory, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4, aParam5 ) \

    do {if ( aCategory & OST_TRACE_CATEGORY ) \

        OstTraceGen5( aTraceName, aParam1, aParam2, aParam3, aParam4, aParam5 );} while (0)

/**

*************** Trace macros which use RnD as default preprocessor category ***************

*/

/**

RnD trace with no parameters

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

*/

#define OstTrace0( aGroupName, aTraceName, aTraceText ) \

    OstTraceDef0( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText )

/**

RnD trace with one 32-bit parameter

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aParam The 32-bit value to be traced

*/

#define OstTrace1( aGroupName, aTraceName, aTraceText, aParam ) \

    OstTraceDef1( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aParam )

/**

RnD trace with more than 32 bits of data

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aPtr Pointer to the data to be traced

@param aLength Length of the data to be traced

*/

#define OstTraceData( aGroupName, aTraceName, aTraceText, aPtr, aLength ) \

    OstTraceDefData( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aPtr, aLength )

/**

RnD trace with one parameter that is not 32-bit integer. This calls OstTraceGen1,

which is generated by the trace compiler. The generated function will pack the

parameter into a stack-allocated buffer and call OstTraceData with the buffer.

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aParam The parameter to be traced

*/

#define OstTraceExt1( aGroupName, aTraceName, aTraceText, aParam ) \

    OstTraceDefExt1( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aParam )

/**

RnD trace with two parameters. This calls OstTraceGen2, which is generated by trace compiler.

The generated function will pack the parameters into a stack-allocated buffer and

call OstTraceData with the buffer.

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aParam1 The first parameter to be traced

@param aParam2 The second parameter to be traced

*/

#define OstTraceExt2( aGroupName, aTraceName, aTraceText, aParam1, aParam2 ) \

    OstTraceDefExt2( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aParam1, aParam2 )

/**

RnD trace with three parameters. This calls OstTraceGen3, which is generated by trace compiler.

The generated function will pack the parameters into a stack-allocated buffer and

call OstTraceData with the buffer.

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aParam1 The first parameter to be traced

@param aParam2 The second parameter to be traced

@param aParam3 The third parameter to be traced

*/

#define OstTraceExt3( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3 ) \

    OstTraceDefExt3( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3 )

/**

RnD trace with four parameters. This calls OstTraceGen4, which is generated by trace compiler.

The generated function will pack the parameters into a stack-allocated buffer and

call OstTraceData with the buffer.

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aParam1 The first parameter to be traced

@param aParam2 The second parameter to be traced

@param aParam3 The third parameter to be traced

@param aParam4 The fourth parameter to be traced

*/

#define OstTraceExt4( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4 ) \

    OstTraceDefExt4( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4 )

/**

RnD trace with five parameters. This calls OstTraceGen5, which is generated by trace compiler.

The generated function will pack the parameters into a stack-allocated buffer and

call OstTraceData with the buffer.

@param aGroupName Name of the trace group. Trace Compiler associates the group name with a 16-bit integer.

                  Then, it combines the group name with a unique trace id (16-bit integer) to produce the trace name

                  (aTraceName 32-bit integer). Only the trace name is sent in the trace packet.

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aTraceText The trace text, which is parsed by the trace compiler.

                  The text itself is not sent in the trace packet

@param aParam1 The first parameter to be traced

@param aParam2 The second parameter to be traced

@param aParam3 The third parameter to be traced

@param aParam4 The fourth parameter to be traced

@param aParam5 The fifth parameter to be traced

*/

#define OstTraceExt5( aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4, aParam5 ) \

    OstTraceDefExt5( OST_TRACE_CATEGORY_RND, aGroupName, aTraceName, aTraceText, aParam1, aParam2, aParam3, aParam4, aParam5 )

/**

Function entry trace without extra parameters.

The trace is mapped to TRACE_FLOW or TRACE_API group by the trace compiler

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

*/

#define OstTraceFunctionEntry0( aTraceName ) \

    do {if ( OST_TRACE_CATEGORY_RND & OST_TRACE_CATEGORY ) \

    BTraceFilteredContext8( EXTRACT_GROUP_ID(aTraceName), \

                        EOstTrace, \

                        KOstTraceComponentID, \

                        aTraceName );} while (0)

/**

Function entry trace with a parameter representing the instance identifier.

The trace is mapped to TRACE_FLOW or TRACE_API group by the trace compiler

@param aTraceName Name of the trace. The name is mapped to a 32-bit identifier and thus must be unique

@param aInstance The instance identifier, for example "this" pointer

*/

#define OstTraceFunctionEntry1( aTraceName, aInstance ) \

    do {if ( OST_TRACE_CATEGORY_RND & OST_TRACE_CATEGORY ) \

    BTraceFilteredContext12( EXTRACT_GROUP_ID(aTraceName), \

                         EOstTrace, \

                         KOstTraceComponentID, \

                         aTraceName, \

                         (TUint32) aInstance );} while (0)

/**

Function entry trace, which traces function parameters.

The trace is mapped to TRACE_FLOW or TRACE_API group by the trace compiler