; --------------------------------------------------------------------------------
; @Title: Readme for "simple" task awareness
; @Description: -
; @Author: DIE
; @Copyright: (C) 1989-2014 Lauterbach GmbH, licensed for use with TRACE32(R) only
; --------------------------------------------------------------------------------
; $Id: readme.txt 8112 2015-02-10 13:57:22Z rdienstbeck $

SIMPLE task awareness for statistic analysis

Several statistical analysis out of the trace (e.g. Trace.STATistic.FUNCtion) 
need to know, if a task switch happened within a function. (Otherwise the 
function call tree of one task will be handled as sub-tree of another task.)

If you use one of the already supported RTOS (see demo/<processor>/kernel 
directories), then please configure the RTOS awareness as described in the 
appropriate awareness manual (see pdf/rtos_*.pdf).

If you use an proprietary kernel, or an RTOS that is not yet supported by 
Lauterbach, you can use this "simple" awareness to configure the debugger. 
 
Each RTOS has a variable that specifies which task is the current running one.
This variable may hold a task id, or a pointer to tcb, or somthing else that 
is unique for this task.

In order to do a correct function statistic evaluation out of the real time 
trace, you need to record the accesses to this variable, and configure the 
debugger to know about this.

Configure the "simple" kernel awareness:

TASK.CONFIG simple.t32 <address> <size>

where <address> is the the address of the variable mentioned above, and <size> 
is the size of this variable (<size> defaults to 4 if left blank). 
E.g. if a 32bit variable "current_task", bound to address 0x1234, holds the 
task id of the running task, each of the following statements will work:

TASK.CONFIG simple.t32 0x1234
TASK.CONFIG simple.t32 0x1234 4
TASK.CONFIG simple.t32 current_task v.sizeof(current_task)

Additionally, you have to program your trace equipment to record the accesses 
to this variable. This can be done by using the function task.config(magic) 
that returns the specified address. E.g. if using an ETM:

Break.Set task.config(magic) /TraceData

This will program the trace logic to record program flow plus task switches.

Now you can start your trace recordings and statistical evaluations. The 
functions will be evaluated depending on their calling task.

The task id recorded will be displayed as hex value. You can assign task names
to each id by using the TASK.NAME command group, e.g.

TASK.NAME.Set 0x1001 "firstTask"

Task id 0 and 1 are by default assiged to "(root)" and "(kernel)".
If you use these ids for ordinary tasks, you can reassign the "root"
and "kernel" id with the third and fourth TASK.CONFIG parameter.
E.g. to set them to -2 and -1:

TASK.CONFIG simple.t32 0x1234 4 -2 -1