From patchwork Tue Jun 19 01:41:44 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Roth X-Patchwork-Id: 10472881 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 86AD060244 for ; Tue, 19 Jun 2018 02:18:46 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 7116B28988 for ; Tue, 19 Jun 2018 02:18:46 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 65DF928AD0; Tue, 19 Jun 2018 02:18:46 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.8 required=2.0 tests=BAYES_00,DKIM_SIGNED, MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI, T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id E46A528988 for ; Tue, 19 Jun 2018 02:18:44 +0000 (UTC) Received: from localhost ([::1]:38567 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fV6EG-0001k1-3E for patchwork-qemu-devel@patchwork.kernel.org; Mon, 18 Jun 2018 22:18:44 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:45160) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fV5hL-0000rz-0W for qemu-devel@nongnu.org; Mon, 18 Jun 2018 21:44:44 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fV5hJ-00081s-VJ for qemu-devel@nongnu.org; Mon, 18 Jun 2018 21:44:43 -0400 Received: from mail-oi0-x243.google.com ([2607:f8b0:4003:c06::243]:43741) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fV5hJ-00080n-Q3; Mon, 18 Jun 2018 21:44:41 -0400 Received: by mail-oi0-x243.google.com with SMTP id t133-v6so16694477oif.10; Mon, 18 Jun 2018 18:44:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references; bh=moPj3wj24eIc6ejZOSJOqyGu/mGmW+arqcOvgKc3ydI=; b=H4h44Y0EmfYcxrlI1woyUsmtgGZM5LMEOFqlKv6fLj0U0wG7JPxNPYxCIShmbxE8hD +WE1McZE+X0+6D7oCRNpEY35eoDhyjzVIkHboigzx2TY2+thCYMo2QLJ/r22nbqWkOG8 cFebG/fGk+Pl88AhnMOWG6Dzvo2FFBEzaZMnnw6B4qSXc8GWc46aBT9haGrpbCCWy2Oq BHM2dHOGzhiCkMpPF82CFqkNATt24BsZntb3x2fc4FRRuXT9e7iqlvCZyaaNS2UCkiq3 +uJLWtOhCSw3jMunS+ojiqFvDDFru4NZPwVMzFMy2H+Rzj9J0Kd4SmB3+NtkTinYgABz DgAg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references; bh=moPj3wj24eIc6ejZOSJOqyGu/mGmW+arqcOvgKc3ydI=; b=PALTyOrf4f9O2hp7h2ye+hBgfIaW4hSUsF9/WWKptyOriPfALsBRDa0KLZ2vaM53f/ /kY9i7yEXSnQOzEamJjbT+oHPz0rkUkFT7ftBECJq2qsSsEGVqhmORXC5DVw0/W4p/gr wic2Rjz/ZgiPQ4hcVgNA/qRlGbSZE0rexap02z+TlP2xwb7qrSBYwSTXMM57PQvUrszj buHUFj02iTMElfvv9r7FcrN+r9X0pIL6QXPmDpc0TObGmTT5shuWeI3TGvwsb8ZwXvN8 yZ8HjjIaYDuBNSmC3IcNU4roi/gN5SIjBuxYGMWdi5bG5A9phL+Qeztmyaf/VuZNI2r2 2h4w== X-Gm-Message-State: APt69E1CkHb1tI4VvQGW+CGkS3I16H3DMxZ65fB3/Hzq2bvH1xLZz7ro xsLT8wwuTtr0F8WYR723Nhy4+1Tm X-Google-Smtp-Source: ADUXVKISL/B92goOs8m+86Rj+PlT4s/KZz+YpqvAgcg+WbkURoRuVE0BdPGRmRvygMxpkMBCwEXNwQ== X-Received: by 2002:aca:f484:: with SMTP id s126-v6mr8628884oih.269.1529372680566; Mon, 18 Jun 2018 18:44:40 -0700 (PDT) Received: from localhost ([2600:1700:70:e488:b0ee:9bda:ee6f:91be]) by smtp.gmail.com with ESMTPSA id t15-v6sm8686180ott.6.2018.06.18.18.44.39 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Mon, 18 Jun 2018 18:44:39 -0700 (PDT) From: Michael Roth To: qemu-devel@nongnu.org Date: Mon, 18 Jun 2018 20:41:44 -0500 Message-Id: <20180619014319.28272-19-mdroth@linux.vnet.ibm.com> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20180619014319.28272-1-mdroth@linux.vnet.ibm.com> References: <20180619014319.28272-1-mdroth@linux.vnet.ibm.com> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:4003:c06::243 Subject: [Qemu-devel] [PATCH 018/113] 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-stable@nongnu.org Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP From: Alberto Garcia 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 = 62 - (cluster_bits - 8) for the offset field y = (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. Cc: qemu-stable@nongnu.org Signed-off-by: Alberto Garcia Reviewed-by: Eric Blake Signed-off-by: Kevin Wolf (cherry picked from commit 156b46ded3853dfc6b34c5afae019ff61798491b) Signed-off-by: Michael Roth --- 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: Compressed Clusters Descriptor (x = 62 - (cluster_bits - 8)): - 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! - 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 offset + in the previous field. Some of these sectors may reside + in the next contiguous host cluster. + + Note that the compressed data does not necessarily occupy + all of the bytes in the final sector; rather, decompression + 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. If a cluster is unallocated, read requests shall read the data from the backing file (except if bit 0 in the Standard Cluster Descriptor is set). If there is