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