[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v2 7/8] scripts/qemu-trace-stap: Convert documentation to rST
From: |
Alex Bennée |
Subject: |
Re: [PATCH v2 7/8] scripts/qemu-trace-stap: Convert documentation to rST |
Date: |
Fri, 31 Jan 2020 15:15:47 +0000 |
User-agent: |
mu4e 1.3.7; emacs 27.0.60 |
Peter Maydell <address@hidden> 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 <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Tested-by: Alex Bennée <address@hidden>
> ---
> 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 <address@hidden>'], 8)
> + ['Anthony Liguori <address@hidden>'], 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
- Re: [PATCH v2 1/8] Makefile: Ensure we don't run Sphinx in parallel for manpages, (continued)
- [PATCH v2 2/8] hxtool: Support SRST/ERST directives, Peter Maydell, 2020/01/24
- [PATCH v2 3/8] docs/sphinx: Add new hxtool Sphinx extension, Peter Maydell, 2020/01/24
- [PATCH v2 4/8] qemu-img-cmds.hx: Add rST documentation fragments, Peter Maydell, 2020/01/24
- [PATCH v2 6/8] qemu-img-cmds.hx: Remove texinfo document fragments, Peter Maydell, 2020/01/24
- [PATCH v2 7/8] scripts/qemu-trace-stap: Convert documentation to rST, Peter Maydell, 2020/01/24
- Re: [PATCH v2 7/8] scripts/qemu-trace-stap: Convert documentation to rST,
Alex Bennée <=
- [PATCH v2 8/8] virtfs-proxy-helper: Convert documentation to rST, Peter Maydell, 2020/01/24
- [PATCH v2 5/8] qemu-img: Convert invocation documentation to rST, Peter Maydell, 2020/01/24
- Re: [PATCH v2 0/8] qemu-img, qemu-trace-stap, virtfs-proxy-helper: convert to rST, Peter Maydell, 2020/01/31