293 lines
15 KiB
Plaintext
293 lines
15 KiB
Plaintext
; --------------------------------------------------------------------------------
|
||
; @Title: TRACE32 LiteOS RTOS Support - README
|
||
; @Description: -
|
||
; @Author: -
|
||
; @Copyright: (C) 1989-2022 Lauterbach GmbH, licensed for use with TRACE32(R) only
|
||
; --------------------------------------------------------------------------------
|
||
; $Id: readme.txt 18850 2022-01-26 18:41:29Z bschroefel $
|
||
|
||
---------------------------
|
||
Quick Configuration Guide:
|
||
---------------------------
|
||
To get a quick access to the features of the LiteOS RTOS debugger
|
||
with your application, follow this roadmap:
|
||
1. Start the TRACE32 Debugger.
|
||
|
||
2. Load your application as normal.
|
||
|
||
3. Execute the command: TASK.CONFIG liteos.t32
|
||
|
||
4. Execute the command: MENU.ReProgram liteos.men
|
||
|
||
5. Start your application.
|
||
Now you can access the LiteOS extensions through the menu.
|
||
|
||
-----------
|
||
Features :
|
||
-----------
|
||
The RTOS debugger for LiteOS supports the following features.
|
||
|
||
* Display of Kernel Resources
|
||
-----------------------------
|
||
|
||
The extension defines new PRACTICE commands to display various kernel resources.
|
||
- TASK.Task : display tasks with detailed information including
|
||
task id, name, state, priority, entry address. The "entry" field is mouse sensitive,
|
||
double clicking on it opens appropriate windows.
|
||
You can specify a Task magic or name to display detailed information
|
||
on that Task.
|
||
|
||
- TASK.MUteX : display a list of used mutexes.
|
||
|
||
- TASK.SEMaphore : display a list of used semaphores.
|
||
Without any arguments, a table with all used semaphores.
|
||
You can specify a semaphore magic number to display detailed information
|
||
on that semaphore.
|
||
|
||
- TASK.QUEue : display a list of used queues.
|
||
Without any arguments, a table with all created message queues will be shown.
|
||
You can specify a message queue magic number to display detailed information
|
||
on that message
|
||
queue.
|
||
|
||
- TASK.TIMer : display a list of used timers.
|
||
|
||
The ’magic’ field in all LiteOS awareness windows is a unique ID, used by the
|
||
RTOS Debugger to identify a specific (task, mutex, semaphore ..)..
|
||
The field ’magic’ is mouse sensitive, double clicking on it opens appropriate windows.
|
||
Right clicking on it will show a local menu.
|
||
|
||
If your hardware allows accessing the memory, while the target is running,
|
||
these resources can be displayed "On The Fly", i.e. while the application is running,
|
||
without any intrusion to the application. Without this capability, the information
|
||
will only be displayed, if the target application is stopped.
|
||
|
||
|
||
* Task Stack Coverage
|
||
---------------------
|
||
For stack usage coverage of the tasks, you can use the "TASK.STacK" command.
|
||
Without any parameter, this command will set up a window with all active tasks.
|
||
If you specify only a magic number as parameter, the stack area of this task
|
||
will be automatically calculated. To use the calculation of the maximum stack
|
||
usage, flag memory must be mapped to the task stack areas, when working with
|
||
the emulation memory. When working with the target memory, a stack pattern
|
||
must be defined with the command "TASK.STacK.PATtern" (default value is zero).
|
||
|
||
To add/remove one task to/from the task stack coverage, you can either call
|
||
the "TASK.STacK.ADD" rsp."TASK.STacK.ReMove" commands with the task magic
|
||
number as parameter, or omit the parameter and select from the task list window.
|
||
|
||
It is recommended, to display only the tasks, that you are interested in,
|
||
because the evaluation of the used stack space is very time consuming and slows
|
||
down the debugger display.
|
||
|
||
|
||
* Task Related Breakpoints
|
||
--------------------------
|
||
Any breakpoint set in the debugger can be restricted to fire only, if a specific
|
||
task hits that breakpoint. This is especially useful, when debugging code which
|
||
is shared between several tasks. To set a task related breakpoint, use the command:
|
||
"Break.Set <address>|<range> [/<option>] /TASK <task>" : Set task related breakpoint.
|
||
|
||
Use a task magic, ID or name for <task>.
|
||
|
||
By default, the task related breakpoint will be implemented by a conditional
|
||
breakpoint inside the debugger. I.e., the target will always halt at that breakpoint,
|
||
but the debugger immediately resumes execution, if the current running task is not
|
||
equal to the specified task.
|
||
|
||
NOTE: Task related breakpoints impact the real-time behavior of the application.
|
||
|
||
For a general description of the Break.Set command, please see its documentation.
|
||
|
||
When single stepping, the debugger halts on the next instruction, regardless which
|
||
task hits this breakpoint. When debugging shared code, stepping over an OS function
|
||
may lead to a task switch and coming back to the same place - but with a different task.
|
||
If you want to "stick" the debugging within the current task you can set up the debugger
|
||
with "SETUP.StepWithinTask ON" to use task related breakpoints for single stepping.
|
||
In this case, single stepping will always stay within the current task.
|
||
Other tasks using the same code will not be halted on these events.
|
||
|
||
If you want to halt program execution as soon as a specific task is scheduled to run
|
||
by the OS, you can use the Break.SetTask command.
|
||
by the OS, you can use the Break.SetTask command.
|
||
|
||
* Task Context Display
|
||
----------------------
|
||
You are able to switch the whole viewing context to a currently not executing task.
|
||
This means, that all register and stack related information (such as Register, Data.List, Frame etc.)
|
||
will be shown according to this task. Be aware that this is only for displaying information.
|
||
When continuing debugging the application ( Step or Go), the debugger will switch
|
||
back to the current context.
|
||
|
||
For displaying a specific task context, use the command:
|
||
"Frame.TASK [<task>]" : Display task context.
|
||
Specify a task magic or a task name (in double quotes) as parameter.
|
||
|
||
To switch back to the current context, omit all parameters.
|
||
|
||
For displaying the call stack of a specific task, you can use the following command:
|
||
"Frame /Task <task>" : Display call stack of a task.
|
||
|
||
If you’d like to see the application code, where the task was preempted, execute the command
|
||
Frame /Caller /Task <task> to open a window of the same name.
|
||
Double click on the line showing the OS service call.
|
||
|
||
* Dynamic Task Performance Measurement
|
||
--------------------------------------
|
||
The debugger may execute a dynamic performance measurement by evaluating the current
|
||
running task in changing time intervals. Start the measurement with the commands
|
||
"PERF.Mode TASK" and "PERF.Arm", and view the contents with "PERF.ListTASK".
|
||
The evaluation is done by reading the ‘magic’ location (= current running task) in memory.
|
||
This memory read may be non-intrusive or intrusive, depending on the "PERF.METHOD" used.
|
||
|
||
If "PERF" collects the PC for function profiling of processes in MMU based operating systems
|
||
("SYStem.Option MMUSPACES ON"), then you need to set "PERF.MMUSPACES", too.
|
||
For a general description of the PERF command, refer to
|
||
"General Commands Reference Guide P" (general_ref_p.pdf).
|
||
|
||
|
||
* Task Runtime Statistics
|
||
-------------------------
|
||
NOTE: This feature is only available, if your debugger equipment is able to trace
|
||
task switches (see below).
|
||
|
||
Out of the recordings done by the Trace (if available), the debugger is able to evaluate
|
||
the time spent in a task and display it statistically and graphically.
|
||
To do this, the debugger must be able to detect the task switches out of the trace,
|
||
i.e. the task switches need to be recorded.
|
||
|
||
Usually, there’s a variable in the system that holds the current running task.
|
||
By recording the accesses to this memory location (aka "magic" location), the debugger
|
||
detects a task switch by a change of this variable.
|
||
Please note, that the debugger equipment must be able to trace memory data accesses
|
||
in this case, program flow trace is not sufficient.
|
||
|
||
To do a selective recording on task switches with state analyzers (ICE and FIRE),
|
||
use the following PRACTICE commands:
|
||
|
||
---------------------------------------------------------------------------
|
||
| ; Mark the magic location with an Alpha breakpoint |
|
||
| Break.Set TASK.CONFIG(magic)++(TASK.CONFIG(magicsize)-1) /Alpha |
|
||
| ; Program the Analyzer to record only task switches |
|
||
| Analyzer.ReProgram |
|
||
| ( |
|
||
| Sample.Enable if AlphaBreak&&Write |
|
||
| ) |
|
||
---------------------------------------------------------------------------
|
||
|
||
To do a selective recording on task switches with flow traces (ICD, e.g. ETM and NEXUS trace),
|
||
based on the data accesses, use the following PRACTICE command:
|
||
|
||
-----------------------------------------------
|
||
| ; Enable tracing only on the magic location |
|
||
| Break.Set TASK.CONFIG(magic) /TraceEnable |
|
||
-----------------------------------------------
|
||
|
||
To evaluate the contents of the trace buffer, use these commands:
|
||
- Trace.List List.TASK DEFault : Display trace buffer and task switches
|
||
- Trace.STATistic.TASK : Display task runtime statistic evaluation
|
||
- Trace.Chart.TASK : Display task runtime timechart
|
||
- Trace.PROfileSTATistic.TASK : Display task runtime within fixed time intervals statistically
|
||
- Trace.PROfileChart.TASK : Display task runtime within fixed time intervals as colored graph
|
||
- Trace.FindAll Address task.config(magic) : Display all data access records to the "magic" location
|
||
- Trace.FindAll CYcle owner OR CYcle context : Display all context ID records
|
||
|
||
The start of the recording time, when the calculation doesn’t know, which task is running,
|
||
is calculated as "(unknown)".
|
||
|
||
* Task State Analysis
|
||
---------------------
|
||
NOTE: This feature is only available, if your debugger equipment is able to trace
|
||
memory data accesses (program flow trace is not sufficient).
|
||
|
||
The time different tasks are in a certain state (running, ready, suspended or waiting)
|
||
can be evaluated statistically or displayed graphically.
|
||
|
||
This feature needs recording of all accesses to the status words of all tasks.
|
||
Additionally, the accesses to the current task pointer (=magic) are needed. Adjust your
|
||
trace logic to record all data write accesses, or limit the recorded data to the area
|
||
where all TCBs are located (plus the current task pointer).
|
||
|
||
To do a selective recording on task states with state analyzers (ICE or FIRE), use
|
||
"TASK.TASKState", if available, to mark the status words with Alpha breakpoints.
|
||
Run the following PRACTICE script:
|
||
|
||
------------------------------------------------------------------------------
|
||
| ; Mark the magic location with an Alpha breakpoint |
|
||
| Break.Set task.config(magic)++(task.config(magicsize)-1) /Alpha |
|
||
| ; Mark all task state words with Alpha breakpoints |
|
||
| TASK.TASKState |
|
||
| ; Program the Analyzer to record task state transitions |
|
||
| Analyzer.ReProgram |
|
||
| ( |
|
||
| Sample.Enable if AlphaBreak&&Write |
|
||
| ) |
|
||
------------------------------------------------------------------------------
|
||
|
||
To do a selective recording on task states with flow traces (ICD, e.g. ETM and NEXUS trace),
|
||
just enable the recording of all data write cycles.
|
||
|
||
To evaluate the contents of the trace buffer, use these commands:
|
||
- Trace.STATistic.TASKState : Display task state statistic
|
||
- Trace.Chart.TASKState : Display task state timechart
|
||
|
||
The start of the recording time, when the calculation doesn’t know, which task is running,
|
||
is calculated as "(unknown)".
|
||
All kernel activities up to the task switch are added to the calling task.
|
||
|
||
|
||
* Function Runtime Statistics
|
||
-----------------------------
|
||
NOTE: This feature is only available, if your debugger equipment is able to trace memory data
|
||
accesses (program flow trace is not sufficient).
|
||
|
||
All function related statistic and timechart evaluations can be used with task specific information.
|
||
The function timings will be calculated dependent on the task, that called this function.
|
||
To do this, additionally to the function entries and exits, the task switches must be recorded.
|
||
To do a selective recording on task related function runtimes with state analyzers (ICE and FIRE),
|
||
use the following PRACTICE commands:
|
||
|
||
----------------------------------------------------------------------------
|
||
| ; Mark the magic location with an Alpha breakpoint |
|
||
| Break.Set TASK.CONFIG(magic)++(TASK.CONFIG(magicsize)-1) /Alpha |
|
||
| ; Mark the function entries/exits with Alpha/Beta breakpoints |
|
||
| Break.SetFunc |
|
||
| ; Program the Analyzer to record function entries/exits and task switches |
|
||
| Analyzer.ReProgram |
|
||
| ( |
|
||
| Sample.Enable if AlphaBreak||BetaBreak |
|
||
| Mark.A if AlphaBreak |
|
||
| Mark.B if BetaBreak |
|
||
| ) |
|
||
----------------------------------------------------------------------------
|
||
|
||
To do a selective recording on task related function runtimes with flow traces
|
||
(ICD, e.g. ETM and NEXUS trace), based on the data accesses, use the following PRACTICE command:
|
||
|
||
----------------------------------------------------------------
|
||
| ; Enable flow trace an accesses to the magic location |
|
||
| Break.Set TASK.CONFIG(magic) /TraceData |
|
||
----------------------------------------------------------------
|
||
|
||
To evaluate the contents of the trace buffer, use these commands:
|
||
- Trace.ListNesting : Display function nesting
|
||
- Trace.STATistic.Func : Display function runtime statistic
|
||
- Trace.STATistic.TREE : Display functions as call tree
|
||
- Trace.STATistic.sYmbol /SplitTASK : Display flat runtime analysis
|
||
- Trace.Chart.Func : Display function timechart
|
||
- Trace.Chart.sYmbol /SplitTASK : Display flat runtime timechart
|
||
|
||
The start of the recording time, when the calculation doesn’t know, which task is running,
|
||
is calculated as "(unknown)".
|
||
|
||
|
||
----------------------------
|
||
LiteOS PRACTICE Functions :
|
||
----------------------------
|
||
There are special definitions for LiteOS specific PRACTICE functions:
|
||
|
||
TASK.CONFIG(magic) : Returns the address of the magic number
|
||
TASK.CONFIG(magicsize) :Returns the size of the magic number
|
||
|