Commit Graph

4604 Commits

Author SHA1 Message Date
Peter Krempa
0152aa5673 docs: compiling: Add a note about use of CFLAGS for optimization
Meson doesn't interpret what's set in CFLAGS, but rather simply appeds
it to the command line. Thus any logic which is based on the
optimization level will not work.

Note the caveat in the docs and instruct users to use
``--optimization=N`` instead.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2023-09-04 13:32:28 +02:00
Michal Privoznik
ad8c4d9d6d bhyve: Feed hook scripts with domain XML
Domain related hook scripts are all fed with domain XML on their
stdin, except for bhyve. Fix this.

Resolves: https://gitlab.com/libvirt/libvirt/-/issues/528
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2023-09-04 11:03:33 +02:00
Michal Privoznik
4e73f50b1e docs: Document bhyve hook scripts
We have bhyve hook scripts since v6.1.0-rc1~42 but never mention
them in hooks.rst. Fill the blanks.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2023-09-04 11:03:33 +02:00
Michal Privoznik
4dffe53c5c docs: Document that libxl hooks are also given full domain XML
Our hooks.rst document existence of libxl hook scripts, but
mentions only qemu and lxc as receivers of full domain XML. But
since their introduction in v2.2.0-rc1~201 they are also given
full domain XML. Fix our wording.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2023-09-04 11:03:33 +02:00
Martin Kletzander
a4935d01cf docs, passt: Clarify some niche passt usage
Change example logfile path and clarify how complicated all things passt
are.  I chose not to create the non-existing directory because it could
open a whole new can of worms.

Also explain missing `dev` attribute of `<portForward/>`

Resolves: https://issues.redhat.com/browse/RHEL-1833

Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-09-04 10:54:31 +02:00
Pavel Hrdina
0873d63b09 Revert "capabilities: report full external snapshot support"
Reverting external snapshot for running VM doesn't work correctly so we
should not report this capability until it is fixed.

This reverts commit de71573bfe.

Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2023-09-01 12:09:04 +02:00
Laine Stump
bbfcf18f50 docs: update description of virsh nodedev-detach --driver option
--driver can now be used to specify a specific driver to bind to the
device being detached from the host driver (e.g. vfio-pci-igbvf), not
just the *type* of driver (e.g. "vfio" or "xen", which are unnecessary
anyway, since they are implicit in which hypervisor driver is in use)

Signed-off-by: Laine Stump <laine@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-08-25 15:24:58 -04:00
Kristina Hanicova
96d8ee2cff conf: add support for discard_granularity
This introduces the ability to set the discard granularity option
for a disk.  It defines the smallest amount of data that can be
discarded in a single operation (useful for managing and
optimizing storage).

However, most hypervisors automatically set the proper discard
granularity and users usually do not need to change the default
setting.

Signed-off-by: Kristina Hanicova <khanicov@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2023-08-25 15:05:13 +02:00
Peter Krempa
c3934b2b6b docs: Improve documentation of <disk type='dir'>
Note the implications and caveats of <disk type='dir'>.

Closes: https://gitlab.com/libvirt/libvirt/-/issues/519
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2023-08-25 14:43:22 +02:00
K Shiva Kiran
93d1989a3d virsh exposure of Network Metadata APIs
Adds two new commands and a new option:
- 'net-desc' to show/modify network title and description.
- 'net-metadata' to show/modify network metadata.
- Option '--title' for 'net-list' to print corresponding
  network titles in an additional column.
- Documentation for all the above.
- XML Fallback function `virshNetworkGetXMLFromNet` for title and
  description for compatibility with hosts running older versions
  of libvirtd.

Signed-off-by: K Shiva Kiran <shiva_kr@riseup.net>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-08-25 12:36:37 +02:00
K Shiva Kiran
742c87d453 Add <title> and <description> for Network Objects
This patch adds new elements <title> and <description> to the Network XML.
- The <title> attribute holds a short title defined by the user and
  cannot contain newlines.
- The <description> attribute holds any documentation that the user
  wants to store.
- Schema definitions of <title> and <description> have been moved from
  domaincommon.rng to basictypes.rng for use by network and future objects.
- Added Network XML parser logic for the above.

