From patchwork Mon Oct 5 20:52:26 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 303656 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-9.6 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id F3F03C4363A for ; Mon, 5 Oct 2020 20:54:31 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 697882078E for ; Mon, 5 Oct 2020 20:54:31 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="BJlP9S7E" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 697882078E Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:34798 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kPXV8-0003Cj-IJ for qemu-devel@archiver.kernel.org; Mon, 05 Oct 2020 16:54:30 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40594) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kPXTL-0001Uz-AQ for qemu-devel@nongnu.org; Mon, 05 Oct 2020 16:52:39 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:48133) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kPXTJ-0005pM-EP for qemu-devel@nongnu.org; Mon, 05 Oct 2020 16:52:39 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601931156; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=FWkmw4jnNLa7e3WcK8lioDh1h4GLfEcOUGIGYwjsRmI=; b=BJlP9S7EEXqEdnwpRYNIHK7TPh7J67LrVSjKcK2GLYo3x8FnjnmrlL/bkMIj0qx4MQ+Gxc 7x5tvlRPh2FSHyZ85Llmyzw9PecOYNagYDA2845KP6QA1kNZN9RpBW32O8zkm7yGAJV5Ev YHoSVrltJ9t5co4itnfA5B1QH4uph5w= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-281-SkYGjG08NJyxM9AGBmVDNg-1; Mon, 05 Oct 2020 16:52:34 -0400 X-MC-Unique: SkYGjG08NJyxM9AGBmVDNg-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id B0A28801AE2 for ; Mon, 5 Oct 2020 20:52:33 +0000 (UTC) Received: from localhost (ovpn-119-102.rdu2.redhat.com [10.10.119.102]) by smtp.corp.redhat.com (Postfix) with ESMTP id 4664678800; Mon, 5 Oct 2020 20:52:33 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH 1/3] docs: Move QTest documentation to its own document Date: Mon, 5 Oct 2020 16:52:26 -0400 Message-Id: <20201005205228.697463-2-ehabkost@redhat.com> In-Reply-To: <20201005205228.697463-1-ehabkost@redhat.com> References: <20201005205228.697463-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=216.205.24.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/10/05 02:11:31 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.733, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Laurent Vivier , Paolo Bonzini , Thomas Huth Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" 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 --- 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 ----------------- From patchwork Mon Oct 5 20:52:27 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 272016 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-9.6 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,WEIRD_QUOTING autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id E9831C47095 for ; Mon, 5 Oct 2020 20:54:34 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 3105E2078E for ; Mon, 5 Oct 2020 20:54:34 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="gHebiPwQ" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 3105E2078E Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:35046 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kPXVB-0003Iu-3B for qemu-devel@archiver.kernel.org; Mon, 05 Oct 2020 16:54:33 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40602) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kPXTM-0001Vv-Ak for qemu-devel@nongnu.org; Mon, 05 Oct 2020 16:52:40 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:29296) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kPXTK-0005pV-Hx for qemu-devel@nongnu.org; Mon, 05 Oct 2020 16:52:40 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601931157; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=wVQsFC/6CHovH8ATZVlcErcvtcUa1Ob5fQfvHRinQcI=; b=gHebiPwQ8owwQiDh0byB2Z15z7EX0jPx+WdgoZj4fBJnaA1KQ2fapQmu+lg2LdIUWFcu1P EF1XT9W6uIHXaQPTWil/CxhIWf0eAHmfrFVbhMcdPvLeh3wW/DBVLFXzwIvlw3doKeXMn8 zPcMlS2A9lCtzcPo8g96ARiMYhviooA= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-343-faz0S_b8Pwi1uWGzbbzbag-1; Mon, 05 Oct 2020 16:52:36 -0400 X-MC-Unique: faz0S_b8Pwi1uWGzbbzbag-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 65FEA925C46 for ; Mon, 5 Oct 2020 20:52:35 +0000 (UTC) Received: from localhost (ovpn-119-102.rdu2.redhat.com [10.10.119.102]) by smtp.corp.redhat.com (Postfix) with ESMTP id 2925618E3C; Mon, 5 Oct 2020 20:52:35 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH 2/3] docs/devel/qtest: Include protocol spec in document Date: Mon, 5 Oct 2020 16:52:27 -0400 Message-Id: <20201005205228.697463-3-ehabkost@redhat.com> In-Reply-To: <20201005205228.697463-1-ehabkost@redhat.com> References: <20201005205228.697463-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=216.205.24.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/10/05 02:11:31 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.733, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, WEIRD_QUOTING=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Laurent Vivier , Paolo Bonzini , Thomas Huth Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" Include the QTest Protocol doc string in docs/devel/qtest.rst, after converting it to use Sphinx syntax. Signed-off-by: Eduardo Habkost --- 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. * From patchwork Mon Oct 5 20:52:28 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 272015 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-9.6 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id B0E98C4363A for ; Mon, 5 Oct 2020 20:56:45 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 21A5E212CC for ; Mon, 5 Oct 2020 20:56:45 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="Bx6+7n+w" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 21A5E212CC Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:40894 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kPXXI-0005ol-A6 for qemu-devel@archiver.kernel.org; Mon, 05 Oct 2020 16:56:44 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40620) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kPXTQ-0001ap-5f for qemu-devel@nongnu.org; Mon, 05 Oct 2020 16:52:44 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:51621) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kPXTO-0005pz-9D for qemu-devel@nongnu.org; Mon, 05 Oct 2020 16:52:43 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601931161; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=xxT0lWY/pBsdRzPLysfCVHNonuY7lEkIqV/GVx79ho4=; b=Bx6+7n+wXLZRMn4jahfyo9w+2Qnj2TiqTPviwlbCMTL3ivbJjBcJkAxefRn2HC/Kg59O7H bjh9zQQ7i0tLVxa6Nh6WjAeqSDqBsyC7hi+6JlGFt/JHdlX7iVbatzIK0k4Qa2KuGmseiE HnTYfSrwKVfA9ms+h/13cL6yWopRIm0= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-85-042pkQhWOmuK30pVYDKPrg-1; Mon, 05 Oct 2020 16:52:40 -0400 X-MC-Unique: 042pkQhWOmuK30pVYDKPrg-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 2FA5E925C3E for ; Mon, 5 Oct 2020 20:52:39 +0000 (UTC) Received: from localhost (ovpn-119-102.rdu2.redhat.com [10.10.119.102]) by smtp.corp.redhat.com (Postfix) with ESMTP id 5525578807; Mon, 5 Oct 2020 20:52:36 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH 3/3] docs/devel/qtest: Include libqtest API reference Date: Mon, 5 Oct 2020 16:52:28 -0400 Message-Id: <20201005205228.697463-4-ehabkost@redhat.com> In-Reply-To: <20201005205228.697463-1-ehabkost@redhat.com> References: <20201005205228.697463-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=216.205.24.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/10/05 02:11:31 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.733, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Laurent Vivier , Paolo Bonzini , Thomas Huth Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" Signed-off-by: Eduardo Habkost --- 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 '%'. *