diff options
-rw-r--r-- | tools/perf/Documentation/perf-trace-perl.txt | 219 | ||||
-rw-r--r-- | tools/perf/Documentation/perf-trace.txt | 11 |
2 files changed, 229 insertions, 1 deletions
diff --git a/tools/perf/Documentation/perf-trace-perl.txt b/tools/perf/Documentation/perf-trace-perl.txt new file mode 100644 index 000000000000..c5f55f439091 --- /dev/null +++ b/tools/perf/Documentation/perf-trace-perl.txt | |||
@@ -0,0 +1,219 @@ | |||
1 | perf-trace-perl(1) | ||
2 | ================== | ||
3 | |||
4 | NAME | ||
5 | ---- | ||
6 | perf-trace-perl - Process trace data with a Perl script | ||
7 | |||
8 | SYNOPSIS | ||
9 | -------- | ||
10 | [verse] | ||
11 | 'perf trace' [-s [lang]:script[.ext] ] | ||
12 | |||
13 | DESCRIPTION | ||
14 | ----------- | ||
15 | |||
16 | This perf trace option is used to process perf trace data using perf's | ||
17 | built-in Perl interpreter. It reads and processes the input file and | ||
18 | displays the results of the trace analysis implemented in the given | ||
19 | Perl script, if any. | ||
20 | |||
21 | STARTER SCRIPTS | ||
22 | --------------- | ||
23 | |||
24 | You can avoid reading the rest of this document by running 'perf trace | ||
25 | -g perl' in the same directory as an existing perf.data trace file. | ||
26 | That will generate a starter script containing a handler for each of | ||
27 | the event types in the trace file; it simply prints every available | ||
28 | field for each event in the trace file. | ||
29 | |||
30 | You can also look at the existing scripts in | ||
31 | ~/libexec/perf-core/scripts/perl for typical examples showing how to | ||
32 | do basic things like aggregate event data, print results, etc. Also, | ||
33 | the check-perf-trace.pl script, while not interesting for its results, | ||
34 | attempts to exercise all of the main scripting features. | ||
35 | |||
36 | EVENT HANDLERS | ||
37 | -------------- | ||
38 | |||
39 | When perf trace is invoked using a trace script, a user-defined | ||
40 | 'handler function' is called for each event in the trace. If there's | ||
41 | no handler function defined for a given event type, the event is | ||
42 | ignored (or passed to a 'trace_handled' function, see below) and the | ||
43 | next event is processed. | ||
44 | |||
45 | Most of the event's field values are passed as arguments to the | ||
46 | handler function; some of the less common ones aren't - those are | ||
47 | available as calls back into the perf executable (see below). | ||
48 | |||
49 | As an example, the following perf record command can be used to record | ||
50 | all sched_wakeup events in the system: | ||
51 | |||
52 | # perf record -c 1 -f -a -M -R -e sched:sched_wakeup | ||
53 | |||
54 | Traces meant to be processed using a script should be recorded with | ||
55 | the above options: -c 1 says to sample every event, -a to enable | ||
56 | system-wide collection, -M to multiplex the output, and -R to collect | ||
57 | raw samples. | ||
58 | |||
59 | The format file for the sched_wakep event defines the following fields | ||
60 | (see /sys/kernel/debug/tracing/events/sched/sched_wakeup/format): | ||
61 | |||
62 | ---- | ||
63 | format: | ||
64 | field:unsigned short common_type; | ||
65 | field:unsigned char common_flags; | ||
66 | field:unsigned char common_preempt_count; | ||
67 | field:int common_pid; | ||
68 | field:int common_lock_depth; | ||
69 | |||
70 | field:char comm[TASK_COMM_LEN]; | ||
71 | field:pid_t pid; | ||
72 | field:int prio; | ||
73 | field:int success; | ||
74 | field:int target_cpu; | ||
75 | ---- | ||
76 | |||
77 | The handler function for this event would be defined as: | ||
78 | |||
79 | ---- | ||
80 | sub sched::sched_wakeup | ||
81 | { | ||
82 | my ($event_name, $context, $common_cpu, $common_secs, | ||
83 | $common_nsecs, $common_pid, $common_comm, | ||
84 | $comm, $pid, $prio, $success, $target_cpu) = @_; | ||
85 | } | ||
86 | ---- | ||
87 | |||
88 | The handler function takes the form subsystem::event_name. | ||
89 | |||
90 | The $common_* arguments in the handler's argument list are the set of | ||
91 | arguments passed to all event handlers; some of the fields correspond | ||
92 | to the common_* fields in the format file, but some are synthesized, | ||
93 | and some of the common_* fields aren't common enough to to be passed | ||
94 | to every event as arguments but are available as library functions. | ||
95 | |||
96 | Here's a brief description of each of the invariant event args: | ||
97 | |||
98 | $event_name the name of the event as text | ||
99 | $context an opaque 'cookie' used in calls back into perf | ||
100 | $common_cpu the cpu the event occurred on | ||
101 | $common_secs the secs portion of the event timestamp | ||
102 | $common_nsecs the nsecs portion of the event timestamp | ||
103 | $common_pid the pid of the current task | ||
104 | $common_comm the name of the current process | ||
105 | |||
106 | All of the remaining fields in the event's format file have | ||
107 | counterparts as handler function arguments of the same name, as can be | ||
108 | seen in the example above. | ||
109 | |||
110 | The above provides the basics needed to directly access every field of | ||
111 | every event in a trace, which covers 90% of what you need to know to | ||
112 | write a useful trace script. The sections below cover the rest. | ||
113 | |||
114 | SCRIPT LAYOUT | ||
115 | ------------- | ||
116 | |||
117 | Every perf trace Perl script should start by setting up a Perl module | ||
118 | search path and 'use'ing a few support modules (see module | ||
119 | descriptions below): | ||
120 | |||
121 | ---- | ||
122 | use lib "$ENV{'PERF_EXEC_PATH'}/scripts/perl/Perf-Trace-Util/lib"; | ||
123 | use lib "./Perf-Trace-Util/lib"; | ||
124 | use Perf::Trace::Core; | ||
125 | use Perf::Trace::Context; | ||
126 | use Perf::Trace::Util; | ||
127 | ---- | ||
128 | |||
129 | The rest of the script can contain handler functions and support | ||
130 | functions in any order. | ||
131 | |||
132 | Aside from the event handler functions discussed above, every script | ||
133 | can implement a set of optional functions: | ||
134 | |||
135 | *trace_begin*, if defined, is called before any event is processed and | ||
136 | gives scripts a chance to do setup tasks: | ||
137 | |||
138 | ---- | ||
139 | sub trace_begin | ||
140 | { | ||
141 | } | ||
142 | ---- | ||
143 | |||
144 | *trace_end*, if defined, is called after all events have been | ||
145 | processed and gives scripts a chance to do end-of-script tasks, such | ||
146 | as display results: | ||
147 | |||
148 | ---- | ||
149 | sub trace_end | ||
150 | { | ||
151 | } | ||
152 | ---- | ||
153 | |||
154 | *trace_unhandled*, if defined, is called after for any event that | ||
155 | doesn't have a handler explicitly defined for it. The standard set | ||
156 | of common arguments are passed into it: | ||
157 | |||
158 | ---- | ||
159 | sub trace_unhandled | ||
160 | { | ||
161 | my ($event_name, $context, $common_cpu, $common_secs, | ||
162 | $common_nsecs, $common_pid, $common_comm) = @_; | ||
163 | } | ||
164 | ---- | ||
165 | |||
166 | The remaining sections provide descriptions of each of the available | ||
167 | built-in perf trace Perl modules and their associated functions. | ||
168 | |||
169 | AVAILABLE MODULES AND FUNCTIONS | ||
170 | ------------------------------- | ||
171 | |||
172 | The following sections describe the functions and variables available | ||
173 | via the various Perf::Trace::* Perl modules. To use the functions and | ||
174 | variables from the given module, add the corresponding 'use | ||
175 | Perf::Trace::XXX' line to your perf trace script. | ||
176 | |||
177 | Perf::Trace::Core Module | ||
178 | ~~~~~~~~~~~~~~~~~~~~~~~~ | ||
179 | |||
180 | These functions provide some essential functions to user scripts. | ||
181 | |||
182 | The *flag_str* and *symbol_str* functions provide human-readable | ||
183 | strings for flag and symbolic fields. These correspond to the strings | ||
184 | and values parsed from the 'print fmt' fields of the event format | ||
185 | files: | ||
186 | |||
187 | flag_str($event_name, $field_name, $field_value) - returns the string represention corresponding to $field_value for the flag field $field_name of event $event_name | ||
188 | symbol_str($event_name, $field_name, $field_value) - returns the string represention corresponding to $field_value for the symbolic field $field_name of event $event_name | ||
189 | |||
190 | Perf::Trace::Context Module | ||
191 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
192 | |||
193 | Some of the 'common' fields in the event format file aren't all that | ||
194 | common, but need to be made accessible to user scripts nonetheless. | ||
195 | |||
196 | Perf::Trace::Context defines a set of functions that can be used to | ||
197 | access this data in the context of the current event. Each of these | ||
198 | functions expects a $context variable, which is the same as the | ||
199 | $context variable passed into every event handler as the second | ||
200 | argument. | ||
201 | |||
202 | common_pc($context) - returns common_preempt count for the current event | ||
203 | common_flags($context) - returns common_flags for the current event | ||
204 | common_lock_depth($context) - returns common_lock_depth for the current event | ||
205 | |||
206 | Perf::Trace::Util Module | ||
207 | ~~~~~~~~~~~~~~~~~~~~~~~~ | ||
208 | |||
209 | Various utility functions for use with perf trace: | ||
210 | |||
211 | nsecs($secs, $nsecs) - returns total nsecs given secs/nsecs pair | ||
212 | nsecs_secs($nsecs) - returns whole secs portion given nsecs | ||
213 | nsecs_nsecs($nsecs) - returns nsecs remainder given nsecs | ||
214 | nsecs_str($nsecs) - returns printable string in the form secs.nsecs | ||
215 | avg($total, $n) - returns average given a sum and a total number of values | ||
216 | |||
217 | SEE ALSO | ||
218 | -------- | ||
219 | linkperf:perf-trace[1] | ||
diff --git a/tools/perf/Documentation/perf-trace.txt b/tools/perf/Documentation/perf-trace.txt index 41ed75398ca9..07065efa60e0 100644 --- a/tools/perf/Documentation/perf-trace.txt +++ b/tools/perf/Documentation/perf-trace.txt | |||
@@ -20,6 +20,15 @@ OPTIONS | |||
20 | --dump-raw-trace=:: | 20 | --dump-raw-trace=:: |
21 | Display verbose dump of the trace data. | 21 | Display verbose dump of the trace data. |
22 | 22 | ||
23 | -s:: | ||
24 | --script=:: | ||
25 | Process trace data with the given script ([lang]:script[.ext]). | ||
26 | |||
27 | -g:: | ||
28 | --gen-script=:: | ||
29 | Generate perf-trace.[ext] starter script for given language, | ||
30 | using current perf.data. | ||
31 | |||
23 | SEE ALSO | 32 | SEE ALSO |
24 | -------- | 33 | -------- |
25 | linkperf:perf-record[1] | 34 | linkperf:perf-record[1], linkperf:perf-trace-perl[1] |