diff options
Diffstat (limited to 'c/src/libmisc/capture/README')
| -rw-r--r-- | c/src/libmisc/capture/README | 255 |
1 files changed, 0 insertions, 255 deletions
diff --git a/c/src/libmisc/capture/README b/c/src/libmisc/capture/README deleted file mode 100644 index 2ea76a4cfe..0000000000 --- a/c/src/libmisc/capture/README +++ /dev/null @@ -1,255 +0,0 @@ -# -# $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. |