Commit | Line | Data |
---|---|---|
595c3649 MH |
1 | perf-probe(1) |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | perf-probe - Define new dynamic tracepoints | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
c937fe20 | 11 | 'perf probe' [options] --add='PROBE' [...] |
c43f9d1e | 12 | or |
c937fe20 MH |
13 | 'perf probe' [options] PROBE |
14 | or | |
15 | 'perf probe' [options] --del='[GROUP:]EVENT' [...] | |
16 | or | |
17 | 'perf probe' --list | |
631c9def MH |
18 | or |
19 | 'perf probe' --line='FUNC[:RLN[+NUM|:RLN2]]|SRC:ALN[+NUM|:ALN2]' | |
595c3649 MH |
20 | |
21 | DESCRIPTION | |
22 | ----------- | |
23 | This command defines dynamic tracepoint events, by symbol and registers | |
24 | without debuginfo, or by C expressions (C line numbers, C function names, | |
25 | and C local variables) with debuginfo. | |
26 | ||
27 | ||
28 | OPTIONS | |
29 | ------- | |
30 | -k:: | |
c43f9d1e | 31 | --vmlinux=PATH:: |
595c3649 MH |
32 | Specify vmlinux path which has debuginfo (Dwarf binary). |
33 | ||
34 | -v:: | |
35 | --verbose:: | |
36 | Be more verbose (show parsed arguments, etc). | |
37 | ||
c43f9d1e | 38 | -a:: |
c937fe20 MH |
39 | --add=:: |
40 | Define a probe event (see PROBE SYNTAX for detail). | |
41 | ||
42 | -d:: | |
43 | --del=:: | |
ee391de8 MH |
44 | Delete probe events. This accepts glob wildcards('*', '?') and character |
45 | classes(e.g. [a-z], [!A-Z]). | |
c937fe20 MH |
46 | |
47 | -l:: | |
48 | --list:: | |
49 | List up current probe events. | |
595c3649 | 50 | |
631c9def MH |
51 | -L:: |
52 | --line=:: | |
53 | Show source code lines which can be probed. This needs an argument | |
ee391de8 MH |
54 | which specifies a range of the source code. (see LINE SYNTAX for detail) |
55 | ||
56 | -f:: | |
57 | --force:: | |
58 | Forcibly add events with existing name. | |
631c9def | 59 | |
595c3649 MH |
60 | PROBE SYNTAX |
61 | ------------ | |
62 | Probe points are defined by following syntax. | |
63 | ||
af663d75 | 64 | "[EVENT=]FUNC[+OFFS|:RLN|%return][@SRC]|SRC:ALN [ARG ...]" |
595c3649 | 65 | |
af663d75 | 66 | 'EVENT' specifies the name of new event, if omitted, it will be set the name of the probed function. Currently, event group name is set as 'probe'. |
c43f9d1e MH |
67 | 'FUNC' specifies a probed function name, and it may have one of the following options; '+OFFS' is the offset from function entry address in bytes, 'RLN' is the relative-line number from function entry line, and '%return' means that it probes function return. In addition, 'SRC' specifies a source file which has that function. |
68 | It is also possible to specify a probe point by the source line number by using 'SRC:ALN' syntax, where 'SRC' is the source file path and 'ALN' is the line number. | |
595c3649 MH |
69 | 'ARG' specifies the arguments of this probe point. You can use the name of local variable, or kprobe-tracer argument format (e.g. $retval, %ax, etc). |
70 | ||
631c9def MH |
71 | LINE SYNTAX |
72 | ----------- | |
73 | Line range is descripted by following syntax. | |
74 | ||
75 | "FUNC[:RLN[+NUM|:RLN2]]|SRC:ALN[+NUM|:ALN2]" | |
76 | ||
77 | FUNC specifies the function name of showing lines. 'RLN' is the start line | |
78 | number from function entry line, and 'RLN2' is the end line number. As same as | |
79 | probe syntax, 'SRC' means the source file path, 'ALN' is start line number, | |
80 | and 'ALN2' is end line number in the file. It is also possible to specify how | |
81 | many lines to show by using 'NUM'. | |
82 | So, "source.c:100-120" shows lines between 100th to l20th in source.c file. And "func:10+20" shows 20 lines from 10th line of func function. | |
83 | ||
ee391de8 MH |
84 | EXAMPLES |
85 | -------- | |
86 | Display which lines in schedule() can be probed: | |
87 | ||
88 | ./perf probe --line schedule | |
89 | ||
90 | Add a probe on schedule() function 12th line with recording cpu local variable: | |
91 | ||
92 | ./perf probe schedule:12 cpu | |
93 | or | |
94 | ./perf probe --add='schedule:12 cpu' | |
95 | ||
96 | this will add one or more probes which has the name start with "schedule". | |
97 | ||
98 | Delete all probes on schedule(). | |
99 | ||
100 | ./perf probe --del='schedule*' | |
101 | ||
102 | ||
595c3649 MH |
103 | SEE ALSO |
104 | -------- | |
105 | linkperf:perf-trace[1], linkperf:perf-record[1] |