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 the License "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 // e32\include\e32btrace.h

    15 // 

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

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

    18 //          outside the Kernel and Hardware Services package.

    19 //

    20 

    21 #ifndef E32BTRACE_H

    22 #define E32BTRACE_H

    23 

    24 #ifdef __KERNEL_MODE__

    25 class TSpinLock;

    26 #endif

    27 

    28 /**

    29 Class for handling fast tracing.

    30 

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

    32 and the trace data itself.

    33 

    34 The header consists of four bytes containing:

    35 

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

    37 -#	Flags. See enum TFlags.

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

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

    40 

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

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

    43 the address of the next record. E.g.

    44 @code

    45 	TUint8* record; // pointer to trace record

    46 	TInt size = record[BTrace::ESizeIndex];

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

    48 @endcode

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

    50 

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

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

    53 is set in the Header.

    54 

    55 -#	Header2.		Contains flag values from enum Flags2.

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

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

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

    59 					typically will contain the same values as would be returned by

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

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

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

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

    64 					to be present even if the previous Timestamp is absent.

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

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

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

    68 					least significant bits:

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

    70 							the currently executing thread.

    71 					-	01	indicates Fast Interrupt (FIQ) context.

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

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

    74 							are currently reserved for future use.

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

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

    77 					.

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

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

    80 					the trace was output.

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

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

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

    84 

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

    86 was output.

    87 

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

    89 - BTrace0

    90 - BTrace4

    91 - BTrace8

    92 - BTrace12

    93 - BTraceN

    94 - BTraceBig

    95 - BTracePc0

    96 - BTracePc4

    97 - BTracePc8

    98 - BTracePc12

    99 - BTracePcN

   100 - BTracePcBig

   101 - BTraceContext0

   102 - BTraceContext4

   103 - BTraceContext8

   104 - BTraceContext12

   105 - BTraceContextN

   106 - BTraceContextBig

   107 - BTraceContextPc0

   108 - BTraceContextPc4

   109 - BTraceContextPc8

   110 - BTraceContextPc12

   111 - BTraceContextPcN

   112 - BTraceContextPcBig

   113 

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

   115 See typedef THandler and SetHandler().

   116 

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

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

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

   120 an OBY file used to build a ROM image.

   121 

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

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

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

   125 set using the SetFilter2 methods.

   126 

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

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

   129 are reserved.

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

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

   132 

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

   134 macros can be used:

   135 

   136 - BTraceFiltered4

   137 - BTraceFiltered8

   138 - BTraceFiltered12

   139 - BTraceFilteredN

   140 - BTraceFilteredBig

   141 - BTraceFilteredPc4

   142 - BTraceFilteredPc8

   143 - BTraceFilteredPc12

   144 - BTraceFilteredPcN

   145 - BTraceFilteredPcBig

   146 - BTraceFilteredContext4

   147 - BTraceFilteredContext8

   148 - BTraceFilteredContext12

   149 - BTraceFilteredContextN

   150 - BTraceFilteredContextBig

   151 - BTraceFilteredContextPc4

   152 - BTraceFilteredContextPc8

   153 - BTraceFilteredContextPc12

   154 - BTraceFilteredContextPcN

   155 - BTraceFilteredContextPcBig

   156 

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

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

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

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

   161 

   162 @publishedPartner

   163 @released

   164 */

   165 class BTrace

   166 	{

   167 public:

   168 	/**

   169 	Byte indices into the trace header for specific fields.

   170 	*/

   171 	enum THeaderStructure

   172 		{

   173 		/**

   174 		Size of record in bytes.

   175 		*/

   176 		ESizeIndex = 0,

   177 

   178 		/**

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

   180 		the record, code like this could be used.

   181 		@code

   182 			TUint8* record; // pointer to trace record

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

   184 				TimestampPresent();

   185 			else

   186 				TimestampNotPresent();

   187 		@endcode

   188 		*/

   189 		EFlagsIndex = 1,

   190 

   191 		/**

   192 		Category value from enum BTrace::TCategory.

   193 		*/

   194 		ECategoryIndex = 2,

   195 

   196 		/**

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

   198 		*/

   199 		ESubCategoryIndex = 3,

   200 		};

   201 

   202 	/**

   203 	Bit flags which indicate state of a trace record.

   204 	*/

   205 	enum TFlags

   206 		{

   207 		/**

   208 		Header2 is present in the trace record.

   209 		*/

   210 		EHeader2Present		= 1<<0,

   211 

   212 		/**

   213 		A timestamp value is present in the trace record.

   214 		*/

   215 		ETimestampPresent	= 1<<1,

   216 

   217 		/**

   218 		A second timestamp value is present in the trace record.

   219 		*/

   220 		ETimestamp2Present	= 1<<2,

   221 

   222 		/**

   223 		A context ID is present in the trace record.

   224 		*/

   225 		EContextIdPresent	= 1<<3,

   226 

   227 		/**

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

   229 		*/

   230 		EPcPresent			= 1<<4,

   231 

   232 		/**

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

   234 		*/

   235 		EExtraPresent		= 1<<5,

   236 

   237 		/**

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

   239 		within the maximum permissible.

   240 		*/

   241 		ERecordTruncated	= 1<<6,

   242 

   243 		/**

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

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

   246 		*/

   247 		EMissingRecord		= 1<<7

   248 		};

   249 

   250 	/**

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

   252 	*/

   253 	enum TFlags2

   254 		{

   255 		/**

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

   257 		*/

   258 		EMultipartFlagMask		= 3<<0,

   259 

   260 		/**

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

   262 		*/

   263 		ECpuIdMask			= 0xfff<<20,

   264 		};

   265 

   266 	/**

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

   268 	are obtained by ANDing with the value EMultipartFlagMask.

   269 

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

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

   272 

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

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

   275 	which is the same is all parts of the trace.

   276 

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

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

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

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

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

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

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

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

   285 

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

   287 	structure:

   288 

   289 	-	4 bytes containing N.

   290 	-	4 bytes containing A.

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

   292 

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

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

   295 

   296 	-	4 bytes containing N.

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

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

   299 

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

   301 

   302 	-	4 bytes containing N.

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

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

   305 	*/

   306 	enum TMultiPart

   307 		{

   308 		/**

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

   310 		*/

   311 		EMultipartFirst			= 1,

   312 

   313 		/**

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

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

   316 		*/

   317 		EMultipartMiddle		= 2,

   318 

   319 		/**

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

   321 		*/

   322 		EMultipartLast			= 3,

   323 		};

   324 

   325 	/**

   326 	Enumeration of trace categories.

   327 	*/

   328 	enum TCategory

   329 		{

   330 		/**

   331 		Trace generated by all calls to RDebug::Printf.

   332 

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

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

   335 		thread context, this id has the value KNullThreadId.

   336 

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

   338 		generated by Kern::Printf.

   339 

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

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

   342 

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

   344 		a multipart trace is generated. See enum TMultiPart.

   345 		*/

   346 		ERDebugPrintf = 0,

   347 

   348 		/**

   349 		Trace generated by all calls to Kern::Printf.

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

   351 		*/

   352 		EKernPrintf = 1,

   353 

   354 		/**

   355 		Trace generated by platform security diagnostic messages.

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

   357 		*/

   358 		EPlatsecPrintf = 2,

   359 

   360 		/**

   361 		Trace generated for the purpose of associating thread context ids with

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

   363 		thread is created, renamed or destroyed.

   364 

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

   366 		threads currently extant.

   367 

   368 		@see enum TThreadIdentification

   369 		*/

   370 		EThreadIdentification = 3,

   371 

   372 		/**

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

   374 		or during interrupt and DFC processing.

   375 

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

   377 

   378 		@see enum TCpuUsage

   379 		*/

   380 		ECpuUsage = 4,

   381 

   382         /**

   383         Category used for profiling device drivers, kernel extensions etc.

   384         Used by PERF_LOG macro.

   385         @prototype 9.3

   386         */

   387         EKernPerfLog = 5,

   388 

   389         /**

   390 		@internalTechnology

   391         @prototype 9.3

   392         */

   393         EClientServer = 6,

   394 

   395         /**

   396 		@internalTechnology

   397         @prototype 9.3

   398         */

   399         ERequests = 7,

   400 

   401         /**

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

   403 		is committed and decommitted to and from chunks.

   404 

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

   406 		chunks currently extant.

   407 

   408 		@see TChunks

   409         */

   410         EChunks = 8,

   411 

   412         /**

   413 		Trace generated when code segments are created and destroyed, mapped

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

   415 		and from them.

   416 

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

   418 		code segments currently extant.

   419 

   420 		@see TCodeSegs

   421         */

   422         ECodeSegs = 9,

   423 

   424 		/**

   425 		Trace generated by Demand Paging.

   426 		@prototype 9.3

   427 		*/

   428 		EPaging = 10,

   429 

   430 		/**

   431 		Trace generated when thread and process priorities are modified, whether

   432 		directly or through priority inheritance, aging or other mechanisms used

   433 		by the kernel.

   434 

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

   436 		priority usage.

   437 

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

   439 		threads currently extant.

   440 

   441 		@see enum TThreadPriority

   442 		@internalTechnology

   443         @prototype 9.3

   444 		*/

   445 		EThreadPriority = 11,

   446 

   447 		/**

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

   449 		@prototype 9.3

   450 		*/

   451 		EPagingMedia = 12,

   452 

   453 		/**

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

   455 		@see enum TKernelMemory

   456 		@prototype 9.4

   457 		*/

   458 		EKernelMemory = 13,

   459 

   460 		/**

   461 		Trace generated by user-mode heap usage.

   462 

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

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

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

   466 

   467 			firstlib eexe_instrumented_heap.lib

   468 

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

   470 

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

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

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

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

   475 

   476 			trace 0 0 1

   477 

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

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

   480 

   481 		@see enum THeap

   482 		@prototype 9.4

   483 		*/

   484 		EHeap = 14,

   485 

   486 		/**

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

   488 		@see enum TMetaTrace

   489 		@prototype 9.4

   490 		*/

   491 		EMetaTrace = 15,

   492 

   493 		/**

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

   495 		to be tracked.

   496 		@internalTechnology

   497 		*/

   498 		ERamAllocator = 16,

   499 

   500 		/**

   501 		Trace generated by the Fast Mutex in the Nkern.

   502 		*/

   503 		EFastMutex = 17,

   504 

   505 

   506 		/**

   507 		Trace generated by any sampling profiler.

   508 		@see enum TProfiling

   509 		*/

   510 		EProfiling = 18,

   511 

   512 		/**

   513         Trace generated by Power Resource Manager.

   514         @prototype 9.5

   515         */

   516         EResourceManager = 19,

   517 

   518 

   519         /**

   520         Trace generated by Power Resource Manager User-Side API.

   521         @prototype 9.5

   522         */

   523         EResourceManagerUs = 20,

   524 

   525 		/**

   526 		Trace generated by Raw Event subsystem APIs

   527 		@see enum TRawEventTrace

   528 		@prototype 9.5

   529 		*/

   530 		ERawEvent  =21,

   531 

   532 		/**

   533 		Trace generated by USB communications (Client, Host and OTG) where use

   534 		of standard logging (conditional Kern::Printf() calls) is sufficiently

   535 		time-consuming that the required device timings mandated by the core

   536 		USB standards cannot be achieved

   537         @prototype 9.5

   538 		*/

   539 		EUsb = 22,

   540 

   541 		/**

   542 		Trace generated by Symbian OS kernel synchronization objects.

   543         @prototype 9.5

   544 		*/

   545 		ESymbianKernelSync = 23,

   546 

   547 		/**

   548 		Trace generated by the flexible memory model.

   549 		*/

   550 		EFlexibleMemModel = 24,

   551 

   552 		/**

   553         Trace generated by IIC bus.

   554         @prototype 9.6

   555         */

   556         EIic = 25,

   557 

   558 		/**

   559 		First category value in the range reserved for platform specific use;

   560 		the end of this range is #EPlatformSpecificLast.

   561 		Symbian's code will not generate any traces with categories in this range.

   562 

   563 		It is strongly recommended that platforms reserve the first half of this range

   564 		(128..143) for definition and use by base-port (kernel-side) code. Any general

   565 		trace framework built on top of BTrace APIs should use the second half of the range.

   566 		This allows fast (primary filtered only) BTrace categories to be used in device drivers

   567 		and other base-port code, without clashing with more general trace frameworks implemented

   568 		for application layer code.

   569 		*/

   570 		EPlatformSpecificFirst = 128,

   571 

   572 		/**

   573 		Last category value in the range reserved for platform specific use.

   574 		@see EPlatformSpecificFirst

   575 		*/

   576 		EPlatformSpecificLast = 191,

   577 

   578 		/**

   579 		First category value in the range reserved for Symbian tools and future trace framework

   580 		implementations; the end of this range is #ESymbianExtentionsLast.

   581 		*/

   582 		ESymbianExtentionsFirst = 192,

   583 

   584 		/**

   585 		Last category value in the range reserved for Symbian tools and future trace framework

   586 		implementations.

   587 		@see ESymbianExtentionsFirst

   588 		*/

   589 		ESymbianExtentionsLast = 253,

   590 

   591 		/**

   592 		Used for testing purposes.

   593 

   594 		This may be used for ad-hoc testing purposes, e.g. special builds of components

   595 		with tracing enabled for diagnostic purposes.

   596 

   597 		This category is also used by the E32 BTrace unit tests.

   598 		@test

   599 		*/

   600 		ETest1 = 254,

   601 

   602 		/**

   603 		Used for testing purposes.

   604 

   605 		This may be used for ad-hoc testing purposes, e.g. special builds of components

   606 		with tracing enabled for diagnostic purposes.

   607 

   608 		This category is also used by the E32 BTrace unit tests.

   609 		@test

   610 		*/

   611 		ETest2 = 255

   612 		};

   613 

   614 	/**

   615 	Enumeration of sub-category values for trace category EThreadIdentification.

   616 	@see EThreadIdentification

   617 	*/

   618 	enum TThreadIdentification

   619 		{

   620 		/**

   621 		A nano-kernel thread (NThread) has been created.

   622 

   623 		Trace data format:

   624 		- 4 bytes containing the context id (an NThread*) for this thread.

   625 		*/

   626 		ENanoThreadCreate,

   627 

   628 		/**

   629 		A nano-kernel thread (NThread) has been destroyed.

   630 

   631 		Trace data format:

   632 		- 4 bytes containing the context id (an NThread*) for this thread.

   633 		*/

   634 		ENanoThreadDestroy,

   635 

   636 		/**

   637 		A thread (DThread) has been created.

   638 

   639 		Trace data format:

   640 		- 4 bytes containing the context id (an NThread*) for this thread.

   641 		- 4 bytes containing trace id (a DProcess*) for the process to which this thread belongs.

   642 		- Remaining data is the ASCII name of the thread.

   643 		*/

   644 		EThreadCreate,

   645 

   646 		/**

   647 		A thread (DThread) has been destroyed.

   648 

   649 		Trace data format:

   650 		- 4 bytes containing the context id (an NThread*) for this thread.

   651 		- 4 bytes containing trace id for the process to which this thread belongs.

   652 		- 4 bytes containing thread ID, as returned by RThread::Id().

   653 		*/

   654 		EThreadDestroy,

   655 

   656 		/**

   657 		A thread (DThread) has been renamed.

   658 		This trace may also be output by the tracing system at initialisation

   659 		in order to identify threads already in existence.

   660 

   661 		Trace data format:

   662 		- 4 bytes containing the context id (an NThread*) for this thread.

   663 		- 4 bytes containing trace id (a DProcess*) for the process to which this thread belongs.

   664 		- Remaining data is the ASCII name of the thread.

   665 		*/

   666 		EThreadName,

   667 

   668 		/**

   669 		A process has been renamed.

   670 		This trace may also be output together with EThreadCreate or EThreadName traces

   671 		to help identify the name of the process to which the thread belongs.

   672 

   673 		Trace data format:

   674 		- 4 bytes containing zero, or if this trace is generated together with EThreadName

   675 		  or EThreadCreate, this contains the context id (an NThread*) for the thread.

   676 		- 4 bytes containing trace id (a DProcess*) for process.

   677 		- Remaining data is the ASCII name of the process.

   678 		*/

   679 		EProcessName,

   680 

   681 		/**

   682 		Informational trace giving a threads ID, as returned by RThread::Id().

   683 		Trace data format:

   684 		- 4 bytes containing the context id (an NThread*) for this thread.

   685 		- 4 bytes containing trace id (a DProcess*) for the process to which this thread belongs.

   686 		- 4 bytes containing thread ID, as returned by RThread::Id().

   687 		*/

   688 		EThreadId,

   689 

   690 		/**

   691 		A process has been created.

   692 

   693 		Trace data format:

   694 		- 4 bytes containing trace id (a DProcess*) for the process.

   695 		*/

   696 		EProcessCreate,

   697 

   698 		/**

   699 		A process has been destroyed.

   700 

   701 		Trace data format:

   702 		- 4 bytes containing trace id (a DProcess*) for the process.

   703 		*/

   704 		EProcessDestroy

   705 

   706 		};

   707 

   708 	/**

   709 	Enumeration of sub-category values for trace category ECpuUsage.

   710 	@see ECpuUsage

   711 	*/

   712 	enum TCpuUsage

   713 		{

   714 		/**

   715 		Trace output at start of Interrupt (IRQ) dispatch.

   716 

   717 		On platforms which support nested interrupts, traces for these will also

   718 		be nested.

   719 		*/

   720 		EIrqStart,

   721 

   722 		/**

   723 		Trace output at end of Interrupt (IRQ) dispatch.

   724 

   725 		Note, this trace isn't generated if an Interrupt Service Routine queues

   726 		a DFC or causes a thread to be scheduled. In these cases, the traces for

   727 		these events (EIDFCStart or ENewThreadContext) should be taken to indicate

   728 		that interrupt servicing has ended.

   729 		*/

   730 		EIrqEnd,

   731 

   732 		/**

   733 		Trace output at start of Fast Interrupt (FIQ) dispatch.

   734 

   735 		On platforms which support nested interrupts, traces for these will also

   736 		be nested.

   737 		*/

   738 		EFiqStart,

   739 

   740 		/**

   741 		Trace output at end of Fast Interrupt (FIQ) dispatch.

   742 

   743 		Note, this trace isn't generated if an Interrupt Service Routine queues

   744 		a DFC or causes a thread to be scheduled. In these cases, the traces for

   745 		these events (EIDFCStart or ENewThreadContext) should be taken to indicate

   746 		that interrupt servicing has ended.

   747 		*/

   748 		EFiqEnd,

   749 

   750 		/**

   751 		Trace output at start of Immediate Delayed Function Call (IDFC) processing.

   752 		This processing also includes moving DFCs to their final queue, so the trace

   753 		does not necessarily indicate that any IDFCs have been executed.

   754 		*/

   755 		EIDFCStart,

   756 

   757 		/**

   758 		Trace output at end of Immediate Delayed Function Call (IDFC) processing.

   759 		*/

   760 		EIDFCEnd,

   761 

   762 		/**

   763 		Trace output when a thread is scheduled to run.

   764 		The context id (NThread*) in this trace is that of the thread being scheduled.

   765 		*/

   766 		ENewThreadContext

   767 		};

   768 

   769     /**

   770 	@internalTechnology

   771     @prototype 9.3

   772     */

   773 	enum TClientServer

   774 		{

   775 		/**

   776 		Trace generated whenever a server is created.

   777 

   778 		Trace data format:

   779 		- 4 bytes containing the server id (a DServer*).

   780 		- 4 bytes containing undefined data

   781 		- Remaining data is the ASCII name of the server.

   782 

   783 		The context id (NThread*) in this trace is that of the thread creating the server.

   784 		*/

   785 		EServerCreate,

   786 

   787 		/**

   788 		Trace generated whenever a server is destroyed.

   789 

   790 		Trace data format:

   791 		- 4 bytes containing the server id (a DServer*).

   792 

   793 		*/

   794 		EServerDestroy,

   795 

   796 		/**

   797 		Trace generated whenever a new session is attached to a server.

   798 		I.e. a new session has been created.

   799 

   800 		Trace data format:

   801 		- 4 bytes containing the session id (a DSession*).

   802 		- 4 bytes containing the server id (a DServer*).

   803 

   804 		The context id (NThread*) in this trace is that of the thread creating the session.

   805 		*/

   806 		ESessionAttach,

   807 

   808 		/**

   809 		Trace generated whenever a server session is detached from a server.

   810 		I.e. a session has been closed.

   811 

   812 		Trace data format:

   813 		- 4 bytes containing the session id (a DSession*).

   814 		- 4 bytes containing the reasons (error code) for the session being closed.

   815 

   816 		*/

   817 		ESessionDetach,

   818 

   819 		/**

   820 		Trace generated whenever a new message is sent to a server.

   821 

   822 		Trace data format:

   823 		- 4 bytes containing the message handle.

   824 		- 4 bytes containing the iFunction value for the message.

   825 		- 4 bytes containing the session id (a DSession*).

   826 

   827 		The context id (NThread*) in this trace is that of the thread which sent the message.

   828 		*/

   829 		EMessageSend,

   830 

   831 		/**

   832 		Trace generated when a server receives a new message.

   833 

   834 		Trace data format:

   835 		- 4 bytes containing the message handle.

   836 		*/

   837 		EMessageReceive,

   838 

   839 		/**

   840 		Trace generated whenever a message is completed using RMessagePtr2::Complete.

   841 

   842 		Trace data format:

   843 		- 4 bytes containing the message handle.

   844 		- 4 bytes containing the completion reason, or object handle, value.

   845 		    (The object handle value is that which is delivered to the sender of the

   846 			message, not that supplied by the server actually completing the request.)

   847 

   848 		The context id (NThread*) in this trace is that of the thread which completed the message.

   849 		*/

   850 		EMessageComplete

   851 		};

   852 

   853 

   854     /**

   855 	@internalTechnology

   856     @prototype 9.3

   857     */

   858 	enum TRequests

   859 		{

   860 		/**

   861 		Trace generated whenever a request status is completed.

   862 

   863 		Trace data format:

   864 		- 4 bytes containing the thread id (NThread*) of the thread being signalled.

   865 		- 4 bytes containing the address of the TRequestStatus object.

   866 		- 4 bytes containing the completion reason.

   867 

   868 		The context id (NThread*) in this trace is that of the thread which completed the request.

   869 		*/

   870 		ERequestComplete

   871 		};

   872 

   873 

   874 	/**

   875 	Enumeration of sub-category values for trace category EChunks.

   876 	@see EChunks

   877 	*/

   878 	enum TChunks

   879 		{

   880 		/**

   881 		Trace output when a chunk is created.

   882 

   883 		Trace data format:

   884 		- 4 bytes containing the chunk id (a DChunk*).

   885 		- 4 bytes containing the maximum size of the chunk.

   886 		- The ASCII name of the chunk.

   887 		*/

   888 		EChunkCreated,

   889 

   890 		/**

   891 		@internalTechnology

   892 

   893 		Trace output when a chunk is created containing extra chunk information.

   894 

   895 		Note that the meaning of the data in this trace is different between

   896 		memory models, and may change without warning.

   897 

   898 		Trace data format:

   899 		- 4 bytes containing the chunk id (a DChunk*).

   900 		- 4 bytes containing the chunk type.

   901 		- 4 bytes containing the chunk's attributes.

   902 		*/

   903 		EChunkInfo,

   904 

   905 		/**

   906 		Trace output when a chunk is destroyed.

   907 

   908 		Trace data format:

   909 		- 4 bytes containing the chunk id (a DChunk*)

   910 		*/

   911 		EChunkDestroyed,

   912 

   913 		/**

   914 		Trace output when memory is allocated and committed to a chunk.

   915 

   916 		Trace data format:

   917 		- 4 bytes containing the chunk id (a DChunk*).

   918 		- 4 bytes containing the offset into the chunk.

   919 		- 4 bytes containing the size of the memory committed.

   920 		*/

   921 		EChunkMemoryAllocated,

   922 

   923 		/**

   924 		Trace output when memory is decommitted from a chunk and deallocated.

   925 

   926 		Trace data format:

   927 		- 4 bytes containing the chunk id (a DChunk*).

   928 		- 4 bytes containing the offset into the chunk.

   929 		- 4 bytes containing the size of the memory decommitted.

   930 		*/

   931 		EChunkMemoryDeallocated,

   932 

   933 		/**

   934 		Trace output when un-owned memory is committed to a chunk.

   935 

   936 		Trace data format:

   937 		- 4 bytes containing the chunk id (a DChunk*).

   938 		- 4 bytes containing the offset into the chunk.

   939 		- 4 bytes containing the size of the memory committed.

   940 		*/

   941 		EChunkMemoryAdded,

   942 

   943 		/**

   944 		Trace output when un-owned memory is decommitted to a chunk.

   945 

   946 		Trace data format:

   947 		- 4 bytes containing the chunk id (a DChunk*).

   948 		- 4 bytes containing the offset into the chunk.

   949 		- 4 bytes containing the size of the memory decommitted.

   950 		*/

   951 		EChunkMemoryRemoved,

   952 

   953 		/**

   954 		Trace to indicate the owning process of a chunk - only for local (private) chunks.

   955 

   956 		Trace data format:

   957 		- 4 bytes containing the chunk id (a DChunk*).

   958 		- 4 bytes containing the process id of the owner (a DProcess*).

   959 		*/

   960 		EChunkOwner

   961 		};

   962 

   963 	/**

   964 	Enumeration of sub-category values for trace category ECodeSegs.

   965 	@see ECodeSegs

   966 	*/

   967 	enum TCodeSegs

   968 		{

   969 		/**

   970 		Trace output when a code segment is created to associate a code segment

   971 		id with a filename.

   972 

   973 		Trace data format:

   974 		- 4 bytes containing the code segment id (a DCodeSeg*).

   975 		- The ASCII filename.

   976 		*/

   977 		ECodeSegCreated,

   978 

   979 		/**

   980 		Trace output when a code segment is created.

   981 

   982 		Trace data format:

   983 		- 4 bytes containing the code segment id (a DCodeSeg*).

   984 		- 4 bytes containing the attributes.

   985 		- 4 bytes containing the code base address (.text).

   986 		- 4 bytes containing the size of the code section (.text).

   987 		- 4 bytes containing the base address of the constant data section (.rodata).

   988 		- 4 bytes containing the size of the constant data section (.rodata).

   989 		- 4 bytes containing the base address of the initialised data section (.data).

   990 		- 4 bytes containing the size of the initialised data section (.data).

   991 		- 4 bytes containing the base address of the uninitialised data section (.bss).

   992 		- 4 bytes containing the size of the uninitialised data section (.bss).

   993 		*/

   994 		ECodeSegInfo,

   995 

   996 		/**

   997 		Trace output when a code segment is destroyed.

   998 

   999 		Trace data format:

  1000 		- 4 bytes containing the code segment id (a DCodeSeg*).

  1001 		*/

  1002 		ECodeSegDestroyed,

  1003 

  1004 		/**

  1005 		Trace output when a code segment is mapped into a process.

  1006 

  1007 		Trace data format:

  1008 		- 4 bytes containing the code segment id (a DCodeSeg*).

  1009 		- 4 bytes containing the process id (a DProcess*).

  1010 		*/

  1011 		ECodeSegMapped,

  1012 

  1013 		/**

  1014 		Trace output when a code segment is unmapped from a process.

  1015 

  1016 		Trace data format:

  1017 		- 4 bytes containing the code segment id (a DCodeSeg*).

  1018 		- 4 bytes containing the process id (a DProcess*).

  1019 		*/

  1020 		ECodeSegUnmapped,

  1021 

  1022 		/**

  1023 		Trace output when memory is allocated to a code segment.

  1024 

  1025 		Under the multiple memory model, code segments for RAM-loaded user code

  1026 		own the RAM pages the code occupies.  The pages are not owned by any

  1027 		chunk, but are mapped into the code chunk of each process that uses the

  1028 		code segment.

  1029 

  1030 		Trace data format:

  1031 		- 4 bytes containing the code segment id (a DCodeSeg*).

  1032 		- 4 bytes containing the size of the memory allocated.

  1033 		*/

  1034 		ECodeSegMemoryAllocated,

  1035 

  1036 		/**

  1037 		Trace output when memory is deallocated from a code segment.

  1038 

  1039 		Under the multiple memory model, code segments for RAM-loaded user code

  1040 		own the RAM pages the code occupies.  The pages are not owned by any

  1041 		chunk, but are mapped into the code chunk of each process that uses the

  1042 		code segment.

  1043 

  1044 		Trace data format:

  1045 		- 4 bytes containing the code segment id (a DCodeSeg*).

  1046 		- 4 bytes containing the size of the memory deallocated.

  1047 		*/

  1048 		ECodeSegMemoryDeallocated

  1049 		};

  1050 

  1051 

  1052 	/**

  1053 	Enumeration of sub-category values for trace category EPaging.

  1054 	@see EPaging

  1055 	*/

  1056 	enum TPaging

  1057 		{

  1058 		/**

  1059 		This event indicates the beginning of the 'page in' activity.

  1060 		The end of this activity is indicated by one of the following events:

  1061 		- EPagingPageInUnneeded

  1062 		- EPagingPageInROM

  1063 		- EPagingPageInCode

  1064 		- EPagingPageIn (flexible memory model)

  1065 

  1066 		Trace data format:

  1067 		- 4 bytes containing the virtual address which was accessed, causing this paging event.

  1068 		- 4 bytes containing the virtual address of the instruction which caused this paging event.

  1069 		  (The PC value.)

  1070 

  1071 		On the flexible memory model, the following addition trace data is also present:

  1072 		- 1 byte containing the required access permissions, as defined by TMappingPermissions.

  1073 		- 3 spare bytes, currently zero

  1074 

  1075 		The context id (NThread*) in this trace is that of the thread caused this paging event.

  1076 		*/

  1077 		EPagingPageInBegin,

  1078 

  1079 		/**

  1080 		Event which terminates the 'page in' activity when the required page was found to have been

  1081 		paged in by another thread while the current thread was processing the fault (see

  1082 		EPagingPageInBegin).

  1083 

  1084 		Trace data format:

  1085 		- 0 bytes. (No extra data.)

  1086 

  1087 		The context id (NThread*) in this trace is that of the thread caused this paging event.

  1088 		*/

  1089 		EPagingPageInUnneeded,

  1090 

  1091 		/**

  1092 		A ROM page has been paged in.

  1093 		This event indicates the end of the 'page in' activity. (See EPagingPageInBegin.)

  1094 

  1095 		Trace data format:

  1096 		- 4 bytes containing the physical address of the page 'paged in'.

  1097 		- 4 bytes containing the virtual address of the page 'paged in'.

  1098 

  1099 		The context id (NThread*) in this trace is that of the thread caused this paging event.

  1100 

  1101 		This trace is not emitted on the flexible memory model - EPagingPageIn is used instead.

  1102 		*/

  1103 		EPagingPageInROM,

  1104 

  1105 		/**

  1106 		A ROM page has been 'paged out'. I.e. removed from the live list to be either

  1107 		reused or returned to free pool.

  1108 

  1109 		Trace data format:

  1110 		- 4 bytes containing the physical address of the page being 'paged out'.

  1111 		- 4 bytes containing the virtual address of the page being 'paged out'.

  1112 

  1113 		The context id (NThread*) in this trace is that of the thread caused this paging event.

  1114 

  1115 		This trace is not emitted on the flexible memory model - EPagingPageOut is used instead.

  1116 		*/

  1117 		EPagingPageOutROM,

  1118 

  1119 		/**

  1120 		A Free page has been 'paged in'. I.e. added to the live list.

  1121 

  1122 		Trace data format:

  1123 		- 4 bytes containing the physical address of the page being 'paged in'.

  1124 

  1125 		The context id (NThread*) in this trace is that of the thread caused this paging event.

  1126 		*/

  1127 		EPagingPageInFree,

  1128 

  1129 		/**

  1130 		A Free page has been 'paged out'. I.e. removed from the live list to be either

  1131 		reused or returned to free pool.

  1132 

  1133 		Trace data format:

  1134 		- 4 bytes containing the physical address of the page being 'paged out'.