blob: d71fafffce90de81cba916c5d98dae7db5e9eb63 [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
17
181. Concepts: Kprobes, Jprobes, Return Probes
19
20Kprobes enables you to dynamically break into any kernel routine and
21collect debugging and performance information non-disruptively. You
22can trap at almost any kernel code address, specifying a handler
23routine to be invoked when the breakpoint is hit.
24
25There are currently three types of probes: kprobes, jprobes, and
26kretprobes (also called return probes). A kprobe can be inserted
27on virtually any instruction in the kernel. A jprobe is inserted at
28the entry to a kernel function, and provides convenient access to the
29function's arguments. A return probe fires when a specified function
30returns.
31
32In the typical case, Kprobes-based instrumentation is packaged as
33a kernel module. The module's init function installs ("registers")
34one or more probes, and the exit function unregisters them. A
35registration function such as register_kprobe() specifies where
36the probe is to be inserted and what handler is to be called when
37the probe is hit.
38
39The next three subsections explain how the different types of
40probes work. They explain certain things that you'll need to
41know in order to make the best use of Kprobes -- e.g., the
42difference between a pre_handler and a post_handler, and how
43to use the maxactive and nmissed fields of a kretprobe. But
44if you're in a hurry to start using Kprobes, you can skip ahead
45to section 2.
46
471.1 How Does a Kprobe Work?
48
49When a kprobe is registered, Kprobes makes a copy of the probed
50instruction and replaces the first byte(s) of the probed instruction
51with a breakpoint instruction (e.g., int3 on i386 and x86_64).
52
53When a CPU hits the breakpoint instruction, a trap occurs, the CPU's
54registers are saved, and control passes to Kprobes via the
55notifier_call_chain mechanism. Kprobes executes the "pre_handler"
56associated with the kprobe, passing the handler the addresses of the
57kprobe struct and the saved registers.
58
59Next, Kprobes single-steps its copy of the probed instruction.
60(It would be simpler to single-step the actual instruction in place,
61but then Kprobes would have to temporarily remove the breakpoint
62instruction. This would open a small time window when another CPU
63could sail right past the probepoint.)
64
65After the instruction is single-stepped, Kprobes executes the
66"post_handler," if any, that is associated with the kprobe.
67Execution then continues with the instruction following the probepoint.
68
691.2 How Does a Jprobe Work?
70
71A jprobe is implemented using a kprobe that is placed on a function's
72entry point. It employs a simple mirroring principle to allow
73seamless access to the probed function's arguments. The jprobe
74handler routine should have the same signature (arg list and return
75type) as the function being probed, and must always end by calling
76the Kprobes function jprobe_return().
77
78Here's how it works. When the probe is hit, Kprobes makes a copy of
79the saved registers and a generous portion of the stack (see below).
80Kprobes then points the saved instruction pointer at the jprobe's
81handler routine, and returns from the trap. As a result, control
82passes to the handler, which is presented with the same register and
83stack contents as the probed function. When it is done, the handler
84calls jprobe_return(), which traps again to restore the original stack
85contents and processor state and switch to the probed function.
86
87By convention, the callee owns its arguments, so gcc may produce code
88that unexpectedly modifies that portion of the stack. This is why
89Kprobes saves a copy of the stack and restores it after the jprobe
90handler has run. Up to MAX_STACK_SIZE bytes are copied -- e.g.,
9164 bytes on i386.
92
93Note that the probed function's args may be passed on the stack
94or in registers (e.g., for x86_64 or for an i386 fastcall function).
95The jprobe will work in either case, so long as the handler's
96prototype matches that of the probed function.
97
981.3 How Does a Return Probe Work?
99
100When you call register_kretprobe(), Kprobes establishes a kprobe at
101the entry to the function. When the probed function is called and this
102probe is hit, Kprobes saves a copy of the return address, and replaces
103the return address with the address of a "trampoline." The trampoline
104is an arbitrary piece of code -- typically just a nop instruction.
105At boot time, Kprobes registers a kprobe at the trampoline.
106
107When the probed function executes its return instruction, control
108passes to the trampoline and that probe is hit. Kprobes' trampoline
109handler calls the user-specified handler associated with the kretprobe,
110then sets the saved instruction pointer to the saved return address,
111and that's where execution resumes upon return from the trap.
112
113While the probed function is executing, its return address is
114stored in an object of type kretprobe_instance. Before calling
115register_kretprobe(), the user sets the maxactive field of the
116kretprobe struct to specify how many instances of the specified
117function can be probed simultaneously. register_kretprobe()
118pre-allocates the indicated number of kretprobe_instance objects.
119
120For example, if the function is non-recursive and is called with a
121spinlock held, maxactive = 1 should be enough. If the function is
122non-recursive and can never relinquish the CPU (e.g., via a semaphore
123or preemption), NR_CPUS should be enough. If maxactive <= 0, it is
124set to a default value. If CONFIG_PREEMPT is enabled, the default
125is max(10, 2*NR_CPUS). Otherwise, the default is NR_CPUS.
126
127It's not a disaster if you set maxactive too low; you'll just miss
128some probes. In the kretprobe struct, the nmissed field is set to
129zero when the return probe is registered, and is incremented every
130time the probed function is entered but there is no kretprobe_instance
131object available for establishing the return probe.
132
1332. Architectures Supported
134
135Kprobes, jprobes, and return probes are implemented on the following
136architectures:
137
138- i386
Jim Keniston8861da32006-02-14 13:53:06 -0800139- x86_64 (AMD-64, EM64T)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700140- ppc64
Jim Keniston8861da32006-02-14 13:53:06 -0800141- ia64 (Does not support probes on instruction slot1.)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700142- sparc64 (Return probes not yet implemented.)
143
1443. Configuring Kprobes
145
146When configuring the kernel using make menuconfig/xconfig/oldconfig,
Jim Keniston8861da32006-02-14 13:53:06 -0800147ensure that CONFIG_KPROBES is set to "y". Under "Instrumentation
148Support", look for "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".
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700153
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700154Also make sure that CONFIG_KALLSYMS and perhaps even CONFIG_KALLSYMS_ALL
155are set to "y", since kallsyms_lookup_name() is used by the in-kernel
156kprobe address resolution code.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700157
158If you need to insert a probe in the middle of a function, you may find
159it useful to "Compile the kernel with debug info" (CONFIG_DEBUG_INFO),
160so you can use "objdump -d -l vmlinux" to see the source-to-object
161code mapping.
162
1634. API Reference
164
165The Kprobes API includes a "register" function and an "unregister"
166function for each type of probe. Here are terse, mini-man-page
167specifications for these functions and the associated probe handlers
168that you'll write. See the latter half of this document for examples.
169
1704.1 register_kprobe
171
172#include <linux/kprobes.h>
173int register_kprobe(struct kprobe *kp);
174
175Sets a breakpoint at the address kp->addr. When the breakpoint is
176hit, Kprobes calls kp->pre_handler. After the probed instruction
177is single-stepped, Kprobe calls kp->post_handler. If a fault
178occurs during execution of kp->pre_handler or kp->post_handler,
179or during single-stepping of the probed instruction, Kprobes calls
180kp->fault_handler. Any or all handlers can be NULL.
181
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700182NOTE:
1831. With the introduction of the "symbol_name" field to struct kprobe,
184the probepoint address resolution will now be taken care of by the kernel.
185The following will now work:
186
187 kp.symbol_name = "symbol_name";
188
189(64-bit powerpc intricacies such as function descriptors are handled
190transparently)
191
1922. Use the "offset" field of struct kprobe if the offset into the symbol
193to install a probepoint is known. This field is used to calculate the
194probepoint.
195
1963. Specify either the kprobe "symbol_name" OR the "addr". If both are
197specified, kprobe registration will fail with -EINVAL.
198
1994. With CISC architectures (such as i386 and x86_64), the kprobes code
200does not validate if the kprobe.addr is at an instruction boundary.
201Use "offset" with caution.
202
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700203register_kprobe() returns 0 on success, or a negative errno otherwise.
204
205User's pre-handler (kp->pre_handler):
206#include <linux/kprobes.h>
207#include <linux/ptrace.h>
208int pre_handler(struct kprobe *p, struct pt_regs *regs);
209
210Called with p pointing to the kprobe associated with the breakpoint,
211and regs pointing to the struct containing the registers saved when
212the breakpoint was hit. Return 0 here unless you're a Kprobes geek.
213
214User's post-handler (kp->post_handler):
215#include <linux/kprobes.h>
216#include <linux/ptrace.h>
217void post_handler(struct kprobe *p, struct pt_regs *regs,
218 unsigned long flags);
219
220p and regs are as described for the pre_handler. flags always seems
221to be zero.
222
223User's fault-handler (kp->fault_handler):
224#include <linux/kprobes.h>
225#include <linux/ptrace.h>
226int fault_handler(struct kprobe *p, struct pt_regs *regs, int trapnr);
227
228p and regs are as described for the pre_handler. trapnr is the
229architecture-specific trap number associated with the fault (e.g.,
230on i386, 13 for a general protection fault or 14 for a page fault).
231Returns 1 if it successfully handled the exception.
232
2334.2 register_jprobe
234
235#include <linux/kprobes.h>
236int register_jprobe(struct jprobe *jp)
237
238Sets a breakpoint at the address jp->kp.addr, which must be the address
239of the first instruction of a function. When the breakpoint is hit,
240Kprobes runs the handler whose address is jp->entry.
241
242The handler should have the same arg list and return type as the probed
243function; and just before it returns, it must call jprobe_return().
244(The handler never actually returns, since jprobe_return() returns
245control to Kprobes.) If the probed function is declared asmlinkage,
246fastcall, or anything else that affects how args are passed, the
247handler's declaration must match.
248
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700249NOTE: A macro JPROBE_ENTRY is provided to handle architecture-specific
250aliasing of jp->entry. In the interest of portability, it is advised
251to use:
252
253 jp->entry = JPROBE_ENTRY(handler);
254
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700255register_jprobe() returns 0 on success, or a negative errno otherwise.
256
2574.3 register_kretprobe
258
259#include <linux/kprobes.h>
260int register_kretprobe(struct kretprobe *rp);
261
262Establishes a return probe for the function whose address is
263rp->kp.addr. When that function returns, Kprobes calls rp->handler.
264You must set rp->maxactive appropriately before you call
265register_kretprobe(); see "How Does a Return Probe Work?" for details.
266
267register_kretprobe() returns 0 on success, or a negative errno
268otherwise.
269
270User's return-probe handler (rp->handler):
271#include <linux/kprobes.h>
272#include <linux/ptrace.h>
273int kretprobe_handler(struct kretprobe_instance *ri, struct pt_regs *regs);
274
275regs is as described for kprobe.pre_handler. ri points to the
276kretprobe_instance object, of which the following fields may be
277of interest:
278- ret_addr: the return address
279- rp: points to the corresponding kretprobe object
280- task: points to the corresponding task struct
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700281
282The regs_return_value(regs) macro provides a simple abstraction to
283extract the return value from the appropriate register as defined by
284the architecture's ABI.
285
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700286The handler's return value is currently ignored.
287
2884.4 unregister_*probe
289
290#include <linux/kprobes.h>
291void unregister_kprobe(struct kprobe *kp);
292void unregister_jprobe(struct jprobe *jp);
293void unregister_kretprobe(struct kretprobe *rp);
294
295Removes the specified probe. The unregister function can be called
296at any time after the probe has been registered.
297
2985. Kprobes Features and Limitations
299
Jim Keniston8861da32006-02-14 13:53:06 -0800300Kprobes allows multiple probes at the same address. Currently,
301however, there cannot be multiple jprobes on the same function at
302the same time.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700303
304In general, you can install a probe anywhere in the kernel.
305In particular, you can probe interrupt handlers. Known exceptions
306are discussed in this section.
307
Jim Keniston8861da32006-02-14 13:53:06 -0800308The register_*probe functions will return -EINVAL if you attempt
309to install a probe in the code that implements Kprobes (mostly
310kernel/kprobes.c and arch/*/kernel/kprobes.c, but also functions such
311as do_page_fault and notifier_call_chain).
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700312
313If you install a probe in an inline-able function, Kprobes makes
314no attempt to chase down all inline instances of the function and
315install probes there. gcc may inline a function without being asked,
316so keep this in mind if you're not seeing the probe hits you expect.
317
318A probe handler can modify the environment of the probed function
319-- e.g., by modifying kernel data structures, or by modifying the
320contents of the pt_regs struct (which are restored to the registers
321upon return from the breakpoint). So Kprobes can be used, for example,
322to install a bug fix or to inject faults for testing. Kprobes, of
323course, has no way to distinguish the deliberately injected faults
324from the accidental ones. Don't drink and probe.
325
326Kprobes makes no attempt to prevent probe handlers from stepping on
327each other -- e.g., probing printk() and then calling printk() from a
Jim Keniston8861da32006-02-14 13:53:06 -0800328probe handler. If a probe handler hits a probe, that second probe's
329handlers won't be run in that instance, and the kprobe.nmissed member
330of the second probe will be incremented.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700331
Jim Keniston8861da32006-02-14 13:53:06 -0800332As of Linux v2.6.15-rc1, multiple handlers (or multiple instances of
333the same handler) may run concurrently on different CPUs.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700334
Jim Keniston8861da32006-02-14 13:53:06 -0800335Kprobes does not use mutexes or allocate memory except during
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700336registration and unregistration.
337
338Probe handlers are run with preemption disabled. Depending on the
339architecture, handlers may also run with interrupts disabled. In any
340case, your handler should not yield the CPU (e.g., by attempting to
341acquire a semaphore).
342
343Since a return probe is implemented by replacing the return
344address with the trampoline's address, stack backtraces and calls
345to __builtin_return_address() will typically yield the trampoline's
346address instead of the real return address for kretprobed functions.
347(As far as we can tell, __builtin_return_address() is used only
348for instrumentation and error reporting.)
349
Jim Keniston8861da32006-02-14 13:53:06 -0800350If the number of times a function is called does not match the number
351of times it returns, registering a return probe on that function may
352produce undesirable results. We have the do_exit() case covered.
353do_execve() and do_fork() are not an issue. We're unaware of other
354specific cases where this could be a problem.
355
356If, upon entry to or exit from a function, the CPU is running on
357a stack other than that of the current task, registering a return
358probe on that function may produce undesirable results. For this
359reason, Kprobes doesn't support return probes (or kprobes or jprobes)
360on the x86_64 version of __switch_to(); the registration functions
361return -EINVAL.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700362
3636. Probe Overhead
364
365On a typical CPU in use in 2005, a kprobe hit takes 0.5 to 1.0
366microseconds to process. Specifically, a benchmark that hits the same
367probepoint repeatedly, firing a simple handler each time, reports 1-2
368million hits per second, depending on the architecture. A jprobe or
369return-probe hit typically takes 50-75% longer than a kprobe hit.
370When you have a return probe set on a function, adding a kprobe at
371the entry to that function adds essentially no overhead.
372
373Here are sample overhead figures (in usec) for different architectures.
374k = kprobe; j = jprobe; r = return probe; kr = kprobe + return probe
375on same function; jr = jprobe + return probe on same function
376
377i386: Intel Pentium M, 1495 MHz, 2957.31 bogomips
378k = 0.57 usec; j = 1.00; r = 0.92; kr = 0.99; jr = 1.40
379
380x86_64: AMD Opteron 246, 1994 MHz, 3971.48 bogomips
381k = 0.49 usec; j = 0.76; r = 0.80; kr = 0.82; jr = 1.07
382
383ppc64: POWER5 (gr), 1656 MHz (SMT disabled, 1 virtual CPU per physical CPU)
384k = 0.77 usec; j = 1.31; r = 1.26; kr = 1.45; jr = 1.99
385
3867. TODO
387
Jim Keniston8861da32006-02-14 13:53:06 -0800388a. SystemTap (http://sourceware.org/systemtap): Provides a simplified
389programming interface for probe-based instrumentation. Try it out.
390b. Kernel return probes for sparc64.
391c. Support for other architectures.
392d. User-space probes.
393e. Watchpoint probes (which fire on data references).
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700394
3958. Kprobes Example
396
397Here's a sample kernel module showing the use of kprobes to dump a
398stack trace and selected i386 registers when do_fork() is called.
399----- cut here -----
400/*kprobe_example.c*/
401#include <linux/kernel.h>
402#include <linux/module.h>
403#include <linux/kprobes.h>
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700404#include <linux/sched.h>
405
406/*For each probe you need to allocate a kprobe structure*/
407static struct kprobe kp;
408
409/*kprobe pre_handler: called just before the probed instruction is executed*/
410int handler_pre(struct kprobe *p, struct pt_regs *regs)
411{
412 printk("pre_handler: p->addr=0x%p, eip=%lx, eflags=0x%lx\n",
413 p->addr, regs->eip, regs->eflags);
414 dump_stack();
415 return 0;
416}
417
418/*kprobe post_handler: called after the probed instruction is executed*/
419void handler_post(struct kprobe *p, struct pt_regs *regs, unsigned long flags)
420{
421 printk("post_handler: p->addr=0x%p, eflags=0x%lx\n",
422 p->addr, regs->eflags);
423}
424
425/* fault_handler: this is called if an exception is generated for any
426 * instruction within the pre- or post-handler, or when Kprobes
427 * single-steps the probed instruction.
428 */
429int handler_fault(struct kprobe *p, struct pt_regs *regs, int trapnr)
430{
431 printk("fault_handler: p->addr=0x%p, trap #%dn",
432 p->addr, trapnr);
433 /* Return 0 because we don't handle the fault. */
434 return 0;
435}
436
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700437static int __init kprobe_init(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700438{
439 int ret;
440 kp.pre_handler = handler_pre;
441 kp.post_handler = handler_post;
442 kp.fault_handler = handler_fault;
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700443 kp.symbol_name = "do_fork";
444
Alexey Dobriyan565762f2006-11-16 01:19:28 -0800445 ret = register_kprobe(&kp);
446 if (ret < 0) {
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700447 printk("register_kprobe failed, returned %d\n", ret);
Alexey Dobriyan565762f2006-11-16 01:19:28 -0800448 return ret;
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700449 }
450 printk("kprobe registered\n");
451 return 0;
452}
453
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700454static void __exit kprobe_exit(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700455{
456 unregister_kprobe(&kp);
457 printk("kprobe unregistered\n");
458}
459
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700460module_init(kprobe_init)
461module_exit(kprobe_exit)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700462MODULE_LICENSE("GPL");
463----- cut here -----
464
465You can build the kernel module, kprobe-example.ko, using the following
466Makefile:
467----- cut here -----
468obj-m := kprobe-example.o
469KDIR := /lib/modules/$(shell uname -r)/build
470PWD := $(shell pwd)
471default:
472 $(MAKE) -C $(KDIR) SUBDIRS=$(PWD) modules
473clean:
474 rm -f *.mod.c *.ko *.o
475----- cut here -----
476
477$ make
478$ su -
479...
480# insmod kprobe-example.ko
481
482You will see the trace data in /var/log/messages and on the console
483whenever do_fork() is invoked to create a new process.
484
4859. Jprobes Example
486
487Here's a sample kernel module showing the use of jprobes to dump
488the arguments of do_fork().
489----- cut here -----
490/*jprobe-example.c */
491#include <linux/kernel.h>
492#include <linux/module.h>
493#include <linux/fs.h>
494#include <linux/uio.h>
495#include <linux/kprobes.h>
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700496
497/*
498 * Jumper probe for do_fork.
499 * Mirror principle enables access to arguments of the probed routine
500 * from the probe handler.
501 */
502
503/* Proxy routine having the same arguments as actual do_fork() routine */
504long jdo_fork(unsigned long clone_flags, unsigned long stack_start,
505 struct pt_regs *regs, unsigned long stack_size,
506 int __user * parent_tidptr, int __user * child_tidptr)
507{
508 printk("jprobe: clone_flags=0x%lx, stack_size=0x%lx, regs=0x%p\n",
509 clone_flags, stack_size, regs);
510 /* Always end with a call to jprobe_return(). */
511 jprobe_return();
512 /*NOTREACHED*/
513 return 0;
514}
515
516static struct jprobe my_jprobe = {
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700517 .entry = JPROBE_ENTRY(jdo_fork)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700518};
519
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700520static int __init jprobe_init(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700521{
522 int ret;
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700523 my_jprobe.kp.symbol_name = "do_fork";
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700524
525 if ((ret = register_jprobe(&my_jprobe)) <0) {
526 printk("register_jprobe failed, returned %d\n", ret);
527 return -1;
528 }
529 printk("Planted jprobe at %p, handler addr %p\n",
530 my_jprobe.kp.addr, my_jprobe.entry);
531 return 0;
532}
533
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700534static void __exit jprobe_exit(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700535{
536 unregister_jprobe(&my_jprobe);
537 printk("jprobe unregistered\n");
538}
539
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700540module_init(jprobe_init)
541module_exit(jprobe_exit)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700542MODULE_LICENSE("GPL");
543----- cut here -----
544
545Build and insert the kernel module as shown in the above kprobe
546example. You will see the trace data in /var/log/messages and on
547the console whenever do_fork() is invoked to create a new process.
548(Some messages may be suppressed if syslogd is configured to
549eliminate duplicate messages.)
550
55110. Kretprobes Example
552
553Here's a sample kernel module showing the use of return probes to
554report failed calls to sys_open().
555----- cut here -----
556/*kretprobe-example.c*/
557#include <linux/kernel.h>
558#include <linux/module.h>
559#include <linux/kprobes.h>
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700560
561static const char *probed_func = "sys_open";
562
563/* Return-probe handler: If the probed function fails, log the return value. */
564static int ret_handler(struct kretprobe_instance *ri, struct pt_regs *regs)
565{
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700566 int retval = regs_return_value(regs);
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700567 if (retval < 0) {
568 printk("%s returns %d\n", probed_func, retval);
569 }
570 return 0;
571}
572
573static struct kretprobe my_kretprobe = {
574 .handler = ret_handler,
575 /* Probe up to 20 instances concurrently. */
576 .maxactive = 20
577};
578
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700579static int __init kretprobe_init(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700580{
581 int ret;
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700582 my_kretprobe.kp.symbol_name = (char *)probed_func;
583
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700584 if ((ret = register_kretprobe(&my_kretprobe)) < 0) {
585 printk("register_kretprobe failed, returned %d\n", ret);
586 return -1;
587 }
588 printk("Planted return probe at %p\n", my_kretprobe.kp.addr);
589 return 0;
590}
591
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700592static void __exit kretprobe_exit(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700593{
594 unregister_kretprobe(&my_kretprobe);
595 printk("kretprobe unregistered\n");
596 /* nmissed > 0 suggests that maxactive was set too low. */
597 printk("Missed probing %d instances of %s\n",
598 my_kretprobe.nmissed, probed_func);
599}
600
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700601module_init(kretprobe_init)
602module_exit(kretprobe_exit)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700603MODULE_LICENSE("GPL");
604----- cut here -----
605
606Build and insert the kernel module as shown in the above kprobe
607example. You will see the trace data in /var/log/messages and on the
608console whenever sys_open() returns a negative value. (Some messages
609may be suppressed if syslogd is configured to eliminate duplicate
610messages.)
611
612For additional information on Kprobes, refer to the following URLs:
613http://www-106.ibm.com/developerworks/library/l-kprobes.html?ca=dgr-lnxw42Kprobe
614http://www.redhat.com/magazine/005mar05/features/kprobes/
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700615http://www-users.cs.umn.edu/~boutcher/kprobes/
616http://www.linuxsymposium.org/2006/linuxsymposium_procv2.pdf (pages 101-115)