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

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(a)redhat.com&gt; --- 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 data automatically once the corresponding ``.xml`` or ``.replies`` file +is present in ``tests/qemucapabilitiesdata``.

+ +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::

+ + $ 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

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