forked from Imagelibrary/rtems
9b4422a251
Script does what is expected and tries to do it as smartly as possible. + remove occurrences of two blank comment lines next to each other after Id string line removed. + remove entire comment blocks which only exited to contain CVS Ids + If the processing left a blank line at the top of a file, it was removed.
252 lines
8.1 KiB
Plaintext
252 lines
8.1 KiB
Plaintext
RTEMS Performance Monitoring and Measurement Framework
|
|
|
|
Copyright 2002-2007 Chris Johns (chrisj@rtems.org)
|
|
23 April 2002
|
|
|
|
This directory contains the source code for the performance monitoring and
|
|
measurement framework. It is more commonly know as the capture engine.
|
|
|
|
The capture engine is in an early phase of development. Please review the Status
|
|
section of this document for the current status.
|
|
|
|
Performance.
|
|
|
|
The capture engine is designed to not effect the system it is
|
|
monitoring. Resources such as memory are used as well as a small performance
|
|
hit in task creation, deletion and context switch. The overhead is small and
|
|
will not be noticed unless the system is operating close to the performance
|
|
limit of the target.
|
|
|
|
Structure.
|
|
|
|
The capture engine is implemented in a couple of layers. This lowest layer is
|
|
the capture engine. Its interface is in the file 'capture.h'. Typically this
|
|
interface is directly used unless you are implementing a target interface. The
|
|
user interface is via a target interface.
|
|
|
|
Command Line Interface (CLI).
|
|
|
|
This is a target interface that provides a number of user commands via the
|
|
RTEMS monitor. To use you need to provide the following in your
|
|
application initialisation:
|
|
|
|
#include <rtems/monitor.h>
|
|
#include <rtems/capture-cli.h>
|
|
|
|
rtems_monitor_init (0);
|
|
rtems_capture_cli_init (0);
|
|
|
|
Check the file capture-cli.h for documentation of the interface. The parameter
|
|
is a pointer to your board support package's time stamp handler. The time stamp
|
|
handler is yet to be tested so it is recommended this is left as 0, unless you
|
|
wish to test this part of the engine.
|
|
|
|
The commands are:
|
|
|
|
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.
|
|
|
|
Open
|
|
|
|
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.
|
|
|
|
Close
|
|
|
|
usage: cclose
|
|
|
|
Close the capture engine and release all resources held by the capture engine.
|
|
|
|
Enable
|
|
|
|
usage: cenable
|
|
|
|
Enable the capture engine if it has been opened.
|
|
|
|
Disable
|
|
|
|
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.
|
|
|
|
Task List
|
|
|
|
usage: ctlist
|
|
|
|
List the tasks the capture engine knows about. This may contain tasks that have
|
|
been deleted.
|
|
|
|
Task Load
|
|
|
|
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:
|
|
|
|
1) 'a' the task is active, and 'd' the task has been deleted.
|
|
2) 't' the task has been traced.
|
|
3) 'F' the task has a from (TO_ANY) trigger.
|
|
4) 'T' the task has a to (FROM_ANY) trigger.
|
|
5) 'E' the task has an edge (FROM_TO) trigger.
|
|
6) '+' the task as a watch control attached, 'w' a watch is enabled.
|
|
7) '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.
|
|
|
|
Watch List
|
|
|
|
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.
|
|
|
|
Watch Add
|
|
|
|
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.
|
|
|
|
Watch Delete
|
|
|
|
usage: cwdel [task name] [id]
|
|
|
|
Delete a watch that has been added.
|
|
|
|
Watch Control
|
|
|
|
usage: cwctl [task name] [id] on/off
|
|
|
|
Enable or disable a watch. The name and id parameters are the same as the watch
|
|
add command.
|
|
|
|
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.
|
|
|
|
Watch Priority 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.
|
|
|
|
Watch Priority 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.
|
|
|
|
Trace
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Flush
|
|
|
|
usage: cflush [-n]
|
|
|
|
Flush the trace record. The option '-n' stops the capture engine be
|
|
primed. This means an exising trigger state will not be cleared and tracing
|
|
will continue.
|
|
|
|
Status.
|
|
|
|
The following is a list of outstanding issues or bugs.
|
|
|
|
1) The capture engine does not scan the existing list of tasks in the kernel
|
|
when initialised. This means tasks that exist but are not active are not
|
|
seen. Not sure how to implement this one.
|
|
|
|
2) The blocking read of trace records has not been completely implemented or
|
|
tested. This will wait until I complete the csv support for the cli for a
|
|
serial UI or the tcp server is implemented.
|
|
|
|
3) Task control block clean up is not implemented. The control block should be
|
|
dumped to the trace buffer. This requires extended record formats. This can
|
|
be implemented using an event flag to indicate an extended record follows
|
|
the trace record. This would allow a task delete record to be directly
|
|
followed by the task information.
|
|
|
|
4) Complete csv (comma separated variable) support for the CLI.
|
|
|
|
5) Implement a tcp server interface.
|
|
|
|
6) Complete the capture engine API documentation.
|
|
|
|
7) Test the user supplied time stamp handler.
|
|
|
|
8) Task name support is only for the rtems_name type. This means the only the
|
|
classic API tasks are currently supported. Partial support for the different
|
|
task names is provided how-ever this is not clean and does not support the
|
|
variable length task name such as found in the POSIX tasks.
|