NEWS

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