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