D-Bus VMState

The QEMU dbus-vmstate object’s aim is to migrate helpers’ data running on a QEMU D-Bus bus. (refer to the D-Bus document for some recommendations on D-Bus usage)

Upon migration, QEMU will go through the queue of org.qemu.VMState1 D-Bus name owners and query their Id. It must be unique among the helpers.

It will then save arbitrary data of each Id to be transferred in the migration stream and restored/loaded at the corresponding destination helper.

For now, the data amount to be transferred is arbitrarily limited to 1Mb. The state must be saved quickly (a fraction of a second). (D-Bus imposes a time limit on reply anyway, and migration would fail if data isn’t given quickly enough.)

dbus-vmstate object can be configured with the expected list of helpers by setting its id-list property, with a comma-separated Id list.

Warning

Sphinx 4 is required to build D-Bus documentation.

This is the content of backends/dbus-vmstate1.xml:

<?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>
  </interface>
</node>