diff -r 000000000000 -r a41df078684a kernel/eka/include/e32utf.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kernel/eka/include/e32utf.h Mon Oct 19 15:55:17 2009 +0100 @@ -0,0 +1,180 @@ +// 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 E32UTRACE_H +#define E32UTRACE_H + +#include + + +/** +Methods for tracing from user and kernel side. + +These methods are used to output trace packets. +Each trace packet consist of attributes and the user defined payload. +The attributes in @see TTraceContext is used to identify and filter the trace packet. + +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. +@see e32utrace.mmh +@see RUlogger for information on how to filter at run-time + +Trace example: + +To include tracing you need to include the e32utrace.mmh +in your executables mmp file. You also need to enable tracing at +build time, which you do by defining the +SYMBIAN_INCLUDE_EXECUTABLE_TRACE before the mmh is included. + +@code +#define SYMBIAN_INCLUDE_EXECUTABLE_TRACE +#include +@endcode + +Example usage of UTrace: + +@code +#include +using namespace UTF; + +TInt E32Main() + { + TFormatId formatId = TMyAppFormatExample::KFilePrintfStringLookupId; + TUint32 myData = SomeData(); + + //One line trace examples + Printf(TTraceContext(EError), "My data %d.", myData); + Printf(TTraceContext(KMyModuleUid, EError), "My data %d.", myData); + Printf(TTraceContext(EError, ENoThreadIdentification, ENoProgramCounter), "My data %d.", myData); + + //In case Printf is overloaded + UTF::Printf(TTraceContext(EError), "My data %d.", myData); + + //Using default ModuleUid, i.e. UID3 + TTraceContext context(EError); + if(WouldBeTracedNow(context)) + { + Printf(context, "My data %d.", myData); + Trace(context, formatId, myData); + } + + //Setting the default ModuleUid to something other than UID3 + #define EXECUTABLE_DEFAULT_MODULEUID 0x00210D3B + TTraceContext otherDefault(EError); + if(WouldBeTracedNow(otherDefault)) + { + Printf(otherDefault, "My data %i.", myData); + Trace(otherDefault, formatId, myData); + } + + //Setting different ModuleUid for each trace point + static const TModuleUid KTelephony = 0x00210D3B; + static const TModuleUid KConnectivity = 0x0039399A; + TTraceContext telephony(KTelephony, ECallControl); + TTraceContext connectivity(KConnectivity, EBluetooth); + if(WouldBeTracedNow(telephony)) + { + Printf(telephony, "My data %i.", myData); + } + if(WouldBeTracedNow(connectivity)) + { + Printf(connectivity, "My data %i.", myData); + } + + //Don't add the thread identification into the trace packet + TTraceContext noThreadIdentifier(EError, ENoThreadIdentification, ENoProgramCounter); + if(WouldBeTracedNow(noThreadIdentifier)) + { + Printf(noThreadIdentifier, "My data %i.", myData); + Trace(noThreadIdentifier, formatId, myData); + } + + return KErrNone; + } + +@endcode + + +Note: +UTrace 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 +*/ +namespace UTF +{ +/** +Class used to encapsulate the context of a trace point. +For more information about the attributes please @see e32utrace_basic_types.h. +*/ +NONSHARABLE_CLASS(TTraceContext) + { +public: + inline TTraceContext(const TClassification aClassification); + inline TTraceContext(const TClassification aClassification, const THasThreadIdentification aHasThreadIdentification, const THasProgramCounter aHasProgramCounter); + + inline TTraceContext(const TModuleUid aModuleUid, const TClassification aClassification); + inline TTraceContext(const TModuleUid aModuleUid, const TClassification aClassification, const THasThreadIdentification aHasThreadIdentification, const THasProgramCounter aHasProgramCounter); + + IMPORT_C TModuleUid ModuleUid() const; + IMPORT_C TClassification Classification() const; + IMPORT_C THasThreadIdentification HasThreadIdentification() const; + IMPORT_C THasProgramCounter HasProgramCounter() const; + IMPORT_C static TModuleUid DefaultModuleUid(); +private: + inline TTraceContext(){}; +private: + TModuleUid iModuleUid; //@see TModuleUid + TClassification iClassification; //@see TClassification + THasThreadIdentification iHasThreadIdentification; //@see THasThreadIdentification + THasProgramCounter iHasProgramCounter; //@see THasProgramCounter + TUint32 iReserved1; //Reserved for future use + TUint32 iReserved2; //Reserved for future use + }; + + IMPORT_C TBool Printf(const TTraceContext& aContext, const char* aFmt, ...); + IMPORT_C TBool Print(const TTraceContext& aContext, const TDesC8& aDes); + IMPORT_C TBool Printf(const TTraceContext& aContext, TRefByValue aFmt,...); + #ifndef __KERNEL_MODE__ + IMPORT_C TBool Print(const TTraceContext& aContext, const TDesC16& aDes); + IMPORT_C TBool Printf(const TTraceContext& aContext, TRefByValue aFmt,...); + #endif //__KERNEL_MODE__ + + IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId); + IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TUint8 aData); + IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TUint16 aData); + IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TUint32 aData); + IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TUint32 aData1, const TUint32 aData2); + IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TDesC8& aData); + #ifndef __KERNEL_MODE__ + IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TDesC16& aData); + #endif + template + static inline TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const T& aData); + IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TAny* aData, const TInt aDataSize); + + IMPORT_C TBool WouldBeTracedNow(const TTraceContext& aContext); + + +#include +}//end of UTF namespace + + +#endif //E32UTRACE_H