From nobody Mon Feb 9 03:47:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; 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=1599151233; cv=none; d=zohomail.com; s=zohoarc; b=TBae8TbWCEy0ZKkdLo3bFjmS3FitiqechSo3cVOrfUDfCUQfN3cH2l+SILb00XXC+lPzM7uR3L1EFmvYVt4HwtqEOoIveVxu8JQOJ7VN4meAgXMfBQ5pLYBiluBVyuFkS8ki6jnC2w4MvPAiGnGrRm6o7QWDHLdBqWaXiAwZPOY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1599151233; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Chtlc5CuptQATyKkRPvXZLK+rkXSeQl8f2zRB9Ijl1E=; b=AAsQ/V8HrbaS9rjqfpxZY9VFR3rw1+sCUIfzeSqnK5vwzeklunPIO47NPsWJIHtI9R7GDhU7zmUBScY7hxXUYQ6iiogo9FYs5fSJ1HpChQo4UWt/s+GMjbOHJFsKRtVr4ONDrG4Uv16DeqOZA1N0+J4EbjMOj5ABiGw2kDzb7c8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; 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 1599151233827760.1503984175993; Thu, 3 Sep 2020 09:40:33 -0700 (PDT) Received: from localhost ([::1]:56566 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kDsHp-00062p-2m for importer@patchew.org; Thu, 03 Sep 2020 12:40:33 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:42670) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kDsFc-0002Kw-OE; Thu, 03 Sep 2020 12:38:16 -0400 Received: from fanzine.igalia.com ([178.60.130.6]:40627) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kDsFZ-0003v8-4O; Thu, 03 Sep 2020 12:38:16 -0400 Received: from [81.0.33.67] (helo=perseus.local) by fanzine.igalia.com with esmtpsa (Cipher TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim) id 1kDsFW-0002FF-Ob; Thu, 03 Sep 2020 18:38:10 +0200 Received: from berto by perseus.local with local (Exim 4.92) (envelope-from ) id 1kDsFJ-00082o-TM; Thu, 03 Sep 2020 18:37:57 +0200 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=igalia.com; s=20170329; h=Content-Transfer-Encoding:MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From; bh=Chtlc5CuptQATyKkRPvXZLK+rkXSeQl8f2zRB9Ijl1E=; b=VAE7/2IivqlWvSmDkU7gVZDMkdrTbWdMMTKZD13iJm9tMYBhtv0BdEQTF7sLEFs+Yj6uZ3xDNVJw71q8yaJW3Uxsv47/Eq0RuoRX8SnKpRNDIJtPbAWpYMpHimP4Y88YrPwhSjZBONBgrDETZDbaUZhe/paZ3OwdmhKHq9H5eOq4bQL7Pkmghb8b+iFqSVc/vIJfxlEq5eKpQ5nHt6DNwF03AH6k1hBSdFvvqQnlT9fgsAzKnaFR2SUKyaV95tKz0X4wDeyeJGph7sHYUyY9Qjm8Gb0Qr31gZdOHdJleDrHo4CKfw0vvOfsZjWwKMp/WIW0I1Uf0tJLxpXSe+5QteA==; From: Alberto Garcia To: qemu-devel@nongnu.org Subject: [PATCH v2 3/3] qcow2: Rewrite the documentation of qcow2_alloc_cluster_offset() Date: Thu, 3 Sep 2020 18:37:49 +0200 Message-Id: X-Mailer: git-send-email 2.20.1 In-Reply-To: References: 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=178.60.130.6; envelope-from=berto@igalia.com; helo=fanzine.igalia.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/03 12:38:03 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x (no timestamps) [generic] [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action 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: 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) Content-Type: text/plain; charset="utf-8" The current text corresponds to an earlier, simpler version of this function and it does not explain how it works now. Signed-off-by: Alberto Garcia --- block/qcow2-cluster.c | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/block/qcow2-cluster.c b/block/qcow2-cluster.c index 25e38daa78..f1ce6afcf5 100644 --- a/block/qcow2-cluster.c +++ b/block/qcow2-cluster.c @@ -1713,18 +1713,22 @@ out: } =20 /* - * alloc_cluster_offset + * For a given area on the virtual disk defined by @offset and @bytes, + * find the corresponding area on the qcow2 image, allocating new + * clusters (or subclusters) if necessary. The result can span a + * combination of allocated and previously unallocated clusters. * - * For a given offset on the virtual disk, find the cluster offset in qcow2 - * file. If the offset is not found, allocate a new cluster. + * On return, @host_offset is set to the beginning of the requested + * area. This area is guaranteed to be contiguous on the qcow2 file + * but it can be smaller than initially requested. In this case @bytes + * is updated with the actual size. * - * If the cluster was already allocated, m->nb_clusters is set to 0 and - * other fields in m are meaningless. - * - * If the cluster is newly allocated, m->nb_clusters is set to the number = of - * contiguous clusters that have been allocated. In this case, the other - * fields of m are valid and contain information about the first allocated - * cluster. + * If any clusters or subclusters were allocated then @m contains a + * list with the information of all the affected regions. Note that + * this can happen regardless of whether this function succeeds or + * not. The caller is responsible for updating the L2 metadata of the + * allocated clusters (on success) or freeing them (on failure), and + * for clearing the contents of @m afterwards in both cases. * * If the request conflicts with another write request in flight, the coro= utine * is queued and will be reentered when the dependency has completed. --=20 2.20.1