* [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation
@ 2020-10-05 20:52 Eduardo Habkost
2020-10-05 20:52 ` [PATCH 1/3] docs: Move QTest documentation to its own document Eduardo Habkost
` (4 more replies)
0 siblings, 5 replies; 11+ messages in thread
From: Eduardo Habkost @ 2020-10-05 20:52 UTC (permalink / raw)
To: qemu-devel; +Cc: Laurent Vivier, Paolo Bonzini, Thomas Huth
This moves the QTest section of testing.rst to a separate
document, and include the QTest Protocol specification and
libqtest API reference in the document.
Eduardo Habkost (3):
docs: Move QTest documentation to its own document
docs/devel/qtest: Include protocol spec in document
docs/devel/qtest: Include libqtest API reference
docs/devel/index.rst | 1 +
docs/devel/qtest.rst | 72 ++++++++++++++++++++++++++++++++++
docs/devel/testing.rst | 47 +---------------------
tests/qtest/libqos/libqtest.h | 20 +++++-----
softmmu/qtest.c | 73 +++++++++++++++++++++++++++++++----
5 files changed, 150 insertions(+), 63 deletions(-)
create mode 100644 docs/devel/qtest.rst
--
2.26.2
^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH 1/3] docs: Move QTest documentation to its own document
2020-10-05 20:52 [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation Eduardo Habkost
@ 2020-10-05 20:52 ` Eduardo Habkost
2020-10-05 20:52 ` [PATCH 2/3] docs/devel/qtest: Include protocol spec in document Eduardo Habkost
` (3 subsequent siblings)
4 siblings, 0 replies; 11+ messages in thread
From: Eduardo Habkost @ 2020-10-05 20:52 UTC (permalink / raw)
To: qemu-devel; +Cc: Laurent Vivier, Paolo Bonzini, Thomas Huth
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>
---
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 c34b43ec28e..d147b900a98 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 00000000000..86dec84a0ba
--- /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 bd64c1bdcdd..a171494b4e5 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
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [PATCH 2/3] docs/devel/qtest: Include protocol spec in document
2020-10-05 20:52 [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation Eduardo Habkost
2020-10-05 20:52 ` [PATCH 1/3] docs: Move QTest documentation to its own document Eduardo Habkost
@ 2020-10-05 20:52 ` Eduardo Habkost
2020-10-07 11:03 ` Paolo Bonzini
2020-10-05 20:52 ` [PATCH 3/3] docs/devel/qtest: Include libqtest API reference Eduardo Habkost
` (2 subsequent siblings)
4 siblings, 1 reply; 11+ messages in thread
From: Eduardo Habkost @ 2020-10-05 20:52 UTC (permalink / raw)
To: qemu-devel; +Cc: Laurent Vivier, Paolo Bonzini, Thomas Huth
Include the QTest Protocol doc string in docs/devel/qtest.rst,
after converting it to use Sphinx syntax.
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
docs/devel/qtest.rst | 12 ++++++--
softmmu/qtest.c | 73 +++++++++++++++++++++++++++++++++++++++-----
2 files changed, 75 insertions(+), 10 deletions(-)
diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst
index 86dec84a0ba..3bf9ebee7f0 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 4e439caec7e..9382fd25439 100644
--- a/softmmu/qtest.c
+++ b/softmmu/qtest.c
@@ -49,92 +49,141 @@ static void *qtest_server_send_opaque;
#define FMT_timeval "%ld.%06ld"
/**
- * QTest Protocol
+ * DOC: QTest Protocol
+ *
+ * .. highlight:: none
*
* 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::
+ *
* > 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::
*
* > clock_step NS
* < OK VALUE
*
- * Advance the clock by NS nanoseconds.
+ * Advance the clock by NS nanoseconds.
+ *
+ * .. code-block::
*
* > 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::
*
* > outb ADDR VALUE
* < OK
*
+ * .. code-block::
+ *
* > outw ADDR VALUE
* < OK
*
+ * .. code-block::
+ *
* > outl ADDR VALUE
* < OK
*
+ * .. code-block::
+ *
* > inb ADDR
* < OK VALUE
*
+ * .. code-block::
+ *
* > inw ADDR
* < OK VALUE
*
+ * .. code-block::
+ *
* > inl ADDR
* < OK VALUE
*
+ * .. code-block::
+ *
* > writeb ADDR VALUE
* < OK
*
+ * .. code-block::
+ *
* > writew ADDR VALUE
* < OK
*
+ * .. code-block::
+ *
* > writel ADDR VALUE
* < OK
*
+ * .. code-block::
+ *
* > writeq ADDR VALUE
* < OK
*
+ * .. code-block::
+ *
* > readb ADDR
* < OK VALUE
*
+ * .. code-block::
+ *
* > readw ADDR
* < OK VALUE
*
+ * .. code-block::
+ *
* > readl ADDR
* < OK VALUE
*
+ * .. code-block::
+ *
* > readq ADDR
* < OK VALUE
*
+ * .. code-block::
+ *
* > read ADDR SIZE
* < OK DATA
*
+ * .. code-block::
+ *
* > write ADDR SIZE DATA
* < OK
*
+ * .. code-block::
+ *
* > b64read ADDR SIZE
* < OK B64_DATA
*
+ * .. code-block::
+ *
* > b64write ADDR SIZE B64_DATA
* < OK
*
+ * .. code-block::
+ *
* > memset ADDR SIZE VALUE
* < OK
*
@@ -149,16 +198,21 @@ static void *qtest_server_send_opaque;
* If the sizes do not match, the data will be truncated.
*
* IRQ management:
+ * """""""""""""""
+ *
+ * .. code-block::
*
* > irq_intercept_in QOM-PATH
* < OK
*
+ * .. code-block::
+ *
* > 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 +222,15 @@ static void *qtest_server_send_opaque;
* NUM=0 even though it is remapped to GSI 2).
*
* Setting interrupt level:
+ * """"""""""""""""""""""""
+ *
+ * .. code-block::
*
* > 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.
*
--
2.26.2
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [PATCH 3/3] docs/devel/qtest: Include libqtest API reference
2020-10-05 20:52 [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation Eduardo Habkost
2020-10-05 20:52 ` [PATCH 1/3] docs: Move QTest documentation to its own document Eduardo Habkost
2020-10-05 20:52 ` [PATCH 2/3] docs/devel/qtest: Include protocol spec in document Eduardo Habkost
@ 2020-10-05 20:52 ` Eduardo Habkost
2020-10-06 17:12 ` Thomas Huth
2020-10-06 12:42 ` [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation Paolo Bonzini
2020-10-06 17:12 ` Thomas Huth
4 siblings, 1 reply; 11+ messages in thread
From: Eduardo Habkost @ 2020-10-05 20:52 UTC (permalink / raw)
To: qemu-devel; +Cc: Laurent Vivier, Paolo Bonzini, Thomas Huth
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
docs/devel/qtest.rst | 6 ++++++
tests/qtest/libqos/libqtest.h | 20 ++++++++++----------
2 files changed, 16 insertions(+), 10 deletions(-)
diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst
index 3bf9ebee7f0..075fe5f7d53 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 a6ee1654f20..209fcf69737 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 '%'.
*
--
2.26.2
^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation
2020-10-05 20:52 [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation Eduardo Habkost
` (2 preceding siblings ...)
2020-10-05 20:52 ` [PATCH 3/3] docs/devel/qtest: Include libqtest API reference Eduardo Habkost
@ 2020-10-06 12:42 ` Paolo Bonzini
2020-10-06 17:12 ` Thomas Huth
4 siblings, 0 replies; 11+ messages in thread
From: Paolo Bonzini @ 2020-10-06 12:42 UTC (permalink / raw)
To: Eduardo Habkost, qemu-devel; +Cc: Laurent Vivier, Thomas Huth
On 05/10/20 22:52, Eduardo Habkost wrote:
> This moves the QTest section of testing.rst to a separate
> document, and include the QTest Protocol specification and
> libqtest API reference in the document.
>
> Eduardo Habkost (3):
> docs: Move QTest documentation to its own document
> docs/devel/qtest: Include protocol spec in document
> docs/devel/qtest: Include libqtest API reference
>
> docs/devel/index.rst | 1 +
> docs/devel/qtest.rst | 72 ++++++++++++++++++++++++++++++++++
> docs/devel/testing.rst | 47 +---------------------
> tests/qtest/libqos/libqtest.h | 20 +++++-----
> softmmu/qtest.c | 73 +++++++++++++++++++++++++++++++----
> 5 files changed, 150 insertions(+), 63 deletions(-)
> create mode 100644 docs/devel/qtest.rst
>
The series is moving obsolete (non-mesonified) information. I should
fix the docs at the same time, so I've queued it and will send the fix
on top.
Paolo
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 3/3] docs/devel/qtest: Include libqtest API reference
2020-10-05 20:52 ` [PATCH 3/3] docs/devel/qtest: Include libqtest API reference Eduardo Habkost
@ 2020-10-06 17:12 ` Thomas Huth
2020-10-06 17:22 ` Eduardo Habkost
0 siblings, 1 reply; 11+ messages in thread
From: Thomas Huth @ 2020-10-06 17:12 UTC (permalink / raw)
To: Eduardo Habkost, qemu-devel; +Cc: Laurent Vivier, Paolo Bonzini
On 05/10/2020 22.52, Eduardo Habkost wrote:
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
> docs/devel/qtest.rst | 6 ++++++
> tests/qtest/libqos/libqtest.h | 20 ++++++++++----------
> 2 files changed, 16 insertions(+), 10 deletions(-)
>
> diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst
> index 3bf9ebee7f0..075fe5f7d53 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 a6ee1654f20..209fcf69737 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
I think you should mention those changes to all those "fmt..." in the commit
message?
Thomas
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation
2020-10-05 20:52 [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation Eduardo Habkost
` (3 preceding siblings ...)
2020-10-06 12:42 ` [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation Paolo Bonzini
@ 2020-10-06 17:12 ` Thomas Huth
4 siblings, 0 replies; 11+ messages in thread
From: Thomas Huth @ 2020-10-06 17:12 UTC (permalink / raw)
To: Eduardo Habkost, qemu-devel; +Cc: Laurent Vivier, Paolo Bonzini
On 05/10/2020 22.52, Eduardo Habkost wrote:
> This moves the QTest section of testing.rst to a separate
> document, and include the QTest Protocol specification and
> libqtest API reference in the document.
>
> Eduardo Habkost (3):
> docs: Move QTest documentation to its own document
> docs/devel/qtest: Include protocol spec in document
> docs/devel/qtest: Include libqtest API reference
>
> docs/devel/index.rst | 1 +
> docs/devel/qtest.rst | 72 ++++++++++++++++++++++++++++++++++
> docs/devel/testing.rst | 47 +---------------------
> tests/qtest/libqos/libqtest.h | 20 +++++-----
> softmmu/qtest.c | 73 +++++++++++++++++++++++++++++++----
> 5 files changed, 150 insertions(+), 63 deletions(-)
> create mode 100644 docs/devel/qtest.rst
FWIW:
Acked-by: Thomas Huth <thuth@redhat.com>
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 3/3] docs/devel/qtest: Include libqtest API reference
2020-10-06 17:12 ` Thomas Huth
@ 2020-10-06 17:22 ` Eduardo Habkost
0 siblings, 0 replies; 11+ messages in thread
From: Eduardo Habkost @ 2020-10-06 17:22 UTC (permalink / raw)
To: Thomas Huth; +Cc: Laurent Vivier, Paolo Bonzini, qemu-devel
On Tue, Oct 06, 2020 at 07:12:17PM +0200, Thomas Huth wrote:
> On 05/10/2020 22.52, Eduardo Habkost wrote:
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
> > docs/devel/qtest.rst | 6 ++++++
> > tests/qtest/libqos/libqtest.h | 20 ++++++++++----------
> > 2 files changed, 16 insertions(+), 10 deletions(-)
> >
> > diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst
> > index 3bf9ebee7f0..075fe5f7d53 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 a6ee1654f20..209fcf69737 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
>
> I think you should mention those changes to all those "fmt..." in the commit
> message?
Yes. I mentioned "after converting it to Sphinx syntax" on patch
2/3, but forgot to mention the same thing in this patch.
--
Eduardo
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 2/3] docs/devel/qtest: Include protocol spec in document
2020-10-05 20:52 ` [PATCH 2/3] docs/devel/qtest: Include protocol spec in document Eduardo Habkost
@ 2020-10-07 11:03 ` Paolo Bonzini
2020-10-07 11:39 ` Eduardo Habkost
0 siblings, 1 reply; 11+ messages in thread
From: Paolo Bonzini @ 2020-10-07 11:03 UTC (permalink / raw)
To: Eduardo Habkost, qemu-devel; +Cc: Laurent Vivier, Thomas Huth
On 05/10/20 22:52, Eduardo Habkost wrote:
> + * DOC: QTest Protocol
> + *
> + * .. highlight:: none
> *
> * 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::
What version of Sphinx do you have? I need to have ".. code-block::
none" here, so presumably the "highlight" directive is newer than my
version (1.7.6, pretty old I admit)?
Paolo
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 2/3] docs/devel/qtest: Include protocol spec in document
2020-10-07 11:03 ` Paolo Bonzini
@ 2020-10-07 11:39 ` Eduardo Habkost
2020-10-07 12:01 ` Paolo Bonzini
0 siblings, 1 reply; 11+ messages in thread
From: Eduardo Habkost @ 2020-10-07 11:39 UTC (permalink / raw)
To: Paolo Bonzini; +Cc: Laurent Vivier, Thomas Huth, qemu-devel
On Wed, Oct 07, 2020 at 01:03:21PM +0200, Paolo Bonzini wrote:
> On 05/10/20 22:52, Eduardo Habkost wrote:
> > + * DOC: QTest Protocol
> > + *
> > + * .. highlight:: none
> > *
> > * 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::
>
> What version of Sphinx do you have? I need to have ".. code-block::
> none" here, so presumably the "highlight" directive is newer than my
> version (1.7.6, pretty old I admit)?
I have 2.2.2.
It looks like we should really add code to print a warning if not
running Sphinx 2.x.
--
Eduardo
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 2/3] docs/devel/qtest: Include protocol spec in document
2020-10-07 11:39 ` Eduardo Habkost
@ 2020-10-07 12:01 ` Paolo Bonzini
0 siblings, 0 replies; 11+ messages in thread
From: Paolo Bonzini @ 2020-10-07 12:01 UTC (permalink / raw)
To: Eduardo Habkost; +Cc: Laurent Vivier, Thomas Huth, qemu-devel
On 07/10/20 13:39, Eduardo Habkost wrote:
>> What version of Sphinx do you have? I need to have ".. code-block::
>> none" here, so presumably the "highlight" directive is newer than my
>> version (1.7.6, pretty old I admit)?
> I have 2.2.2.
>
> It looks like we should really add code to print a warning if not
> running Sphinx 2.x.
1.x seems to work just fine though, and it's what is included in RHEL8
"CodeReady Linux Builder" repository
(https://developers.redhat.com/blog/2018/11/15/introducing-codeready-linux-builder/).
Paolo
^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2020-10-07 12:18 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-10-05 20:52 [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation Eduardo Habkost
2020-10-05 20:52 ` [PATCH 1/3] docs: Move QTest documentation to its own document Eduardo Habkost
2020-10-05 20:52 ` [PATCH 2/3] docs/devel/qtest: Include protocol spec in document Eduardo Habkost
2020-10-07 11:03 ` Paolo Bonzini
2020-10-07 11:39 ` Eduardo Habkost
2020-10-07 12:01 ` Paolo Bonzini
2020-10-05 20:52 ` [PATCH 3/3] docs/devel/qtest: Include libqtest API reference Eduardo Habkost
2020-10-06 17:12 ` Thomas Huth
2020-10-06 17:22 ` Eduardo Habkost
2020-10-06 12:42 ` [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation Paolo Bonzini
2020-10-06 17:12 ` Thomas Huth
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).