[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 14/38] docs: Move QTest documentation to its own document
From: |
Paolo Bonzini |
Subject: |
[PULL 14/38] docs: Move QTest documentation to its own document |
Date: |
Mon, 12 Oct 2020 16:33:19 -0400 |
From: Eduardo Habkost <ehabkost@redhat.com>
The qtest and libqtest doc comments will be parsed to generate
API documentation, so move QTest documentation to its own
document where the API and format documentation and will be
included.
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Acked-by: Thomas Huth <thuth@redhat.com>
Message-Id: <20201005205228.697463-2-ehabkost@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
docs/devel/index.rst | 1 +
docs/devel/qtest.rst | 58 ++++++++++++++++++++++++++++++++++++++++++
docs/devel/testing.rst | 47 ++--------------------------------
3 files changed, 61 insertions(+), 45 deletions(-)
create mode 100644 docs/devel/qtest.rst
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 5fda2d3509..77baae5c77 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -21,6 +21,7 @@ Contents:
atomics
stable-process
testing
+ qtest
decodetree
secure-coding-practices
tcg
diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst
new file mode 100644
index 0000000000..86dec84a0b
--- /dev/null
+++ b/docs/devel/qtest.rst
@@ -0,0 +1,58 @@
+========================================
+QTest Device Emulation Testing Framework
+========================================
+
+QTest is a device emulation testing framework. It can be very useful to test
+device models; it could also control certain aspects of QEMU (such as virtual
+clock stepping), with a special purpose "qtest" protocol. Refer to the
+documentation in ``qtest.c`` for more details of the protocol.
+
+QTest cases can be executed with
+
+.. code::
+
+ make check-qtest
+
+The QTest library is implemented by ``tests/qtest/libqtest.c`` and the API is
+defined in ``tests/qtest/libqtest.h``.
+
+Consider adding a new QTest case when you are introducing a new virtual
+hardware, or extending one if you are adding functionalities to an existing
+virtual device.
+
+On top of libqtest, a higher level library, ``libqos``, was created to
+encapsulate common tasks of device drivers, such as memory management and
+communicating with system buses or devices. Many virtual device tests use
+libqos instead of directly calling into libqtest.
+
+Steps to add a new QTest case are:
+
+1. Create a new source file for the test. (More than one file can be added as
+ necessary.) For example, ``tests/qtest/foo-test.c``.
+
+2. Write the test code with the glib and libqtest/libqos API. See also existing
+ tests and the library headers for reference.
+
+3. Register the new test in ``tests/qtest/Makefile.include``. Add the test
+ executable name to an appropriate ``check-qtest-*-y`` variable. For example:
+
+ ``check-qtest-generic-y = tests/qtest/foo-test$(EXESUF)``
+
+4. Add object dependencies of the executable in the Makefile, including the
+ test source file(s) and other interesting objects. For example:
+
+ ``tests/qtest/foo-test$(EXESUF): tests/qtest/foo-test.o $(libqos-obj-y)``
+
+Debugging a QTest failure is slightly harder than the unit test because the
+tests look up QEMU program names in the environment variables, such as
+``QTEST_QEMU_BINARY`` and ``QTEST_QEMU_IMG``, and also because it is not easy
+to attach gdb to the QEMU process spawned from the test. But manual invoking
+and using gdb on the test is still simple to do: find out the actual command
+from the output of
+
+.. code::
+
+ make check-qtest V=1
+
+which you can run manually.
+
diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst
index 8875a40a2b..e58389b29f 100644
--- a/docs/devel/testing.rst
+++ b/docs/devel/testing.rst
@@ -70,8 +70,8 @@ QTest
QTest is a device emulation testing framework. It can be very useful to test
device models; it could also control certain aspects of QEMU (such as virtual
-clock stepping), with a special purpose "qtest" protocol. Refer to the
-documentation in ``qtest.c`` for more details of the protocol.
+clock stepping), with a special purpose "qtest" protocol. Refer to
+:doc:`qtest` for more details.
QTest cases can be executed with
@@ -79,49 +79,6 @@ QTest cases can be executed with
make check-qtest
-The QTest library is implemented by ``tests/qtest/libqtest.c`` and the API is
-defined in ``tests/qtest/libqtest.h``.
-
-Consider adding a new QTest case when you are introducing a new virtual
-hardware, or extending one if you are adding functionalities to an existing
-virtual device.
-
-On top of libqtest, a higher level library, ``libqos``, was created to
-encapsulate common tasks of device drivers, such as memory management and
-communicating with system buses or devices. Many virtual device tests use
-libqos instead of directly calling into libqtest.
-
-Steps to add a new QTest case are:
-
-1. Create a new source file for the test. (More than one file can be added as
- necessary.) For example, ``tests/qtest/foo-test.c``.
-
-2. Write the test code with the glib and libqtest/libqos API. See also existing
- tests and the library headers for reference.
-
-3. Register the new test in ``tests/qtest/Makefile.include``. Add the test
- executable name to an appropriate ``check-qtest-*-y`` variable. For example:
-
- ``check-qtest-generic-y = tests/qtest/foo-test$(EXESUF)``
-
-4. Add object dependencies of the executable in the Makefile, including the
- test source file(s) and other interesting objects. For example:
-
- ``tests/qtest/foo-test$(EXESUF): tests/qtest/foo-test.o $(libqos-obj-y)``
-
-Debugging a QTest failure is slightly harder than the unit test because the
-tests look up QEMU program names in the environment variables, such as
-``QTEST_QEMU_BINARY`` and ``QTEST_QEMU_IMG``, and also because it is not easy
-to attach gdb to the QEMU process spawned from the test. But manual invoking
-and using gdb on the test is still simple to do: find out the actual command
-from the output of
-
-.. code::
-
- make check-qtest V=1
-
-which you can run manually.
-
QAPI schema tests
-----------------
--
2.26.2
- [PULL 18/38] docs/devel: update instruction on how to add new unit tests, (continued)
- [PULL 18/38] docs/devel: update instruction on how to add new unit tests, Paolo Bonzini, 2020/10/12
- [PULL 29/38] scsi/scsi_bus: switch search direction in scsi_device_find, Paolo Bonzini, 2020/10/12
- [PULL 26/38] qtest: check that drives are really appearing and disappearing, Paolo Bonzini, 2020/10/12
- [PULL 22/38] qtest: Reintroduce qtest_qmp_receive with QMP event buffering, Paolo Bonzini, 2020/10/12
- [PULL 23/38] qtest: remove qtest_qmp_receive_success, Paolo Bonzini, 2020/10/12
- [PULL 19/38] build-sys: fix git version from -version, Paolo Bonzini, 2020/10/12
- [PULL 24/38] device-plug-test: use qtest_qmp to send the device_del command, Paolo Bonzini, 2020/10/12
- [PULL 25/38] qtest: switch users back to qtest_qmp_receive, Paolo Bonzini, 2020/10/12
- [PULL 20/38] meson.build: Re-enable KVM support for MIPS, Paolo Bonzini, 2020/10/12
- [PULL 21/38] qtest: rename qtest_qmp_receive to qtest_qmp_receive_dict, Paolo Bonzini, 2020/10/12
- [PULL 14/38] docs: Move QTest documentation to its own document,
Paolo Bonzini <=
- [PULL 28/38] qdev: add "check if address free" callback for buses, Paolo Bonzini, 2020/10/12
- [PULL 16/38] docs/devel/qtest: Include libqtest API reference, Paolo Bonzini, 2020/10/12
- [PULL 33/38] device-core: use atomic_set on .realized property, Paolo Bonzini, 2020/10/12
- [PULL 32/38] scsi: switch to bus->check_address, Paolo Bonzini, 2020/10/12
- [PULL 13/38] qom: fix objects with improper parent type, Paolo Bonzini, 2020/10/12
- [PULL 38/38] meson: identify more sections of meson.build, Paolo Bonzini, 2020/10/12
- [PULL 30/38] device_core: use drain_call_rcu in in qmp_device_add, Paolo Bonzini, 2020/10/12
- [PULL 37/38] scsi/scsi_bus: fix races in REPORT LUNS, Paolo Bonzini, 2020/10/12
- [PULL 34/38] scsi/scsi-bus: scsi_device_find: don't return unrealized devices, Paolo Bonzini, 2020/10/12
- [PULL 31/38] device-core: use RCU for list of children of a bus, Paolo Bonzini, 2020/10/12