docs: Include QTest protocol and libqtest API on documentation
cover docs: Include QTest protocol and libqtest API on documentation
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
Signature · 1 line
2.26.2
PATCH 1/3 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.
--- 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
docs/devel/index.rst +1 -0
@@ -21,6 +21,7 @@ Contents: atomics stable-process testing + qtest decodetree secure-coding-practices tcg
docs/devel/qtest.rst new file +58 -0
58 lines not on this page · raw message
docs/devel/testing.rst +2 -45
59 lines not on this page · raw message
Signature · 1 line
2.26.2
PATCH 2/3 docs/devel/qtest: Include protocol spec in document
In reply to Eduardo HabkostInclude the QTest Protocol doc string in docs/devel/qtest.rst, after converting it to use Sphinx syntax.
--- docs/devel/qtest.rst | 12 ++++++-- softmmu/qtest.c | 73 +++++++++++++++++++++++++++++++++++++++----- 2 files changed, 75 insertions(+), 10 deletions(-)
docs/devel/qtest.rst +10 -2
@@ -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
softmmu/qtest.c +65 -8
185 lines not on this page · raw message
Signature · 1 line
2.26.2
PATCH 3/3 docs/devel/qtest: Include libqtest API reference
In reply to Eduardo Habkost--- docs/devel/qtest.rst | 6 ++++++ tests/qtest/libqos/libqtest.h | 20 ++++++++++---------- 2 files changed, 16 insertions(+), 10 deletions(-)
docs/devel/qtest.rst +6 -0
@@ -64,3 +64,9 @@ QTest Protocol .. kernel-doc:: softmmu/qtest.c :doc: QTest Protocol + + +libqtest API reference +---------------------- + +.. kernel-doc:: tests/qtest/libqos/libqtest.h
tests/qtest/libqos/libqtest.h +10 -10
@@ -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 '%'. *
Signature · 1 line
2.26.2
Quoted 9 lines · Eduardo Habkost
This moves the QTest section of
testing.rstto 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
Quoted 8 lines
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
Re: [PATCH 3/3] docs/devel/qtest: Include libqtest API reference
In reply to Eduardo HabkostQuoted 43 lines · Eduardo Habkost
Signed-off-by Eduardo Habkost <[email protected]>--- docs/devel/qtest.rst | 6 ++++++ tests/qtest/libqos/libqtest.h | 20 ++++++++++---------- 2 files changed, 16 insertions(+), 10 deletions(-)docs/devel/qtest.rst +6
-0@@ -64,3 +64,9 @@ QTest Protocol .. kernel-doc:: softmmu/qtest.c :doc: QTest Protocol + + +libqtest API reference +---------------------- + +.. kernel-doc:: tests/qtest/libqos/libqtest.htests/qtest/libqos/libqtest.h +2
-2@@ -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 '%'. *
tests/qtest/libqos/libqtest.h QDict *qtest_qmp_fds(QTestState *s, int *fds, size_t fds_num, · line 103
Quoted 5 lines
tests/qtest/libqos/libqtest.h +1
-1@@ -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
Quoted 9 lines · Eduardo Habkost
This moves the QTest section of
testing.rstto 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
Quoted 7 lines
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:
Re: [PATCH 3/3] docs/devel/qtest: Include libqtest API reference
In reply to Thomas HuthQuoted 42 lines · Thomas Huth
Quoted 41 lines · Eduardo Habkost
Signed-off-by Eduardo Habkost <[email protected]>--- docs/devel/qtest.rst | 6 ++++++ tests/qtest/libqos/libqtest.h | 20 ++++++++++---------- 2 files changed, 16 insertions(+), 10 deletions(-)docs/devel/qtest.rst +6
-0@@ -64,3 +64,9 @@ QTest Protocol .. kernel-doc:: softmmu/qtest.c :doc: QTest Protocol + + +libqtest API reference +---------------------- + +.. kernel-doc:: tests/qtest/libqos/libqtest.htests/qtest/libqos/libqtest.h +2
-2@@ -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,
Quoted 8 lines
tests/qtest/libqos/libqtest.h QDict *qtest_qmp_fds(QTestState *s, int *fds, size_t fds_num, · line 103
Quoted 5 lines
tests/qtest/libqos/libqtest.h +1
-1/** * 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.
Signature · 1 line
Eduardo
Re: [PATCH 2/3] docs/devel/qtest: Include protocol spec in document
In reply to Eduardo HabkostQuoted 11 lines · Eduardo Habkost
+ * 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
+ * ^^^^^^^^^^^^^^
*
Quoted 8 lines
* Clock management:
+ * """""""""""""""""
*
* The qtest client is completely in charge of theQEMU_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
Re: [PATCH 2/3] docs/devel/qtest: Include protocol spec in document
Quoted 21 lines · Paolo Bonzini
Quoted 11 lines · Eduardo Habkost
+ * 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
+ * ^^^^^^^^^^^^^^
*Quoted 8 lines
* Clock management:
+ * """""""""""""""""
*
* The qtest client is completely in charge of theQEMU_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::
Quoted 3 lines
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.
Signature · 1 line
Eduardo
Re: [PATCH 2/3] docs/devel/qtest: Include protocol spec in document
Quoted 7 lines · Eduardo Habkost
Quoted 3 lines
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