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 6 7@c man begin DESCRIPTION 8 9The @command{qemu-trace-stap} program facilitates tracing of the execution 10of QEMU emulators using SystemTap. 11 12It is required to have the SystemTap runtime environment installed to use 13this program, since it is a wrapper around execution of the @command{stap} 14program. 15 16@c man end 17 18@c man begin OPTIONS 19 20The following global options may be used regardless of which command 21is executed: 22 23@table @option 24@item @var{--verbose}, @var{-v} 25 26Display verbose information about command execution. 27 28@end table 29 30The following commands are valid: 31 32@table @option 33 34@item @var{list} @var{BINARY} @var{PATTERN...} 35 36List all the probe names provided by @var{BINARY} that match 37@var{PATTERN}. 38 39If @var{BINARY} is not an absolute path, it will be located by searching 40the directories listed in the @code{$PATH} environment variable. 41 42@var{PATTERN} is a plain string that is used to filter the results of 43this command. It may optionally contain a @code{*} wildcard to facilitate 44matching multiple probes without listing each one explicitly. Multiple 45@var{PATTERN} arguments may be given, causing listing of probes that match 46any of the listed names. If no @var{PATTERN} is given, the all possible 47probes will be listed. 48 49For example, to list all probes available in the @command{qemu-system-x86_64} 50binary: 51 52@example 53$ qemu-trace-stap list qemu-system-x86_64 54@end example 55 56To filter the list to only cover probes related to QEMU's cryptographic 57subsystem, in a binary outside @code{$PATH} 58 59@example 60$ qemu-trace-stap list /opt/qemu/4.0.0/bin/qemu-system-x86_64 'qcrypto*' 61@end example 62 63 64@item @var{run} @var{OPTIONS} @var{BINARY} @var{PATTERN...} 65 66Run a trace session, printing formatted output any time a process that is 67executing @var{BINARY} triggers a probe matching @var{PATTERN}. 68 69If @var{BINARY} is not an absolute path, it will be located by searching 70the directories listed in the @code{$PATH} environment variable. 71 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 74facilitate matching multiple probes without listing each one explicitly. 75Multiple @var{PATTERN} arguments may be given, causing all matching probes 76to be monitored. At least one @var{PATTERN} is required, since stap is not 77capable of tracing all known QEMU probes concurrently without overflowing 78its trace buffer. 79 80Invocation of this command does not need to be synchronized with 81invocation of the QEMU process(es). It will match probes on all 82existing running processes and all future launched processes, 83unless told to only monitor a specific process. 84 85Valid command specific options are: 86 87@table @option 88@item @var{--pid=PID}, @var{-p PID} 89 90Restrict the tracing session so that it only triggers for the process 91identified by @code{PID}. 92 93@end table 94 95For example, to monitor all processes executing @command{qemu-system-x86_64} 96as found on $PATH, displaying all I/O related probes: 97 98@example 99$ qemu-trace-stap run qemu-system-x86_64 'qio*' 100@end example 101 102To monitor only the QEMU process with PID 1732 103 104@example 105$ qemu-trace-stap run --pid=1732 qemu-system-x86_64 'qio*' 106@end example 107 108To monitor QEMU processes running an alternative binary outside of 109@code{$PATH}, displaying verbose information about setup of the 110tracing environment: 111 112@example 113$ qemu-trace-stap -v run /opt/qemu/4.0.0/qemu-system-x86_64 'qio*' 114@end example 115 116@end table 117 118@c man end 119 120@ignore 121 122@setfilename qemu-trace-stap 123@settitle QEMU SystemTap trace tool 124 125@c man begin LICENSE 126 127Copyright (C) 2019 Red Hat, Inc. 128 129This program is free software; you can redistribute it and/or modify 130it under the terms of the GNU General Public License as published by 131the Free Software Foundation; either version 2 of the License, or 132# (at your option) any later version. 133 134@c man end 135 136@c man begin SEEALSO 137qemu(1), stap(1) 138@c man end 139 140@end ignore 141