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 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``.
diff --git a/tests/qemucapabilitiestest.c b/tests/qemucapabilitiestest.c
index 8c86095e1c..379fe427d8 100644
--- a/tests/qemucapabilitiestest.c
+++ b/tests/qemucapabilitiestest.c
@@ -206,23 +206,7 @@ mymain(void)
if (testQemuCapsIterate(".replies", doCapsTest, &data) < 0)
return EXIT_FAILURE;
- /*
- * Run "tests/qemucapsprobe /path/to/qemu/binary >foo.replies"
- * to generate updated or new *.replies data files.
- *
- * If you manually edit replies files you can run
- * VIR_TEST_REGENERATE_OUTPUT=1 tests/qemucapabilitiesnumbering
- * to fix the replies ids. The tool also allows for programmatic
- * modification of the replies file.
- *
- * Once a replies file has been generated and tweaked if necessary,
- * you can drop it into tests/qemucapabilitiesdata/ (with a sensible
- * name - look at what's already there for inspiration) and test
- * programs will automatically pick it up.
- *
- * To generate the corresponding output files after a new replies
- * file has been added, run "VIR_TEST_REGENERATE_OUTPUT=1 ninja test".
- */
+ /* See documentation in qemucapabilitiesdata/README.rst */
testQemuDataReset(&data);
--
2.39.2
