]>
Commit | Line | Data |
---|---|---|
6e0c15da FCE |
1 | * What's new in version 1.5 |
2 | ||
710a2a45 SC |
3 | - Compiler optimization may sometimes result in systemtap not being able to |
4 | access a user-space probe argument. Compiling the application with | |
5 | -DSTAP_SDT_ARG_CONSTRAINT=nr will force the argument to be an immediate or | |
6 | register value which should enable systemtap to access the argument. | |
7 | ||
2a990836 LB |
8 | - GNU Gettext has now been intergrated with systemtap. Our translation |
9 | page can be found at http://www.transifex.net/projects/p/systemtap/ . | |
10 | "make update-po" will generate the necessary files to use translated | |
11 | messages. Please refer to the po/README file for more info and | |
12 | please consider contributing to this I18N effort! | |
13 | ||
bf8e91d0 JS |
14 | - The new addr() function returns the probe's instruction pointer. |
15 | ||
b73a1293 SC |
16 | - process("...").library("...") probes are now supported. Wildcards |
17 | are supported in the library-name part, to refer to any shared | |
18 | library that is required by process-name, which matches the glob | |
19 | pattern and the rest of the probe point. | |
20 | ||
b9d64db6 JS |
21 | - The "--remote USER@HOST" functionality can now be specified multiple times |
22 | to fan out on multiple targets. If the targets have distinct kernel and | |
23 | architecture configurations, stap will automatically build the script | |
24 | appropriately for each one. This option is also no longer considered | |
25 | experimental. | |
26 | ||
e96e9380 DB |
27 | - The NSS certificate database generated for use by the compile server is now |
28 | generated with no password. Previously, a random password was generated and | |
29 | used to access the database. This change should be transparent to most users. | |
30 | However, if you are prompted for a password when using systemtap, then | |
31 | running $libexecdir/stap-gen-cert should correct the problem. | |
32 | ||
798cba32 FCE |
33 | - The timestamp tapset includes jiffies() and HZ() for lightweight approximate |
34 | timekeeping. | |
35 | ||
4ce43c59 FCE |
36 | - A powerful new command line option --version has been added. |
37 | ||
c2807b0b SC |
38 | - process.mark now supports $$parms for reading probe parameters. |
39 | ||
cc28ec4f FCE |
40 | - A new command line option, --use-server-on-error[=yes|no] is available |
41 | for stap. It instructs stap to retry compilation of a script using a | |
42 | compile server if it fails on the local host. The default setting | |
43 | is 'no'. | |
ce286ff0 | 44 | |
1114c4f2 DB |
45 | - The following deprecated tools have been removed: |
46 | stap-client | |
47 | stap-authorize-server-cert | |
48 | stap-authorize-signing-cert | |
49 | stap-find-or-start-server | |
50 | stap-find-servers | |
51 | Use the --use-server, --trust-server and --list-servers options of stap | |
cc28ec4f | 52 | instead. |
6e0c15da | 53 | |
c36cb86a | 54 | * What's new in version 1.4, 2011-01-17 |
051bc1a0 | 55 | |
02f44009 DB |
56 | - A new /* myproc-unprivileged */ marker is now available for embedded C |
57 | code and and expressions. Like the /* unprivileged */ marker, it makes | |
58 | the code or expression available for use in unprivileged mode (see | |
59 | --unprivileged). However, it also automatically adds a call to | |
60 | assert_is_myproc() to the code or expression, thus, making it available | |
61 | to the unprivileged user only if the target of the current probe is within | |
62 | the user's own process. | |
63 | ||
e37d61db FCE |
64 | - The experimental "--remote USER@HOST" option will run pass 5 on a given |
65 | ssh host, after building locally (or with --use-server) for that target. | |
6eb5c1a1 | 66 | |
8358a79c FCE |
67 | - Warning messages from the script may now be suppressed with the stap |
68 | and/or staprun -w option. By default, duplicate warning messages are | |
69 | suppressed (up to a certain limit). With stap --vp 00002 and above, | |
70 | the duplicate elimination is defeated. | |
71 | ||
35f71b69 FCE |
72 | - The print_ubacktrace and usym* functions attempt to print the full |
73 | path of the user-space binaries' paths, instead of just the basename. | |
74 | The maximum saved path length is set by -DTASK_FINDER_VMA_ENTRY_PATHLEN, | |
121d2e8f FCE |
75 | default 64. Warning messages are produced if unwinding fails due to |
76 | a missing 'stap -d MODULE' option, providing preloaded unwind data. | |
35f71b69 | 77 | |
d62c7736 FCE |
78 | - The new tz_ctime() tapset function prints times in the local time zone. |
79 | ||
685087ea FCE |
80 | - More kernel tracepoints are accessible to the kernel.trace("...") mechanism, |
81 | if kernel source trees or debuginfo are available. These formerly "hidden" | |
82 | tracepoints are those that are declared somewhere other than the usual | |
83 | include/linux/trace/ headers, such as xfs and kvm. | |
84 | ||
c480f651 FCE |
85 | - debuginfo-based process("...").function/.statement/.mark probes support |
86 | wildcards in the process-name part, to refer to any executable files that | |
87 | match the glob pattern and the rest of the probe point. | |
c3c5e2eb | 88 | |
a1e3433a LB |
89 | - The -t option now displays information per probe-point rather than a summary |
90 | for each probe. It also now shows the derivation chain for each probe-point. | |
d1eef011 | 91 | |
6a46f4fb FCE |
92 | - A rewrite of the sys/sdt.h header file provides zero-cost startup (few or |
93 | no ELF relocations) for the debuginfo-less near-zero-cost runtime probes. | |
94 | Binaries compiled with earlier sdt.h versions remain supported. The | |
95 | stap -L (listing) option now lists parameters for sys/sdt.h markers. | |
96 | ||
0dd4c6e7 DB |
97 | - The implementation of the integrated compile-server client has been |
98 | extended. | |
0dd4c6e7 DB |
99 | o --use-server now accepts an argument representing a particular server and |
100 | may be specified more than once. | |
101 | o --list-servers now accepts an expanded range of arguments. | |
c3c5e2eb FCE |
102 | o a new --trust-servers option has been added to stap to replace several |
103 | old certificate-management scripts. | |
219868f8 DB |
104 | o The following tools are now deprecated and will be removed in release 1.5: |
105 | stap-client | |
106 | stap-authorize-server-cert | |
107 | stap-authorize-signing-cert | |
108 | stap-find-or-start-server | |
109 | stap-find-servers | |
110 | See man stap(1) for complete details. | |
111 | ||
112 | - The compile-server now returns the uprobes.ko to the client when it is | |
113 | required by the script being compiled. The integrated compile-server client | |
114 | now makes it available to be loaded by staprun. The old (deprecated) | |
115 | stap-client does not do this. | |
0dd4c6e7 | 116 | |
d1bcbe71 RH |
117 | - process probes with scripts as the target are recognized by stap and the |
118 | interpreter would be selected for probing. | |
119 | ||
8dc503b6 FCE |
120 | - Starting in release 1.5, these old variables/functions will be deprecated |
121 | and will only be available when the '--compatible=1.4' flag is used: | |
122 | ||
d1eef011 DS |
123 | - In the 'syscall.add_key' probe, the 'description_auddr' variable |
124 | has been deprecated in favor of the new 'description_uaddr' | |
125 | variable. | |
126 | - In the 'syscall.fgetxattr', 'syscall.fsetxattr', | |
127 | 'syscall.getxattr', 'syscall.lgetxattr', and | |
128 | 'syscall.lremovexattr' probes, the 'name2' variable has been | |
129 | deprecated in favor of the new 'name_str' variable. | |
89e2abb1 DS |
130 | - In the 'nd_syscall.accept' probe the 'flag_str' variable |
131 | has been deprecated in favor of the new 'flags_str' variable. | |
132 | - In the 'nd_syscall.dup' probe the 'old_fd' variable has been | |
133 | deprecated in favor of the new 'oldfd' variable. | |
134 | - In the 'nd_syscall.fgetxattr', 'nd_syscall.fremovexattr', | |
135 | 'nd_syscall.fsetxattr', 'nd_syscall.getxattr', and | |
136 | 'nd_syscall.lremovexattr' probes, the 'name2' variable has been | |
137 | deprecated in favor of the new 'name_str' variable. | |
8dc503b6 FCE |
138 | - The tapset alias 'nd_syscall.compat_pselect7a' was misnamed. It should |
139 | have been 'nd_syscall.compat_pselect7' (without the trailing 'a'). | |
140 | - The tapset function 'cpuid' is deprecated in favor of the better known | |
141 | 'cpu'. | |
b149489c DS |
142 | - In the i386 'syscall.sigaltstack' probe, the 'ussp' variable has |
143 | been deprecated in favor of the new 'uss_uaddr' variable. | |
144 | - In the ia64 'syscall.sigaltstack' probe, the 'ss_uaddr' and | |
145 | 'oss_uaddr' variables have been deprecated in favor of the new | |
146 | 'uss_uaddr' and 'uoss_uaddr' variables. | |
147 | - The powerpc tapset alias 'syscall.compat_sysctl' was deprecated | |
148 | and renamed 'syscall.sysctl32'. | |
149 | - In the x86_64 'syscall.sigaltstack' probe, the 'regs_uaddr' | |
150 | variable has been deprecated in favor of the new 'regs' variable. | |
89e2abb1 | 151 | |
4432f146 | 152 | * What's new in version 1.3, 2010-07-21 |
649260f3 | 153 | |
c9b524b2 JS |
154 | - The uprobes kernel module now has about half the overhead when probing |
155 | NOPs, which is particularly relevant for sdt.h markers. | |
156 | ||
866b7fea FCE |
157 | - New stap option -G VAR=VALUE allows overriding global variables |
158 | by passing the settings to staprun as module options. | |
bb25d08f | 159 | |
b352f4b0 DS |
160 | - The tapset alias 'syscall.compat_pselect7a' was misnamed. It should |
161 | have been 'syscall.compat_pselect7' (without the trailing 'a'). | |
70032df1 DS |
162 | Starting in release 1.4, the old name will be deprecated and |
163 | will only be available when the '--compatible=1.3' flag is used. | |
b352f4b0 | 164 | |
279aece5 FCE |
165 | - A new procfs parameter .umask(UMASK) which provides modification of |
166 | file permissions using the proper umask value. Default file | |
167 | permissions for a read probe are 0400, 0200 for a write probe, and | |
168 | 0600 for a file with a read and write probe. | |
169 | ||
49db4869 MW |
170 | - It is now possible in some situations to use print_ubacktrace() to |
171 | get a user space stack trace from a kernel probe point. e.g. for | |
172 | user backtraces when there is a pagefault: | |
173 | $ stap -d /bin/sort --ldd -e 'probe vm.pagefault { | |
174 | if (pid() == target()) { | |
175 | printf("pagefault @0x%x\n", address); print_ubacktrace(); | |
176 | } }' -c /bin/sort | |
177 | [...] | |
178 | pagefault @0x7fea0595fa70 | |
179 | 0x000000384f07f958 : __GI_strcmp+0x12b8/0x1440 [libc-2.12.so] | |
180 | 0x000000384f02824e : __gconv_lookup_cache+0xee/0x5a0 [libc-2.12.so] | |
181 | 0x000000384f021092 : __gconv_find_transform+0x92/0x2cf [libc-2.12.so] | |
182 | 0x000000384f094896 : __wcsmbs_load_conv+0x106/0x2b0 [libc-2.12.so] | |
183 | 0x000000384f08bd90 : mbrtowc+0x1b0/0x1c0 [libc-2.12.so] | |
184 | 0x0000000000404199 : ismbblank+0x39/0x90 [sort] | |
185 | 0x0000000000404a4f : inittables_mb+0xef/0x290 [sort] | |
186 | 0x0000000000406934 : main+0x174/0x2510 [sort] | |
187 | 0x000000384f01ec5d : __libc_start_main+0xfd/0x1d0 [libc-2.12.so] | |
188 | 0x0000000000402509 : _start+0x29/0x2c [sort] | |
189 | [...] | |
190 | ||
191 | - New tapset functions to get a string representation of a stack trace: | |
192 | sprint_[u]backtrace() and sprint_[u]stack(). | |
193 | ||
194 | - New tapset function to get the module (shared library) name for a | |
195 | user space address umodname:string(long). The module name will now | |
196 | also be in the output of usymdata() and in backtrace addresses even | |
197 | when they were not given with -d at the command line. | |
198 | ||
199 | - Kernel backtraces are now much faster (replaced a linear search | |
200 | with a binary search). | |
201 | ||
eb3a0eee | 202 | - A new integrated compile-server client is now available as part of stap. |
1e7630bf | 203 | |
eb3a0eee DB |
204 | o 'stap --use-server ...' is equivalent to 'stap-client ...' |
205 | o 'stap --list-servers' is equivalent to 'stap-find-servers' | |
206 | o 'stap --list-servers=online' is equivalent to 'stap-find-servers --all' | |
1e7630bf DB |
207 | o stap-client and its related tools will soon be deprecated. |
208 | o the nss-devel and avahi-devel packages are required for building stap with | |
209 | the integrated client (checked during configuration). | |
210 | o nss and avahi are required to run the integrated client. | |
211 | ||
8cc799a5 JS |
212 | - A new operator @entry is available for automatically saving an expression |
213 | at entry time for use in a .return probe. | |
214 | probe foo.return { println(get_cycles() - @entry(get_cycles())) } | |
215 | ||
34af38db JS |
216 | - Probe $target variables and @cast() can now use a suffix to print complex |
217 | data types as strings. Use a single '$' for a shallow view, or '$$' for a | |
218 | deeper view that includes nested types. For example, with fs_struct: | |
219 | $fs$ : "{.users=%i, .lock={...}, .umask=%i, | |
220 | .in_exec=%i, .root={...}, .pwd={...}}" | |
221 | $fs$$ : "{.users=%i, .lock={.raw_lock={.lock=%u}}, .umask=%i, .in_exec=%i, | |
222 | .root={.mnt=%p, .dentry=%p}, .pwd={.mnt=%p, .dentry=%p}}" | |
223 | ||
a794dbeb FCE |
224 | - The <sys/sdt.h> user-space markers no longer default to an implicit |
225 | MARKER_NAME_ENABLED() semaphore check for each marker. To check for | |
226 | enabled markers use a .d declaration file, then: | |
227 | if (MARKER_NAME_ENABLED()) MARKER_NAME() | |
954b1d89 | 228 | |
ef428667 FCE |
229 | - Hyphenated <sys/sdt.h> marker names such as process(...).mark("foo-bar") |
230 | are now accepted in scripts. They are mapped to the double-underscore | |
231 | form ("foo__bar"). | |
232 | ||
279aece5 FCE |
233 | - More robust <sys/sdt.h> user-space markers support is included. For |
234 | some platforms (x86*, ppc*), this can let systemtap probe the markers | |
235 | without debuginfo. This implementation also supports preserving | |
a794dbeb FCE |
236 | the "provider" name associated with a marker: |
237 | probe process("foo").provider("bar").mark("baz") to match | |
238 | STAP_PROBE<n>(bar, baz <...>) | |
279aece5 FCE |
239 | (Compile with -DSTAP_SDT_V1 to revert to the previous implementation. |
240 | Systemtap supports pre-existing or new binaries using them.) | |
f83336a5 | 241 | |
7d902887 FCE |
242 | - Embedded-C may be used within expressions as values, when in guru mode: |
243 | num = %{ LINUX_VERSION_CODE %} // int64_t | |
244 | name = %{ /* string */ THIS_MODULE->name %} // const char* | |
245 | printf ("%s %x\n", name, num) | |
246 | The usual /* pure */, /* unprivileged */, and /* guru */ markers may be used | |
247 | as with embedded-C functions. | |
248 | ||
38105915 | 249 | - By default the systemtap-runtime RPM builds now include a shared |
114fbea7 | 250 | library, staplog.so, that allows crash to extract systemtap data from |
38105915 WC |
251 | a vmcore image. |
252 | ||
9747ca47 JS |
253 | - Iterating with "foreach" can now explicitly save the value for the loop. |
254 | foreach(v = [i,j] in array) | |
255 | printf("array[%d,%s] = %d\n", i, j, v /* array[i,j] */) | |
256 | ||
ef06c938 FCE |
257 | - The new "--ldd" option automatically adds any additional shared |
258 | libraries needed by probed or -d-listed userspace binaries to the -d | |
e19ae9a8 FCE |
259 | list, to enable symbolic backtracing through them. Similarly, the |
260 | new "--all-modules" option automatically adds any currently loaded | |
261 | kernel modules (listed in /proc/modules) to the -d list. | |
ef06c938 | 262 | |
b2c904c0 JS |
263 | - A new family of set_kernel_* functions make it easier for gurus to write |
264 | new values at arbitrary memory addresses. | |
265 | ||
649260f3 JS |
266 | - Probe wildcards can now use '**' to cross the '.' separator. |
267 | $ stap -l 'sys**open' | |
268 | syscall.mq_open | |
269 | syscall.open | |
270 | ||
13c4a0b0 FCE |
271 | - Backward compatibility flags (--compatible=VERSION, and matching |
272 | script preprocessing predicate %( systemtap_v CMP "version" %) | |
273 | and a deprecation policy are being introduced, in case future | |
274 | tapset/language changes break valid scripts. | |
275 | ||
4432f146 | 276 | * What's new in version 1.2, 2010-03-22 |
489e3d51 | 277 | |
f33e9151 FCE |
278 | - Prototype support for "perf events", where the kernel supports the |
279 | 2.6.33 in-kernel API. Probe points may refer to low-level | |
280 | perf_event_attr type/config numbers, or to a number of aliases | |
281 | defined in the new perf.stp tapset: | |
282 | probe perf.sw.cpu_clock, perf.type(0).config(4) { } | |
283 | ||
da9e11bd JS |
284 | - Type-casting can now use multiple headers to resolve codependencies. |
285 | @cast(task, "task_struct", | |
286 | "kernel<linux/sched.h><linux/fs_struct.h>")->fs->umask | |
287 | ||
9039b639 FCE |
288 | - Tapset-related man pages have been renamed. 'man -k 3stap' should show |
289 | the installed list, which due to prefixing should no longer collide over | |
290 | ordinary system functions. | |
291 | ||
985adad3 | 292 | - User space marker arguments no longer use volatile if the version of gcc, |
03a74626 | 293 | which must be at least 4.5.0, supports richer DWARF debuginfo. Use cflags |
87d85b96 FCE |
294 | -DSTAP_SDT_VOLATILE=volatile or -DSTAP_SDT_VOLATILE= when building |
295 | the sys/sdt.h application to override this one way or another. | |
103c7c8d | 296 | |
f4fe2e93 FCE |
297 | - A new construct for error handling is available. It is similar to c++ |
298 | exception catching, using try and catch as new keywords. Within a handler | |
299 | or function, the following is valid and may be nested: | |
300 | try { /* arbitrary statements */ } | |
301 | catch (er) { /* e.g. println("caught error ", er) */ } | |
302 | ||
57a56e00 FCE |
303 | - A new command line flag '-W' forces systemtap to abort translation of |
304 | a script if any warnings are produced. It is similar to gcc's -Werror. | |
305 | (If '-w' is also supplied to suppress warnings, it wins.) | |
306 | ||
30263a73 FCE |
307 | - A new predicate @defined is available for testing whether a |
308 | particular $variable/expression is resolvable at translate time: | |
309 | probe foo { if (@defined($bar)) log ("$bar is available here") } | |
310 | ||
489e3d51 FCE |
311 | - Adjacent string literals are glued together, making this |
312 | construct valid: | |
313 | probe process("/usr" @1 "/bin").function("*") { ... } | |
314 | ||
15b2e969 FCE |
315 | - In order to limit potential impact from future security problems, |
316 | the stap-server process does not permit its being launched as root. | |
317 | ||
489e3d51 FCE |
318 | - On recent kernels, for some architectures/configurations, hardware |
319 | breakpoint probes are supported. The probe point syntax is: | |
320 | ||
321 | probe kernel.data(ADDRESS).write | |
322 | probe kernel.data(ADDRESS).length(LEN).write | |
323 | probe kernel.data("SYMBOL_NAME").write | |
dd225250 | 324 | |
4432f146 | 325 | * What's new in version 1.1, 2010-01-15 |
450718c9 | 326 | |
d5d6f6f1 RD |
327 | - New tracepoint based tapset for memory subsystem. |
328 | ||
bcdf36b1 FCE |
329 | - The loading of signed modules by staprun is no longer allowed for |
330 | ordinary, unprivileged users. This means that only root, members of | |
de23650e | 331 | the group 'stapdev' and members of the group 'stapusr' can load |
bcdf36b1 FCE |
332 | systemtap modules using staprun, stap or stap-client. The minimum |
333 | privilege required to run arbitrary --unprivileged scripts is now | |
de23650e | 334 | 'stapusr' membership. |
bcdf36b1 FCE |
335 | |
336 | - The stap-server initscript is available. This initscript allows you | |
337 | to start systemtap compile servers as a system service and to manage | |
338 | these servers as a group or individually. The stap-server initscript | |
339 | is installed by the systemtap-server rpm. The build directory for | |
340 | the uprobes module (/usr/share/systemtap/runtime/uprobes) is made | |
341 | writable by the 'stap-server' group. All of the files generated when | |
342 | building the uprobes module, including the digital signature, are | |
343 | also writable by members of stap-server. | |
d2c9f522 | 344 | |
5807ac64 DB |
345 | See initscript/README.stap-server for details. |
346 | ||
b515db67 WH |
347 | - Some of the compile server client, server and certificate management |
348 | tools have been moved from $bindir to $libexecdir/systemtap. | |
0f4e0b6f DB |
349 | You should use the new stap-server script or the stap-server initscript |
350 | for server management where possible. The stap-server script provides the same | |
351 | functionality as the stap-server initscript except that the servers are | |
352 | run by the invoking user by default as opposed to servers started by the | |
353 | stap-server initscript which are run by the user stap-server | |
354 | by default. See stap-server(8) for more information. | |
355 | ||
356 | You may continue to use these tools by adding $libexecdir/systemtap to | |
357 | your path. You would need to do this, for example, if you are not root, | |
358 | you want to start a compile server and you are not running systemtap from a | |
359 | private installation. In this case you still need to use stap-start-server. | |
360 | ||
0710d850 DS |
361 | - Any diagnostic output line that starts with "ERROR", as in |
362 | error("foo"), will promote a "Pass 5: run failed", and the return | |
363 | code is 1. | |
b49f69f3 | 364 | |
2e526dab FCE |
365 | - Systemtap now warns about global variables being referenced from other |
366 | script files. This aims to protect against unintended local-vs-global | |
367 | namespace collisions such as: | |
368 | ||
369 | % cat some_tapset.stp | |
370 | probe baz.one = bar { foo = $foo; bar = $bar } | |
371 | % cat end_user_script.stp | |
372 | global foo # intended to be private variable | |
373 | probe timer.s(1) { foo ++ } | |
374 | probe baz.* { println(foo, pp()) } | |
375 | % stap end_user_script.stp | |
376 | WARNING: cross-file global variable reference to foo from some_tapset.stp | |
377 | ||
561079c8 FCE |
378 | - Preprocessor conditional for kernel configuration testing: |
379 | %( CONFIG_foo == "y" %? ... %) | |
380 | ||
450718c9 FCE |
381 | - ftrace(msg:string) tapset function to send strings to the system-wide |
382 | ftrace ring-buffer (if any). | |
383 | ||
6e2d1162 MW |
384 | - Better support for richer DWARF debuginfo output from GCC 4.5 |
385 | (variable tracking assignments). Kernel modules are now always resolved | |
386 | against all their dependencies to find any info referring to missing | |
387 | symbols. DW_AT_const_value is now supported when no DW_AT_location | |
388 | is available. | |
389 | ||
4432f146 | 390 | * What's new in verson 1.0, 2009-09-22 |
f07c3b68 | 391 | |
23c0a2b3 JS |
392 | - process().mark() probes now use an enabling semaphore to reduce the |
393 | computation overhead of dormant probes. | |
394 | ||
bb2b3e3b JS |
395 | - The function spec for dwarf probes now supports C++ scopes, so you can |
396 | limit the probes to specific namespaces or classes. Multiple scopes | |
397 | can be specified, and they will be matched progressively outward. | |
398 | probe process("foo").function("std::vector<*>::*") { } | |
399 | probe process("foo").function("::global_function") { } | |
400 | ||
4b2cdd06 JS |
401 | - It is now possible to cross-compile systemtap scripts for foreign |
402 | architectures, using the new '-a ARCH' and '-B OPT=VALUE' flags. | |
403 | For example, put arm-linux-gcc etc. into your $PATH, and point | |
404 | systemtap at the target kernel build tree with: | |
405 | stap -a arm -B CROSS_COMPILE=arm-linux- -r /build/tree [...] | |
406 | The -B option is passed to kbuild make. -r identifies the already | |
407 | configured/built kernel tree and -a its architecture (kbuild ARCH=...). | |
408 | Systemtap will infer -p4. | |
409 | ||
ba01c24c | 410 | - Cross compilation using the systemtap client and server |
742b8971 JS |
411 | - stap-start-server now accepts the -r, -R, -I, -B and -a options in |
412 | order to start a cross compiling server. The server will correctly | |
413 | advertise itself with respect to the kernel release and architecture | |
414 | that it compiles for. | |
415 | - When specified on stap-client, the -r and -a options will be | |
416 | considered when searching for a suitable server. | |
ba01c24c | 417 | |
742b8971 | 418 | - When using the systemtap client and server udp port 5353 must be open |
de23650e | 419 | in your firewall in order for the client to find servers using |
742b8971 JS |
420 | avahi-browse. Also the systemtap server will choose a random port in |
421 | the range 1024-63999 for accepting ssl connections. | |
902d0d67 | 422 | |
500bc85c | 423 | - Support for unprivileged users: |
f6efd18a MW |
424 | *********************************************************************** |
425 | * WARNING!!!!!!!!!! * | |
426 | * This feature is EXPERIMENTAL at this time and should be used with * | |
427 | * care. This feature allows systemtap kernel modules to be loaded by * | |
428 | * unprivileged users. The user interface and restrictions will change * | |
429 | * as this feature evolves. * | |
430 | *********************************************************************** | |
742b8971 JS |
431 | - Systemtap modules generated from scripts which use a restricted |
432 | subset of the features available may be loaded by staprun for | |
433 | unprivileged users. Previously, staprun would load modules only for | |
434 | root or for members of the groups stapdev and stapusr. | |
f6efd18a MW |
435 | - Using the --unprivileged option on stap enables translation-time |
436 | checking for use by unprivileged users (see restrictions below). | |
437 | - All modules deemed suitable for use by unprivileged users will be | |
ba01c24c | 438 | signed by the systemtap server when --unprivileged is specified on |
742b8971 JS |
439 | stap-client. See module signing in release 0.9.8 and stap-server in |
440 | release 0.9 below. | |
f6efd18a MW |
441 | - Modules signed by trusted signers (servers) and verified by staprun |
442 | will be loaded by staprun regardless of the user's privilege level. | |
443 | - The system administrator asserts the trustworthiness of a signer | |
444 | (server) by running stap-authorize-signing-cert <cert-file> as root, | |
ba01c24c | 445 | where the <cert-file> can be found in |
742b8971 JS |
446 | ~<user>/.systemtap/ssl/server/stap.cert for servers started by |
447 | ordinary users and in $sysconfdir/systemtap/ssl/server/stap.cert for | |
448 | servers started by root. | |
449 | - Restrictions are intentionally strict at this time and may be | |
450 | relaxed in the future: | |
500bc85c | 451 | - probe points are restricted to: |
20ab90b5 DB |
452 | begin, begin(n), end, end(n), error, error(n), never, |
453 | timer.{jiffies,s,sec,ms,msec,us,usec,ns,nsec}(n)*, timer.hz(n), | |
742b8971 | 454 | process.* (for processes owned by the user). |
b232fab3 | 455 | - use of embedded C code is not allowed. |
ba01c24c DB |
456 | - use of tapset functions is restricted. |
457 | - some tapset functions may not be used at all. A message will be | |
458 | generated at module compilation time. | |
742b8971 JS |
459 | - some actions by allowed tapset functions may only be performed |
460 | in the context of the user's own process. A runtime fault will | |
461 | occur in these situations, for example, direct memory access. | |
462 | - The is_myproc() tapset function has been provided so that | |
463 | tapset writers for unprivileged users can check that the | |
464 | context is of the users own process before attempting these | |
465 | actions. | |
500bc85c | 466 | - accessing the kernel memory space is not allowed. |
ba01c24c DB |
467 | - The following command line options may not be used by stap-client |
468 | -g, -I, -D, -R, -B | |
469 | - The following environment variables are ignored by stap-client: | |
500bc85c DB |
470 | SYSTEMTAP_RUNTIME, SYSTEMTAP_TAPSET, SYSTEMTAP_DEBUGINFO_PATH |
471 | - nss and nss-tools are required to use this feature. | |
472 | ||
bc7cd435 MH |
473 | - Support output file switching by SIGUSR2. Users can command running |
474 | stapio to switch output file by sending SIGUSR2. | |
475 | ||
8faf4a73 DB |
476 | - Memory consumption for scripts involving many uprobes has been |
477 | dramatically reduced. | |
478 | ||
479 | - The preprocessor now supports || and && in the conditions. | |
f6efd18a | 480 | e.g. %( arch == "x86_64" || arch == "ia64" %: ... %) |
8faf4a73 | 481 | |
8faf4a73 DB |
482 | - The systemtap notion of "architecture" now matches the kernel's, rather |
483 | than that of "uname -m". This means that 32-bit i386 family are all | |
484 | known as "i386" rather than "i386" or "i686"; "ppc64" as "powerpc"; | |
485 | "s390x" as "s390", and so on. This is consistent between the new | |
486 | "-a ARCH" flag and the script-level %( arch ... %) conditional. | |
487 | ||
488 | - It is now possible to define multiple probe aliases with the same name. | |
489 | A probe will expand to all matching aliases. | |
742b8971 JS |
490 | probe foo = bar { } |
491 | probe foo = baz { } | |
492 | probe foo { } # expands twice, once to bar and once to baz | |
8faf4a73 | 493 | |
96fb769c DS |
494 | - A new experimental transport mechanism, using ftrace's ring_buffer, |
495 | has been added. This may become the default transport mechanism in | |
496 | future versions of systemtap. To test this new transport mechanism, | |
497 | define 'STP_USE_RING_BUFFER'. | |
498 | ||
f6efd18a MW |
499 | - Support for recognizing DW_OP_{stack,implicit}_value DWARF expressions |
500 | as emitted by GCC 4.5. | |
c61807d2 | 501 | |
4432f146 | 502 | * What's new in version 0.9.9, 2009-08-04 |
f07c3b68 FCE |
503 | |
504 | - Systemwide kernel .function.return (kretprobe) maxactive defaults may | |
505 | be overridden with the -DKRETACTIVE=nnn parameter. | |
506 | ||
76ff718a FCE |
507 | - Translation pass 2 is significantly faster by avoiding unnecessary |
508 | searching through a kernel build/module directory tree. | |
509 | ||
230a1203 MW |
510 | - When compiled against elfutils 0.142 systemtap now handles the new |
511 | DW_OP_call_frame_CFA generated by by GCC. | |
512 | ||
513 | - uprobes and ustack() are more robust when used on applications that | |
514 | depend on prelinked/separate debuginfo shared libraries. | |
515 | ||
516 | - User space PROBE marks are not always found with or without separate | |
517 | debuginfo. The .probes section itself is now always put in the main | |
de23650e WH |
518 | elf file and marked as allocated. When building pic code the section |
519 | is marked writable. The selinux memory check problems seen with | |
520 | programs using STAP_PROBES is fixed. | |
230a1203 MW |
521 | |
522 | - statement() probes can now override "address not at start of statement" | |
523 | errors in guru mode. They also provide alternative addresses to use | |
524 | in non-guru mode. | |
525 | ||
da01fcc6 JS |
526 | - The stapgraph application can generate graphs of data and events |
527 | emitted by systemtap scripts in real time. Run "stapgraph | |
79bd71a1 TM |
528 | testsuite/systemtap.examples/general/grapher.stp" for an example of |
529 | graphing the system load average and keyboard events. | |
530 | ||
da01fcc6 JS |
531 | - Dwarf probes now show parameters and local variables in the verbose |
532 | listing mode (-L). | |
533 | ||
534 | - Symbol aliases are now resolved to their canonical dwarf names. For | |
535 | example, probing "malloc" in libc resolves to "__libc_malloc". | |
536 | ||
537 | - The syntax for dereferencing $target variables and @cast() gained new | |
538 | capabilities: | |
539 | - Array indexes can now be arbitrary numeric expressions. | |
540 | - Array subscripts are now supported on pointer types. | |
541 | - An '&' operator before a @cast or $target returns the address of the | |
542 | final component, especially useful for nested structures. | |
543 | ||
544 | - For reading all probe variables, kernel.mark now supports $$vars and | |
545 | $$parms, and process.syscall now supports $$vars. | |
546 | ||
547 | - The SNMP tapset provides probes and functions for many network | |
548 | statistics. See stapprobes.snmp(3stap) for more details. | |
549 | ||
550 | - The dentry tapset provides functions to map kernel VFS directory entries | |
551 | to file or full path names: d_path(), d_name() and reverse_path_walk(). | |
552 | ||
553 | - SystemTap now has userspace markers in its own binaries, and the stap | |
554 | tapset provides the available probepoints and local variables. | |
555 | ||
556 | - Miscellaneous new tapset functions: | |
557 | - pgrp() returns the process group ID of the current process | |
558 | - str_replace() performs string replacement | |
559 | ||
4432f146 | 560 | * What's new in version 0.9.8, 2009-06-11 |
c3e80cab | 561 | |
849d6546 JS |
562 | - Miscellaneous new tapset functions: |
563 | - sid() returns the session ID of the current process | |
564 | - stringat() indexes a single character from a string. | |
565 | ||
566 | - Using %M in print formats for hex dumps can now print entire buffers, | |
567 | instead of just small numbers. | |
568 | ||
6766808e JS |
569 | - Dwarfless syscalls: The nd_syscalls tapset is now available to probe |
570 | system calls without requiring kernel debugging information. All of | |
571 | the same probepoints in the normal syscalls tapset are available with | |
572 | an "nd_" prefix, e.g. syscall.open becomes nd_syscall.open. Most | |
573 | syscall arguments are also available by name in nd_syscalls. | |
574 | ||
87c589a9 | 575 | - Module signing: If the appropriate nss libraries are available on your |
b232fab3 | 576 | system, stap-server will sign each compiled module using a self-generated |
87c589a9 JS |
577 | certificate. This is the first step toward extending authority to |
578 | load certain modules to unprivileged users. For now, if the system | |
579 | administrator adds a certificate to a database of trusted signers | |
580 | (stap-authorize-signing-cert), modules signed using that certificate | |
581 | will be verified by staprun against tampering. Otherwise, you should | |
582 | notice no difference in the operation of stap or staprun. | |
c3e80cab | 583 | |
4432f146 | 584 | * What's new in version 0.9.7, 2009-04-23 |
dcfd7fed | 585 | |
cff7feda JS |
586 | - @cast can now determine its type information using an explicit header |
587 | specification. For example: | |
588 | @cast(tv, "timeval", "<sys/time.h>")->tv_sec | |
589 | @cast(task, "task_struct", "kernel<linux/sched.h>")->tgid | |
590 | ||
1f65cc4f JS |
591 | - The overlapping process.* tapsets are now separated. Those probe points |
592 | documented in stapprobes(3stap) remain the same. Those that were formerly | |
593 | in stapprobes.process(3stap) have been renamed to kprocess, to reflect | |
594 | their kernel perspective on processes. | |
595 | ||
dcfd7fed FCE |
596 | - The --skip-badvars option now also suppresses run-time error |
597 | messages that would otherwise result from erroneous memory accesses. | |
598 | Such accesses can originate from $context expressions fueled by | |
599 | erroneous debug data, or by kernel_{long,string,...}() tapset calls. | |
600 | ||
94c3c803 AM |
601 | - New probes kprobe.function(FUNCTION) and kprobe.function(FUNCTION).return |
602 | for dwarfless probing. These postpone function address resolution to | |
603 | run-time and use the kprobe symbol-resolution mechanism. | |
604 | Probing of absolute statements can be done using the | |
605 | kprobe.statement(ADDRESS).absolute construct. | |
606 | ||
819ec23d MW |
607 | - EXPERIMENTAL support for user process unwinding. A new collection of |
608 | tapset functions have been added to handle user space backtraces from | |
609 | probe points that support them (currently process and timer probes - | |
610 | for timer probes test whether or not in user space first with the | |
611 | already existing user_mode() function). The new tapset functions are: | |
612 | uaddr - User space address of current running task. | |
613 | usymname - Return the symbol of an address in the current task. | |
614 | usymdata - Return the symbol and module offset of an address. | |
615 | print_ustack - Print out stack for the current task from string. | |
616 | print_ubacktrace - Print stack back trace for current task. | |
617 | ubacktrace - Hex backtrace of current task stack. | |
618 | Please read http://sourceware.org/ml/systemtap/2009-q2/msg00364.html | |
619 | on the current restrictions and possible changes in the future and | |
620 | give feedback if you want to influence future developments. | |
621 | ||
4432f146 | 622 | * What's new in version 0.9.5, 2009-03-27 |
944e2486 | 623 | |
891e4fb2 JS |
624 | - New probes process().insn and process().insn.block that allows |
625 | inspection of the process after each instruction or block of | |
626 | instructions executed. So to count the total number of instructions | |
627 | a process executes during a run do something like: | |
628 | $ stap -e 'global steps; probe process("/bin/ls").insn {steps++} | |
629 | probe end {printf("Total instructions: %d\n", steps);}' \ | |
630 | -c /bin/ls | |
631 | This feature can slow down execution of a process somewhat. | |
83dd1a8e | 632 | |
891e4fb2 JS |
633 | - Systemtap probes and function man pages extracted from the tapsets |
634 | are now available under 3stap. To show the page for probe vm.pagefault | |
635 | or the stap function pexecname do: | |
636 | $ man 3stap vm.pagefault | |
637 | $ man 3stap pexecname | |
8e9d6257 | 638 | |
b1a4288c JS |
639 | - Kernel tracepoints are now supported for probing predefined kernel |
640 | events without any debuginfo. Tracepoints incur less overhead than | |
641 | kprobes, and context parameters are available with full type | |
642 | information. Any kernel 2.6.28 and later should have defined | |
643 | tracepoints. Try the following to see what's available: | |
644 | $ stap -L 'kernel.trace("*")' | |
645 | ||
ccd65d4a JS |
646 | - Typecasting with @cast now supports modules search paths, which is |
647 | useful in case there are multiple places where the type definition | |
648 | may be found. For example: | |
649 | @cast(sdev, "scsi_device", "kernel:scsi_mod")->sdev_state | |
650 | ||
701c41be MH |
651 | - On-file flight recorder is supported. It allows stap to record huge |
652 | trace log on the disk and to run in background. | |
653 | Passing -F option with -o option runs stap in background mode. In this | |
654 | mode, staprun is detached from console, and stap itself shows staprun's | |
655 | pid and exits. | |
656 | Specifying the max size and the max number of log files are also available | |
657 | by passing -S option. This option has one or two arguments seperated by | |
658 | a comma. The first argument is the max size of a log file in MB. If the | |
659 | size of a log file exceeds it, stap switches to the next log file | |
660 | automatically. The second is how many files are kept on the disk. If the | |
661 | number of log files exceeds it, the oldest log file is removed | |
662 | automatically. The second argument can be omitted. | |
663 | ||
664 | For example, this will record output on log files each of them is smaller | |
665 | than 1024MB and keep last 3 logs, in background. | |
666 | % stap -F -o /tmp/staplog -S 1024,3 script.stp | |
667 | ||
e2ae0696 LR |
668 | - In guru mode (-g), the kernel probing blacklist is disabled, leaving |
669 | only a subset - the kernel's own internal kprobe blacklist - to attempt | |
670 | to filter out areas unsafe to probe. The differences may be enough to | |
671 | probe more interrupt handlers. | |
672 | ||
3bd0d4df | 673 | - Variables unavailable in current context may be skipped by setting a |
947d86f9 FCE |
674 | session level flag with command line option --skip-badvars now available. |
675 | This replaces any dwarf $variable expressions that could not be resolved | |
676 | with literal numeric zeros, along with a warning message. | |
3bd0d4df | 677 | |
59fde7cc MW |
678 | - Both kernel markers and kernel tracepoint support argument listing |
679 | through stap -L 'kernel.mark("*")' or stap -L 'kernel.trace("*")' | |
680 | ||
681 | - Users can use -DINTERRUPTIBLE=0 to prevent interrupt reentrancy in | |
682 | their script, at the cost of a bit more overhead to toggle the | |
683 | interrupt mask. | |
684 | ||
685 | - Added reentrancy debugging. If stap is run with the arguments | |
686 | "-t -DDEBUG_REENTRANCY", additional warnings will be printed for | |
687 | every reentrancy event, including the probe points of the | |
688 | resident and interloper probes. | |
689 | ||
387a7a57 MW |
690 | - Default to --disable-pie for configure. |
691 | Use --enable-pie to turn it back on. | |
692 | ||
693 | - Improved sdt.h compatibility and test suite for static dtrace | |
694 | compatible user space markers. | |
695 | ||
696 | - Some architectures now use syscall wrappers (HAVE_SYSCALL_WRAPPERS). | |
697 | The syscall tapset has been enhanced to take care of the syscall | |
698 | wrappers in this release. | |
699 | ||
700 | - Security fix for CVE-2009-0784: stapusr module-path checking race. | |
701 | ||
4432f146 | 702 | * What's new in version 0.9, 2009-02-19 |
6b2ad26c | 703 | |
60ea9291 JS |
704 | - Typecasting is now supported using the @cast operator. A script can |
705 | define a pointer type for a "long" value, and then access type members | |
706 | using the same syntax as with $target variables. For example, this will | |
707 | retrieve the parent pid from a kernel task_struct: | |
708 | @cast(pointer, "task_struct", "kernel")->parent->pid | |
709 | ||
76d146ad MW |
710 | - process().mark() probes are now possible to trace static user space |
711 | markers put in programs with the STAP_PROBE macro using the new | |
712 | sys/sdt.h include file. This also provides dtrace compatible markers | |
713 | through DTRACE_PROBE and an associated python 'dtrace' script that | |
714 | can be used in builds based on dtrace that need dtrace -h or -G | |
715 | functionality. | |
716 | ||
62c977f5 MW |
717 | - For those that really want to run stap from the build tree there is |
718 | now the 'run-stap' script in the top-level build directory that sets | |
719 | up the SYSTEMTAP_TAPSET, SYSTEMTAP_RUNTIME, SYSTEMTAP_STAPRUN, and | |
720 | SYSTEMTAP_STAPIO environment variables (installing systemtap, in a | |
721 | local prefix, is still recommended for common use). | |
722 | ||
723 | - Systemtap now comes with a new Beginners Guide that walks the user | |
724 | through their first steps setting up stap, understanding how it all | |
2a321362 MW |
725 | works, introduces some useful scripts and describes some common |
726 | pitfalls. It isn't created by default since it needs a Publican | |
727 | setup, but full build instructions can be found in the wiki: | |
728 | http://sourceware.org/systemtap/wiki/PublicanQuikHowto | |
729 | An online version can be found at: | |
730 | http://sourceware.org/systemtap/SystemTap_Beginners_Guide.pdf | |
731 | ||
3ad1e1ee MW |
732 | - Standard tapsets included with Systemtap were modified to include |
733 | extractable documentation information based on the kernel-doc | |
734 | infrastructure. When configured --enabled-docs a HTML and PDF | |
735 | version of the Tapset Reference Manual is produced explaining probes | |
736 | defined in each tapset. | |
737 | ||
9e494cbb DB |
738 | - The systemtap client and compile server are now available. |
739 | These allow you to compile a systemtap module on a host other than | |
740 | the one which it will be run, providing the client and server | |
741 | are compatible. Other than using a server for passes 1 through | |
742 | 4, the client behaves like the 'stap' front end itself. This | |
743 | means, among other things, that the client will automatically | |
744 | load the resulting module on the local host unless -p[1234] | |
c8bf931d | 745 | was specified. See stap-server(8) for more details. |
9e494cbb | 746 | The client/server now use SSL for network connection security and |
6288515e DB |
747 | for signing. |
748 | ||
749 | The systemtap client and server are prototypes only. Interfaces, options | |
750 | and usage may change at any time. | |
9e494cbb | 751 | |
592470cd SC |
752 | - function("func").label("label") probes are now supported to allow matching |
753 | the label of a function. | |
754 | ||
9a8d8be3 MH |
755 | - Systemtap initscript is available. This initscript allows you to run |
756 | systemtap scripts as system services (in flight recorder mode) and | |
757 | control those scripts individually. | |
e2a741be | 758 | See README.systemtap for details. |
9a8d8be3 | 759 | |
b5e66ada FCE |
760 | - The stap "-r DIR" option may be used to identify a hand-made kernel |
761 | build directory. The tool determines the appropriate release string | |
762 | automatically from the directory. | |
7471ea1f | 763 | |
453edad1 | 764 | - Serious problems associated with user-space probing in shared libraries |
592470cd | 765 | were corrected, making it now possible to experiment with probe shared |
7d091090 FCE |
766 | libraries. Assuming dwarf debugging information is installed, use this |
767 | twist on the normal syntax: | |
768 | ||
769 | probe process("/lib64/libc-2.8.so").function("....") { ... } | |
770 | ||
771 | This would probe all threads that call into that library. Running | |
772 | "stap -c CMD" or "stap -x PID" naturally restricts this to the target | |
453edad1 | 773 | command+descendants only. $$vars etc. may be used. |
7d091090 FCE |
774 | |
775 | - For scripts that sometimes terminate with excessive "skipped" probes, | |
776 | rerunning the script with "-t" (timing) will print more details about | |
777 | the skippage reasons. | |
778 | ||
fd2aeae9 FCE |
779 | - Symbol tables and unwind (backtracing) data support were formerly |
780 | compiled in for all probed modules as identified by the script | |
781 | (kernel; module("name"); process("file")) plus those listed by the | |
782 | stap "-d BINARY" option. Now, this data is included only if the systemtap | |
783 | script uses tapset functions like probefunc() or backtrace() that require | |
784 | such information. This shrinks the probe modules considerably for the rest. | |
785 | ||
e0b4e89d | 786 | - Per-pass verbosity control is available with the new "--vp {N}+" option. |
fd2aeae9 FCE |
787 | "stap --vp 040" adds 4 units of -v verbosity only to pass 2. This is useful |
788 | for diagnosing errors from one pass without excessive verbosity from others. | |
e0b4e89d | 789 | |
5c4dcbfb FCE |
790 | - Most probe handlers now run with interrupts enabled, for improved |
791 | system responsiveness and less probing overhead. This may result | |
792 | in more skipped probes, for example if a reentrant probe handler | |
fd2aeae9 FCE |
793 | is attempted from within an interrupt handler. It may also make the |
794 | systemtap overload detection facility more likely to be triggered, as | |
795 | interrupt handlers' run time would be included in the self-assessed | |
796 | overhead of running probe handlers. | |
6b2ad26c | 797 | |
4432f146 | 798 | * What's new in version 0.8, 2008-11-13 |
cfaa068c | 799 | |
2f9f9366 FCE |
800 | - Cache limiting is now available. If the compiled module cache size is |
801 | over a limit specified in the $SYSTEMTAP_DIR/cache/cache_mb_limit file, | |
802 | some old cache entries will be unlinked. See man stap(1) for more. | |
803 | ||
57b2fd2b RA |
804 | - Error and warning messages are now followed by source context displaying |
805 | the erroneous line/s and a handy '^' in the following line pointing to the | |
806 | appropriate column. | |
807 | ||
23433b34 EB |
808 | - A bug reporting tool "stap-report" is now available which will quickly |
809 | retrieve much of the information requested here: | |
810 | http://sourceware.org/systemtap/wiki/HowToReportBugs | |
811 | ||
25a63204 FCE |
812 | - The translator can resolve members of anonymous structs / unions: |
813 | given struct { int foo; struct { int bar; }; } *p; | |
814 | this now works: $p->bar | |
815 | ||
2fa2a091 NT |
816 | - The stap "-F" flag activates "flight recorder" mode, which consists of |
817 | translating the given script as usual, but implicitly launching it into | |
818 | the background with staprun's existing "-L" (launch) option. A user | |
819 | can later reattach to the module with "staprun -A MODULENAME". | |
820 | ||
6270adc1 MH |
821 | - Additional context variables are available on user-space syscall probes. |
822 | - $argN ($arg1, $arg2, ... $arg6) in process(PATH_OR_PID).syscall | |
823 | gives you the argument of the system call. | |
5d67b47c MH |
824 | - $return in process(PATH_OR_PID).syscall.return gives you the return |
825 | value of the system call. | |
6270adc1 | 826 | |
cec7293b | 827 | - Target process mode (stap -c CMD or -x PID) now implicitly restricts all |
094b05c7 | 828 | "process.*" probes to the given child process. (It does not affect |
34f2e0b9 FCE |
829 | kernel.* or other probe types.) The CMD string is normally run directly, |
830 | rather than via a /bin/sh -c subshell, since then utrace/uprobe probes | |
831 | receive a fairly "clean" event stream. If metacharacters like | |
832 | redirection operators were present in CMD, then "sh -c CMD" is still | |
833 | used, and utrace/uprobe probes will receive events from the shell. | |
cec7293b FCE |
834 | |
835 | % stap -e 'probe process.syscall, process.end { | |
836 | printf("%s %d %s\n", execname(), pid(), pp())}'\ | |
837 | -c ls | |
838 | ls 2323 process.syscall | |
839 | ls 2323 process.syscall | |
840 | ls 2323 process.end | |
841 | ||
1044139f FCE |
842 | - Probe listing mode is improved: "-L" lists available script-level variables |
843 | ||
844 | % stap -L 'syscall.*open*' | |
845 | syscall.mq_open name:string name_uaddr:long filename:string mode:long u_attr_uaddr:long oflag:long argstr:string | |
846 | syscall.open name:string filename:string flags:long mode:long argstr:string | |
847 | syscall.openat name:string filename:string flags:long mode:long argstr:string | |
848 | ||
e070cc9c FCE |
849 | - All user-space-related probes support $PATH-resolved executable |
850 | names, so | |
851 | ||
852 | probe process("ls").syscall {} | |
853 | probe process("./a.out").syscall {} | |
854 | ||
855 | work now, instead of just | |
856 | ||
857 | probe process("/bin/ls").syscall {} | |
858 | probe process("/my/directory/a.out").syscall {} | |
859 | ||
860 | - Prototype symbolic user-space probing support: | |
861 | ||
862 | # stap -e 'probe process("ls").function("*").call { | |
863 | log (probefunc()." ".$$parms) | |
864 | }' \ | |
865 | -c 'ls -l' | |
866 | ||
867 | This requires: | |
868 | - debugging information for the named program | |
869 | - a version of utrace in the kernel that is compatible with the "uprobes" | |
870 | kernel module prototype. This includes RHEL5 and older Fedora, but not | |
871 | yet current lkml-track utrace; a "pass 4a"-time build failure means | |
872 | your system cannot use this yet. | |
873 | ||
cd221ed4 | 874 | - Global variables which are written to but never read are now |
e070cc9c | 875 | automatically displayed when the session does a shutdown. For example: |
5d954165 | 876 | |
e070cc9c FCE |
877 | global running_tasks |
878 | probe timer.profile {running_tasks[pid(),tid()] = execname()} | |
5d954165 | 879 | probe timer.ms(8000) {exit()} |
cd221ed4 | 880 | |
a93f0b31 SC |
881 | - A formatted string representation of the variables, parameters, or local |
882 | variables at a probe point is now supported via the special $$vars, | |
a43ba433 FCE |
883 | $$parms, and $$locals context variables, which expand to a string |
884 | containing a list "var1=0xdead var2=0xbeef var3=?". (Here, var3 exists | |
885 | but is for some reason unavailable.) In return probes only, $$return | |
fd574705 | 886 | expands to an empty string for a void function, or "return=0xf00". |
a93f0b31 | 887 | |
e10599ff | 888 | |
4432f146 | 889 | * What's new in version 0.7, 2008-07-15 |
c2af6f02 | 890 | |
99a5f9cf SC |
891 | - .statement("func@file:*") and .statement("func@file:M-N") probes are now |
892 | supported to allow matching a range of lines in a function. This allows | |
893 | tracing the execution of a function. | |
894 | ||
14a75801 FCE |
895 | - Scripts relying on probe point wildcards like "syscall.*" that expand |
896 | to distinct kprobes are processed significantly faster than before. | |
897 | ||
d57671d3 FCE |
898 | - The vector of script command line arguments is available in a |
899 | tapset-provided global array argv[]. It is indexed 1 ... argc, | |
900 | another global. This can substitute for of preprocessor | |
901 | directives @NNN that fail at parse time if there are not | |
902 | enough arguments. | |
903 | ||
904 | printf("argv: %s %s %s", argv[1], argv[2], argv[3]) | |
905 | ||
1bd128a3 SC |
906 | - .statement("func@file+line") probes are now supported to allow a |
907 | match relative to the entry of the function incremented by line | |
908 | number. This allows using the same systemtap script if the rest | |
909 | of the file.c source only changes slightly. | |
910 | ||
16442b90 FCE |
911 | - A probe listing mode is available. |
912 | % stap -l vm.* | |
913 | vm.brk | |
914 | vm.mmap | |
915 | vm.munmap | |
916 | vm.oom_kill | |
917 | vm.pagefault | |
918 | vm.write_shared | |
919 | ||
159cb109 DS |
920 | - More user-space probe types are added: |
921 | ||
dd078c96 DS |
922 | probe process(PID).begin { } |
923 | probe process("PATH").begin { } | |
924 | probe process(PID).thread.begin { } | |
925 | probe process("PATH").thread.begin { } | |
926 | probe process(PID).end { } | |
927 | probe process("PATH").end { } | |
928 | probe process(PID).thread.end { } | |
929 | probe process("PATH").thread.end { } | |
159cb109 DS |
930 | probe process(PID).syscall { } |
931 | probe process("PATH").syscall { } | |
932 | probe process(PID).syscall.return { } | |
933 | probe process("PATH").syscall.return { } | |
16442b90 | 934 | |
c3799d72 AM |
935 | - Globals now accept ; terminators |
936 | ||
937 | global odds, evens; | |
938 | global little[10], big[5]; | |
939 | ||
4432f146 | 940 | * What's new in version 0.6, 2007-12-15 |
62802575 FCE |
941 | |
942 | - A copy of the systemtap tutorial and language reference guide | |
943 | are now included. | |
683b62c0 | 944 | |
34201621 DB |
945 | - There is a new format specifier, %m, for the printf family of |
946 | functions. It functions like %s, except that it does not stop when | |
947 | a nul ('\0') byte is encountered. The number of bytes output is | |
948 | determined by the precision specifier. The default precision is 1. | |
949 | For example: | |
950 | ||
951 | printf ("%m", "My String") // prints one character: M | |
952 | printf ("%.5", myString) // prints 5 bytes beginning at the start | |
953 | // of myString | |
954 | ||
955 | - The %b format specifier for the printf family of functions has been enhanced | |
956 | as follows: | |
957 | ||
958 | 1) When the width and precision are both unspecified, the default is %8.8b. | |
959 | 2) When only one of the width or precision is specified, the other defaults | |
960 | to the same value. For example, %4b == %.4b == %4.4b | |
961 | 3) Nul ('\0') bytes are used for field width padding. For example, | |
962 | ||
963 | printf ("%b", 0x1111deadbeef2222) // prints all eight bytes | |
964 | printf ("%4.2b", 0xdeadbeef) // prints \0\0\xbe\xef | |
965 | ||
966 | - Dynamic width and precision are now supported for all printf family format | |
967 | specifiers. For example: | |
968 | ||
969 | four = 4 | |
970 | two = 2 | |
971 | printf ("%*.*b", four, two, 0xdeadbbeef) // prints \0\0\xbe\xef | |
972 | printf ("%*d", four, two) // prints <space><space><space>2 | |
973 | ||
7a468d68 | 974 | - Preprocessor conditional expressions can now include wildcard style |
e070cc9c | 975 | matches on kernel versions. |
7a468d68 FCE |
976 | %( kernel_vr != "*xen" %? foo %: bar %) |
977 | ||
1ada6f08 FCE |
978 | - Prototype support for user-space probing is showing some progress. |
979 | No symbolic notations are supported yet (so no probing by function names, | |
980 | file names, process names, and no access to $context variables), but at | |
981 | least it's something: | |
982 | ||
983 | probe process(PID).statement(ADDRESS).absolute { } | |
984 | ||
985 | This will set a uprobe on the given process-id and given virtual address. | |
986 | The proble handler runs in kernel-space as usual, and can generally use | |
987 | existing tapset functions. | |
988 | ||
149eaccd MH |
989 | - Crash utility can retrieve systemtap's relay buffer from a kernel dump |
990 | image by using staplog which is a crash extension module. To use this | |
991 | feature, type commands as below from crash(8)'s command line: | |
992 | ||
993 | crash> extend staplog.so | |
994 | crash> help systemtaplog | |
995 | ||
996 | Then, you can see more precise help message. | |
997 | ||
998 | - You can share a relay buffer amoung several scripts and merge outputs from | |
999 | several scripts by using "-DRELAY_HOST" and "-DRELAY_GUEST" options. | |
1000 | For example: | |
1001 | ||
1002 | # run a host script | |
1003 | % stap -ve 'probe begin{}' -o merged.out -DRELAY_HOST & | |
1004 | # wait until starting the host. | |
1005 | % stap -ve 'probe begin{print("hello ");exit()}' -DRELAY_GUEST | |
1006 | % stap -ve 'probe begin{print("world\n");exit()}' -DRELAY_GUEST | |
1007 | ||
1008 | Then, you'll see "hello world" in merged.out. | |
1009 | ||
dfd11cc3 MH |
1010 | - You can add a conditional statement for each probe point or aliase, which |
1011 | is evaluated when the probe point is hit. If the condition is false, the | |
1012 | whole probe body(including aliases) is skipped. For example: | |
1013 | ||
1014 | global switch = 0; | |
1015 | probe syscall.* if (switch) { ... } | |
1016 | probe procfs.write {switch = strtol($value,10)} /* enable/disable ctrl */ | |
1017 | ||
a9e8f7e0 FCE |
1018 | - Systemtap will warn you if your script contains unused variables or |
1019 | functions. This is helpful in case of misspelled variables. If it | |
1020 | doth protest too much, turn it off with "stap -w ...". | |
1021 | ||
683b62c0 FCE |
1022 | - You can add error-handling probes to a script, which are run if a |
1023 | script was stopped due to errors. In such a case, "end" probes are | |
1024 | not run, but "error" ones are. | |
1025 | ||
1026 | probe error { println ("oops, errors encountered; here's a report anyway") | |
1027 | foreach (coin in mint) { println (coin) } } | |
98aab489 | 1028 | |
d898100a FCE |
1029 | - In a related twist, one may list probe points in order of preference, |
1030 | and mark any of them as "sufficient" beyond just "optional". Probe | |
1031 | point sequence expansion stops if a sufficient-marked probe point has a hit. | |
1032 | This is useful for probes on functions that may be in a module (CONFIG_FOO=m) | |
1033 | or may have been compiled into the kernel (CONFIG_FOO=y), but we don't know | |
1034 | which. Instead of | |
1035 | ||
1036 | probe module("sd").function("sd_init_command") ? , | |
1037 | kernel.function("sd_init_command") ? { ... } | |
1038 | ||
1039 | which might match neither, now one can write this: | |
1040 | ||
1041 | probe module("sd").function("sd_init_command") ! , /* <-- note excl. mark */ | |
1042 | kernel.function("sd_init_command") { ... } | |
1043 | ||
98aab489 | 1044 | - New security model. To install a systemtap kernel module, a user |
fedd4090 FCE |
1045 | must be one of the following: the root user; a member of the |
1046 | 'stapdev' group; or a member of the 'stapusr' group. Members of the | |
1047 | stapusr group can only use modules located in the | |
1048 | /lib/modules/VERSION/systemtap directory (where VERSION is the | |
1049 | output of "uname -r"). | |
1050 | ||
1051 | - .statement("...@file:line") probes now apply heuristics to allow an | |
1052 | approximate match for the line number. This works similarly to gdb, | |
1053 | where a breakpoint placed on an empty source line is automatically | |
1054 | moved to the next statement. A silly bug that made many $target | |
1055 | variables inaccessible to .statement() probes was also fixed. | |
98aab489 | 1056 | |
6d4a0530 FCE |
1057 | - LKET has been retired. Please let us know on <systemtap@sourceware.org> |
1058 | if you have been a user of the tapset/tools, so we can help you find | |
1059 | another way. | |
1060 | ||
4fcb4393 FCE |
1061 | - New families of printing functions println() and printd() have been added. |
1062 | println() is like print() but adds a newline at the end; | |
1063 | printd() is like a sequence of print()s, with a specified field delimiter. | |
1064 | ||
4432f146 | 1065 | * What's new since version 0.5.14?, 2007-07-03 |
db6f191e | 1066 | |
3f99432c FCE |
1067 | - The way in which command line arguments for scripts are substituted has |
1068 | changed. Previously, $1 etc. would interpret the corresponding command | |
1069 | line argument as an numeric literal, and @1 as a string literal. Now, | |
1070 | the command line arguments are pasted uninterpreted wherever $1 etc. | |
1071 | appears at the beginning of a token. @1 is similar, but is quoted as | |
1072 | a string. This change does not modify old scripts, but has the effect | |
1073 | of permitting substitution of arbitrary token sequences. | |
1074 | ||
1075 | # This worked before, and still does: | |
1076 | % stap -e 'probe timer.s($1) {}' 5 | |
1077 | # Now this also works: | |
1078 | % stap -e 'probe syscall.$1 {log(@1)}' open | |
1079 | # This won't crash, just signal a recursion error: | |
1080 | % stap -e '$1' '$1' | |
1081 | # As before, $1... is recognized only at the beginning of a token | |
1082 | % stap -e 'probe begin {foo$1=5}' | |
db6f191e | 1083 | |
4432f146 | 1084 | * What's new since version 0.5.13?, 2007-03-26 |
8438f752 | 1085 | |
b8da0ad1 FCE |
1086 | - The way in which systemtap resolves function/inline probes has changed: |
1087 | .function(...) - now refers to all functions, inlined or not | |
1088 | .inline(...) - is deprecated, use instead: | |
1089 | .function(...).inline - filters function() to only inlined instances | |
1090 | .function(...).call - filters function() to only non-inlined instances | |
1091 | .function(...).return - as before, but now pairs best with .function().call | |
1092 | .statement() is unchanged. | |
8438f752 | 1093 | |
4432f146 | 1094 | * What's new since version 0.5.12?, 2007-01-01 |
9abec538 FCE |
1095 | |
1096 | - When running in -p4 (compile-only) mode, the compiled .ko file name | |
1097 | is printed on standard output. | |
1098 | ||
dcc4fec4 FCE |
1099 | - An array element with a null value such as zero or an empty string |
1100 | is now preserved, and will show up in a "foreach" loop or "in" test. | |
1101 | To delete such an element, the scripts needs to use an explicit | |
1102 | "delete array[idx]" statement rather than something like "array[idx]=0". | |
1103 | ||
44f75386 FCE |
1104 | - The new "-P" option controls whether prologue searching heuristics |
1105 | will be activated for function probes. This was needed to get correct | |
1106 | debugging information (dwarf location list) data for $target variables. | |
1107 | Modern compilers (gcc 4.1+) tend not to need this heuristic, so it is | |
1108 | no longer default. A new configure flag (--enable-prologues) restores | |
1109 | it as a default setting, and is appropriate for older compilers (gcc 3.*). | |
9abec538 | 1110 | |
74525094 FCE |
1111 | - Each systemtap module prints a one-line message to the kernel informational |
1112 | log when it starts. This line identifies the translator version, base | |
1113 | address of the probe module, a broken-down memory consumption estimate, and | |
1114 | the total number of probes. This is meant as a debugging / auditing aid. | |
1115 | ||
29fdb4e4 DS |
1116 | - Begin/end probes are run with interrupts enabled (but with |
1117 | preemption disabled). This will allow begin/end probes to be | |
1118 | longer, to support generating longer reports. | |
74525094 | 1119 | |
37ebca01 FCE |
1120 | - The numeric forms of kernel.statement() and kernel.function() probe points |
1121 | are now interpreted as relocatable values - treated as relative to the | |
1122 | _stext symbol in that kernel binary. Since some modern kernel images | |
1123 | are relocated to a different virtual address at startup, such addresses | |
1124 | may shift up or down when actually inserted into a running kernel. | |
1125 | ||
1126 | kernel.statement(0xdeadbeef): validated, interpreted relative to _stext, | |
1127 | may map to 0xceadbeef at run time. | |
1128 | ||
1129 | In order to specify unrelocated addresses, use the new ".absolute" | |
1130 | probe point suffix for such numeric addresses. These are only | |
1131 | allowed in guru mode, and provide access to no $target variables. | |
1132 | They don't use debugging information at all, actually. | |
1133 | ||
1134 | kernel.statement(0xfeedface).absolute: raw, unvalidated, guru mode only | |
1135 | ||
4432f146 | 1136 | * What's new since version 0.5.10?, 2006-10-19 |
7ad9d4f5 FCE |
1137 | |
1138 | - Offline processing of debugging information, enabling general | |
1139 | cross-compilation of probe scripts to remote hosts, without | |
1140 | requiring identical module/memory layout. This slows down | |
1141 | compilation/translation somewhat. | |
1142 | ||
1143 | - Kernel symbol table data is loaded by staprun at startup time | |
1144 | rather than compiled into the module. | |
1145 | ||
1146 | - Support the "limit" keyword for foreach iterations: | |
1147 | foreach ([x,y] in ary limit 5) { ... } | |
1148 | This implicitly exits after the fifth iteration. It also enables | |
1149 | more efficient key/value sorting. | |
1150 | ||
1151 | - Support the "maxactive" keyword for return probes: | |
1152 | probe kernel.function("sdfsdf").maxactive(848) { ... } | |
1153 | This allows up to 848 concurrently outstanding entries to | |
1154 | the sdfsdf function before one returns. The default maxactive | |
1155 | number is smaller, and can result in missed return probes. | |
1156 | ||
1157 | - Support accessing of saved function arguments from within | |
1158 | return probes. These values are saved by a synthesized | |
1159 | function-entry probe. | |
1160 | ||
1161 | - Add substantial version/architecture checking in compiled probes to | |
1162 | assert correct installation of debugging information and correct | |
1163 | execution on a compatible kernel. | |
1164 | ||
1165 | - Add probe-time checking for sufficient free stack space when probe | |
1166 | handlers are invoked, as a safety improvement. | |
1167 | ||
1168 | - Add an optional numeric parameter for begin/end probe specifications, | |
e070cc9c | 1169 | to order their execution. |
7ad9d4f5 FCE |
1170 | probe begin(10) { } /* comes after */ probe begin(-10) {} |
1171 | ||
1172 | - Add an optional array size declaration, which is handy for very small | |
1173 | or very large ones. | |
e070cc9c | 1174 | global little[5], big[20000] |
7ad9d4f5 FCE |
1175 | |
1176 | - Include some example scripts along with the documentation. | |
1177 | ||
1178 | - Change the start-time allocation of probe memory to avoid causing OOM | |
1179 | situations, and to abort cleanly if free kernel memory is short. | |
1180 | ||
1181 | - Automatically use the kernel DWARF unwinder, if present, for stack | |
1182 | tracebacks. | |
1183 | ||
1184 | - Many minor bug fixes, performance, tapset, and error message | |
1185 | improvements. |