mirror of
https://github.com/izzy2lost/xemu.git
synced 2026-07-06 00:20:22 -07:00
Merge remote-tracking branch 'remotes/pmaydell/tags/pull-docs-20200203' into staging
docs: * Fix Makefile concurrency bug where we could run Sphinx twice in parallel on the same manual (which makes it crash) * Support handling hxtool doc fragments for rST manuals * Convert qemu-img docs to rST * Convert qemu-trace-stap docs to rST * Convert virtfs-proxy-helper docs to rST # gpg: Signature made Mon 03 Feb 2020 11:11:44 GMT # gpg: using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE # gpg: issuer "peter.maydell@linaro.org" # gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [ultimate] # gpg: aka "Peter Maydell <pmaydell@gmail.com>" [ultimate] # gpg: aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [ultimate] # Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83 15CF 3C25 25ED 1436 0CDE * remotes/pmaydell/tags/pull-docs-20200203: virtfs-proxy-helper: Convert documentation to rST scripts/qemu-trace-stap: Convert documentation to rST qemu-img-cmds.hx: Remove texinfo document fragments qemu-img: Convert invocation documentation to rST qemu-img-cmds.hx: Add rST documentation fragments docs/sphinx: Add new hxtool Sphinx extension hxtool: Support SRST/ERST directives Makefile: Ensure we don't run Sphinx in parallel for manpages Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
This commit is contained in:
Peter Maydell
@@ -1574,6 +1574,7 @@ S: Odd Fixes
|
||||
F: hw/9pfs/
|
||||
X: hw/9pfs/xen-9p*
|
||||
F: fsdev/
|
||||
F: docs/interop/virtfs-proxy-helper.rst
|
||||
F: tests/qtest/virtio-9p-test.c
|
||||
T: git https://github.com/gkurz/qemu.git 9p-next
|
||||
|
||||
@@ -1834,6 +1835,7 @@ F: block/
|
||||
F: hw/block/
|
||||
F: include/block/
|
||||
F: qemu-img*
|
||||
F: docs/interop/qemu-img.rst
|
||||
F: qemu-io*
|
||||
F: tests/qemu-iotests/
|
||||
F: util/qemu-progress.c
|
||||
@@ -2192,6 +2194,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
|
||||
|
||||
|
||||
@@ -344,7 +344,8 @@ MANUAL_BUILDDIR := docs
|
||||
endif
|
||||
|
||||
ifdef BUILD_DOCS
|
||||
DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1
|
||||
DOCS=qemu-doc.html qemu-doc.txt qemu.1
|
||||
DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-img.1
|
||||
DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8
|
||||
DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8
|
||||
DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
|
||||
@@ -353,10 +354,10 @@ DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qe
|
||||
DOCS+=docs/qemu-cpu-models.7
|
||||
DOCS+=$(MANUAL_BUILDDIR)/index.html
|
||||
ifdef CONFIG_VIRTFS
|
||||
DOCS+=fsdev/virtfs-proxy-helper.1
|
||||
DOCS+=$(MANUAL_BUILDDIR)/interop/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=
|
||||
@@ -744,7 +745,7 @@ rm -f $(MANUAL_BUILDDIR)/$1/objects.inv $(MANUAL_BUILDDIR)/$1/searchindex.js $(M
|
||||
endef
|
||||
|
||||
distclean: clean
|
||||
rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi qemu-monitor-info.texi
|
||||
rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi
|
||||
rm -f tests/tcg/config-*.mak
|
||||
rm -f config-all-devices.mak config-all-disas.mak config.status
|
||||
rm -f $(SUBDIR_DEVICES_MAK)
|
||||
@@ -842,12 +843,12 @@ ifdef CONFIG_POSIX
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"
|
||||
ifeq ($(CONFIG_TOOLS),y)
|
||||
$(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-img.1 "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
|
||||
$(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"
|
||||
@@ -858,7 +859,7 @@ endif
|
||||
endif
|
||||
ifdef CONFIG_VIRTFS
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DATA) fsdev/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"
|
||||
endif
|
||||
|
||||
install-datadir:
|
||||
@@ -1028,11 +1029,19 @@ build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build $(if
|
||||
manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \
|
||||
$(wildcard $(SRC_PATH)/docs/$1/*.rst.inc) \
|
||||
$(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
|
||||
# Macro to write out the rule and dependencies for building manpages
|
||||
# Usage: $(call define-manpage-rule,manualname,manpage1 manpage2...[,extradeps])
|
||||
# 'extradeps' is optional, and specifies extra files (eg .hx files) that
|
||||
# the manual page depends on.
|
||||
define define-manpage-rule
|
||||
$(call atomic,$(foreach manpage,$2,$(MANUAL_BUILDDIR)/$1/$(manpage)),$(call manual-deps,$1) $3)
|
||||
$(call build-manual,$1,man)
|
||||
endef
|
||||
|
||||
$(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel)
|
||||
$(call build-manual,devel,html)
|
||||
|
||||
$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
|
||||
$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qemu-img-cmds.hx
|
||||
$(call build-manual,interop,html)
|
||||
|
||||
$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
|
||||
@@ -1041,14 +1050,11 @@ $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
|
||||
$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)
|
||||
$(call build-manual,system,html)
|
||||
|
||||
$(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop)
|
||||
$(call build-manual,interop,man)
|
||||
$(call define-manpage-rule,interop,\
|
||||
qemu-ga.8 qemu-img.1 qemu-nbd.8 qemu-trace-stap.1 virtfs-proxy-helper.1,\
|
||||
$(SRC_PATH/qemu-img-cmds.hx))
|
||||
|
||||
$(MANUAL_BUILDDIR)/interop/qemu-nbd.8: $(call manual-deps,interop)
|
||||
$(call build-manual,interop,man)
|
||||
|
||||
$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7: $(call manual-deps,system)
|
||||
$(call build-manual,system,man)
|
||||
$(call define-manpage-rule,system,qemu-block-drivers.7)
|
||||
|
||||
$(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h
|
||||
@mkdir -p "$(MANUAL_BUILDDIR)"
|
||||
@@ -1064,9 +1070,6 @@ qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx $(SRC_PATH)/scripts/hxtool
|
||||
qemu-monitor-info.texi: $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/scripts/hxtool
|
||||
$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")
|
||||
|
||||
qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/scripts/hxtool
|
||||
$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")
|
||||
|
||||
docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi
|
||||
@cp -p $< $@
|
||||
|
||||
@@ -1075,10 +1078,7 @@ docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi
|
||||
|
||||
qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi
|
||||
qemu.1: qemu-option-trace.texi
|
||||
qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.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
|
||||
@@ -1086,9 +1086,9 @@ pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
|
||||
txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
|
||||
|
||||
qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
|
||||
qemu-img.texi qemu-options.texi \
|
||||
qemu-options.texi \
|
||||
qemu-tech.texi qemu-option-trace.texi \
|
||||
qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi \
|
||||
qemu-deprecated.texi qemu-monitor.texi \
|
||||
qemu-monitor-info.texi \
|
||||
docs/qemu-cpu-models.texi docs/security.texi
|
||||
|
||||
|
||||
+2
-1
@@ -54,7 +54,7 @@ needs_sphinx = '1.3'
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = ['kerneldoc', 'qmp_lexer']
|
||||
extensions = ['kerneldoc', 'qmp_lexer', 'hxtool']
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
@@ -221,3 +221,4 @@ texinfo_documents = [
|
||||
# find everything.
|
||||
kerneldoc_bin = os.path.join(qemu_docdir, '../scripts/kernel-doc')
|
||||
kerneldoc_srctree = os.path.join(qemu_docdir, '..')
|
||||
hxtool_srctree = os.path.join(qemu_docdir, '..')
|
||||
|
||||
@@ -19,6 +19,13 @@ html_theme_options['description'] = u'System Emulation Management and Interopera
|
||||
man_pages = [
|
||||
('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',
|
||||
['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),
|
||||
('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),
|
||||
('virtfs-proxy-helper', 'virtfs-proxy-helper',
|
||||
u'QEMU 9p virtfs proxy filesystem helper',
|
||||
['M. Mohan Kumar'], 1)
|
||||
]
|
||||
|
||||
@@ -18,6 +18,9 @@ Contents:
|
||||
live-block-operations
|
||||
pr-helper
|
||||
qemu-ga
|
||||
qemu-img
|
||||
qemu-nbd
|
||||
qemu-trace-stap
|
||||
vhost-user
|
||||
vhost-user-gpu
|
||||
virtfs-proxy-helper
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -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.
|
||||
@@ -0,0 +1,72 @@
|
||||
QEMU 9p virtfs proxy filesystem helper
|
||||
======================================
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
|
||||
**virtfs-proxy-helper** [*OPTIONS*]
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
Pass-through security model in QEMU 9p server needs root privilege to do
|
||||
few file operations (like chown, chmod to any mode/uid:gid). There are two
|
||||
issues in pass-through security model:
|
||||
|
||||
- TOCTTOU vulnerability: Following symbolic links in the server could
|
||||
provide access to files beyond 9p export path.
|
||||
|
||||
- Running QEMU with root privilege could be a security issue.
|
||||
|
||||
To overcome above issues, following approach is used: A new filesystem
|
||||
type 'proxy' is introduced. Proxy FS uses chroot + socket combination
|
||||
for securing the vulnerability known with following symbolic links.
|
||||
Intention of adding a new filesystem type is to allow qemu to run
|
||||
in non-root mode, but doing privileged operations using socket IO.
|
||||
|
||||
Proxy helper (a stand alone binary part of qemu) is invoked with
|
||||
root privileges. Proxy helper chroots into 9p export path and creates
|
||||
a socket pair or a named socket based on the command line parameter.
|
||||
QEMU and proxy helper communicate using this socket. QEMU proxy fs
|
||||
driver sends filesystem request to proxy helper and receives the
|
||||
response from it.
|
||||
|
||||
The proxy helper is designed so that it can drop root privileges except
|
||||
for the capabilities needed for doing filesystem operations.
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
The following options are supported:
|
||||
|
||||
.. program:: virtfs-proxy-helper
|
||||
|
||||
.. option:: -h
|
||||
|
||||
Display help and exit
|
||||
|
||||
.. option:: -p, --path PATH
|
||||
|
||||
Path to export for proxy filesystem driver
|
||||
|
||||
.. option:: -f, --fd SOCKET_ID
|
||||
|
||||
Use given file descriptor as socket descriptor for communicating with
|
||||
qemu proxy fs drier. Usually a helper like libvirt will create
|
||||
socketpair and pass one of the fds as parameter to this option.
|
||||
|
||||
.. option:: -s, --socket SOCKET_FILE
|
||||
|
||||
Creates named socket file for communicating with qemu proxy fs driver
|
||||
|
||||
.. option:: -u, --uid UID
|
||||
|
||||
uid to give access to named socket file; used in combination with -g.
|
||||
|
||||
.. option:: -g, --gid GID
|
||||
|
||||
gid to give access to named socket file; used in combination with -u.
|
||||
|
||||
.. option:: -n, --nodaemon
|
||||
|
||||
Run as a normal program. By default program will run in daemon mode
|
||||
@@ -0,0 +1,210 @@
|
||||
# coding=utf-8
|
||||
#
|
||||
# QEMU hxtool .hx file parsing extension
|
||||
#
|
||||
# Copyright (c) 2020 Linaro
|
||||
#
|
||||
# This work is licensed under the terms of the GNU GPLv2 or later.
|
||||
# See the COPYING file in the top-level directory.
|
||||
"""hxtool is a Sphinx extension that implements the hxtool-doc directive"""
|
||||
|
||||
# The purpose of this extension is to read fragments of rST
|
||||
# from .hx files, and insert them all into the current document.
|
||||
# The rST fragments are delimited by SRST/ERST lines.
|
||||
# The conf.py file must set the hxtool_srctree config value to
|
||||
# the root of the QEMU source tree.
|
||||
# Each hxtool-doc:: directive takes one argument which is the
|
||||
# path of the .hx file to process, relative to the source tree.
|
||||
|
||||
import os
|
||||
import re
|
||||
from enum import Enum
|
||||
|
||||
from docutils import nodes
|
||||
from docutils.statemachine import ViewList
|
||||
from docutils.parsers.rst import directives, Directive
|
||||
from sphinx.errors import ExtensionError
|
||||
from sphinx.util.nodes import nested_parse_with_titles
|
||||
import sphinx
|
||||
|
||||
# Sphinx up to 1.6 uses AutodocReporter; 1.7 and later
|
||||
# use switch_source_input. Check borrowed from kerneldoc.py.
|
||||
Use_SSI = sphinx.__version__[:3] >= '1.7'
|
||||
if Use_SSI:
|
||||
from sphinx.util.docutils import switch_source_input
|
||||
else:
|
||||
from sphinx.ext.autodoc import AutodocReporter
|
||||
|
||||
__version__ = '1.0'
|
||||
|
||||
# We parse hx files with a state machine which may be in one of three
|
||||
# states: reading the C code fragment, inside a texi fragment,
|
||||
# or inside a rST fragment.
|
||||
class HxState(Enum):
|
||||
CTEXT = 1
|
||||
TEXI = 2
|
||||
RST = 3
|
||||
|
||||
def serror(file, lnum, errtext):
|
||||
"""Raise an exception giving a user-friendly syntax error message"""
|
||||
raise ExtensionError('%s line %d: syntax error: %s' % (file, lnum, errtext))
|
||||
|
||||
def parse_directive(line):
|
||||
"""Return first word of line, if any"""
|
||||
return re.split('\W', line)[0]
|
||||
|
||||
def parse_defheading(file, lnum, line):
|
||||
"""Handle a DEFHEADING directive"""
|
||||
# The input should be "DEFHEADING(some string)", though note that
|
||||
# the 'some string' could be the empty string. If the string is
|
||||
# empty we ignore the directive -- these are used only to add
|
||||
# blank lines in the plain-text content of the --help output.
|
||||
#
|
||||
# Return the heading text
|
||||
match = re.match(r'DEFHEADING\((.*)\)', line)
|
||||
if match is None:
|
||||
serror(file, lnum, "Invalid DEFHEADING line")
|
||||
return match.group(1)
|
||||
|
||||
def parse_archheading(file, lnum, line):
|
||||
"""Handle an ARCHHEADING directive"""
|
||||
# The input should be "ARCHHEADING(some string, other arg)",
|
||||
# though note that the 'some string' could be the empty string.
|
||||
# As with DEFHEADING, empty string ARCHHEADINGs will be ignored.
|
||||
#
|
||||
# Return the heading text
|
||||
match = re.match(r'ARCHHEADING\((.*),.*\)', line)
|
||||
if match is None:
|
||||
serror(file, lnum, "Invalid ARCHHEADING line")
|
||||
return match.group(1)
|
||||
|
||||
class HxtoolDocDirective(Directive):
|
||||
"""Extract rST fragments from the specified .hx file"""
|
||||
required_argument = 1
|
||||
optional_arguments = 1
|
||||
option_spec = {
|
||||
'hxfile': directives.unchanged_required
|
||||
}
|
||||
has_content = False
|
||||
|
||||
def run(self):
|
||||
env = self.state.document.settings.env
|
||||
hxfile = env.config.hxtool_srctree + '/' + self.arguments[0]
|
||||
|
||||
# Tell sphinx of the dependency
|
||||
env.note_dependency(os.path.abspath(hxfile))
|
||||
|
||||
state = HxState.CTEXT
|
||||
# We build up lines of rST in this ViewList, which we will
|
||||
# later put into a 'section' node.
|
||||
rstlist = ViewList()
|
||||
current_node = None
|
||||
node_list = []
|
||||
|
||||
with open(hxfile) as f:
|
||||
lines = (l.rstrip() for l in f)
|
||||
for lnum, line in enumerate(lines, 1):
|
||||
directive = parse_directive(line)
|
||||
|
||||
if directive == 'HXCOMM':
|
||||
pass
|
||||
elif directive == 'STEXI':
|
||||
if state == HxState.RST:
|
||||
serror(hxfile, lnum, 'expected ERST, found STEXI')
|
||||
elif state == HxState.TEXI:
|
||||
serror(hxfile, lnum, 'expected ETEXI, found STEXI')
|
||||
else:
|
||||
state = HxState.TEXI
|
||||
elif directive == 'ETEXI':
|
||||
if state == HxState.RST:
|
||||
serror(hxfile, lnum, 'expected ERST, found ETEXI')
|
||||
elif state == HxState.CTEXT:
|
||||
serror(hxfile, lnum, 'expected STEXI, found ETEXI')
|
||||
else:
|
||||
state = HxState.CTEXT
|
||||
elif directive == 'SRST':
|
||||
if state == HxState.RST:
|
||||
serror(hxfile, lnum, 'expected ERST, found SRST')
|
||||
elif state == HxState.TEXI:
|
||||
serror(hxfile, lnum, 'expected ETEXI, found SRST')
|
||||
else:
|
||||
state = HxState.RST
|
||||
elif directive == 'ERST':
|
||||
if state == HxState.TEXI:
|
||||
serror(hxfile, lnum, 'expected ETEXI, found ERST')
|
||||
elif state == HxState.CTEXT:
|
||||
serror(hxfile, lnum, 'expected SRST, found ERST')
|
||||
else:
|
||||
state = HxState.CTEXT
|
||||
elif directive == 'DEFHEADING' or directive == 'ARCHHEADING':
|
||||
if directive == 'DEFHEADING':
|
||||
heading = parse_defheading(hxfile, lnum, line)
|
||||
else:
|
||||
heading = parse_archheading(hxfile, lnum, line)
|
||||
if heading == "":
|
||||
continue
|
||||
# Put the accumulated rST into the previous node,
|
||||
# and then start a fresh section with this heading.
|
||||
if len(rstlist) > 0:
|
||||
if current_node is None:
|
||||
# We had some rST fragments before the first
|
||||
# DEFHEADING. We don't have a section to put
|
||||
# these in, so rather than magicing up a section,
|
||||
# make it a syntax error.
|
||||
serror(hxfile, lnum,
|
||||
'first DEFHEADING must precede all rST text')
|
||||
self.do_parse(rstlist, current_node)
|
||||
rstlist = ViewList()
|
||||
if current_node is not None:
|
||||
node_list.append(current_node)
|
||||
section_id = 'hxtool-%d' % env.new_serialno('hxtool')
|
||||
current_node = nodes.section(ids=[section_id])
|
||||
current_node += nodes.title(heading, heading)
|
||||
else:
|
||||
# Not a directive: put in output if we are in rST fragment
|
||||
if state == HxState.RST:
|
||||
# Sphinx counts its lines from 0
|
||||
rstlist.append(line, hxfile, lnum - 1)
|
||||
|
||||
if current_node is None:
|
||||
# We don't have multiple sections, so just parse the rst
|
||||
# fragments into a dummy node so we can return the children.
|
||||
current_node = nodes.section()
|
||||
self.do_parse(rstlist, current_node)
|
||||
return current_node.children
|
||||
else:
|
||||
# Put the remaining accumulated rST into the last section, and
|
||||
# return all the sections.
|
||||
if len(rstlist) > 0:
|
||||
self.do_parse(rstlist, current_node)
|
||||
node_list.append(current_node)
|
||||
return node_list
|
||||
|
||||
# This is from kerneldoc.py -- it works around an API change in
|
||||
# Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use
|
||||
# sphinx.util.nodes.nested_parse_with_titles() rather than the
|
||||
# plain self.state.nested_parse(), and so we can drop the saving
|
||||
# of title_styles and section_level that kerneldoc.py does,
|
||||
# because nested_parse_with_titles() does that for us.
|
||||
def do_parse(self, result, node):
|
||||
if Use_SSI:
|
||||
with switch_source_input(self.state, result):
|
||||
nested_parse_with_titles(self.state, result, node)
|
||||
else:
|
||||
save = self.state.memo.reporter
|
||||
self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
|
||||
try:
|
||||
nested_parse_with_titles(self.state, result, node)
|
||||
finally:
|
||||
self.state.memo.reporter = save
|
||||
|
||||
def setup(app):
|
||||
""" Register hxtool-doc directive with Sphinx"""
|
||||
app.add_config_value('hxtool_srctree', None, 'env')
|
||||
app.add_directive('hxtool-doc', HxtoolDocDirective)
|
||||
|
||||
return dict(
|
||||
version = __version__,
|
||||
parallel_read_safe = True,
|
||||
parallel_write_safe = True
|
||||
)
|
||||
@@ -1,63 +0,0 @@
|
||||
@example
|
||||
@c man begin SYNOPSIS
|
||||
@command{virtfs-proxy-helper} @var{options}
|
||||
@c man end
|
||||
@end example
|
||||
|
||||
@c man begin DESCRIPTION
|
||||
@table @description
|
||||
Pass-through security model in QEMU 9p server needs root privilege to do
|
||||
few file operations (like chown, chmod to any mode/uid:gid). There are two
|
||||
issues in pass-through security model
|
||||
|
||||
1) TOCTTOU vulnerability: Following symbolic links in the server could
|
||||
provide access to files beyond 9p export path.
|
||||
|
||||
2) Running QEMU with root privilege could be a security issue.
|
||||
|
||||
To overcome above issues, following approach is used: A new filesystem
|
||||
type 'proxy' is introduced. Proxy FS uses chroot + socket combination
|
||||
for securing the vulnerability known with following symbolic links.
|
||||
Intention of adding a new filesystem type is to allow qemu to run
|
||||
in non-root mode, but doing privileged operations using socket IO.
|
||||
|
||||
Proxy helper(a stand alone binary part of qemu) is invoked with
|
||||
root privileges. Proxy helper chroots into 9p export path and creates
|
||||
a socket pair or a named socket based on the command line parameter.
|
||||
QEMU and proxy helper communicate using this socket. QEMU proxy fs
|
||||
driver sends filesystem request to proxy helper and receives the
|
||||
response from it.
|
||||
|
||||
The proxy helper is designed so that it can drop root privileges except
|
||||
for the capabilities needed for doing filesystem operations.
|
||||
|
||||
@end table
|
||||
@c man end
|
||||
|
||||
@c man begin OPTIONS
|
||||
The following options are supported:
|
||||
@table @option
|
||||
@item -h
|
||||
@findex -h
|
||||
Display help and exit
|
||||
@item -p|--path path
|
||||
Path to export for proxy filesystem driver
|
||||
@item -f|--fd socket-id
|
||||
Use given file descriptor as socket descriptor for communicating with
|
||||
qemu proxy fs drier. Usually a helper like libvirt will create
|
||||
socketpair and pass one of the fds as parameter to -f|--fd
|
||||
@item -s|--socket socket-file
|
||||
Creates named socket file for communicating with qemu proxy fs driver
|
||||
@item -u|--uid uid -g|--gid gid
|
||||
uid:gid combination to give access to named socket file
|
||||
@item -n|--nodaemon
|
||||
Run as a normal program. By default program will run in daemon mode
|
||||
@end table
|
||||
@c man end
|
||||
|
||||
@setfilename virtfs-proxy-helper
|
||||
@settitle QEMU 9p virtfs proxy filesystem helper
|
||||
|
||||
@c man begin AUTHOR
|
||||
M. Mohan Kumar
|
||||
@c man end
|
||||
+3
-7
@@ -632,7 +632,6 @@ encrypted disk images.
|
||||
* disk_images_quickstart:: Quick start for disk image creation
|
||||
* disk_images_snapshot_mode:: Snapshot mode
|
||||
* vm_snapshots:: VM snapshots
|
||||
* qemu_img_invocation:: qemu-img Invocation
|
||||
@end menu
|
||||
|
||||
@node disk_images_quickstart
|
||||
@@ -646,7 +645,9 @@ where @var{myimage.img} is the disk image filename and @var{mysize} is its
|
||||
size in kilobytes. You can add an @code{M} suffix to give the size in
|
||||
megabytes and a @code{G} suffix for gigabytes.
|
||||
|
||||
See @ref{qemu_img_invocation} for more information.
|
||||
@c When this document is converted to rst we should make this into
|
||||
@c a proper linked reference to the qemu-img documentation again:
|
||||
See the qemu-img invocation documentation for more information.
|
||||
|
||||
@node disk_images_snapshot_mode
|
||||
@subsection Snapshot mode
|
||||
@@ -708,11 +709,6 @@ A few device drivers still have incomplete snapshot support so their
|
||||
state is not saved or restored properly (in particular USB).
|
||||
@end itemize
|
||||
|
||||
@node qemu_img_invocation
|
||||
@subsection @code{qemu-img} Invocation
|
||||
|
||||
@include qemu-img.texi
|
||||
|
||||
@node pcsys_network
|
||||
@section Network emulation
|
||||
|
||||
|
||||
+45
-54
@@ -1,102 +1,93 @@
|
||||
HXCOMM Keep the list of subcommands sorted by name.
|
||||
HXCOMM Use DEFHEADING() to define headings in both help text and texi
|
||||
HXCOMM Text between STEXI and ETEXI are copied to texi version and
|
||||
HXCOMM Text between SRST and ERST are copied to rST version and
|
||||
HXCOMM discarded from C version
|
||||
HXCOMM DEF(command, callback, arg_string) is used to construct
|
||||
HXCOMM command structures and help message.
|
||||
HXCOMM HXCOMM can be used for comments, discarded from both texi and C
|
||||
HXCOMM HXCOMM can be used for comments, discarded from both rST and C
|
||||
|
||||
HXCOMM When amending the TEXI sections, please remember to copy the usage
|
||||
HXCOMM When amending the rST sections, please remember to copy the usage
|
||||
HXCOMM over to the per-command sections in qemu-img.texi.
|
||||
|
||||
STEXI
|
||||
@table @option
|
||||
ETEXI
|
||||
|
||||
DEF("amend", img_amend,
|
||||
"amend [--object objectdef] [--image-opts] [-p] [-q] [-f fmt] [-t cache] -o options filename")
|
||||
STEXI
|
||||
@item amend [--object @var{objectdef}] [--image-opts] [-p] [-q] [-f @var{fmt}] [-t @var{cache}] -o @var{options} @var{filename}
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: amend [--object OBJECTDEF] [--image-opts] [-p] [-q] [-f FMT] [-t CACHE] -o OPTIONS FILENAME
|
||||
ERST
|
||||
|
||||
DEF("bench", img_bench,
|
||||
"bench [-c count] [-d depth] [-f fmt] [--flush-interval=flush_interval] [-n] [--no-drain] [-o offset] [--pattern=pattern] [-q] [-s buffer_size] [-S step_size] [-t cache] [-i aio] [-w] [-U] filename")
|
||||
STEXI
|
||||
@item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-interval=@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern=@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var{cache}] [-i @var{aio}] [-w] [-U] @var{filename}
|
||||
ETEXI
|
||||
|
||||
SRST
|
||||
.. option:: bench [-c COUNT] [-d DEPTH] [-f FMT] [--flush-interval=FLUSH_INTERVAL] [-n] [--no-drain] [-o OFFSET] [--pattern=PATTERN] [-q] [-s BUFFER_SIZE] [-S STEP_SIZE] [-t CACHE] [-i AIO] [-w] [-U] FILENAME
|
||||
ERST
|
||||
DEF("check", img_check,
|
||||
"check [--object objectdef] [--image-opts] [-q] [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename")
|
||||
STEXI
|
||||
@item check [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] [-U] @var{filename}
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: check [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [--output=OFMT] [-r [leaks | all]] [-T SRC_CACHE] [-U] FILENAME
|
||||
ERST
|
||||
|
||||
DEF("commit", img_commit,
|
||||
"commit [--object objectdef] [--image-opts] [-q] [-f fmt] [-t cache] [-b base] [-d] [-p] filename")
|
||||
STEXI
|
||||
@item commit [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename}
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: commit [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [-t CACHE] [-b BASE] [-d] [-p] FILENAME
|
||||
ERST
|
||||
|
||||
DEF("compare", img_compare,
|
||||
"compare [--object objectdef] [--image-opts] [-f fmt] [-F fmt] [-T src_cache] [-p] [-q] [-s] [-U] filename1 filename2")
|
||||
STEXI
|
||||
@item compare [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [-F @var{fmt}] [-T @var{src_cache}] [-p] [-q] [-s] [-U] @var{filename1} @var{filename2}
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: compare [--object OBJECTDEF] [--image-opts] [-f FMT] [-F FMT] [-T SRC_CACHE] [-p] [-q] [-s] [-U] FILENAME1 FILENAME2
|
||||
ERST
|
||||
|
||||
DEF("convert", img_convert,
|
||||
"convert [--object objectdef] [--image-opts] [--target-image-opts] [-U] [-C] [-c] [-p] [-q] [-n] [-f fmt] [-t cache] [-T src_cache] [-O output_fmt] [-B backing_file] [-o options] [-l snapshot_param] [-S sparse_size] [-m num_coroutines] [-W] [--salvage] filename [filename2 [...]] output_filename")
|
||||
STEXI
|
||||
@item convert [--object @var{objectdef}] [--image-opts] [--target-image-opts] [-U] [-C] [-c] [-p] [-q] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-O @var{output_fmt}] [-B @var{backing_file}] [-o @var{options}] [-l @var{snapshot_param}] [-S @var{sparse_size}] [-m @var{num_coroutines}] [-W] [--salvage] @var{filename} [@var{filename2} [...]] @var{output_filename}
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: convert [--object OBJECTDEF] [--image-opts] [--target-image-opts] [-U] [-C] [-c] [-p] [-q] [-n] [-f FMT] [-t CACHE] [-T SRC_CACHE] [-O OUTPUT_FMT] [-B BACKING_FILE] [-o OPTIONS] [-l SNAPSHOT_PARAM] [-S SPARSE_SIZE] [-m NUM_COROUTINES] [-W] [--salvage] FILENAME [FILENAME2 [...]] OUTPUT_FILENAME
|
||||
ERST
|
||||
|
||||
DEF("create", img_create,
|
||||
"create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size]")
|
||||
STEXI
|
||||
@item create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}]
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: create [--object OBJECTDEF] [-q] [-f FMT] [-b BACKING_FILE] [-F BACKING_FMT] [-u] [-o OPTIONS] FILENAME [SIZE]
|
||||
ERST
|
||||
|
||||
DEF("dd", img_dd,
|
||||
"dd [--image-opts] [-U] [-f fmt] [-O output_fmt] [bs=block_size] [count=blocks] [skip=blocks] if=input of=output")
|
||||
STEXI
|
||||
@item dd [--image-opts] [-U] [-f @var{fmt}] [-O @var{output_fmt}] [bs=@var{block_size}] [count=@var{blocks}] [skip=@var{blocks}] if=@var{input} of=@var{output}
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: dd [--image-opts] [-U] [-f FMT] [-O OUTPUT_FMT] [bs=BLOCK_SIZE] [count=BLOCKS] [skip=BLOCKS] if=INPUT of=OUTPUT
|
||||
ERST
|
||||
|
||||
DEF("info", img_info,
|
||||
"info [--object objectdef] [--image-opts] [-f fmt] [--output=ofmt] [--backing-chain] [-U] filename")
|
||||
STEXI
|
||||
@item info [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] [-U] @var{filename}
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: info [--object OBJECTDEF] [--image-opts] [-f FMT] [--output=OFMT] [--backing-chain] [-U] FILENAME
|
||||
ERST
|
||||
|
||||
DEF("map", img_map,
|
||||
"map [--object objectdef] [--image-opts] [-f fmt] [--output=ofmt] [-U] filename")
|
||||
STEXI
|
||||
@item map [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--output=@var{ofmt}] [-U] @var{filename}
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: map [--object OBJECTDEF] [--image-opts] [-f FMT] [--output=OFMT] [-U] FILENAME
|
||||
ERST
|
||||
|
||||
DEF("measure", img_measure,
|
||||
"measure [--output=ofmt] [-O output_fmt] [-o options] [--size N | [--object objectdef] [--image-opts] [-f fmt] [-l snapshot_param] filename]")
|
||||
STEXI
|
||||
@item measure [--output=@var{ofmt}] [-O @var{output_fmt}] [-o @var{options}] [--size @var{N} | [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [-l @var{snapshot_param}] @var{filename}]
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: measure [--output=OFMT] [-O OUTPUT_FMT] [-o OPTIONS] [--size N | [--object OBJECTDEF] [--image-opts] [-f FMT] [-l SNAPSHOT_PARAM] FILENAME]
|
||||
ERST
|
||||
|
||||
DEF("snapshot", img_snapshot,
|
||||
"snapshot [--object objectdef] [--image-opts] [-U] [-q] [-l | -a snapshot | -c snapshot | -d snapshot] filename")
|
||||
STEXI
|
||||
@item snapshot [--object @var{objectdef}] [--image-opts] [-U] [-q] [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot}] @var{filename}
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: snapshot [--object OBJECTDEF] [--image-opts] [-U] [-q] [-l | -a SNAPSHOT | -c SNAPSHOT | -d SNAPSHOT] FILENAME
|
||||
ERST
|
||||
|
||||
DEF("rebase", img_rebase,
|
||||
"rebase [--object objectdef] [--image-opts] [-U] [-q] [-f fmt] [-t cache] [-T src_cache] [-p] [-u] -b backing_file [-F backing_fmt] filename")
|
||||
STEXI
|
||||
@item rebase [--object @var{objectdef}] [--image-opts] [-U] [-q] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: rebase [--object OBJECTDEF] [--image-opts] [-U] [-q] [-f FMT] [-t CACHE] [-T SRC_CACHE] [-p] [-u] -b BACKING_FILE [-F BACKING_FMT] FILENAME
|
||||
ERST
|
||||
|
||||
DEF("resize", img_resize,
|
||||
"resize [--object objectdef] [--image-opts] [-f fmt] [--preallocation=prealloc] [-q] [--shrink] filename [+ | -]size")
|
||||
STEXI
|
||||
@item resize [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--preallocation=@var{prealloc}] [-q] [--shrink] @var{filename} [+ | -]@var{size}
|
||||
ETEXI
|
||||
|
||||
STEXI
|
||||
@end table
|
||||
ETEXI
|
||||
SRST
|
||||
.. option:: resize [--object OBJECTDEF] [--image-opts] [-f FMT] [--preallocation=PREALLOC] [-q] [--shrink] FILENAME [+ | -]SIZE
|
||||
ERST
|
||||
|
||||
-798
File diff suppressed because it is too large
Load Diff
@@ -399,3 +399,39 @@ GEN_SUBST = $(call quiet-command, \
|
||||
|
||||
%.json: %.json.in
|
||||
$(call GEN_SUBST)
|
||||
|
||||
# Support for building multiple output files by atomically executing
|
||||
# a single rule which depends on several input files (so the rule
|
||||
# will be executed exactly once, not once per output file, and
|
||||
# not multiple times in parallel.) For more explanation see:
|
||||
# https://www.cmcrossroads.com/article/atomic-rules-gnu-make
|
||||
|
||||
# Given a space-separated list of filenames, create the name of
|
||||
# a 'sentinel' file to use to indicate that they have been built.
|
||||
# We use fixed text on the end to avoid accidentally triggering
|
||||
# automatic pattern rules, and . on the start to make the file
|
||||
# not show up in ls output.
|
||||
sentinel = .$(subst $(SPACE),_,$(subst /,_,$1)).sentinel.
|
||||
|
||||
# Define an atomic rule that builds multiple outputs from multiple inputs.
|
||||
# To use:
|
||||
# $(call atomic,out1 out2 ...,in1 in2 ...)
|
||||
# <TAB>rule to do the operation
|
||||
#
|
||||
# Make 4.3 will have native support for this, and you would be able
|
||||
# to instead write:
|
||||
# out1 out2 ... &: in1 in2 ...
|
||||
# <TAB>rule to do the operation
|
||||
#
|
||||
# The way this works is that it creates a make rule
|
||||
# "out1 out2 ... : sentinel-file ; @:" which says that the sentinel
|
||||
# depends on the dependencies, and the rule to do that is "do nothing".
|
||||
# Then we have a rule
|
||||
# "sentinel-file : in1 in2 ..."
|
||||
# whose commands start with "touch sentinel-file" and then continue
|
||||
# with the rule text provided by the user of this 'atomic' function.
|
||||
# The foreach... is there to delete the sentinel file if any of the
|
||||
# output files don't exist, so that we correctly rebuild in that situation.
|
||||
atomic = $(eval $1: $(call sentinel,$1) ; @:) \
|
||||
$(call sentinel,$1) : $2 ; @touch $$@ \
|
||||
$(foreach t,$1,$(if $(wildcard $t),,$(shell rm -f $(call sentinel,$1))))
|
||||
|
||||
+32
-1
@@ -7,7 +7,7 @@ hxtoh()
|
||||
case $str in
|
||||
HXCOMM*)
|
||||
;;
|
||||
STEXI*|ETEXI*) flag=$(($flag^1))
|
||||
STEXI*|ETEXI*|SRST*|ERST*) flag=$(($flag^1))
|
||||
;;
|
||||
*)
|
||||
test $flag -eq 1 && printf "%s\n" "$str"
|
||||
@@ -27,12 +27,17 @@ print_texi_heading()
|
||||
hxtotexi()
|
||||
{
|
||||
flag=0
|
||||
rstflag=0
|
||||
line=1
|
||||
while read -r str; do
|
||||
case "$str" in
|
||||
HXCOMM*)
|
||||
;;
|
||||
STEXI*)
|
||||
if test $rstflag -eq 1 ; then
|
||||
printf "line %d: syntax error: expected ERST, found '%s'\n" "$line" "$str" >&2
|
||||
exit 1
|
||||
fi
|
||||
if test $flag -eq 1 ; then
|
||||
printf "line %d: syntax error: expected ETEXI, found '%s'\n" "$line" "$str" >&2
|
||||
exit 1
|
||||
@@ -40,12 +45,38 @@ hxtotexi()
|
||||
flag=1
|
||||
;;
|
||||
ETEXI*)
|
||||
if test $rstflag -eq 1 ; then
|
||||
printf "line %d: syntax error: expected ERST, found '%s'\n" "$line" "$str" >&2
|
||||
exit 1
|
||||
fi
|
||||
if test $flag -ne 1 ; then
|
||||
printf "line %d: syntax error: expected STEXI, found '%s'\n" "$line" "$str" >&2
|
||||
exit 1
|
||||
fi
|
||||
flag=0
|
||||
;;
|
||||
SRST*)
|
||||
if test $rstflag -eq 1 ; then
|
||||
printf "line %d: syntax error: expected ERST, found '%s'\n" "$line" "$str" >&2
|
||||
exit 1
|
||||
fi
|
||||
if test $flag -eq 1 ; then
|
||||
printf "line %d: syntax error: expected ETEXI, found '%s'\n" "$line" "$str" >&2
|
||||
exit 1
|
||||
fi
|
||||
rstflag=1
|
||||
;;
|
||||
ERST*)
|
||||
if test $flag -eq 1 ; then
|
||||
printf "line %d: syntax error: expected ETEXI, found '%s'\n" "$line" "$str" >&2
|
||||
exit 1
|
||||
fi
|
||||
if test $rstflag -ne 1 ; then
|
||||
printf "line %d: syntax error: expected SRST, found '%s'\n" "$line" "$str" >&2
|
||||
exit 1
|
||||
fi
|
||||
rstflag=0
|
||||
;;
|
||||
DEFHEADING*)
|
||||
print_texi_heading "$(expr "$str" : "DEFHEADING(\(.*\))")"
|
||||
;;
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user