Peter Maydell <peter.mayd...@linaro.org> writes:
> 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.mayd...@linaro.org> Reviewed-by: Alex Bennée <alex.ben...@linaro.org> Tested-by: Alex Bennée <alex.ben...@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 4e1a5e9906c..5dded94bf63 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 39423cd07f2..54c4429069d 100644 > --- a/MAINTAINERS > +++ b/MAINTAINERS > @@ -2191,6 +2191,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 <anth...@codemonkey.ws>'], 8) > + ['Anthony Liguori <anth...@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 -- Alex Bennée
