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>
---
 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 <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

Peter Maydell <peter.maydell@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.maydell@linaro.org>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Tested-by: Alex Bennée <alex.bennee@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 <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


-- 
Alex Bennée