Commit 605ffebb authored by Peter Maydell's avatar Peter Maydell
Browse files

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: default avatarPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: default avatarAlex Bennée <alex.bennee@linaro.org>
Tested-by: default avatarAlex Bennée <alex.bennee@linaro.org>
Message-id: 20200124162606.8787-8-peter.maydell@linaro.org
parent 96ddefbc

MAINTAINERS

+1 −0
Original line number Diff line number Diff line
@@ -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

Makefile

+5 −4
Original line number Diff line number Diff line
@@ -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

docs/interop/conf.py

+3 −1
Original line number Diff line number Diff line
@@ -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)

]

docs/interop/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -20,5 +20,6 @@ Contents: 
   qemu-ga

   qemu-img

   qemu-nbd

   qemu-trace-stap

   vhost-user

   vhost-user-gpu

docs/interop/qemu-trace-stap.rst

0 → 100644
+124 −0
Original line number Diff line number Diff line 
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.