aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/kprobes.txt
diff options
context:
space:
mode:
authorJim Keniston <jkenisto@us.ibm.com>2006-02-14 16:53:06 -0500
committerLinus Torvalds <torvalds@g5.osdl.org>2006-02-14 19:09:34 -0500
commit8861da31e3b3e3df7b05e7b157230de3d486e53b (patch)
tree15b8874fbad4dc1170f64cd8a5be7df4eced9686 /Documentation/kprobes.txt
parent61b9a26ae6d308ade964db122e0e89299586422c (diff)
[PATCH] kprobes: Update Documentation/kprobes.txt
Update Documentation/kprobes.txt to reflect Kprobes enhancements and other recent developments. Acked-by: Ananth Mavinakayanahalli <mananth@in.ibm.com> Signed-off-by: Jim Keniston <jkenisto@us.ibm.com> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'Documentation/kprobes.txt')
-rw-r--r--Documentation/kprobes.txt81
1 files changed, 42 insertions, 39 deletions
diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt
index 0ea5a0c6e827..2c3b1eae4280 100644
--- a/Documentation/kprobes.txt
+++ b/Documentation/kprobes.txt
@@ -136,17 +136,20 @@ Kprobes, jprobes, and return probes are implemented on the following
136architectures: 136architectures:
137 137
138- i386 138- i386
139- x86_64 (AMD-64, E64MT) 139- x86_64 (AMD-64, EM64T)
140- ppc64 140- ppc64
141- ia64 (Support for probes on certain instruction types is still in progress.) 141- ia64 (Does not support probes on instruction slot1.)
142- sparc64 (Return probes not yet implemented.) 142- sparc64 (Return probes not yet implemented.)
143 143
1443. Configuring Kprobes 1443. Configuring Kprobes
145 145
146When configuring the kernel using make menuconfig/xconfig/oldconfig, 146When configuring the kernel using make menuconfig/xconfig/oldconfig,
147ensure that CONFIG_KPROBES is set to "y". Under "Kernel hacking", 147ensure that CONFIG_KPROBES is set to "y". Under "Instrumentation
148look for "Kprobes". You may have to enable "Kernel debugging" 148Support", look for "Kprobes".
149(CONFIG_DEBUG_KERNEL) before you can enable Kprobes. 149
150So that you can load and unload Kprobes-based instrumentation modules,
151make sure "Loadable module support" (CONFIG_MODULES) and "Module
152unloading" (CONFIG_MODULE_UNLOAD) are set to "y".
150 153
151You may also want to ensure that CONFIG_KALLSYMS and perhaps even 154You may also want to ensure that CONFIG_KALLSYMS and perhaps even
152CONFIG_KALLSYMS_ALL are set to "y", since kallsyms_lookup_name() 155CONFIG_KALLSYMS_ALL are set to "y", since kallsyms_lookup_name()
@@ -262,18 +265,18 @@ at any time after the probe has been registered.
262 265
2635. Kprobes Features and Limitations 2665. Kprobes Features and Limitations
264 267
265As of Linux v2.6.12, Kprobes allows multiple probes at the same 268Kprobes allows multiple probes at the same address. Currently,
266address. Currently, however, there cannot be multiple jprobes on 269however, there cannot be multiple jprobes on the same function at
267the same function at the same time. 270the same time.
268 271
269In general, you can install a probe anywhere in the kernel. 272In general, you can install a probe anywhere in the kernel.
270In particular, you can probe interrupt handlers. Known exceptions 273In particular, you can probe interrupt handlers. Known exceptions
271are discussed in this section. 274are discussed in this section.
272 275
273For obvious reasons, it's a bad idea to install a probe in 276The register_*probe functions will return -EINVAL if you attempt
274the code that implements Kprobes (mostly kernel/kprobes.c and 277to install a probe in the code that implements Kprobes (mostly
275arch/*/kernel/kprobes.c). A patch in the v2.6.13 timeframe instructs 278kernel/kprobes.c and arch/*/kernel/kprobes.c, but also functions such
276Kprobes to reject such requests. 279as do_page_fault and notifier_call_chain).
277 280
278If you install a probe in an inline-able function, Kprobes makes 281If you install a probe in an inline-able function, Kprobes makes
279no attempt to chase down all inline instances of the function and 282no attempt to chase down all inline instances of the function and
@@ -290,18 +293,14 @@ from the accidental ones. Don't drink and probe.
290 293
291Kprobes makes no attempt to prevent probe handlers from stepping on 294Kprobes makes no attempt to prevent probe handlers from stepping on
292each other -- e.g., probing printk() and then calling printk() from a 295each other -- e.g., probing printk() and then calling printk() from a
293probe handler. As of Linux v2.6.12, if a probe handler hits a probe, 296probe handler. If a probe handler hits a probe, that second probe's
294that second probe's handlers won't be run in that instance. 297handlers won't be run in that instance, and the kprobe.nmissed member
295 298of the second probe will be incremented.
296In Linux v2.6.12 and previous versions, Kprobes' data structures are 299
297protected by a single lock that is held during probe registration and 300As of Linux v2.6.15-rc1, multiple handlers (or multiple instances of
298unregistration and while handlers are run. Thus, no two handlers 301the same handler) may run concurrently on different CPUs.
299can run simultaneously. To improve scalability on SMP systems, 302
300this restriction will probably be removed soon, in which case 303Kprobes does not use mutexes or allocate memory except during
301multiple handlers (or multiple instances of the same handler) may
302run concurrently on different CPUs. Code your handlers accordingly.
303
304Kprobes does not use semaphores or allocate memory except during
305registration and unregistration. 304registration and unregistration.
306 305
307Probe handlers are run with preemption disabled. Depending on the 306Probe handlers are run with preemption disabled. Depending on the
@@ -316,11 +315,18 @@ address instead of the real return address for kretprobed functions.
316(As far as we can tell, __builtin_return_address() is used only 315(As far as we can tell, __builtin_return_address() is used only
317for instrumentation and error reporting.) 316for instrumentation and error reporting.)
318 317
319If the number of times a function is called does not match the 318If the number of times a function is called does not match the number
320number of times it returns, registering a return probe on that 319of times it returns, registering a return probe on that function may
321function may produce undesirable results. We have the do_exit() 320produce undesirable results. We have the do_exit() case covered.
322and do_execve() cases covered. do_fork() is not an issue. We're 321do_execve() and do_fork() are not an issue. We're unaware of other
323unaware of other specific cases where this could be a problem. 322specific cases where this could be a problem.
323
324If, upon entry to or exit from a function, the CPU is running on
325a stack other than that of the current task, registering a return
326probe on that function may produce undesirable results. For this
327reason, Kprobes doesn't support return probes (or kprobes or jprobes)
328on the x86_64 version of __switch_to(); the registration functions
329return -EINVAL.
324 330
3256. Probe Overhead 3316. Probe Overhead
326 332
@@ -347,14 +353,12 @@ k = 0.77 usec; j = 1.31; r = 1.26; kr = 1.45; jr = 1.99
347 353
3487. TODO 3547. TODO
349 355
350a. SystemTap (http://sourceware.org/systemtap): Work in progress 356a. SystemTap (http://sourceware.org/systemtap): Provides a simplified
351to provide a simplified programming interface for probe-based 357programming interface for probe-based instrumentation. Try it out.
352instrumentation. 358b. Kernel return probes for sparc64.
353b. Improved SMP scalability: Currently, work is in progress to handle 359c. Support for other architectures.
354multiple kprobes in parallel. 360d. User-space probes.
355c. Kernel return probes for sparc64. 361e. Watchpoint probes (which fire on data references).
356d. Support for other architectures.
357e. User-space probes.
358 362
3598. Kprobes Example 3638. Kprobes Example
360 364
@@ -411,8 +415,7 @@ int init_module(void)
411 printk("Couldn't find %s to plant kprobe\n", "do_fork"); 415 printk("Couldn't find %s to plant kprobe\n", "do_fork");
412 return -1; 416 return -1;
413 } 417 }
414 ret = register_kprobe(&kp); 418 if ((ret = register_kprobe(&kp) < 0)) {
415 if (ret < 0) {
416 printk("register_kprobe failed, returned %d\n", ret); 419 printk("register_kprobe failed, returned %d\n", ret);
417 return -1; 420 return -1;
418 } 421 }