Currently the documentation for Arm system emulator targets is in a
single target-arm.rst. This describes only some of the boards and
often in a fairly abbreviated fashion. Restructure it so that each
board has its own documentation file in the docs/system/arm/
subdirectory.
This will hopefully encourage us to write board documentation that
describes the board in detail, rather than a few brief paragraphs
in a single long page. The table of contents should also help users
to find the board they care about faster.
Once the structure is in place we'll be able to move microvm.rst
from the top-level docs/ directory.
All the text from the old page is retained, except for the final
paragraph ("A Linux 2.6 test image is available on the QEMU web site.
More information is available in the QEMU mailing-list archive."),
which is deleted. The git history shows this was originally added
in reference to the integratorcp board (at that time the only
Arm board that was supported), and has subsequently gradually been
further and further separated from the integratorcp documentation
by the insertion of other board documentation sections. It's
extremely out of date and no longer accurate, since AFAICT there
isn't an integratorcp kernel on the website any more; so better
deleted than retained.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Niek Linnenbank <nieklinnenbank@gmail.com>
Message-id: 20200309215818.2021-3-peter.maydell@linaro.org
Now that qemu-doc.html is no longer present, the ordering of manuals
within the top-level index page looks a bit odd. Reshuffle so that
the manuals the user is most likely to be interested in are at the
top of the list, and the reference material is at the bottom.
Similarly, we reorder the index.rst file used as the base of
the "all manuals in one" documentation for readthedocs.
The new order is:
* system
* user
* tools
* interop
* specs
* QMP reference (if present)
* Guest agent protocol reference (if present)
* devel (if present)
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-id: 20200306171749.10756-7-peter.maydell@linaro.org
Mapping object-add to the command line as is doesn't result in nice
syntax because of the nesting introduced with 'props'. This becomes
nicer and more consistent with device_add and netdev_add when we accept
properties for the object on the top level instead.
'props' is still accepted after this patch, but marked as deprecated.
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Message-Id: <20200224143008.13362-8-kwolf@redhat.com>
Acked-by: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Sphinx doesn't have very good facilities for marking chunks
of documentation as "put this in the manpage only". So instead
we move the parts we want to put into both the HTML manuals
and the manpage into their own .rst.inc files, which we can
include from both the main manual rst files and a new toplevel
rst file that will be the skeleton of the qemu.1 manpage.
In this commit, just split out the parts of the documentation
that go in the manpage.
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-29-peter.maydell@linaro.org
This commit contains hand-written fixes for some issues with the
autogenerated rST fragments in qemu-options.hx:
* Sphinx complains about the UTF-8 art table in the documentation of
the -drive option. Replace it with a proper rST format table.
* rST does not like definition list entries with no actual
definition, but it is possible to work around this by putting a
single escaped literal space as the definition line.
* The "-g widthxheight" option documentation suffers particularly
badly from losing the distinction between italics and fixed-width
as a result of the auto conversion, so put it back in again.
* The script missed some places that use the |qemu_system| etc
macros and need to be marked up as parsed-literal blocks.
* The script autogenerated an expanded out version of the
contents of qemu-option-trace.texi; replace it with an
qemu-option-trace.rst.inc include.
This is sufficient that we can enable inclusion of the
option documentation from invocation.rst.
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-28-peter.maydell@linaro.org
The SPARC and PPC targets currently have a fragment of target-specific
information about the -g and -prom options which would be better placed
as part of the general documentation of those options in qemu-options.hx.
Move the relevant information to those locations.
SPARC also has a bit of text about the -M option which is out of
date and provides no useful information over the generic documentation
of that option, so just delete it.
The motivation here is again to avoid having to awkwardly include
this text into the rST version of the qemu.1 manpage.
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-25-peter.maydell@linaro.org
Currently the per-target documentation for those targets that
implement semihosting includes a bit of text that goes into both the
manual and the manpage about options specific to the target. This
text is redundant with the earlier generic option description of the
semihosting option produced from qemu-options.hx. To avoid having
to create a lot of stub include files to include into the rST
generated qemu.1 manpage, roll target-specific bits of information
into the qemu-options.hx text, so the user doesn't have to look
in two places for this information.
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-24-peter.maydell@linaro.org
In hxtool files, section headings defined with the DEFHEADING
and ARCHHEADING macros have a trailing ':'
DEFHEADING(Standard options:)
This is for the benefit of the --help output. For consistency
with the rest of the rST documentation, strip any trailing ':'
when we construct headings with the Sphinx hxtool extension.
This makes the table of contents look neater.
This only affects generation of documentation from qemu-options.hx,
which we will start doing in a later commit.
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-23-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.
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>
