From nobody Fri Oct 24 09:59:47 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1519222732743974.4027089177965; Wed, 21 Feb 2018 06:18:52 -0800 (PST) Received: from localhost ([::1]:32866 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eoVER-0004Sk-LS for importer@patchew.org; Wed, 21 Feb 2018 09:18:51 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42453) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eoV59-000509-8T for qemu-devel@nongnu.org; Wed, 21 Feb 2018 09:09:16 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eoV56-0002B5-2d for qemu-devel@nongnu.org; Wed, 21 Feb 2018 09:09:15 -0500 Received: from fanzine.igalia.com ([91.117.99.155]:40113) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1eoV55-0002AI-N2; Wed, 21 Feb 2018 09:09:12 -0500 Received: from [194.100.51.2] (helo=perseus.local) by fanzine.igalia.com with esmtpsa (Cipher TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim) id 1eoV54-0007HA-58; Wed, 21 Feb 2018 15:09:10 +0100 Received: from berto by perseus.local with local (Exim 4.89) (envelope-from ) id 1eoV4l-0004Bs-UG; Wed, 21 Feb 2018 16:08:51 +0200 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=igalia.com; s=20170329; h=Message-Id:Date:Subject:Cc:To:From; bh=h+35eUvbBVJ/X0AhMIm8wswNKsni5ghpxqcRKCX9emk=; b=Ng9dIx1nB7Hjs6waZFfRa/1hOzLTLxsQNeSZxZeE6AngrYRFKIdh8S9CU2MHTmgl4IZIOmwuWCHW/+p1R32mCWOvwFGWNJry4yBBm8nff48RfJkF7YYCjKxO++8ueTxXgQpf8YzyvK4A/iO2d3Ux6XhKh4x8hXi5e6NZpthdYFpir+HnYoaYf+7dw71Mu+cDr1vZUW4xF7+Ncmvr6CamZ7r4J5OHu/2g59Du/tE9R6UDswLG4jeJ8lbzkKZjisKd3qZEtiQVchoZwy/wFopzlRcy9SiLKp1vQ7x97824gnqZqZ4mfOduPyK9Jrmb/VrYjLl7ebmxZvr+DNvCDC06rQ==; From: Alberto Garcia To: qemu-devel@nongnu.org Date: Wed, 21 Feb 2018 16:08:49 +0200 Message-Id: <20180221140849.16068-1-berto@igalia.com> X-Mailer: git-send-email 2.11.0 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x (no timestamps) [generic] [fuzzy] X-Received-From: 91.117.99.155 Subject: [Qemu-devel] [PATCH v3] specs/qcow2: Fix documentation of the compressed cluster descriptor 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: Kevin Wolf , Alberto Garcia , qemu-block@nongnu.org, Max Reitz Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZohoMail: RDKM_2 RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" This patch fixes several mistakes in the documentation of the compressed cluster descriptor: 1) the documentation claims that the cluster descriptor contains the number of sectors used to store the compressed data, but what it actually contains is the number of sectors *minus one* or, in other words, the number of additional sectors after the first one. 2) the width of the fields is incorrectly specified. The number of bits used by each field is x =3D 62 - (cluster_bits - 8) for the offset field y =3D (cluster_bits - 8) for the size field So the offset field's location is [0, x-1], not [0, x] as stated. 3) the size field does not contain the size of the compressed data, but rather the number of sectors where that data is stored. The compressed data starts at the exact point specified in the offset field and ends when there's enough data to produce a cluster of decompressed data. Both points can be in the middle of a sector, allowing several compressed clusters to be stored next to one another, sharing sectors if necessary. Signed-off-by: Alberto Garcia Reviewed-by: Eric Blake --- v3: Fix the specification of the width of the fields, and update the explanation of how the compressed data is stored [Eric]. v2: I realized that the documentation is not completely clear about the exact location and size of the compressed data, so I updated the patch to clarify this. --- docs/interop/qcow2.txt | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/interop/qcow2.txt b/docs/interop/qcow2.txt index d7fdb1fee3..feb711fb6a 100644 --- a/docs/interop/qcow2.txt +++ b/docs/interop/qcow2.txt @@ -426,10 +426,20 @@ Standard Cluster Descriptor: =20 Compressed Clusters Descriptor (x =3D 62 - (cluster_bits - 8)): =20 - Bit 0 - x: Host cluster offset. This is usually _not_ aligned to a - cluster boundary! + Bit 0 - x-1: Host cluster offset. This is usually _not_ aligned to a + cluster or sector boundary! =20 - x+1 - 61: Compressed size of the images in sectors of 512 bytes + x - 61: Number of additional 512-byte sectors used for the + compressed data, beyond the sector containing the offs= et + in the previous field. Some of these sectors may reside + in the next contiguous host cluster. + + Note that the compressed data does not necessarily occ= upy + all of the bytes in the final sector; rather, decompre= ssion + stops when it has produced a cluster of data. + + Another compressed cluster may map to the tail of the = final + sector used by this compressed cluster. =20 If a cluster is unallocated, read requests shall read the data from the ba= cking file (except if bit 0 in the Standard Cluster Descriptor is set). If there= is --=20 2.11.0