From nobody Tue Apr 7 06:15:59 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org ARC-Seal: i=1; a=rsa-sha256; t=1773645251; cv=none; d=zohomail.com; s=zohoarc; b=bVkeQ2U16q7x6SBrs52PL1nJX6o71O/gBakJT2zYfKqnflMvtgUzB2v60XXYFqInlcQFVRJa2fIPPwWgxL+3XkZuaUGkaxToVGXA6eqdiyUmeVH2Zp/U/sYzcEJK0KNejaAWUgz2IPle7HpsDcdCY9PH0jJguYJkokzX6jHMYoM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1773645251; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=diP3xyNUd3ZEg7N2XiBrEuaQ9ghYMt/w1qHZdpyEdMI=; b=EabzLs6FjpQzV56sjN/DivYS+5Dky3dmuHJxlOS/lRpf5tgrcXwigvepGhjtwMscngD6Qiy1NU/qlthTbldHxOZ7U9RWVaW7gPHcZys0r13ExaGOsHEKBuf9tsTvjw+xMUEpFlnP2QDeLa55K8rc6x/tcN2mjD4dlaTZkcG7ZCM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 177364525154387.64321785178299; Mon, 16 Mar 2026 00:14:11 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1w226Q-0007pU-Mb; Mon, 16 Mar 2026 03:11:02 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1w225t-0007Vy-EJ; Mon, 16 Mar 2026 03:10:32 -0400 Received: from isrv.corpit.ru ([212.248.84.144]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1w225p-0007m0-DP; Mon, 16 Mar 2026 03:10:27 -0400 Received: from tsrv.corpit.ru (tsrv.tls.msk.ru [192.168.177.2]) by isrv.corpit.ru (Postfix) with ESMTP id D8879193C29; Mon, 16 Mar 2026 10:10:02 +0300 (MSK) Received: from think4mjt.tls.msk.ru (mjtthink.wg.tls.msk.ru [192.168.177.146]) by tsrv.corpit.ru (Postfix) with ESMTP id E1253380051; Mon, 16 Mar 2026 10:10:05 +0300 (MSK) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=tls.msk.ru; s=202602; t=1773645002; bh=9L7t5ss71R6N1H6jAb9ssg+VvhN8SmRC3QAN3PvN090=; h=From:To:Cc:Subject:Date:In-Reply-To:References; b=uEjMThPdNNmeB13Vzh3Dc0Mr5AIOfnV++U9PH7s9jjYYY1F4B2iyI1x6C2r6BkmMZ 5Mq/KQduGGh6BF6Wy+WEkc4d7Y78KJDf85TkIH/t6S5fkDc3LVYHprXtm6CpUs1uwb f5FW83rE1fu9IEiBx58R1cVf5gKLxqw8xZsOLE+e3JdxzxRKqw8a13ygnBt/Qm4HTE ljeCK3P+XMmKd94q70bisC4zE9HWiDSL0scmNJIleT28YnKUG7izuGMQQNYBJ5GILh s+LGzHu+pvCRMPcl+KcAADriW6MNXae18YM2oiIfLmXYrFBFMPQt3LBi8OkGAYmoK3 QQzj93TXRm0nw== From: Michael Tokarev To: qemu-devel@nongnu.org Cc: Thomas Huth , qemu-trivial@nongnu.org, Michael Tokarev Subject: [PULL 07/14] docs: Move xbzrle.txt into the migration folder and convert to rst Date: Mon, 16 Mar 2026 10:09:55 +0300 Message-ID: <20260316071005.91624-8-mjt@tls.msk.ru> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260316071005.91624-1-mjt@tls.msk.ru> References: <20260316071005.91624-1-mjt@tls.msk.ru> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=212.248.84.144; envelope-from=mjt@tls.msk.ru; helo=isrv.corpit.ru X-Spam_score_int: -2 X-Spam_score: -0.3 X-Spam_bar: / X-Spam_report: (-0.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.819, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.903, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, WEIRD_PORT=0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @tls.msk.ru) X-ZM-MESSAGEID: 1773645253418154100 Content-Type: text/plain; charset="utf-8" From: Thomas Huth 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 Reviewed-by: Peter Xu Reviewed-by: Michael Tokarev Signed-off-by: Michael Tokarev --- docs/devel/migration/features.rst | 1 + .../migration/xbzrle.rst} | 106 +++++++++++------- 2 files changed, 65 insertions(+), 42 deletions(-) rename docs/{xbzrle.txt =3D> devel/migration/xbzrle.rst} (74%) diff --git a/docs/devel/migration/features.rst b/docs/devel/migration/featu= res.rst index 8f431d52f9..9aef79e7fa 100644 --- a/docs/devel/migration/features.rst +++ b/docs/devel/migration/features.rst @@ -15,3 +15,4 @@ Migration has plenty of features to support different use= cases. qpl-compression uadk-compression qatzip-compression + xbzrle diff --git a/docs/xbzrle.txt b/docs/devel/migration/xbzrle.rst similarity index 74% rename from docs/xbzrle.txt rename to docs/devel/migration/xbzrle.rst index bcb3f0c901..d4f4007261 100644 --- a/docs/xbzrle.txt +++ b/docs/devel/migration/xbzrle.rst @@ -20,7 +20,7 @@ A small cache size will result in high cache miss rate. Cache size can be changed before and during migration. =20 Format -=3D=3D=3D=3D=3D=3D=3D +------ =20 The compression format performs a XOR between the previous and current con= tent of the page, where zero represents an unchanged value. @@ -29,17 +29,19 @@ A zero run is represented by its length (in bytes). A non zero run is represented by its length (in bytes) and the new data. The run length is encoded using ULEB128 (http://en.wikipedia.org/wiki/LEB1= 28) =20 -There can be more than one valid encoding, the sender may send a longer en= coding -for the benefit of reducing computation cost. +There can be more than one valid encoding, the sender may send a longer +encoding for the benefit of reducing computation cost. =20 -page =3D zrun nzrun - | zrun nzrun page +:: =20 -zrun =3D length + page =3D zrun nzrun + | zrun nzrun page =20 -nzrun =3D length byte... + zrun =3D length =20 -length =3D uleb128 encoded integer + nzrun =3D length byte... + + length =3D uleb128 encoded integer =20 On the sender side XBZRLE is used as a compact delta encoding of page upda= tes, retrieving the old page content from the cache (default size of 64MB). The @@ -55,24 +57,34 @@ instead. XBZRLE has a sustained bandwidth of 2-2.5 GB/s for typical workloads makin= g it ideal for in-line, real-time encoding such as is needed for live-migration. =20 -Example +Example: + old buffer: -1001 zeros -05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 68 00 00 6b 00 6d -3074 zeros + +.. code:: batch + + 1001 zeros + 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 68 00 00 6b 00 6d + 3074 zeros =20 new buffer: -1001 zeros -01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 68 00 00 67 00 69 -3074 zeros + +.. code:: batch + + 1001 zeros + 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 68 00 00 67 00 69 + 3074 zeros =20 encoded buffer: =20 -encoded length 24 -e9 07 0f 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 03 01 67 01 01 69 +.. code:: batch + + encoded length 24 + e9 07 0f 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 03 01 67 01 01 69 =20 Cache update strategy -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +--------------------- + Keeping the hot pages in the cache is effective for decreasing cache misses. XBZRLE uses a counter as the age of each page. The counter will 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 tha= t are older than a threshold. =20 Usage -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -1. Verify the destination QEMU version is able to decode the new format. - {qemu} info migrate_capabilities - {qemu} xbzrle: off , ... +----- =20 -2. Activate xbzrle on both source and destination: - {qemu} migrate_set_capability xbzrle on +1. Verify the destination QEMU version is able to decode the new format:: + + (qemu) info migrate_capabilities + xbzrle: off + ... + +2. Activate xbzrle on both source and destination:: + + (qemu) migrate_set_capability xbzrle on =20 3. Set the XBZRLE cache size - the cache size is in MBytes and should be a -power of 2. The cache default value is 64MBytes. (on source only) - {qemu} migrate_set_parameter xbzrle-cache-size 256m + power of 2. The cache default value is 64 MBytes (on source only):: + + (qemu) migrate_set_parameter xbzrle-cache-size 256m =20 -4. Start outgoing migration - {qemu} migrate -d tcp:destination.host:4444 - {qemu} info migrate +4. Start outgoing migration:: + + (qemu) migrate -d tcp:destination.host:4444 + (qemu) info migrate capabilities: xbzrle: on Migration status: active transferred ram: A kbytes @@ -114,6 +132,7 @@ power of 2. The cache default value is 64MBytes. (on so= urce only) =20 xbzrle cache miss: the number of cache misses to date - high cache-miss ra= te indicates that the cache size is set too low. + xbzrle overflow: the number of overflows in the decoding which where the d= elta could not be compressed. This can happen if the changes in the pages are t= oo large or there are many short changes; for example, changing every second = byte @@ -123,16 +142,19 @@ Testing: Testing indicated that live migration with X= BZRLE was completed in 110 seconds, whereas without it would not be able to complete. =20 A simple synthetic memory r/w load generator: -.. include -.. include -.. int main() -.. { -.. char *buf =3D (char *) calloc(4096, 4096); -.. while (1) { -.. int i; -.. for (i =3D 0; i < 4096 * 4; i++) { -.. buf[i * 4096 / 4]++; -.. } -.. printf("."); -.. } -.. } + +.. code-block:: c + + #include + #include + int main() + { + char *buf =3D (char *) calloc(4096, 4096); + while (1) { + int i; + for (i =3D 0; i < 4096 * 4; i++) { + buf[i * 4096 / 4]++; + } + printf("."); + } + } --=20 2.47.3