// Copyright (c) 2005-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:

// e32\include\e32btrace.h

// 

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

//

#ifndef E32BTRACE_H

#define E32BTRACE_H

#ifdef __KERNEL_MODE__

class TSpinLock;

#endif

/**

Class for handling fast tracing.

A trace record consists of three parts: a header, header extensions,

and the trace data itself.

The header consists of four bytes containing:

-#	Size of the record in bytes. (Maximum value is KMaxBTraceRecordSize.)

-#	Flags. See enum TFlags.

-#	Category. Category value from enum BTrace::TCategory.

-#	Sub-category. The meaning of this is dependent on the value of Category.

When trace records are stored in memory they are stored word (32 bit) aligned.

Therefore the size must be rounded up to a multiple of four when calculating

the address of the next record. E.g.

@code

	TUint8* record; // pointer to trace record

	TInt size = record[BTrace::ESizeIndex];

	record += (size+3)&~3; // move record pointer on to next record.

@endcode

The NextRecord() method is provided to do this operation.

Following the header are optionally a number of 32 bit 'header extension' values.

These are present in the order shown below but only exist if the appropriate flag bit

is set in the Header.

-#	Header2.		Contains flag values from enum Flags2.

					This value is only present if the EHeader2Present flag is set.

-#	Timestamp.		A timestamp value indicating when the trace was generated.

					The format and resolution of this value are platform-dependent, but

					typically will contain the same values as would be returned by

					User::FastCounter() or NKern::FastCounter().

					This value is only present if the ETimestampPresent flag is set.

-#	Timestamp2. 	Additional timestamp information. E.g. the most significant

					half of a 64bit timestamp value. Note, it is valid for a Timestamp2 value

					to be present even if the previous Timestamp is absent.

					This value is only present if the ETimestamp2Present flag is set.

-#	Context ID. 	This value indicates the context in which the trace was generated.

					The meaning of the id is dependent on the contents of the two

					least significant bits:

					-	00	indicates the value is the address of the NThread object for

							the currently executing thread.

					-	01	indicates Fast Interrupt (FIQ) context.

							Other bits of the value are currently reserved for future use.

					-	10	indicates Interrupt (IRQ) context. Other bits of the value

							are currently reserved for future use.

					-	11	indicates Immediate Delayed Function Call (IDFC) context.

							Other bits of the value are currently reserved for future use.

					.

					This value is only present if the EContextIdPresent flag is set.

-#	Program Counter. This is the memory address of the instruction after the location

					the trace was output.

					This value is only present if the EPcPresent flag is set.

-#	Extra.			An extra value used for different purposes depending on the trace type.

					This value is only present if the EExtraPresent flag is set.

Following the header extensions are 0 or more bytes of trace data specified when the trace

was output.

To output a trace, the following macros can be used:

- BTrace0

- BTrace4

- BTrace8

- BTrace12

- BTraceN

- BTraceBig

- BTracePc0

- BTracePc4

- BTracePc8

- BTracePc12

- BTracePcN

- BTracePcBig

- BTraceContext0

- BTraceContext4

- BTraceContext8

- BTraceContext12

- BTraceContextN

- BTraceContextBig

- BTraceContextPc0

- BTraceContextPc4

- BTraceContextPc8

- BTraceContextPc12

- BTraceContextPcN

- BTraceContextPcBig

Whenever a trace is output, the trace handler is called with the arguments specified.

See typedef THandler and SetHandler().

Each tracing category has a filter bit, which if set to zero means that traces in that category

are discarded, see SetFilter(). This filtering is performed before the trace handler is

called. This filter may also be initialised from boot time by using the 'btrace' keyword in

an OBY file used to build a ROM image.

Traces may also be additionally sent through a second level of filtering. This examines the

first 32 bits of data in the trace and if this value isn't present in the list maintained

in the secondary filter, the trace is discarded. The contents of the secondary filter are

set using the SetFilter2 methods.

Values used for secondary filtering must be Symbian Unique Identifiers (UIDs) allocated

using the normal UID allocation process. Note, the following non-valid UID value ranges

are reserved.

- 0x00000000..0x007fffff	Reserved for platform specific use.

- 0x00800000..0x00ffffff	Reserved for use by Symbian.

To generate traces which are to be processed by the secondary filter, the following

macros can be used:

- BTraceFiltered4

- BTraceFiltered8

- BTraceFiltered12

- BTraceFilteredN

- BTraceFilteredBig

- BTraceFilteredPc4

- BTraceFilteredPc8

- BTraceFilteredPc12

- BTraceFilteredPcN

- BTraceFilteredPcBig

- BTraceFilteredContext4

- BTraceFilteredContext8

- BTraceFilteredContext12

- BTraceFilteredContextN

- BTraceFilteredContextBig

- BTraceFilteredContextPc4

- BTraceFilteredContextPc8

- BTraceFilteredContextPc12

- BTraceFilteredContextPcN

- BTraceFilteredContextPcBig

Traces generated using the above methods will be filtered twice; once using the primary

filter which checks the trace's category, and once using the secondary filter which checks

the 32 bit UID value at the start of the trace data. Therefore the trace must pass both filter

checks for it to be sent to the trace handler for output.

@publishedPartner

@released

*/

