From: Eduardo Habkost <ehabkost@redhat.com>
To: qemu-devel@nongnu.org
Cc: Laurent Vivier <lvivier@redhat.com>,
Paolo Bonzini <pbonzini@redhat.com>,
Thomas Huth <thuth@redhat.com>
Subject: [PATCH 2/3] docs/devel/qtest: Include protocol spec in document
Date: Mon, 5 Oct 2020 16:52:27 -0400 [thread overview]
Message-ID: <20201005205228.697463-3-ehabkost@redhat.com> (raw)
In-Reply-To: <20201005205228.697463-1-ehabkost@redhat.com>
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
next prev parent reply other threads:[~2020-10-05 20:54 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
2020-10-07 11:03 ` [PATCH 2/3] docs/devel/qtest: Include protocol spec in document 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20201005205228.697463-3-ehabkost@redhat.com \
--to=ehabkost@redhat.com \
--cc=lvivier@redhat.com \
--cc=pbonzini@redhat.com \
--cc=qemu-devel@nongnu.org \
--cc=thuth@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).