Re: [PATCH 08/24] tests: qemucapabilitiesdata: Add README file

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On a Thursday in 2023, Peter Krempa wrote:
Explain what the purpose of these files is as well as how they are
named, captured, used and modified.

Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
tests/qemucapabilitiesdata/README.rst | 94 +++++++++++++++++++++++++++
tests/qemucapabilitiestest.c          | 18 +----
2 files changed, 95 insertions(+), 17 deletions(-)
create mode 100644 tests/qemucapabilitiesdata/README.rst

diff --git a/tests/qemucapabilitiesdata/README.rst b/tests/qemucapabilitiesdata/README.rst
new file mode 100644
index 0000000000..0bf6c97284
--- /dev/null
+++ b/tests/qemucapabilitiesdata/README.rst
@@ -0,0 +1,94 @@
+=========================
+QEMU capabilities testing
+=========================
+
+Purpose
+=======
+
+The test data is used to excercise the capability parsing code in
+``qemucapabilitiestest`` but also provides "real" capabilities data for test
+suites such as ``domaincapstest`` and ``qemuxml2(argv|xml)test``.
+
+It also 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
+
+``$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
+
+Usage in tests
+==============
+
+Testsuites such as ``qemucapabilitiestest`` or ``domaincapstest`` pick up the

Test suites

+test data automatically once the corresponding ``.xml`` or ``.replies`` file
+is  present in ``tests/qemucapabilitiesdata``.

    ^^
double space

+
+Other test suites such as ``qemuxml2argvtest`` 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 ``qemucapsrpobe`` tool::

qemucapsprobe

+
+  $ 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 ``.repliess`` is tolerated.
+
+To aid such modification the tool ``tests/qemucapabilitiesnumbering`` can be
+used.
+
+The tool validates and updates the numbering of the entres in the QMP dump in

*entries

+case something was modified.
+
+The tool also allows programatic modification of the ``.replies`` file.
+
+See ``tests/qemucapabilitiesnumbering.c``.

Jano

Attachment: signature.asc
Description: PGP signature


[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux