From: Marc-André Lureau <marcandre.lur...@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.lur...@redhat.com> Acked-by: Gerd Hoffmann <kra...@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 1d719c1c604f..5fb3f279e280 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 cc8563be4c92..601ee8dc7e4d 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.34.1.8.g35151cf07204