Merge remote-tracking branch 'remotes/stefanha/tags/block-pull-request' into staging
[qemu/ar7.git] / scripts / qemu-trace-stap.texi
blob07bb9eb94e7f2e4929a58becfdf0c5e12dd9eed9
1 @example
2 @c man begin SYNOPSIS
3 @command{qemu-trace-stap} @var{GLOBAL-OPTIONS} @var{COMMAND} @var{COMMAND-OPTIONS} @var{ARGS...}
4 @c man end
5 @end example
7 @c man begin DESCRIPTION
9 The @command{qemu-trace-stap} program facilitates tracing of the execution
10 of QEMU emulators using SystemTap.
12 It is required to have the SystemTap runtime environment installed to use
13 this program, since it is a wrapper around execution of the @command{stap}
14 program.
16 @c man end
18 @c man begin OPTIONS
20 The following global options may be used regardless of which command
21 is executed:
23 @table @option
24 @item @var{--verbose}, @var{-v}
26 Display verbose information about command execution.
28 @end table
30 The following commands are valid:
32 @table @option
34 @item @var{list} @var{BINARY} @var{PATTERN...}
36 List all the probe names provided by @var{BINARY} that match
37 @var{PATTERN}.
39 If @var{BINARY} is not an absolute path, it will be located by searching
40 the directories listed in the @code{$PATH} environment variable.
42 @var{PATTERN} is a plain string that is used to filter the results of
43 this command. It may optionally contain a @code{*} wildcard to facilitate
44 matching multiple probes without listing each one explicitly. Multiple
45 @var{PATTERN} arguments may be given, causing listing of probes that match
46 any of the listed names. If no @var{PATTERN} is given, the all possible
47 probes will be listed.
49 For example, to list all probes available in the @command{qemu-system-x86_64}
50 binary:
52 @example
53 $ qemu-trace-stap list qemu-system-x86_64
54 @end example
56 To filter the list to only cover probes related to QEMU's cryptographic
57 subsystem, in a binary outside @code{$PATH}
59 @example
60 $ qemu-trace-stap list /opt/qemu/4.0.0/bin/qemu-system-x86_64 'qcrypto*'
61 @end example
64 @item @var{run} @var{OPTIONS} @var{BINARY} @var{PATTERN...}
66 Run a trace session, printing formatted output any time a process that is
67 executing @var{BINARY} triggers a probe matching @var{PATTERN}.
69 If @var{BINARY} is not an absolute path, it will be located by searching
70 the directories listed in the @code{$PATH} environment variable.
72 @var{PATTERN} is a plain string that matches a probe name shown by the
73 @var{list} command. It may optionally contain a @code{*} wildcard to
74 facilitate matching multiple probes without listing each one explicitly.
75 Multiple @var{PATTERN} arguments may be given, causing all matching probes
76 to be monitored. At least one @var{PATTERN} is required, since stap is not
77 capable of tracing all known QEMU probes concurrently without overflowing
78 its trace buffer.
80 Invocation of this command does not need to be synchronized with
81 invocation of the QEMU process(es). It will match probes on all
82 existing running processes and all future launched processes,
83 unless told to only monitor a specific process.
85 Valid command specific options are:
87 @table @option
88 @item @var{--pid=PID}, @var{-p PID}
90 Restrict the tracing session so that it only triggers for the process
91 identified by @code{PID}.
93 @end table
95 For example, to monitor all processes executing @command{qemu-system-x86_64}
96 as found on $PATH, displaying all I/O related probes:
98 @example
99 $ qemu-trace-stap run qemu-system-x86_64 'qio*'
100 @end example
102 To monitor only the QEMU process with PID 1732
104 @example
105 $ qemu-trace-stap run --pid=1732 qemu-system-x86_64 'qio*'
106 @end example
108 To monitor QEMU processes running an alternative binary outside of
109 @code{$PATH}, displaying verbose information about setup of the
110 tracing environment:
112 @example
113 $ qemu-trace-stap -v run /opt/qemu/4.0.0/qemu-system-x86_64 'qio*'
114 @end example
116 @end table
118 @c man end
120 @ignore
122 @setfilename qemu-trace-stap
123 @settitle QEMU SystemTap trace tool
125 @c man begin LICENSE
127 Copyright (C) 2019 Red Hat, Inc.
129 This program is free software; you can redistribute it and/or modify
130 it under the terms of the GNU General Public License as published by
131 the Free Software Foundation; either version 2 of the License, or
132 # (at your option) any later version.
134 @c man end
136 @c man begin SEEALSO
137 qemu(1), stap(1)
138 @c man end
140 @end ignore