class BTrace

	{

public:

	/**

	Byte indices into the trace header for specific fields.

	*/

	enum THeaderStructure

		{

		/**

		Size of record in bytes.

		*/

		ESizeIndex = 0,

		/**

		Bitfield of flags from enum TFlags. E.g. to detect if a timestamp is present in

		the record, code like this could be used.

		@code

			TUint8* record; // pointer to trace record

			if(record[BTrace::EFlagsIndex]&BTrace::ETimestampPresent)

				TimestampPresent();

			else

				TimestampNotPresent();

		@endcode

		*/

		EFlagsIndex = 1,

		/**

		Category value from enum BTrace::TCategory.

		*/

		ECategoryIndex = 2,

		/**

		Sub-category value. The meaning of this is dependent on the Category.

		*/

		ESubCategoryIndex = 3,

		};

	/**

	Bit flags which indicate state of a trace record.

	*/

	enum TFlags

		{

		/**

		Header2 is present in the trace record.

		*/

		EHeader2Present 	= 1<<0,

		/**

		A timestamp value is present in the trace record.

		*/

		ETimestampPresent	= 1<<1,

		/**

		A second timestamp value is present in the trace record.

		*/

		ETimestamp2Present	= 1<<2,

		/**

		A context ID is present in the trace record.

		*/

		EContextIdPresent	= 1<<3,

		/**

		A CPU program counter (PC) value is present in the trace record.

		*/

		EPcPresent			= 1<<4,

		/**

		An 'extra' value is present in the trace record.

		*/

		EExtraPresent		= 1<<5,

		/**

		Indicates that the data in this trace record was truncated to keep the size

		within the maximum permissible.

		*/

		ERecordTruncated	= 1<<6,

		/**

		Indicates that trace record(s) before this one are missing.

		This can happen if the trace buffer was full when a trace output was attempted.

		*/

		EMissingRecord		= 1<<7

		};

	/**

	Bit flags present in the Flags2 value of the header extension.

	*/

	enum TFlags2

		{

		/**

		Masks out the bits for the multipart trace type. (See enum TMultiPart.)

		*/

		EMultipartFlagMask		= 3<<0,

		/**

		Masks out the bits for the CPU ID for SMP systems (zero if present on non SMP systems)

		*/

		};

	/**

	Values for multipart trace indicator. These values are stored in Flags2 an

	are obtained by ANDing with the value EMultipartFlagMask.

	If a 'Big' trace is generated which doesn't fit into a single trace record

	then its data is split into several separate trace records; a multipart trace.

	In multipart traces the 'extra' trace value is present in the header extension.

	(EExtraPresent is set.) This extra value contains a unique trace identifier

	which is the same is all parts of the trace.

	The structure of the data part of each trace record in a multipart trace is described

	below. In this description, the following labels are used.

	-	A is the initial 4 bytes of data; the a1 argument of BTraceBig.

	-	D is the array of bytes of additional data; the aData argument of BTraceBig.

	-	N is the size of D; the aDataSize argument of BTraceBig

	-	X is the maximum number of additional bytes which will fit into a trace record.

		This is usually KMaxBTraceDataArray but this should not be assumed, instead

		the size and other information present in each trace record should be examined.

	For the first part of a multipart trace, the data in a trace record has the following

	structure:

	-	4 bytes containing N.

	-	4 bytes containing A.

	-	X bytes containing D[0..X-1]

	If the parts are numbered 0 through to 'j', then a middle part of a multipart trace

	is numbered 'i' where 0<i<j. The data in these parts has the structure:

	-	4 bytes containing N.

	-	4 bytes containing X*i. I.e. the offset within D for the data in this trace record.

	-	X bytes containing D[X*i..X*i+X-1]

	For the last part of a multipart trace, the data has the structure:

	-	4 bytes containing N.

	-	4 bytes containing X*j. I.e. the offset within D for the data in this trace record.

	-	N modulo X bytes containing D[X*j..N-1]. I.e. the final bytes of the trace data.

	*/

	enum TMultiPart

		{

		/**

		Indicates that this trace is the first part of a multipart trace.

		*/

		EMultipartFirst 		= 1,

		/**

		Indicates that this trace is a middle part of a multipart trace.

		I.e. it is not the first or last part.

		*/

		EMultipartMiddle		= 2,

		/**

		Indicates that this trace is the last part of a multipart trace.

		*/

		EMultipartLast			= 3,

		};

	/**

	Enumeration of trace categories.

	*/

	enum TCategory

		{

		/**

		Trace generated by all calls to RDebug::Printf.

		The first 4 bytes of trace data contain the thread ID, RThread::Id(), for the

		thread which caused this trace to be emitted. If the trace wasn't generated in

		thread context, this id has the value KNullThreadId.

		Subsequent bytes of data contain the ASCII text for the formatted string

		generated by Kern::Printf.

		These traces also contain a context ID, i.e. the EContextIdPresent flag is

		set and a context ID value is present in the extended header.

		If the trace text doesn't fit completely into one trace record, then

		a multipart trace is generated. See enum TMultiPart.

		*/

		ERDebugPrintf = 0,

		/**

		Trace generated by all calls to Kern::Printf.

		Trace records in this category have the same structure as ERDebugPrintf.

		*/

		EKernPrintf = 1,

		/**

		Trace generated by platform security diagnostic messages.

		Trace records in this category have the same structure as ERDebugPrintf.

		*/

		EPlatsecPrintf = 2,

		/**

		Trace generated for the purpose of associating thread context ids with

		the textual names of threads. These traces are usually generated when a

		thread is created, renamed or destroyed.

		If #Prime is called with this category, traces will be generated for all

		threads currently extant.

		@see enum TThreadIdentification

		*/

		EThreadIdentification = 3,

		/**

		Trace generated when the CPU usage changes state, e.g. at thread context switch

		or during interrupt and DFC processing.

		The purpose of this trace category is to profile CPU usage.

		@see enum TCpuUsage

		*/

		ECpuUsage = 4,

		/**

		Category used for profiling device drivers, kernel extensions etc.

		Used by PERF_LOG macro.

		@prototype 9.3

		*/

		EKernPerfLog = 5,

		/**

		Trace generated when client-server activity takes place such as server creation,

		session management, message handling, etc.

		If #Prime is called with this category, traces will be generated for all

		servers currently running and their sessions.

		*/

		EClientServer = 6,

		/**

		Trace generated on thread request completion.

		*/

		ERequests = 7,

		/**

		Trace generated when chunks are created and destroyed, and when memory

		is committed and decommitted to and from chunks.

		If #Prime is called with this category, traces will be generated for all

		chunks currently extant.

		@see TChunks

		*/

		EChunks = 8,

		/**

		Trace generated when code segments are created and destroyed, mapped

		into out of processes, and when memory is committed and decommitted to

		and from them.

		If #Prime is called with this category, traces will be generated for all

		code segments currently extant.

		@see TCodeSegs

		*/

		ECodeSegs = 9,

		/**

		Trace generated by Demand Paging.

		@prototype 9.3

		*/

		EPaging = 10,

		/**

		Trace generated when thread and process priorities are modified, whether

		directly or through priority inheritance, aging or other mechanisms used

		by the kernel.

		The purpose of this category is to enable system-wide study of thread

		priority usage.

		If #Prime is called with this category, traces will be generated for all

		threads currently extant.

		@see enum TThreadPriority

		@internalTechnology

		@prototype 9.3

		*/

		EThreadPriority = 11,

		/**

		Trace generated by processing Paging requests in the Media subsystem and Media drivers.

		@prototype 9.3

		*/

		EPagingMedia = 12,

		/**

		Trace generated by the kernel for memory regions which don't belong to any chunk.

		@see enum TKernelMemory

		@prototype 9.4

		*/

		EKernelMemory = 13,

		/**

		Trace generated by user-mode heap usage.

		Unlike other trace categories, capturing heap trace involves an additional step

		depending on how much trace is required. To enable heap trace for a single process

		from the moment it starts, add the following line to the .exe's project (.mmp) file:

			firstlib eexe_instrumented_heap.lib

		This overrides the build tools default implicit link (for .exe projects) against eexe.lib.

		Alternatively, to enable heap trace for all processes at once you can enable the

		KUSERHEAPTRACE bit (#96) of the kernel trace flags. You can set this flag either at

		ROM-building time (look for the 'kerneltrace' line generally in \epoc32\rom\<platform>\header.iby)

		or at runtime by running the following at the Eshell command prompt:

			trace 0 0 1

		Note that changing this flag at runtime only affects processes created after the flag

		is set or unset. It will not affect running processes.

		@see enum THeap

		@prototype 9.4

		*/

		EHeap = 14,

		/**

		Meta trace. Trace that is only useful to programs which use or display BTrace-based data.

		@see enum TMetaTrace

		@prototype 9.4

		*/

		EMetaTrace = 15,

		/**

		Trace generated by the ram allocator to allow the physical layout of RAM

		to be tracked.

		@internalTechnology

		*/

		ERamAllocator = 16,

		/**

		Trace generated by the Fast Mutex in the Nkern.

		*/

		EFastMutex = 17,

		/**

		Trace generated by any sampling profiler.

		@see enum TProfiling

		*/

		EProfiling = 18,

		/**

		Trace generated by Power Resource Manager.

		@prototype 9.5

		*/

		EResourceManager = 19,

		/**

		Trace generated by Power Resource Manager User-Side API.

		@prototype 9.5

		*/