From nobody Tue May 14 05:01:35 2024 Delivered-To: importer@patchew.org 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; Authentication-Results: mx.zohomail.com; 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; dmarc=fail(p=none dis=none) header.from=virtuozzo.com ARC-Seal: i=1; a=rsa-sha256; t=1576498757; cv=none; d=zohomail.com; s=zohoarc; b=hwuSaBECOGrVr4AILkUfBjONsgI29c7V7tvc6Zv8JsSkZbtD+K6euxzQga40vo/b77p4Hh5tw/gVNiN6a1sgeNYs+qdvHYXOtpkEqR5OMSd/pRpfLc0Z16v8O9LeWiuZkeDWOBjsJEVAzW23leujAJccwGB90DUkgkZ94legOdU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1576498757; h=Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:Message-ID:References:Sender:Subject:To; bh=sqfD9mzGO45vNO6dKhE1BIVTuV4ZbzaoQKSGYf+lM2g=; b=PGjuZgGTAeQgO8UlvBtE3zHdiTRLgYj0A/kHXNC2qOabJWC5LzpShMCxrgVix0T2JraWEnse+v44Nt+xsCfLZpRJOTUx7NevBnu42guWqktfrkJ5diC8RisQ+67CKinhTyaIb4VSOcIexwUY/G8T0qPnqwbfZX7gX0ezgGgiu7o= ARC-Authentication-Results: i=1; mx.zohomail.com; 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; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1576498757392208.85087881174456; Mon, 16 Dec 2019 04:19:17 -0800 (PST) Received: from localhost ([::1]:52601 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1igpLH-00023a-Ic for importer@patchew.org; Mon, 16 Dec 2019 07:19:15 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:49371) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1igpJp-0000Wj-ID for qemu-devel@nongnu.org; Mon, 16 Dec 2019 07:17:46 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1igpJo-0001rx-3X for qemu-devel@nongnu.org; Mon, 16 Dec 2019 07:17:45 -0500 Received: from relay.sw.ru ([185.231.240.75]:33572) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1igpJn-0001rB-Sb; Mon, 16 Dec 2019 07:17:44 -0500 Received: from vovaso.qa.sw.ru ([10.94.3.0] helo=kvm.qa.sw.ru) by relay.sw.ru with esmtp (Exim 4.92.3) (envelope-from ) id 1igpJe-00033D-4D; Mon, 16 Dec 2019 15:17:34 +0300 From: Vladimir Sementsov-Ogievskiy To: qemu-devel@nongnu.org Subject: [PATCH v9 1/2] docs: improve qcow2 spec about extending image header Date: Mon, 16 Dec 2019 15:17:32 +0300 Message-Id: <20191216121733.63562-2-vsementsov@virtuozzo.com> X-Mailer: git-send-email 2.18.0 In-Reply-To: <20191216121733.63562-1-vsementsov@virtuozzo.com> References: <20191216121733.63562-1-vsementsov@virtuozzo.com> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [fuzzy] X-Received-From: 185.231.240.75 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: kwolf@redhat.com, vsementsov@virtuozzo.com, qemu-block@nongnu.org, armbru@redhat.com, mreitz@redhat.com, dplotnikov@virtuozzo.com, den@openvz.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Make it more obvious how to add new fields to the version 3 header and how to interpret them. The specification is adjusted so for new defined optional fields: 1. Software may support some of these optional fields and ignore the others, which means that features may be backported to downstream Qemu independently. 2. If we want to add incompatible field (or a field, for which some its values would be incompatible), it must be accompanied by incompatible feature bit. Also the concept of "default is zero" is clarified, as it's strange to say that the value of the field is assumed to be zero for the software version which don't know about the field at all and don't know how to treat it be it zero or not. Signed-off-by: Vladimir Sementsov-Ogievskiy --- docs/interop/qcow2.txt | 39 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/docs/interop/qcow2.txt b/docs/interop/qcow2.txt index af5711e533..d92c827763 100644 --- a/docs/interop/qcow2.txt +++ b/docs/interop/qcow2.txt @@ -79,9 +79,9 @@ The first cluster of a qcow2 image contains the file head= er: Offset into the image file at which the snapshot table starts. Must be aligned to a cluster boundary. =20 -If the version is 3 or higher, the header has the following additional fie= lds. -For version 2, the values are assumed to be zero, unless specified otherwi= se -in the description of a field. +For version 2, the header is exactly 72 bytes in length, and finishes here. +For version 3 or higher, the header length is at least 104 bytes, including +the next fields through header_length. =20 72 - 79: incompatible_features Bitmask of incompatible features. An implementation mu= st @@ -164,6 +164,39 @@ in the description of a field. 100 - 103: header_length Length of the header structure in bytes. For version 2 images, the length is always assumed to be 72 bytes. + For version 3 it's at least 104 bytes and must be a mu= ltiply + of 8. + +Additional fields (version 3 and higher) + +In general, these fields are optional and may be safely ignored by the sof= tware, +as well as filled by zeros (which is equal to field absence), if software = needs +to set field B, but don't want to care about field A, which precedes B. Mo= re +formally, additional fields have the following compatibility rules: + +1. If the value of the additional field must not be ignored for correct +handling of the file, it will be accompanied by a corresponding incompatib= le +feature bit. + +2. If there are no unrecognized incompatible feature bits set, an unknown +additional field may be safely ignored other than preserving its value when +rewriting the image header. + +3. An explicit value of 0 will have the same behavior as when the field is= not +present*, if not altered by specific incompatible bit. + +*. Field is not present when header_length is less or equal to field's off= set. +Also, all additional fields are not present for version 2. + + < ... No additional fields in the header currently ... > + +Header padding + +@header_length must be a multiply of 8, which means that if last additiona= l field +end is not aligned, some padding is needed. This padding must be zeroed, s= o that, +if some existing (or future) additional field will fall into the padding, = it +will be interpreted accordingly to point [3.] of the previous paragraph, i= .e. +in same manner as when this field is not present. =20 Directly after the image header, optional sections called header extension= s can be stored. Each extension has a structure like the following: --=20 2.18.0 From nobody Tue May 14 05:01:35 2024 Delivered-To: importer@patchew.org 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; Authentication-Results: mx.zohomail.com; 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; dmarc=fail(p=none dis=none) header.from=virtuozzo.com ARC-Seal: i=1; a=rsa-sha256; t=1576498759; cv=none; d=zohomail.com; s=zohoarc; b=D2G/+UJHjwfBbHMI7m+wv8k7JwoGTV5NucGCl0w7faSqNVj8TPTGGjWJOgHsCrK51tAlS+8KsG4N1nhuo4VXuouLPWzfU/F8PYqh3Nec1tbKM4VzrLs5KJ6NoE22YIctPl0ltSOO7pvi9GvefDnnGm2pou9DJqARMPUZN3yx9Ms= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1576498759; h=Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:Message-ID:References:Sender:Subject:To; bh=sQAWK0brmVWLa3B/U1oSId2nhxKOYgvP4XOD7mSUii8=; b=fnZwWGWD/I+qIyS193VgrT/H/zSfAUJ2yt2FiGjHmCZajPnk1XIjX1Y3CPxcqLmiTaZUnU4nMIhMmv9Idma/fzQbN4f8gtO2wxVC65hg3v9+eyGcgBbaeYH+tUf2tLtCN93o4+3xtNx7k8pP5p6saR/iWGep+MFdJIrxmpNxrCg= ARC-Authentication-Results: i=1; mx.zohomail.com; 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; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 157649875902465.72408289231191; Mon, 16 Dec 2019 04:19:19 -0800 (PST) Received: from localhost ([::1]:52596 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1igpLJ-00020k-Fv for importer@patchew.org; Mon, 16 Dec 2019 07:19:17 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:49370) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1igpJp-0000Wi-Hb for qemu-devel@nongnu.org; Mon, 16 Dec 2019 07:17:46 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1igpJn-0001rp-TL for qemu-devel@nongnu.org; Mon, 16 Dec 2019 07:17:45 -0500 Received: from relay.sw.ru ([185.231.240.75]:33562) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1igpJn-0001r9-M5; Mon, 16 Dec 2019 07:17:43 -0500 Received: from vovaso.qa.sw.ru ([10.94.3.0] helo=kvm.qa.sw.ru) by relay.sw.ru with esmtp (Exim 4.92.3) (envelope-from ) id 1igpJe-00033D-Gr; Mon, 16 Dec 2019 15:17:34 +0300 From: Vladimir Sementsov-Ogievskiy To: qemu-devel@nongnu.org Subject: [PATCH v9 2/2] docs: qcow2: introduce compression type feature Date: Mon, 16 Dec 2019 15:17:33 +0300 Message-Id: <20191216121733.63562-3-vsementsov@virtuozzo.com> X-Mailer: git-send-email 2.18.0 In-Reply-To: <20191216121733.63562-1-vsementsov@virtuozzo.com> References: <20191216121733.63562-1-vsementsov@virtuozzo.com> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [fuzzy] X-Received-From: 185.231.240.75 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: kwolf@redhat.com, vsementsov@virtuozzo.com, qemu-block@nongnu.org, armbru@redhat.com, mreitz@redhat.com, dplotnikov@virtuozzo.com, den@openvz.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" The patch add new additional field to qcow2 header: compression_type, which specifies compression type. If field is absent or zero, default compression type is set: ZLIB, which corresponds to current behavior. New compression type (ZSTD) is to be added in further commit. Suggested-by: Denis Plotnikov Signed-off-by: Vladimir Sementsov-Ogievskiy --- docs/interop/qcow2.txt | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/interop/qcow2.txt b/docs/interop/qcow2.txt index d92c827763..77146b5169 100644 --- a/docs/interop/qcow2.txt +++ b/docs/interop/qcow2.txt @@ -109,6 +109,11 @@ the next fields through header_length. An External Data File Name header extensio= n may be present if this bit is set. =20 + Bit 3: Compression type bit. If this bit is set, + non-default compression is used for compre= ssed + clusters. compression_type field must be + present and not zero. + Bits 3-63: Reserved (set to 0) =20 80 - 87: compatible_features @@ -188,7 +193,16 @@ present*, if not altered by specific incompatible bit. *. Field is not present when header_length is less or equal to field's off= set. Also, all additional fields are not present for version 2. =20 - < ... No additional fields in the header currently ... > + 104: compression_type + Defines the compression method used for compressed clu= sters. + A single compression type is applied to all compressed= image + clusters. + If incompatible compression type bit is set: the field= must + be present and non-zero (which means non-zlib compress= ion type) + If incompatible compression type bit is unset: the fie= ld + may not exist or it must be zero (which means zlib). + Available compression type values: + 0: zlib =20 Header padding =20 --=20 2.18.0