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

[Ján Tomko]

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 at redhat.com>
>---
> 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 228 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20230330/b520eb5a/attachment.sig>