Add the rST versions of the documentation fragments. Once we've
converted fully from Texinfo to rST we can remove the ETEXI
fragments; for the moment we need both.
Note that most of the SRST fragments are 2-space indented so that the
'info foo' documentation entries appear as a sublist under the 'info'
entry in the top level list.
Again, all we need to do to put the documentation in the Sphinx manual
is a one-line hxtool-doc invocation.
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>
Message-id: 20200228153619.9906-22-peter.maydell@linaro.org
Add the rST versions of the documentation fragments. Once we've
converted fully from Texinfo to rST we can remove the ETEXI
fragments; for the moment we need both.
Since the only consumer of the hmp-commands hxtool documentation
is the HTML manual, all we need to do for the monitor command
documentation to appear in the Sphinx system manual is add the
one line that invokes the hxtool extension on the .hx file.
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>
Message-id: 20200228153619.9906-21-peter.maydell@linaro.org
Apart from targets.rst, which was written by hand, this is an automated
conversion obtained with the following command:
makeinfo --force -o - --docbook \
-D 'qemu_system_x86 QEMU_SYSTEM_X86_MACRO' \
-D 'qemu_system QEMU_SYSTEM_MACRO' \
$texi | pandoc -f docbook -t rst+smart | perl -e '
$/=undef;
$_ = <>;
s/^- − /- /gm;
s/QEMU_SYSTEM_MACRO/|qemu_system|/g;
s/QEMU_SYSTEM_X86_MACRO/|qemu_system_x86|/g;
s/(?=::\n\n +\|qemu)/.. parsed-literal/g;
s/:\n\n::$/::/gm;
print' > $rst
In addition, the following changes were made manually:
- target-i386.rst and target-mips.rst: replace CPU model documentation with
an include directive
- monitor.rst: replace the command section with a comment
- images.rst: add toctree
- target-arm.rst: Replace use of :math: (which Sphinx complains
about) with :sup:, and hide it behind |I2C| and |I2C| substitutions.
Content that is not @included remains exclusive to qemu-doc.texi.
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Reviewed-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>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-id: 20200228153619.9906-20-peter.maydell@linaro.org
Message-id: 20200226113034.6741-19-pbonzini@redhat.com
[PMM: Fixed target-arm.rst use of :math:; remove out of date
note about images.rst from commit message; fixed expansion
of |qemu_system_x86|; use parsed-literal in invocation.rst
when we want to use |qemu_system_x86|; fix incorrect subsection
level for "OS requirements" in target-i386.rst; fix incorrect
syntax for making links to other sections of the manual]
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
This doc was originally written by Daniel P. Berrangé
<berrange@redhat.com>, introduced via commit[1]: 2544e9e4aa (docs: add
guidance on configuring CPU models for x86, 2018-06-27).
In this patch:
- 1-1 conversion of Texinfo to rST, besides a couple of minor
tweaks that are too trivial to mention. (Thanks to Stephen
Finucane on IRC for the suggestion to use rST "definition lists"
instead of bullets in some places.)
Further modifications will be done via a separate patch.
- rST and related infra changes: manual page generation, Makefile
fixes, clean up references to qemu-cpu-models.texi, update year in
the copyright notice, etc.
[1] https://git.qemu.org/?p=qemu.git;a=commit;h=2544e9e4aa
As part of the conversion, we use a more generic 'author' attribution
for the manpage than we previously had, as agreed with the original
author Dan Berrange.
Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-id: 20200228153619.9906-16-peter.maydell@linaro.org
Message-id: 20200226113034.6741-15-pbonzini@redhat.com
[Move macros to defs.rst.inc, split in x86 and MIPS parts,
make qemu-cpu-models.rst a standalone document. - Paolo]
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
[PMM: Move defs.rst.inc setup to its own commit;
fix minor issues with MAINTAINERS file updates;
drop copyright date change; keep capitalization of
"QEMU Project developers" consistent with other uses;
minor Makefile fixups]
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Rather than accumulating generally useful rST substitution
definitions in individual rST files, create a defs.rst.inc where we
can define these. To start with it has the |qemu_system| definition
from qemu-block-drivers.rst.
Add a comment noting a pitfall where putting literal markup in the
definition of |qemu_system| makes it misrender manpage output; this
means the point-of-use must handle the literal markup (which is
almost always done by having it inside a parsed-literal block).
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Message-id: 20200228153619.9906-15-peter.maydell@linaro.org
Document the qemu command-line and qmp commands for continuous replication
Signed-off-by: Lukas Straub <lukasstraub2@web.de>
Signed-off-by: Jason Wang <jasowang@redhat.com>
For good reason, vhost-user is currently built asynchronously, that
way better performance can be obtained. However, for certain use
cases such as simulation, this is problematic.
Consider an event-based simulation in which both the device and CPU
have scheduled according to a simulation "calendar". Now, consider
the CPU sending I/O to the device, over a vring in the vhost-user
protocol. In this case, the CPU must wait for the vring interrupt
to have been processed by the device, so that the device is able to
put an entry onto the simulation calendar to obtain time to handle
the interrupt. Note that this doesn't mean the I/O is actually done
at this time, it just means that the handling of it is scheduled
before the CPU can continue running.
This cannot be done with the asynchronous eventfd based vring kick
and call design.
Extend the protocol slightly, so that a message can be used for kick
and call instead, if VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS is
negotiated. This in itself doesn't guarantee synchronisation, but both
sides can also negotiate VHOST_USER_PROTOCOL_F_REPLY_ACK and thus get
a reply to this message by setting the need_reply flag, and ensure
synchronisation this way.
To really use it in both directions, VHOST_USER_PROTOCOL_F_SLAVE_REQ
is also needed.
Since it is used for simulation purposes and too many messages on
the socket can lock up the virtual machine, document that this should
only be used together with the mentioned features.
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Message-Id: <20200123081708.7817-6-johannes@sipsolutions.net>
Reviewed-by: Michael S. Tsirkin <mst@redhat.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
The qemu-option-trace.rst.inc file contains a rST documentation
fragment which describes trace options common to qemu-nbd and
qemu-img. We put this file into interop/, but we'd like to move the
qemu-nbd and qemu-img files into the tools/ manual. We could move
the .rst.inc file along with them, but we're eventually going to want
to use it for the main QEMU binary options documentation too, and
that will be in system/. So move qemu-option-trace.rst.inc to the
top-level docs/ directory, where all these files can include it via
.. include:: ../qemu-option-trace.rst.inc
This does have the slight downside that we now need to explicitly
tell Make which manuals use this file rather than relying on
a wildcard for all .rst.inc in the manual.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Acked-by: Paolo Bonzini <pbonzini@redhat.com>
Message-id: 20200217155415.30949-3-peter.maydell@linaro.org
Some of the documentation for QEMU "tools" which are standalone
binaries like qemu-img is an awkward fit in our current 5-manual
split. We've put it into "interop", but they're not really
about interoperability.
Create a new top level manual "tools" which will be a better
home for this documentation. This commit creates an empty
initial manual; we will move the relevant documentation
files in a subsequent commit.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Acked-by: Paolo Bonzini <pbonzini@redhat.com>
Message-id: 20200217155415.30949-2-peter.maydell@linaro.org
In many cases the target of a convert operation is a newly provisioned
target that the user knows is blank (reads as zero). In this situation
there is no requirement for qemu-img to wastefully zero out the entire
device.
Add a new option, --target-is-zero, allowing the user to indicate that
an existing target device will return zeros for all reads.
Signed-off-by: David Edmondson <david.edmondson@oracle.com>
Message-Id: <20200205110248.2009589-2-david.edmondson@oracle.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Max Reitz <mreitz@redhat.com>
The patch adds a new additional field to the qcow2 header: compression_type,
which specifies compression type. If field is absent or zero, default
compression type is set: ZLIB, which corresponds to current behavior.
New compression type (ZSTD) is to be added in further commit.
Suggested-by: Denis Plotnikov <dplotnikov@virtuozzo.com>
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Message-Id: <20200131142219.3264-3-vsementsov@virtuozzo.com>
[mreitz: s/Bits 3-63: Reserved/Bits 4-63: Reserved/]
Signed-off-by: Max Reitz <mreitz@redhat.com>
Make it more obvious how to add new fields to the version 3 header and
how to interpret them.
The specification is adjusted so that for new defined optional fields:
1. Software may support some of these optional fields and ignore the
others, which means that features may be backported to downstream
Qemu independently.
2. If we want to add incompatible field (or a field, for which some of
its values would be incompatible), it must be accompanied by
incompatible feature bit.
Also the concept of "default is zero" is clarified, as it's strange to
say that the value of the field is assumed to be zero for the software
version which don't know about the field at all and don't know how to
treat it be it zero or not.
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20200131142219.3264-2-vsementsov@virtuozzo.com>
Reviewed-by: Alberto Garcia <berto@igalia.com>
[mreitz: s/some its/some of its/]
Signed-off-by: Max Reitz <mreitz@redhat.com>
Currently configure's has_sphinx_build() check simply runs a dummy
sphinx-build and either passes or fails. This means that "no
sphinx-build at all" and "sphinx-build exists but is too old" are
both reported the same way.
Further, we want to assume that all the Python we write is running
with at least Python 3.5; configure checks that for our scripts, but
Sphinx extensions run with whatever Python version sphinx-build
itself is using.
Add a check to our conf.py which makes sphinx-build fail if it would
be running our extensions with an old Python, and handle this
in configure so we can report failure helpfully to the user.
This will mean that configure --enable-docs will fail like this
if the sphinx-build provided is not suitable:
Warning: sphinx-build exists but it is either too old or uses too old a Python version
ERROR: User requested feature docs
configure was not able to find it.
Install texinfo, Perl/perl-podlators and a Python 3 version of python-sphinx
(As usual, the default is to simply not build the docs, as we would
if sphinx-build wasn't present at all.)
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Wainer dos Santos Moschetta <wainersm@redhat.com>
Message-Id: <20200213175647.17628-3-peter.maydell@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Document the virtiofsd(1) program and its command-line options. This
man page is a rST conversion of the original texi documentation that I
wrote.
Reviewed-by: Liam Merwick <liam.merwick@oracle.com>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
The qtests have recently been moved to a separate subdirectory, so
the paths that are mentioned in the documentation have to be adjusted
accordingly. And some of the iotests are now always run as part of
"make check", so this information has to be adjusted here, too.
Message-Id: <20200122134511.23806-1-thuth@redhat.com>
Signed-off-by: Thomas Huth <thuth@redhat.com>
The virtfs-proxy-helper documentation is currently in
fsdev/qemu-trace-stap.texi in Texinfo format, which we
present to the user as:
* a virtfs-proxy-helper 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 virtfs-proxy-helper manpage
* part of the interop/ Sphinx manual
There are minor formatting changes to suit Sphinx, but no
content changes. In particular I've split the -u and -g
options into each having their own description text.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Acked-by: Greg Kurz <groug@kaod.org>
Message-id: 20200124162606.8787-9-peter.maydell@linaro.org
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>
Message-id: 20200124162606.8787-8-peter.maydell@linaro.org
The qemu-img documentation is currently in qemu-nbd.texi in Texinfo
format, which we present to the user as:
* a qemu-img manpage
* a section of the main qemu-doc HTML documentation
Convert the documentation to rST format, and present it to the user as:
* a qemu-img manpage
* part of the interop/ Sphinx manual
The qemu-img rST document uses the new hxtool extension
to handle pulling rST fragments out of qemu-img-cmds.hx.
The documentation of the various options and commands is rather
muddled, with some options being described inside the relevant
command description and some in a more general section near the start
of the manual. All the command synopses are replicated in the .hx
file and then again in the manual. A lot of text is also duplicated
in the qemu-img.c code for the help text. I have not attempted to
deal with any of this, but have simply transposed the existing
structure into rST.
As usual, there are some minor formatting changes but no
textual changes, except that as with one or two other conversions
I have dropped the 'see also' section since it's not very
informative and looks odd in the HTML.
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>
Message-id: 20200124162606.8787-6-peter.maydell@linaro.org
Some of our documentation includes sections which are created
by assembling fragments of texinfo from a .hx source file into
a .texi file, which is then included from qemu-doc.texi or
qemu-img.texi.
For Sphinx, rather than creating a file to include, the most natural
way to handle this is to have a small custom Sphinx extension which
reads the .hx file and process it. So instead of:
* makefile produces foo.texi from foo.hx
* qemu-doc.texi says '@include foo.texi'
we have:
* qemu-doc.rst says 'hxtool-doc:: foo.hx'
* the Sphinx extension for hxtool has code that runs to handle that
Sphinx directive which reads the .hx file and emits the appropriate
documentation contents
This is pretty much the same way the kerneldoc extension works right
now. It also has the advantage that it should work for third-party
services like readthedocs that expect to build the docs directly with
sphinx rather than by invoking our makefiles.
In this commit we implement the hxtool extension.
Note that syntax errors in the rST fragments will be correctly
reported to the user with the filename and line number within the
hx file.
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>
Message-id: 20200124162606.8787-4-peter.maydell@linaro.org
Implement support for TPM on ppc64 by implementing the vTPM CRQ interface
as a frontend. It can use the tpm_emulator driver backend with the external
swtpm.
The Linux vTPM driver for ppc64 works with this emulation.
This TPM emulator also handles the TPM 2 case.
Signed-off-by: Stefan Berger <stefanb@linux.vnet.ibm.com>
Reviewed-by: David Gibson <david@gibson.dropbear.id.au>
Message-Id: <20200121152935.649898-4-stefanb@linux.ibm.com>
[dwg: Use device_class_set_props(), tweak Kconfig]
Signed-off-by: David Gibson <david@gibson.dropbear.id.au>
