blob: 83f515c2905a806d88276ea587da5d9ef5196c52 [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
Harvey Harrisonb5606c22008-02-13 15:03:16 -080095or in registers. The jprobe will work in either case, so long as the
96handler's prototype matches that of the probed function.
Jim Kenistond27a4dd2005-08-04 12:53:35 -070097
Abhishek Sagarf47cd9b2008-02-06 01:38:22 -0800981.3 Return Probes
99
1001.3.1 How Does a Return Probe Work?
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700101
102When you call register_kretprobe(), Kprobes establishes a kprobe at
103the entry to the function. When the probed function is called and this
104probe is hit, Kprobes saves a copy of the return address, and replaces
105the return address with the address of a "trampoline." The trampoline
106is an arbitrary piece of code -- typically just a nop instruction.
107At boot time, Kprobes registers a kprobe at the trampoline.
108
109When the probed function executes its return instruction, control
110passes to the trampoline and that probe is hit. Kprobes' trampoline
Abhishek Sagarf47cd9b2008-02-06 01:38:22 -0800111handler calls the user-specified return handler associated with the
112kretprobe, then sets the saved instruction pointer to the saved return
113address, and that's where execution resumes upon return from the trap.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700114
115While the probed function is executing, its return address is
116stored in an object of type kretprobe_instance. Before calling
117register_kretprobe(), the user sets the maxactive field of the
118kretprobe struct to specify how many instances of the specified
119function can be probed simultaneously. register_kretprobe()
120pre-allocates the indicated number of kretprobe_instance objects.
121
122For example, if the function is non-recursive and is called with a
123spinlock held, maxactive = 1 should be enough. If the function is
124non-recursive and can never relinquish the CPU (e.g., via a semaphore
125or preemption), NR_CPUS should be enough. If maxactive <= 0, it is
126set to a default value. If CONFIG_PREEMPT is enabled, the default
127is max(10, 2*NR_CPUS). Otherwise, the default is NR_CPUS.
128
129It's not a disaster if you set maxactive too low; you'll just miss
130some probes. In the kretprobe struct, the nmissed field is set to
131zero when the return probe is registered, and is incremented every
132time the probed function is entered but there is no kretprobe_instance
133object available for establishing the return probe.
134
Abhishek Sagarf47cd9b2008-02-06 01:38:22 -08001351.3.2 Kretprobe entry-handler
136
137Kretprobes also provides an optional user-specified handler which runs
138on function entry. This handler is specified by setting the entry_handler
139field of the kretprobe struct. Whenever the kprobe placed by kretprobe at the
140function entry is hit, the user-defined entry_handler, if any, is invoked.
141If the entry_handler returns 0 (success) then a corresponding return handler
142is guaranteed to be called upon function return. If the entry_handler
143returns a non-zero error then Kprobes leaves the return address as is, and
144the kretprobe has no further effect for that particular function instance.
145
146Multiple entry and return handler invocations are matched using the unique
147kretprobe_instance object associated with them. Additionally, a user
148may also specify per return-instance private data to be part of each
149kretprobe_instance object. This is especially useful when sharing private
150data between corresponding user entry and return handlers. The size of each
151private data object can be specified at kretprobe registration time by
152setting the data_size field of the kretprobe struct. This data can be
153accessed through the data field of each kretprobe_instance object.
154
155In case probed function is entered but there is no kretprobe_instance
156object available, then in addition to incrementing the nmissed count,
157the user entry_handler invocation is also skipped.
158
Jim Kenistond27a4dd2005-08-04 12:53:35 -07001592. Architectures Supported
160
161Kprobes, jprobes, and return probes are implemented on the following
162architectures:
163
164- i386
Jim Keniston8861da32006-02-14 13:53:06 -0800165- x86_64 (AMD-64, EM64T)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700166- ppc64
Jim Keniston8861da32006-02-14 13:53:06 -0800167- ia64 (Does not support probes on instruction slot1.)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700168- sparc64 (Return probes not yet implemented.)
Nicolas Pitre5de865b2007-12-03 17:15:52 -0500169- arm
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700170
1713. Configuring Kprobes
172
173When configuring the kernel using make menuconfig/xconfig/oldconfig,
Jim Keniston8861da32006-02-14 13:53:06 -0800174ensure that CONFIG_KPROBES is set to "y". Under "Instrumentation
175Support", look for "Kprobes".
176
177So that you can load and unload Kprobes-based instrumentation modules,
178make sure "Loadable module support" (CONFIG_MODULES) and "Module
179unloading" (CONFIG_MODULE_UNLOAD) are set to "y".
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700180
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700181Also make sure that CONFIG_KALLSYMS and perhaps even CONFIG_KALLSYMS_ALL
182are set to "y", since kallsyms_lookup_name() is used by the in-kernel
183kprobe address resolution code.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700184
185If you need to insert a probe in the middle of a function, you may find
186it useful to "Compile the kernel with debug info" (CONFIG_DEBUG_INFO),
187so you can use "objdump -d -l vmlinux" to see the source-to-object
188code mapping.
189
1904. API Reference
191
192The Kprobes API includes a "register" function and an "unregister"
193function for each type of probe. Here are terse, mini-man-page
194specifications for these functions and the associated probe handlers
195that you'll write. See the latter half of this document for examples.
196
1974.1 register_kprobe
198
199#include <linux/kprobes.h>
200int register_kprobe(struct kprobe *kp);
201
202Sets a breakpoint at the address kp->addr. When the breakpoint is
203hit, Kprobes calls kp->pre_handler. After the probed instruction
204is single-stepped, Kprobe calls kp->post_handler. If a fault
205occurs during execution of kp->pre_handler or kp->post_handler,
206or during single-stepping of the probed instruction, Kprobes calls
207kp->fault_handler. Any or all handlers can be NULL.
208
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700209NOTE:
2101. With the introduction of the "symbol_name" field to struct kprobe,
211the probepoint address resolution will now be taken care of by the kernel.
212The following will now work:
213
214 kp.symbol_name = "symbol_name";
215
216(64-bit powerpc intricacies such as function descriptors are handled
217transparently)
218
2192. Use the "offset" field of struct kprobe if the offset into the symbol
220to install a probepoint is known. This field is used to calculate the
221probepoint.
222
2233. Specify either the kprobe "symbol_name" OR the "addr". If both are
224specified, kprobe registration will fail with -EINVAL.
225
2264. With CISC architectures (such as i386 and x86_64), the kprobes code
227does not validate if the kprobe.addr is at an instruction boundary.
228Use "offset" with caution.
229
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700230register_kprobe() returns 0 on success, or a negative errno otherwise.
231
232User's pre-handler (kp->pre_handler):
233#include <linux/kprobes.h>
234#include <linux/ptrace.h>
235int pre_handler(struct kprobe *p, struct pt_regs *regs);
236
237Called with p pointing to the kprobe associated with the breakpoint,
238and regs pointing to the struct containing the registers saved when
239the breakpoint was hit. Return 0 here unless you're a Kprobes geek.
240
241User's post-handler (kp->post_handler):
242#include <linux/kprobes.h>
243#include <linux/ptrace.h>
244void post_handler(struct kprobe *p, struct pt_regs *regs,
245 unsigned long flags);
246
247p and regs are as described for the pre_handler. flags always seems
248to be zero.
249
250User's fault-handler (kp->fault_handler):
251#include <linux/kprobes.h>
252#include <linux/ptrace.h>
253int fault_handler(struct kprobe *p, struct pt_regs *regs, int trapnr);
254
255p and regs are as described for the pre_handler. trapnr is the
256architecture-specific trap number associated with the fault (e.g.,
257on i386, 13 for a general protection fault or 14 for a page fault).
258Returns 1 if it successfully handled the exception.
259
2604.2 register_jprobe
261
262#include <linux/kprobes.h>
263int register_jprobe(struct jprobe *jp)
264
265Sets a breakpoint at the address jp->kp.addr, which must be the address
266of the first instruction of a function. When the breakpoint is hit,
267Kprobes runs the handler whose address is jp->entry.
268
269The handler should have the same arg list and return type as the probed
270function; and just before it returns, it must call jprobe_return().
271(The handler never actually returns, since jprobe_return() returns
Harvey Harrisonb5606c22008-02-13 15:03:16 -0800272control to Kprobes.) If the probed function is declared asmlinkage
273or anything else that affects how args are passed, the handler's
274declaration must match.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700275
276register_jprobe() returns 0 on success, or a negative errno otherwise.
277
2784.3 register_kretprobe
279
280#include <linux/kprobes.h>
281int register_kretprobe(struct kretprobe *rp);
282
283Establishes a return probe for the function whose address is
284rp->kp.addr. When that function returns, Kprobes calls rp->handler.
285You must set rp->maxactive appropriately before you call
286register_kretprobe(); see "How Does a Return Probe Work?" for details.
287
288register_kretprobe() returns 0 on success, or a negative errno
289otherwise.
290
291User's return-probe handler (rp->handler):
292#include <linux/kprobes.h>
293#include <linux/ptrace.h>
294int kretprobe_handler(struct kretprobe_instance *ri, struct pt_regs *regs);
295
296regs is as described for kprobe.pre_handler. ri points to the
297kretprobe_instance object, of which the following fields may be
298of interest:
299- ret_addr: the return address
300- rp: points to the corresponding kretprobe object
301- task: points to the corresponding task struct
Abhishek Sagarf47cd9b2008-02-06 01:38:22 -0800302- data: points to per return-instance private data; see "Kretprobe
303 entry-handler" for details.
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700304
305The regs_return_value(regs) macro provides a simple abstraction to
306extract the return value from the appropriate register as defined by
307the architecture's ABI.
308
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700309The handler's return value is currently ignored.
310
3114.4 unregister_*probe
312
313#include <linux/kprobes.h>
314void unregister_kprobe(struct kprobe *kp);
315void unregister_jprobe(struct jprobe *jp);
316void unregister_kretprobe(struct kretprobe *rp);
317
318Removes the specified probe. The unregister function can be called
319at any time after the probe has been registered.
320
3215. Kprobes Features and Limitations
322
Jim Keniston8861da32006-02-14 13:53:06 -0800323Kprobes allows multiple probes at the same address. Currently,
324however, there cannot be multiple jprobes on the same function at
325the same time.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700326
327In general, you can install a probe anywhere in the kernel.
328In particular, you can probe interrupt handlers. Known exceptions
329are discussed in this section.
330
Jim Keniston8861da32006-02-14 13:53:06 -0800331The register_*probe functions will return -EINVAL if you attempt
332to install a probe in the code that implements Kprobes (mostly
333kernel/kprobes.c and arch/*/kernel/kprobes.c, but also functions such
334as do_page_fault and notifier_call_chain).
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700335
336If you install a probe in an inline-able function, Kprobes makes
337no attempt to chase down all inline instances of the function and
338install probes there. gcc may inline a function without being asked,
339so keep this in mind if you're not seeing the probe hits you expect.
340
341A probe handler can modify the environment of the probed function
342-- e.g., by modifying kernel data structures, or by modifying the
343contents of the pt_regs struct (which are restored to the registers
344upon return from the breakpoint). So Kprobes can be used, for example,
345to install a bug fix or to inject faults for testing. Kprobes, of
346course, has no way to distinguish the deliberately injected faults
347from the accidental ones. Don't drink and probe.
348
349Kprobes makes no attempt to prevent probe handlers from stepping on
350each other -- e.g., probing printk() and then calling printk() from a
Jim Keniston8861da32006-02-14 13:53:06 -0800351probe handler. If a probe handler hits a probe, that second probe's
352handlers won't be run in that instance, and the kprobe.nmissed member
353of the second probe will be incremented.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700354
Jim Keniston8861da32006-02-14 13:53:06 -0800355As of Linux v2.6.15-rc1, multiple handlers (or multiple instances of
356the same handler) may run concurrently on different CPUs.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700357
Jim Keniston8861da32006-02-14 13:53:06 -0800358Kprobes does not use mutexes or allocate memory except during
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700359registration and unregistration.
360
361Probe handlers are run with preemption disabled. Depending on the
362architecture, handlers may also run with interrupts disabled. In any
363case, your handler should not yield the CPU (e.g., by attempting to
364acquire a semaphore).
365
366Since a return probe is implemented by replacing the return
367address with the trampoline's address, stack backtraces and calls
368to __builtin_return_address() will typically yield the trampoline's
369address instead of the real return address for kretprobed functions.
370(As far as we can tell, __builtin_return_address() is used only
371for instrumentation and error reporting.)
372
Jim Keniston8861da32006-02-14 13:53:06 -0800373If the number of times a function is called does not match the number
374of times it returns, registering a return probe on that function may
Ananth N Mavinakayanahallibf8f6e52007-05-08 00:34:16 -0700375produce undesirable results. In such a case, a line:
376kretprobe BUG!: Processing kretprobe d000000000041aa8 @ c00000000004f48c
377gets printed. With this information, one will be able to correlate the
378exact instance of the kretprobe that caused the problem. We have the
379do_exit() case covered. do_execve() and do_fork() are not an issue.
380We're unaware of other specific cases where this could be a problem.
Jim Keniston8861da32006-02-14 13:53:06 -0800381
382If, upon entry to or exit from a function, the CPU is running on
383a stack other than that of the current task, registering a return
384probe on that function may produce undesirable results. For this
385reason, Kprobes doesn't support return probes (or kprobes or jprobes)
386on the x86_64 version of __switch_to(); the registration functions
387return -EINVAL.
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700388
3896. Probe Overhead
390
391On a typical CPU in use in 2005, a kprobe hit takes 0.5 to 1.0
392microseconds to process. Specifically, a benchmark that hits the same
393probepoint repeatedly, firing a simple handler each time, reports 1-2
394million hits per second, depending on the architecture. A jprobe or
395return-probe hit typically takes 50-75% longer than a kprobe hit.
396When you have a return probe set on a function, adding a kprobe at
397the entry to that function adds essentially no overhead.
398
399Here are sample overhead figures (in usec) for different architectures.
400k = kprobe; j = jprobe; r = return probe; kr = kprobe + return probe
401on same function; jr = jprobe + return probe on same function
402
403i386: Intel Pentium M, 1495 MHz, 2957.31 bogomips
404k = 0.57 usec; j = 1.00; r = 0.92; kr = 0.99; jr = 1.40
405
406x86_64: AMD Opteron 246, 1994 MHz, 3971.48 bogomips
407k = 0.49 usec; j = 0.76; r = 0.80; kr = 0.82; jr = 1.07
408
409ppc64: POWER5 (gr), 1656 MHz (SMT disabled, 1 virtual CPU per physical CPU)
410k = 0.77 usec; j = 1.31; r = 1.26; kr = 1.45; jr = 1.99
411
4127. TODO
413
Jim Keniston8861da32006-02-14 13:53:06 -0800414a. SystemTap (http://sourceware.org/systemtap): Provides a simplified
415programming interface for probe-based instrumentation. Try it out.
416b. Kernel return probes for sparc64.
417c. Support for other architectures.
418d. User-space probes.
419e. Watchpoint probes (which fire on data references).
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700420
4218. Kprobes Example
422
423Here's a sample kernel module showing the use of kprobes to dump a
424stack trace and selected i386 registers when do_fork() is called.
425----- cut here -----
426/*kprobe_example.c*/
427#include <linux/kernel.h>
428#include <linux/module.h>
429#include <linux/kprobes.h>
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700430#include <linux/sched.h>
431
432/*For each probe you need to allocate a kprobe structure*/
433static struct kprobe kp;
434
435/*kprobe pre_handler: called just before the probed instruction is executed*/
436int handler_pre(struct kprobe *p, struct pt_regs *regs)
437{
438 printk("pre_handler: p->addr=0x%p, eip=%lx, eflags=0x%lx\n",
439 p->addr, regs->eip, regs->eflags);
440 dump_stack();
441 return 0;
442}
443
444/*kprobe post_handler: called after the probed instruction is executed*/
445void handler_post(struct kprobe *p, struct pt_regs *regs, unsigned long flags)
446{
447 printk("post_handler: p->addr=0x%p, eflags=0x%lx\n",
448 p->addr, regs->eflags);
449}
450
451/* fault_handler: this is called if an exception is generated for any
452 * instruction within the pre- or post-handler, or when Kprobes
453 * single-steps the probed instruction.
454 */
455int handler_fault(struct kprobe *p, struct pt_regs *regs, int trapnr)
456{
457 printk("fault_handler: p->addr=0x%p, trap #%dn",
458 p->addr, trapnr);
459 /* Return 0 because we don't handle the fault. */
460 return 0;
461}
462
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700463static int __init kprobe_init(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700464{
465 int ret;
466 kp.pre_handler = handler_pre;
467 kp.post_handler = handler_post;
468 kp.fault_handler = handler_fault;
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700469 kp.symbol_name = "do_fork";
470
Alexey Dobriyan565762f2006-11-16 01:19:28 -0800471 ret = register_kprobe(&kp);
472 if (ret < 0) {
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700473 printk("register_kprobe failed, returned %d\n", ret);
Alexey Dobriyan565762f2006-11-16 01:19:28 -0800474 return ret;
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700475 }
476 printk("kprobe registered\n");
477 return 0;
478}
479
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700480static void __exit kprobe_exit(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700481{
482 unregister_kprobe(&kp);
483 printk("kprobe unregistered\n");
484}
485
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700486module_init(kprobe_init)
487module_exit(kprobe_exit)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700488MODULE_LICENSE("GPL");
489----- cut here -----
490
491You can build the kernel module, kprobe-example.ko, using the following
492Makefile:
493----- cut here -----
494obj-m := kprobe-example.o
495KDIR := /lib/modules/$(shell uname -r)/build
496PWD := $(shell pwd)
497default:
498 $(MAKE) -C $(KDIR) SUBDIRS=$(PWD) modules
499clean:
500 rm -f *.mod.c *.ko *.o
501----- cut here -----
502
503$ make
504$ su -
505...
506# insmod kprobe-example.ko
507
508You will see the trace data in /var/log/messages and on the console
509whenever do_fork() is invoked to create a new process.
510
5119. Jprobes Example
512
513Here's a sample kernel module showing the use of jprobes to dump
514the arguments of do_fork().
515----- cut here -----
516/*jprobe-example.c */
517#include <linux/kernel.h>
518#include <linux/module.h>
519#include <linux/fs.h>
520#include <linux/uio.h>
521#include <linux/kprobes.h>
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700522
523/*
524 * Jumper probe for do_fork.
525 * Mirror principle enables access to arguments of the probed routine
526 * from the probe handler.
527 */
528
529/* Proxy routine having the same arguments as actual do_fork() routine */
530long jdo_fork(unsigned long clone_flags, unsigned long stack_start,
531 struct pt_regs *regs, unsigned long stack_size,
532 int __user * parent_tidptr, int __user * child_tidptr)
533{
534 printk("jprobe: clone_flags=0x%lx, stack_size=0x%lx, regs=0x%p\n",
535 clone_flags, stack_size, regs);
536 /* Always end with a call to jprobe_return(). */
537 jprobe_return();
538 /*NOTREACHED*/
539 return 0;
540}
541
542static struct jprobe my_jprobe = {
Michael Ellerman9e367d82007-07-19 01:48:10 -0700543 .entry = jdo_fork
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700544};
545
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700546static int __init jprobe_init(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700547{
548 int ret;
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700549 my_jprobe.kp.symbol_name = "do_fork";
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700550
551 if ((ret = register_jprobe(&my_jprobe)) <0) {
552 printk("register_jprobe failed, returned %d\n", ret);
553 return -1;
554 }
555 printk("Planted jprobe at %p, handler addr %p\n",
556 my_jprobe.kp.addr, my_jprobe.entry);
557 return 0;
558}
559
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700560static void __exit jprobe_exit(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700561{
562 unregister_jprobe(&my_jprobe);
563 printk("jprobe unregistered\n");
564}
565
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700566module_init(jprobe_init)
567module_exit(jprobe_exit)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700568MODULE_LICENSE("GPL");
569----- cut here -----
570
571Build and insert the kernel module as shown in the above kprobe
572example. You will see the trace data in /var/log/messages and on
573the console whenever do_fork() is invoked to create a new process.
574(Some messages may be suppressed if syslogd is configured to
575eliminate duplicate messages.)
576
57710. Kretprobes Example
578
579Here's a sample kernel module showing the use of return probes to
580report failed calls to sys_open().
581----- cut here -----
582/*kretprobe-example.c*/
583#include <linux/kernel.h>
584#include <linux/module.h>
585#include <linux/kprobes.h>
Abhishek Sagarf47cd9b2008-02-06 01:38:22 -0800586#include <linux/ktime.h>
587
588/* per-instance private data */
589struct my_data {
590 ktime_t entry_stamp;
591};
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700592
593static const char *probed_func = "sys_open";
594
Abhishek Sagarf47cd9b2008-02-06 01:38:22 -0800595/* Timestamp function entry. */
596static int entry_handler(struct kretprobe_instance *ri, struct pt_regs *regs)
597{
598 struct my_data *data;
599
600 if(!current->mm)
601 return 1; /* skip kernel threads */
602
603 data = (struct my_data *)ri->data;
604 data->entry_stamp = ktime_get();
605 return 0;
606}
607
608/* If the probed function failed, log the return value and duration.
609 * Duration may turn out to be zero consistently, depending upon the
610 * granularity of time accounting on the platform. */
611static int return_handler(struct kretprobe_instance *ri, struct pt_regs *regs)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700612{
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700613 int retval = regs_return_value(regs);
Abhishek Sagarf47cd9b2008-02-06 01:38:22 -0800614 struct my_data *data = (struct my_data *)ri->data;
615 s64 delta;
616 ktime_t now;
617
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700618 if (retval < 0) {
Abhishek Sagarf47cd9b2008-02-06 01:38:22 -0800619 now = ktime_get();
620 delta = ktime_to_ns(ktime_sub(now, data->entry_stamp));
621 printk("%s: return val = %d (duration = %lld ns)\n",
622 probed_func, retval, delta);
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700623 }
624 return 0;
625}
626
627static struct kretprobe my_kretprobe = {
Abhishek Sagarf47cd9b2008-02-06 01:38:22 -0800628 .handler = return_handler,
629 .entry_handler = entry_handler,
630 .data_size = sizeof(struct my_data),
631 .maxactive = 20, /* probe up to 20 instances concurrently */
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700632};
633
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700634static int __init kretprobe_init(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700635{
636 int ret;
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700637 my_kretprobe.kp.symbol_name = (char *)probed_func;
638
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700639 if ((ret = register_kretprobe(&my_kretprobe)) < 0) {
640 printk("register_kretprobe failed, returned %d\n", ret);
641 return -1;
642 }
Abhishek Sagarf47cd9b2008-02-06 01:38:22 -0800643 printk("Kretprobe active on %s\n", my_kretprobe.kp.symbol_name);
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700644 return 0;
645}
646
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700647static void __exit kretprobe_exit(void)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700648{
649 unregister_kretprobe(&my_kretprobe);
650 printk("kretprobe unregistered\n");
651 /* nmissed > 0 suggests that maxactive was set too low. */
652 printk("Missed probing %d instances of %s\n",
Abhishek Sagarf47cd9b2008-02-06 01:38:22 -0800653 my_kretprobe.nmissed, probed_func);
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700654}
655
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700656module_init(kretprobe_init)
657module_exit(kretprobe_exit)
Jim Kenistond27a4dd2005-08-04 12:53:35 -0700658MODULE_LICENSE("GPL");
659----- cut here -----
660
661Build and insert the kernel module as shown in the above kprobe
662example. You will see the trace data in /var/log/messages and on the
663console whenever sys_open() returns a negative value. (Some messages
664may be suppressed if syslogd is configured to eliminate duplicate
665messages.)
666
667For additional information on Kprobes, refer to the following URLs:
668http://www-106.ibm.com/developerworks/library/l-kprobes.html?ca=dgr-lnxw42Kprobe
669http://www.redhat.com/magazine/005mar05/features/kprobes/
Ananth N Mavinakayanahalli09b18202006-10-02 02:17:32 -0700670http://www-users.cs.umn.edu/~boutcher/kprobes/
671http://www.linuxsymposium.org/2006/linuxsymposium_procv2.pdf (pages 101-115)
Ananth N Mavinakayanahallibf8f6e52007-05-08 00:34:16 -0700672
673
674Appendix A: The kprobes debugfs interface
675
676With recent kernels (> 2.6.20) the list of registered kprobes is visible
677under the /debug/kprobes/ directory (assuming debugfs is mounted at /debug).
678
679/debug/kprobes/list: Lists all registered probes on the system
680
681c015d71a k vfs_read+0x0
682c011a316 j do_fork+0x0
683c03dedc5 r tcp_v4_rcv+0x0
684
685The first column provides the kernel address where the probe is inserted.
686The second column identifies the type of probe (k - kprobe, r - kretprobe
687and j - jprobe), while the third column specifies the symbol+offset of
688the probe. If the probed function belongs to a module, the module name
689is also specified.
690
691/debug/kprobes/enabled: Turn kprobes ON/OFF
692
693Provides a knob to globally turn registered kprobes ON or OFF. By default,
694all kprobes are enabled. By echoing "0" to this file, all registered probes
695will be disarmed, till such time a "1" is echoed to this file.