devel/migration/mapped-ram.rst

4 Mapped-ram is a new stream format for the RAM section designed to
5 supplement the existing ``file:`` migration and make it compatible
9 The core of the feature is to ensure that RAM pages are mapped
10 directly to offsets in the resulting migration file. This enables the
11 ``multifd`` threads to write exclusively to those offsets even if the
13 benefit is that the resulting file will have a bounded size, since
15 location in the file, rather than constantly being added to a
16 sequential stream. Having the pages at fixed offsets also allows the
17 usage of O_DIRECT for save/restore of the migration stream as the
24 On both source and destination, enable the ``multifd`` and
35 Mapped-ram migration is best done non-live, i.e. by stopping the VM on
36 the source side before migrating.
38 For best performance enable the ``direct-io`` parameter as well:
45 The mapped-ram feature was designed for use cases where the migration
46 stream will be directed to a file in the filesystem and not
47 immediately restored on the destination VM\ [#alternatives]_. These could be
53 If the use case requires a VM to be stopped before taking a snapshot,
54 that's the ideal scenario for mapped-ram migration. Not having to
55 track dirty pages, the migration will write the RAM pages to the disk
58 Note: if a snapshot is taken of a running VM, but the VM will be
59 stopped after the snapshot by the admin, then consider stopping it
60 right before the snapshot to take benefit of the performance gains
65 If the use case requires that the VM keeps running during and after
66 the snapshot operation, then mapped-ram migration can still be used,
73 .. [#alternatives] While this same effect could be obtained with the usage of
74        snapshots or the ``file:`` migration alone, mapped-ram provides
76        100s of GiBs), specially if the VM has been stopped beforehand.
81 Instead of having a sequential stream of pages that follow the
82 RAMBlock headers, the dirty pages for a RAMBlock follow its header
83 instead. This ensures that each RAM page has a fixed offset in the
86 A bitmap is introduced to track which pages have been written in the
88 ramblock. Zero pages are ignored as they'd be zero in the destination
124  - ramblock header: the generic information for a ramblock, such as
127  - ramblock mapped-ram header: the information added by this feature:
128    bitmap of pages written, bitmap size and offset of pages in the
135 (due to the memory dirtying patterns), streaming channels such as
137 required. This can be verified in the QIOChannel by the presence of
138 the QIO_CHANNEL_FEATURE_SEEKABLE.
140 The improvements brought by this feature apply only to guest physical