From: Peter Maydell <peter.maydell@linaro.org>
To: qemu-devel@nongnu.org
Subject: [PULL 7/8] scripts/qemu-trace-stap: Convert documentation to rST
Date: Mon, 3 Feb 2020 11:13:17 +0000 [thread overview]
Message-ID: <20200203111318.23378-8-peter.maydell@linaro.org> (raw)
In-Reply-To: <20200203111318.23378-1-peter.maydell@linaro.org>
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
---
Makefile | 9 +-
MAINTAINERS | 1 +
docs/interop/conf.py | 4 +-
docs/interop/index.rst | 1 +
docs/interop/qemu-trace-stap.rst | 124 +++++++++++++++++++++++++++
scripts/qemu-trace-stap.texi | 140 -------------------------------
6 files changed, 134 insertions(+), 145 deletions(-)
create mode 100644 docs/interop/qemu-trace-stap.rst
delete mode 100644 scripts/qemu-trace-stap.texi
diff --git a/Makefile b/Makefile
index c9dc4422170..1e0440c3738 100644
--- a/Makefile
+++ b/Makefile
@@ -357,7 +357,7 @@ ifdef CONFIG_VIRTFS
DOCS+=fsdev/virtfs-proxy-helper.1
endif
ifdef CONFIG_TRACE_SYSTEMTAP
-DOCS+=scripts/qemu-trace-stap.1
+DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1
endif
else
DOCS=
@@ -848,7 +848,7 @@ ifeq ($(CONFIG_TOOLS),y)
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"
endif
ifdef CONFIG_TRACE_SYSTEMTAP
- $(INSTALL_DATA) scripts/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
+ $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
endif
ifneq (,$(findstring qemu-ga,$(TOOLS)))
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
@@ -1050,7 +1050,9 @@ $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)
$(call build-manual,system,html)
-$(call define-manpage-rule,interop,qemu-ga.8 qemu-img.1 qemu-nbd.8,$(SRC_PATH/qemu-img-cmds.hx))
+$(call define-manpage-rule,interop,\
+ qemu-ga.8 qemu-img.1 qemu-nbd.8 qemu-trace-stap.1,\
+ $(SRC_PATH/qemu-img-cmds.hx))
$(call define-manpage-rule,system,qemu-block-drivers.7)
@@ -1078,7 +1080,6 @@ qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi
qemu.1: qemu-option-trace.texi
fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
-scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi
html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
diff --git a/MAINTAINERS b/MAINTAINERS
index 80263385190..db3cbc18c92 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2193,6 +2193,7 @@ F: qemu-option-trace.texi
F: scripts/tracetool.py
F: scripts/tracetool/
F: scripts/qemu-trace-stap*
+F: docs/interop/qemu-trace-stap.rst
F: docs/devel/tracing.txt
T: git https://github.com/stefanha/qemu.git tracing
diff --git a/docs/interop/conf.py b/docs/interop/conf.py
index 0de444a900d..baea7fb50ee 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 5e4de07d4cc..d756a826b26 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 00000000000..fb70445c751
--- /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.
diff --git a/scripts/qemu-trace-stap.texi b/scripts/qemu-trace-stap.texi
deleted file mode 100644
index 07bb9eb94e7..00000000000
--- a/scripts/qemu-trace-stap.texi
+++ /dev/null
@@ -1,140 +0,0 @@
-@example
-@c man begin SYNOPSIS
-@command{qemu-trace-stap} @var{GLOBAL-OPTIONS} @var{COMMAND} @var{COMMAND-OPTIONS} @var{ARGS...}
-@c man end
-@end example
-
-@c man begin DESCRIPTION
-
-The @command{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 @command{stap}
-program.
-
-@c man end
-
-@c man begin OPTIONS
-
-The following global options may be used regardless of which command
-is executed:
-
-@table @option
-@item @var{--verbose}, @var{-v}
-
-Display verbose information about command execution.
-
-@end table
-
-The following commands are valid:
-
-@table @option
-
-@item @var{list} @var{BINARY} @var{PATTERN...}
-
-List all the probe names provided by @var{BINARY} that match
-@var{PATTERN}.
-
-If @var{BINARY} is not an absolute path, it will be located by searching
-the directories listed in the @code{$PATH} environment variable.
-
-@var{PATTERN} is a plain string that is used to filter the results of
-this command. It may optionally contain a @code{*} wildcard to facilitate
-matching multiple probes without listing each one explicitly. Multiple
-@var{PATTERN} arguments may be given, causing listing of probes that match
-any of the listed names. If no @var{PATTERN} is given, the all possible
-probes will be listed.
-
-For example, to list all probes available in the @command{qemu-system-x86_64}
-binary:
-
-@example
-$ qemu-trace-stap list qemu-system-x86_64
-@end example
-
-To filter the list to only cover probes related to QEMU's cryptographic
-subsystem, in a binary outside @code{$PATH}
-
-@example
-$ qemu-trace-stap list /opt/qemu/4.0.0/bin/qemu-system-x86_64 'qcrypto*'
-@end example
-
-
-@item @var{run} @var{OPTIONS} @var{BINARY} @var{PATTERN...}
-
-Run a trace session, printing formatted output any time a process that is
-executing @var{BINARY} triggers a probe matching @var{PATTERN}.
-
-If @var{BINARY} is not an absolute path, it will be located by searching
-the directories listed in the @code{$PATH} environment variable.
-
-@var{PATTERN} is a plain string that matches a probe name shown by the
-@var{list} command. It may optionally contain a @code{*} wildcard to
-facilitate matching multiple probes without listing each one explicitly.
-Multiple @var{PATTERN} arguments may be given, causing all matching probes
-to be monitored. At least one @var{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:
-
-@table @option
-@item @var{--pid=PID}, @var{-p PID}
-
-Restrict the tracing session so that it only triggers for the process
-identified by @code{PID}.
-
-@end table
-
-For example, to monitor all processes executing @command{qemu-system-x86_64}
-as found on $PATH, displaying all I/O related probes:
-
-@example
-$ qemu-trace-stap run qemu-system-x86_64 'qio*'
-@end example
-
-To monitor only the QEMU process with PID 1732
-
-@example
-$ qemu-trace-stap run --pid=1732 qemu-system-x86_64 'qio*'
-@end example
-
-To monitor QEMU processes running an alternative binary outside of
-@code{$PATH}, displaying verbose information about setup of the
-tracing environment:
-
-@example
-$ qemu-trace-stap -v run /opt/qemu/4.0.0/qemu-system-x86_64 'qio*'
-@end example
-
-@end table
-
-@c man end
-
-@ignore
-
-@setfilename qemu-trace-stap
-@settitle QEMU SystemTap trace tool
-
-@c man begin LICENSE
-
-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.
-
-@c man end
-
-@c man begin SEEALSO
-qemu(1), stap(1)
-@c man end
-
-@end ignore
--
2.20.1
next prev parent reply other threads:[~2020-02-03 11:14 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-03 11:13 [PULL 0/8] docs queue Peter Maydell
2020-02-03 11:13 ` [PULL 1/8] Makefile: Ensure we don't run Sphinx in parallel for manpages Peter Maydell
2020-02-03 11:13 ` [PULL 2/8] hxtool: Support SRST/ERST directives Peter Maydell
2020-02-03 11:13 ` [PULL 3/8] docs/sphinx: Add new hxtool Sphinx extension Peter Maydell
2020-02-03 11:13 ` [PULL 4/8] qemu-img-cmds.hx: Add rST documentation fragments Peter Maydell
2020-02-03 11:13 ` [PULL 5/8] qemu-img: Convert invocation documentation to rST Peter Maydell
2020-02-03 11:13 ` [PULL 6/8] qemu-img-cmds.hx: Remove texinfo document fragments Peter Maydell
2020-02-03 11:13 ` Peter Maydell [this message]
2020-02-03 11:13 ` [PULL 8/8] virtfs-proxy-helper: Convert documentation to rST Peter Maydell
2020-02-03 13:04 ` [PULL 0/8] docs queue Peter Maydell
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200203111318.23378-8-peter.maydell@linaro.org \
--to=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.