docs: Move xbzrle.txt into the migration folder and convert to rst
xbzrle is a feature of migration and thus this file should go into the docs/devel/migration/ folder. While we're at it, turn it into proper .rst format, too. Signed-off-by: Thomas Huth <thuth@redhat.com> Reviewed-by: Peter Xu <peterx@redhat.com> Reviewed-by: Michael Tokarev <mjt@tls.msk.ru> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
Thomas Huth committed
Mar 10, 2026 at 10:28 UTC
271e2a38a22c4db76e30c9293eb7f9b8b6081cd6
2 files changed
+65
-42
docs/devel/migration/features.rst
+1
@@ -15,3 +15,4 @@ Migration has plenty of features to support different use cases.
15
qpl-compression
16
uadk-compression
17
qatzip-compression
18
+ xbzrle
docs/devel/migration/xbzrle.rst
renamed
+64
-42
@@ -20,7 +20,7 @@ A small cache size will result in high cache miss rate.
20
Cache size can be changed before and during migration.
21
22
Format
23
-=======
23
+------
24
25
The compression format performs a XOR between the previous and current content
26
of the page, where zero represents an unchanged value.
@@ -29,17 +29,19 @@ A zero run is represented by its length (in bytes).
29
A non zero run is represented by its length (in bytes) and the new data.
30
The run length is encoded using ULEB128 (http://en.wikipedia.org/wiki/LEB128)
31
32
-There can be more than one valid encoding, the sender may send a longer encoding
33
-for the benefit of reducing computation cost.
32
+There can be more than one valid encoding, the sender may send a longer
33
+encoding for the benefit of reducing computation cost.
34
35
-page = zrun nzrun
36
- | zrun nzrun page
35
+::
36
38
-zrun = length
37
+ page = zrun nzrun
38
+ | zrun nzrun page
39
40
-nzrun = length byte...
40
+ zrun = length
41
42
-length = uleb128 encoded integer
42
+ nzrun = length byte...
43
+
44
+ length = uleb128 encoded integer
45
46
On the sender side XBZRLE is used as a compact delta encoding of page updates,
47
retrieving the old page content from the cache (default size of 64MB). The
@@ -55,24 +57,34 @@ instead.
57
XBZRLE has a sustained bandwidth of 2-2.5 GB/s for typical workloads making it
58
ideal for in-line, real-time encoding such as is needed for live-migration.
59
58
-Example
60
+Example:
61
+
62
old buffer:
60
-1001 zeros
61
-05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 68 00 00 6b 00 6d
62
-3074 zeros
63
+
64
+.. code:: batch
65
+
66
+ 1001 zeros
67
+ 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 68 00 00 6b 00 6d
68
+ 3074 zeros
69
70
new buffer:
65
-1001 zeros
66
-01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 68 00 00 67 00 69
67
-3074 zeros
71
+
72
+.. code:: batch
73
+
74
+ 1001 zeros
75
+ 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 68 00 00 67 00 69
76
+ 3074 zeros
77
78
encoded buffer:
79
71
-encoded length 24
72
-e9 07 0f 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 03 01 67 01 01 69
80
+.. code:: batch
81
+
82
+ encoded length 24
83
+ e9 07 0f 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 03 01 67 01 01 69
84
85
Cache update strategy
75
-=====================
86
+---------------------
87
+
88
Keeping the hot pages in the cache is effective for decreasing cache
89
misses. XBZRLE uses a counter as the age of each page. The counter will
90
increase after each ram dirty bitmap sync. When a cache conflict is
@@ -80,21 +92,27 @@ detected, XBZRLE will only evict pages in the cache that are older than
92
a threshold.
93
94
Usage
83
-======================
84
-1. Verify the destination QEMU version is able to decode the new format.
85
- {qemu} info migrate_capabilities
86
- {qemu} xbzrle: off , ...
95
+-----
96
88
-2. Activate xbzrle on both source and destination:
89
- {qemu} migrate_set_capability xbzrle on
97
+1. Verify the destination QEMU version is able to decode the new format::
98
+
99
+ (qemu) info migrate_capabilities
100
+ xbzrle: off
101
+ ...
102
+
103
+2. Activate xbzrle on both source and destination::
104
+
105
+ (qemu) migrate_set_capability xbzrle on
106
107
3. Set the XBZRLE cache size - the cache size is in MBytes and should be a
92
-power of 2. The cache default value is 64MBytes. (on source only)
93
- {qemu} migrate_set_parameter xbzrle-cache-size 256m
108
+ power of 2. The cache default value is 64 MBytes (on source only)::
109
+
110
+ (qemu) migrate_set_parameter xbzrle-cache-size 256m
111
95
-4. Start outgoing migration
96
- {qemu} migrate -d tcp:destination.host:4444
97
- {qemu} info migrate
112
+4. Start outgoing migration::
113
+
114
+ (qemu) migrate -d tcp:destination.host:4444
115
+ (qemu) info migrate
116
capabilities: xbzrle: on
117
Migration status: active
118
transferred ram: A kbytes
@@ -114,6 +132,7 @@ power of 2. The cache default value is 64MBytes. (on source only)
132
133
xbzrle cache miss: the number of cache misses to date - high cache-miss rate
134
indicates that the cache size is set too low.
135
+
136
xbzrle overflow: the number of overflows in the decoding which where the delta
137
could not be compressed. This can happen if the changes in the pages are too
138
large or there are many short changes; for example, changing every second byte
@@ -123,16 +142,19 @@ Testing: Testing indicated that live migration with XBZRLE was completed in 110
142
seconds, whereas without it would not be able to complete.
143
144
A simple synthetic memory r/w load generator:
126
-.. include <stdlib.h>
127
-.. include <stdio.h>
128
-.. int main()
129
-.. {
130
-.. char *buf = (char *) calloc(4096, 4096);
131
-.. while (1) {
132
-.. int i;
133
-.. for (i = 0; i < 4096 * 4; i++) {
134
-.. buf[i * 4096 / 4]++;
135
-.. }
136
-.. printf(".");
137
-.. }
138
-.. }
145
+
146
+.. code-block:: c
147
+
148
+ #include <stdlib.h>
149
+ #include <stdio.h>
150
+ int main()
151
+ {
152
+ char *buf = (char *) calloc(4096, 4096);
153
+ while (1) {
154
+ int i;
155
+ for (i = 0; i < 4096 * 4; i++) {
156
+ buf[i * 4096 / 4]++;
157
+ }
158
+ printf(".");
159
+ }
160
+ }