1 // Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // Trace API

    15 // 

    16 //

    17 

    18 #ifndef UTRACE_H

    19 #define UTRACE_H

    20 

    21 #ifdef __KERNEL_MODE__

    22 #include <kernel/kernel.h>

    23 #else //__KERNEL_MODE__

    24 #include <e32std.h>

    25 #endif //__KERNEL_MODE__

    26 #include <e32btrace.h>

    27 

    28 

    29 /**

    30 @file

    31 @publishedPartner

    32 @prototype

    33 */

    34 

    35 /**

    36 Primary filter type.

    37 The primary filter type used as classification information.

    38 */

    39 typedef TUint8 TPrimaryFilter;

    40 /**

    41 Secondary filter type.

    42 The secondary filter type used as classification information.

    43 */

    44 typedef TUint32 TSecondaryFilter;

    45 

    46 

    47 /**

    48 The trace contains information used to debug an application

    49 This can be used in both UREL and UDEB builds.

    50 */

    51 const TPrimaryFilter  KDebug = 253;

    52 

    53 

    54 /**

    55 Schema type.

    56 Use the schema in conjunction with primary and secondary filters to determine

    57 how a trace shall be interpreted.

    58 The schema must represent a specific, well-documented, and consistent plan;

    59 a way to define the structure and/or its content.

    60 */

    61 typedef TUint8 TTraceSchema;

    62 

    63 /**

    64 The schema is binary, or raw data.

    65 */

    66 const TTraceSchema KBinary = 0;//Binary format

    67 /**

    68 The schema is ASCII text.

    69 */

    70 const TTraceSchema KText = 1;//Text only

    71 

    72 /**

    73 Maximum length of a formatted string

    74 */

    75 const TInt KMaxPrintfSize = 256;

    76 

    77 

    78 /**@internalComponent*/

    79 #define UTRACE_HEADER(aSize,aF1,aSchema,aContext,aPc)																\

    80 	((((aSize)+(4&(TBool)aContext<<2)+(4&(TBool)aPc<<2))<<BTrace::ESizeIndex*8)										\

    81 	+(((BTrace::EContextIdPresent & (aContext<<3))|(BTrace::EPcPresent & (aPc<<4)))<<BTrace::EFlagsIndex*8)			\

    82 	+((aF1)<<BTrace::ECategoryIndex*8)																				\

    83 	+((aSchema)<<BTrace::ESubCategoryIndex*8))

    84 /**@internalComponent*/

    85 #define UTracePf0(aF1,aSchema,aContext,aPc)	\

    86 	((BTrace::TBTrace1)BTrace::OutX) \

    87 		(UTRACE_HEADER(4,(aF1),(aSchema),(aContext),(aPc)))

    88 /**@internalComponent*/

    89 #define UTracePf1(aF1,aSchema,aContext,aPc,a1)	\

    90 	((BTrace::TBTrace2)BTrace::OutX)(UTRACE_HEADER(8,(aF1),(aSchema),(aContext),(aPc)),(TUint32)(a1))

    91 /**@internalComponent*/

    92 #define UTracePf2(aF1,aSchema,aContext,aPc,a1,a2) \

    93 	((BTrace::TBTrace3)BTrace::OutX)(UTRACE_HEADER(12,(aF1),(aSchema),(aContext),(aPc)),(TUint32)(a1),(TUint32)(a2))

    94 /**@internalComponent*/

    95 #define UTracePf3(aF1,aSchema,aContext,aPc,a1,a2,a3) \

    96 	BTrace::OutX(UTRACE_HEADER(16,(aF1),(aSchema),(aContext),(aPc)),(TUint32)(a1),(TUint32)(a2),(TUint32)(a3))

    97 /**@internalComponent*/

    98 #define UTracePfAny(aF1,aSchema,aContext,aPc,a1,aData,aDataSize) \

    99 	BTrace::OutBig(UTRACE_HEADER(8,(aF1),(aSchema),(aContext),(aPc)),(TUint32)(a1),aData,(TInt)(aDataSize))

   100 /**@internalComponent*/

   101 #define UTraceSf0(aF1,aF2,aSchema,aContext,aPc)	\

   102 	((BTrace::TBTrace2)BTrace::OutFilteredX)(UTRACE_HEADER(8,(aF1),(aSchema),(aContext),(aPc)),(TUint32)(aF2))

   103 /** @internalComponent */

   104 #define UTraceSf1(aF1,aF2,aSchema,aContext,aPc,a1) \

   105 	((BTrace::TBTrace3)BTrace::OutFilteredX)(UTRACE_HEADER(12,(aF1),(aSchema),(aContext),(aPc)),(TUint32)(aF2),(TUint32)(a1))

   106 /** @internalComponent */

   107 #define UTraceSf2(aF1,aF2,aSchema,aContext,aPc,a1,a2) \

   108 	BTrace::OutFilteredX(UTRACE_HEADER(16,(aF1),(aSchema),(aContext),(aPc)),(TUint32)(aF2),(TUint32)(a1),(TUint32)(a2))

   109 /** @internalComponent */

   110 #define UTraceSfAny(aF1,aF2,aSchema,aContext,aPc,aData,aDataSize) \

   111 	BTrace::OutFilteredBig(UTRACE_HEADER(8,(aF1),(aSchema),(aContext),(aPc)),(TUint32)(aF2),aData,(TInt)(aDataSize))

   112 

   113 

   114 /**

   115 Class for tracing from user and kernel side.

   116 

   117 This appends entries to a trace log.

   118 Each trace point require classification information to be passed.

   119 Classification information, i.e. primary and secondary filter,

   120 is meta-data about the trace entry that can be used for

   121 filtering, e.g. the  trace was inserted by a particular component.

   122 

   123 In order to append trace points to the trace log they

   124 need to be turned on and off at run-time, based on the classification.

   125 It is also possible to turn trace points on and off

   126 at compile-time using the SYMBIAN_TRACE_ENABLE macro.

   127 

   128 The class can be used in two ways, either using the

   129 static methods without any preparatory work, or by setting up

   130 an object which has all necessary information pre-defined which

   131 allows each consecutive call to contain a minimum of information.

   132 The latter set of methods are more intrusive both at run-time and

   133 for foot print.

   134 

   135 @code

   136 TBool includeContextID = ETrue;

   137 TBool includePc = EFalse;

   138 TUint32 traceData = aData;

   139 TPrimaryFilter filter1 = 253;

   140 

   141 TUTrace tracer(filter1, KBinary, includeContextID, includePc);

   142 tracer.Printf(_L("My trace point."));

   143 tracer.Trace(traceData);

   144 

   145 //or

   146 

   147 TUTrace::PrintfPrimary(filter1, KBinary, includeContextID, includePc, _L("My trace point with data %i."), traceData);

   148 TUTrace::TracePrimary(filter1, KBinary, includeContextID, includePc, traceData);

   149 

   150 @endcode

   151 

   152 

   153 Note:

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

   155 to ensure that trace points do not contain any sensitive information that may 

   156 be used to compromise platform security.

   157 

   158 @publishedPartner

   159 @prototype

   160 */

   161 #if defined (SYMBIAN_TRACE_ENABLE) || defined (__DOXYGEN__)

   162 class TUTrace

   163 {

   164 public:

   165 

   166 	/**

   167 	Construct a trace object with classification for

   168 	primary filter only.

   169 

   170 	@param aF1 Primary filter as classification information

   171 	@param aSchema The schema used to determine the format of the content

   172 	@param aIncludeContextID Include context ID in the trace

   173 	@param aIncludePc Include program counter in the trace

   174 	*/

   175 	TUTrace(TPrimaryFilter aF1, TTraceSchema aSchema, TBool aIncludeContextID, TBool aIncludePc)

   176 		{

   177 		Set(aF1, aSchema, aIncludeContextID, aIncludePc);

   178 		}

   179 

   180 	/**

   181 	Construct a trace object with classification for both

   182 	primary and secondary filters.

   183 

   184 	@param aF1 Primary filter as classification information

   185 	@param aF2 Secondary filter as classification information

   186 	@param aSchema The schema used to determine the format of the content

   187 	@param aIncludeContextID Include context ID in the trace

   188 	@param aIncludePc Include program counter in the trace

   189 	*/

   190 	TUTrace(TPrimaryFilter aF1, TSecondaryFilter aF2, TTraceSchema aSchema, TBool aIncludeContextID, TBool aIncludePc)

   191 		{

   192 		Set(aF1, aF2, aSchema, aIncludeContextID, aIncludePc);

   193 		}

   194 

   195 

   196 	/**

   197 	Set the classification and additional information.

   198 

   199 	@param aF1 Primary filter as classification information

   200 	@param aSchema The schema used to determine the format of the content

   201 	@param aIncludeContextID Include context ID in the trace

   202 	@param aIncludePc Include program counter in the trace

   203 	*/

   204 	void Set(TPrimaryFilter aF1, TTraceSchema aSchema, TBool aIncludeContextID, TBool aIncludePc)

   205 		{

   206 		iF2 = 0;

   207 		iF1 = aF1;

   208 		iSchema = aSchema;

   209 		iPresent = aIncludeContextID;

   210 		iPresent |= aIncludePc << EPc;

   211 		iReserved1 = 0;

   212 		iReserved2 = 0;

   213 		}

   214 

   215 

   216 	/**

   217 	Set the classification and additional information.

   218 

   219 	@param aF1 Primary filter as classification information

   220 	@param aF2 Secondary filter as classification information

   221 	@param aSchema The schema used to determine the format of the content

   222 	@param aIncludeContextID Include context ID in the trace

   223 	@param aIncludePc Include program counter in the trace

   224 	*/

   225 	void Set(TPrimaryFilter aF1, TSecondaryFilter aF2, TTraceSchema aSchema, TBool aIncludeContextID , TBool aIncludePc)

   226 		{

   227 		Set(aF1, aSchema, aIncludeContextID, aIncludePc);

   228 		iF2 = aF2;

   229 		}

   230 

   231 	#ifdef  __KERNEL_MODE__

   232 

   233 	/**

   234 	Prints a formatted string in kernel mode only.

   235 

   236 	The function uses Kern::AppendFormat() to do the formatting.

   237 

   238 	Although it is safe to call this function from an ISR, it polls the output

   239 	serial port and may take a long time to complete, invalidating any

   240 	real-time guarantee.

   241 

   242 	If called from an ISR, it is possible for output text to be intermingled

   243 	with other output text if one set of output interrupts or preempts another.

   244 

   245 	Some of the formatting options may not work inside an ISR.

   246 

   247 	Be careful not to use a string that is too long to fit onto the stack.

   248 	If the specified string is too big to fit into a single	trace

   249 	a multipart trace is generated.

   250 

   251 	@param aFmt The format string. This must not be longer than 256 characters.

   252 	@param ...	A variable number of arguments to be converted to text as dictated

   253 				by the format string.

   254 

   255 	@return The trace was/was not logged.

   256 

   257 	@pre Calling thread can either be in a critical section or not.

   258 	@pre Interrupts must be enabled.

   259 	@pre Kernel must be unlocked

   260 	@pre Call in any context.

   261 	@pre Suitable for use in a device driver

   262 	@pre Classification information must be set up

   263 

   264 	@see Kern::AppendFormat()

   265 	@see BTrace::TMultipart

   266 	*/

   267 	TBool Printf(const char* aFmt, ...)

   268 		{

   269 		TBuf8<KMaxPrintfSize> buf;

   270 		VA_LIST list;

   271 		VA_START(list,aFmt);

   272 		Kern::AppendFormat(buf,aFmt,list);

   273 		TUint8 oldFormat = iSchema;

   274 		iSchema = KText;

   275 		TBool logged = EFalse;

   276 		logged = Trace(buf.Ptr(),buf.Size());

   277 		iSchema = oldFormat;

   278 		return logged;

   279 		}

   280 

   281 	#else //__KERNEL_MODE__

   282 

   283 	/**

   284 	Prints a formatted string.

   285 

   286 	@param aFmt The format string. This must not be longer than 256 characters.

   287 	@param ...	A variable number of arguments to be converted to text as dictated

   288 				by the format string.

   289 

   290 	@return The trace was/was not logged.

   291 

   292 	@pre Classification information must be set up

   293 	*/

   294 	TBool Printf(const char* aFmt, ...)

   295 		{

   296 		TTruncateOverflow8 overflow;

   297 		VA_LIST list;

   298 		VA_START(list,aFmt);

   299 		TPtrC8 fmt((const TText8*)aFmt);

   300 		TBuf8<KMaxPrintfSize> buf;

   301 		buf.AppendFormatList(fmt,list,&overflow);

   302 		TUint8 oldFormat = iSchema;

   303 		iSchema = KText;

   304 		TBool logged = EFalse;

   305 		logged = Trace(buf.PtrZ(),buf.Size());

   306 		iSchema = oldFormat;

   307 		return logged;

   308 		};

   309 

   310 	/**

   311 	Prints a formatted string.

   312 

   313 	@param aFmt The format string. This must not be longer than 256 characters.

   314 	@param ...	A variable number of arguments to be converted to text as dictated

   315 				by the format string.

   316 

   317 	@return The trace was/was not logged.

   318 

   319 	@pre Classification information must be set up

   320 	*/

   321 	TBool Printf(TRefByValue<const TDesC16> aFmt,...)

   322 	    {

   323 	    TTruncateOverflow16 overflow;

   324 		VA_LIST list;

   325 		VA_START(list,aFmt);

   326 		TBuf<KMaxPrintfSize> buf;

   327 		buf.AppendFormatList(aFmt,list,&overflow);

   328 		TUint8 oldFormat = iSchema;

   329 		iSchema = KText;

   330 		TBool logged = EFalse;

   331 		#ifdef _UNICODE

   332 		TPtr8 p(buf.Collapse());

   333 		logged = Trace(buf.PtrZ(), p.Size());

   334 		#else

   335 		logged = Trace(buf.PtrZ(), buf.Size());

   336 		#endif //_UNICODE

   337 		iSchema = oldFormat;

   338 		return logged;

   339 	    };

   340 

   341 	/**

   342 	Prints a string.

   343 

   344 	@param aDes The string. This can be of variable length.

   345 

   346 	@return The trace was/was not logged.

   347 

   348 	@pre Classification information must be set up

   349 	*/

   350 	TBool Printf(const TDesC8& aDes)

   351 		{

   352 		TUint8 oldFormat = iSchema;

   353 		iSchema = KText;

   354 		TBool logged = EFalse;

   355 		logged = Trace(aDes.Ptr(), aDes.Size());

   356 		iSchema = oldFormat;

   357 		return logged;

   358 		};

   359 

   360 	/**

   361 	Prints a string.

   362 

   363 	@param aDes The string. This can be of variable length.

   364 

   365 	@return The trace was/was not logged.

   366 

   367 	@pre Classification information must be set up

   368 	*/

   369 	TBool Printf(const TDesC16& aDes)

   370 	    {

   371 		TUint8 oldFormat = iSchema;

   372 		iSchema = KText;

   373 		TBool logged = EFalse;

   374 		logged = Trace(aDes.Ptr(), aDes.Size());

   375 		iSchema = oldFormat;

   376 		return logged;

   377 		};

   378 

   379 	#endif //__KERNEL_MODE__

   380 

   381 	/**

   382 	Sends a trace with no payload data.

   383 

   384 	@return The trace was/was not logged.

   385 

   386 	@pre Classification information must be set up

   387 	*/

   388     TBool Trace()

   389 		{

   390 		if(iF2 > 0)

   391 			{

   392 			return UTraceSf0(iF1,iF2,iSchema,ContextID(),Pc());

   393 			}

   394 		return UTracePf0(iF1,iSchema,ContextID(),Pc());

   395 		};

   396 

   397 	/**

   398 	Sends a trace containing 4 bytes of data.

   399 

   400 	@param aData1	4 bytes of data.

   401 

   402 	@return 		The trace was/was not logged.

   403 

   404 	@pre Classification information must be set up

   405 	*/

   406 	TBool Trace(TUint32 aData1)

   407 		{

   408 		if(iF2 > 0)

   409 			{

   410 			return UTraceSf1(iF1,iF2,iSchema,ContextID(),Pc(), aData1);

   411 			}

   412 		return UTracePf1(iF1,iSchema,ContextID(),Pc(), aData1);

   413 		};

   414 

   415 	/**

   416 	Sends a trace with 8 bytes of data.

   417 

   418 	@param aData1	4 bytes of data

   419 	@param aData2	4 bytes of data

   420 

   421 	@return 		The trace was/was not logged.

   422 

   423 	@pre Classification information must be set up

   424 	*/

   425 	TBool Trace(TUint32 aData1, TUint32 aData2)

   426 		{

   427 		if(iF2 > 0)

   428 			{

   429 			return UTraceSf2(iF1,iF2,iSchema,ContextID(),Pc(), aData1, aData2);

   430 			}

   431 		return UTracePf2(iF1,iSchema,ContextID(),Pc(),aData1,aData2);

   432 		};

   433 

   434 	/**

   435 	Sends a trace with 12 bytes of data.

   436 	Note: This method does not support secondary filtering.

   437 

   438 	@param aData1	4 bytes of data

   439 	@param aData2	4 bytes of data

   440 	@param aData3	4 bytes of data

   441 

   442 	@return 		The trace was/was not logged.

   443 

   444 	@pre Classification information must be set up

   445 	*/

   446 	TBool Trace(TUint32 aData1, TUint32 aData2,  TUint32 aData3)

   447 		{

   448 		if(iF2 > 0)

   449 			{

   450 			return EFalse;

   451 			}

   452 		return UTracePf3(iF1,iSchema,ContextID(),Pc(),aData1,aData2,aData3);

   453 		};

   454 

   455 	/**

   456 	Sends a trace with variable length data.

   457 

   458 	If the specified data is too big to fit into a single

   459 	trace record a multipart trace is generated.

   460 

   461 	@param aData	Address of addition data to add to trace.

   462 					Must be word aligned, i.e. a multiple of 4.

   463 	@param aSize	Number of bytes of additional data.

   464 

   465 	@return 		The trace was/was not logged.

   466 

   467 	@pre Classification information must be set up

   468 

   469 	@see BTrace::TMultipart

   470 	*/

   471 	TBool Trace(const TAny* aData, TInt aSize)

   472 		{

   473 		if(iF2 > 0)

   474 			{

   475 			return UTraceSfAny(iF1,iF2,iSchema,ContextID(),Pc(),aData,aSize);

   476 			}

   477 		return UTracePfAny(iF1,iSchema,ContextID(),Pc(),0,aData,aSize);

   478 		};

   479 

   480 

   481 	//Static methods

   482 	#ifdef __KERNEL_MODE__

   483 

   484 	/**

   485 	Prints a formatted string in kernel mode only.

   486 	The trace is classified by primary filter only.

   487 

   488 	The function uses Kern::AppendFormat() to do the formatting.

   489 

   490 	Although it is safe to call this function from an ISR, it polls the output

   491 	serial port and may take a long time to complete, invalidating any

   492 	real-time guarantee.

   493 

   494 	If called from an ISR, it is possible for output text to be intermingled

   495 	with other output text if one set of output interrupts or preempts another.

   496 

   497 	Some of the formatting options may not work inside an ISR.

   498 

   499 	Be careful not to use a string that is too long to fit onto the stack.

   500 	If the specified string is too long to fit into a single trace record

   501 	a multipart trace is generated.

   502 

   503 

   504 	@param aF1			Primary filter as classification information

   505 	@param aIncludeContextID Include context ID in the trace

   506 	@param aIncludePc	Include program counter in the trace

   507 	@param aFmt 		The format string. This must not be longer than 256 characters.

   508 	@param ...			A variable number of arguments to be converted to text as dictated

   509 						by the format string.

   510 

   511 	@return 			The trace was/was not logged.

   512 

   513 	@pre Calling thread can either be in a critical section or not.

   514 	@pre Interrupts must be enabled.

   515 	@pre Kernel must be unlocked

   516 	@pre Call in any context.

   517 	@pre Suitable for use in a device driver

   518 

   519 	@see Kern::AppendFormat()

   520 	@see BTrace::TMultipart

   521 	*/

   522 	static TBool PrintfPrimary(TPrimaryFilter aF1, TBool aIncludeContextID, TBool aIncludePc, const char* aFmt, ...)

   523 		{

   524 		TBuf8<KMaxPrintfSize> buf;

   525 		VA_LIST list;

   526 		VA_START(list,aFmt);

   527 		Kern::AppendFormat(buf,aFmt,list);

   528 		return UTracePfAny(aF1, KText, aIncludeContextID, aIncludePc, 0, buf.Ptr(),buf.Size());

   529 		}

   530 

   531 	#else //__KERNEL_MODE__

   532 

   533 	/**

   534 	Prints a formatted string. The trace is classified by primary filter only.

   535 

   536 	If the specified string is too long to fit into a single trace record

   537 	a multipart trace is generated.

   538 

   539 	@param aF1			Primary filter as classification information

   540 	@param aIncludeContextID Include context ID in the trace

   541 	@param aIncludePc	Include program counter in the trace

   542 	@param aFmt 		The format string. This must not be longer than 256 characters.

   543 	@param ...			A variable number of arguments to be converted to text as dictated

   544 						by the format string.

   545 

   546 	@return 			The trace was/was not logged.

   547 

   548 	@see BTrace::TMultipart

   549 	*/

   550     static TBool PrintfPrimary(TPrimaryFilter aF1, TBool aIncludeContextID, TBool aIncludePc, const char* aFmt, ...)

   551 		{

   552 		TTruncateOverflow8 overflow;

   553 		VA_LIST list;

   554 		VA_START(list,aFmt);

   555 		TPtrC8 fmt((const TText8*)aFmt);

   556 		TBuf8<KMaxPrintfSize> buf;

   557 		buf.AppendFormatList(fmt,list,&overflow);

   558 		return UTracePfAny(aF1, KText, aIncludeContextID, aIncludePc, 0, buf.PtrZ(),buf.Size());

   559 		};

   560 

   561 	/**

   562 	Prints a formatted string. The trace is classified by primary filter only.

   563 

   564 	If the specified string is too long to fit into a single trace record

   565 	a multipart trace is generated.

   566 

   567 	@param aF1			Primary filter as classification information

   568 	@param aIncludeContextID Include context ID in the trace

   569 	@param aIncludePc	Include program counter in the trace

   570 	@param aFmt 		The format string. This must not be longer than 256 characters.

   571 	@param ...			A variable number of arguments to be converted to text as dictated

   572 						by the format string.

   573 

   574 	@return 			The trace was/was not logged.

   575 

   576 	@see BTrace::TMultipart

   577 	*/

   578     static TBool PrintfPrimary(TPrimaryFilter aF1, TBool aIncludeContextID, TBool aIncludePc, TRefByValue<const TDesC16> aFmt,...)

   579     	{

   580 	    TTruncateOverflow16 overflow;

   581 		VA_LIST list;

   582 		VA_START(list,aFmt);

   583 		TBuf<KMaxPrintfSize> buf;

   584 		buf.AppendFormatList(aFmt,list,&overflow);

   585 		#ifdef _UNICODE

   586 		TPtr8 p(buf.Collapse());

   587 		return UTracePfAny(aF1, KText, aIncludeContextID, aIncludePc, 0, buf.PtrZ(), p.Size());

   588 		#else

   589 		return UTracePfAny(aF1, KText, aIncludeContextID, aIncludePc, 0, buf.PtrZ(), buf.Size());

   590 		#endif //_UNICODE

   591     	};

   592 

   593 	/**

   594 	Prints a string. The trace is classified by primary filter only.

   595 

   596 	If the specified string is too long to fit into a single trace record

   597 	a multipart trace is generated.

   598 

   599 	@param aF1			Primary filter as classification information

   600 	@param aIncludeContextID Include context ID in the trace

   601 	@param aIncludePc	Include program counter in the trace

   602 	@param aDes			The string. This can be of variable length.

   603 

   604 	@return 			The trace was/was not logged.

   605 

   606 	@see BTrace::TMultipart

   607 	*/

   608     static TBool PrintfPrimary(TPrimaryFilter aF1, TBool aIncludeContextID, TBool aIncludePc, const TDesC8& aDes)

   609     	{

   610 		return UTracePfAny(aF1, KText, aIncludeContextID, aIncludePc,0, aDes.Ptr(), aDes.Size());

   611 		};

   612 

   613 	/**

   614 	Prints a string. The trace is classified by primary filter only.

   615 

   616 

   617 	If the specified string is too long to fit into a single trace record

   618 	a multipart trace is generated.

   619 

   620 	@param aF1			Primary filter as classification information

   621 	@param aIncludeContextID Include context ID in the trace

   622 	@param aIncludePc	Include program counter in the trace

   623 	@param aDes			The string. This can be of variable length.

   624 

   625 	@return 			The trace was/was not logged.

   626 

   627 	@see BTrace::TMultipart

   628 	*/

   629     static TBool PrintfPrimary(TPrimaryFilter aF1, TBool aIncludeContextID, TBool aIncludePc, const TDesC16& aDes)

   630     	{

   631     	TUTrace trace(aF1,KText,aIncludeContextID,aIncludePc);

   632     	return trace.Printf(aDes);

   633     	};

   634 

   635 	/**

   636 	Prints a formatted string. The trace is classified by primary and secondary filter.

   637 

   638 

   639 	If the specified string is too long to fit into a single trace record

   640 	a multipart trace is generated.

   641 

   642 	@param aF1			Primary filter as classification information

   643 	@param aF2			Secondary filter as classification information

   644 	@param aIncludeContextID Include context ID in the trace

   645 	@param aIncludePc	Include program counter in the trace

   646 	@param aFmt 		The format string. This must not be longer than 256 characters.

   647 	@param ...			A variable number of arguments to be converted to text as dictated

   648 						by the format string.

   649 

   650 	@return 			The trace was/was not logged.

   651 

   652 	@see BTrace::TMultipart

   653 	*/

   654     static TBool Printf(TPrimaryFilter aF1, TSecondaryFilter aF2, TBool aIncludeContextID, TBool aIncludePc, const char* aFmt, ...)

   655 		{

   656 		TTruncateOverflow8 overflow;

   657 		VA_LIST list;

   658 		VA_START(list,aFmt);

   659 		TPtrC8 fmt((const TText8*)aFmt);

   660 		TBuf8<KMaxPrintfSize> buf;

   661 		buf.AppendFormatList(fmt,list,&overflow);

   662 		return UTraceSfAny(aF1, aF2, KText, aIncludeContextID, aIncludePc, buf.PtrZ(),buf.Size());

   663 		};

   664 

   665 	/**

   666 	Prints a formatted string. The trace is classified by primary and secondary filter.

   667 

   668 	If the specified string is too long to fit into a single trace record

   669 	a multipart trace is generated.

   670 

   671 	@param aF1			Primary filter as classification information

   672 	@param aF2			Secondary filter as classification information

   673 	@param aIncludeContextID Include context ID in the trace

   674 	@param aIncludePc	Include program counter in the trace

   675 	@param aFmt 		The format string. This must not be longer than 256 characters.

   676 	@param ...			A variable number of arguments to be converted to text as dictated

   677 						by the format string.

   678 

   679 	@return 			The trace was/was not logged.

   680 

   681 	@see BTrace::TMultipart

   682 	*/

   683     static TBool Printf(TPrimaryFilter aF1, TSecondaryFilter aF2, TBool aIncludeContextID, TBool aIncludePc, TRefByValue<const TDesC16> aFmt,...)

   684     	{

   685 	    TTruncateOverflow16 overflow;

   686 		VA_LIST list;

   687 		VA_START(list,aFmt);

   688 		TBuf<KMaxPrintfSize> buf;

   689 		buf.AppendFormatList(aFmt,list,&overflow);

   690 		#ifdef _UNICODE

   691 		TPtr8 p(buf.Collapse());

   692 		return UTraceSfAny(aF1, aF2, KText, aIncludeContextID, aIncludePc, buf.PtrZ(), p.Size());

   693 		#else

   694 		return UTraceSfAny(aF1, aF2, KText, aIncludeContextID, aIncludePc, buf.PtrZ(), buf.Size());

   695 		#endif //_UNICODE

   696     	};

   697 

   698 	/**

   699 	Prints a string. The trace is classified by primary and secondary filter.

   700 

   701 	If the specified string is too long to fit into a single trace record

   702 	a multipart trace is generated.

   703 

   704 	@param aF1			Primary filter as classification information

   705 	@param aF2			Secondary filter as classification information

   706 	@param aIncludeContextID Include context ID in the trace

   707 	@param aIncludePc	Include program counter in the trace

   708 	@param aDes			The string. This can be of variable length.

   709 

   710 	@return 			The trace was/was not logged.

   711 

   712 	@see BTrace::TMultipart

   713 	*/

   714     static TBool Printf(TPrimaryFilter aF1, TSecondaryFilter aF2, TBool aIncludeContextID, TBool aIncludePc, const TDesC8& aDes)

   715     	{

   716 		return UTraceSfAny(aF1,  aF2, KText,aIncludeContextID, aIncludePc, aDes.Ptr(), aDes.Size());

   717 		};

   718 

   719 	/**

   720 	Prints a string. The trace is classified by primary and secondary filter.

   721 

   722 	If the specified string is too long to fit into a single trace record

   723 	a multipart trace is generated.

   724 

   725 	@param aF1			Primary filter as classification information

   726 	@param aF2			Secondary filter as classification information

   727 	@param aIncludeContextID Include context ID in the trace

   728 	@param aIncludePc	Include program counter in the trace

   729 	@param aDes			The string. This can be of variable length.

   730 

   731 	@return 			The trace was/was not logged.

   732 

   733 	@see BTrace::TMultipart

   734 	*/

   735     static TBool Printf(TPrimaryFilter aF1, TSecondaryFilter aF2, TBool aIncludeContextID, TBool aIncludePc, const TDesC16& aDes)

   736     	{

   737     	TUTrace trace(aF1,aF2,KText,aIncludeContextID,aIncludePc);

   738     	return trace.Printf(aDes);

   739     	};

   740 

   741 	#endif //__KERNEL_MODE_

   742 

   743 	/**

   744 	Sends a trace with no payload. The trace is classified

   745 	by primary filter only.

   746 

   747 	@param aF1			Primary filter as classification information

   748 	@param aSchema		The schema used to determine the format of the content

   749 	@param aIncludeContextID Include context ID in the trace

   750 	@param aIncludePc	Include program counter in the trace

   751 

   752 	@return 		The trace was/was not logged.

   753 	*/

   754 	static TBool TracePrimary(TPrimaryFilter aF1, TTraceSchema aSchema, TBool aIncludeContextID, TBool aIncludePc)

   755 		{

   756 		return UTracePf0(aF1, aSchema, aIncludeContextID, aIncludePc);

   757 		}

   758 

   759 	/**

   760 	Sends a trace with 4 bytes of data. The trace is classified

   761 	by primary filter only.

   762 

   763 	@param aF1			Primary filter as classification information

   764 	@param aSchema		The schema used to determine the format of the content

   765 	@param aIncludeContextID Include context ID in the trace

   766 	@param aIncludePc	Include program counter in the trace

   767 	@param aData1		4 bytes of data

   768 

   769 	@return 		The trace was/was not logged.

   770 	*/

   771 	static TBool TracePrimary(TPrimaryFilter aF1, TTraceSchema aSchema, TBool aIncludeContextID, TBool aIncludePc, TUint32 aData1)

   772 		{

   773 		return UTracePf1(aF1, aSchema, aIncludeContextID, aIncludePc, aData1);

   774 		}

   775 

   776 	/**

   777 	Sends a trace with 8 bytes of data. The trace is classified

   778 	by primary filter only.

   779 

   780 	@param aF1			Primary filter as classification information

   781 	@param aSchema		The schema used to determine the format of the content

   782 	@param aIncludeContextID Include context ID in the trace

   783 	@param aIncludePc	Include program counter in the trace

   784 	@param aData1		4 bytes of data

   785 	@param aData2		4 bytes of data

   786 

   787 	@return 		The trace was/was not logged.

   788 	*/

   789 	static TBool TracePrimary(TPrimaryFilter aF1, TTraceSchema aSchema, TBool aIncludeContextID, TBool aIncludePc, TUint32 aData1, TUint32 aData2)

   790 		{

   791 		return UTracePf2(aF1, aSchema, aIncludeContextID, aIncludePc,aData1,aData2);

   792 		}

   793 

   794 	/**

   795 	Sends a trace with 12 bytes of data. The trace is classified

   796 	by primary filter only.

   797 

   798 	@param aF1			Primary filter as classification information

   799 	@param aSchema		The schema used to determine the format of the content

   800 	@param aIncludeContextID Include context ID in the trace

   801 	@param aIncludePc	Include program counter in the trace

   802 	@param aData1		4 bytes of data

   803 	@param aData2		4 bytes of data

   804 	@param aData3		4 bytes of data

   805 

   806 	@return 		The trace was/was not logged.

   807 	*/

   808 	static TBool TracePrimary(TPrimaryFilter aF1, TTraceSchema aSchema, TBool aIncludeContextID, TBool aIncludePc, TUint32 aData1, TUint32 aData2, TUint aData3)

   809 		{

   810 		return UTracePf3(aF1, aSchema, aIncludeContextID, aIncludePc,aData1,aData2,aData3);

   811 		}

   812 

   813 	/**

   814 	Sends a trace with variable length data. The trace is classified

   815 	by primary filter only.

   816 

   817 	If the specified data is too big to fit into a single

   818 	trace record a multipart trace is generated.

   819 

   820 	@param aF1		Primary filter as classification information

   821 	@param aSchema	The schema used to determine the format of the content

   822 	@param aIncludeContextID Include context ID in the trace

   823 	@param aIncludePc	Include program counter in the trace

   824 	@param aData	Address of addition data to add to trace.

   825 					Must be word aligned, i.e. a multiple of 4.

   826 	@param aSize	Number of bytes of additional data.

   827 

   828 	@return 		The trace was/was not logged.

   829 

   830 	@see BTrace::TMultipart

   831 	*/

   832 	static TBool TracePrimary(TPrimaryFilter aF1, TTraceSchema aSchema, TBool aIncludeContextID, TBool aIncludePc, const TAny* aData, TInt aSize)

   833 		{

   834 		return UTracePfAny(aF1, aSchema, aIncludeContextID, aIncludePc, 0, aData, aSize);

   835 		}

   836 

   837 	/**

   838 	Sends a trace with no payload. The trace is classified

   839 	by primary and secondary filter.

   840 

   841 	@param aF1			Primary filter as classification information

   842 	@param aF2			Secondary filter as classification information

   843 	@param aSchema		The schema used to determine the format of the content

   844 	@param aIncludeContextID Include context ID in the trace

   845 	@param aIncludePc	Include program counter in the trace

   846 

   847 	@return 		The trace was/was not logged.

   848 	*/

   849 	static TBool Trace(TPrimaryFilter aF1, TSecondaryFilter aF2, TTraceSchema aSchema, TBool aIncludeContextID, TBool aIncludePc)

   850 		{

   851 		return UTraceSf0(aF1, aF2, aSchema, aIncludeContextID, aIncludePc);

   852 		}

   853 

   854 	/**

   855 	Sends a trace with 4 bytes of data. The trace is classified

   856 	by primary and secondary filter.

   857 

   858 	@param aF1			Primary filter as classification information

   859 	@param aF2			Secondary filter as classification information

   860 	@param aSchema		The schema used to determine the format of the content

   861 	@param aIncludeContextID Include context ID in the trace

   862 	@param aIncludePc	Include program counter in the trace

   863 	@param aData1		4 bytes of data

   864 

   865 	@return 		The trace was/was not logged.

   866 	*/

   867 	static TBool Trace(TPrimaryFilter aF1, TSecondaryFilter aF2, TTraceSchema aSchema, TBool aIncludeContextID, TBool aIncludePc, TUint32 aData1)

   868 		{

   869 		return UTraceSf1(aF1, aF2, aSchema , aIncludeContextID, aIncludePc, aData1);

   870 		}

   871 

   872 	/**

   873 	Sends a trace with 8 bytes of data. The trace is classified

   874 	by primary and secondary filter.

   875 

   876 	@param aF1			Primary filter as classification information

   877 	@param aF2			Secondary filter as classification information

   878 	@param aSchema		The schema used to determine the format of the content

   879 	@param aIncludeContextID Include context ID in the trace

   880 	@param aIncludePc	Include program counter in the trace

   881 	@param aData1		4 bytes of data

   882 	@param aData2		4 bytes of data

   883 

   884 	@return 		The trace was/was not logged.

   885 	*/

   886 	static TBool Trace(TPrimaryFilter aF1, TSecondaryFilter aF2, TTraceSchema aSchema, TBool aIncludeContextID, TBool aIncludePc, TUint32 aData1, TUint32 aData2)

   887 		{

   888 		return UTraceSf2(aF1, aF2, aSchema , aIncludeContextID, aIncludePc,aData1,aData2);

   889 		}

   890 

   891 	/**

   892 	Sends a trace with variable length data. The trace is classified

   893 	by primary and secondary filter.

   894 

   895 	If the specified data is too big to fit into a single

   896 	trace record a multipart trace is generated.

   897 

   898 	@param aF1			Primary filter as classification information

   899 	@param aF2			Secondary filter as classification information

   900 	@param aSchema		The schema used to determine the format of the content

   901 	@param aIncludeContextID Include context ID in the trace

   902 	@param aIncludePc	Include program counter in the trace

   903 	@param aData		Address of addition data to add to trace.

   904 						Must be word aligned, i.e. a multiple of 4.

   905 	@param aSize		Number of bytes of additional data.

   906 

   907 	@return 			The trace was/was not logged.

   908 

   909 	@see BTrace::TMultipart

   910 	*/

   911 	static TBool Trace(TPrimaryFilter aF1, TSecondaryFilter aF2, TTraceSchema aSchema, TBool aIncludeContextID, TBool aIncludePc, const TAny* aData, TInt aSize)

   912 		{

   913 		return UTraceSfAny(aF1, aF2, aSchema, aIncludeContextID, aIncludePc, aData, aSize);

   914 		}

   915 

   916 private:

   917 

   918 	// See/Update comments below

   919 	TUTrace(){};

   920 

   921 	/**

   922 	@internalComponent

   923 	*/

   924 	enum TTraceInfoPresent

   925 		{

   926 		EContext = 0,

   927 		EPc = 1

   928 		};

   929 

   930 	/**

   931 	Dummy class to toss away overflow

   932 	@internalComponent

   933 	*/

   934 	#ifndef __KERNEL_MODE__

   935 	class TTruncateOverflow16 : public TDes16Overflow

   936 		{

   937 		public:

   938 		virtual void Overflow(TDes&) {};

   939 		};

   940 	/**

   941 	Dummy class to toss away overflow

   942 	@internalComponent

   943 	*/

   944 	class TTruncateOverflow8 : public TDes8Overflow

   945 		{

   946 		public:

   947 		virtual void Overflow(TDes8&) {};

   948 		};

   949 	#endif  //__KERNEL_MODE__

   950 

   951 	/**

   952 	@internalComponent

   953 	*/

   954 	TBool ContextID()

   955 		{

   956 			return iPresent&1;

   957 		};

   958 

   959 	/**

   960 	@internalComponent

   961 	*/

   962 	TBool Pc()

   963 		{

   964 			return (iPresent&2)>>EPc;

   965 		};

   966 

   967 private:

   968 	TPrimaryFilter iF1;

   969 	TTraceSchema iSchema;

   970 	TSecondaryFilter iF2;

   971 	TInt8 iPresent;

   972 

   973 	TUint32 iReserved1;

   974 	TUint32 iReserved2;

   975 };

   976 

   977 #else //SYMBIAN_TRACE_ENABLE

   978 

   979 

   980 class TUTrace

   981 {

   982 public:

   983 	/**

   984 	Construct a trace object with classification for

   985 	primary filter only.

   986 

   987 	@param aF1 Primary filter as classification information

   988 	@param aSchema The schema used to determine the format of the content

   989 	@param aIncludeContextID Include context ID in the trace

   990 	@param aIncludePc Include program counter in the trace

   991 	*/

   992 	TUTrace(TPrimaryFilter /*aF1*/, TTraceSchema /*aSchema*/, TBool /*aIncludeContextID*/, TBool /*aIncludePc*/){};

   993 

   994 	/**

   995 	Construct a trace object with classification for both

   996 	primary and secondary filters.

   997 

   998 	@param aF1 Primary filter as classification information

   999 	@param aF2 Secondary filter as classification information

  1000 	@param aSchema The schema used to determine the format of the content

  1001 	@param aIncludeContextID Include context ID in the trace

  1002 	@param aIncludePc Include program counter in the trace

  1003 	*/

  1004 	TUTrace(TPrimaryFilter /*aF1*/, TSecondaryFilter /*aF2*/, TTraceSchema /*aSchema*/, TBool /*aIncludeContextID*/, TBool /*aIncludePc*/){};

  1005 

  1006 	/**

  1007 	Set the classification and additional information.

  1008 

  1009 	@param aF1 Primary filter as classification information

  1010 	@param aSchema The schema used to determine the format of the content

  1011 	@param aIncludeContextID Include context ID in the trace

  1012 	@param aIncludePc Include program counter in the trace

  1013 	*/

  1014 	void Set(TPrimaryFilter /*aF1*/, TTraceSchema /*aSchema*/, TBool /*aIncludeContextID*/, TBool /*aIncludePc*/){};

  1015 

  1016 	/**

  1017 	Set the classification and additional information.

  1018 

  1019 	@param aF1 Primary filter as classification information

  1020 	@param aF2 Secondary filter as classification information

  1021 	@param aSchema The schema used to determine the format of the content

  1022 	@param aIncludeContextID Include context ID in the trace

  1023 	@param aIncludePc Include program counter in the trace

  1024 	*/

  1025 	void Set(TPrimaryFilter /*aF1*/, TSecondaryFilter /*aF2*/, TTraceSchema /*aSchema*/, TBool /*aIncludeContextID*/, TBool /*aIncludePc*/){};

  1026 	#ifdef  __KERNEL_MODE__

  1027 

  1028 	/**

  1029 	Prints a formatted string in kernel mode only.

  1030 

  1031 	The function uses Kern::AppendFormat() to do the formatting.

  1032 

  1033 	Although it is safe to call this function from an ISR, it polls the output

  1034 	serial port and may take a long time to complete, invalidating any

  1035 	real-time guarantee.

  1036 

  1037 	If called from an ISR, it is possible for output text to be intermingled

  1038 	with other output text if one set of output interrupts or preempts another.

  1039 

  1040 	Some of the formatting options may not work inside an ISR.

  1041 

  1042 	Be careful not to use a string that is too long to fit onto the stack.

  1043 	If the specified string is too big to fit into a single	trace

  1044 	a multipart trace is generated.

  1045 

  1046 	@param aFmt The format string. This must not be longer than 256 characters.

  1047 	@param ...	A variable number of arguments to be converted to text as dictated

  1048 				by the format string.

  1049 

  1050 	@return The trace was/was not logged.

  1051 

  1052 	@pre Calling thread can either be in a critical section or not.

  1053 	@pre Interrupts must be enabled.

  1054 	@pre Kernel must be unlocked

  1055 	@pre Call in any context.

  1056 	@pre Suitable for use in a device driver

  1057 	@pre Classification information must be set up

  1058 

  1059 	@see Kern::AppendFormat()

  1060 	@See BTrace::TMultipart

  1061 	*/

  1062 	TBool Printf(const char* /*aFmt*/, ...)

  1063 		{

  1064 		return EFalse;

  1065 		}

  1066 

  1067 	#else //__KERNEL_MODE__

  1068 

  1069 	/**

  1070 	Prints a formatted string.

  1071 

  1072 	@param aFmt The format string. This must not be longer than 256 characters.

  1073 	@param ...	A variable number of arguments to be converted to text as dictated

  1074 				by the format string.

  1075 

  1076 	@return The trace was/was not logged.

  1077 

  1078 	@pre Classification information must be set up

  1079 	*/

  1080 	TBool Printf(const char* /*aFmt*/, ...)

  1081 		{

  1082 		return EFalse;

  1083 		};

  1084 

  1085 	/**

  1086 	Prints a formatted string.

  1087 

  1088 	@param aFmt The format string. This must not be longer than 256 characters.

  1089 	@param ...	A variable number of arguments to be converted to text as dictated

  1090 				by the format string.

  1091 

  1092 	@return The trace was/was not logged.

  1093 

  1094 	@pre Classification information must be set up

  1095 	*/

  1096 	TBool Printf(TRefByValue<const TDesC16> /*aFmt*/,...)

  1097 	    {

  1098 		return EFalse;

  1099 	    };

  1100 

  1101 	/**

  1102 	Prints a string.

  1103 

  1104 	@param aDes The string. This can be of variable length.

  1105 

  1106 	@return The trace was/was not logged.

  1107 

  1108 	@pre Classification information must be set up

  1109 	*/

  1110 	TBool Printf(const TDesC8& /*aDes*/)

  1111 		{

  1112 		return EFalse;

  1113 		};

  1114 

  1115 	/**

  1116 	Prints a string.

  1117 

  1118 	@param aDes The string. This can be of variable length.

  1119 

  1120 	@return The trace was/was not logged.

  1121 

  1122 	@pre Classification information must be set up

  1123 	*/

  1124 	TBool Printf(const TDesC16& /*aDes*/)

  1125 	    {

  1126 		return EFalse;

  1127 		};

  1128 

  1129 	#endif // __KERNEL_MODE__

  1130 

  1131 	/**

  1132 	Sends a trace with no payload data.

  1133 

  1134 	@return The trace was/was not logged.