diff options
author | Tom Zanussi <tom.zanussi@linux.intel.com> | 2010-11-10 09:19:35 -0500 |
---|---|---|
committer | Tom Zanussi <tom.zanussi@linux.intel.com> | 2010-11-10 09:19:35 -0500 |
commit | d3c4f798ac4b7337b417467f36f4b2e6dcb49240 (patch) | |
tree | 3ee6581672aa90a0bb25d4775e9357dda3a86d71 /tools/perf/Documentation/perf-trace.txt | |
parent | b5b8731219ddd007c229feacbfe745d1be070e6a (diff) |
perf trace: update Documentation with new perf trace variants
Add documentation describing new 'perf trace' command changes
e.g. <command> handling and live-mode/top variants.
Signed-off-by: Tom Zanussi <tom.zanussi@linux.intel.com>
Acked-by: Arnaldo Carvalho de Melo <acme@ghostprotocols.net>
Diffstat (limited to 'tools/perf/Documentation/perf-trace.txt')
-rw-r--r-- | tools/perf/Documentation/perf-trace.txt | 57 |
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 | |||
8 | SYNOPSIS | 8 | SYNOPSIS |
9 | -------- | 9 | -------- |
10 | [verse] | 10 | [verse] |
11 | 'perf trace' {record <script> | report <script> [args] } | 11 | 'perf trace' [<options>] |
12 | 'perf trace' [<options>] record <script> [<record-options>] <command> | ||
13 | 'perf trace' [<options>] report <script> [script-args] | ||
14 | 'perf trace' [<options>] <script> <required-script-args> [<record-options>] <command> | ||
15 | 'perf trace' [<options>] <top-script> [script-args] | ||
12 | 16 | ||
13 | DESCRIPTION | 17 | DESCRIPTION |
14 | ----------- | 18 | ----------- |
@@ -24,23 +28,53 @@ There are several variants of perf trace: | |||
24 | available via 'perf trace -l'). The following variants allow you to | 28 | available via 'perf trace -l'). The following variants allow you to |
25 | record and run those scripts: | 29 | record and run those scripts: |
26 | 30 | ||
27 | 'perf trace record <script>' to record the events required for 'perf | 31 | 'perf trace record <script> <command>' to record the events required |
28 | trace report'. <script> is the name displayed in the output of | 32 | for 'perf trace report'. <script> is the name displayed in the |
29 | 'perf trace --list' i.e. the actual script name minus any language | 33 | output of 'perf trace --list' i.e. the actual script name minus any |
30 | extension. | 34 | language extension. If <command> is not specified, the events are |
35 | recorded using the -a (system-wide) 'perf record' option. | ||
31 | 36 | ||
32 | 'perf trace report <script>' to run and display the results of | 37 | 'perf trace report <script> [args]' to run and display the results |
33 | <script>. <script> is the name displayed in the output of 'perf | 38 | of <script>. <script> is the name displayed in the output of 'perf |
34 | trace --list' i.e. the actual script name minus any language | 39 | trace --list' i.e. the actual script name minus any language |
35 | extension. The perf.data output from a previous run of 'perf trace | 40 | extension. The perf.data output from a previous run of 'perf trace |
36 | record <script>' is used and should be present for this command to | 41 | record <script>' is used and should be present for this command to |
37 | succeed. | 42 | succeed. [args] refers to the (mainly optional) args expected by |
43 | the script. | ||
44 | |||
45 | 'perf trace <script> <required-script-args> <command>' to both | ||
46 | record the events required for <script> and to run the <script> | ||
47 | using 'live-mode' i.e. without writing anything to disk. <script> | ||
48 | is the name displayed in the output of 'perf trace --list' i.e. the | ||
49 | actual script name minus any language extension. If <command> is | ||
50 | not specified, the events are recorded using the -a (system-wide) | ||
51 | 'perf record' option. If <script> has any required args, they | ||
52 | should be specified before <command>. This mode doesn't allow for | ||
53 | optional script args to be specified; if optional script args are | ||
54 | desired, they can be specified using separate 'perf trace record' | ||
55 | and 'perf trace report' commands, with the stdout of the record step | ||
56 | piped to the stdin of the report script, using the '-o -' and '-i -' | ||
57 | options of the corresponding commands. | ||
58 | |||
59 | 'perf trace <top-script>' to both record the events required for | ||
60 | <top-script> and to run the <top-script> using 'live-mode' | ||
61 | i.e. without writing anything to disk. <top-script> is the name | ||
62 | displayed in the output of 'perf trace --list' i.e. the actual | ||
63 | script name minus any language extension; a <top-script> is defined | ||
64 | as any script name ending with the string 'top'. | ||
65 | |||
66 | [<record-options>] can be passed to the record steps of 'perf trace | ||
67 | record' and 'live-mode' variants; this isn't possible however for | ||
68 | <top-script> 'live-mode' or 'perf trace report' variants. | ||
38 | 69 | ||
39 | See the 'SEE ALSO' section for links to language-specific | 70 | See the 'SEE ALSO' section for links to language-specific |
40 | information on how to write and run your own trace scripts. | 71 | information on how to write and run your own trace scripts. |
41 | 72 | ||
42 | OPTIONS | 73 | OPTIONS |
43 | ------- | 74 | ------- |
75 | <command>...:: | ||
76 | Any command you can specify in a shell. | ||
77 | |||
44 | -D:: | 78 | -D:: |
45 | --dump-raw-trace=:: | 79 | --dump-raw-trace=:: |
46 | Display verbose dump of the trace data. | 80 | Display verbose dump of the trace data. |
@@ -64,6 +98,13 @@ OPTIONS | |||
64 | Generate perf-trace.[ext] starter script for given language, | 98 | Generate perf-trace.[ext] starter script for given language, |
65 | using current perf.data. | 99 | using current perf.data. |
66 | 100 | ||
101 | -a:: | ||
102 | Force system-wide collection. Scripts run without a <command> | ||
103 | normally use -a by default, while scripts run with a <command> | ||
104 | normally don't - this option allows the latter to be run in | ||
105 | system-wide mode. | ||
106 | |||
107 | |||
67 | SEE ALSO | 108 | SEE ALSO |
68 | -------- | 109 | -------- |
69 | linkperf:perf-record[1], linkperf:perf-trace-perl[1], | 110 | linkperf:perf-record[1], linkperf:perf-trace-perl[1], |