qemu-devel.nongnu.org archive mirror
 help / color / mirror / Atom feed
From: marcandre.lureau@redhat.com
To: qemu-devel@nongnu.org
Cc: "Marc-André Lureau" <marcandre.lureau@redhat.com>, kraxel@redhat.com
Subject: [PATCH v2 23/37] docs: move D-Bus VMState documentation to source XML
Date: Sun, 10 Oct 2021 01:08:24 +0400	[thread overview]
Message-ID: <20211009210838.2219430-24-marcandre.lureau@redhat.com> (raw)
In-Reply-To: <20211009210838.2219430-1-marcandre.lureau@redhat.com>

From: Marc-André Lureau <marcandre.lureau@redhat.com>

Use the source XML document as single reference, importing its
documentation via the dbus-doc directive.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/interop/dbus-vmstate.rst | 52 ++++++-----------------------------
 backends/dbus-vmstate1.xml    | 42 +++++++++++++++++++++++++++-
 2 files changed, 49 insertions(+), 45 deletions(-)

diff --git a/docs/interop/dbus-vmstate.rst b/docs/interop/dbus-vmstate.rst
index 1d719c1c60..5fb3f279e2 100644
--- a/docs/interop/dbus-vmstate.rst
+++ b/docs/interop/dbus-vmstate.rst
@@ -2,9 +2,6 @@
 D-Bus VMState
 =============
 
-Introduction
-============
-
 The QEMU dbus-vmstate object's aim is to migrate helpers' data running
 on a QEMU D-Bus bus. (refer to the :doc:`dbus` document for
 some recommendations on D-Bus usage)
@@ -26,49 +23,16 @@ dbus-vmstate object can be configured with the expected list of
 helpers by setting its ``id-list`` property, with a comma-separated
 ``Id`` list.
 
-Interface
-=========
-
-On object path ``/org/qemu/VMState1``, the following
-``org.qemu.VMState1`` interface should be implemented:
-
-.. code:: xml
-
-  <interface name="org.qemu.VMState1">
-    <property name="Id" type="s" access="read"/>
-    <method name="Load">
-      <arg type="ay" name="data" direction="in"/>
-    </method>
-    <method name="Save">
-      <arg type="ay" name="data" direction="out"/>
-    </method>
-  </interface>
-
-"Id" property
--------------
-
-A string that identifies the helper uniquely. (maximum 256 bytes
-including terminating NUL byte)
-
-.. note::
-
-   The helper ID namespace is a separate namespace. In particular, it is not
-   related to QEMU "id" used in -object/-device objects.
-
-Load(in u8[] bytes) method
---------------------------
-
-The method called on destination with the state to restore.
+.. only:: sphinx4
 
-The helper may be initially started in a waiting state (with
-an --incoming argument for example), and it may resume on success.
+   .. dbus-doc:: backends/dbus-vmstate1.xml
 
-An error may be returned to the caller.
+.. only:: not sphinx4
 
-Save(out u8[] bytes) method
----------------------------
+   .. warning::
+      Sphinx 4 is required to build D-Bus documentation.
 
-The method called on the source to get the current state to be
-migrated. The helper should continue to run normally.
+      This is the content of ``backends/dbus-vmstate1.xml``:
 
-An error may be returned to the caller.
+   .. literalinclude:: ../../backends/dbus-vmstate1.xml
+      :language: xml
diff --git a/backends/dbus-vmstate1.xml b/backends/dbus-vmstate1.xml
index cc8563be4c..601ee8dc7e 100644
--- a/backends/dbus-vmstate1.xml
+++ b/backends/dbus-vmstate1.xml
@@ -1,10 +1,50 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="utf-8"?>
 <node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
+  <!--
+      org.qemu.VMState1:
+
+      This interface must be implemented at the object path
+      ``/org/qemu/VMState1`` to support helper migration.
+  -->
   <interface name="org.qemu.VMState1">
+
+    <!--
+        Id:
+
+        A string that identifies the helper uniquely. (maximum 256 bytes
+        including terminating NUL byte)
+
+        .. note::
+
+           The VMState helper ID namespace is its own namespace. In particular,
+           it is not related to QEMU "id" used in -object/-device objects.
+    -->
     <property name="Id" type="s" access="read"/>
+
+    <!--
+        Load:
+        @data: data to restore the state.
+
+        The method called on destination with the state to restore.
+
+        The helper may be initially started in a waiting state (with an
+        ``-incoming`` argument for example), and it may resume on success.
+
+        An error may be returned to the caller.
+    -->
     <method name="Load">
       <arg type="ay" name="data" direction="in"/>
     </method>
