Capture Engine

Capture Engine

The Capture Engine is a software module that captures context switches to a buffer to allow post analysis. The software is located in the <kbd>cpukit/libmisc/capture</kbd>. To use you need add initialisation calls to your <kbd>Init</tt> task.

The Capture Engine has the folowing features:

• Works on all targets RTEMS supports,

• The user interface and the engine are separate allowing the addition of new user interfaces,

• Compact data format allowing streaming of data to an external reporting program,

• Flexible set of filters gives you the ability to view only the task switches you are interested in,

• Flexible and powerful triggers allow you the ability to focus on your specific problem,

• Ability to add a high resolution timer.

The Capture Engine has a Command Line Interface (CLI). The CLI is available from the RTEMS monitor prompt.

Capture Engine CLI

To access the CLI add the following to your Init task:

#include <rtems/monitor.h> #include <rtems/capture-cli.h>

rtems_monitor_init (0); rtems_capture_cli_init (0);

The CLI uses the RTEMS monitor and this typcially has the highest priority so you should be able to get a trace of tasks looping or an interrupt overloading a task. The CLI has the following commands:

#copen: Open the capture engine. #cclose: Close the capture engine. #cenable: Enable the capture engine. #cdisable: Disable the capture engine. #ctlist: List the tasks known to the capture engine. #ctload: Display the current load (sort of top). #cwlist: List the watch and trigger controls. #cwadd: Add a watch. #cwdel: Delete a watch. #cwctl: Enable or disable a watch. #cwglob: Enable or disable the global watch. #cwceil: Set the watch ceiling. #cwfloor: Set the watch floor. #ctrace: Dump the trace records. #ctrig: Define a trigger.

If the capture engine fails to start you may need to change your RTEMS configuration increasing the number of user extensions:

#define CONFIGURE_MAXIMUM_USER_EXTENSIONS 4

copen: Open the capture engine

usage: copen [-i] size

Open the capture engine. The size parameter is the size of the capture engine trace buffer. A single record hold a single event, for example a task create or a context in or out. The option '-i' will enable the capture engine after it is opened.

cclose: Close the capture engine.

usage: cclose

Close the capture engine and release all resources held by the capture engine.

cenable: Enable the capture engine.

usage: cenable

Enable the capture engine if it has been opened.

cdisable: Disable the capture engine.

usage: cdisable

Disable the capture engine. The enable and disable commands provide a means of removing the overhead of the capture engine from the context switch. This may be needed when testing if it is felt the capture engines overhead is effecting the system.

ctlist: List the tasks known to the capture engine.

usage: ctlist

List the tasks the capture engine knows about. This may contain tasks that have been deleted.

ctload: Display the current load (sort of top).

usage: ctload

List the tasks in the order of load in a similar way top does on Unix. The command sends ANSI terminal codes. You press enter to stop the update. The update period is fixed at 5 seconds. The output looks like:

Press ENTER to exit.

PID NAME RPRI CPRI STATE %CPU %STK FLGS EXEC TIME

04010001 IDLE 255 255 READY 96.012% 0% a-----g 1 08010009 CPlt 1 1 READY 3.815% 15% a------ 0 08010003 ntwk 20 20 Wevnt 0.072% 0% at----g 0 08010004 CSr0 20 20 Wevnt 0.041% 0% at----g 0 08010001 main 250 250 DELAY 0.041% 0% a-----g 0 08010008 test 100 100 Wevnt 0.000% 20% at-T-+g 0 08010007 test 100 100 Wevnt 0.000% 0% at-T-+g 0 08010005 CSt0 20 20 Wevnt 0.000% 0% at----g 0 08010006 RMON 1 1 Wsem 0.000% 0% a------ 0

There are 7 flags and from left to right are:

#'a' the task is active, and 'd' the task has been deleted. #'t' the task has been traced. #'F' the task has a from (TO_ANY) trigger. #'T' the task has a to (FROM_ANY) trigger. #'E' the task has an edge (FROM_TO) trigger. #'+' the task has a watch control attached, 'w' a watch is enabled. #'g' the task is part of a global trigger.

The %STK is the percentage of stack used by a task. Currently only tasks created while the capture engine is enabled can be monitored.

The RPRI is the real priority. This is the priority set for the task. The current priority is the executing priority that may reflect a level set as a result of priority inversion.

cwlist: List the watch and trigger controls.

usage: cwlist

This command lists the watch and trigger controls the capture engine has. A control is a structure used by the capture engine to determine if a task is watched or triggers capturing.

cwadd: Add a watch.

usage: cwadd [task name] [id]

Add a watch for a task. You can provide a name or id or both. A name will cause all tasks with that name to have the watch added. An id results in a watch being for a specific task.

Using a name is useful when the task is not yet created.

cwdel: Delete a watch.

usage: cwdel [task name] [id]

Delete a watch that has been added.

cwctl: Enable or disable a watch.

usage: cwctl [task name] [id] on/off

Enable or disable the global watch. A global watch is an easy way to enable watches for all tasks with real priorities between the watch ceiling and floor priorities.

cwglob: Enable or disable the global watch.

usage: cwglob on/off

Enable or disable the global watch. A global watch is an easy way to enable watches for all tasks with real priorities between the watch ceiling and floor priorities.

cwceil: Set the watch ceiling.

usage: cwceil priority

Set the watch priority ceiling. All tasks with a priority less than the ceiling priority are not watched. This allow you to ignore high priority system and driver tasks.

cwfloor: Set the watch floor.

usage: cwfloor priority

Set the watch priority floor. All tasks with a priority greater than the floor priority level are not watched. This allows you to remove tasks such as IDLE from being monitored.

ctrace: Dump the trace records.

usage: ctrace [-c] [-r records]

Dump the trace record. The option '-c' will output the records in comma separated variables (CSV). The '-r' option controls the number of records dumped. This can help stop the command looping for-ever.

ctrig: Define a trigger.

usage: ctrig type [from name] [from id] [to name] [to id]

Set a trigger. The types of triggers are :

from : trigger on a context switch from a task
to : trigger on a context switch to a task
edge : trigger on a context switch from a task to a task

The from and to trigger types requires a task name or task id or both be provided. The edge requires a from name and/or id and a to name and/or id be provided.

RTEMS Trace Tool

To find out more info on the rtems-trace tool access this link?.