summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--tools/perf/Documentation/perf-trace.txt57
1 files changed, 49 insertions, 8 deletions
diff --git a/tools/perf/Documentation/perf-trace.txt b/tools/perf/Documentation/perf-trace.txt
index 122ec9dc4853..26aff6bf9e50 100644
--- a/tools/perf/Documentation/perf-trace.txt
+++ b/tools/perf/Documentation/perf-trace.txt
@@ -8,7 +8,11 @@ perf-trace - Read perf.data (created by perf record) and display trace output
SYNOPSIS
--------
[verse]
-'perf trace' {record <script> | report <script> [args] }
+'perf trace' [<options>]
+'perf trace' [<options>] record <script> [<record-options>] <command>
+'perf trace' [<options>] report <script> [script-args]
+'perf trace' [<options>] <script> <required-script-args> [<record-options>] <command>
+'perf trace' [<options>] <top-script> [script-args]
DESCRIPTION
-----------
@@ -24,23 +28,53 @@ There are several variants of perf trace:
available via 'perf trace -l'). The following variants allow you to
record and run those scripts:
- 'perf trace record <script>' to record the events required for 'perf
- trace report'. <script> is the name displayed in the output of
- 'perf trace --list' i.e. the actual script name minus any language
- extension.
+ 'perf trace record <script> <command>' to record the events required
+ for 'perf trace report'. <script> is the name displayed in the
+ output of 'perf trace --list' i.e. the actual script name minus any
+ language extension. If <command> is not specified, the events are
+ recorded using the -a (system-wide) 'perf record' option.
- 'perf trace report <script>' to run and display the results of
- <script>. <script> is the name displayed in the output of 'perf
+ 'perf trace report <script> [args]' to run and display the results
+ of <script>. <script> is the name displayed in the output of 'perf
trace --list' i.e. the actual script name minus any language
extension. The perf.data output from a previous run of 'perf trace
record <script>' is used and should be present for this command to
- succeed.
+ succeed. [args] refers to the (mainly optional) args expected by
+ the script.
+
+ 'perf trace <script> <required-script-args> <command>' to both
+ record the events required for <script> and to run the <script>
+ using 'live-mode' i.e. without writing anything to disk. <script>
+ is the name displayed in the output of 'perf trace --list' i.e. the
+ actual script name minus any language extension. If <command> is
+ not specified, the events are recorded using the -a (system-wide)
+ 'perf record' option. If <script> has any required args, they
+ should be specified before <command>. This mode doesn't allow for
+ optional script args to be specified; if optional script args are
+ desired, they can be specified using separate 'perf trace record'
+ and 'perf trace report' commands, with the stdout of the record step
+ piped to the stdin of the report script, using the '-o -' and '-i -'
+ options of the corresponding commands.
+
+ 'perf trace <top-script>' to both record the events required for
+ <top-script> and to run the <top-script> using 'live-mode'
+ i.e. without writing anything to disk. <top-script> is the name
+ displayed in the output of 'perf trace --list' i.e. the actual
+ script name minus any language extension; a <top-script> is defined
+ as any script name ending with the string 'top'.
+
+ [<record-options>] can be passed to the record steps of 'perf trace
+ record' and 'live-mode' variants; this isn't possible however for
+ <top-script> 'live-mode' or 'perf trace report' variants.
See the 'SEE ALSO' section for links to language-specific
information on how to write and run your own trace scripts.
OPTIONS
-------
+<command>...::
+ Any command you can specify in a shell.
+
-D::
--dump-raw-trace=::
Display verbose dump of the trace data.
@@ -64,6 +98,13 @@ OPTIONS
Generate perf-trace.[ext] starter script for given language,
using current perf.data.
+-a::
+ Force system-wide collection. Scripts run without a <command>
+ normally use -a by default, while scripts run with a <command>
+ normally don't - this option allows the latter to be run in
+ system-wide mode.
+
+
SEE ALSO
--------
linkperf:perf-record[1], linkperf:perf-trace-perl[1],