blob: da5404ab75691c58e3d69c89ea1a3f8ba1fd993b [file] [log] [blame]
Jim Kenistond27a4dd2005-08-04 12:53:35 -07001Title : Kernel Probes (Kprobes)
2Authors : Jim Keniston <jkenisto@us.ibm.com>
3 : Prasanna S Panchamukhi <prasanna@in.ibm.com>
4
5CONTENTS
6
71. Concepts: Kprobes, Jprobes, Return Probes
82. Architectures Supported
93. Configuring Kprobes
104. API Reference
115. Kprobes Features and Limitations
126. Probe Overhead
137. TODO
148. Kprobes Example
159. Jprobes Example
1610. Kretprobes Example
Ananth N Mavinakayanahallibf8f6e52007-05-08 00:34:16 -070017Appendix A: The kprobes debugfs interface
Jim Kenistond27a4dd2005-08-04 12:53:35 -070018
191. Concepts: Kprobes, Jprobes, Return Probes
20
21Kprobes enables you to dynamically break into any kernel routine and
22collect debugging and performance information non-disruptively. You
23can trap at almost any kernel code address, specifying a handler
24routine to be invoked when the breakpoint is hit.
25
26There are currently three types of probes: kprobes, jprobes, and
27kretprobes (also called return probes). A kprobe can be inserted
28on virtually any instruction in the kernel. A jprobe is inserted at
29the entry to a kernel function, and provides convenient access to the
30function's arguments. A return probe fires when a specified function
31returns.
32
33In the typical case, Kprobes-based instrumentation is packaged as
34a kernel module. The module's init function installs ("registers")
35one or more probes, and the exit function unregisters them. A
36registration function such as register_kprobe() specifies where
37the probe is to be inserted and what handler is to be called when
38the probe is hit.
39
40The next three subsections explain how the different types of
41probes work. They explain certain things that you'll need to
42know in order to make the best use of Kprobes -- e.g., the
43difference between a pre_handler and a post_handler, and how
44to use the maxactive and nmissed fields of a kretprobe. But
45if you're in a hurry to start using Kprobes, you can skip ahead
46to section 2.
47
481.1 How Does a Kprobe Work?
49
50When a kprobe is registered, Kprobes makes a copy of the probed
51instruction and replaces the first byte(s) of the probed instruction
52with a breakpoint instruction (e.g., int3 on i386 and x86_64).
53
54When a CPU hits the breakpoint instruction, a trap occurs, the CPU's
55registers are saved, and control passes to Kprobes via the
56notifier_call_chain mechanism. Kprobes executes the "pre_handler"
57associated with the kprobe, passing the handler the addresses of the
58kprobe struct and the saved registers.
59
60Next, Kprobes single-steps its copy of the probed instruction.
61(It would be simpler to single-step the actual instruction in place,
62but then Kprobes would have to temporarily remove the breakpoint
63instruction. This would open a small time window when another CPU
64could sail right past the probepoint.)
65
66After the instruction is single-stepped, Kprobes executes the
67"post_handler," if any, that is associated with the kprobe.
68Execution then continues with the instruction following the probepoint.
69
701.2 How Does a Jprobe Work?
71
72A jprobe is implemented using a kprobe that is placed on a function's
73entry point. It employs a simple mirroring principle to allow
74seamless access to the probed function's arguments. The jprobe
75handler routine should have the same signature (arg list and return
76type) as the function being probed, and must always end by calling
77the Kprobes function jprobe_return().
78
79Here's how it works. When the probe is hit, Kprobes makes a copy of
80the saved registers and a generous portion of the stack (see below).
81Kprobes then points the saved instruction pointer at the jprobe's
82handler routine, and returns from the trap. As a result, control
83passes to the handler, which is presented with the same register and
84stack contents as the probed function. When it is done, the handler
85calls jprobe_return(), which traps again to restore the original stack
86contents and processor state and switch to the probed function.
87
88By convention, the callee owns its arguments, so gcc may produce code
89that unexpectedly modifies that portion of the stack. This is why
90Kprobes saves a copy of the stack and restores it after the jprobe
91handler has run. Up to MAX_STACK_SIZE bytes are copied -- e.g.,
9264 bytes on i386.
93
94Note that the probed function's args may be passed on the stack
95or in registers (e.g., for x86_64 or for an i386 fastcall function).
96The jprobe will work in either case, so long as the handler's
97prototype matches that of the probed function.
98
991.3 How Does a Return Probe Work?
100
101When you call register_kretprobe(), Kprobes establishes a kprobe at
102the entry to the function. When the probed function is called and this
103probe is hit, Kprobes saves a copy of the return address, and replaces
104the return address with the address of a "trampoline." The trampoline
105is an arbitrary piece of code -- typically just a nop instruction.
106At boot time, Kprobes registers a kprobe at the trampoline.
107
108When the probed function executes its return instruction, control
109passes to the trampoline and that probe is hit. Kprobes' trampoline
110handler calls the user-specified handler associated with the kretprobe,
111then sets the saved instruction pointer to the saved return address,
112and that's where execution resumes upon return from the trap.
113
114While the probed function is executing, its return address is
115stored in an object of type kretprobe_instance. Before calling
116register_kretprobe(), the user sets the maxactive field of the
117kretprobe struct to specify how many instances of the specified
118function can be probed simultaneously. register_kretprobe()
119pre-allocates the indicated number of kretprobe_instance objects.
120
121For example, if the function is non-recursive and is called with a
122spinlock held, maxactive = 1 should be enough. If the function is
123non-recursive and can never relinquish the CPU (e.g., via a semaphore
124or preemption), NR_CPUS should be enough. If maxactive <= 0, it is
125set to a default value. If CONFIG_PREEMPT is enabled, the default
126is max(10, 2*NR_CPUS). Otherwise, the default is NR_CPUS.
127
128It's not a disaster if you set maxactive too low; you'll just miss
129some probes. In the kretprobe struct, the nmissed field is set to
130zero when the return probe is registered, and is incremented every
131time the probed function is entered but there is no kretprobe_instance
132object available for establishing the return probe.
133
1342. Architectures Supported
135
136Kprobes, jprobes, and return probes are implemented on the following
137architectures:
138
139- i386
Jim Keniston8861da32006-02-14 13:53:06 -0800140- x86_64 (AMD-64, EM64T)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700141- ppc64
Jim Keniston8861da32006-02-14 13:53:06 -0800142- ia64 (Does not support probes on instruction slot1.)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700143- sparc64 (Return probes not yet implemented.)
144
1453. Configuring Kprobes
146
147When configuring the kernel using make menuconfig/xconfig/oldconfig,
Jim Keniston8861da32006-02-14 13:53:06 -0800148ensure that CONFIG_KPROBES is set to "y". Under "Instrumentation
149Support", look for "Kprobes".
150
151So that you can load and unload Kprobes-based instrumentation modules,
152make sure "Loadable module support" (CONFIG_MODULES) and "Module
153unloading" (CONFIG_MODULE_UNLOAD) are set to "y".
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700154
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700155Also make sure that CONFIG_KALLSYMS and perhaps even CONFIG_KALLSYMS_ALL
156are set to "y", since kallsyms_lookup_name() is used by the in-kernel
157kprobe address resolution code.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700158
159If you need to insert a probe in the middle of a function, you may find
160it useful to "Compile the kernel with debug info" (CONFIG_DEBUG_INFO),
161so you can use "objdump -d -l vmlinux" to see the source-to-object
162code mapping.
163
1644. API Reference
165
166The Kprobes API includes a "register" function and an "unregister"
167function for each type of probe. Here are terse, mini-man-page
168specifications for these functions and the associated probe handlers
169that you'll write. See the latter half of this document for examples.
170
1714.1 register_kprobe
172
173#include <linux/kprobes.h>
174int register_kprobe(struct kprobe *kp);
175
176Sets a breakpoint at the address kp->addr. When the breakpoint is
177hit, Kprobes calls kp->pre_handler. After the probed instruction
178is single-stepped, Kprobe calls kp->post_handler. If a fault
179occurs during execution of kp->pre_handler or kp->post_handler,
180or during single-stepping of the probed instruction, Kprobes calls
181kp->fault_handler. Any or all handlers can be NULL.
182
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700183NOTE:
1841. With the introduction of the "symbol_name" field to struct kprobe,
185the probepoint address resolution will now be taken care of by the kernel.
186The following will now work:
187
188 kp.symbol_name = "symbol_name";
189
190(64-bit powerpc intricacies such as function descriptors are handled
191transparently)
192
1932. Use the "offset" field of struct kprobe if the offset into the symbol
194to install a probepoint is known. This field is used to calculate the
195probepoint.
196
1973. Specify either the kprobe "symbol_name" OR the "addr". If both are
198specified, kprobe registration will fail with -EINVAL.
199
2004. With CISC architectures (such as i386 and x86_64), the kprobes code
201does not validate if the kprobe.addr is at an instruction boundary.
202Use "offset" with caution.
203
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700204register_kprobe() returns 0 on success, or a negative errno otherwise.
205
206User's pre-handler (kp->pre_handler):
207#include <linux/kprobes.h>
208#include <linux/ptrace.h>
209int pre_handler(struct kprobe *p, struct pt_regs *regs);
210
211Called with p pointing to the kprobe associated with the breakpoint,
212and regs pointing to the struct containing the registers saved when
213the breakpoint was hit. Return 0 here unless you're a Kprobes geek.
214
215User's post-handler (kp->post_handler):
216#include <linux/kprobes.h>
217#include <linux/ptrace.h>
218void post_handler(struct kprobe *p, struct pt_regs *regs,
219 unsigned long flags);
220
221p and regs are as described for the pre_handler. flags always seems
222to be zero.
223
224User's fault-handler (kp->fault_handler):
225#include <linux/kprobes.h>
226#include <linux/ptrace.h>
227int fault_handler(struct kprobe *p, struct pt_regs *regs, int trapnr);
228
229p and regs are as described for the pre_handler. trapnr is the
230architecture-specific trap number associated with the fault (e.g.,
231on i386, 13 for a general protection fault or 14 for a page fault).
232Returns 1 if it successfully handled the exception.
233
2344.2 register_jprobe
235
236#include <linux/kprobes.h>
237int register_jprobe(struct jprobe *jp)
238
239Sets a breakpoint at the address jp->kp.addr, which must be the address
240of the first instruction of a function. When the breakpoint is hit,
241Kprobes runs the handler whose address is jp->entry.
242
243The handler should have the same arg list and return type as the probed
244function; and just before it returns, it must call jprobe_return().
245(The handler never actually returns, since jprobe_return() returns
246control to Kprobes.) If the probed function is declared asmlinkage,
247fastcall, or anything else that affects how args are passed, the
248handler's declaration must match.
249
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700250NOTE: A macro JPROBE_ENTRY is provided to handle architecture-specific
251aliasing of jp->entry. In the interest of portability, it is advised
252to use:
253
254 jp->entry = JPROBE_ENTRY(handler);
255
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700256register_jprobe() returns 0 on success, or a negative errno otherwise.
257
2584.3 register_kretprobe
259
260#include <linux/kprobes.h>
261int register_kretprobe(struct kretprobe *rp);
262
263Establishes a return probe for the function whose address is
264rp->kp.addr. When that function returns, Kprobes calls rp->handler.
265You must set rp->maxactive appropriately before you call
266register_kretprobe(); see "How Does a Return Probe Work?" for details.
267
268register_kretprobe() returns 0 on success, or a negative errno
269otherwise.
270
271User's return-probe handler (rp->handler):
272#include <linux/kprobes.h>
273#include <linux/ptrace.h>
274int kretprobe_handler(struct kretprobe_instance *ri, struct pt_regs *regs);
275
276regs is as described for kprobe.pre_handler. ri points to the
277kretprobe_instance object, of which the following fields may be
278of interest:
279- ret_addr: the return address
280- rp: points to the corresponding kretprobe object
281- task: points to the corresponding task struct
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700282
283The regs_return_value(regs) macro provides a simple abstraction to
284extract the return value from the appropriate register as defined by
285the architecture's ABI.
286
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700287The handler's return value is currently ignored.
288
2894.4 unregister_*probe
290
291#include <linux/kprobes.h>
292void unregister_kprobe(struct kprobe *kp);
293void unregister_jprobe(struct jprobe *jp);
294void unregister_kretprobe(struct kretprobe *rp);
295
296Removes the specified probe. The unregister function can be called
297at any time after the probe has been registered.
298
2995. Kprobes Features and Limitations
300
Jim Keniston8861da32006-02-14 13:53:06 -0800301Kprobes allows multiple probes at the same address. Currently,
302however, there cannot be multiple jprobes on the same function at
303the same time.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700304
305In general, you can install a probe anywhere in the kernel.
306In particular, you can probe interrupt handlers. Known exceptions
307are discussed in this section.
308
Jim Keniston8861da32006-02-14 13:53:06 -0800309The register_*probe functions will return -EINVAL if you attempt
310to install a probe in the code that implements Kprobes (mostly
311kernel/kprobes.c and arch/*/kernel/kprobes.c, but also functions such
312as do_page_fault and notifier_call_chain).
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700313
314If you install a probe in an inline-able function, Kprobes makes
315no attempt to chase down all inline instances of the function and
316install probes there. gcc may inline a function without being asked,
317so keep this in mind if you're not seeing the probe hits you expect.
318
319A probe handler can modify the environment of the probed function
320-- e.g., by modifying kernel data structures, or by modifying the
321contents of the pt_regs struct (which are restored to the registers
322upon return from the breakpoint). So Kprobes can be used, for example,
323to install a bug fix or to inject faults for testing. Kprobes, of
324course, has no way to distinguish the deliberately injected faults
325from the accidental ones. Don't drink and probe.
326
327Kprobes makes no attempt to prevent probe handlers from stepping on
328each other -- e.g., probing printk() and then calling printk() from a
Jim Keniston8861da32006-02-14 13:53:06 -0800329probe handler. If a probe handler hits a probe, that second probe's
330handlers won't be run in that instance, and the kprobe.nmissed member
331of the second probe will be incremented.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700332
Jim Keniston8861da32006-02-14 13:53:06 -0800333As of Linux v2.6.15-rc1, multiple handlers (or multiple instances of
334the same handler) may run concurrently on different CPUs.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700335
Jim Keniston8861da32006-02-14 13:53:06 -0800336Kprobes does not use mutexes or allocate memory except during
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700337registration and unregistration.
338
339Probe handlers are run with preemption disabled. Depending on the
340architecture, handlers may also run with interrupts disabled. In any
341case, your handler should not yield the CPU (e.g., by attempting to
342acquire a semaphore).
343
344Since a return probe is implemented by replacing the return
345address with the trampoline's address, stack backtraces and calls
346to __builtin_return_address() will typically yield the trampoline's
347address instead of the real return address for kretprobed functions.
348(As far as we can tell, __builtin_return_address() is used only
349for instrumentation and error reporting.)
350
Jim Keniston8861da32006-02-14 13:53:06 -0800351If the number of times a function is called does not match the number
352of times it returns, registering a return probe on that function may
Ananth N Mavinakayanahallibf8f6e52007-05-08 00:34:16 -0700353produce undesirable results. In such a case, a line:
354kretprobe BUG!: Processing kretprobe d000000000041aa8 @ c00000000004f48c
355gets printed. With this information, one will be able to correlate the
356exact instance of the kretprobe that caused the problem. We have the
357do_exit() case covered. do_execve() and do_fork() are not an issue.
358We're unaware of other specific cases where this could be a problem.
Jim Keniston8861da32006-02-14 13:53:06 -0800359
360If, upon entry to or exit from a function, the CPU is running on
361a stack other than that of the current task, registering a return
362probe on that function may produce undesirable results. For this
363reason, Kprobes doesn't support return probes (or kprobes or jprobes)
364on the x86_64 version of __switch_to(); the registration functions
365return -EINVAL.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700366
3676. Probe Overhead
368
369On a typical CPU in use in 2005, a kprobe hit takes 0.5 to 1.0
370microseconds to process. Specifically, a benchmark that hits the same
371probepoint repeatedly, firing a simple handler each time, reports 1-2
372million hits per second, depending on the architecture. A jprobe or
373return-probe hit typically takes 50-75% longer than a kprobe hit.
374When you have a return probe set on a function, adding a kprobe at
375the entry to that function adds essentially no overhead.
376
377Here are sample overhead figures (in usec) for different architectures.
378k = kprobe; j = jprobe; r = return probe; kr = kprobe + return probe
379on same function; jr = jprobe + return probe on same function
380
381i386: Intel Pentium M, 1495 MHz, 2957.31 bogomips
382k = 0.57 usec; j = 1.00; r = 0.92; kr = 0.99; jr = 1.40
383
384x86_64: AMD Opteron 246, 1994 MHz, 3971.48 bogomips
385k = 0.49 usec; j = 0.76; r = 0.80; kr = 0.82; jr = 1.07
386
387ppc64: POWER5 (gr), 1656 MHz (SMT disabled, 1 virtual CPU per physical CPU)
388k = 0.77 usec; j = 1.31; r = 1.26; kr = 1.45; jr = 1.99
389
3907. TODO
391
Jim Keniston8861da32006-02-14 13:53:06 -0800392a. SystemTap (http://sourceware.org/systemtap): Provides a simplified
393programming interface for probe-based instrumentation. Try it out.
394b. Kernel return probes for sparc64.
395c. Support for other architectures.
396d. User-space probes.
397e. Watchpoint probes (which fire on data references).
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700398
3998. Kprobes Example
400
401Here's a sample kernel module showing the use of kprobes to dump a
402stack trace and selected i386 registers when do_fork() is called.
403----- cut here -----
404/*kprobe_example.c*/
405#include <linux/kernel.h>
406#include <linux/module.h>
407#include <linux/kprobes.h>
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700408#include <linux/sched.h>
409
410/*For each probe you need to allocate a kprobe structure*/
411static struct kprobe kp;
412
413/*kprobe pre_handler: called just before the probed instruction is executed*/
414int handler_pre(struct kprobe *p, struct pt_regs *regs)
415{
416 printk("pre_handler: p->addr=0x%p, eip=%lx, eflags=0x%lx\n",
417 p->addr, regs->eip, regs->eflags);
418 dump_stack();
419 return 0;
420}
421
422/*kprobe post_handler: called after the probed instruction is executed*/
423void handler_post(struct kprobe *p, struct pt_regs *regs, unsigned long flags)
424{
425 printk("post_handler: p->addr=0x%p, eflags=0x%lx\n",
426 p->addr, regs->eflags);
427}
428
429/* fault_handler: this is called if an exception is generated for any
430 * instruction within the pre- or post-handler, or when Kprobes
431 * single-steps the probed instruction.
432 */
433int handler_fault(struct kprobe *p, struct pt_regs *regs, int trapnr)
434{
435 printk("fault_handler: p->addr=0x%p, trap #%dn",
436 p->addr, trapnr);
437 /* Return 0 because we don't handle the fault. */
438 return 0;
439}
440
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700441static int __init kprobe_init(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700442{
443 int ret;
444 kp.pre_handler = handler_pre;
445 kp.post_handler = handler_post;
446 kp.fault_handler = handler_fault;
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700447 kp.symbol_name = "do_fork";
448
Alexey Dobriyan565762f2006-11-16 01:19:28 -0800449 ret = register_kprobe(&kp);
450 if (ret < 0) {
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700451 printk("register_kprobe failed, returned %d\n", ret);
Alexey Dobriyan565762f2006-11-16 01:19:28 -0800452 return ret;
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700453 }
454 printk("kprobe registered\n");
455 return 0;
456}
457
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700458static void __exit kprobe_exit(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700459{
460 unregister_kprobe(&kp);
461 printk("kprobe unregistered\n");
462}
463
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700464module_init(kprobe_init)
465module_exit(kprobe_exit)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700466MODULE_LICENSE("GPL");
467----- cut here -----
468
469You can build the kernel module, kprobe-example.ko, using the following
470Makefile:
471----- cut here -----
472obj-m := kprobe-example.o
473KDIR := /lib/modules/$(shell uname -r)/build
474PWD := $(shell pwd)
475default:
476 $(MAKE) -C $(KDIR) SUBDIRS=$(PWD) modules
477clean:
478 rm -f *.mod.c *.ko *.o
479----- cut here -----
480
481$ make
482$ su -
483...
484# insmod kprobe-example.ko
485
486You will see the trace data in /var/log/messages and on the console
487whenever do_fork() is invoked to create a new process.
488
4899. Jprobes Example
490
491Here's a sample kernel module showing the use of jprobes to dump
492the arguments of do_fork().
493----- cut here -----
494/*jprobe-example.c */
495#include <linux/kernel.h>
496#include <linux/module.h>
497#include <linux/fs.h>
498#include <linux/uio.h>
499#include <linux/kprobes.h>
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700500
501/*
502 * Jumper probe for do_fork.
503 * Mirror principle enables access to arguments of the probed routine
504 * from the probe handler.
505 */
506
507/* Proxy routine having the same arguments as actual do_fork() routine */
508long jdo_fork(unsigned long clone_flags, unsigned long stack_start,
509 struct pt_regs *regs, unsigned long stack_size,
510 int __user * parent_tidptr, int __user * child_tidptr)
511{
512 printk("jprobe: clone_flags=0x%lx, stack_size=0x%lx, regs=0x%p\n",
513 clone_flags, stack_size, regs);
514 /* Always end with a call to jprobe_return(). */
515 jprobe_return();
516 /*NOTREACHED*/
517 return 0;
518}
519
520static struct jprobe my_jprobe = {
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700521 .entry = JPROBE_ENTRY(jdo_fork)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700522};
523
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700524static int __init jprobe_init(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700525{
526 int ret;
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700527 my_jprobe.kp.symbol_name = "do_fork";
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700528
529 if ((ret = register_jprobe(&my_jprobe)) <0) {
530 printk("register_jprobe failed, returned %d\n", ret);
531 return -1;
532 }
533 printk("Planted jprobe at %p, handler addr %p\n",
534 my_jprobe.kp.addr, my_jprobe.entry);
535 return 0;
536}
537
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700538static void __exit jprobe_exit(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700539{
540 unregister_jprobe(&my_jprobe);
541 printk("jprobe unregistered\n");
542}
543
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700544module_init(jprobe_init)
545module_exit(jprobe_exit)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700546MODULE_LICENSE("GPL");
547----- cut here -----
548
549Build and insert the kernel module as shown in the above kprobe
550example. You will see the trace data in /var/log/messages and on
551the console whenever do_fork() is invoked to create a new process.
552(Some messages may be suppressed if syslogd is configured to
553eliminate duplicate messages.)
554
55510. Kretprobes Example
556
557Here's a sample kernel module showing the use of return probes to
558report failed calls to sys_open().
559----- cut here -----
560/*kretprobe-example.c*/
561#include <linux/kernel.h>
562#include <linux/module.h>
563#include <linux/kprobes.h>
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700564
565static const char *probed_func = "sys_open";
566
567/* Return-probe handler: If the probed function fails, log the return value. */
568static int ret_handler(struct kretprobe_instance *ri, struct pt_regs *regs)
569{
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700570 int retval = regs_return_value(regs);
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700571 if (retval < 0) {
572 printk("%s returns %d\n", probed_func, retval);
573 }
574 return 0;
575}
576
577static struct kretprobe my_kretprobe = {
578 .handler = ret_handler,
579 /* Probe up to 20 instances concurrently. */
580 .maxactive = 20
581};
582
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700583static int __init kretprobe_init(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700584{
585 int ret;
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700586 my_kretprobe.kp.symbol_name = (char *)probed_func;
587
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700588 if ((ret = register_kretprobe(&my_kretprobe)) < 0) {
589 printk("register_kretprobe failed, returned %d\n", ret);
590 return -1;
591 }
592 printk("Planted return probe at %p\n", my_kretprobe.kp.addr);
593 return 0;
594}
595
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700596static void __exit kretprobe_exit(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700597{
598 unregister_kretprobe(&my_kretprobe);
599 printk("kretprobe unregistered\n");
600 /* nmissed > 0 suggests that maxactive was set too low. */
601 printk("Missed probing %d instances of %s\n",
602 my_kretprobe.nmissed, probed_func);
603}
604
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700605module_init(kretprobe_init)
606module_exit(kretprobe_exit)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700607MODULE_LICENSE("GPL");
608----- cut here -----
609
610Build and insert the kernel module as shown in the above kprobe
611example. You will see the trace data in /var/log/messages and on the
612console whenever sys_open() returns a negative value. (Some messages
613may be suppressed if syslogd is configured to eliminate duplicate
614messages.)
615
616For additional information on Kprobes, refer to the following URLs:
617http://www-106.ibm.com/developerworks/library/l-kprobes.html?ca=dgr-lnxw42Kprobe
618http://www.redhat.com/magazine/005mar05/features/kprobes/
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700619http://www-users.cs.umn.edu/~boutcher/kprobes/
620http://www.linuxsymposium.org/2006/linuxsymposium_procv2.pdf (pages 101-115)
Ananth N Mavinakayanahallibf8f6e52007-05-08 00:34:16 -0700621
622
623Appendix A: The kprobes debugfs interface
624
625With recent kernels (> 2.6.20) the list of registered kprobes is visible
626under the /debug/kprobes/ directory (assuming debugfs is mounted at /debug).
627
628/debug/kprobes/list: Lists all registered probes on the system
629
630c015d71a k vfs_read+0x0
631c011a316 j do_fork+0x0
632c03dedc5 r tcp_v4_rcv+0x0
633
634The first column provides the kernel address where the probe is inserted.
635The second column identifies the type of probe (k - kprobe, r - kretprobe
636and j - jprobe), while the third column specifies the symbol+offset of
637the probe. If the probed function belongs to a module, the module name
638is also specified.
639
640/debug/kprobes/enabled: Turn kprobes ON/OFF
641
642Provides a knob to globally turn registered kprobes ON or OFF. By default,
643all kprobes are enabled. By echoing "0" to this file, all registered probes
644will be disarmed, till such time a "1" is echoed to this file.