| Marc-André Lureau | 5010cec | 2019-12-16 11:48:53 +0400 | [diff] [blame] | 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. |
