From 2b60c5b996e71eb5186bed7727982a471d5d2558 Mon Sep 17 00:00:00 2001 From: Alberto Garcia Date: Thu, 3 Sep 2020 18:37:49 +0200 Subject: qcow2: Rewrite the documentation of qcow2_alloc_cluster_offset() 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 Message-Id: Signed-off-by: Max Reitz --- block/qcow2-cluster.c | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) (limited to 'block/qcow2-cluster.c') diff --git a/block/qcow2-cluster.c b/block/qcow2-cluster.c index f65ccc5840..ce1260e746 100644 --- a/block/qcow2-cluster.c +++ b/block/qcow2-cluster.c @@ -1714,18 +1714,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. -- cgit v1.2.3