NEWS

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