1 |
1026 |
ivang |
#
|
2 |
|
|
# README,v 1.1 2002/05/15 16:35:56 joel Exp
|
3 |
|
|
#
|
4 |
|
|
|
5 |
|
|
RTEMS Performance Monitoring and Measurement Framework
|
6 |
|
|
|
7 |
|
|
Copyright 2002 Chris Johns (ccj@acm.org)
|
8 |
|
|
23 April 2002
|
9 |
|
|
|
10 |
|
|
This directory contains the source code for the performance monitoring and
|
11 |
|
|
measurement framework. It is more commonly know as the capture engine.
|
12 |
|
|
|
13 |
|
|
The capture engine is in an early phase of development. Please review the Status
|
14 |
|
|
section of this document for the current status.
|
15 |
|
|
|
16 |
|
|
Performance.
|
17 |
|
|
|
18 |
|
|
The capture engine is designed to not effect the system it is
|
19 |
|
|
monitoring. Resources such as memory are used as well as a small performance
|
20 |
|
|
hit in task creation, deletion and context switch. The overhead is small and
|
21 |
|
|
will not be noticed unless the system is operating close to the performance
|
22 |
|
|
limit of the target.
|
23 |
|
|
|
24 |
|
|
Structure.
|
25 |
|
|
|
26 |
|
|
The capture engine is implemented in a couple of layers. This lowest layer is
|
27 |
|
|
the capture engine. Its interface is in the file 'capture.h'. Typically this
|
28 |
|
|
interface is directly used unless you are implementing a target interface. The
|
29 |
|
|
user interface is via a target interface.
|
30 |
|
|
|
31 |
|
|
Command Line Interface (CLI).
|
32 |
|
|
|
33 |
|
|
This is a target interface that provides a number of user commands via the
|
34 |
|
|
RTEMS monitor. To use you need to provide the following in your
|
35 |
|
|
application initialisation:
|
36 |
|
|
|
37 |
|
|
#include
|
38 |
|
|
#include
|
39 |
|
|
|
40 |
|
|
rtems_monitor_init (0);
|
41 |
|
|
rtems_capture_cli_init (0);
|
42 |
|
|
|
43 |
|
|
Check the file capture-cli.h for documentation of the interface. The parameter
|
44 |
|
|
is a pointer to your board support package's time stamp handler. The time stamp
|
45 |
|
|
handler is yet to be tested so it is recommended this is left as 0, unless you
|
46 |
|
|
wish to test this part of the engine.
|
47 |
|
|
|
48 |
|
|
The 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 |
|
|
|
66 |
|
|
Open
|
67 |
|
|
|
68 |
|
|
usage: copen [-i] size
|
69 |
|
|
|
70 |
|
|
Open the capture engine. The size parameter is the size of the capture engine
|
71 |
|
|
trace buffer. A single record hold a single event, for example a task create or
|
72 |
|
|
a context in or out. The option '-i' will enable the capture engine after it is
|
73 |
|
|
opened.
|
74 |
|
|
|
75 |
|
|
Close
|
76 |
|
|
|
77 |
|
|
usage: cclose
|
78 |
|
|
|
79 |
|
|
Close the capture engine and release all resources held by the capture engine.
|
80 |
|
|
|
81 |
|
|
Enable
|
82 |
|
|
|
83 |
|
|
usage: cenable
|
84 |
|
|
|
85 |
|
|
Enable the capture engine if it has been opened.
|
86 |
|
|
|
87 |
|
|
Disable
|
88 |
|
|
|
89 |
|
|
usage: cdisable
|
90 |
|
|
|
91 |
|
|
Disable the capture engine. The enable and disable commands provide a means of
|
92 |
|
|
removing the overhead of the capture engine from the context switch. This may
|
93 |
|
|
be needed when testing if it is felt the capture engines overhead is effecting
|
94 |
|
|
the system.
|
95 |
|
|
|
96 |
|
|
Task List
|
97 |
|
|
|
98 |
|
|
usage: ctlist
|
99 |
|
|
|
100 |
|
|
List the tasks the capture engine knows about. This may contain tasks that have
|
101 |
|
|
been deleted.
|
102 |
|
|
|
103 |
|
|
Task Load
|
104 |
|
|
|
105 |
|
|
usage: ctload
|
106 |
|
|
|
107 |
|
|
List the tasks in the order of load in a similar way top does on Unix. The
|
108 |
|
|
command sends ANSI terminal codes. You press enter to stop the update. The
|
109 |
|
|
update 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
|
114 |
|
|
04010001 IDLE 255 255 READY 96.012% 0% a-----g 1
|
115 |
|
|
08010009 CPlt 1 1 READY 3.815% 15% a------ 0
|
116 |
|
|
08010003 ntwk 20 20 Wevnt 0.072% 0% at----g 0
|
117 |
|
|
08010004 CSr0 20 20 Wevnt 0.041% 0% at----g 0
|
118 |
|
|
08010001 main 250 250 DELAY 0.041% 0% a-----g 0
|
119 |
|
|
08010008 test 100 100 Wevnt 0.000% 20% at-T-+g 0
|
120 |
|
|
08010007 test 100 100 Wevnt 0.000% 0% at-T-+g 0
|
121 |
|
|
08010005 CSt0 20 20 Wevnt 0.000% 0% at----g 0
|
122 |
|
|
08010006 RMON 1 1 Wsem 0.000% 0% a------ 0
|
123 |
|
|
|
124 |
|
|
There are 7 flags and from left to right are:
|
125 |
|
|
|
126 |
|
|
1) 'a' the task is active, and 'd' the task has been deleted.
|
127 |
|
|
2) 't' the task has been traced.
|
128 |
|
|
3) 'F' the task has a from (TO_ANY) trigger.
|
129 |
|
|
4) 'T' the task has a to (FROM_ANY) trigger.
|
130 |
|
|
5) 'E' the task has an edge (FROM_TO) trigger.
|
131 |
|
|
6) '+' the task as a watch control attached, 'w' a watch is enabled.
|
132 |
|
|
7) 'g' the task is part of a global trigger.
|
133 |
|
|
|
134 |
|
|
The %STK is the percentage of stack used by a task. Currently only tasks
|
135 |
|
|
created while the capture engine is enabled can be monitored.
|
136 |
|
|
|
137 |
|
|
The RPRI is the real priority. This is the priority set for the task. The
|
138 |
|
|
current priority is the executing priority that may reflect a level set as a
|
139 |
|
|
result of priority inversion.
|
140 |
|
|
|
141 |
|
|
Watch List
|
142 |
|
|
|
143 |
|
|
usage: cwlist
|
144 |
|
|
|
145 |
|
|
This command lists the watch and trigger controls the capture engine has. A
|
146 |
|
|
control is a structure used by the capture engine to determine if a task is
|
147 |
|
|
watched or triggers capturing.
|
148 |
|
|
|
149 |
|
|
Watch Add
|
150 |
|
|
|
151 |
|
|
usage: cwadd [task name] [id]
|
152 |
|
|
|
153 |
|
|
Add a watch for a task. You can provide a name or id or both. A name will cause
|
154 |
|
|
all tasks with that name to have the watch added. An id results in a watch
|
155 |
|
|
being for a specific task.
|
156 |
|
|
|
157 |
|
|
Using a name is useful when the task is not yet created.
|
158 |
|
|
|
159 |
|
|
Watch Delete
|
160 |
|
|
|
161 |
|
|
usage: cwdel [task name] [id]
|
162 |
|
|
|
163 |
|
|
Delete a watch that has been added.
|
164 |
|
|
|
165 |
|
|
Watch Control
|
166 |
|
|
|
167 |
|
|
usage: cwctl [task name] [id] on/off
|
168 |
|
|
|
169 |
|
|
Enable or disable a watch. The name and id parameters are the same as the watch
|
170 |
|
|
add command.
|
171 |
|
|
|
172 |
|
|
Global Watch
|
173 |
|
|
|
174 |
|
|
usage: cwglob on/off
|
175 |
|
|
|
176 |
|
|
Enable or disable the global watch. A global watch is an easy way to enable
|
177 |
|
|
watches for all tasks with real priorities between the watch ceiling and floor
|
178 |
|
|
priorities.
|
179 |
|
|
|
180 |
|
|
Watch Priority Ceiling
|
181 |
|
|
|
182 |
|
|
usage: cwceil priority
|
183 |
|
|
|
184 |
|
|
Set the watch priority ceiling. All tasks with a priority less than the ceiling
|
185 |
|
|
priority are not watched. This allow you to ignore high priority system and
|
186 |
|
|
driver tasks.
|
187 |
|
|
|
188 |
|
|
Watch Priority Floor
|
189 |
|
|
|
190 |
|
|
usage: cwfloor priority
|
191 |
|
|
|
192 |
|
|
Set the watch priority floor. All tasks with a priority greater than the floor
|
193 |
|
|
priority level are not watched. This allows you to remove tasks such as IDLE
|
194 |
|
|
from being monitored.
|
195 |
|
|
|
196 |
|
|
Trace
|
197 |
|
|
|
198 |
|
|
usage: ctrace [-c] [-r records]
|
199 |
|
|
|
200 |
|
|
Dump the trace record. The option '-c' will output the records in comma
|
201 |
|
|
separated variables (CSV). The '-r' option controls the number of records
|
202 |
|
|
dumped. This can help stop the command looping for-ever.
|
203 |
|
|
|
204 |
|
|
Trigger
|
205 |
|
|
|
206 |
|
|
usage: ctrig type [from name] [from id] [to name] [to id]
|
207 |
|
|
|
208 |
|
|
Set 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 |
|
|
|
214 |
|
|
The from and to trigger types requires a task name or task id or both be
|
215 |
|
|
provided. The edge requires a from name and/or id and a to name and/or id be
|
216 |
|
|
provided.
|
217 |
|
|
|
218 |
|
|
Flush
|
219 |
|
|
|
220 |
|
|
usage: cflush [-n]
|
221 |
|
|
|
222 |
|
|
Flush the trace record. The option '-n' stops the capture engine be
|
223 |
|
|
primed. This means an exising trigger state will not be cleared and tracing
|
224 |
|
|
will continue.
|
225 |
|
|
|
226 |
|
|
Status.
|
227 |
|
|
|
228 |
|
|
The following is a list of outstanding issues or bugs.
|
229 |
|
|
|
230 |
|
|
1) 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 |
|
|
|
234 |
|
|
2) 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 |
|
|
|
238 |
|
|
3) 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 |
|
|
|
244 |
|
|
4) Complete csv (comma separated variable) support for the CLI.
|
245 |
|
|
|
246 |
|
|
5) Implement a tcp server interface.
|
247 |
|
|
|
248 |
|
|
6) Complete the capture engine API documentation.
|
249 |
|
|
|
250 |
|
|
7) Test the user supplied time stamp handler.
|
251 |
|
|
|
252 |
|
|
8) 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.
|