source: rtems/cpukit/libmisc/capture/README @ a29d2e7

4.104.114.84.95
Last change on this file since a29d2e7 was a923a82, checked in by Joel Sherrill <joel.sherrill@…>, on May 15, 2002 at 4:36:10 PM

2002-05-16 Chris Johns <ccj@…>

  • Per PR194, added the Capture engine.
  • capture/Makefile.am, capture/README, capture/capture-cli.c, capture/capture-cli.h, capture/capture.c, capture/capture.h, capture/.cvsignore: New files.
  • Makefile.am, configure.ac, wrapup/Makefile.am: Modified to reflect addition.
  • Property mode set to 100644
File size: 8.1 KB
Line 
1#
2#  $Id$
3#
4
5          RTEMS Performance Monitoring and Measurement Framework
6
7                                      Copyright 2002 Chris Johns (ccj@acm.org)
8                                                                 23 April 2002
9
10This directory contains the source code for the performance monitoring and
11measurement framework. It is more commonly know as the capture engine.
12
13The capture engine is in an early phase of development. Please review the Status
14section of this document for the current status.
15
16Performance.
17
18The capture engine is designed to not effect the system it is
19monitoring. Resources such as memory are used as well as a small performance
20hit in task creation, deletion and context switch. The overhead is small and
21will not be noticed unless the system is operating close to the performance
22limit of the target.
23
24Structure.
25
26The capture engine is implemented in a couple of layers. This lowest layer is
27the capture engine. Its interface is in the file 'capture.h'. Typically this
28interface is directly used unless you are implementing a target interface. The
29user interface is via a target interface.
30
31Command Line Interface (CLI).
32
33This is a target interface that provides a number of user commands via the
34RTEMS monitor. To use you need to provide the following in your
35application initialisation:
36
37  #include <rtems/monitor.h>
38  #include <rtems/capture-cli.h>
39
40  rtems_monitor_init (0);
41  rtems_capture_cli_init (0);
42
43Check the file capture-cli.h for documentation of the interface. The parameter
44is a pointer to your board support package's time stamp handler. The time stamp
45handler is yet to be tested so it is recommended this is left as 0, unless you
46wish to test this part of the engine.
47
48The commands are:
49
50  copen    - Open the capture engine.
51  cclose   - Close the capture engine.
52  cenable  - Enable the capture engine.
53  cdisable - Disable the capture engine.
54  ctlist   - List the tasks known to the capture engine.
55  ctload   - Display the current load (sort of top).
56  cwlist   - List the watch and trigger controls.
57  cwadd    - Add a watch.
58  cwdel    - Delete a watch.
59  cwctl    - Enable or disable a watch.
60  cwglob   - Enable or disable the global watch.
61  cwceil   - Set the watch ceiling.
62  cwfloor  - Set the watch floor.
63  ctrace   - Dump the trace records.
64  ctrig    - Define a trigger.
65
66Open
67
68  usage: copen [-i] size
69
70Open the capture engine. The size parameter is the size of the capture engine
71trace buffer. A single record hold a single event, for example a task create or
72a context in or out. The option '-i' will enable the capture engine after it is
73opened.
74
75Close
76
77  usage: cclose
78
79Close the capture engine and release all resources held by the capture engine.
80
81Enable
82
83  usage: cenable
84
85Enable the capture engine if it has been opened.
86
87Disable
88
89  usage: cdisable
90
91Disable the capture engine. The enable and disable commands provide a means of
92removing the overhead of the capture engine from the context switch. This may
93be needed when testing if it is felt the capture engines overhead is effecting
94the system.
95
96Task List
97
98  usage: ctlist
99
100List the tasks the capture engine knows about. This may contain tasks that have
101been deleted.
102
103Task Load
104
105  usage: ctload
106
107List the tasks in the order of load in a similar way top does on Unix. The
108command sends ANSI terminal codes. You press enter to stop the update. The
109update period is fixed at 5 seconds. The output looks like:
110
111 Press ENTER to exit.
112
113     PID NAME RPRI CPRI STATE  %CPU     %STK FLGS   EXEC TIME
11404010001 IDLE  255  255 READY   96.012%   0% a-----g   1
11508010009 CPlt    1    1 READY    3.815%  15% a------   0
11608010003 ntwk   20   20 Wevnt    0.072%   0% at----g   0
11708010004 CSr0   20   20 Wevnt    0.041%   0% at----g   0
11808010001 main  250  250 DELAY    0.041%   0% a-----g   0
11908010008 test  100  100 Wevnt    0.000%  20% at-T-+g   0
12008010007 test  100  100 Wevnt    0.000%   0% at-T-+g   0
12108010005 CSt0   20   20 Wevnt    0.000%   0% at----g   0
12208010006 RMON    1    1 Wsem     0.000%   0% a------   0
123
124There are 7 flags and from left to right are:
125
1261) 'a' the task is active, and 'd' the task has been deleted.
1272) 't' the task has been traced.
1283) 'F' the task has a from (TO_ANY) trigger.
1294) 'T' the task has a to (FROM_ANY) trigger.
1305) 'E' the task has an edge (FROM_TO) trigger.
1316) '+' the task as a watch control attached, 'w' a watch is enabled.
1327) 'g' the task is part of a global trigger.
133
134The %STK is the percentage of stack used by a task. Currently only tasks
135created while the capture engine is enabled can be monitored.
136
137The RPRI is the real priority. This is the priority set for the task. The
138current priority is the executing priority that may reflect a level set as a
139result of priority inversion.
140
141Watch List
142
143  usage: cwlist
144
145This command lists the watch and trigger controls the capture engine has. A
146control is a structure used by the capture engine to determine if a task is
147watched or triggers capturing.
148
149Watch Add
150
151  usage: cwadd [task name] [id]
152
153Add a watch for a task. You can provide a name or id or both. A name will cause
154all tasks with that name to have the watch added. An id results in a watch
155being for a specific task.
156
157Using a name is useful when the task is not yet created.
158
159Watch Delete
160
161  usage: cwdel [task name] [id]
162
163Delete a watch that has been added.
164
165Watch Control
166
167  usage: cwctl [task name] [id] on/off
168
169Enable or disable a watch. The name and id parameters are the same as the watch
170add command.
171
172Global Watch
173
174  usage: cwglob on/off
175
176Enable or disable the global watch. A global watch is an easy way to enable
177watches for all tasks with real priorities between the watch ceiling and floor
178priorities.
179
180Watch Priority Ceiling
181
182  usage: cwceil priority
183
184Set the watch priority ceiling. All tasks with a priority less than the ceiling
185priority are not watched. This allow you to ignore high priority system and
186driver tasks.
187
188Watch Priority Floor
189
190  usage: cwfloor priority
191
192Set the watch priority floor. All tasks with a priority greater than the floor
193priority level are not watched. This allows you to remove tasks such as IDLE
194from being monitored.
195
196Trace
197
198  usage: ctrace [-c] [-r records]
199
200Dump the trace record. The option '-c' will output the records in comma
201separated variables (CSV). The '-r' option controls the number of records
202dumped. This can help stop the command looping for-ever.
203
204Trigger
205
206 usage: ctrig type [from name] [from id] [to name] [to id]
207
208Set a trigger. The types of triggers are :
209
210 from : trigger on a context switch from a task
211 to   : trigger on a context switch to a task
212 edge : trigger on a context switch from a task to a task
213
214The from and to trigger types requires a task name or task id or both be
215provided. The edge requires a from name and/or id and a to name and/or id be
216provided.
217
218Flush
219
220  usage: cflush [-n]
221
222Flush the trace record. The option '-n' stops the capture engine be
223primed. This means an exising trigger state will not be cleared and tracing
224will continue.
225
226Status.
227
228The following is a list of outstanding issues or bugs.
229
2301) The capture engine does not scan the existing list of tasks in the kernel
231   when initialised. This means tasks that exist but are not active are not
232   seen. Not sure how to implement this one.
233
2342) The blocking read of trace records has not been completely implemented or
235   tested.  This will wait until I complete the csv support for the cli for a
236   serial UI or the tcp server is implemented.
237
2383) Task control block clean up is not implemented. The control block should be
239   dumped to the trace buffer. This requires extended record formats. This can
240   be implemented using an event flag to indicate an extended record follows
241   the trace record. This would allow a task delete record to be directly
242   followed by the task information.
243
2444) Complete csv (comma separated variable) support for the CLI.
245
2465) Implement a tcp server interface.
247
2486) Complete the capture engine API documentation.
249
2507) Test the user supplied time stamp handler.
251
2528) Task name support is only for the rtems_name type. This means the only the
253   classic API tasks are currently supported. Partial support for the different
254   task names is provided how-ever this is not clean and does not support the
255   variable length task name such as found in the POSIX tasks.
Note: See TracBrowser for help on using the repository browser.