Signed-off-by: K Shiva Kiran <shiva_kr@riseup.net>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-08-25 12:36:37 +02:00
Pavel Hrdina
de71573bfe capabilities: report full external snapshot support
Now that deleting and reverting external snapshots is implemented we can
report that in capabilities so management applications can use that
information and start using external snapshots.

Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2023-08-24 19:08:20 +02:00
Pavel Hrdina
ec642b1efe capabilities: reword disksnapshot feature to mention creating snapshots
Libvirt supports creating snapshots for a long time but the wording of
the feature may imply that libvirt supports external snapshots in
general but that is not true as users were not able to use APIs to
delete or revert external snapshots.

Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2023-08-24 19:08:09 +02:00
Erik Skultety
4e381c3e1d docs: index: Add a quick link to Submitting patches
We still get MRs in Gitlab from individual contributors on a regular
basis which in some ways just makes maintainer's or reviewer's life
just a bit more complicated. This ultimately means our guidelines are
probably not visible enough on the main page
(or some people wouldn't read them anyway). While this patch can't make
the problem go away, it can at least attempt to mitigate it by creating
a quick link to the 'hacking' page, skipping a lot of TL;DR contents
in contributing.rst which we link from the main page.

Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Kristina Hanicova <khanicov@redhat.com>
2023-08-11 14:57:51 +02:00
Han Han
0cec8abdba docs: formatdomain: Mention the QEMU requirement for discard_no_unref
Signed-off-by: Han Han <hhan@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
2023-07-26 10:08:26 +02:00
Han Han
8cb0c11f29 docs: Mention vhostuser for queues and queue_size
These two attributes are supported for vhost-user-blk as well.

Signed-off-by: Han Han <hhan@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-07-25 10:24:59 +02:00
Michal Privoznik
7ba20863a7 meson: Annotate each test() with 'suite'
A test case can be part of a test suite (just like we already
have 'syntax-check'). This then allows developers to run only a
subset of tests. For instance - when using valgrind test setup
(`meson test -C _build/ --setup valgrind`) it makes zero sense to
run syntax-check tests or other script based tests (e.g.
check-augeas-*, check-remote_protocol, etc.). What does makes
sense is to run compiled binaries.

Strictly speaking, reaching that goal is as trivial as annotating
only those compiled tests (declared in tests/meson.build) and
running them selectively:

  meson test -C _build/ --setup valgrind --suite $TAG

But it may be also desirable to run test scripts separately.

Therefore, introduce two new tags: 'bin' for compiled tests, and
'script' for script based tests and annotate each test()
accordingly.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2023-07-20 10:58:01 +02:00
Boris Fiuczynski
aece25f665 conf: domcaps: Add 'async-teardown' domain capability
Add async-teardown to the features list in domain capabilities allowing
high level management to introspect the availability of the asynchronous
teardown feature.

Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-07-18 08:49:32 +02:00
Jonathon Jongsma
2d7542a8a5 docs: expand clangd instructions
Add some additional information about running clangd for LSP when clang
is not your normal compiler.

Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-By: Tim Small <tim@seoss.co.uk>
2023-07-17 10:43:29 -05:00
Tim Small
36b247b908 docs: Reword ninja invocation note to clarify build directory
Minor rewording to clarify purpose of the -C flag in the ninja
invocation, whilst retaining previous meaning.

Signed-off-by: Tim Small <tim@seoss.co.uk>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-07-14 15:19:34 +02:00
Tim Small
ef7228f5ca docs: Fix deprecated use of implicit meson "setup" command
Use the explicit meson "setup" command instead of the deprecated
implicit invocation. The implied setup usage generates a warning with
meson version 1.0.1:

WARNING: Running the setup command as `meson [options]` instead of
`meson setup [options]` is ambiguous and deprecated.

Additionally the implicit command is likely to be confusing to those
unfamiliar with Meson - the `build` argument in `meson build` resembles
an action rather than an arbitrary path.

Signed-off-by: Tim Small <tim@seoss.co.uk>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-07-14 15:19:29 +02:00
Tim Small
4d50cd23c9 docs: Point to mailing list archives from submitting-patches
Suggest that new contributors should review past patch submissions for
typical style, feedback etc. prior to submitting. Link to archives.

Signed-off-by: Tim Small <tim@seoss.co.uk>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-07-14 15:19:27 +02:00
Tim Small
7160215146 docs: Advise running CI tests prior to submission
In the preparing patches section, note that it is possible to run CI
tests via gitlab prior to submitting patches.

Signed-off-by: Tim Small <tim@seoss.co.uk>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-07-14 15:19:24 +02:00
Tim Small
941fc36f11 docs: Reword "Preparing Patches" to clarify
Clarify that patches should apply cleanly to the master branch. Give
guidance for typical bug fix process for existing releases.

Signed-off-by: Tim Small <tim@seoss.co.uk>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-07-14 15:19:22 +02:00
Tim Small
3da8d8b5b1 docs: Add config instructions for clangd with libvirt
In build environments which use gcc as the default compiler, use of the
clangd LSP server (for enhanced code editing and navigation etc.) with
libvirt requires some additional configuration.  Detail this and link
from `hacking.rst`.

Signed-off-by: Tim Small <tim@seoss.co.uk>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-07-14 15:19:19 +02:00
Tim Small
401a6171a3 docs: Point to compiling guide from code contribution guide
The "hacking" doc details where to find the code, but not how to compile
it - link to the instructions contained in `compiling.rst`.

Signed-off-by: Tim Small <tim@seoss.co.uk>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-07-14 15:19:17 +02:00
Tim Small
7218970862 docs: Link main "contributing" from programming-specific guide
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>
2023-07-14 15:19:14 +02:00
Tim Small
225f6de45f docs: Missing "full-stop"/"period" on some bullet items
Signed-off-by: Tim Small <tim@seoss.co.uk>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2023-07-14 15:19:10 +02:00
Tim Small
cccf129c2d docs: Link to main docs directory from Quick Links
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>
2023-07-14 15:19:07 +02:00
Boris Fiuczynski
3bf02acdc5 qemu: allow use of async teardown in domain
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>
2023-07-10 13:28:17 +02:00
Han Han
1ed695bcff qemu: Support removable for scsi disk
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>
2023-07-09 07:39:57 +02:00
Michal Privoznik
ceb4dc8e17 docs: Move passt log file in our example XML
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>
2023-06-26 15:52:54 +02:00
Jean-Louis Dupond
b855f8ea1e Add discard_no_unref option for qcow2 images
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>
2023-06-26 13:06:00 +02:00
Jiri Denemark
be1b7d5b18 qemu: Report physical address size in domain capabilities
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>
2023-06-16 12:44:54 +02:00
Oleg Vasilev
794c583f46 docs: fix changed API calls
Signed-off-by: Oleg Vasilev <oleg.vasilev@virtuozzo.com>
2023-06-05 13:34:31 +00:00
Peter Krempa
2380242928 docs: Use '--exit-status=' option for 'rst2html5'
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>
2023-06-02 09:39:10 +02:00
Peter Krempa
9f49f60aca docs: go: Add 'go-import' metadata via rST
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>
2023-06-02 09:39:10 +02:00
Peter Krempa
54c1f31fda docs: page.xsl: Drop passhrough of <script> elements into header
No generated headers have inline javascript.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
2023-06-02 09:39:10 +02:00
Peter Krempa
464450772f docs: newapi: Remove unused 'docomponents' template
Never used since introduction in b38893c3ea

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
2023-06-02 09:39:10 +02:00
Michal Privoznik
677156f662 conf: Introduce <address/> for virtio-mem and virtio-pmem
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>
2023-05-26 16:44:42 +02:00
Michal Privoznik
6a15e22265 docs: newapi.xsl: Generate overall docs for enums too
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>
2023-05-25 14:22:34 +02:00
Michal Privoznik
1fa7443dc7 docs: newapi.xsl: Generate docs on generic typedefs
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>
2023-05-25 14:22:13 +02:00
Andrea Bolognani
3b6d69237f Revert "conf: Introduce MTE domain feature"
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>
2023-05-22 15:13:19 +02:00
Laszlo Ersek
90404c5368 docs: make isa-debugcon example more useful / directly applicable
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>
2023-05-18 16:24:59 +02:00
Laszlo Ersek
f06d15b512 docs: fix typo in isa-debugcon example
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>
2023-05-18 16:24:59 +02:00
Jiang Jiacheng
4ab5591c95 virsh: Add migrate options to set parallel compress level
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>
2023-05-18 15:47:30 +02:00
Peter Krempa
5ee27c37e6 docs: xsl: Simplify templating XSL
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>
2023-05-18 10:06:51 +02:00
Peter Krempa
f11c773014 docs: newapi.xsl: Remove support for generating index page
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>
2023-05-18 10:06:51 +02:00
Peter Krempa
7aa2706d3b docs: html: Add a manually written index page
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>
2023-05-18 10:06:51 +02:00
Peter Krempa
02e7f8d709 css: Remove override of width for 'hvsupport' page
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>
2023-05-18 10:06:51 +02:00