From a738a50e62303f9dfb345790ffd8d01f9e20527a Mon Sep 17 00:00:00 2001 From: Eduardo Habkost Date: Mon, 5 Oct 2020 16:52:26 -0400 Subject: docs: Move QTest documentation to its own document 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 Acked-by: Thomas Huth Message-Id: <20201005205228.697463-2-ehabkost@redhat.com> Signed-off-by: Paolo Bonzini --- 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 (limited to 'docs/devel') 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 ----------------- -- cgit 1.4.1 From f59c6de7f00e664358a9aad49248094ab1b29461 Mon Sep 17 00:00:00 2001 From: Eduardo Habkost Date: Mon, 5 Oct 2020 16:52:27 -0400 Subject: docs/devel/qtest: Include protocol spec in document Include the QTest Protocol doc string in docs/devel/qtest.rst, after converting it to use Sphinx syntax. Signed-off-by: Eduardo Habkost Acked-by: Thomas Huth Message-Id: <20201005205228.697463-3-ehabkost@redhat.com> Signed-off-by: Paolo Bonzini --- docs/devel/qtest.rst | 12 +++++++-- softmmu/qtest.c | 71 ++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 73 insertions(+), 10 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst index 86dec84a0b..3bf9ebee7f 100644 --- a/docs/devel/qtest.rst +++ b/docs/devel/qtest.rst @@ -4,8 +4,8 @@ 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. +clock stepping), with a special purpose "qtest" protocol. Refer to +:ref:`qtest-protocol` for more details of the protocol. QTest cases can be executed with @@ -56,3 +56,11 @@ from the output of which you can run manually. + +.. _qtest-protocol: + +QTest Protocol +-------------- + +.. kernel-doc:: softmmu/qtest.c + :doc: QTest Protocol diff --git a/softmmu/qtest.c b/softmmu/qtest.c index 0d43cf8883..2c6e8dc858 100644 --- a/softmmu/qtest.c +++ b/softmmu/qtest.c @@ -49,92 +49,139 @@ static void *qtest_server_send_opaque; #define FMT_timeval "%ld.%06ld" /** - * QTest Protocol + * DOC: QTest Protocol * * Line based protocol, request/response based. Server can send async messages * so clients should always handle many async messages before the response * comes in. * * Valid requests + * ^^^^^^^^^^^^^^ * * Clock management: + * """"""""""""""""" * * The qtest client is completely in charge of the QEMU_CLOCK_VIRTUAL. qtest commands * let you adjust the value of the clock (monotonically). All the commands * return the current value of the clock in nanoseconds. * + * .. code-block:: none + * * > clock_step * < OK VALUE * - * Advance the clock to the next deadline. Useful when waiting for - * asynchronous events. + * Advance the clock to the next deadline. Useful when waiting for + * asynchronous events. + * + * .. code-block:: none * * > clock_step NS * < OK VALUE * - * Advance the clock by NS nanoseconds. + * Advance the clock by NS nanoseconds. + * + * .. code-block:: none * * > clock_set NS * < OK VALUE * - * Advance the clock to NS nanoseconds (do nothing if it's already past). + * Advance the clock to NS nanoseconds (do nothing if it's already past). * * PIO and memory access: + * """""""""""""""""""""" + * + * .. code-block:: none * * > outb ADDR VALUE * < OK * + * .. code-block:: none + * * > outw ADDR VALUE * < OK * + * .. code-block:: none + * * > outl ADDR VALUE * < OK * + * .. code-block:: none + * * > inb ADDR * < OK VALUE * + * .. code-block:: none + * * > inw ADDR * < OK VALUE * + * .. code-block:: none + * * > inl ADDR * < OK VALUE * + * .. code-block:: none + * * > writeb ADDR VALUE * < OK * + * .. code-block:: none + * * > writew ADDR VALUE * < OK * + * .. code-block:: none + * * > writel ADDR VALUE * < OK * + * .. code-block:: none + * * > writeq ADDR VALUE * < OK * + * .. code-block:: none + * * > readb ADDR * < OK VALUE * + * .. code-block:: none + * * > readw ADDR * < OK VALUE * + * .. code-block:: none + * * > readl ADDR * < OK VALUE * + * .. code-block:: none + * * > readq ADDR * < OK VALUE * + * .. code-block:: none + * * > read ADDR SIZE * < OK DATA * + * .. code-block:: none + * * > write ADDR SIZE DATA * < OK * + * .. code-block:: none + * * > b64read ADDR SIZE * < OK B64_DATA * + * .. code-block:: none + * * > b64write ADDR SIZE B64_DATA * < OK * + * .. code-block:: none + * * > memset ADDR SIZE VALUE * < OK * @@ -149,16 +196,21 @@ static void *qtest_server_send_opaque; * If the sizes do not match, the data will be truncated. * * IRQ management: + * """"""""""""""" + * + * .. code-block:: none * * > irq_intercept_in QOM-PATH * < OK * + * .. code-block:: none + * * > irq_intercept_out QOM-PATH * < OK * * Attach to the gpio-in (resp. gpio-out) pins exported by the device at * QOM-PATH. When the pin is triggered, one of the following async messages - * will be printed to the qtest stream: + * will be printed to the qtest stream:: * * IRQ raise NUM * IRQ lower NUM @@ -168,12 +220,15 @@ static void *qtest_server_send_opaque; * NUM=0 even though it is remapped to GSI 2). * * Setting interrupt level: + * """""""""""""""""""""""" + * + * .. code-block:: none * * > set_irq_in QOM-PATH NAME NUM LEVEL * < OK * - * where NAME is the name of the irq/gpio list, NUM is an IRQ number and - * LEVEL is an signed integer IRQ level. + * where NAME is the name of the irq/gpio list, NUM is an IRQ number and + * LEVEL is an signed integer IRQ level. * * Forcibly set the given interrupt pin to the given level. * -- cgit 1.4.1 From 51c778edd347452ce22146bd004bc7adab5f3a1a Mon Sep 17 00:00:00 2001 From: Eduardo Habkost Date: Mon, 5 Oct 2020 16:52:28 -0400 Subject: docs/devel/qtest: Include libqtest API reference Signed-off-by: Eduardo Habkost Acked-by: Thomas Huth Message-Id: <20201005205228.697463-4-ehabkost@redhat.com> Signed-off-by: Paolo Bonzini --- docs/devel/qtest.rst | 6 ++++++ tests/qtest/libqos/libqtest.h | 20 ++++++++++---------- 2 files changed, 16 insertions(+), 10 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst index 3bf9ebee7f..075fe5f7d5 100644 --- a/docs/devel/qtest.rst +++ b/docs/devel/qtest.rst @@ -64,3 +64,9 @@ QTest Protocol .. kernel-doc:: softmmu/qtest.c :doc: QTest Protocol + + +libqtest API reference +---------------------- + +.. kernel-doc:: tests/qtest/libqos/libqtest.h diff --git a/tests/qtest/libqos/libqtest.h b/tests/qtest/libqos/libqtest.h index a6ee1654f2..209fcf6973 100644 --- a/tests/qtest/libqos/libqtest.h +++ b/tests/qtest/libqos/libqtest.h @@ -24,7 +24,7 @@ typedef struct QTestState QTestState; /** * qtest_initf: - * @fmt...: Format for creating other arguments to pass to QEMU, formatted + * @fmt: Format for creating other arguments to pass to QEMU, formatted * like sprintf(). * * Convenience wrapper around qtest_init(). @@ -87,7 +87,7 @@ void qtest_quit(QTestState *s); * @s: #QTestState instance to operate on. * @fds: array of file descriptors * @fds_num: number of elements in @fds - * @fmt...: QMP message to send to qemu, formatted like + * @fmt: QMP message to send to qemu, formatted like * qobject_from_jsonf_nofail(). See parse_escape() for what's * supported after '%'. * @@ -100,7 +100,7 @@ QDict *qtest_qmp_fds(QTestState *s, int *fds, size_t fds_num, /** * qtest_qmp: * @s: #QTestState instance to operate on. - * @fmt...: QMP message to send to qemu, formatted like + * @fmt: QMP message to send to qemu, formatted like * qobject_from_jsonf_nofail(). See parse_escape() for what's * supported after '%'. * @@ -112,7 +112,7 @@ QDict *qtest_qmp(QTestState *s, const char *fmt, ...) /** * qtest_qmp_send: * @s: #QTestState instance to operate on. - * @fmt...: QMP message to send to qemu, formatted like + * @fmt: QMP message to send to qemu, formatted like * qobject_from_jsonf_nofail(). See parse_escape() for what's * supported after '%'. * @@ -124,7 +124,7 @@ void qtest_qmp_send(QTestState *s, const char *fmt, ...) /** * qtest_qmp_send_raw: * @s: #QTestState instance to operate on. - * @fmt...: text to send, formatted like sprintf() + * @fmt: text to send, formatted like sprintf() * * Sends text to the QMP monitor verbatim. Need not be valid JSON; * this is useful for negative tests. @@ -201,7 +201,7 @@ QDict *qtest_qmp_receive(QTestState *s); /** * qtest_qmp_eventwait: * @s: #QTestState instance to operate on. - * @s: #event event to wait for. + * @event: event to wait for. * * Continuously polls for QMP responses until it receives the desired event. */ @@ -210,7 +210,7 @@ void qtest_qmp_eventwait(QTestState *s, const char *event); /** * qtest_qmp_eventwait_ref: * @s: #QTestState instance to operate on. - * @s: #event event to wait for. + * @event: event to wait for. * * Continuously polls for QMP responses until it receives the desired event. * Returns a copy of the event for further investigation. @@ -237,7 +237,7 @@ QDict *qtest_qmp_receive_success(QTestState *s, /** * qtest_hmp: * @s: #QTestState instance to operate on. - * @fmt...: HMP command to send to QEMU, formats arguments like sprintf(). + * @fmt: HMP command to send to QEMU, formats arguments like sprintf(). * * Send HMP command to QEMU via QMP's human-monitor-command. * QMP events are discarded. @@ -629,7 +629,7 @@ void qtest_add_abrt_handler(GHookFunc fn, const void *data); /** * qtest_qmp_assert_success: * @qts: QTestState instance to operate on - * @fmt...: QMP message to send to qemu, formatted like + * @fmt: QMP message to send to qemu, formatted like * qobject_from_jsonf_nofail(). See parse_escape() for what's * supported after '%'. * @@ -676,7 +676,7 @@ void qtest_qmp_device_add_qdict(QTestState *qts, const char *drv, * @qts: QTestState instance to operate on * @driver: Name of the device that should be added * @id: Identification string - * @fmt...: QMP message to send to qemu, formatted like + * @fmt: QMP message to send to qemu, formatted like * qobject_from_jsonf_nofail(). See parse_escape() for what's * supported after '%'. * -- cgit 1.4.1 From bab88ead6fcbc7097ed75981622cce7850da1cc7 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Tue, 6 Oct 2020 08:49:55 -0400 Subject: docs/devel: update instruction on how to add new unit tests Signed-off-by: Paolo Bonzini --- docs/devel/qtest.rst | 30 +++++++++++++++++++++--------- docs/devel/testing.rst | 19 ++++++++++--------- 2 files changed, 31 insertions(+), 18 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst index 075fe5f7d5..97c5a75626 100644 --- a/docs/devel/qtest.rst +++ b/docs/devel/qtest.rst @@ -33,15 +33,27 @@ Steps to add a new QTest case are: 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)`` +3. Register the new test in ``tests/qtest/meson.build``. Add the test + executable name to an appropriate ``qtests_*`` variable. There is + one variable per architecture, plus ``qtests_generic`` for tests + that can be run for all architectures. For example:: + + qtests_generic = [ + ... + 'foo-test', + ... + ] + +4. If the test has more than one source file or needs to be linked with any + dependency other than ``qemuutil`` and ``qos``, list them in the ``qtests`` + dictionary. For example a test that needs to use the ``QIO`` library + will have an entry like:: + + { + ... + 'foo-test': [io], + ... + } 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 diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index e58389b29f..0c3e79d31c 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -41,15 +41,16 @@ add a new unit test: test. The test code should be organized with the glib testing framework. Copying and modifying an existing test is usually a good idea. -3. Add the test to ``tests/Makefile.include``. First, name the unit test - program and add it to ``$(check-unit-y)``; then add a rule to build the - executable. For example: - -.. code:: - - check-unit-y += tests/foo-test$(EXESUF) - tests/foo-test$(EXESUF): tests/foo-test.o $(test-util-obj-y) - ... +3. Add the test to ``tests/meson.build``. The unit tests are listed in a + dictionary called ``tests``. The values are any additional sources and + dependencies to be linked with the test. For a simple test whose source + is in ``tests/foo-test.c``, it is enough to add an entry like:: + + { + ... + 'foo-test': [], + ... + } Since unit tests don't require environment variables, the simplest way to debug a unit test failure is often directly invoking it or even running it under -- cgit 1.4.1