Warning, /cpukit/libmisc/capture/README.md is written in an unsupported language. File is not indexed.
0001 libmisc
0002 =======
0003
0004 RTEMS Performance Monitoring and Measurement Framework
0005
0006 Copyright 2002-2007 Chris Johns (chrisj@rtems.org)
0007 23 April 2002
0008
0009 This directory contains the source code for the performance monitoring and
0010 measurement framework. It is more commonly know as the capture engine.
0011
0012 The capture engine is in an early phase of development. Please review the Status
0013 section of this document for the current status.
0014
0015 Performance.
0016
0017 The capture engine is designed to not effect the system it is
0018 monitoring. Resources such as memory are used as well as a small performance
0019 hit in task creation, deletion and context switch. The overhead is small and
0020 will not be noticed unless the system is operating close to the performance
0021 limit of the target.
0022
0023 Structure.
0024
0025 The capture engine is implemented in a couple of layers. This lowest layer is
0026 the capture engine. Its interface is in the file 'capture.h'. Typically this
0027 interface is directly used unless you are implementing a target interface. The
0028 user interface is via a target interface.
0029
0030 Command Line Interface (CLI).
0031
0032 This is a target interface that provides a number of user commands via the
0033 RTEMS monitor. To use you need to provide the following in your
0034 application initialisation:
0035
0036 ```c
0037 #include <rtems/monitor.h>
0038 #include <rtems/capture-cli.h>
0039
0040 rtems_monitor_init (0);
0041 rtems_capture_cli_init (0);
0042 ```
0043
0044 Check the file capture-cli.h for documentation of the interface. The parameter
0045 is a pointer to your board support package's time stamp handler. The time stamp
0046 handler is yet to be tested so it is recommended this is left as 0, unless you
0047 wish to test this part of the engine.
0048
0049 The commands are:
0050
0051 copen - Open the capture engine.
0052 cclose - Close the capture engine.
0053 cenable - Enable the capture engine.
0054 cdisable - Disable the capture engine.
0055 ctlist - List the tasks known to the capture engine.
0056 ctload - Display the current load (sort of top).
0057 cwlist - List the watch and trigger controls.
0058 cwadd - Add a watch.
0059 cwdel - Delete a watch.
0060 cwctl - Enable or disable a watch.
0061 cwglob - Enable or disable the global watch.
0062 cwceil - Set the watch ceiling.
0063 cwfloor - Set the watch floor.
0064 ctrace - Dump the trace records.
0065 ctrig - Define a trigger.
0066
0067 Open
0068
0069 usage: copen [-i] size
0070
0071 Open the capture engine. The size parameter is the size of the capture engine
0072 trace buffer. A single record hold a single event, for example a task create or
0073 a context in or out. The option '-i' will enable the capture engine after it is
0074 opened.
0075
0076 Close
0077
0078 usage: cclose
0079
0080 Close the capture engine and release all resources held by the capture engine.
0081
0082 Enable
0083
0084 usage: cenable
0085
0086 Enable the capture engine if it has been opened.
0087
0088 Disable
0089
0090 usage: cdisable
0091
0092 Disable the capture engine. The enable and disable commands provide a means of
0093 removing the overhead of the capture engine from the context switch. This may
0094 be needed when testing if it is felt the capture engines overhead is effecting
0095 the system.
0096
0097 Task List
0098
0099 usage: ctlist
0100
0101 List the tasks the capture engine knows about. This may contain tasks that have
0102 been deleted.
0103
0104 Task Load
0105
0106 usage: ctload
0107
0108 List the tasks in the order of load in a similar way top does on Unix. The
0109 command sends ANSI terminal codes. You press enter to stop the update. The
0110 update period is fixed at 5 seconds. The output looks like:
0111
0112 Press ENTER to exit.
0113
0114 PID NAME RPRI CPRI STATE %CPU %STK FLGS EXEC TIME
0115 04010001 IDLE 255 255 READY 96.012% 0% a-----g 1
0116 08010009 CPlt 1 1 READY 3.815% 15% a------ 0
0117 08010003 ntwk 20 20 Wevnt 0.072% 0% at----g 0
0118 08010004 CSr0 20 20 Wevnt 0.041% 0% at----g 0
0119 08010001 main 250 250 DELAY 0.041% 0% a-----g 0
0120 08010008 test 100 100 Wevnt 0.000% 20% at-T-+g 0
0121 08010007 test 100 100 Wevnt 0.000% 0% at-T-+g 0
0122 08010005 CSt0 20 20 Wevnt 0.000% 0% at----g 0
0123 08010006 RMON 1 1 Wsem 0.000% 0% a------ 0
0124
0125 There are 7 flags and from left to right are:
0126
0127 1) 'a' the task is active, and 'd' the task has been deleted.
0128 2) 't' the task has been traced.
0129 3) 'F' the task has a from (TO_ANY) trigger.
0130 4) 'T' the task has a to (FROM_ANY) trigger.
0131 5) 'E' the task has an edge (FROM_TO) trigger.
0132 6) '+' the task as a watch control attached, 'w' a watch is enabled.
0133 7) 'g' the task is part of a global trigger.
0134
0135 The %STK is the percentage of stack used by a task. Currently only tasks
0136 created while the capture engine is enabled can be monitored.
0137
0138 The RPRI is the real priority. This is the priority set for the task. The
0139 current priority is the executing priority that may reflect a level set as a
0140 result of priority inversion.
0141
0142 Watch List
0143
0144 usage: cwlist
0145
0146 This command lists the watch and trigger controls the capture engine has. A
0147 control is a structure used by the capture engine to determine if a task is
0148 watched or triggers capturing.
0149
0150 Watch Add
0151
0152 usage: cwadd [task name] [id]
0153
0154 Add a watch for a task. You can provide a name or id or both. A name will cause
0155 all tasks with that name to have the watch added. An id results in a watch
0156 being for a specific task.
0157
0158 Using a name is useful when the task is not yet created.
0159
0160 Watch Delete
0161
0162 usage: cwdel [task name] [id]
0163
0164 Delete a watch that has been added.
0165
0166 Watch Control
0167
0168 usage: cwctl [task name] [id] on/off
0169
0170 Enable or disable a watch. The name and id parameters are the same as the watch
0171 add command.
0172
0173 Global Watch
0174
0175 usage: cwglob on/off
0176
0177 Enable or disable the global watch. A global watch is an easy way to enable
0178 watches for all tasks with real priorities between the watch ceiling and floor
0179 priorities.
0180
0181 Watch Priority Ceiling
0182
0183 usage: cwceil priority
0184
0185 Set the watch priority ceiling. All tasks with a priority less than the ceiling
0186 priority are not watched. This allow you to ignore high priority system and
0187 driver tasks.
0188
0189 Watch Priority Floor
0190
0191 usage: cwfloor priority
0192
0193 Set the watch priority floor. All tasks with a priority greater than the floor
0194 priority level are not watched. This allows you to remove tasks such as IDLE
0195 from being monitored.
0196
0197 Trace
0198
0199 usage: ctrace [-c] [-r records]
0200
0201 Dump the trace record. The option '-c' will output the records in comma
0202 separated variables (CSV). The '-r' option controls the number of records
0203 dumped. This can help stop the command looping for-ever.
0204
0205 Trigger
0206
0207 usage: ctrig type [from name] [from id] [to name] [to id]
0208
0209 Set a trigger. The types of triggers are :
0210
0211 from : trigger on a context switch from a task
0212 to : trigger on a context switch to a task
0213 edge : trigger on a context switch from a task to a task
0214
0215 The from and to trigger types requires a task name or task id or both be
0216 provided. The edge requires a from name and/or id and a to name and/or id be
0217 provided.
0218
0219 Flush
0220
0221 usage: cflush [-n]
0222
0223 Flush the trace record. The option '-n' stops the capture engine be
0224 primed. This means an exising trigger state will not be cleared and tracing
0225 will continue.
0226
0227 Status.
0228
0229 The following is a list of outstanding issues or bugs.
0230
0231 1) The capture engine does not scan the existing list of tasks in the kernel
0232 when initialised. This means tasks that exist but are not active are not
0233 seen. Not sure how to implement this one.
0234
0235 2) The blocking read of trace records has not been completely implemented or
0236 tested. This will wait until I complete the csv support for the cli for a
0237 serial UI or the tcp server is implemented.
0238
0239 3) Task control block clean up is not implemented. The control block should be
0240 dumped to the trace buffer. This requires extended record formats. This can
0241 be implemented using an event flag to indicate an extended record follows
0242 the trace record. This would allow a task delete record to be directly
0243 followed by the task information.
0244
0245 4) Complete csv (comma separated variable) support for the CLI.
0246
0247 5) Implement a tcp server interface.
0248
0249 6) Complete the capture engine API documentation.
0250
0251 7) Test the user supplied time stamp handler.
0252
0253 8) Task name support is only for the rtems_name type. This means the only the
0254 classic API tasks are currently supported. Partial support for the different
0255 task names is provided how-ever this is not clean and does not support the
0256 variable length task name such as found in the POSIX tasks.