+
+    <!--
+        Save:
+        @data: state data to save for later resume.
+
+        The method called on the source to get the current state to be
+        migrated. The helper should continue to run normally.
+
+        An error may be returned to the caller.
+    -->
     <method name="Save">
       <arg type="ay" name="data" direction="out"/>
     </method>
-- 
2.33.0.721.g106298f7f9



  parent reply	other threads:[~2021-10-09 21:27 UTC|newest]

Thread overview: 54+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-10-09 21:08 [PATCH v2 00/37] Add D-Bus display backend marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 01/37] build-sys: move Spice configure handling to meson marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 02/37] ui/vdagent: add CHECK_SPICE_PROTOCOL_VERSION marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 03/37] ui/vdagent: replace #if 0 with protocol version check marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 04/37] ui: generalize clipboard notifier marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 05/37] ui/vdagent: add serial capability support marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 06/37] ui/clipboard: add qemu_clipboard_check_serial() marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 07/37] ui/clipboard: add a clipboard reset serial event marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 08/37] hw/display: report an error if virgl initialization failed marcandre.lureau
2021-12-17 12:40   ` Philippe Mathieu-Daudé
2021-10-09 21:08 ` [PATCH v2 09/37] virtio-gpu: use VIRTIO_GPU_RESOURCE_FLAG_Y_0_TOP marcandre.lureau
2021-12-17 12:51   ` Philippe Mathieu-Daudé
2021-10-09 21:08 ` [PATCH v2 10/37] ui: do not delay further remote resize marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 11/37] ui: factor out qemu_console_set_display_gl_ctx() marcandre.lureau
2021-12-17 13:36   ` Philippe Mathieu-Daudé
2021-10-09 21:08 ` [PATCH v2 12/37] ui: associate GL context outside of display listener registration marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 13/37] ui: make gl_block use a counter marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 14/37] ui: add a gl-unblock warning timer marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 15/37] ui: simplify gl unblock & flush marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 16/37] ui: dispatch GL events to all listeners marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 17/37] ui: split the GL context in a different object marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 18/37] ui: move qemu_spice_fill_device_address to ui/util.c marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 19/37] console: save current scanout details marcandre.lureau
2022-01-11  3:29   ` Akihiko Odaki
2022-01-11  8:23     ` Marc-André Lureau
2022-01-11 12:45       ` Akihiko Odaki
2021-10-09 21:08 ` [PATCH v2 20/37] scripts: teach modinfo to skip non-C sources marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 21/37] docs/sphinx: add sphinx modules to include D-Bus documentation marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 22/37] backends: move dbus-vmstate1.xml to backends/ marcandre.lureau
2021-10-09 21:08 ` marcandre.lureau [this message]
2021-10-09 21:08 ` [PATCH v2 24/37] docs: add dbus-display documentation marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 25/37] build-sys: set glib dependency version marcandre.lureau
2021-12-17 13:27   ` Philippe Mathieu-Daudé
2021-12-17 13:40     ` Marc-André Lureau
2021-12-17 14:36       ` Philippe Mathieu-Daudé
2021-10-09 21:08 ` [PATCH v2 26/37] ui: add a D-Bus display backend marcandre.lureau
2021-10-13  8:59   ` Marc-André Lureau
2021-10-09 21:08 ` [PATCH v2 27/37] ui/dbus: add p2p=on/off option marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 28/37] tests/qtests: add qtest_qmp_add_client() marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 29/37] tests: start dbus-display-test marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 30/37] audio: add "dbus" audio backend marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 31/37] ui/dbus: add clipboard interface marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 32/37] chardev: teach socket to accept no addresses marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 33/37] chardev: make socket derivable marcandre.lureau
2021-12-17 13:32   ` Philippe Mathieu-Daudé
2021-10-09 21:08 ` [PATCH v2 34/37] option: add g_auto for QemuOpts marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 35/37] ui/dbus: add chardev backend & interface marcandre.lureau
2021-10-09 21:08 ` [PATCH v2 36/37] ui/dbus: register D-Bus VC handler marcandre.lureau
2021-12-17 13:35   ` Philippe Mathieu-Daudé
2021-12-17 14:21     ` Marc-André Lureau
2021-10-09 21:08 ` [PATCH v2 37/37] MAINTAINERS: update D-Bus section marcandre.lureau
2021-10-13  5:22 ` [PATCH v2 00/37] Add D-Bus display backend Gerd Hoffmann
2021-12-16 20:53   ` Marc-André Lureau
2021-12-17  7:05     ` Gerd Hoffmann

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=20211009210838.2219430-24-marcandre.lureau@redhat.com \
    --to=marcandre.lureau@redhat.com \
    --cc=kraxel@redhat.com \
    --cc=qemu-devel@nongnu.org \
    /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).