1a738a50eSEduardo Habkost======================================== 2a738a50eSEduardo HabkostQTest Device Emulation Testing Framework 3a738a50eSEduardo Habkost======================================== 4a738a50eSEduardo Habkost 5a738a50eSEduardo HabkostQTest is a device emulation testing framework. It can be very useful to test 6a738a50eSEduardo Habkostdevice models; it could also control certain aspects of QEMU (such as virtual 7f59c6de7SEduardo Habkostclock stepping), with a special purpose "qtest" protocol. Refer to 8f59c6de7SEduardo Habkost:ref:`qtest-protocol` for more details of the protocol. 9a738a50eSEduardo Habkost 10a738a50eSEduardo HabkostQTest cases can be executed with 11a738a50eSEduardo Habkost 12a738a50eSEduardo Habkost.. code:: 13a738a50eSEduardo Habkost 14a738a50eSEduardo Habkost make check-qtest 15a738a50eSEduardo Habkost 16a738a50eSEduardo HabkostThe QTest library is implemented by ``tests/qtest/libqtest.c`` and the API is 17a738a50eSEduardo Habkostdefined in ``tests/qtest/libqtest.h``. 18a738a50eSEduardo Habkost 19a738a50eSEduardo HabkostConsider adding a new QTest case when you are introducing a new virtual 20a738a50eSEduardo Habkosthardware, or extending one if you are adding functionalities to an existing 21a738a50eSEduardo Habkostvirtual device. 22a738a50eSEduardo Habkost 23a738a50eSEduardo HabkostOn top of libqtest, a higher level library, ``libqos``, was created to 24a738a50eSEduardo Habkostencapsulate common tasks of device drivers, such as memory management and 25a738a50eSEduardo Habkostcommunicating with system buses or devices. Many virtual device tests use 26a738a50eSEduardo Habkostlibqos instead of directly calling into libqtest. 27a738a50eSEduardo Habkost 28a738a50eSEduardo HabkostSteps to add a new QTest case are: 29a738a50eSEduardo Habkost 30a738a50eSEduardo Habkost1. Create a new source file for the test. (More than one file can be added as 31a738a50eSEduardo Habkost necessary.) For example, ``tests/qtest/foo-test.c``. 32a738a50eSEduardo Habkost 33a738a50eSEduardo Habkost2. Write the test code with the glib and libqtest/libqos API. See also existing 34a738a50eSEduardo Habkost tests and the library headers for reference. 35a738a50eSEduardo Habkost 36a738a50eSEduardo Habkost3. Register the new test in ``tests/qtest/Makefile.include``. Add the test 37a738a50eSEduardo Habkost executable name to an appropriate ``check-qtest-*-y`` variable. For example: 38a738a50eSEduardo Habkost 39a738a50eSEduardo Habkost ``check-qtest-generic-y = tests/qtest/foo-test$(EXESUF)`` 40a738a50eSEduardo Habkost 41a738a50eSEduardo Habkost4. Add object dependencies of the executable in the Makefile, including the 42a738a50eSEduardo Habkost test source file(s) and other interesting objects. For example: 43a738a50eSEduardo Habkost 44a738a50eSEduardo Habkost ``tests/qtest/foo-test$(EXESUF): tests/qtest/foo-test.o $(libqos-obj-y)`` 45a738a50eSEduardo Habkost 46a738a50eSEduardo HabkostDebugging a QTest failure is slightly harder than the unit test because the 47a738a50eSEduardo Habkosttests look up QEMU program names in the environment variables, such as 48a738a50eSEduardo Habkost``QTEST_QEMU_BINARY`` and ``QTEST_QEMU_IMG``, and also because it is not easy 49a738a50eSEduardo Habkostto attach gdb to the QEMU process spawned from the test. But manual invoking 50a738a50eSEduardo Habkostand using gdb on the test is still simple to do: find out the actual command 51a738a50eSEduardo Habkostfrom the output of 52a738a50eSEduardo Habkost 53a738a50eSEduardo Habkost.. code:: 54a738a50eSEduardo Habkost 55a738a50eSEduardo Habkost make check-qtest V=1 56a738a50eSEduardo Habkost 57a738a50eSEduardo Habkostwhich you can run manually. 58a738a50eSEduardo Habkost 59f59c6de7SEduardo Habkost 60f59c6de7SEduardo Habkost.. _qtest-protocol: 61f59c6de7SEduardo Habkost 62f59c6de7SEduardo HabkostQTest Protocol 63f59c6de7SEduardo Habkost-------------- 64f59c6de7SEduardo Habkost 65f59c6de7SEduardo Habkost.. kernel-doc:: softmmu/qtest.c 66f59c6de7SEduardo Habkost :doc: QTest Protocol 67*51c778edSEduardo Habkost 68*51c778edSEduardo Habkost 69*51c778edSEduardo Habkostlibqtest API reference 70*51c778edSEduardo Habkost---------------------- 71*51c778edSEduardo Habkost 72*51c778edSEduardo Habkost.. kernel-doc:: tests/qtest/libqos/libqtest.h 73