There are various ideas / plans floating around for future libvirt work,
some of which is actively in progress. Historically we've never captured
this kind of information anywhere, except in mailing list discussions.
In particular guidelines in hacking.html.in don't appear until a policy
is actively applied.
This patch attempts to fill the documentation gap, by creating a new
"strategy" page which outlines the general vision for some notable
future changes. The key thing to note is that none of the stuff on this
page is guaranteed, plans may change as new information arises. IOW this
is a "best guess" as to the desired future.
This doc has focused on three areas, related to the topic of language
usage / consolidation
- Use of non-C languages for the library, daemons or helper tools
- Replacement of autotools with meson
- Use of RST and Sphinx for documentation (website + man pages)
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
The NVDIMM backend file can be a normal file or a real device file,
Current xml example and explainations may mislead users. So add more
info about the NVDIMM related elements and update the xml examples.
Signed-off-by: Luyao Zhong <luyao.zhong@intel.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Blacklist Perl and Shell code in favour of Python for
sake of readability and portability.
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Some of the typed parameter APIs are exported publicly, but the
implementation was intermixed with private functions. Introduce
virtypedparam-public.c, move all public API functions there and purge
the comments stating that some functions are public.
This will decrease the likelihood of messing up the expectations as well
as it will become more clear which of them are actually public.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
vhost-user-gpu helper takes --render-node option to specify on which
GPU should the renderning be done.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Accept a new driver name attribute to specify usage of helper process, ex:
<video>
<driver name='vhostuser'/>
<model type='virtio'/>
</video>
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Python3 versions less than 3.7 have very unhelpful handling
of the C locale where they assume data is 7-bit only. This
violates POSIX which requires the C locale to be 8-bit clean.
Python3 >= 3.7 now assumes that the C locale is always UTF-8.
Set env variables to force LC_CTYPE to en_US.UTF-8 so that
we get UTF-8 handling on all python versions. Note we do
not use C.UTF-8 since not all C libraries support that.
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Commit 50dfabbb59 forgot to add this important bit on how to check that
all the changes to the XML actually worked.
Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The OOM handling requires special build time options which we never
enable in our CI. Even once enabled the tests are incredibly slow and
typically require manual inspection of the results to weed out false
positives.
Since there was previous agreement to switch to abort on OOM in libvirt
code, there's no point continuing to keep the unused OOM testing code.
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Rewrite some parts for clarity, elaborate the meaning of some of the XML
attributes. And where necessary, distinguish that we're dealing with
two different XML documents here:
- the domainCapabilities XML, to detect the host "hypervisor"
(QEMU/KVM) capabilities, and what libvirt knows about them.
- the guest XML definition, i.e. what features a guest can use, based
on the capabilities (of QEMU and libvirt and the host) reported in
the domainCapabilities XML.
Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Although <interface type='ethernet'> has always been able to use an
existing tap device, this is just a coincidence due to the fact that
the same ioctl is used to create a new tap device or get a handle to
an existing device.
Even then, once we have the handle to the device, we still insist on
doing extra setup to it (setting the MAC address and IFF_UP). That
*might* be okay if libvirtd is running as a privileged process, but if
libvirtd is running as an unprivileged user, those attempted
modifications to the tap device will fail (yes, even if the tap is set
to be owned by the user running libvirtd). We could avoid this if we
knew that the device already existed, but as stated above, an existing
device and new device are both accessed in the same manner, and
anyway, we need to preserve existing behavior for those who are
already using pre-existing devices with privileged libvirtd (and
allowing/expecting libvirt to configure the pre-existing device).
In order to cleanly support the idea of using a pre-existing and
pre-configured tap device, this patch introduces a new optional
attribute "managed" for the interface <target> element. This
attribute is only valid for <interface type='ethernet'> (since all
other interface types have mandatory config that doesn't apply in the
case where we expect the tap device to be setup before we
get it). The syntax would look something like this:
<interface type='ethernet'>
<target dev='mytap0' managed='no'/>
...
</interface>
This patch just adds managed to the grammar and parser for <target>,
but has no functionality behind it.
(NB: when managed='no' (the default when not specified is 'yes'), the
target dev is always a name explicitly provided, so we don't
auto-remove it from the config just because it starts with "vnet"
(VIR_NET_GENERATED_TAP_PREFIX); this makes it possible to use the
same pattern of names that libvirt itself uses when it automatically
creates the tap devices.)
Signed-off-by: Laine Stump <laine@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
We currently generate two completely separate API references for the
libvirt public API. One at 'docs/html/' and one at 'docs/devhelp/'.
Both are published on the website, but we only link to content in
the 'docs/html/' pages.
Both are installed in the libvirt-docs sub-RPM, with a full copy
of the website including 'docs/html/' in /usr/share/docs/libvirt-docs,
while the 'docs/devhelp/' content goes to /usr/share/gtk-doc/. The
latter was broken for years until:
commit ca6f602546
Author: Andrea Bolognani <abologna@redhat.com>
Date: Fri May 10 14:54:52 2019 +0200
docs: Introduce $(devhelphtml_generated)
Our XSLT magic generates one Devhelp-compatible HTML file
per documentation module, but so far we have only shipped
and installed documentation for virterror.
Now that we have $(modules), however, we can generate the
list of files the same way we do for regular documentation
and make sure we always ship and install everything.
That this bug went unnoticed for so long is a sign of how few
people are using the devhelp docs. The only commits to the devhelp
code since it was first introduced have been fixing various build
problems that hit.
The only obvious difference between the two sets of docs is the CSS
styling in use. Overall devhelp does not look compelling enough to
justify having two duplicated sets of API docs. Eliminating it will
reduce the amount of XSL code we are carrying in the tree which is
an attractive benefit.
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
The xenapi driver has not seen any development since its initial
contribution 9 years ago. There have been no bug reports, no patches,
and no queries about the driver on the developer or user mailing lists.
Remove the driver from the libvirt sources.
Signed-off-by: Jim Fehlig <jfehlig@suse.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
The (pre-copy) bandwidth was historically the only bandwidth we
supported and thus it is called just "bandwidth" in all other places.
E.g., virsh migrate-setspeed or in the migration typed parameter name.
Let's make the new option for virsh migrate consistent.
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Use the templates at https://github.com/terinjokes/StickerConstructorSpec
to provide square and hexagon logos for libvirt, suitable for printing
as stickers.
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
According to HTML specification, <a name=''> works in HTML4, but
<a id=''> works in both HTML4 and HTML5. This is followed even in
docs/page.xsl where HTML bookmark links are generated only for
those anchors which have @id attribute.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>
Tested-by: Daniel Henrique Barboza <danielhb413@gmail.com>
The QEMU driver now supports Direct Mode for Hyper-V Synthetic timers
for Hyper-V guests.
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Vitaly Kuznetsov <vkuznets@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Support 'Direct Mode' for Hyper-V Synthetic Timers in domain config.
Make it 'stimer' enlightenment option as it is not a separate thing.
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Vitaly Kuznetsov <vkuznets@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Use 'id' instead of 'name' for anchors which adds the hidden clickable
headerlink helper so it's way simpler to link to a specific part of the
docs.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
This reverts commit 47cbc92987.
The section is no longer correct when the patch switching to gnulib's
make coverage was reverted.
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
Acked-By: Eric Blake <eblake@redhat.com>
QEMU version 2.12.1 introduced a performance feature under commit
be7773268d98 ("target-i386: add KVM_HINTS_DEDICATED performance hint")
This patch adds a new KVM feature 'hint-dedicated' to set this performance
hint for KVM guests. The feature is off by default.
To enable this hint and have libvirt add "-cpu host,kvm-hint-dedicated=on"
to the QEMU command line, the following XML code needs to be added to the
guest's domain description in conjunction with CPU mode='host-passthrough'.
<features>
<kvm>
<hint-dedicated state='on'/>
</kvm>
</features>
...
<cpu mode='host-passthrough ... />
Signed-off-by: Wim ten Have <wim.ten.have@oracle.com>
Signed-off-by: Menno Lageman <menno.lageman@oracle.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Historically URIs handled by the remote driver will always connect to
the libvirtd UNIX socket. There will now be one daemon per driver, and
each of these has its own UNIX sockets to connect to.
It will still be possible to run the traditional monolithic libvirtd
though, which will have the original UNIX socket path.
In addition there is a virproxyd daemon that doesn't run any drivers,
but provides proxying for clients accessing libvirt over IP sockets, or
tunnelling to the legacy libvirtd UNIX socket path.
Finally when running inside a daemon, the remote driver must not reject
connections unconditionally. For example, the QEMU driver needs to be
able to connect to the network driver. The remote driver must thus be
willing to handle connections even when inside the daemon, provided no
local driver is registered.
This refactoring enables the remote driver to be able to connect to the
per-driver daemons. The URI parameter "mode" accepts the values "auto",
"direct" and "legacy" to control which daemons are connected to.
The client side libvirt.conf config file also supports a "remote_mode"
setting which is used if the URI parameter is not set.
If neither the config file or URI parameter set a mode, then "auto"
is used, whereby the client looks to see which sockets actually exist
right now.
The remote driver will only ever spawn the per-driver daemons, or
the legacy libvirtd. It won't ever try to spawn virtproxyd, as
that is only there for IP based connectivity, or for access from
legacy remote clients.
If connecting to a remote host over any kind of ssh tunnel, for now we
must assume only the legacy socket exists. A future patch will introduce
a netcat replacement that is tailored for libvirt to make remote
tunnelling easier.
The configure arg '--with-remote-default-mode=legacy|direct' allows
packagers to set a default at build time. If not given, it will default
to legacy mode.
Eventually the default will switch to direct mode. Distros can choose
to do the switch earlier if desired. The main blocker is testing and
suitable SELinux/AppArmor policies.
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
host-passthrough documentation menions that the source and destination
hosts are not identical in both hardware and configuration. Configuration
actually includes microcode version and QEMU version, but this is not
clear so make it explicit
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20190802125415.15227-1-pbonzini@redhat.com>
Reviewed-by: Jiri Denemark <jdenemar@redhat.com>
There is no restriction on maximum value of PCI domain. In fact,
Linux kernel uses plain atomic inc when assigning PCI domains:
drivers/pci/pci.c:static int pci_get_new_domain_nr(void)
drivers/pci/pci.c-{
drivers/pci/pci.c- return atomic_inc_return(&__domain_nr);
drivers/pci/pci.c-}
Of course, this function is called only if kernel was compiled
without PCI domain support or ACPI did not provide PCI domain.
However, QEMU still has the same restriction as us: in
set_pci_host_devaddr() QEMU checks if domain isn't greater than
0xffff. But one can argue that that's a QEMU limitation. We still
want to be able to cope with other hypervisors that don't have
this limitation (possibly).
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
In v5.6.0-rc1~347 I've mistakenly messed up news.xml as the
change I wanted to promote was added into a comment (I blame git
rebase for that). Anyway, restore the original state of the
comment so it can be copied again.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Checkpoints are definitely a news-worthy addition, even if the
virDomainBackup API is not going to make it until a later release.
Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Introduced by: commit e9528f41c6
'msrs' is a feature unrelated to Hyper-V Enlightenments, the commit message
which added it and the test have it right:
<features>
...
<msrs unknown='ignore'>
...
</features>
Signed-off-by: Vitaly Kuznetsov <vkuznets@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
SynIC stands for 'Synthetic Interrupt Controller', it is not a NIC. Fix the
spelling in accordance with Hypervisor Top Level Functional Specification.
Signed-off-by: Vitaly Kuznetsov <vkuznets@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
The example XML we have contains all other Hyper-V Enlightenments but
'stimer' is missing.
Signed-off-by: Vitaly Kuznetsov <vkuznets@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Earlier patches mentioned that the initial implementation will prevent
snapshots and checkpoints from being used on the same domain at once.
However, the actual restriction is done in this separate patch to make
it easier to lift that restriction via a revert, when we are finally
ready to tackle that integration in the future.
Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
