Skip to contentSkip to conversation

docs: Include QTest protocol and libqtest API on documentation

PATCH In review Eduardo Habkost 3 participants 11 messages Oct 5, 2020 – Oct 7, 2020

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index c34b43ec28e..d147b900a98 100644
@@ -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
#2 lore raw

PATCH 2/3 docs/devel/qtest: Include protocol spec in document

In reply to Eduardo Habkost

Include 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
index 86dec84a0ba..3bf9ebee7f0 100644
@@ -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
#6 lore raw

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
index 3bf9ebee7f0..075fe5f7d53 100644
@@ -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
index a6ee1654f20..209fcf69737 100644
@@ -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
#9 lore raw
In reply to Eduardo Habkost
Quoted 9 lines · Eduardo Habkost

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

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

#7 lore raw

Re: [PATCH 3/3] docs/devel/qtest: Include libqtest API reference

In reply to Eduardo Habkost
Quoted 43 lines · 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
index 3bf9ebee7f0..075fe5f7d53 100644
@@ -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 +2 -2
index a6ee1654f20..209fcf69737 100644
@@ -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

Acked-by on the v1 series
#10 lore raw
In reply to Eduardo Habkost
Quoted 9 lines · Eduardo Habkost

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

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:

#8 lore raw

Re: [PATCH 3/3] docs/devel/qtest: Include libqtest API reference

In reply to Thomas Huth
Quoted 42 lines · Thomas Huth
Quoted 41 lines · 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
index 3bf9ebee7f0..075fe5f7d53 100644
@@ -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 +2 -2
index a6ee1654f20..209fcf69737 100644
@@ -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
#3 lore raw

Re: [PATCH 2/3] docs/devel/qtest: Include protocol spec in document

In reply to Eduardo Habkost
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 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

#4 lore raw

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 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::

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
#5 lore raw

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