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
This commit is contained in:
parent
96ddefbc87
commit
605ffebb2e
|
@ -2193,6 +2193,7 @@ F: qemu-option-trace.texi
|
||||||
F: scripts/tracetool.py
|
F: scripts/tracetool.py
|
||||||
F: scripts/tracetool/
|
F: scripts/tracetool/
|
||||||
F: scripts/qemu-trace-stap*
|
F: scripts/qemu-trace-stap*
|
||||||
|
F: docs/interop/qemu-trace-stap.rst
|
||||||
F: docs/devel/tracing.txt
|
F: docs/devel/tracing.txt
|
||||||
T: git https://github.com/stefanha/qemu.git tracing
|
T: git https://github.com/stefanha/qemu.git tracing
|
||||||
|
|
||||||
|
|
9
Makefile
9
Makefile
|
@ -357,7 +357,7 @@ ifdef CONFIG_VIRTFS
|
||||||
DOCS+=fsdev/virtfs-proxy-helper.1
|
DOCS+=fsdev/virtfs-proxy-helper.1
|
||||||
endif
|
endif
|
||||||
ifdef CONFIG_TRACE_SYSTEMTAP
|
ifdef CONFIG_TRACE_SYSTEMTAP
|
||||||
DOCS+=scripts/qemu-trace-stap.1
|
DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1
|
||||||
endif
|
endif
|
||||||
else
|
else
|
||||||
DOCS=
|
DOCS=
|
||||||
|
@ -848,7 +848,7 @@ ifeq ($(CONFIG_TOOLS),y)
|
||||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"
|
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"
|
||||||
endif
|
endif
|
||||||
ifdef CONFIG_TRACE_SYSTEMTAP
|
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
|
endif
|
||||||
ifneq (,$(findstring qemu-ga,$(TOOLS)))
|
ifneq (,$(findstring qemu-ga,$(TOOLS)))
|
||||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
|
$(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)
|
$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)
|
||||||
$(call build-manual,system,html)
|
$(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)
|
$(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
|
qemu.1: qemu-option-trace.texi
|
||||||
fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
|
fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
|
||||||
docs/qemu-cpu-models.7: docs/qemu-cpu-models.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
|
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
|
info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
|
||||||
|
|
|
@ -22,5 +22,7 @@ man_pages = [
|
||||||
('qemu-img', 'qemu-img', u'QEMU disk image utility',
|
('qemu-img', 'qemu-img', u'QEMU disk image utility',
|
||||||
['Fabrice Bellard'], 1),
|
['Fabrice Bellard'], 1),
|
||||||
('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
|
('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)
|
||||||
]
|
]
|
||||||
|
|
|
@ -20,5 +20,6 @@ Contents:
|
||||||
qemu-ga
|
qemu-ga
|
||||||
qemu-img
|
qemu-img
|
||||||
qemu-nbd
|
qemu-nbd
|
||||||
|
qemu-trace-stap
|
||||||
vhost-user
|
vhost-user
|
||||||
vhost-user-gpu
|
vhost-user-gpu
|
||||||
|
|
|
@ -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.
|
|
@ -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
|
|
Loading…
Reference in New Issue