There are two guides to contributing: `hacking.rst` is focused on code
contributions, and `contributing.rst` is more general. Clarify scope of
`hacking.rst` and link to the general guide in its references.
Signed-off-by: Tim Small <tim@seoss.co.uk>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Whilst the "docs" documentation map is linked in the navigation bar,
users may scroll down and lose sight of this, so also place at the
bottom of the "Quick Links" section.
Signed-off-by: Tim Small <tim@seoss.co.uk>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Asynchronous teardown can be specified if the QEMU binary supports it by
adding in the domain XML
<features>
...
<async-teardown enabled='yes|no'/>
...
</features>
By default this new feature is disabled.
Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com>
Reviewed-by: Thomas Huth <thuth@redhat.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Allow //disk/target@removable for scsi disk devices, since QEMU has support
the removable attribute for scsi-hd device from v0.14.0[1].
[1]: 419e691f8e: scsi-disk: Allow overriding SCSI INQUIRY removable bit
Signed-off-by: Han Han <hhan@redhat.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
In our passt example XML we use /var/log/passt.log as path to the
log file. This is not optimal, because in case of unprivileged
daemon, neither libvirt nor passt has enough permissions to
create the file. Let's move the file under /tmp.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Qemu 8.1.0 will add discard_no_unref option for qcow2 images.
When this option is enabled (default=false), then it will no longer
unreference clusters when guest does a discard, but it will just free
the blocks (useful for incremental backups for example) and pass the
discard to the lower layer.
This was implemented to avoid fragmentation within the qcow2 image.
Signed-off-by: Jean-Louis Dupond <jean-louis@dupond.be>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
We already report the hosts physical address size in host capabilities,
but computing a baseline CPU definition is done from domain
capabilities.
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Ensure that also 'non-halting' messages stop the build process.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
The '.. meta::' rST directive allows adding header metadata. Move the
specific metadata from page.xsl into the individual files and pass them
through into the header from page.xsl.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
Both virtio-mem and virtio-pmem devices have '.memaddr' attribute
which controls the address where they are mapped in the guest
memory. Ideally, users do not need to specify this as QEMU does
the right thing and computes addresses automatically on startup.
But soon, we will need to record this address as it is part of
guest ABI. And also, there might be some users that want to
control this value. Now, we are in a bit of a pickle, because
both these device types already have a PCI address, therefore we
can't just use <address/> blindly. But what we can do, is
introduce <address/> under the <target/> element. This is also
more conceptual, as knobs under <target/> control guest visible
config of memory device (and .memaddr surely falls into that
category).
NB, SgxEPCDeviceInfo struct in QMP definition also has .memaddr
attribute, but because of the way we build cmd line there's no
(easy) way to set the attribute. So ignore that for now.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
There are/can be overall docs for enums (e.g.
virDomainModificationImpact) not just individual values. But
these never make it into the generated HTML which is a bit
unfortunate as they can contain valuable information for users.
Generate a block with overall enum documentation, just like we do
for functions.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
We have plenty of generic typedefs (that basically just alias a
struct, or our popular virXXXPtr). Because we do not generate
HTML docs for it, the documentation is placed at random places,
e.g.: comment from virDomainPtr typedef ("a virDomainPtr is
pointer to a virDomain private structure ...") ends up after
virDomainProcessSignal enum block.
There are some less weird occurrences of this problem (e.g.
virBlkioParameterPtr), but yet - the typedef appears in TOC.
Therefore, generate a block for each typedef and put its
description there.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
The QEMU interface is still in a state of flux, and KVM support
has been pulled shortly after having been merged. Let's not
commit to a stable interface in libvirt just yet.
Reverts: 720e8f13ff
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
The type='pty' attribute in the <serial> element causes a Pseudo TTY to be
allocated on the host side via "/dev/ptmx", which is meant to be
interacted with via "virsh console" or similar.
That's not how a firmware log is typically viewed or saved. Replace
type='pty' with type='file', and also provide an example <source> element
(with the pathname of the logfile), similarly to how the <serial> example
just above provides a <source> element too.
Cc: "Daniel P. Berrangé" <berrange@redhat.com>
Cc: Andrea Bolognani <abologna@redhat.com>
Updates: 654968381d
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The <serial> opening tag is paired with the </console> closing tag; that's
a mismatch. The question is then whether to modify the former to
<console>, or the latter to </serial>.
Per section "Relationship between serial ports and consoles", <serial> is
used for emulated (not paravirt) consoles, and it's the type that's
suitable for early debug output (such as from firmware). Thus, change
</console> to </serial>.
Cc: "Daniel P. Berrangé" <berrange@redhat.com>
Cc: Andrea Bolognani <abologna@redhat.com>
Fixes: 654968381d
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Add migrate options: --compression-zlib-level
--compression-zstd-level
These options are used to set compress level for "zlib"
or "zstd" during parallel migration if the compress method
is specified.
Signed-off-by: Jiang Jiacheng <jiangjiacheng@huawei.com>
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
Reviewed-by: Jiri Denemark <jdenemar@redhat.com>
Wrap the auto-generated pages (API ref and hvsupport.html) in the proper
top level element similarly to what the pages generated from RST have to
remove the extra case when templating our web.
(Best viewed with 'git show -w')
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Since we need to generate API docs for multiple input files the index
page is not useful for us and was replaced by a manual one. Drop the XSL
for generating it.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The auto-generated index contains only references to one run of the
generator but we in total run it 4 times missing the admin, lxc, and
qemu specific apis.
Rewrite it manually so that we can drop the generator for it.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Now that the table is not so wide we can treat it as any other page.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The only remaining page was 'hvsupport.html' which is generated by
'scripts/hvsupport.py'. The script already has all the data to generate
the table of contents internally so we can remove the whole complicated
template.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Final piece of conversion of our non-generated pages to 'rst'.
Special raw HTML is used for adding the appropriate code to fetch the
blog planet.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The only special bit about the 'acl' page was the inclusion of the
objects and permissions tables. We can do that by the '.. raw::'
directive.
One reference from 'aclpolkit.rst' needed to be updated to go with the
new header anchor naming.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Use the same 'margin-bottom' bot for the normal and mobile layout fixing
one of the panels touching the footer.
Use same font size both for <h1> and <h2> used as the column titles as
rst2html5 based on version can generate either of them.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Use the full width of the parent box and drop the unnecessarily bigger
margin.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Use the '#index' id to select the proper page as the body element
doesn't have 'index' class.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
When the pages were converted to rST it required changes to how the
panels are created. This change was not reproduced in the specific media
override for narrow displays and thus made those pages unusable.
Note that two lines per document are needed as some rst2html5 versions
format a <div class='section'> and others do a <section> element
instead.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
There's nothing with such element id. The last mention was removed in
2818359075
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The Memory Tagging Extensions are hardware acceleration present
in some ARM processors that allow memory error detection [1].
Introduce a domain XML knob that turns them on or off.
1: https://www.arm.com/blogs/blueprint/memory-safety-arm-memory-tagging-extension
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
Allow users controlling the multi-channel mode by adding a
'multichannel' property parsed for USB audio devices and wire up the
support in the qemu driver.
Closes: https://gitlab.com/libvirt/libvirt/-/issues/472
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Emphasize the various sound card models and other config options by
using ``...``.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Currently we allow configuring the 'poll-max-ns', 'poll-grow', and
'poll-shrink' parameters of qemu iothreads only during runtime and they
are not persisted. Add XML machinery to persist them.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
We no longer link to it from anywhere, and a server-side
redirect has been created to keep existing external links
working.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
All the information from java.rst have been transferred
to the subproject's own website.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Treat:
<maxphysaddr mode="emulate"/>
as a request not to take the maximum address size from the host.
This is useful if QEMU changes the default.
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
Spell out that TCP and TLS needs virtproxyd as 'off-host' might mean
that also ssh transport requires it.
Also fix the name of the 'virtproxyd' daemon.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Disabling the daemon timeout is important so that the settings don't get
discarded. Remove the comment saying it's optional and add a paragraph
outlining what to do if it is not available.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
