NEWS

   1 * What's new in version 0.7
   2
   3 - Stack backtraces for x86 and x86-64 are generated by a dwarf
   4   debuginfo-based unwinder based on the code from <jbeulich@novell.com>.
   5   This should give more accurate backtraces.
   6
   7 - A probe listing mode is available.
   8   % stap -l vm.*
   9   vm.brk
  10   vm.mmap
  11   vm.munmap
  12   vm.oom_kill
  13   vm.pagefault
  14   vm.write_shared
  15
  16 - More user-space probe types are added:
  17
  18   probe process(PID).clone { }
  19   probe process("PATH").clone { }
  20   probe process(PID).exec { }
  21   probe process("PATH").exec { }
  22   probe process(PID).death { }
  23   probe process("PATH").death { }
  24   probe process(PID).syscall { }
  25   probe process("PATH").syscall { }
  26   probe process(PID).syscall.return { }
  27   probe process("PATH").syscall.return { }
  28
  29 * What's new in version 0.6
  30
  31 - A copy of the systemtap tutorial and language reference guide
  32   are now included.
  33
  34 - There is a new format specifier, %m, for the printf family of
  35   functions.  It functions like %s, except that it does not stop when
  36   a nul ('\0') byte is encountered.  The number of bytes output is
  37   determined by the precision specifier.  The default precision is 1.
  38   For example:
  39
  40       printf ("%m", "My String") // prints one character: M
  41       printf ("%.5", myString)   // prints 5 bytes beginning at the start
  42                                  // of myString
  43
  44 - The %b format specifier for the printf family of functions has been enhanced
  45   as follows:
  46
  47   1) When the width and precision are both unspecified, the default is %8.8b.
  48   2) When only one of the width or precision is specified, the other defaults
  49      to the same value.  For example, %4b == %.4b == %4.4b
  50   3) Nul ('\0') bytes are used for field width padding.  For example,
  51
  52      printf ("%b", 0x1111deadbeef2222) // prints all eight bytes
  53      printf ("%4.2b", 0xdeadbeef)      // prints  \0\0\xbe\xef
  54
  55 - Dynamic width and precision are now supported for all printf family format
  56   specifiers.  For example:
  57
  58      four = 4
  59      two = 2
  60      printf ("%*.*b", four, two, 0xdeadbbeef) // prints  \0\0\xbe\xef
  61      printf ("%*d", four, two)                // prints  <space><space><space>2
  62
  63 - Preprocessor conditional expressions can now include wildcard style
  64   matches on kernel versions.
  65   %( kernel_vr != "*xen" %? foo %: bar %)
  66
  67 - Prototype support for user-space probing is showing some progress.
  68   No symbolic notations are supported yet (so no probing by function names,
  69   file names, process names, and no access to $context variables), but at
  70   least it's something:
  71
  72     probe process(PID).statement(ADDRESS).absolute { }
  73
  74   This will set a uprobe on the given process-id and given virtual address.
  75   The proble handler runs in kernel-space as usual, and can generally use
  76   existing tapset functions.
  77
  78 - Crash utility can retrieve systemtap's relay buffer from a kernel dump
  79   image by using staplog which is a crash extension module. To use this
  80   feature, type commands as below from crash(8)'s command line:
  81
  82     crash> extend staplog.so
  83     crash> help systemtaplog
  84
  85   Then, you can see more precise help message.
  86
  87 - You can share a relay buffer amoung several scripts and merge outputs from
  88   several scripts by using "-DRELAY_HOST" and "-DRELAY_GUEST" options.
  89   For example:
  90
  91     # run a host script
  92     % stap -ve 'probe begin{}' -o merged.out -DRELAY_HOST &
  93     # wait until starting the host.
  94     % stap -ve 'probe begin{print("hello ");exit()}' -DRELAY_GUEST
  95     % stap -ve 'probe begin{print("world\n");exit()}' -DRELAY_GUEST
  96
  97   Then, you'll see "hello world" in merged.out.
  98
  99 - You can add a conditional statement for each probe point or aliase, which
 100   is evaluated when the probe point is hit. If the condition is false, the
 101   whole probe body(including aliases) is skipped. For example:
 102
 103     global switch = 0;
 104     probe syscall.* if (switch) { ... }
 105     probe procfs.write {switch = strtol($value,10)} /* enable/disable ctrl */
 106
 107 - Systemtap will warn you if your script contains unused variables or
 108   functions.  This is helpful in case of misspelled variables.  If it
 109   doth protest too much, turn it off with "stap -w ...".
 110
 111 - You can add error-handling probes to a script, which are run if a
 112   script was stopped due to errors.  In such a case, "end" probes are
 113   not run, but "error" ones are.
 114
 115     probe error { println ("oops, errors encountered; here's a report anyway")
 116                   foreach (coin in mint) { println (coin) } }
 117
 118 - In a related twist, one may list probe points in order of preference,
 119   and mark any of them as "sufficient" beyond just "optional".  Probe
 120   point sequence expansion stops if a sufficient-marked probe point has a hit.
 121   This is useful for probes on functions that may be in a module (CONFIG_FOO=m)
 122   or may have been compiled into the kernel (CONFIG_FOO=y), but we don't know
 123   which.  Instead of
 124
 125     probe module("sd").function("sd_init_command") ? ,
 126           kernel.function("sd_init_command") ? { ... }
 127
 128   which might match neither, now one can write this:
 129
 130     probe module("sd").function("sd_init_command") ! , /* <-- note excl. mark */
 131           kernel.function("sd_init_command")  { ... }
 132
 133 - New security model.  To install a systemtap kernel module, a user
 134   must be one of the following: the root user; a member of the
 135   'stapdev' group; or a member of the 'stapusr' group.  Members of the
 136   stapusr group can only use modules located in the
 137   /lib/modules/VERSION/systemtap directory (where VERSION is the
 138   output of "uname -r").
 139
 140 - .statement("...@file:line") probes now apply heuristics to allow an
 141   approximate match for the line number.  This works similarly to gdb,
 142   where a breakpoint placed on an empty source line is automatically
 143   moved to the next statement.  A silly bug that made many $target
 144   variables inaccessible to .statement() probes was also fixed.
 145
 146 - LKET has been retired.  Please let us know on <systemtap@sourceware.org>
 147   if you have been a user of the tapset/tools, so we can help you find
 148   another way.
 149
 150 - New families of printing functions println() and printd() have been added.
 151   println() is like print() but adds a newline at the end;
 152   printd() is like a sequence of print()s, with a specified field delimiter.
 153
 154 * What's new since version 0.5.14?
 155
 156 - The way in which command line arguments for scripts are substituted has
 157   changed.  Previously, $1 etc. would interpret the corresponding command
 158   line argument as an numeric literal, and @1 as a string literal.  Now,
 159   the command line arguments are pasted uninterpreted wherever $1 etc.
 160   appears at the beginning of a token.  @1 is similar, but is quoted as
 161   a string.  This change does not modify old scripts, but has the effect
 162   of permitting substitution of arbitrary token sequences.
 163
 164   # This worked before, and still does:
 165   % stap -e 'probe timer.s($1) {}'        5
 166   # Now this also works:
 167   % stap -e 'probe syscall.$1 {log(@1)}'  open
 168   # This won't crash, just signal a recursion error:
 169   % stap -e '$1'                          '$1'
 170   # As before, $1... is recognized only at the beginning of a token
 171   % stap -e 'probe begin {foo$1=5}'
 172
 173 * What's new since version 0.5.13?
 174
 175 - The way in which systemtap resolves function/inline probes has changed:
 176    .function(...) - now refers to all functions, inlined or not
 177    .inline(...)   - is deprecated, use instead:
 178    .function(...).inline - filters function() to only inlined instances
 179    .function(...).call - filters function() to only non-inlined instances
 180    .function(...).return - as before, but now pairs best with .function().call
 181    .statement() is unchanged.
 182
 183 * What's new since version 0.5.12?
 184
 185 - When running in -p4 (compile-only) mode, the compiled .ko file name
 186   is printed on standard output.
 187
 188 - An array element with a null value such as zero or an empty string
 189   is now preserved, and will show up in a "foreach" loop or "in" test.
 190   To delete such an element, the scripts needs to use an explicit
 191   "delete array[idx]" statement rather than something like "array[idx]=0".
 192
 193 - The new "-P" option controls whether prologue searching heuristics
 194   will be activated for function probes.  This was needed to get correct
 195   debugging information (dwarf location list) data for $target variables.
 196   Modern compilers (gcc 4.1+) tend not to need this heuristic, so it is
 197   no longer default.  A new configure flag (--enable-prologues) restores
 198   it as a default setting, and is appropriate for older compilers (gcc 3.*).
 199
 200 - Each systemtap module prints a one-line message to the kernel informational
 201   log when it starts.  This line identifies the translator version, base
 202   address of the probe module, a broken-down memory consumption estimate, and
 203   the total number of probes.  This is meant as a debugging / auditing aid.
 204
 205 - Begin/end probes are run with interrupts enabled (but with
 206   preemption disabled).  This will allow begin/end probes to be
 207   longer, to support generating longer reports.
 208
 209 - The numeric forms of kernel.statement() and kernel.function() probe points
 210   are now interpreted as relocatable values - treated as relative to the
 211   _stext symbol in that kernel binary.  Since some modern kernel images
 212   are relocated to a different virtual address at startup, such addresses
 213   may shift up or down when actually inserted into a running kernel.
 214
 215      kernel.statement(0xdeadbeef): validated, interpreted relative to _stext,
 216                                    may map to 0xceadbeef at run time.
 217
 218   In order to specify unrelocated addresses, use the new ".absolute"
 219   probe point suffix for such numeric addresses.  These are only
 220   allowed in guru mode, and provide access to no $target variables.
 221   They don't use debugging information at all, actually.
 222
 223      kernel.statement(0xfeedface).absolute: raw, unvalidated, guru mode only
 224
 225 * What's new since version 0.5.10?
 226
 227 - Offline processing of debugging information, enabling general
 228   cross-compilation of probe scripts to remote hosts, without
 229   requiring identical module/memory layout.  This slows down
 230   compilation/translation somewhat.
 231
 232 - Kernel symbol table data is loaded by staprun at startup time
 233   rather than compiled into the module.
 234
 235 - Support the "limit" keyword for foreach iterations:
 236     foreach ([x,y] in ary limit 5) { ... }
 237   This implicitly exits after the fifth iteration.  It also enables
 238   more efficient key/value sorting.
 239
 240 - Support the "maxactive" keyword for return probes:
 241     probe kernel.function("sdfsdf").maxactive(848) { ... }
 242   This allows up to 848 concurrently outstanding entries to
 243   the sdfsdf function before one returns.  The default maxactive
 244   number is smaller, and can result in missed return probes.
 245
 246 - Support accessing of saved function arguments from within
 247   return probes.  These values are saved by a synthesized
 248   function-entry probe.
 249
 250 - Add substantial version/architecture checking in compiled probes to
 251   assert correct installation of debugging information and correct
 252   execution on a compatible kernel.
 253
 254 - Add probe-time checking for sufficient free stack space when probe
 255   handlers are invoked, as a safety improvement.
 256
 257 - Add an optional numeric parameter for begin/end probe specifications,
 258   to order their execution.
 259      probe begin(10) { } /* comes after */ probe begin(-10) {}
 260
 261 - Add an optional array size declaration, which is handy for very small
 262   or very large ones.
 263      global little[5], big[20000]
 264
 265 - Include some example scripts along with the documentation.
 266
 267 - Change the start-time allocation of probe memory to avoid causing OOM
 268   situations, and to abort cleanly if free kernel memory is short.
 269
 270 - Automatically use the kernel DWARF unwinder, if present, for stack
 271   tracebacks.
 272
 273 - Many minor bug fixes, performance, tapset, and error message
 274   improvements.