Debian Codegraph @

NEWS

raw
1 * What's new in version 5.4, 2025-10-31
2
3 - The kernel-context @cast operator now implicitly searches a kernel's
4 <vmlinux.h> generated header file first, if available (kernel 5.7+),
5 for type declarations. This can make some debuginfo access
6 unnecessary, and thus processing faster. It can work around kernel
7 API changes where type declarations move between headers.
8 Use --compatible=5.3 to disable this behaviour.
9 Use @cast(..., "kernel<vmlinux.h>") manually if desired.
10
11 - Type checking and autocast processing have been made more thorough,
12 so elided variables are checked more and @defined() tests may be
13 more complicated. Preexisting scripts that rely on elision for
14 bypassing type violations may now get caught. No --compatible
15 option exists to suppress this new behaviour.
16
17 - The sys/sdt.h file now arranges to include the section flag "R"
18 (RETAIN) for the .stapsdt.base elf sections related to sdt markers,
19 for compatibility with aggressive GC operations in some linkers.
20
21 * What's new in version 5.3, 2025-05-02
22
23 - Updated to support drastic linux 6.13 kbuild changes, numerous
24 other 6.14/6.15 linux API changes.
25
26 - The first pass (-p1) now runs parse operations concurrently over of
27 the hundreds of tapset .stp files, potentially saving seconds of
28 time at startup.
29
30 - The systemtap rpm package now invokes a few basic tests during
31 %check, intended to confirm compatibility with the kernel.
32
33 * What's new in version 5.2, 2024-11-08
34
35 - New /* pragma:suffix */ for file-level embedded C code blocks to
36 be placed near the end of the emitted kernel module C file.
37
38 - The systemtap-sdt-devel subrpm has been split into -dtrace and
39 -devel subpackages.
40
41 * What's new in version 5.1, 2024-04-26
42
43 - An experimental "--build-as=USER" flag to reduce privilege during
44 script compilation.
45
46 - Support DWARF "DW_OP_bra" location construct.
47
48 - Dynamic namespace switching for processes targeted via "-x PID".
49
50 - New probe-points for userland hardware breakpoints/watchpoints
51 targeting processes (PR31180):
52
53 probe process.data(ADDRESS).write
54 probe process.data(ADDRESS).rw
55 probe process.data(ADDRESS).length(LEN).write
56 probe process.data(ADDRESS).length(LEN).rw
57
58 - Support for stap --remote=bpf.
59
60 - Improved searching heuristics for probing symbol names with/without
61 symbol-version suffixes.
62
63 - Improved message transport robustness for heavy traffic and for
64 short runs.
65
66 * What's new in version 5.0, 2023-11-04
67
68 - Performance improvements in uprobe registration and module startup.
69
70 - More probe point process details are printed in "-L" list mode with
71 more "-v".
72
73 - For the case where newer kernels may break systemtap runtime APIs,
74 better pass-4 failure diagnostics are printed.
75
76 - Tapset function print_ubacktrace_fileline() now understands DWARF5.
77
78 - The target(s) of process probes may be specified by path name globs,
79 as located selected debuginfod servers. This requires the
80 debuginfod servers to support "metadata" queries. The following
81 probes all of the binaries matching /usr/*/curl known to the
82 debuginfod servers, regardless of what's currently installed as the
83 system /usr/bin/curl:
84
85 # export DEBUGINFOD_URLS="URL1 URL2 ..."
86 # stap -e 'probe debuginfod.process("/usr/*/curl").begin { log("hi") }'
87
88 The archive glob may be given as an optional component to filter further:
89
90 # stap -e 'probe debuginfod.archive("*.fc38*")
91 .process("/usr/*/c*").function("main") { log("Hello World") }'
92
93 - The kernel-user message transport system added framing codes, making
94 the transport more reliable, but becoming incompatible across
95 pre-5.0 versions. Use matching versions of stap and staprun.
96
97 - RHEL6, kernel 2.6.32* as well as older releases have been deprecated
98 from the codebase. RHEL7 and kernel version 3.10 are now the oldest
99 supported versions for Systemtap.
100
101 - The testsuite Makefile has been simplified to remove concurrency,
102 so "parallel" and "resume" modes are gone.
103
104 - New runtime macro STP_TIMING_NSECS is now supported for reporting probe timing
105 stats in nsecs instead of cycles. This may become default later.
106
107 - Add new runtime macro STP_FORCE_STDOUT_TTY to override STP_STDOUT_NOT_ATTY.
108
109 * What's new in version 4.9, 2023-04-28
110
111 - ISystemtap: the new interactive systemtap jupyter kernel. This provides
112 a simple GUI for writing/running Systemtap scripts in an easy, incremental
113 way within Jupyterlab. Added 2 news scripts, stap-jupyter-install
114 and stap-jupyter-container. See stap-jupyter(1).
115
116 - The new "language-server" mode, specified by "stap --language-server",
117 starts a LSP server which will communicate with the client via stdio.
118 This server currently supports code completion suggestions.
119 See language-server/README.md for more details and usage instructions.
120
121 - Safety/liveness checking for $context variable assignments in probes of
122 retpoline-compiled kernels is temporarily disabled.
123
124 * What's new in version 4.8, 2022-11-03
125
126 - DWARF-related probes (.function, .statement) now merge DWARF and
127 non-DWARF symbol-table based matches, rather than being either-or.
128
129 - The python3 tapset was extended to support python3 3.9, 3.10, and 3.11.
130 See stapprobes(3stap) for further details on probing python functions.
131
132 - A template cve band-aid script is now included, which demonstrates
133 how to use a new 'livepatch.stp' tapset to standardize activation,
134 interactive control, and monitoring of systemtap cve band-aids.
135
136 - The kernel runtime now uses much less memory when the number of
137 "possible CPUs" are way more than the online ones. For example,
138 VMWare guests usually have 128 "possible CPUs" while fewer
139 CPUs are actually present or online in the guest system.
140
141 - The memory allocation size is now irrelevant to the value of
142 NR_CPUS of the current kernel. It is only subject to the number
143 of "possible CPUs" or "online CPUs".
144
145 - CPU hotplug is supported to the extent that there won't be any
146 kernel panics or memory corruptions.
147
148 - The bpf backend's embedded-code assembler has been improved to
149 support more conventional assembly syntax with named opcodes. The
150 opcode names are based on the iovisor bpf-docs documentation at
151 https://github.com/iovisor/bpf-docs/blob/master/eBPF.md
152
153 * What's new in version 4.7, 2022-05-02
154
155 - SystemTap now supports an additional method to sign modules on
156 UEFI/SecureBoot systems. In addition to the existing method of
157 using a trusted stap-server, the module can also be signed without
158 using a server by specifying the "stap --sign-module" option. (Key
159 enrollment still requires a one-time reboot and BIOS conversation.)
160 https://sourceware.org/systemtap/wiki/SecureBoot
161
162 - Includes new tool stap-profile-annotate, combining systemtap &
163 debuginfod to collect system-wide profiling statistics, and
164 produce annotated source files for all relevant programs/libraries.
165
166 - target processes given with the -c/-x parameters are now always
167 added to the -d list for possible symbol/unwind data extraction,
168 for simplifying profiling invocations. Consider --ldd.
169
170 - The "subbuf" size for kernel-to-user bulk message passing is fixed
171 at the page size. Number of such subbufs is affected by the
172 stap "-s" parameter and amount of free memory available.
173
174 * What's new in version 4.6, 2021-11-15
175
176 - SystemTap has added support for the 64-bit RISC-V architecture.
177
178 - stap-prep now tries to download the main kernel debuginfo file from
179 a debuginfod server, if configured.
180
181 - Updated syscall_any tapset mapping to include newer syscalls.
182
183 - syscall_any tapset can be used by the bpf backend.
184
185 - SystemTap now uses DynInst to perform a liveness analysis on
186 target variables and warn when a guru-mode modification to a variable
187 will have no effect. The liveness analysis is currently done on
188 x86_64, PowerPC, and AArch64.
189
190 - The kernel-user relayfs transport again sorts messages into a total
191 time order across CPUs. High output-volume scripts may need a
192 larger "-s BUF" parameter to reliably transfer. "-b" bulk mode
193 is also available again as an alternative.
194
195 - abort() tapset can be used by the bpf backend.
196
197 - The bpf backend now supports foreach iteration in multi-key
198 associative arrays.
199
200 * What's new in version 4.5, 2021-05-07
201
202 - Java probing support has been updated to work with the latest
203 versions of the JVM and byteman (PR27739).
204
205 - An initial version of the bpf/uconversions.stp tapset provides
206 tapset functions such as user_long_error() to access values in
207 userspace.
208
209 - Enabled the -c option to work with the bpf backend (PR25177).
210
211 - Enum values can now be accessed as $context variables (PR25346).
212
213 - Executables for which stap has execute but not read permissions
214 (--x--x--x) can now be probed with build-id probes and debuginfod.
215 This allows probing some setuid programs (PR27251).
216
217 - Added VMA-tracking support to the stapdyn backend.
218
219 - Several concurrency/locking fixes and improvements were made to the
220 uprobes family of probes and to the transport subsystem. Large
221 machines with hundreds of CPUs are better supported.
222
223 - The kernel runtime now uses procfs as the default namespace for
224 the relayfs pseudo-files.
225
226 - Floating point variables may now be accessed directly as normal
227 $context variables. 32-bit floats are automatically widened to
228 doubles. (PR13838)
229
230 - A wider variety of SecureBoot MOK keys are now recognized for
231 more reliable triggering of stap-server module signing. Document
232 some additional lockdown/secureboot administrative escape options.
233 (PR26665)
234
235 - On startup, stap explains the [man FOO] diagnostic syntax.
236
237 * What's new in version 4.4, 2020-11-09
238
239 - Make syscall arguments writable again in non-DWARF probes on kernels
240 that use syscall wrappers to pass arguments via pt_regs (currently
241 x86_64 4.17+ and aarch64 4.19+).
242
243 - Add new syntax for defining aliases with both a prologue and an epilogue:
244 'probe ALIAS = PROBE { <prologue> }, { <epilogue> }'
245
246 - Add @probewrite predicate. @probewrite(var) returns 1 if var has been
247 written to in the probe handler body and 0 otherwise. The check can
248 only be used with probes that have an epilogue or prologue.
249
250 - Implicit thread local storage variables can now be accessed on
251 x86_64, ppc64le, and s390x.
252
253 - Replaced spinlocks with RCU locks in vma map and utrace task's hash
254 table lookups which reduces CPU time a lot when there are a lot of
255 target processes and vma tracker or task finder is enabled. We also
256 increased the default hash table sizes to reduce hash conflicts.
257
258 - stap-prep now avoids downloading kernel debuginfo if a successful
259 connection to debuginfod server is made.
260
261 - The locks required to protect concurrent access to global variables
262 has been optimized with a "pushdown" algorithm, so that they span
263 the smallest possible critical region. Formerly, and with
264 --compatible=4.3, locks always spanned the entire probe handler.
265 Lock pushdown means much greater potential concurrency between
266 probes running on different CPUs.
267
268 - Systemtap now supports kernel-lockdown configurations that disable
269 debugfs, by instead using procfs to carry relayfs transport files.
270
271 - Systemtap now supports extracting 64-bit floating point and stored
272 in long type. Also basic floating point arithmetic and comparison
273 functions are provided in a tapset. More automated syntax coming
274 soon. e.g.:
275 probe process.function("foo") {
276 fp = user_long(& $fp_variable)
277 println (fp_to_string (fp_add (string_to_fp("3.14"), fp)))
278 }
279
280 * What's new in version 4.3, 2020-06-11
281
282 - tapset functions for reading CPU registers and primitives involved with the
283 process memory maps work in 'probe process.begin'.
284
285 - probe aliases starting with nfs.proc support IPv6 as server_ip and client_ip.
286 Also, ip are represented with string valued now.
287
288 - The target of process probes may be specified by hexadecimal buildid
289 as an alternative to path names. This makes it possible to probe a
290 variety of versions or aliases of a program, even if they are
291 running inside containers under a different path name. Works best
292 with a debuginfod server that publishes the executables / debuginfo.
293 The following probes glibc.so 2.32-2.fc32.x86_64 from fedora running
294 anywhere on your machine.
295
296 # export DEBUGINFOD_URLS=https://debuginfod.elfutils.org/
297 # stap -e 'probe process("7ca24d4dc3de9d62d9ad6bb25e5b70a3e57a342f")
298 .function("*system") { log("hi") }'
299
300 - Functions can now be context-sensitive, meaning that they may make
301 references to $context variables and similar constructs that could
302 formerly appear only inside probe handlers. This is implemented by
303 cloning the such functions for each probe.
304 Only some probe point (dwarf-based user & kernel) types supported.
305 function foo () { println ($$vars) }
306 probe kernel.function("do_exit") { foo() }
307 probe process("/bin/ls").function("main") { foo() }
308 probe process("/lib*/libc.so.6").mark("*") { foo() }
309
310 - Add new tapset function dump_stack() which prints the current
311 kernel backtrace to the kernel trace buffer (as a thin wrapper
312 around the kernel C API function dump_stack).
313
314 - Almost all of the kmalloc() allocations exceeding 4KB have been
315 replaced by vmalloc(). This helps stap's kernel runtime work
316 properly on systems with serious fragmentation in physical memory
317 address space.
318
319 - More $variable resolution errors may be generated, especially for
320 @var("") constructs that target global variables. These are
321 duplicate-eliminated by default, but may be seen with verbosity>=2.
322
323 - The stapbpf backend now supports try-catch statements, an improved
324 error tapset and error probes.
325
326 - The "Build-id mismatch" condition now becomes a warning, so while
327 related probes are not inserted, the rest of the script may run.
328
329 - The process(EXE).begin probe handlers are now always triggered for
330 already-running target processes.
331
332 - The proc_mem_rss() tapset function now includes the resident shared
333 memory pages as expected. The old behavior can be restored by the
334 --compatible=4.2 option on the command line.
335
336 - Modules compiled with guru mode for a particular kernel version can
337 now only be loaded on kernels with exactly matching version
338 (vermagic string) instead of any kernel whose API matches according
339 to the modversions mechanism. Use -B CONFIG_MODVERSIONS=y to restore
340 the prior behaviour.
341
342 * What's new in version 4.2, 2019-11-18
343
344 - Initial support for multi-dimensional supports has been added to
345 the stapbpf backend. Note that these arrays cannot be iterated upon
346 with a foreach loop.
347
348 - The stapbpf backend now supports sorting by value in foreach loops.
349
350 - The stapbpf backend now supports the concatenation operator for
351 userspace probes.
352
353 - The stapbpf backend now supports the target() function and -x option.
354
355 - The gettimeofday_* functions are now provided for the stapbpf backend.
356
357 - The values of an array can now be iterated over in foreach loops in
358 the stapbpf backend. They are no longer defaulted to 0.
359
360 - The stapbpf backend now supports order parameterization for begin
361 and end probes.
362
363 - When the -v option is set along with -L option, the output includes
364 duplicate probe points which are distinguished by their PC address.
365
366 - The stapbpf backend now supports stap-exporter extensions.
367
368 - The stapbpf backend now supports procfs probes. The implementation
369 uses FIFO special files in /var/tmp/systemtap-$EFFUSER/MODNAME instead
370 of the proc filesystem files.
371
372 - The eBPF backend now uses bpf raw tracepoints for kernel.trace("*")
373 probes. These have target variable arguments that match the
374 arguments available for the traditional linux kernel modules
375 tracepoints. Support for the older bpf tracepoint arguments can be
376 forced with a --compatible=4.1 option on the command line.
377
378 - New backtracing functions print_[u]backtrace_fileline() have been added
379 to the tapset. These functions behave similarly to print_[u]backtrace(),
380 the only difference being that file names and line numbers are added
381 to the backtrace.
382
383 - Now it is possible to issue a backtrace using user specified pc, sp,
384 and fp which can be used to generate backtraces of different contexts.
385 This was introduced to get backtraces of user code from within the go
386 runtime but it can also be used to do things like generating backtraces
387 of user code from within signal handlers.
388
389 - The compiler optimizes out probes with empty handlers. Previously,
390 warnings were issued but, the probe was not internally removed. For
391 example, this script now outputs a warning and an error as the only
392 probe handler is empty:
393
394 probe begin {}
395
396 Additionally, probe handlers that evaluate to empty are also removed.
397 For example, in this script, the begin probe is elided as $foo does
398 not exist, however, an error won't be outputted because atleast one
399 probe with a non-empty handler exists (probe begin):
400
401 probe begin {
402 print("Protected from elision")
403 }
404
405 probe end {
406 if (@defined($foo)) { print("Evaluates to empty handler") }
407 }
408
409 - The automatic printing implementation now differentiates between
410 pointer and integer types, which are printed as hex or decimal
411 respectively.
412
413 - The sys/sdt.h file changes the way i386 registers operands are
414 sometimes named, due to an ambiguity. A comment block explains.
415
416 * What's new in version 4.1, 2019-05-07
417
418 - Runtime/tapsets were ported to include up to kernel version 5.1-rc2
419
420 - The translator's pass-2 (elaboration) phase has been dramatically
421 accelerated by eschewing processing of unreferenced parts of the
422 tapset and embedded-C code.
423
424 - New macros @this1, ..., @this8 have been added to the script language.
425 The macros can be used to save values in entry probes and later retrieve
426 them in return probes. This can be used in instances where @entry does
427 not work. For example:
428
429 probe tp_syscall.read {
430 @this1 = buf_uaddr
431 }
432
433 probe tp_syscall.read.return {
434 buf_uaddr = @this1
435 printf("%s", user_string(buf_uaddr))
436 }
437
438 - Operator @var() no longer assumes @entry() in return probes.
439 The old behavior can be restored by the '--compatible 4.0' option.
440
441 - Where available (kernel 4.15+), the kernel-module runtime now uses
442 the kernel-provided ktime_get_real_fast_ns() mechanism for timekeeping
443 rather than the SystemTap runtime's own timekeeping machinery.
444
445 - New stapbpf tapset task.stp with function task_current.
446
447 - New stapbpf tapset functions kernel_string, kernel_string_n,
448 execname, ktime_get_ns.
449
450 - A new stapbpf transport layer has been implemented based on perf_events
451 infrastructure. This transport layer removes some limitations on strings
452 and printf() that were previously imposed by BPF's trace_printk() mechanism:
453 - It is now possible to use format-width specifiers in printf().
454 - It is now possible to use more than three format specifiers in printf().
455 - It is now possible to use multiple '%s' format specifiers in printf().
456 - Using stapbpf should no longer trigger a trace_printk()-associated
457 warning on dmesg.
458
459 - In the stapbpf backend, foreach() now supports iteration of arrays
460 with string keys.
461
462 - A preview version of statistical aggregate functionality for stapbpf
463 is now included. For now, in the stapbpf backend, aggregates only
464 support @count(), @sum() and @avg() operations.
465
466 - Added support for unhandled DWARF operator DW_OP_GNU_parameter_ref in
467 location expressions for target symbols.
468
469 * What's new in version 4.0, 2018-10-13
470
471 - Runtime/tapsets were ported to include up to kernel version 4.19-rc
472
473 - A new network service, stap-exporter, is included. It glues
474 systemtap and the web. It allows a prometheus (or compatible
475 systems such as pcp) to consume metrics exported by systemtap
476 scripts. Some tapset macros/functions are available to make it
477 easier to write such scripts. See the stap-exporter(8) man page and
478 the systemd service.
479
480 - When a systemtap module is loaded, the name of the original stap script
481 is now printed to dmesg by the kernel runtime.
482
483 - On some Fedora kernels, the information necessary to automatically
484 engage in SecureBoot module signing is hidden from systemtap.
485 Setting the $SYSTEMTAP_SIGN environment variable forces it on.
486 A running stap-server instance will also be needed.
487
488 - Embedded-C functions marked /* guru */ may now be invoked from other
489 tapset probes / functions, while still being invalid for normal call
490 from an unprivileged user script.
491
492 - The syscall tapset is now updated to work on kernel 4.17+.
493 Additionally, the tapset now includes an automatic fallback alias to
494 the sys_enter / sys_exit kernel tracepoints, if no other
495 kprobe-based mechanism is found. These changes have brought
496 unavoidable consequences. Raw $target variables for the syscall
497 arguments and return probes (e.g. @entry($fd), $return, returnval())
498 may not longer be relied upon. Instead, use the variables defined by
499 the tapset aliases. For example:
500
501 % stap -L syscall.read
502 syscall.read name:string fd:long buf_uaddr:long count:long argstr:string
503 % stap -L syscall.read.return
504 syscall.read.return name:string retval:long retstr:string
505
506 to see the available variables for that syscall. See
507 [man stapprobes] for further details. returnval() in particular is
508 being deprecated soon; use retval in syscall.*.return probes instead.
509
510 - New script language operators @kderef/@uderef and @kregister/@uregister
511 were added.
512 @kderef/@uderef (size,address) can be used to dereference integers and
513 @kregister/@uregister (dwarf#) can be used to access register values.
514
515 - A systemd service file has been added for systemtap.service (which
516 runs a configurable set of scripts automatically on system
517 startup). The existing /etc/init.d/systemtap init script has been
518 moved to a new utility command 'systemtap-service' which preserves
519 functionality such as configuring onboot systemtap scripts via
520 dracut. See systemtap-service(8) for details.
521
522 - The eBPF backend's string support has been improved. Strings
523 can now be stored in variables, passed as function arguments,
524 and stored as array keys and values.
525
526 - The 3rd operand of the ternary operator '?:' in the script language
527 now binds tighter than the binary assignment operators like '=' and
528 '+=', just like the C language. The original operator precedence can
529 be restored by the '--compatible 3.3' option.
530
531 - The script language now supports the use of bare 'return' statements
532 (without any return values) inside functions which do not return any
533 values. A trailing semicolon is recommended for such return
534 statements to avoid any potential ambiguity. The parser treats a
535 following semicolon (';') or a closing curly bracket ('}') as a
536 terminator for such bare return statements.
537
538 - Parentheses after unary '&' with a target-symbol expression is
539 now accepted in the script language.
540
541 - Tapset functions register() and u_register() now support 8-bit
542 x86 register names "ah", "al", "bh", "bl", "ch", "cl", "dh", and
543 "dl" on both x86_64 and i386. And 16-bit x86 registers are now
544 truly read as 16-bit integers instead of as 32-bit ones.
545
546 - The experimental ftrace ring buffer mechanism (STP_USE_RING_BUFFER)
547 has been deprecated and may be removed in future versions.
548
549 * What's new in version 3.3, 2018-06-08
550
551 - A new "stap --example FOO.stp" mode searches the example scripts
552 distributed with systemtap for a file named FOO.stp, so its whole
553 path does not need to be typed in.
554
555 - Systemtap's runtime has learned to deal with several of the
556 collateral damage from kernel hardening after meltdown/spectre,
557 including more pointer hiding and relocation. The kptr_restrict
558 procfs flag is forced on if running on a new enough kernel.
559
560 - The "stap --sysroot /PATH" option has received a revamp, so it
561 works much better against cross-compiled environments.
562
563 - The eBPF backend has learned to perform loops - at least in the
564 userspace "begin/end" probe contexts, so one can iterate across BPF
565 arrays for reporting. (The linux kernel eBPF interpreter precludes
566 loops and string processing.) It can also handle much larger probe
567 handler bodies, with a smarter register spiller/allocator.
568
569 - The eBPF backend now supports uprobes, perf counter, timer, and
570 tracepoint probes.
571
572 - An rpm macro %_systemtap_tapsetdir is now defined, to make it
573 easier for third party packages to add .stp files into the standard
574 tapset.
575
576 - Several low level locking-related fixes were added to the runtime
577 that used uprobes/tracepoint apis, in order to work more reliably on
578 rt kernels and on high-cpu-count machines.
579
580 - Runtime/tapsets were ported to include up to kernel version 4.16.
581 (The syscall tapsets are broken on kernel 4.17-rc, and will be fixed
582 in a next release coming soon; PR23160.)
583
584 - Add new built-in tapset function abort() which is similar to exit(),
585 but it aborts the current probe handler (and any function calls in
586 it) immediately instead of waiting for its completion. Probe handlers
587 already running on *other* CPU cores, however, will still continue
588 to their completion. Unlike error(), abort() cannot be caught by
589 try {...} catch {...}. Similar to exit(), abort() yeilds the zero
590 process exit code. It works with both the kernel and dyninst runtimes.
591 This function can be disabled by the '--compatible 3.3' option.
592
593 * What's new in version 3.2, 2017-10-18
594
595 - SystemTap now includes an extended Berkeley Packet Filter (eBPF)
596 backend. This experimental backend does not use kernel modules
597 and instead produces eBPF programs that are verified by the kernel
598 and executed by an in-kernel virtual machine. Select this backend
599 with the new stap option '--runtime=bpf'. For example:
600
601 stap --runtime=bpf -e \
602 'probe kernel.function("sys_open") { printf("hi from stapbpf!\n") }'
603
604 Please see the stapbpf(8) man page for more information.
605
606 - The regular expression engine now supports extraction of the matched
607 string and subexpressions using the matched() tapset function:
608
609 if ("regexculpicator" =~ "reg(ex.*p).*r") log(matched(1))
610 -> exculp
611
612 - The translator produces better diagnostics for common/annoying case
613 of missing debuginfo that blocks use of context $variables.
614
615 - "stap -k" build trees in $TMPDIR now also include a preprocessed .i form
616 of the generated module .c code, for problem diagnostics purposes.
617
618 - The syscall.execve probes now provide a decoded env_str string vector,
619 just like the argument vector. Because of this, the unused
620 __count_envp() and __count_compat_evenp() functions have been
621 deprecated.
622
623 - The task_exe_file() Function has been deprecated and replaced by the
624 current_exe_file() function.
625
626 - A new probe alias input.char allows scripts to access input from stdin
627 during runtime.
628
629 * What's new in version 3.1, 2017-02-17
630
631 - Systemtap now needs C++11 to build.
632
633 - Syscall and nd_syscall tapsets have been merged in a way that either
634 dwarf-based, or non-dwarf probe gets automatically used based on
635 debuginfo availability (e.g. probe syscall.open).
636
637 To force use the dwarf based probe, a dw_syscall has been introduced
638 (e.g. probe dw_syscall.open) and the non-dwarf syscall probes were
639 left untouched (e.g. nd_syscall.open).
640
641 - The syscall tapset files have been reorganized in a way that original
642 big tapset files carrying many syscall probes were split into smaller
643 'sysc_' prefixed tapset files. This should reduce the syscall tapset
644 maintenance burden.
645
646 - The powerpc variant of syscall.compat_sysctl got deprecated on favor of
647 syscall.sysctl32. This aligns the syscall to its respective nd_syscall and
648 to ia64/s390/x86_64 variants too.
649
650 - The syscall.compat_pselect7a (this was actually a typo, but still available
651 for compatibility purposes with --compatible 1.3) has beed deprecated.
652
653 - The 'description_auddr' convenience variable of syscall.add_key has been
654 deprecated.
655
656 - Support has been added for probing python 2 and 3 functions using a
657 custom python helper module. Python function probes can target
658 function entry, returns, or specific line numbers.
659
660 probe python2.module("myscript").function("foo")
661 { println($$parms) }
662
663 To run with the custom python helper module, you'd use python's '-m'
664 option like the following:
665
666 stap myscript.stp -c "python -m HelperSDT myscript.py"
667
668 - Java method probes now convert all types of java parameters to
669 strings using the java toString() method before passing them to
670 systemtap probes; new argN variables copy them into string
671 variables. Previously, only numeric types were passed, and only by
672 casting to integers. The previous behaviour is available with
673 --compatible=3.0 .
674
675 3.1: probe java(...).class(...).method(...) { printf("%s", arg1) }
676 3.0: probe java(...).class(...).method(...) { printf("%d", $arg1) }
677
678 - An older defensive measure to suppress kernel kprobes optimizations
679 since the 3.x era has been disabled for recent kernels. This improves
680 the performance of kernel function probes. In case of related problems,
681 please report and work around with:
682 # echo 0 > /proc/sys/debug/kprobes-optimization
683
684 - Context variables in .return probes should be accessed with @entry($var)
685 rather than $var, to make it clear that entry-time snapshots are being
686 used. The latter construct now generates a warning. Availability testing
687 with either @defined(@entry($var)) or @defined($var) works.
688
689 - Tapsets containing process probes may now be placed in the special
690 $prefix/share/systemtap/tapset/PATH/ directory to have their process parameter
691 prefixed with the location of the tapset. For example,
692
693 process("foo").function("NAME") expands to process("/usr/bin/foo").function("NAME")
694 when placed in $prefix/share/systemtap/tapset/PATH/usr/bin/
695
696 This is intended to help write more reusable tapsets for userspace binaries.
697
698 - The implementation of "var <<< X" for each aggregate variable is now
699 specially compiled to compute only the script-requested @op(var) values,
700 not all potential ones. This speeds up the <<< operations.
701
702 - Systemtap now warns if script arguments given on the command line are unused,
703 instead of mentioned by the script with $n/@n.
704
705 - Netfilter tapsets now provide variables data_hex and data_str to display packet
706 contents in hexadecimal and ASCII respectively.
707
708 - Translator now accepts new @const() operator for convenient expressing
709 constants in tapset code, or guru-mode scripts. See stap(1) for details.
710
711 - New -T option allows the script to be terminated after a specified number
712 of seconds. This is a shortcut for adding the probe, timer {exit()}.
713
714 - New installcheck-parallel testsuite feature allows running the tests in
715 parallel in order to save time. See testsuite/README for details.
716
717 - New tapset functions set_user_string(), set_user_string_n(), set_user_long()
718 set_user_int(), set_user_short(), set_user_char() and set_user_pointer() to
719 write a value of specified type directly to a user space address.
720
721 - New tapset functions user_buffer_quoted(), user_buffer_quoted_error(),
722 kernel_buffer_quoted(), and kernel_buffer_quoted_error() to print a
723 buffer of an exact length. These functions can handle '\0' characters
724 as well.
725
726 - New statistics @variance() operator using the Welford's online algorithm
727 for per-cpu computation, and the Total Variance formula authored by
728 Niranjan Kamat and Arnab Nandi from the Ohio State University for the
729 cross-cpu aggregation.
730
731 - New command within interactive mode, sample. Allows you to search through
732 all included example scripts to load for further editing or running. Sample
733 and example scripts have been moved to /usr/share/systemtap/examples. A
734 symlink in the former location under $docdir links to it.
735
736 * What's new in version 3.0, 2016-03-27
737
738 - The new experimental "interactive" mode, specified by "stap -i",
739 drops you into a command-line prompt where you can build up a script,
740 run it, edit it, run it again, etc. Type "help" for a list of commands.
741
742 - New experimental --monitor[=INTERVAL] option similar to unix "top". This
743 allows users to see statistics about the running module(uptime, module name,
744 invoker uid, memory sizes, global variables, and the current probe list
745 along with their statistics).
746
747 An interface is also provided to allow control over the running
748 module(resetting global variables, sorting the list of probes, deactivating
749 and reactivating probes).
750
751 - The performance of associative arrays have been dramatically
752 improved, especially for densely filled tables and for multiple
753 indexes. The hash tables behind these arrays is now sized as a
754 function of the array maximum size with an optional MAPHASHBIAS
755 space/time tradeoff knob.
756
757 - Add macros @prints to print a scalar aggregate variable, @prints[1-9]
758 to print an array aggregate (of given index-arity), formatted similarly
759 to the automatic printing of written-only global variables.
760
761 global a, b
762 probe oneshot { a <<< 1; b[tid()] <<< 2 }
763 probe end { @prints(a); @prints1(b) }
764
765 - Functions may now be overloaded during module runtime using the "next"
766 statement in script functions and STAP_NEXT macro for embedded-C functions.
767 They may also be overloaded by number of parameters during compile time.
768 For example,
769
770 Runtime overloading:
771 function f() { if (condition) next; print("first function") }
772 function f() %{ STAP_NEXT; print("second function") %}
773 function f() { print("third function") }
774
775 For the given functions above, a functioncall f(), will execute the body of the
776 third function if condition evaluates to true and print "third function".
777 Note that the second function is unconditionally nexted.
778
779 Parameter overloading:
780 function g() { print("first function") }
781 function g(x) { print("second function") }
782 g() -> "first function"
783 g(1) -> "second function"
784
785 Note that runtime overloading does not occur in the above example as the number
786 of parameters of the functions differ. The use of a next statement inside a function
787 while no more overloads remain will trigger a runtime exception. The function
788 candidates are selected at compile time and is determined by the number of arguments
789 provided for the functioncall.
790
791 - Add Czech version of manual pages.
792
793 - The stap compile server will log the stap client's options that are passed
794 to the server. The options that get logged on the server will include the
795 script name or the -e script, depending on which is used by the client.
796
797 - Embedded-C functions and blocks may now access script level global variables
798 using the STAP_GLOBAL_GET_* and STAP_GLOBAL_SET_* macros.
799
800 To read or write the script global var, the /* pragma:read:var */ or
801 /* pragma:write:var */ marker must be placed in the embedded-C function or block.
802 The written type must match the type inferred at script level.
803
804 Scalars:
805 STAP_GLOBAL_SET_var(STAP_GLOBAL_GET_var()+1) -> increments script global var by 1
806 STAP_GLOBAL_SET_var("hello")
807
808 Associative arrays:
809 STAP_GLOBAL_GET_var(index-1, ..., index-n)
810 STAP_GLOBAL_SET_var(index-1, ..., index-n, new value)
811
812 - Probe point brace expansion is now supported to improve brevity in
813 specifying probe points. For example,
814
815 process.{function("a"), function("b").{call,return}}
816 => process.function("a"), process.function("b").call, process.function("b").return
817
818 process.{function("*").callees,plt}?
819 => process.function("*").callees?, process.plt?
820
821 {kernel,module("nfs")}.function("nfs*")!
822 => kernel.function("nfs*")!, module("nfs").function("nfs*")!
823
824 - Profiling timers at arbitrary frequencies are now provided and perf probes
825 now support a frequency field as an alternative to sampling counts.
826
827 probe timer.profile.freq.hz(N)
828 probe perf.type(N).config(M).hz(X)
829
830 The specified frequency is only accurate up to around 100hz. You may
831 need to provide a higher value to achieve the desired rate.
832
833 - Added support for private global variables and private functions. The scope
834 of these is limited to the tapset file they are defined in (PR19136).
835
836 - New tapset function string_quoted() to quote and \-escape general strings.
837 String $context variables that are pretty-printed are now processed with
838 such a quotation engine, falling back to a 0x%x (hex pointer) on errors.
839
840 - Functions get_mmap_args() and get_32mmap_args() got deprecated.
841
842 * What's new in version 2.9, 2015-10-08
843
844 - SystemTap now uses symbols from /proc/kallsyms when kernel debuginfo is not
845 available.
846
847 - New --prologue-searching[=WHEN] option has been added to stap with '-P' being
848 its short counterpart. Using --prologue-searching=never turns prologue
849 searching deliberately off working around issue of int_arg() returning wrong
850 value when a 32-bit userspace binary having debug info is being probed with
851 active prologue searching (PR18649).
852
853 - The powerpc variant of nd_syscall.compat_sysctl got deprecated on favor of
854 nd_syscall.sysctl32. This aligns the nd_syscall to its respective syscall and
855 to ia64/s390/x86_64 variants too.
856
857 - New tapset function assert(expression, msg) has been added.
858
859 - Embedded-C functions may now use the new STAP_PRINTF(fmt, ...)
860 macro for output.
861
862 - New tapset functions fullname_struct_path and fullname_struct_nameidata
863 resolve full path names from internal kernel struct pointers.
864
865 - New tapset functions arch_bytes() and uarch_bytes() to obtain address size
866 for kernel and user space respectively.
867
868 - New tapset function switch_file() allows control over rotation
869 of output files.
870
871 - The [nd_]syscall tapset got autodocumented. Related paragraph got added to PDF
872 and HTML tapset reference. Also a new tapset::syscall 3stap man page got added.
873
874 - Embedded-C functions with parameter arity-0 can now be marked with
875 the /* stable */ /* pure */ pragmas, if (roughly speaking) the
876 function is side-effect-free and idempotent. The translator may
877 execute these speculatively and have their results memoized. This
878 lets probes with multiple calls to such functions run faster.
879
880 Context variable ($foo) getter functions (in non-guru mode), and
881 numerous tapset functions are now marked as /* stable */ /* pure */.
882 Several example scripts have been modified to eschew explicit
883 memoization.
884
885 - Callee probe points now support '.return' and '.call' suffix.
886 For example,
887
888 process("proc").function("foo").callee("bar").return
889
890 will fire upon returning from bar when called by foo.
891
892 process("proc").function("foo").callee("bar").call
893
894 will only fire for non-inlined callees.
895
896 - The following tapset variables and functions are deprecated in
897 version 2.9:
898 - The '__int32_compat' library macro got deprecated in favor of
899 new '__compat_long' library macro.
900 - The 'uargs' convenience variable of the 'seccomp' syscall probe
901 got deprecated in favor of new 'uargs_uaddr' variable.
902
903 - SystemTap has reduced its memory consumption by using interned_strings (a
904 wrapper for boost::string_ref) in place of std::string instances. The change
905 is to reduce the number of duplicate strings created by replacing them with
906 interned_strings which act like pointers to existing strings.
907
908 For the implementation of interned_string, see stringtable.h
909
910 * What's new in version 2.8, 2015-06-17
911
912 - SystemTap has improved support for probing golang programs. Work has been
913 done to be able to handle DWARF information, reporting file names, line
914 numbers, and column numbers, and tolerance of odd characters in symbol names.
915
916 - The function::*, probe::* and new macro::* man pages cross-references the
917 enclosing tapset::* man page. For example:
918
919 function::pn(3stap) mentions tapset::pn(3stap) in the SEE ALSO section
920
921 - New stapref(1) man page provides a reference for the scripting language. The
922 stapref page contains an overview of the features available in the language,
923 such as keywords, data types, operators and more.
924
925 - The @task macro performs the very common @cast to a task_struct.
926
927 The embedded-C bodies of task_current() and pid2task() are now wrapped
928 by @task, which gives them a debuginfo type on the return value. With
929 autocast type propagation, this removes the need for any explicit @cast
930 in many places.
931
932 Other places which take untyped task pointers as parameters, for
933 instance, now use @task as well to simplify their code.
934
935 - New namespace-aware tapset functions [task_]ns_*() and ia new option
936 --target-namespaces=PID to denote a target set of namespaces corresponding to
937 the PID's namespaces. The namespace-aware tapsets will return values
938 relative to the target namespaces if specified, or the stap process' namespaces.
939
940 - Netfilter probes now attempt to decode Spanning Tree Protocol packets
941 into local variables: probe netfilter.bridge.*, br_* variables,
942 stp_dump.stp sample script.
943
944 - Colorization of error string tokens is made more robust, especially
945 in presence of $N/@N substitution.
946
947 - The following tapset variables and functions are deprecated in
948 version 2.8:
949 - The 'hostname_uaddr' variable in the syscall.setdomainname and
950 nd_syscall.setdomainname probe aliases have been deprecated in
951 favor of the new 'domainname_uaddr' variable.
952 - The 'fd' and 'fd_str' variables in the syscall.execveat and
953 nd_syscall.execveat probe aliases have been deprecated in favor of
954 the new 'dirfd' and 'dirfd_str' variables.
955
956 * What's new in version 2.7, 2015-02-18
957
958 - Some systemtap sample scripts are now identified with the "_best" keyword,
959 because they are generally useful or educational. They are now promoted
960 within the generated index files.
961
962 - Passing strings to and from functions has become faster due to optimization
963 (passing some strings by reference instead of by value/copy). It may
964 be disabled by using the unoptimize flag (-u).
965
966 To make embedded-C functions eligible for the same optimization, use the pragma
967 /* unmodified-fnargs */ to indicate that the function body will not modify
968 the function arguments. Remember to use MAXSTRINGLEN for string length,
969 rather than sizeof(string_arg) (which might now be a pointer).
970
971 - SystemTap now allows .function probes to be specified by their full function
972 name, file, and declaration line number. Use the .statement probe to probe a
973 specific line number.
974
975 - Tracepoint probes can now also be specified by the target subsystem. For
976 example, the following are all supported:
977
978 probe kernel.trace("sched:sched_switch") --> probe sched_switch found in the
979 sched subsystem
980 probe kernel.trace("sched:*") --> probe all tracepoints in sched subsystem
981
982 As a result, tapset functions such as pn() will now return a different string
983 than before. To retain the previous behaviour, use '--compatible=2.6'.
984
985 - The following functions are deprecated in release 2.7:
986 - _adjtx_mode_str(), _statfs_f_type_str(), _waitid_opt_str(),
987 _internal_wait_opt_str(), and _epoll_events_str().
988
989 - New tapset functions [u]symfileline(), [u]symfile() and [u]symline() will
990 return a string containing the specified portion of the filename:linenumber
991 match from a given address.
992
993 Using these functions may result in large generated modules from stored
994 address->file:line information.
995
996 * What's new in version 2.6, 2014-09-05
997
998 - SystemTap now supports on-the-fly arming/disarming of certain probe types:
999 kprobes, uprobes, and timer.*s(NUM) probes. For example, this probe
1000
1001 probe kernel.function("vfs_read") if (i > 4) { ... }
1002
1003 will automatically register/unregister the associated kprobe on vfs_read
1004 whenever the value of the condition changes (as some probe handler
1005 modifies 'i'). This allows us to avoid probe overhead when we're not
1006 interested. If the arming capability is not relevant/useful, nest the
1007 condition in the normal probe handler:
1008
1009 probe kernel.function("vfs_read") { if (i > 4) { ... } }
1010
1011 - statement("*@file:NNN").nearest probes now available to let systemtap
1012 translate probe to nearest probe-able line to one given if necessary
1013
1014 - process("PATH").library("PATH").plt("NAME").return probes are now supported.
1015
1016 - SystemTap now supports SDT probes with operands that refer to symbols.
1017
1018 - While in listing mode (-l/-L), probes printed are now more consistent
1019 and precise.
1020
1021 - Statement probes now support enumerated linenos to probe discontiguous
1022 linenos using the form:
1023
1024 process.statement("[email protected]:3,5-7,9")
1025
1026 - Statement counting is now suppressed in the generated c code for probes that
1027 are non-recursive and loop-free. Statement counting can be turned back on in
1028 unoptimize mode (-u).
1029
1030 - SystemTap now asserts that the PID provided for a process probe corresponds
1031 to a running process.
1032
1033 - DWARF process probes can be bound to a specific process using the form:
1034
1035 process(PID).function("*")
1036
1037 - SystemTap now accepts additional scripts through the new -E SCRIPT option.
1038 There still needs to be a main script specified through -e or file in order
1039 to provide an additional script. This makes it feasible to have scripts in
1040 the $HOME/.systemtap/rc file. For example:
1041
1042 -E 'probe begin, end, error { log("systemtap script " . pn()) }'
1043 -E 'probe timer.s(30) { error ("timeout") }
1044
1045 The -E SCRIPT option can also be used in listing mode (-l/-L), such that
1046 probe points for the additional scripts will not listed, but other parts of
1047 the script are still available, such as macros or aliases.
1048
1049 - SystemTap now supports array slicing within foreach loop conditions, delete
1050 statements and membership tests. Wildcards are represented by "*". Examples
1051 of the expressions are:
1052
1053 foreach ([a,b,c] in val[*,2,*])
1054 delete val[*, 2, *]
1055 [*, 2, *] in val
1056
1057 - Integer expressions which are derived from DWARF values, like context $vars,
1058 @cast, and @var, will now carry that type information into subsequent reads.
1059 Such expressions can now use "->" and "[]" operators, as can local variables
1060 which were assigned such values.
1061
1062 foo = $param->foo; printf("x:%d y:%d\n", foo->x, foo->y)
1063 printf("my value is %d\n", ($type == 42 ? $foo : $bar)->value)
1064 printf("my parent pid is %d\n", task_parent(task_current())->tgid)
1065
1066 * What's new in version 2.5, 2014-04-30
1067
1068 - Systemtap now supports backtracing through its own, invoking module.
1069
1070 - Java probes now support backtracing using the print_java_backtrace()
1071 and sprint_java_backtrace() functions.
1072
1073 - Statement probes (e.g. process.statement) are now faster to resolve,
1074 more precise, and work better with inlined functions.
1075
1076 - New switches have been added to help inspect the contents of installed
1077 library files:
1078
1079 stap --dump-functions --> list all library functions and their args
1080 stap --dump-probe-aliases --> list all library probe aliases
1081
1082 - The heuristic algorithms used to search for function-prologue
1083 endings were improved, to cover more optimization (or
1084 lack-of-optimization, or incorrect-debuginfo) cases. These
1085 heuristics are necessary to find $context parameters for some
1086 function-call/entry probes. We recommend programs be built with
1087 CFLAGS+=-grecord-gcc-switches to feed information to the heuristics.
1088
1089 - The stap --use-server option now more correctly supports address:port
1090 type parametrization, for manual use in the absence of avahi.
1091
1092 - A new probe alias "oneshot" allows a single quick script fragment to run,
1093 then exit.
1094
1095 - The argv tapset now merges translate-time and run-time positional
1096 arguments, so all of these work:
1097
1098 stap -e 'probe oneshot {println(argv[1]," ",argv[2])}' hello world
1099
1100 stap -e 'probe oneshot {println(argv[1]," ",argv[2])}' \
1101 -G argv_1=hello -G argv_2=world
1102
1103 staprun hello.ko argv_1=hello argv_2=world
1104
1105 - SystemTap now falls back on the symbol table for probing
1106 functions in processes if the debuginfo is not available.
1107
1108 - SystemTap now supports a %( guru_mode == 0 /* or 1 */ %)
1109 conditional for making dual-use scripts.
1110
1111 - SystemTap now supports UEFI/SecureBoot systems, via
1112 machine-owner-keys maintained by a trusted stap-server on the
1113 network. (Key enrollment requires a one-time reboot and BIOS
1114 conversation.)
1115 https://sourceware.org/systemtap/wiki/SecureBoot
1116
1117 - SystemTap now reports more accurate and succinct errors on type
1118 mismatches.
1119
1120 - Embedded-C functions may use STAP_RETURN(value) instead of the
1121 more wordy STAP_RETVALUE assignment followed by a "goto out".
1122 The macro supports numeric or string values as appropriate.
1123 STAP_ERROR(...) is available to return with a (catchable) error.
1124
1125 - Some struct-sockaddr fields are now individually decoded for
1126 socket-related syscalls:
1127 probe syscall.connect { println (uaddr_af, ":", uaddr_ip) }
1128
1129 - The documentation for the SystemTap initscript service and the
1130 SystemTap compile-server service have been completely converted from
1131 README files to man pages (see systemtap(8) and stap-server(8)).
1132
1133 - SystemTap is now capable of inserting modules early during the boot
1134 process on dracut-based systems. See the 'onboot' command in
1135 systemtap(8) for more information.
1136
1137 - DWARF probes can now use the '.callee[s]' variants, which allow more
1138 precise function probing. For example, the probe point
1139
1140 process("myproc").function("foo").callee("bar")
1141
1142 will fire upon entering bar() from foo(). A '.callees' probe will
1143 instead place probes on all callees of foo().
1144 Note that this also means that probe point wildcards should be used
1145 with more care. For example, use signal.*.return rather than
1146 signal.*.*, which would also match '.callees'. See stapprobes(3stap)
1147 for more info. This feature requires at least GCC 4.7.
1148
1149 - A few new functions in the task_time tapsets, as well as a new tapset
1150 function task_ancestry(), which prints out the parentage of a process.
1151
1152 - The kprocess.exec probe has been updated to use syscall.execve, which
1153 allows access to the new process' arguments (through the new 'argstr'
1154 or 'args' variables) as well as giving better support across kernel
1155 versions. Note also that the 'filename' variable now holds the
1156 filename (quoted), or the address (unquoted) if it couldn't be
1157 retrieved.
1158
1159 - The [s]println() function can now be called without any arguments to
1160 simply print a newline.
1161
1162 - Suggestions are now provided when markers could not be resolved. For
1163 example, process("stap").mark("benchmart") will suggest 'benchmark'.
1164
1165 - SystemTap colors can now be turned off by simply setting
1166 SYSTEMTAP_COLORS to be empty, rather than having to make it invalid.
1167
1168 - There is a new context tapset function, pnlabel(), which returns the
1169 name of the label which fired.
1170
1171 - The following tapset variables and functions are deprecated in
1172 release 2.5:
1173 - The 'clone_flags', 'stack_start', 'stack_size',
1174 'parent_tid_uaddr', and 'child_tid_uaddr' variables in the
1175 'syscall.fork' and 'nd_syscall.fork' probe aliases.
1176 - The '_sendflags_str()' and '_recvflags_str()' functions have been
1177 deprecated in favor of the new '_msg_flags_str()' function.
1178 - The 'flags' and 'flags_str' variables in the 'syscall.accept' and
1179 'nd_syscall.accept' probe alias.
1180 - The 'first', 'second', and 'uptr_uaddr' variables in the
1181 'syscall.compat_sys_shmctl', and 'nd_syscall.compat_sys_shmctl'
1182 probe aliases have been deprecated in favor of the new 'shmid',
1183 'cmd', and 'buf_uaddr' variables.
1184
1185 * What's new in version 2.4, 2013-11-06
1186
1187 - Better suggestions are given in many of the semantic errors in which
1188 alternatives are provided. Additionally, suggestions are now provided
1189 when plt and trace probes could not be resolved. For example,
1190 kernel.trace("sched_siwtch") will suggest 'sched_switch'.
1191
1192 - SystemTap is now smarter about error reporting. Errors from the same
1193 source are considered duplicates and suppressed. A message is
1194 displayed on exit if any errors/warnings were suppressed.
1195
1196 - Statistics aggregate typed objects are now implemented locklessly,
1197 if the translator finds that they are only ever read (using the
1198 foreach / @count / etc. constructs) in a probe-begin/end/error.
1199
1200 - SystemTap now supports probing inside virtual machines using the
1201 libvirt and unix schemes, e.g.
1202
1203 stap -ve 'probe timer.s(1) { printf("hello!\n") }' \
1204 --remote=libvirt://MyVirtualMachine
1205
1206 Virtual machines managed by libvirt can be prepared using stapvirt.
1207 See stapvirt(1) and the --remote option in stap(1) for more details.
1208
1209 - Systemtap now checks for and uses (when available) the .gnu_debugdata
1210 section which contains a subset of debuginfo, useful for backtraces
1211 and function probing
1212
1213 - SystemTap map variables are now allocated with vmalloc() instead of
1214 with kmalloc(), which should cause memory to be less fragmented.
1215
1216 - Although SystemTap itself requires elfutils 0.148+, staprun only
1217 requires elfutils 0.142+, which could be useful with the
1218 '--disable-translator' configure switch.
1219
1220 - Under FIPS mode (/proc/sys/crypto/fips_enabled=1), staprun will
1221 refuse to load systemtap modules (since these are not normally
1222 signed with the kernel's build-time keys). This protection may
1223 be suppressed with the $STAP_FIPS_OVERRIDE environment variable.
1224
1225 - The stap-server client & server code now enable all SSL/TLS
1226 ciphers rather than just the "export" subset.
1227
1228 - For systems with in-kernel utrace, 'process.end' and 'thread.end'
1229 probes will hit before the target's parent process is notified of
1230 the target's death. This matches the behavior of newer kernels
1231 without in-kernel utrace.
1232
1233 * What's new in version 2.3, 2013-07-25
1234
1235 - More context-accessing functions throw systemtap exceptions upon a
1236 failure, whereas in previous versions they might return non-error
1237 sentinel values like "" or "<unknown>". Use try { } / catch { }
1238 around these, or new wrapper functions such as user_string_{n_}quoted()
1239 that internally absorb exceptions.
1240
1241 - java("org.my.MyApp") probes are now restricted to pre-existing jvm pid's with
1242 a listing in jps -l output to avoid recursive calls
1243
1244 - The tapset [nd_]syscall.semop parameter tsops_uaddr is renamed sops_uaddr for
1245 consistency with [nd_]syscall.semtimedop.
1246
1247 - The udp.stp tapset adds some ip-address/port variables.
1248
1249 - A new guru-mode-only tapset function raise() is available to send signals
1250 to the current task.
1251
1252 - Support for the standard Posix ERE named character classes has been
1253 added to the regexp engine, e.g. [:digit:], [:alpha:], ...
1254
1255 - A substantial internal overhaul of the regexp engine has resulted in
1256 correct behaviour on further obscure edge cases. The regexp engine
1257 now implements the ERE standard and correctly passes the testsuite
1258 for the glibc regexp engine (minus portions corresponding to
1259 unimplemented features -- i.e. subexpression capture and reuse).
1260
1261 - Alternative functions are now suggested when function probes could not be
1262 resolved. For example, kernel.function("vfs_reads") will suggest vfs_read.
1263 Other probes for which suggestions are made are module.function,
1264 process.function, and process.library.function.
1265
1266 - Has life been a bit bland lately? Want to spice things up? Why not write a
1267 few faulty probes and feast your eyes upon the myriad of colours adorning
1268 your terminal as SystemTap softly whispers in your ear... 'parse error'.
1269 Search for '--color' in 'man stap' for more info.
1270
1271 - The following tapset functions are deprecated in release 2.3:
1272 'stap_NFS_CLIENT', '__getfh_inode', '_success_check',
1273 '_sock_prot_num', '_sock_fam_num', '_sock_state_num',
1274 '_sock_type_num', and '_sock_flags_num'.
1275
1276 * What's new in version 2.2.1, 2013-05-16
1277 * What's new in version 2.2, 2013-05-14
1278
1279 - Experimental support has been added for probing Java methods using
1280 Byteman 2.0 as a backend. Java method probes can target method entries,
1281 returns, or specific statements in the method as specified by line number.
1282
1283 probe java("org.my.MyApp").class("^java.lang.Object").method("foo(int)")
1284 { println($$parms) }
1285
1286 See java/README for information on how to set up Java/Byteman
1287 functionality. Set env STAPBM_VERBOSE=yes for more tracing.
1288
1289 - The stap -l output and pn() tapset function's return value may be slightly
1290 different for complicated web of wildcarded/aliased probes.
1291
1292 - The dyninst backend has improved in several aspects:
1293
1294 - Setting custom values for global variables is now supported, both
1295 with -G when compiling a script, and from the stapdyn command line
1296 when loading a precompiled module.
1297
1298 - A high-performance shared-memory-based transport is used for
1299 trace data.
1300
1301 - A systemd service file and tmpfile have been added to allow
1302 systemtap-server to be managed natively by systemd.
1303
1304 - Due to the removal of register_timer_hook in recent kernels, the
1305 behaviour of timer.profile has been changed slightly. This probe is
1306 now an alias which uses the old mechanism where possible, but falls
1307 back to perf.sw.cpu_clock or another mechanism when the kernel timer
1308 hook is not available.
1309
1310 To require the kernel timer hook mechanism in your script, use
1311 timer.profile.tick instead of timer.profile.
1312
1313 - The following tapset variables are deprecated in release 2.2:
1314 - The 'origin' variables in the 'generic.fop.llseek',
1315 'generic.fop.llseek.return', and 'nfs.fop.llseek' probes. The
1316 'origin' variable has been replaced by the 'whence' variable.
1317 - The 'page_index' variable in the 'vfs.block_sync_page' and
1318 'vfs.buffer_migrate_page' probe aliases.
1319 - The 'write_from' and 'write_upto' variables in the
1320 '_vfs.block_prepare_write' and '_vfs.block_prepare_write.return'
1321 probe aliases.
1322 - The 'regs' variable in the 'syscall.sigaltstack',
1323 'nd_syscall.sigaltstack', 'syscall.fork', and 'nd_syscall.fork'
1324 probe aliases.
1325 - The 'first', 'second', 'third', and 'uptr_uaddr' variables in the
1326 'syscall.compat_sys_shmat' and 'nd_syscall.compat_sys_shmat' probe
1327 aliases.
1328
1329 - The following tapset functions are deprecated in release 2.2:
1330 'ppos_pos', '_dev_minor', and '_dev_major'
1331
1332 - The folowing tapset functions used to return error strings instead
1333 of raising an error. The original behavior is deprecated in release
1334 2.2.
1335
1336 'ctime', 'probemod', 'modname'
1337
1338 * What's new in version 2.1, 2013-02-13
1339
1340 - EMACS and VIM editor modes for systemtap source files are included / updated.
1341
1342 - The translator now eliminates duplicate tapset files between its
1343 preferred directory (as configured during the build with --prefix=/
1344 or specified with the -I /path option), and files it may find under
1345 $XDG_DATA_DIRS. This should eliminate a class of conflicts between
1346 parallel system- and hand-built systemtap installations.
1347
1348 - The translator accepts a --suppress-time-limits option, which defeats
1349 time-related constraints, to allows probe handlers to run for indefinite
1350 periods. It requires the guru mode (-g) flag to work. Add the earlier
1351 --suppress-handler-errors flag for a gung-ho "just-keep-going" attitude.
1352
1353 - Perf event probes may now be read on demand. The counter probe is
1354 defined using the counter-name part:
1355 probe perf.type(0).config(0).counter("NAME"). The counter is
1356 read in a user space probe using @perf("NAME"), e.g.
1357 process("PROCESS").statement("func@file") {stat <<< @perf("NAME")}
1358
1359 - Perf event probes may now be bound to a specific task using the
1360 process-name part: probe perf.type(0).config(0).process("NAME") { }
1361 If the probed process name is not specified, then it is inferred
1362 from the -c CMD argument.
1363
1364 - Some error messages and warnings now refer to additional information
1365 that is found in man pages. These are generally named
1366 error::FOO or warning::BAR (in the 7stap man page section)
1367 and may be read via
1368 % man error::FOO
1369 % man warning::BAR
1370
1371 - The dyninst backend has improved in several aspects:
1372 - The runtime now allows much more concurrency when probing multithreaded
1373 processes, and will also follow probes across forks.
1374 - Several new probe types are now supported, including timers, function
1375 return, and process.begin/end and process.thread.begin/end.
1376 - Semaphores for SDT probes are now set properly.
1377 - Attaching to existing processes with -x PID now works.
1378
1379 - The foreach looping construct can now sort aggregate arrays by the user's
1380 choice of aggregating function. Previously, @count was implied. e.g.:
1381 foreach ([x,y] in array @sum +) { println(@sum(array[x,y])) }
1382
1383 - Proof of concept support for regular expression matching has been added:
1384 if ("aqqqqqb" =~ "q*b") { ... }
1385 if ("abc" !~ "q*b") { ... }
1386
1387 The eventual aim is to support roughly the same functionality as
1388 the POSIX Extended Regular Expressions implemented by glibc.
1389 Currently missing features include extraction of the matched string
1390 and subexpressions, and named character classes ([:alpha:], [:digit:], &c).
1391
1392 Special thanks go to the re2c project, whose public domain code this
1393 functionality has been based on. For more info on re2c, see:
1394 http://sourceforge.net/projects/re2c/
1395
1396 - The folowing tapset variables are deprecated in release 2.1 and will
1397 be removed in release 2.2:
1398 - The 'send2queue' variable in the 'signal.send' probe.
1399 - The 'oldset_addr' and 'regs' variables in the 'signal.handle' probe.
1400
1401 - The following tapset probes are deprecated in release 2.1 and will
1402 be removed in release 2.2:
1403 - signal.send.return
1404 - signal.handle.return
1405
1406 * What's new in version 2.0, 2012-10-09
1407
1408 - Systemtap includes a new prototype backend, which uses Dyninst to instrument
1409 a user's own processes at runtime. This backend does not use kernel modules,
1410 and does not require root privileges, but is restricted with respect to the
1411 kinds of probes and other constructs that a script may use.
1412
1413 Users from source should configure --with-dyninst and install a
1414 fresh dyninst snapshot such as that in Fedora rawhide. It may be
1415 necessary to disable conflicting selinux checks; systemtap will advise.
1416
1417 Select this new backend with the new stap option --runtime=dyninst
1418 and a -c target process, along with normal options. (-x target
1419 processes are not supported in this prototype version.) For example:
1420
1421 stap --runtime=dyninst -c 'stap -l begin' \
1422 -e 'probe process.function("main") { println("hi from dyninst!") }'
1423
1424 - To aid diagnosis, when a kernel panic occurs systemtap now uses
1425 the panic_notifier_list facility to dump a summary of its trace
1426 buffers to the serial console.
1427
1428 - The systemtap preprocessor now has a simple macro facility as follows:
1429
1430 @define add(a,b) %( ((@a)+(@b)) %)
1431 @define probegin(x) %(
1432 probe begin {
1433 @x
1434 }
1435 %)
1436
1437 @probegin( foo = @add(40, 2); print(foo) )
1438
1439 Macros defined in the user script and regular tapset .stp files are
1440 local to the file. To get around this, the tapset library can define
1441 globally visible 'library macros' inside .stpm files. (A .stpm file
1442 must contain a series of @define directives and nothing else.)
1443
1444 The status of the feature is experimental; semantics of macroexpansion
1445 may change (unlikely) or expand in the future.
1446
1447 - Systemtap probe aliases may be used with additional suffixes
1448 attached. The suffixes are passed on to the underlying probe
1449 point(s) as shown below:
1450
1451 probe foo = bar, baz { }
1452 probe foo.subfoo.option("gronk") { }
1453 // expands to: bar.subfoo.option("gronk"), baz.subfoo.option("gronk")
1454
1455 In practical terms, this allows us to specify additional options to
1456 certain tapset probe aliases, by writing e.g.
1457 probe syscall.open.return.maxactive(5) { ... }
1458
1459 - To support the possibility of separate kernel and dyninst backends,
1460 the tapsets have been reorganized into separate folders according to
1461 backend. Thus kernel-specific tapsets are located under linux/, the
1462 dyninst-specific ones under dyninst/
1463
1464 - The backtrace/unwind tapsets have been expanded to allow random
1465 access to individual elements of the backtrace. (A caching mechanism
1466 ensures that the backtrace computation run at most once for each
1467 time a probe fires, regardless of how many times or what order the
1468 query functions are called in.) New tapset functions are:
1469 stack/ustack - return n'th element of backtrace
1470 callers/ucallers - return first n elements of backtrace
1471 print_syms/print_usyms - print full information on a list of symbols
1472 sprint_syms/sprint_usyms - as above, but return info as a string
1473
1474 The following existing functions have been superseded by print_syms()
1475 et al.; new scripts are recommended to avoid using them:
1476 print_stack()
1477 print_ustack()
1478 sprint_stack()
1479 sprint_ustack()
1480
1481 - The probefunc() tapset function is now myproc-unprivileged, and can
1482 now be used in unprivileged scripts for such things as profiling in
1483 userspace programs. For instance, try running
1484 systemtap.examples/general/para-callgraph.stp in unprivileged mode
1485 with a stapusr-permitted probe. The previous implementation of
1486 probefunc() is available with "stap --compatible=1.8".
1487
1488 - Preprocessor conditional to vary code based on script privilege level:
1489 unprivileged -- %( systemtap_privilege == "stapusr" %? ... %)
1490 privileged -- %( systemtap_privilege != "stapusr" %? ... %)
1491 or, alternately %( systemtap_privilege == "stapsys"
1492 || systemtap_privilege == "stapdev" %? ... %)
1493
1494 - To ease migration to the embedded-C locals syntax introduced in 1.8
1495 (namely, STAP_ARG_* and STAP_RETVALUE), the old syntax can now be
1496 re-enabled on a per-function basis using the /* unmangled */ pragma:
1497
1498 function add_foo:long(a:long, b:long) %{ /* unmangled */
1499 THIS->__retvalue = THIS->a + STAP_ARG_b;
1500 %}
1501
1502 Note that both the old and the new syntax may be used in an
1503 /* unmangled */ function. Functions not marked /* unmangled */
1504 can only use the new syntax.
1505
1506 - Adjacent string literals are now glued together irrespective of
1507 intervening whitespace or comments:
1508 "foo " "bar" --> "foo bar"
1509 "foo " /* comment */ "bar" --> "foo bar"
1510 Previously, the first pair of literals would be glued correctly,
1511 while the second would cause a syntax error.
1512
1513 * What's new in version 1.8, 2012-06-17
1514
1515 - staprun accepts a -T timeout option to allow less frequent wake-ups
1516 to poll for low-throughput output from scripts.
1517
1518 - When invoked by systemtap, the kbuild $PATH environment is sanitized
1519 (prefixed with /usr/bin:/bin:) in an attempt to exclude compilers
1520 other than the one the kernel was presumed built with.
1521
1522 - Printf formats can now use "%#c" to escape non-printing characters.
1523
1524 - Pretty-printed bitfields use integers and chars use escaped formatting
1525 for printing.
1526
1527 - The systemtap compile-server and client now support IPv6 networks.
1528 - IPv6 addresses may now be specified on the --use-server option and will
1529 be displayed by --list-servers, if the avahi-daemon service is running and
1530 has IPv6 enabled.
1531 - Automatic server selection will automatically choose IPv4 or IPv6 servers
1532 according to the normal server selection criteria when avahi-daemon is
1533 running. One is not preferred over the other.
1534 - The compile-server will automatically listen on IPv6 addresses, if
1535 available.
1536 - To enable IPv6 in avahi-daemon, ensure that /etc/avahi/avahi-daemon.conf
1537 contains an active "use-ipv6=yes" line. After adding this line run
1538 "service avahi-daemon restart" to activate IPv6 support.
1539 - See man stap(1) for details on how to use IPv6 addresses with the
1540 --use-server option.
1541
1542 - Support for DWARF4 .debug_types sections (for executables and shared
1543 libraries compiled with recent GCC's -gdwarf-4 / -fdebug-types-section).
1544 PR12997. SystemTap now requires elfutils 0.148+, full .debug_types support
1545 depends on elfutils 0.154+.
1546
1547 - Systemtap modules are somewhat smaller & faster to compile. Their
1548 debuginfo is now suppressed by default; use -B CONFIG_DEBUG_INFO=y to
1549 re-enable.
1550
1551 - @var now an alternative language syntax for accessing DWARF variables
1552 in uprobe and kprobe handlers (process, kernel, module). @var("somevar")
1553 can be used where $somevar can be used. The @var syntax also makes it
1554 possible to access non-local, global compile unit (CU) variables by
1555 specifying the CU source file as follows @var("somevar@some/src/file.c").
1556 This will provide the target variable value of global "somevar" as defined
1557 in the source file "some/src/file.c". The @var syntax combines with all
1558 normal features of DWARF target variables like @defined(), @entry(),
1559 [N] array indexing, field access through ->, taking the address with
1560 the & prefix and shallow or deep pretty printing with a $ or $$ suffix.
1561
1562 - Stap now has resource limit options:
1563 --rlimit-as=NUM
1564 --rlimit-cpu=NUM
1565 --rlimit-nproc=NUM
1566 --rlimit-stack=NUM
1567 --rlimit-fsize=NUM
1568 All resource limiting has been moved from the compile server to stap
1569 itself. When running the server as "stap-server", default resource
1570 limit values are specified in ~stap-server/.systemtap/rc.
1571
1572 - Bug CVE-2012-0875 (kernel panic when processing malformed DWARF unwind data)
1573 is fixed.
1574
1575 - The systemtap compile-server now supports multiple concurrent connections.
1576 Specify the desired maximum number of concurrent connections with
1577 the new stap-server/stap-serverd --max-threads option. Specify a
1578 value of '0' to tell the server not to spawn any new threads (handle
1579 all connections serially in the main thread). The default value is
1580 the number of processor cores on the host.
1581
1582 - The following tapset functions are deprecated in release 1.8 and will be
1583 removed in release 1.9:
1584 daddr_to_string()
1585
1586 - SystemTap now mangles local variables to avoid collisions with C
1587 headers included by tapsets. This required a change in how
1588 embedded-C functions access local parameters and the return value slot.
1589
1590 Instead of THIS->foo in an embedded-C function, please use the newly
1591 defined macro STAP_ARG_foo (substitute the actual name of the
1592 argument for 'foo'); instead of THIS->__retvalue, use the newly
1593 defined STAP_RETVALUE. All of the tapsets and test cases have been
1594 adapted to use this new notation.
1595
1596 If you need to run code which uses the old THIS-> notation, run stap
1597 with the --compatible=1.7 option.
1598
1599 - There is updated support for user-space probing against kernels >=
1600 3.5, which have no utrace but do have the newer inode-uprobes work
1601 by Srikar Dronamraju and colleagues. For kernels < 3.5, the
1602 following 3 sets of kernel patches would need to be backported to
1603 your kernel to use this preliminary user-space probing support:
1604
1605 - inode-uprobes patches:
1606 - 2b144498350860b6ee9dc57ff27a93ad488de5dc
1607 - 7b2d81d48a2d8e37efb6ce7b4d5ef58822b30d89
1608 - a5f4374a9610fd7286c2164d4e680436727eff71
1609 - 04a3d984d32e47983770d314cdb4e4d8f38fccb7
1610 - 96379f60075c75b261328aa7830ef8aa158247ac
1611 - 3ff54efdfaace9e9b2b7c1959a865be6b91de96c
1612 - 35aa621b5ab9d08767f7bc8d209b696df281d715
1613 - 900771a483ef28915a48066d7895d8252315607a
1614 - e3343e6a2819ff5d0dfc4bb5c9fb7f9a4d04da73
1615 - exec tracepoint kernel patch:
1616 - 4ff16c25e2cc48cbe6956e356c38a25ac063a64d
1617 - task_work_add kernel patches:
1618 - e73f8959af0439d114847eab5a8a5ce48f1217c4
1619 - 4d1d61a6b203d957777d73fcebf19d90b038b5b2
1620 - 413cd3d9abeaef590e5ce00564f7a443165db238
1621 - dea649b8ac1861107c5d91e1a71121434fc64193
1622 - f23ca335462e3c84f13270b9e65f83936068ec2c
1623
1624 * What's new in version 1.7, 2012-02-01
1625
1626 - Map inserting and deleting is now significantly faster due to
1627 improved hashing and larger hash tables. The hashes are also
1628 now randomized to provide better protection against deliberate
1629 collision attacks.
1630
1631 - Formatted printing is faster by compiling the formatting directives
1632 to C code rather than interpreting at run time.
1633
1634 - Systemtap loads extra command line options from $SYSTEMTAP_DIR/rc
1635 ($HOME/.systemtap/rc by default) before the normal argc/argv. This
1636 may be useful to activate site options such as --use-server or
1637 --download-debuginfo or --modinfo.
1638
1639 - The stap-server has seen many improvements, and is no longer considered
1640 experimental.
1641
1642 - The stap-server service (initscript) now supports four new options:
1643 -D MACRO[=VALUE]
1644 --log LOGFILE
1645 --port PORT-NUMBER
1646 --SSL CERT-DATABASE
1647 These allow the specification of macro definitions to be passed to stap
1648 by the server, the location of the log file, network port number and
1649 NSS certificate database location respectively. These options are also
1650 supported within individual server configuration files. See stap-server
1651 and initscript/README.stap-server for details. The stap-server is no
1652 longer activated by default.
1653
1654 - process("PATH").[library("PATH")].function("NAME").exported probes are now
1655 supported to filter function() to only exported instances.
1656
1657 - The translator supports a new --suppress-handler-errors option, which
1658 causes most runtime errors to be turned into quiet skipped probes. This
1659 also disables the MAXERRORS and MAXSKIPPED limits.
1660
1661 - Translator warnings have been standardized and controlled by the -w / -W
1662 flags.
1663
1664 - The translator supports a new --modinfo NAME=VALUE option to emit additional
1665 MODULE_INFO(n,v) macros into the generated code.
1666
1667 - There is no more fixed maximum number of VMA pages that will be tracked
1668 at runtime. This reduces memory use for those scripts that don't need any,
1669 or only limited target process VMA tracking and allows easier system
1670 wide probes inspecting shared library variables and/or user backtraces.
1671 stap will now silently ignore -DTASK_FINDER_VMA_ENTRY_ITEMS.
1672
1673 - The tapset functions remote_id() and remote_uri() identify the member of a
1674 swarm of "stap --remote FOO --remote BAR baz.stp" concurrent executions.
1675
1676 - Systemtap now supports a new privilege level and group, "stapsys", which
1677 is equivalent to the privilege afforded by membership in the group "stapdev",
1678 except that guru mode (-g) functionality may not be used. To support this, a
1679 new option, --privilege=[stapusr|stapsys|stapdev] has been added.
1680 --privilege=stapusr is equivalent to specifying the existing --unprivileged
1681 option. --privilege=stapdev is the default. See man stap(1) for details.
1682
1683 - Scripts that use kernel.trace("...") probes compile much faster.
1684
1685 - The systemtap module cache is cleaned less frequently, governed by the
1686 number of seconds in the $SYSTEMTAP_DIR/cache/cache_clean_interval_s file.
1687
1688 - SDT can now define up to 12 arguments in a probe point.
1689
1690 - Parse errors no longer generate a cascade of false errors. Instead, a
1691 parse error skips the rest of the current probe or function, and resumes
1692 at the next one. This should generate fewer and better messages.
1693
1694 - Global array wrapping is now supported for both associative and statistics typed
1695 arrays using the '%' character to signify a wrapped array. For example,
1696 'global foo%[100]' would allow the array 'foo' to be wrapped if more than 100
1697 elements are inserted.
1698
1699 - process("PATH").library("PATH").plt("NAME") probes are now supported.
1700 Wildcards are supported in the plt-name part, to refer to any function in the
1701 program linkage table which matches the glob pattern and the rest of the
1702 probe point.
1703
1704 - A new option, --dump-probe-types, will dump a list of supported probe types.
1705 If --unprivileged is also specified, the list will be limited to probe types
1706 which are available to unprivileged users.
1707
1708 - Systemtap can now automatically download the required debuginfo
1709 using abrt. The --download-debuginfo[=OPTION] can be used to
1710 control this feature. Possible values are: 'yes', 'no', 'ask',
1711 and a positive number representing the timeout desired. The
1712 default behavior is to not automatically download the debuginfo.
1713
1714 - The translator has better support for probing C++ applications by
1715 better undertanding of compilation units, nested types, templates,
1716 as used in probe point and @cast constructs.
1717
1718 - On 2.6.29+ kernels, systemtap can now probe kernel modules that
1719 arrive and/or depart during the run-time of a session. This allows
1720 probing of device driver initialization functions, which had formerly been
1721 blocklisted.
1722
1723 - New tapset functions for cpu_clock and local_clock access were added.
1724
1725 - There is some limited preliminary support for user-space probing
1726 against kernels such as linux-next, which have no utrace but do have
1727 the newer inode-uprobes work by Srikar Dronamraju and colleagues.
1728
1729 - The following probe types are deprecated in release 1.7 and will be
1730 removed in release 1.8:
1731 kernel.function(number).inline
1732 module(string).function(number).inline
1733 process.function(number).inline
1734 process.library(string).function(number).inline
1735 process(string).function(number).inline
1736 process(string).library(string).function(number).inline
1737
1738 - The systemtap-grapher is deprecated in release 1.7 and will be removed in
1739 release 1.8.
1740
1741 - The task_backtrace() tapset function was deprecated in 1.6 and has been
1742 removed in 1.7.
1743
1744 - MAXBACKTRACE did work in earlier releases, but has now been documented
1745 in the stap 1 manual page.
1746
1747 - New tapset function probe_type(). Returns a short string describing
1748 the low level probe handler type for the current probe point.
1749
1750 - Both unwind and symbol data is now only collected and emitted for
1751 scripts actually using backtracing or function/data symbols.
1752 Tapset functions are marked with /* pragma:symbols */ or
1753 /* pragma:unwind */ to indicate they need the specific data.
1754
1755 - Kernel backtraces can now be generated for non-pt_regs probe context
1756 if the kernel support dump_trace(). This enables backtraces from
1757 certain timer probes and tracepoints.
1758
1759 - ubacktrace() should now also work for some kernel probes on x86 which can
1760 use the dwarf unwinder to recover the user registers to provide
1761 more accurate user backtraces.
1762
1763 - For s390x the systemtap runtime now properly splits kernel and user
1764 addresses (which are in separate address spaces on that architecture)
1765 which enable user space introspection.
1766
1767 - ppc and s390x now supports user backtraces through the DWARF unwinder.
1768
1769 - ppc now handles function descriptors as symbol names correctly.
1770
1771 - arm support kernel backtraces through the DWARF unwinder.
1772
1773 - arm now have a uprobes port which enables user probes. This still
1774 requires some kernel patches (user_regsets and tracehook support for
1775 arm).
1776
1777 - Starting in release 1.7, these old variables will be deprecated:
1778 - The 'pid' variable in the 'kprocess.release' probe has been
1779 deprecated in favor of the new 'released_pid' variable.
1780 - The 'args' variable in the
1781 '_sunrpc.clnt.create_client.rpc_new_client_inline' probe has been
1782 deprecated in favor of the new internal-only '__args' variable.
1783
1784 - Experimental support for recent kernels without utrace has been
1785 added for the following probe types:
1786
1787 process(PID).begin
1788 process("PATH").begin
1789 process.begin
1790 process(PID).thread.begin
1791 process("PATH").thread.begin
1792 process.thread.begin
1793 process(PID).end
1794 process("PATH").end
1795 process.end
1796 process(PID).thread.end
1797 process("PATH").thread.end
1798 process.thread.end
1799 process(PID).syscall
1800 process("PATH").syscall
1801 process.syscall
1802 process(PID).syscall.return
1803 process("PATH").syscall.return
1804 process.syscall.return
1805
1806 - staprun disables kprobe-optimizations in recent kernels, as problems
1807 were found. (PR13193)
1808
1809 * What's new in version 1.6, 2011-07-25
1810
1811 - Security fixes for CVE-2011-2503: read instead of mmap to load modules,
1812 CVE-2011-2502: Don't allow path-based auth for uprobes
1813
1814 - The systemtap compile-server no longer uses the -k option when calling the
1815 translator (stap). As a result, the server will now take advantage of the
1816 module cache when compiling the same script more than once. You may observe
1817 an improvement in the performance of the server in this situation.
1818
1819 - The systemtap compile-server and client now each check the version of the
1820 other, allowing both to adapt when communicating with a down-level
1821 counterpart. As a result, all version of the client can communicate
1822 with all versions of the server and vice-versa. Client will prefer newer
1823 servers when selecting a server automatically.
1824
1825 - SystemTap has improved support for the ARM architecture. The
1826 kread() and kwrite() operations for ARM were corrected allowing many
1827 of the tapsets probes and function to work properly on the ARM
1828 architecture.
1829
1830 - Staprun can now rename the module to a unique name with the '-R' option before
1831 inserting it. Systemtap itself will also call staprun with '-R' by default.
1832 This allows the same module to be inserted more than once, without conflicting
1833 duplicate names.
1834
1835 - Systemtap error messages now provide feedback when staprun or any other
1836 process fails to launch. This also specifically covers when the user
1837 doesn't have the proper permissions to launch staprun.
1838
1839 - Systemtap will now map - to _ in module names. Previously,
1840 stap -L 'module("i2c-core").function("*")' would be empty. It now returns
1841 a list had stap -L 'module("i2c_core").function("*") been specified.
1842
1843 - Systemtap now fills in missing process names to probe points, to
1844 avoid having to name them twice twice:
1845 % stap -e 'probe process("a.out").function("*") {}' -c 'a.out ...'
1846 Now the probed process name is inferred from the -c CMD argument.
1847 % stap -e 'probe process.function("*") {}' -c 'a.out ...'
1848
1849 - stap -L 'process("PATH").syscall' will now list context variables
1850
1851 - Depends on elfutils 0.142+.
1852
1853 - Deprecated task_backtrace:string (task:long). This function will go
1854 away after 1.6. Please run your scripts with stap --check-version.
1855
1856 * What's new in version 1.5, 2011-05-23
1857
1858 - Security fixes for CVE-2011-1781, CVE-2011-1769: correct DW_OP_{mod,div}
1859 division-by-zero bug
1860
1861 - The compile server and its related tools (stap-gen-ert, stap-authorize-cert,
1862 stap-sign-module) have been re-implemented in C++. Previously, these
1863 components were a mix of bash scripts and C code. These changes should be
1864 transparent to the end user with the exception of NSS certificate database
1865 password prompting (see below). The old implementation would prompt more
1866 than once for the same password in some situations.
1867
1868 - eventcount.stp now allows for event counting in the format of
1869 'stap eventcount.stp process.end syscall.* ...', and also reports
1870 corresponding event tid's.
1871
1872 - Systemtap checks that the build-id of the module being probed matches the
1873 build-id saved in the systemtap module. Invoking systemtap with
1874 -DSTP_NO_BUILDID_CHECK will bypass this build-id runtime verification. See
1875 man ld(1) for info on --build-id.
1876
1877 - stapio will now report if a child process has an abnormal exit along with
1878 the associated status or signal.
1879
1880 - Compiler optimization may sometimes result in systemtap not being able to
1881 access a user-space probe argument. Compiling the application with
1882 -DSTAP_SDT_ARG_CONSTRAINT=nr will force the argument to be an immediate or
1883 register value which should enable systemtap to access the argument.
1884
1885 - GNU Gettext has now been intergrated with systemtap. Our translation
1886 page can be found at http://www.transifex.net/projects/p/systemtap/ .
1887 "make update-po" will generate the necessary files to use translated
1888 messages. Please refer to the po/README file for more info and
1889 please consider contributing to this I18N effort!
1890
1891 - The new addr() function returns the probe's instruction pointer.
1892
1893 - process("...").library("...") probes are now supported. Wildcards
1894 are supported in the library-name part, to refer to any shared
1895 library that is required by process-name, which matches the glob
1896 pattern and the rest of the probe point.
1897
1898 - The "--remote USER@HOST" functionality can now be specified multiple times
1899 to fan out on multiple targets. If the targets have distinct kernel and
1900 architecture configurations, stap will automatically build the script
1901 appropriately for each one. This option is also no longer considered
1902 experimental.
1903
1904 - The NSS certificate database generated for use by the compile server is now
1905 generated with no password. Previously, a random password was generated and
1906 used to access the database. This change should be transparent to most users.
1907 However, if you are prompted for a password when using systemtap, then
1908 running $libexecdir/stap-gen-cert should correct the problem.
1909
1910 - The timestamp tapset includes jiffies() and HZ() for lightweight approximate
1911 timekeeping.
1912
1913 - A powerful new command line option --version has been added.
1914
1915 - process.mark now supports $$parms for reading probe parameters.
1916
1917 - A new command line option, --use-server-on-error[=yes|no] is available
1918 for stap. It instructs stap to retry compilation of a script using a
1919 compile server if it fails on the local host. The default setting
1920 is 'no'.
1921
1922 - The following deprecated tools have been removed:
1923 stap-client
1924 stap-authorize-server-cert
1925 stap-authorize-signing-cert
1926 stap-find-or-start-server
1927 stap-find-servers
1928 Use the --use-server, --trust-server and --list-servers options of stap
1929 instead.
1930
1931 * What's new in version 1.4, 2011-01-17
1932
1933 - Security fixes for CVE-2010-4170, CVE-2010-4171: staprun module
1934 loading/unloading
1935
1936 - A new /* myproc-unprivileged */ marker is now available for embedded C
1937 code and and expressions. Like the /* unprivileged */ marker, it makes
1938 the code or expression available for use in unprivileged mode (see
1939 --unprivileged). However, it also automatically adds a call to
1940 assert_is_myproc() to the code or expression, thus, making it available
1941 to the unprivileged user only if the target of the current probe is within
1942 the user's own process.
1943
1944 - The experimental "--remote USER@HOST" option will run pass 5 on a given
1945 ssh host, after building locally (or with --use-server) for that target.
1946
1947 - Warning messages from the script may now be suppressed with the stap
1948 and/or staprun -w option. By default, duplicate warning messages are
1949 suppressed (up to a certain limit). With stap --vp 00002 and above,
1950 the duplicate elimination is defeated.
1951
1952 - The print_ubacktrace and usym* functions attempt to print the full
1953 path of the user-space binaries' paths, instead of just the basename.
1954 The maximum saved path length is set by -DTASK_FINDER_VMA_ENTRY_PATHLEN,
1955 default 64. Warning messages are produced if unwinding fails due to
1956 a missing 'stap -d MODULE' option, providing preloaded unwind data.
1957
1958 - The new tz_ctime() tapset function prints times in the local time zone.
1959
1960 - More kernel tracepoints are accessible to the kernel.trace("...") mechanism,
1961 if kernel source trees or debuginfo are available. These formerly "hidden"
1962 tracepoints are those that are declared somewhere other than the usual
1963 include/linux/trace/ headers, such as xfs and kvm.
1964
1965 - debuginfo-based process("...").function/.statement/.mark probes support
1966 wildcards in the process-name part, to refer to any executable files that
1967 match the glob pattern and the rest of the probe point.
1968
1969 - The -t option now displays information per probe-point rather than a summary
1970 for each probe. It also now shows the derivation chain for each probe-point.
1971
1972 - A rewrite of the sys/sdt.h header file provides zero-cost startup (few or
1973 no ELF relocations) for the debuginfo-less near-zero-cost runtime probes.
1974 Binaries compiled with earlier sdt.h versions remain supported. The
1975 stap -L (listing) option now lists parameters for sys/sdt.h markers.
1976
1977 - The implementation of the integrated compile-server client has been
1978 extended.
1979 o --use-server now accepts an argument representing a particular server and
1980 may be specified more than once.
1981 o --list-servers now accepts an expanded range of arguments.
1982 o a new --trust-servers option has been added to stap to replace several
1983 old certificate-management scripts.
1984 o The following tools are now deprecated and will be removed in release 1.5:
1985 stap-client
1986 stap-authorize-server-cert
1987 stap-authorize-signing-cert
1988 stap-find-or-start-server
1989 stap-find-servers
1990 See man stap(1) for complete details.
1991
1992 - The compile-server now returns the uprobes.ko to the client when it is
1993 required by the script being compiled. The integrated compile-server client
1994 now makes it available to be loaded by staprun. The old (deprecated)
1995 stap-client does not do this.
1996
1997 - process probes with scripts as the target are recognized by stap and the
1998 interpreter would be selected for probing.
1999
2000 - Starting in release 1.5, these old variables/functions will be deprecated
2001 and will only be available when the '--compatible=1.4' flag is used:
2002
2003 - In the 'syscall.add_key' probe, the 'description_auddr' variable
2004 has been deprecated in favor of the new 'description_uaddr'
2005 variable.
2006 - In the 'syscall.fgetxattr', 'syscall.fsetxattr',
2007 'syscall.getxattr', 'syscall.lgetxattr', and
2008 'syscall.lremovexattr' probes, the 'name2' variable has been
2009 deprecated in favor of the new 'name_str' variable.
2010 - In the 'nd_syscall.accept' probe the 'flag_str' variable
2011 has been deprecated in favor of the new 'flags_str' variable.
2012 - In the 'nd_syscall.dup' probe the 'old_fd' variable has been
2013 deprecated in favor of the new 'oldfd' variable.
2014 - In the 'nd_syscall.fgetxattr', 'nd_syscall.fremovexattr',
2015 'nd_syscall.fsetxattr', 'nd_syscall.getxattr', and
2016 'nd_syscall.lremovexattr' probes, the 'name2' variable has been
2017 deprecated in favor of the new 'name_str' variable.
2018 - The tapset alias 'nd_syscall.compat_pselect7a' was misnamed. It should
2019 have been 'nd_syscall.compat_pselect7' (without the trailing 'a').
2020 - The tapset function 'cpuid' is deprecated in favor of the better known
2021 'cpu'.
2022 - In the i386 'syscall.sigaltstack' probe, the 'ussp' variable has
2023 been deprecated in favor of the new 'uss_uaddr' variable.
2024 - In the ia64 'syscall.sigaltstack' probe, the 'ss_uaddr' and
2025 'oss_uaddr' variables have been deprecated in favor of the new
2026 'uss_uaddr' and 'uoss_uaddr' variables.
2027 - The powerpc tapset alias 'syscall.compat_sysctl' was deprecated
2028 and renamed 'syscall.sysctl32'.
2029 - In the x86_64 'syscall.sigaltstack' probe, the 'regs_uaddr'
2030 variable has been deprecated in favor of the new 'regs' variable.
2031
2032 * What's new in version 1.3, 2010-07-21
2033
2034 - The uprobes kernel module now has about half the overhead when probing
2035 NOPs, which is particularly relevant for sdt.h markers.
2036
2037 - New stap option -G VAR=VALUE allows overriding global variables
2038 by passing the settings to staprun as module options.
2039
2040 - The tapset alias 'syscall.compat_pselect7a' was misnamed. It should
2041 have been 'syscall.compat_pselect7' (without the trailing 'a').
2042 Starting in release 1.4, the old name will be deprecated and
2043 will only be available when the '--compatible=1.3' flag is used.
2044
2045 - A new procfs parameter .umask(UMASK) which provides modification of
2046 file permissions using the proper umask value. Default file
2047 permissions for a read probe are 0400, 0200 for a write probe, and
2048 0600 for a file with a read and write probe.
2049
2050 - It is now possible in some situations to use print_ubacktrace() to
2051 get a user space stack trace from a kernel probe point. e.g. for
2052 user backtraces when there is a pagefault:
2053 $ stap -d /bin/sort --ldd -e 'probe vm.pagefault {
2054 if (pid() == target()) {
2055 printf("pagefault @0x%x\n", address); print_ubacktrace();
2056 } }' -c /bin/sort
2057 [...]
2058 pagefault @0x7fea0595fa70
2059 0x000000384f07f958 : __GI_strcmp+0x12b8/0x1440 [libc-2.12.so]
2060 0x000000384f02824e : __gconv_lookup_cache+0xee/0x5a0 [libc-2.12.so]
2061 0x000000384f021092 : __gconv_find_transform+0x92/0x2cf [libc-2.12.so]
2062 0x000000384f094896 : __wcsmbs_load_conv+0x106/0x2b0 [libc-2.12.so]
2063 0x000000384f08bd90 : mbrtowc+0x1b0/0x1c0 [libc-2.12.so]
2064 0x0000000000404199 : ismbblank+0x39/0x90 [sort]
2065 0x0000000000404a4f : inittables_mb+0xef/0x290 [sort]
2066 0x0000000000406934 : main+0x174/0x2510 [sort]
2067 0x000000384f01ec5d : __libc_start_main+0xfd/0x1d0 [libc-2.12.so]
2068 0x0000000000402509 : _start+0x29/0x2c [sort]
2069 [...]
2070
2071 - New tapset functions to get a string representation of a stack trace:
2072 sprint_[u]backtrace() and sprint_[u]stack().
2073
2074 - New tapset function to get the module (shared library) name for a
2075 user space address umodname:string(long). The module name will now
2076 also be in the output of usymdata() and in backtrace addresses even
2077 when they were not given with -d at the command line.
2078
2079 - Kernel backtraces are now much faster (replaced a linear search
2080 with a binary search).
2081
2082 - A new integrated compile-server client is now available as part of stap.
2083
2084 o 'stap --use-server ...' is equivalent to 'stap-client ...'
2085 o 'stap --list-servers' is equivalent to 'stap-find-servers'
2086 o 'stap --list-servers=online' is equivalent to 'stap-find-servers --all'
2087 o stap-client and its related tools will soon be deprecated.
2088 o the nss-devel and avahi-devel packages are required for building stap with
2089 the integrated client (checked during configuration).
2090 o nss and avahi are required to run the integrated client.
2091
2092 - A new operator @entry is available for automatically saving an expression
2093 at entry time for use in a .return probe.
2094 probe foo.return { println(get_cycles() - @entry(get_cycles())) }
2095
2096 - Probe $target variables and @cast() can now use a suffix to print complex
2097 data types as strings. Use a single '$' for a shallow view, or '$$' for a
2098 deeper view that includes nested types. For example, with fs_struct:
2099 $fs$ : "{.users=%i, .lock={...}, .umask=%i,
2100 .in_exec=%i, .root={...}, .pwd={...}}"
2101 $fs$$ : "{.users=%i, .lock={.raw_lock={.lock=%u}}, .umask=%i, .in_exec=%i,
2102 .root={.mnt=%p, .dentry=%p}, .pwd={.mnt=%p, .dentry=%p}}"
2103
2104 - The <sys/sdt.h> user-space markers no longer default to an implicit
2105 MARKER_NAME_ENABLED() semaphore check for each marker. To check for
2106 enabled markers use a .d declaration file, then:
2107 if (MARKER_NAME_ENABLED()) MARKER_NAME()
2108
2109 - Hyphenated <sys/sdt.h> marker names such as process(...).mark("foo-bar")
2110 are now accepted in scripts. They are mapped to the double-underscore
2111 form ("foo__bar").
2112
2113 - More robust <sys/sdt.h> user-space markers support is included. For
2114 some platforms (x86*, ppc*), this can let systemtap probe the markers
2115 without debuginfo. This implementation also supports preserving
2116 the "provider" name associated with a marker:
2117 probe process("foo").provider("bar").mark("baz") to match
2118 STAP_PROBE<n>(bar, baz <...>)
2119 (Compile with -DSTAP_SDT_V1 to revert to the previous implementation.
2120 Systemtap supports pre-existing or new binaries using them.)
2121
2122 - Embedded-C may be used within expressions as values, when in guru mode:
2123 num = %{ LINUX_VERSION_CODE %} // int64_t
2124 name = %{ /* string */ THIS_MODULE->name %} // const char*
2125 printf ("%s %x\n", name, num)
2126 The usual /* pure */, /* unprivileged */, and /* guru */ markers may be used
2127 as with embedded-C functions.
2128
2129 - By default the systemtap-runtime RPM builds now include a shared
2130 library, staplog.so, that allows crash to extract systemtap data from
2131 a vmcore image.
2132
2133 - Iterating with "foreach" can now explicitly save the value for the loop.
2134 foreach(v = [i,j] in array)
2135 printf("array[%d,%s] = %d\n", i, j, v /* array[i,j] */)
2136
2137 - The new "--ldd" option automatically adds any additional shared
2138 libraries needed by probed or -d-listed userspace binaries to the -d
2139 list, to enable symbolic backtracing through them. Similarly, the
2140 new "--all-modules" option automatically adds any currently loaded
2141 kernel modules (listed in /proc/modules) to the -d list.
2142
2143 - A new family of set_kernel_* functions make it easier for gurus to write
2144 new values at arbitrary memory addresses.
2145
2146 - Probe wildcards can now use '**' to cross the '.' separator.
2147 $ stap -l 'sys**open'
2148 syscall.mq_open
2149 syscall.open
2150
2151 - Backward compatibility flags (--compatible=VERSION, and matching
2152 script preprocessing predicate %( systemtap_v CMP "version" %)
2153 and a deprecation policy are being introduced, in case future
2154 tapset/language changes break valid scripts.
2155
2156 * What's new in version 1.2, 2010-03-22
2157
2158 - Prototype support for "perf events", where the kernel supports the
2159 2.6.33 in-kernel API. Probe points may refer to low-level
2160 perf_event_attr type/config numbers, or to a number of aliases
2161 defined in the new perf.stp tapset:
2162 probe perf.sw.cpu_clock, perf.type(0).config(4) { }
2163
2164 - Type-casting can now use multiple headers to resolve codependencies.
2165 @cast(task, "task_struct",
2166 "kernel<linux/sched.h><linux/fs_struct.h>")->fs->umask
2167
2168 - Tapset-related man pages have been renamed. 'man -k 3stap' should show
2169 the installed list, which due to prefixing should no longer collide over
2170 ordinary system functions.
2171
2172 - User space marker arguments no longer use volatile if the version of gcc,
2173 which must be at least 4.5.0, supports richer DWARF debuginfo. Use cflags
2174 -DSTAP_SDT_VOLATILE=volatile or -DSTAP_SDT_VOLATILE= when building
2175 the sys/sdt.h application to override this one way or another.
2176
2177 - A new construct for error handling is available. It is similar to c++
2178 exception catching, using try and catch as new keywords. Within a handler
2179 or function, the following is valid and may be nested:
2180 try { /* arbitrary statements */ }
2181 catch (er) { /* e.g. println("caught error ", er) */ }
2182
2183 - A new command line flag '-W' forces systemtap to abort translation of
2184 a script if any warnings are produced. It is similar to gcc's -Werror.
2185 (If '-w' is also supplied to suppress warnings, it wins.)
2186
2187 - A new predicate @defined is available for testing whether a
2188 particular $variable/expression is resolvable at translate time:
2189 probe foo { if (@defined($bar)) log ("$bar is available here") }
2190
2191 - Adjacent string literals are glued together, making this
2192 construct valid:
2193 probe process("/usr" @1 "/bin").function("*") { ... }
2194
2195 - In order to limit potential impact from future security problems,
2196 the stap-server process does not permit its being launched as root.
2197
2198 - On recent kernels, for some architectures/configurations, hardware
2199 breakpoint probes are supported. The probe point syntax is:
2200
2201 probe kernel.data(ADDRESS).write
2202 probe kernel.data(ADDRESS).length(LEN).write
2203 probe kernel.data("SYMBOL_NAME").write
2204
2205 * What's new in version 1.1, 2010-01-15
2206
2207 - New tracepoint based tapset for memory subsystem.
2208
2209 - The loading of signed modules by staprun is no longer allowed for
2210 ordinary, unprivileged users. This means that only root, members of
2211 the group 'stapdev' and members of the group 'stapusr' can load
2212 systemtap modules using staprun, stap or stap-client. The minimum
2213 privilege required to run arbitrary --unprivileged scripts is now
2214 'stapusr' membership.
2215
2216 - The stap-server initscript is available. This initscript allows you
2217 to start systemtap compile servers as a system service and to manage
2218 these servers as a group or individually. The stap-server initscript
2219 is installed by the systemtap-server rpm. The build directory for
2220 the uprobes module (/usr/share/systemtap/runtime/uprobes) is made
2221 writable by the 'stap-server' group. All of the files generated when
2222 building the uprobes module, including the digital signature, are
2223 also writable by members of stap-server.
2224
2225 See initscript/README.stap-server for details.
2226
2227 - Some of the compile server client, server and certificate management
2228 tools have been moved from $bindir to $libexecdir/systemtap.
2229 You should use the new stap-server script or the stap-server initscript
2230 for server management where possible. The stap-server script provides the same
2231 functionality as the stap-server initscript except that the servers are
2232 run by the invoking user by default as opposed to servers started by the
2233 stap-server initscript which are run by the user stap-server
2234 by default. See stap-server(8) for more information.
2235
2236 You may continue to use these tools by adding $libexecdir/systemtap to
2237 your path. You would need to do this, for example, if you are not root,
2238 you want to start a compile server and you are not running systemtap from a
2239 private installation. In this case you still need to use stap-start-server.
2240
2241 - Any diagnostic output line that starts with "ERROR", as in
2242 error("foo"), will promote a "Pass 5: run failed", and the return
2243 code is 1.
2244
2245 - Systemtap now warns about global variables being referenced from other
2246 script files. This aims to protect against unintended local-vs-global
2247 namespace collisions such as:
2248
2249 % cat some_tapset.stp
2250 probe baz.one = bar { foo = $foo; bar = $bar }
2251 % cat end_user_script.stp
2252 global foo # intended to be private variable
2253 probe timer.s(1) { foo ++ }
2254 probe baz.* { println(foo, pp()) }
2255 % stap end_user_script.stp
2256 WARNING: cross-file global variable reference to foo from some_tapset.stp
2257
2258 - Preprocessor conditional for kernel configuration testing:
2259 %( CONFIG_foo == "y" %? ... %)
2260
2261 - ftrace(msg:string) tapset function to send strings to the system-wide
2262 ftrace ring-buffer (if any).
2263
2264 - Better support for richer DWARF debuginfo output from GCC 4.5
2265 (variable tracking assignments). Kernel modules are now always resolved
2266 against all their dependencies to find any info referring to missing
2267 symbols. DW_AT_const_value is now supported when no DW_AT_location
2268 is available.
2269
2270 * What's new in verson 1.0, 2009-09-22
2271
2272 - process().mark() probes now use an enabling semaphore to reduce the
2273 computation overhead of dormant probes.
2274
2275 - The function spec for dwarf probes now supports C++ scopes, so you can
2276 limit the probes to specific namespaces or classes. Multiple scopes
2277 can be specified, and they will be matched progressively outward.
2278 probe process("foo").function("std::vector<*>::*") { }
2279 probe process("foo").function("::global_function") { }
2280
2281 - It is now possible to cross-compile systemtap scripts for foreign
2282 architectures, using the new '-a ARCH' and '-B OPT=VALUE' flags.
2283 For example, put arm-linux-gcc etc. into your $PATH, and point
2284 systemtap at the target kernel build tree with:
2285 stap -a arm -B CROSS_COMPILE=arm-linux- -r /build/tree [...]
2286 The -B option is passed to kbuild make. -r identifies the already
2287 configured/built kernel tree and -a its architecture (kbuild ARCH=...).
2288 Systemtap will infer -p4.
2289
2290 - Cross compilation using the systemtap client and server
2291 - stap-start-server now accepts the -r, -R, -I, -B and -a options in
2292 order to start a cross compiling server. The server will correctly
2293 advertise itself with respect to the kernel release and architecture
2294 that it compiles for.
2295 - When specified on stap-client, the -r and -a options will be
2296 considered when searching for a suitable server.
2297
2298 - When using the systemtap client and server udp port 5353 must be open
2299 in your firewall in order for the client to find servers using
2300 avahi-browse. Also the systemtap server will choose a random port in
2301 the range 1024-63999 for accepting ssl connections.
2302
2303 - Support for unprivileged users:
2304 ***********************************************************************
2305 * WARNING!!!!!!!!!! *
2306 * This feature is EXPERIMENTAL at this time and should be used with *
2307 * care. This feature allows systemtap kernel modules to be loaded by *
2308 * unprivileged users. The user interface and restrictions will change *
2309 * as this feature evolves. *
2310 ***********************************************************************
2311 - Systemtap modules generated from scripts which use a restricted
2312 subset of the features available may be loaded by staprun for
2313 unprivileged users. Previously, staprun would load modules only for
2314 root or for members of the groups stapdev and stapusr.
2315 - Using the --unprivileged option on stap enables translation-time
2316 checking for use by unprivileged users (see restrictions below).
2317 - All modules deemed suitable for use by unprivileged users will be
2318 signed by the systemtap server when --unprivileged is specified on
2319 stap-client. See module signing in release 0.9.8 and stap-server in
2320 release 0.9 below.
2321 - Modules signed by trusted signers (servers) and verified by staprun
2322 will be loaded by staprun regardless of the user's privilege level.
2323 - The system administrator asserts the trustworthiness of a signer
2324 (server) by running stap-authorize-signing-cert <cert-file> as root,
2325 where the <cert-file> can be found in
2326 ~<user>/.systemtap/ssl/server/stap.cert for servers started by
2327 ordinary users and in $sysconfdir/systemtap/ssl/server/stap.cert for
2328 servers started by root.
2329 - Restrictions are intentionally strict at this time and may be
2330 relaxed in the future:
2331 - probe points are restricted to:
2332 begin, begin(n), end, end(n), error, error(n), never,
2333 timer.{jiffies,s,sec,ms,msec,us,usec,ns,nsec}(n)*, timer.hz(n),
2334 process.* (for processes owned by the user).
2335 - use of embedded C code is not allowed.
2336 - use of tapset functions is restricted.
2337 - some tapset functions may not be used at all. A message will be
2338 generated at module compilation time.
2339 - some actions by allowed tapset functions may only be performed
2340 in the context of the user's own process. A runtime fault will
2341 occur in these situations, for example, direct memory access.
2342 - The is_myproc() tapset function has been provided so that
2343 tapset writers for unprivileged users can check that the
2344 context is of the users own process before attempting these
2345 actions.
2346 - accessing the kernel memory space is not allowed.
2347 - The following command line options may not be used by stap-client
2348 -g, -I, -D, -R, -B
2349 - The following environment variables are ignored by stap-client:
2350 SYSTEMTAP_RUNTIME, SYSTEMTAP_TAPSET, SYSTEMTAP_DEBUGINFO_PATH
2351 - nss and nss-tools are required to use this feature.
2352
2353 - Support output file switching by SIGUSR2. Users can command running
2354 stapio to switch output file by sending SIGUSR2.
2355
2356 - Memory consumption for scripts involving many uprobes has been
2357 dramatically reduced.
2358
2359 - The preprocessor now supports || and && in the conditions.
2360 e.g. %( arch == "x86_64" || arch == "ia64" %: ... %)
2361
2362 - The systemtap notion of "architecture" now matches the kernel's, rather
2363 than that of "uname -m". This means that 32-bit i386 family are all
2364 known as "i386" rather than "i386" or "i686"; "ppc64" as "powerpc";
2365 "s390x" as "s390", and so on. This is consistent between the new
2366 "-a ARCH" flag and the script-level %( arch ... %) conditional.
2367
2368 - It is now possible to define multiple probe aliases with the same name.
2369 A probe will expand to all matching aliases.
2370 probe foo = bar { }
2371 probe foo = baz { }
2372 probe foo { } # expands twice, once to bar and once to baz
2373
2374 - A new experimental transport mechanism, using ftrace's ring_buffer,
2375 has been added. This may become the default transport mechanism in
2376 future versions of systemtap. To test this new transport mechanism,
2377 define 'STP_USE_RING_BUFFER'.
2378
2379 - Support for recognizing DW_OP_{stack,implicit}_value DWARF expressions
2380 as emitted by GCC 4.5.
2381
2382 * What's new in version 0.9.9, 2009-08-04
2383
2384 - Systemwide kernel .function.return (kretprobe) maxactive defaults may
2385 be overridden with the -DKRETACTIVE=nnn parameter.
2386
2387 - Translation pass 2 is significantly faster by avoiding unnecessary
2388 searching through a kernel build/module directory tree.
2389
2390 - When compiled against elfutils 0.142 systemtap now handles the new
2391 DW_OP_call_frame_CFA generated by by GCC.
2392
2393 - uprobes and ustack() are more robust when used on applications that
2394 depend on prelinked/separate debuginfo shared libraries.
2395
2396 - User space PROBE marks are not always found with or without separate
2397 debuginfo. The .probes section itself is now always put in the main
2398 elf file and marked as allocated. When building pic code the section
2399 is marked writable. The selinux memory check problems seen with
2400 programs using STAP_PROBES is fixed.
2401
2402 - statement() probes can now override "address not at start of statement"
2403 errors in guru mode. They also provide alternative addresses to use
2404 in non-guru mode.
2405
2406 - The stapgraph application can generate graphs of data and events
2407 emitted by systemtap scripts in real time. Run "stapgraph
2408 testsuite/systemtap.examples/general/grapher.stp" for an example of
2409 graphing the system load average and keyboard events.
2410
2411 - Dwarf probes now show parameters and local variables in the verbose
2412 listing mode (-L).
2413
2414 - Symbol aliases are now resolved to their canonical dwarf names. For
2415 example, probing "malloc" in libc resolves to "__libc_malloc".
2416
2417 - The syntax for dereferencing $target variables and @cast() gained new
2418 capabilities:
2419 - Array indexes can now be arbitrary numeric expressions.
2420 - Array subscripts are now supported on pointer types.
2421 - An '&' operator before a @cast or $target returns the address of the
2422 final component, especially useful for nested structures.
2423
2424 - For reading all probe variables, kernel.mark now supports $$vars and
2425 $$parms, and process.syscall now supports $$vars.
2426
2427 - The SNMP tapset provides probes and functions for many network
2428 statistics. See stapprobes.snmp(3stap) for more details.
2429
2430 - The dentry tapset provides functions to map kernel VFS directory entries
2431 to file or full path names: d_path(), d_name() and reverse_path_walk().
2432
2433 - SystemTap now has userspace markers in its own binaries, and the stap
2434 tapset provides the available probepoints and local variables.
2435
2436 - Miscellaneous new tapset functions:
2437 - pgrp() returns the process group ID of the current process
2438 - str_replace() performs string replacement
2439
2440 * What's new in version 0.9.8, 2009-06-11
2441
2442 - Miscellaneous new tapset functions:
2443 - sid() returns the session ID of the current process
2444 - stringat() indexes a single character from a string.
2445
2446 - Using %M in print formats for hex dumps can now print entire buffers,
2447 instead of just small numbers.
2448
2449 - Dwarfless syscalls: The nd_syscalls tapset is now available to probe
2450 system calls without requiring kernel debugging information. All of
2451 the same probepoints in the normal syscalls tapset are available with
2452 an "nd_" prefix, e.g. syscall.open becomes nd_syscall.open. Most
2453 syscall arguments are also available by name in nd_syscalls.
2454
2455 - Module signing: If the appropriate nss libraries are available on your
2456 system, stap-server will sign each compiled module using a self-generated
2457 certificate. This is the first step toward extending authority to
2458 load certain modules to unprivileged users. For now, if the system
2459 administrator adds a certificate to a database of trusted signers
2460 (stap-authorize-signing-cert), modules signed using that certificate
2461 will be verified by staprun against tampering. Otherwise, you should
2462 notice no difference in the operation of stap or staprun.
2463
2464 * What's new in version 0.9.7, 2009-04-23
2465
2466 - @cast can now determine its type information using an explicit header
2467 specification. For example:
2468 @cast(tv, "timeval", "<sys/time.h>")->tv_sec
2469 @cast(task, "task_struct", "kernel<linux/sched.h>")->tgid
2470
2471 - The overlapping process.* tapsets are now separated. Those probe points
2472 documented in stapprobes(3stap) remain the same. Those that were formerly
2473 in stapprobes.process(3stap) have been renamed to kprocess, to reflect
2474 their kernel perspective on processes.
2475
2476 - The --skip-badvars option now also suppresses run-time error
2477 messages that would otherwise result from erroneous memory accesses.
2478 Such accesses can originate from $context expressions fueled by
2479 erroneous debug data, or by kernel_{long,string,...}() tapset calls.
2480
2481 - New probes kprobe.function(FUNCTION) and kprobe.function(FUNCTION).return
2482 for dwarfless probing. These postpone function address resolution to
2483 run-time and use the kprobe symbol-resolution mechanism.
2484 Probing of absolute statements can be done using the
2485 kprobe.statement(ADDRESS).absolute construct.
2486
2487 - EXPERIMENTAL support for user process unwinding. A new collection of
2488 tapset functions have been added to handle user space backtraces from
2489 probe points that support them (currently process and timer probes -
2490 for timer probes test whether or not in user space first with the
2491 already existing user_mode() function). The new tapset functions are:
2492 uaddr - User space address of current running task.
2493 usymname - Return the symbol of an address in the current task.
2494 usymdata - Return the symbol and module offset of an address.
2495 print_ustack - Print out stack for the current task from string.
2496 print_ubacktrace - Print stack back trace for current task.
2497 ubacktrace - Hex backtrace of current task stack.
2498 Please read http://sourceware.org/ml/systemtap/2009-q2/msg00364.html
2499 on the current restrictions and possible changes in the future and
2500 give feedback if you want to influence future developments.
2501
2502 * What's new in version 0.9.5, 2009-03-27
2503
2504 - New probes process().insn and process().insn.block that allows
2505 inspection of the process after each instruction or block of
2506 instructions executed. So to count the total number of instructions
2507 a process executes during a run do something like:
2508 $ stap -e 'global steps; probe process("/bin/ls").insn {steps++}
2509 probe end {printf("Total instructions: %d\n", steps);}' \
2510 -c /bin/ls
2511 This feature can slow down execution of a process somewhat.
2512
2513 - Systemtap probes and function man pages extracted from the tapsets
2514 are now available under 3stap. To show the page for probe vm.pagefault
2515 or the stap function pexecname do:
2516 $ man 3stap vm.pagefault
2517 $ man 3stap pexecname
2518
2519 - Kernel tracepoints are now supported for probing predefined kernel
2520 events without any debuginfo. Tracepoints incur less overhead than
2521 kprobes, and context parameters are available with full type
2522 information. Any kernel 2.6.28 and later should have defined
2523 tracepoints. Try the following to see what's available:
2524 $ stap -L 'kernel.trace("*")'
2525
2526 - Typecasting with @cast now supports modules search paths, which is
2527 useful in case there are multiple places where the type definition
2528 may be found. For example:
2529 @cast(sdev, "scsi_device", "kernel:scsi_mod")->sdev_state
2530
2531 - On-file flight recorder is supported. It allows stap to record huge
2532 trace log on the disk and to run in background.
2533 Passing -F option with -o option runs stap in background mode. In this
2534 mode, staprun is detached from console, and stap itself shows staprun's
2535 pid and exits.
2536 Specifying the max size and the max number of log files are also available
2537 by passing -S option. This option has one or two arguments seperated by
2538 a comma. The first argument is the max size of a log file in MB. If the
2539 size of a log file exceeds it, stap switches to the next log file
2540 automatically. The second is how many files are kept on the disk. If the
2541 number of log files exceeds it, the oldest log file is removed
2542 automatically. The second argument can be omitted.
2543
2544 For example, this will record output on log files each of them is smaller
2545 than 1024MB and keep last 3 logs, in background.
2546 % stap -F -o /tmp/staplog -S 1024,3 script.stp
2547
2548 - In guru mode (-g), the kernel probing blocklist is disabled, leaving
2549 only a subset - the kernel's own internal kprobe blocklist - to attempt
2550 to filter out areas unsafe to probe. The differences may be enough to
2551 probe more interrupt handlers.
2552
2553 - Variables unavailable in current context may be skipped by setting a
2554 session level flag with command line option --skip-badvars now available.
2555 This replaces any dwarf $variable expressions that could not be resolved
2556 with literal numeric zeros, along with a warning message.
2557
2558 - Both kernel markers and kernel tracepoint support argument listing
2559 through stap -L 'kernel.mark("*")' or stap -L 'kernel.trace("*")'
2560
2561 - Users can use -DINTERRUPTIBLE=0 to prevent interrupt reentrancy in
2562 their script, at the cost of a bit more overhead to toggle the
2563 interrupt mask.
2564
2565 - Added reentrancy debugging. If stap is run with the arguments
2566 "-t -DDEBUG_REENTRANCY", additional warnings will be printed for
2567 every reentrancy event, including the probe points of the
2568 resident and interloper probes.
2569
2570 - Default to --disable-pie for configure.
2571 Use --enable-pie to turn it back on.
2572
2573 - Improved sdt.h compatibility and test suite for static dtrace
2574 compatible user space markers.
2575
2576 - Some architectures now use syscall wrappers (HAVE_SYSCALL_WRAPPERS).
2577 The syscall tapset has been enhanced to take care of the syscall
2578 wrappers in this release.
2579
2580 - Security fix for CVE-2009-0784: stapusr module-path checking race.
2581
2582 * What's new in version 0.9, 2009-02-19
2583
2584 - Typecasting is now supported using the @cast operator. A script can
2585 define a pointer type for a "long" value, and then access type members
2586 using the same syntax as with $target variables. For example, this will
2587 retrieve the parent pid from a kernel task_struct:
2588 @cast(pointer, "task_struct", "kernel")->parent->pid
2589
2590 - process().mark() probes are now possible to trace static user space
2591 markers put in programs with the STAP_PROBE macro using the new
2592 sys/sdt.h include file. This also provides dtrace compatible markers
2593 through DTRACE_PROBE and an associated python 'dtrace' script that
2594 can be used in builds based on dtrace that need dtrace -h or -G
2595 functionality.
2596
2597 - For those that really want to run stap from the build tree there is
2598 now the 'run-stap' script in the top-level build directory that sets
2599 up the SYSTEMTAP_TAPSET, SYSTEMTAP_RUNTIME, SYSTEMTAP_STAPRUN, and
2600 SYSTEMTAP_STAPIO environment variables (installing systemtap, in a
2601 local prefix, is still recommended for common use).
2602
2603 - Systemtap now comes with a new Beginners Guide that walks the user
2604 through their first steps setting up stap, understanding how it all
2605 works, introduces some useful scripts and describes some common
2606 pitfalls. It isn't created by default since it needs a Publican
2607 setup, but full build instructions can be found in the wiki:
2608 http://sourceware.org/systemtap/wiki/PublicanQuikHowto
2609 An online version can be found at:
2610 http://sourceware.org/systemtap/SystemTap_Beginners_Guide.pdf
2611
2612 - Standard tapsets included with Systemtap were modified to include
2613 extractable documentation information based on the kernel-doc
2614 infrastructure. When configured --enabled-docs a HTML and PDF
2615 version of the Tapset Reference Manual is produced explaining probes
2616 defined in each tapset.
2617
2618 - The systemtap client and compile server are now available.
2619 These allow you to compile a systemtap module on a host other than
2620 the one which it will be run, providing the client and server
2621 are compatible. Other than using a server for passes 1 through
2622 4, the client behaves like the 'stap' front end itself. This
2623 means, among other things, that the client will automatically
2624 load the resulting module on the local host unless -p[1234]
2625 was specified. See stap-server(8) for more details.
2626 The client/server now use SSL for network connection security and
2627 for signing.
2628
2629 The systemtap client and server are prototypes only. Interfaces, options
2630 and usage may change at any time.
2631
2632 - function("func").label("label") probes are now supported to allow matching
2633 the label of a function.
2634
2635 - Systemtap initscript is available. This initscript allows you to run
2636 systemtap scripts as system services (in flight recorder mode) and
2637 control those scripts individually.
2638 See README.systemtap for details.
2639
2640 - The stap "-r DIR" option may be used to identify a hand-made kernel
2641 build directory. The tool determines the appropriate release string
2642 automatically from the directory.
2643
2644 - Serious problems associated with user-space probing in shared libraries
2645 were corrected, making it now possible to experiment with probe shared
2646 libraries. Assuming dwarf debugging information is installed, use this
2647 twist on the normal syntax:
2648
2649 probe process("/lib64/libc-2.8.so").function("....") { ... }
2650
2651 This would probe all threads that call into that library. Running
2652 "stap -c CMD" or "stap -x PID" naturally restricts this to the target
2653 command+descendants only. $$vars etc. may be used.
2654
2655 - For scripts that sometimes terminate with excessive "skipped" probes,
2656 rerunning the script with "-t" (timing) will print more details about
2657 the skippage reasons.
2658
2659 - Symbol tables and unwind (backtracing) data support were formerly
2660 compiled in for all probed modules as identified by the script
2661 (kernel; module("name"); process("file")) plus those listed by the
2662 stap "-d BINARY" option. Now, this data is included only if the systemtap
2663 script uses tapset functions like probefunc() or backtrace() that require
2664 such information. This shrinks the probe modules considerably for the rest.
2665
2666 - Per-pass verbosity control is available with the new "--vp {N}+" option.
2667 "stap --vp 040" adds 4 units of -v verbosity only to pass 2. This is useful
2668 for diagnosing errors from one pass without excessive verbosity from others.
2669
2670 - Most probe handlers now run with interrupts enabled, for improved
2671 system responsiveness and less probing overhead. This may result
2672 in more skipped probes, for example if a reentrant probe handler
2673 is attempted from within an interrupt handler. It may also make the
2674 systemtap overload detection facility more likely to be triggered, as
2675 interrupt handlers' run time would be included in the self-assessed
2676 overhead of running probe handlers.
2677
2678 * What's new in version 0.8, 2008-11-13
2679
2680 - Cache limiting is now available. If the compiled module cache size is
2681 over a limit specified in the $SYSTEMTAP_DIR/cache/cache_mb_limit file,
2682 some old cache entries will be unlinked. See man stap(1) for more.
2683
2684 - Error and warning messages are now followed by source context displaying
2685 the erroneous line/s and a handy '^' in the following line pointing to the
2686 appropriate column.
2687
2688 - A bug reporting tool "stap-report" is now available which will quickly
2689 retrieve much of the information requested here:
2690 http://sourceware.org/systemtap/wiki/HowToReportBugs
2691
2692 - The translator can resolve members of anonymous structs / unions:
2693 given struct { int foo; struct { int bar; }; } *p;
2694 this now works: $p->bar
2695
2696 - The stap "-F" flag activates "flight recorder" mode, which consists of
2697 translating the given script as usual, but implicitly launching it into
2698 the background with staprun's existing "-L" (launch) option. A user
2699 can later reattach to the module with "staprun -A MODULENAME".
2700
2701 - Additional context variables are available on user-space syscall probes.
2702 - $argN ($arg1, $arg2, ... $arg6) in process(PATH_OR_PID).syscall
2703 gives you the argument of the system call.
2704 - $return in process(PATH_OR_PID).syscall.return gives you the return
2705 value of the system call.
2706
2707 - Target process mode (stap -c CMD or -x PID) now implicitly restricts all
2708 "process.*" probes to the given child process. (It does not affect
2709 kernel.* or other probe types.) The CMD string is normally run directly,
2710 rather than via a /bin/sh -c subshell, since then utrace/uprobe probes
2711 receive a fairly "clean" event stream. If metacharacters like
2712 redirection operators were present in CMD, then "sh -c CMD" is still
2713 used, and utrace/uprobe probes will receive events from the shell.
2714
2715 % stap -e 'probe process.syscall, process.end {
2716 printf("%s %d %s\n", execname(), pid(), pp())}'\
2717 -c ls
2718 ls 2323 process.syscall
2719 ls 2323 process.syscall
2720 ls 2323 process.end
2721
2722 - Probe listing mode is improved: "-L" lists available script-level variables
2723
2724 % stap -L 'syscall.*open*'
2725 syscall.mq_open name:string name_uaddr:long filename:string mode:long u_attr_uaddr:long oflag:long argstr:string
2726 syscall.open name:string filename:string flags:long mode:long argstr:string
2727 syscall.openat name:string filename:string flags:long mode:long argstr:string
2728
2729 - All user-space-related probes support $PATH-resolved executable
2730 names, so
2731
2732 probe process("ls").syscall {}
2733 probe process("./a.out").syscall {}
2734
2735 work now, instead of just
2736
2737 probe process("/bin/ls").syscall {}
2738 probe process("/my/directory/a.out").syscall {}
2739
2740 - Prototype symbolic user-space probing support:
2741
2742 # stap -e 'probe process("ls").function("*").call {
2743 log (probefunc()." ".$$parms)
2744 }' \
2745 -c 'ls -l'
2746
2747 This requires:
2748 - debugging information for the named program
2749 - a version of utrace in the kernel that is compatible with the "uprobes"
2750 kernel module prototype. This includes RHEL5 and older Fedora, but not
2751 yet current lkml-track utrace; a "pass 4a"-time build failure means
2752 your system cannot use this yet.
2753
2754 - Global variables which are written to but never read are now
2755 automatically displayed when the session does a shutdown. For example:
2756
2757 global running_tasks
2758 probe timer.profile {running_tasks[pid(),tid()] = execname()}
2759 probe timer.ms(8000) {exit()}
2760
2761 - A formatted string representation of the variables, parameters, or local
2762 variables at a probe point is now supported via the special $$vars,
2763 $$parms, and $$locals context variables, which expand to a string
2764 containing a list "var1=0xdead var2=0xbeef var3=?". (Here, var3 exists
2765 but is for some reason unavailable.) In return probes only, $$return
2766 expands to an empty string for a void function, or "return=0xf00".
2767
2768
2769 * What's new in version 0.7, 2008-07-15
2770
2771 - .statement("func@file:*") and .statement("func@file:M-N") probes are now
2772 supported to allow matching a range of lines in a function. This allows
2773 tracing the execution of a function.
2774
2775 - Scripts relying on probe point wildcards like "syscall.*" that expand
2776 to distinct kprobes are processed significantly faster than before.
2777
2778 - The vector of script command line arguments is available in a
2779 tapset-provided global array argv[]. It is indexed 1 ... argc,
2780 another global. This can substitute for of preprocessor
2781 directives @NNN that fail at parse time if there are not
2782 enough arguments.
2783
2784 printf("argv: %s %s %s", argv[1], argv[2], argv[3])
2785
2786 - .statement("func@file+line") probes are now supported to allow a
2787 match relative to the entry of the function incremented by line
2788 number. This allows using the same systemtap script if the rest
2789 of the file.c source only changes slightly.
2790
2791 - A probe listing mode is available.
2792 % stap -l vm.*
2793 vm.brk
2794 vm.mmap
2795 vm.munmap
2796 vm.oom_kill
2797 vm.pagefault
2798 vm.write_shared
2799
2800 - More user-space probe types are added:
2801
2802 probe process(PID).begin { }
2803 probe process("PATH").begin { }
2804 probe process(PID).thread.begin { }
2805 probe process("PATH").thread.begin { }
2806 probe process(PID).end { }
2807 probe process("PATH").end { }
2808 probe process(PID).thread.end { }
2809 probe process("PATH").thread.end { }
2810 probe process(PID).syscall { }
2811 probe process("PATH").syscall { }
2812 probe process(PID).syscall.return { }
2813 probe process("PATH").syscall.return { }
2814
2815 - Globals now accept ; terminators
2816
2817 global odds, evens;
2818 global little[10], big[5];
2819
2820 * What's new in version 0.6, 2007-12-15
2821
2822 - A copy of the systemtap tutorial and language reference guide
2823 are now included.
2824
2825 - There is a new format specifier, %m, for the printf family of
2826 functions. It functions like %s, except that it does not stop when
2827 a nul ('\0') byte is encountered. The number of bytes output is
2828 determined by the precision specifier. The default precision is 1.
2829 For example:
2830
2831 printf ("%m", "My String") // prints one character: M
2832 printf ("%.5", myString) // prints 5 bytes beginning at the start
2833 // of myString
2834
2835 - The %b format specifier for the printf family of functions has been enhanced
2836 as follows:
2837
2838 1) When the width and precision are both unspecified, the default is %8.8b.
2839 2) When only one of the width or precision is specified, the other defaults
2840 to the same value. For example, %4b == %.4b == %4.4b
2841 3) Nul ('\0') bytes are used for field width padding. For example,
2842
2843 printf ("%b", 0x1111deadbeef2222) // prints all eight bytes
2844 printf ("%4.2b", 0xdeadbeef) // prints \0\0\xbe\xef
2845
2846 - Dynamic width and precision are now supported for all printf family format
2847 specifiers. For example:
2848
2849 four = 4
2850 two = 2
2851 printf ("%*.*b", four, two, 0xdeadbbeef) // prints \0\0\xbe\xef
2852 printf ("%*d", four, two) // prints <space><space><space>2
2853
2854 - Preprocessor conditional expressions can now include wildcard style
2855 matches on kernel versions.
2856 %( kernel_vr != "*xen" %? foo %: bar %)
2857
2858 - Prototype support for user-space probing is showing some progress.
2859 No symbolic notations are supported yet (so no probing by function names,
2860 file names, process names, and no access to $context variables), but at
2861 least it's something:
2862
2863 probe process(PID).statement(ADDRESS).absolute { }
2864
2865 This will set a uprobe on the given process-id and given virtual address.
2866 The proble handler runs in kernel-space as usual, and can generally use
2867 existing tapset functions.
2868
2869 - Crash utility can retrieve systemtap's relay buffer from a kernel dump
2870 image by using staplog which is a crash extension module. To use this
2871 feature, type commands as below from crash(8)'s command line:
2872
2873 crash> extend staplog.so
2874 crash> help systemtaplog
2875
2876 Then, you can see more precise help message.
2877
2878 - You can share a relay buffer amoung several scripts and merge outputs from
2879 several scripts by using "-DRELAY_HOST" and "-DRELAY_GUEST" options.
2880 For example:
2881
2882 # run a host script
2883 % stap -ve 'probe begin{}' -o merged.out -DRELAY_HOST &
2884 # wait until starting the host.
2885 % stap -ve 'probe begin{print("hello ");exit()}' -DRELAY_GUEST
2886 % stap -ve 'probe begin{print("world\n");exit()}' -DRELAY_GUEST
2887
2888 Then, you'll see "hello world" in merged.out.
2889
2890 - You can add a conditional statement for each probe point or aliase, which
2891 is evaluated when the probe point is hit. If the condition is false, the
2892 whole probe body(including aliases) is skipped. For example:
2893
2894 global switch = 0;
2895 probe syscall.* if (switch) { ... }
2896 probe procfs.write {switch = strtol($value,10)} /* enable/disable ctrl */
2897
2898 - Systemtap will warn you if your script contains unused variables or
2899 functions. This is helpful in case of misspelled variables. If it
2900 doth protest too much, turn it off with "stap -w ...".
2901
2902 - You can add error-handling probes to a script, which are run if a
2903 script was stopped due to errors. In such a case, "end" probes are
2904 not run, but "error" ones are.
2905
2906 probe error { println ("oops, errors encountered; here's a report anyway")
2907 foreach (coin in mint) { println (coin) } }
2908
2909 - In a related twist, one may list probe points in order of preference,
2910 and mark any of them as "sufficient" beyond just "optional". Probe
2911 point sequence expansion stops if a sufficient-marked probe point has a hit.
2912 This is useful for probes on functions that may be in a module (CONFIG_FOO=m)
2913 or may have been compiled into the kernel (CONFIG_FOO=y), but we don't know
2914 which. Instead of
2915
2916 probe module("sd").function("sd_init_command") ? ,
2917 kernel.function("sd_init_command") ? { ... }
2918
2919 which might match neither, now one can write this:
2920
2921 probe module("sd").function("sd_init_command") ! , /* <-- note excl. mark */
2922 kernel.function("sd_init_command") { ... }
2923
2924 - New security model. To install a systemtap kernel module, a user
2925 must be one of the following: the root user; a member of the
2926 'stapdev' group; or a member of the 'stapusr' group. Members of the
2927 stapusr group can only use modules located in the
2928 /lib/modules/VERSION/systemtap directory (where VERSION is the
2929 output of "uname -r").
2930
2931 - .statement("...@file:line") probes now apply heuristics to allow an
2932 approximate match for the line number. This works similarly to gdb,
2933 where a breakpoint placed on an empty source line is automatically
2934 moved to the next statement. A silly bug that made many $target
2935 variables inaccessible to .statement() probes was also fixed.
2936
2937 - LKET has been retired. Please let us know on <[email protected]>
2938 if you have been a user of the tapset/tools, so we can help you find
2939 another way.
2940
2941 - New families of printing functions println() and printd() have been added.
2942 println() is like print() but adds a newline at the end;
2943 printd() is like a sequence of print()s, with a specified field delimiter.
2944
2945 * What's new since version 0.5.14?, 2007-07-03
2946
2947 - The way in which command line arguments for scripts are substituted has
2948 changed. Previously, $1 etc. would interpret the corresponding command
2949 line argument as an numeric literal, and @1 as a string literal. Now,
2950 the command line arguments are pasted uninterpreted wherever $1 etc.
2951 appears at the beginning of a token. @1 is similar, but is quoted as
2952 a string. This change does not modify old scripts, but has the effect
2953 of permitting substitution of arbitrary token sequences.
2954
2955 # This worked before, and still does:
2956 % stap -e 'probe timer.s($1) {}' 5
2957 # Now this also works:
2958 % stap -e 'probe syscall.$1 {log(@1)}' open
2959 # This won't crash, just signal a recursion error:
2960 % stap -e '$1' '$1'
2961 # As before, $1... is recognized only at the beginning of a token
2962 % stap -e 'probe begin {foo$1=5}'
2963
2964 * What's new since version 0.5.13?, 2007-03-26
2965
2966 - The way in which systemtap resolves function/inline probes has changed:
2967 .function(...) - now refers to all functions, inlined or not
2968 .inline(...) - is deprecated, use instead:
2969 .function(...).inline - filters function() to only inlined instances
2970 .function(...).call - filters function() to only non-inlined instances
2971 .function(...).return - as before, but now pairs best with .function().call
2972 .statement() is unchanged.
2973
2974 * What's new since version 0.5.12?, 2007-01-01
2975
2976 - When running in -p4 (compile-only) mode, the compiled .ko file name
2977 is printed on standard output.
2978
2979 - An array element with a null value such as zero or an empty string
2980 is now preserved, and will show up in a "foreach" loop or "in" test.
2981 To delete such an element, the scripts needs to use an explicit
2982 "delete array[idx]" statement rather than something like "array[idx]=0".
2983
2984 - The new "-P" option controls whether prologue searching heuristics
2985 will be activated for function probes. This was needed to get correct
2986 debugging information (dwarf location list) data for $target variables.
2987 Modern compilers (gcc 4.1+) tend not to need this heuristic, so it is
2988 no longer default. A new configure flag (--enable-prologues) restores
2989 it as a default setting, and is appropriate for older compilers (gcc 3.*).
2990
2991 - Each systemtap module prints a one-line message to the kernel informational
2992 log when it starts. This line identifies the translator version, base
2993 address of the probe module, a broken-down memory consumption estimate, and
2994 the total number of probes. This is meant as a debugging / auditing aid.
2995
2996 - Begin/end probes are run with interrupts enabled (but with
2997 preemption disabled). This will allow begin/end probes to be
2998 longer, to support generating longer reports.
2999
3000 - The numeric forms of kernel.statement() and kernel.function() probe points
3001 are now interpreted as relocatable values - treated as relative to the
3002 _stext symbol in that kernel binary. Since some modern kernel images
3003 are relocated to a different virtual address at startup, such addresses
3004 may shift up or down when actually inserted into a running kernel.
3005
3006 kernel.statement(0xdeadbeef): validated, interpreted relative to _stext,
3007 may map to 0xceadbeef at run time.
3008
3009 In order to specify unrelocated addresses, use the new ".absolute"
3010 probe point suffix for such numeric addresses. These are only
3011 allowed in guru mode, and provide access to no $target variables.
3012 They don't use debugging information at all, actually.
3013
3014 kernel.statement(0xfeedface).absolute: raw, unvalidated, guru mode only
3015
3016 * What's new since version 0.5.10?, 2006-10-19
3017
3018 - Offline processing of debugging information, enabling general
3019 cross-compilation of probe scripts to remote hosts, without
3020 requiring identical module/memory layout. This slows down
3021 compilation/translation somewhat.
3022
3023 - Kernel symbol table data is loaded by staprun at startup time
3024 rather than compiled into the module.
3025
3026 - Support the "limit" keyword for foreach iterations:
3027 foreach ([x,y] in ary limit 5) { ... }
3028 This implicitly exits after the fifth iteration. It also enables
3029 more efficient key/value sorting.
3030
3031 - Support the "maxactive" keyword for return probes:
3032 probe kernel.function("sdfsdf").maxactive(848) { ... }
3033 This allows up to 848 concurrently outstanding entries to
3034 the sdfsdf function before one returns. The default maxactive
3035 number is smaller, and can result in missed return probes.
3036
3037 - Support accessing of saved function arguments from within
3038 return probes. These values are saved by a synthesized
3039 function-entry probe.
3040
3041 - Add substantial version/architecture checking in compiled probes to
3042 assert correct installation of debugging information and correct
3043 execution on a compatible kernel.
3044
3045 - Add probe-time checking for sufficient free stack space when probe
3046 handlers are invoked, as a safety improvement.
3047
3048 - Add an optional numeric parameter for begin/end probe specifications,
3049 to order their execution.
3050 probe begin(10) { } /* comes after */ probe begin(-10) {}
3051
3052 - Add an optional array size declaration, which is handy for very small
3053 or very large ones.
3054 global little[5], big[20000]
3055
3056 - Include some example scripts along with the documentation.
3057
3058 - Change the start-time allocation of probe memory to avoid causing OOM
3059 situations, and to abort cleanly if free kernel memory is short.
3060
3061 - Automatically use the kernel DWARF unwinder, if present, for stack
3062 tracebacks.
3063
3064 - Many minor bug fixes, performance, tapset, and error message
3065 improvements.