docs/interop/dbus-vmstate.rst

   1 =============
   2 D-Bus VMState
   3 =============
   4
   5 Introduction
   6 ============
   7
   8 The QEMU dbus-vmstate object's aim is to migrate helpers' data running
   9 on a QEMU D-Bus bus. (refer to the :doc:`dbus` document for
  10 some recommendations on D-Bus usage)
  11
  12 Upon migration, QEMU will go through the queue of
  13 ``org.qemu.VMState1`` D-Bus name owners and query their ``Id``. It
  14 must be unique among the helpers.
  15
  16 It will then save arbitrary data of each Id to be transferred in the
  17 migration stream and restored/loaded at the corresponding destination
  18 helper.
  19
  20 For now, the data amount to be transferred is arbitrarily limited to
  21 1Mb. The state must be saved quickly (a fraction of a second). (D-Bus
  22 imposes a time limit on reply anyway, and migration would fail if data
  23 isn't given quickly enough.)
  24
  25 dbus-vmstate object can be configured with the expected list of
  26 helpers by setting its ``id-list`` property, with a comma-separated
  27 ``Id`` list.
  28
  29 Interface
  30 =========
  31
  32 On object path ``/org/qemu/VMState1``, the following
  33 ``org.qemu.VMState1`` interface should be implemented:
  34
  35 .. code:: xml
  36
  37   <interface name="org.qemu.VMState1">
  38     <property name="Id" type="s" access="read"/>
  39     <method name="Load">
  40       <arg type="ay" name="data" direction="in"/>
  41     </method>
  42     <method name="Save">
  43       <arg type="ay" name="data" direction="out"/>
  44     </method>
  45   </interface>
  46
  47 "Id" property
  48 -------------
  49
  50 A string that identifies the helper uniquely. (maximum 256 bytes
  51 including terminating NUL byte)
  52
  53 .. note::
  54
  55    The helper ID namespace is a separate namespace. In particular, it is not
  56    related to QEMU "id" used in -object/-device objects.
  57
  58 Load(in u8[] bytes) method
  59 --------------------------
  60
  61 The method called on destination with the state to restore.
  62
  63 The helper may be initially started in a waiting state (with
  64 an --incoming argument for example), and it may resume on success.
  65
  66 An error may be returned to the caller.
  67
  68 Save(out u8[] bytes) method
  69 ---------------------------
  70
  71 The method called on the source to get the current state to be
  72 migrated. The helper should continue to run normally.
  73
  74 An error may be returned to the caller.