aboutsummaryrefslogtreecommitdiff
path: root/docs/interop
diff options
context:
space:
mode:
authorPeter Maydell <peter.maydell@linaro.org>2020-01-24 16:26:05 +0000
committerPeter Maydell <peter.maydell@linaro.org>2020-02-03 11:02:23 +0000
commit605ffebb2e206d9dec746ceed0de7be561b7354b (patch)
tree1bc8cd253484f932068443222d095e1c920213a5 /docs/interop
parent96ddefbc871895ed14b422d3571d61985165cf2a (diff)
scripts/qemu-trace-stap: Convert documentation to rST
The qemu-trace-stap documentation is currently in scripts/qemu-trace-stap.texi in Texinfo format, which we present to the user as: * a qemu-trace-stap manpage * but not (unusually for QEMU) part of the HTML docs Convert the documentation to rST format that lives in the docs/ subdirectory, and present it to the user as: * a qemu-trace-stap manpage * part of the interop/ Sphinx manual There are minor formatting changes to suit Sphinx, but no content changes. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Message-id: 20200124162606.8787-8-peter.maydell@linaro.org
Diffstat (limited to 'docs/interop')
-rw-r--r--docs/interop/conf.py4
-rw-r--r--docs/interop/index.rst1
-rw-r--r--docs/interop/qemu-trace-stap.rst124
3 files changed, 128 insertions, 1 deletions
diff --git a/docs/interop/conf.py b/docs/interop/conf.py
index 0de444a900..baea7fb50e 100644
--- a/docs/interop/conf.py
+++ b/docs/interop/conf.py
@@ -22,5 +22,7 @@ man_pages = [
('qemu-img', 'qemu-img', u'QEMU disk image utility',
['Fabrice Bellard'], 1),
('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
- ['Anthony Liguori <anthony@codemonkey.ws>'], 8)
+ ['Anthony Liguori <anthony@codemonkey.ws>'], 8),
+ ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
+ [], 1)
]
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index 5e4de07d4c..d756a826b2 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -20,5 +20,6 @@ Contents:
qemu-ga
qemu-img
qemu-nbd
+ qemu-trace-stap
vhost-user
vhost-user-gpu
diff --git a/docs/interop/qemu-trace-stap.rst b/docs/interop/qemu-trace-stap.rst
new file mode 100644
index 0000000000..fb70445c75
--- /dev/null
+++ b/docs/interop/qemu-trace-stap.rst
@@ -0,0 +1,124 @@
+QEMU SystemTap trace tool
+=========================
+
+Synopsis
+--------
+
+**qemu-trace-stap** [*GLOBAL-OPTIONS*] *COMMAND* [*COMMAND-OPTIONS*] *ARGS*...
+
+Description
+-----------
+
+The ``qemu-trace-stap`` program facilitates tracing of the execution
+of QEMU emulators using SystemTap.
+
+It is required to have the SystemTap runtime environment installed to use
+this program, since it is a wrapper around execution of the ``stap``
+program.
+
+Options
+-------
+
+.. program:: qemu-trace-stap
+
+The following global options may be used regardless of which command
+is executed:
+
+.. option:: --verbose, -v
+
+ Display verbose information about command execution.
+
+The following commands are valid:
+
+.. option:: list BINARY PATTERN...
+
+ List all the probe names provided by *BINARY* that match
+ *PATTERN*.
+
+ If *BINARY* is not an absolute path, it will be located by searching
+ the directories listed in the ``$PATH`` environment variable.
+
+ *PATTERN* is a plain string that is used to filter the results of
+ this command. It may optionally contain a ``*`` wildcard to facilitate
+ matching multiple probes without listing each one explicitly. Multiple
+ *PATTERN* arguments may be given, causing listing of probes that match
+ any of the listed names. If no *PATTERN* is given, the all possible
+ probes will be listed.
+
+ For example, to list all probes available in the ``qemu-system-x86_64``
+ binary:
+
+ ::
+
+ $ qemu-trace-stap list qemu-system-x86_64
+
+ To filter the list to only cover probes related to QEMU's cryptographic
+ subsystem, in a binary outside ``$PATH``
+
+ ::
+
+ $ qemu-trace-stap list /opt/qemu/4.0.0/bin/qemu-system-x86_64 'qcrypto*'
+
+.. option:: run OPTIONS BINARY PATTERN...
+
+ Run a trace session, printing formatted output any time a process that is
+ executing *BINARY* triggers a probe matching *PATTERN*.
+
+ If *BINARY* is not an absolute path, it will be located by searching
+ the directories listed in the ``$PATH`` environment variable.
+
+ *PATTERN* is a plain string that matches a probe name shown by the
+ *LIST* command. It may optionally contain a ``*`` wildcard to
+ facilitate matching multiple probes without listing each one explicitly.
+ Multiple *PATTERN* arguments may be given, causing all matching probes
+ to be monitored. At least one *PATTERN* is required, since stap is not
+ capable of tracing all known QEMU probes concurrently without overflowing
+ its trace buffer.
+
+ Invocation of this command does not need to be synchronized with
+ invocation of the QEMU process(es). It will match probes on all
+ existing running processes and all future launched processes,
+ unless told to only monitor a specific process.
+
+ Valid command specific options are:
+
+ .. program:: qemu-trace-stap-run
+
+ .. option:: --pid=PID, -p PID
+
+ Restrict the tracing session so that it only triggers for the process
+ identified by *PID*.
+
+ For example, to monitor all processes executing ``qemu-system-x86_64``
+ as found on ``$PATH``, displaying all I/O related probes:
+
+ ::
+
+ $ qemu-trace-stap run qemu-system-x86_64 'qio*'
+
+ To monitor only the QEMU process with PID 1732
+
+ ::
+
+ $ qemu-trace-stap run --pid=1732 qemu-system-x86_64 'qio*'
+
+ To monitor QEMU processes running an alternative binary outside of
+ ``$PATH``, displaying verbose information about setup of the
+ tracing environment:
+
+ ::
+
+ $ qemu-trace-stap -v run /opt/qemu/4.0.0/qemu-system-x86_64 'qio*'
+
+See also
+--------
+
+:manpage:`qemu(1)`, :manpage:`stap(1)`
+
+..
+ Copyright (C) 2019 Red Hat, Inc.
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.