@@ -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
@@ -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.
*
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(-)