NEWS

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