From patchwork Thu Sep 3 16:37:49 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alberto Garcia X-Patchwork-Id: 1356756 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=igalia.com Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=igalia.com header.i=@igalia.com header.a=rsa-sha256 header.s=20170329 header.b=VAE7/2Ii; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4Bj63W4vlCz9sPB for ; Fri, 4 Sep 2020 02:39:51 +1000 (AEST) Received: from localhost ([::1]:53440 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kDsH7-0004nH-KI for incoming@patchwork.ozlabs.org; Thu, 03 Sep 2020 12:39:49 -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 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==; 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 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 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" 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: } /* - * 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 coroutine * is queued and will be reentered when the dependency has completed.