mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-09 23:10:08 +00:00
bb932e2c15
Document the reality that some dumps were faked for purpose of testing corner cases. Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com> Reviewed-by: Andrea Bolognani <abologna@redhat.com>
137 lines
4.1 KiB
ReStructuredText
137 lines
4.1 KiB
ReStructuredText
=========================
|
|
QEMU capabilities testing
|
|
=========================
|
|
|
|
Purpose
|
|
=======
|
|
|
|
Test data in this directory is used:
|
|
|
|
- to excercise the capability parsing code in ``qemucapabilitiestest``
|
|
|
|
- provides "real" capabilities data for test suites such as ``domaincapstest``
|
|
``qemuxmlconftest``, and others
|
|
|
|
- provides the required data to validate the QMP commands used by libvirt
|
|
against qemu's QMP schema
|
|
|
|
Naming
|
|
======
|
|
|
|
Files in this directory have the following naming scheme::
|
|
|
|
caps_$QEMUVERSION_$ARCHITECTURE.$SUFFIX
|
|
|
|
or::
|
|
|
|
caps_$QEMUVERSION_$ARCHITECTURE+$VARIANT.$SUFFIX
|
|
|
|
``$QEMUVERSION``
|
|
|
|
Numeric representation of the qemu version, e.g.: ``7.0.0``
|
|
|
|
``$ARCHITECTURE``
|
|
|
|
Architecture string such as ``x86_64``, ``aarch64``, etc.
|
|
|
|
``$SUFFIX``
|
|
|
|
``.replies`` for the dump of the QMP communication used to probe qemu.
|
|
``.xml`` for the generated capability dump
|
|
|
|
``$VARIANT``
|
|
|
|
The variant name is an optional arbitrary string, not containing any dot.
|
|
|
|
A variant is an additional named version of capabilities for given version and
|
|
architecture tuple. This allows for testing special cases which e.g. depend
|
|
on a specific host platform or operating system feature, which differs from
|
|
the main tests. Note that in the test code the variant name is an empty string
|
|
or includes the '+' sign for ease of use.
|
|
|
|
Known test variants
|
|
-------------------
|
|
|
|
``+hvf``
|
|
|
|
Variant of the test data using the Apple OSX Hypervisor Framework acceleration
|
|
for qemu.
|
|
|
|
|
|
Usage in tests
|
|
==============
|
|
|
|
Test suites such as ``qemucapabilitiestest`` or ``domaincapstest`` pick up the
|
|
test data automatically once the corresponding ``.xml`` or ``.replies`` file
|
|
is present in ``tests/qemucapabilitiesdata``.
|
|
|
|
Other test suites such as ``qemuxmlconftest`` provide macros which invoke test
|
|
cases using this data such as ``DO_TEST_CAPS_LATEST``.
|
|
|
|
Capturing QEMU capabilities
|
|
===========================
|
|
|
|
QEMU capabilities are captured by running the ``qemucapsprobe`` on the QEMU
|
|
binary on given architecture and then capturing the output. Since virtualization
|
|
acceleration is also probed it's required to run it on real hardware.
|
|
|
|
The capabilities dumps contain also host-specific information such as the exact
|
|
CPU definition of the machine where it was ran on, thus they can differ
|
|
significantly when run on other machines.
|
|
|
|
Probing QEMU
|
|
------------
|
|
|
|
Run the ``qemucapsprobe`` tool::
|
|
|
|
$ LIBVIRT_BUILDDIR/tests/qemucapsprobe /path/to/qemu > output.replies
|
|
|
|
The tool spawns the qemu binary and performs probing as if libvirt would do that.
|
|
The QMP conversation between qemu and libvirt is dumped to stdout. User
|
|
running the probe must be able to access the virtualization accelerator (e.g.
|
|
have proper permissions on ``/dev/kvm``)
|
|
|
|
Generating the output files
|
|
---------------------------
|
|
|
|
Place the captured output ``.replies`` file into this directory and run::
|
|
|
|
$ VIR_TEST_REGENERATE_OUTPUT=1 ninja test
|
|
|
|
This runs the test-suite instructing it to update and/or generate all new data
|
|
the test would normally expect.
|
|
|
|
Manual modifications the ``.replies`` file
|
|
==========================================
|
|
|
|
In certain cases it's impractical or impossible to re-generate the ``.replies``
|
|
file on a code change causing a change to the actual QMP query process.
|
|
|
|
In such case a careful manual modification of the ``.replies`` is tolerated.
|
|
|
|
To aid such modification the tool ``scripts/qemu-replies-tool.py`` can be
|
|
used.
|
|
|
|
The tool validates and updates the numbering of the entries in the QMP dump in
|
|
case something was modified.
|
|
|
|
The tool also allows programatic modification of the ``.replies`` file.
|
|
|
|
Fake test data dumps for certain architectures
|
|
==============================================
|
|
|
|
For some architectures it was impossible or impractical to fetch real capability
|
|
dumps. To ensure coverate of certain cases the dumps were collected from
|
|
corresponding binaries running on a different architecture.
|
|
|
|
Capabilities dumps for the following architectures are usually produced on real
|
|
hardware:
|
|
|
|
- x86_64
|
|
- aarch64
|
|
- ppc64
|
|
- s390x
|
|
|
|
In most other cases, x86_64 will be used as the host architecture. A fake caps
|
|
dump can be usually spotted by absence of KVM support.
|