diff options
Diffstat (limited to 'cpukit/libmisc/capture/README')
| -rw-r--r-- | cpukit/libmisc/capture/README | 255 |
1 files changed, 255 insertions, 0 deletions
diff --git a/cpukit/libmisc/capture/README b/cpukit/libmisc/capture/README new file mode 100644 index 0000000000..2ea76a4cfe --- /dev/null +++ b/cpukit/libmisc/capture/README @@ -0,0 +1,255 @@ +# +# $Id$ +# + + RTEMS Performance Monitoring and Measurement Framework + + Copyright 2002 Chris Johns (ccj@acm.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. |