From nobody Tue Apr 15 11:36:08 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.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; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1552050486483609.8482599406707; Fri, 8 Mar 2019 05:08:06 -0800 (PST) Received: from localhost ([127.0.0.1]:42754 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h2FE7-0006Uv-6x for importer@patchew.org; Fri, 08 Mar 2019 08:07:51 -0500 Received: from eggs.gnu.org ([209.51.188.92]:59463) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h2F5d-0008JF-Qs for qemu-devel@nongnu.org; Fri, 08 Mar 2019 07:59:06 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h2F5Z-0006PC-SY for qemu-devel@nongnu.org; Fri, 08 Mar 2019 07:59:02 -0500 Received: from mx1.redhat.com ([209.132.183.28]:43922) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1h2F5X-0005tO-0V; Fri, 08 Mar 2019 07:58:59 -0500 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 2A84180F9A; Fri, 8 Mar 2019 12:58:56 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-117-27.ams2.redhat.com [10.36.117.27]) by smtp.corp.redhat.com (Postfix) with ESMTP id E85665D786; Fri, 8 Mar 2019 12:58:53 +0000 (UTC) From: Kevin Wolf To: qemu-block@nongnu.org Date: Fri, 8 Mar 2019 13:58:03 +0100 Message-Id: <20190308125823.32535-14-kwolf@redhat.com> In-Reply-To: <20190308125823.32535-1-kwolf@redhat.com> References: <20190308125823.32535-1-kwolf@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.27]); Fri, 08 Mar 2019 12:58:56 +0000 (UTC) Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PULL 13/33] qcow2: Extend spec for external data files X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: kwolf@redhat.com, peter.maydell@linaro.org, qemu-devel@nongnu.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Type: text/plain; charset="utf-8" This adds external data file to the qcow2 spec as a new incompatible feature. Signed-off-by: Kevin Wolf --- docs/interop/qcow2.txt | 42 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/docs/interop/qcow2.txt b/docs/interop/qcow2.txt index fb5cb47245..bfb97cfde3 100644 --- a/docs/interop/qcow2.txt +++ b/docs/interop/qcow2.txt @@ -97,7 +97,19 @@ in the description of a field. be written to (unless for regaining consistency). =20 - Bits 2-63: Reserved (set to 0) + Bit 2: External data file bit. If this bit is se= t, an + external data file is used. Guest clusters= are + then stored in the external data file. For= such + images, clusters in the external data file= are + not refcounted. The offset field in the + Standard Cluster Descriptor must match the + guest offset and neither compressed cluste= rs + nor internal snapshots are supported. + + An External Data File Name header extensio= n may + be present if this bit is set. + + Bits 3-63: Reserved (set to 0) =20 80 - 87: compatible_features Bitmask of compatible features. An implementation can @@ -126,7 +138,21 @@ in the description of a field. bit is unset, the bitmaps extension data m= ust be considered inconsistent. =20 - Bits 1-63: Reserved (set to 0) + Bit 1: If this bit is set, the external data file= can + be read as a consistent standalone raw ima= ge + without looking at the qcow2 metadata. + + Setting this bit has a performance impact = for + some operations on the image (e.g. writing + zeros requires writing to the data file in= stead + of only setting the zero flag in the L2 ta= ble + entry) and conflicts with backing files. + + This bit may only be set if the External D= ata + File bit (incompatible feature bit 1) is a= lso + set. + + Bits 2-63: Reserved (set to 0) =20 96 - 99: refcount_order Describes the width of a reference count block entry (= width @@ -148,6 +174,7 @@ be stored. Each extension has a structure like the foll= owing: 0x6803f857 - Feature name table 0x23852875 - Bitmaps extension 0x0537be77 - Full disk encryption header pointer + 0x44415441 - External data file name other - Unknown header extension, can be safe= ly ignored =20 @@ -437,6 +464,11 @@ L2 table entry: This information is only accurate in L2 tables that are reachable from the active L1 table. =20 + With external data files, all guest clusters have an + implicit refcount of 1 (because of the fixed host =3D = guest + mapping for guest cluster offsets), so this bit should= be 1 + for all allocated clusters. + Standard Cluster Descriptor: =20 Bit 0: If set to 1, the cluster reads as all zeros. The host @@ -450,8 +482,10 @@ Standard Cluster Descriptor: 1 - 8: Reserved (set to 0) =20 9 - 55: Bits 9-55 of host cluster offset. Must be aligned to a - cluster boundary. If the offset is 0, the cluster is - unallocated. + cluster boundary. If the offset is 0 and bit 63 is cle= ar, + the cluster is unallocated. The offset may only be 0 w= ith + bit 63 set (indicating a host cluster offset of 0) whe= n an + external data file is used. =20 56 - 61: Reserved (set to 0) =20 --=20 2.20.1