aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlberto Garcia <berto@igalia.com>2020-09-03 18:37:49 +0200
committerMax Reitz <mreitz@redhat.com>2020-09-15 11:05:13 +0200
commit2b60c5b996e71eb5186bed7727982a471d5d2558 (patch)
tree678161ec21a8d5f39d5273a5b08dd119fa8f4c94
parentf7bd5bba1b8ce7200600bacee024bce525083f60 (diff)
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 <berto@igalia.com> Message-Id: <bb5bd06f07c5a05b0818611de0d06ec5b66c8df3.1599150873.git.berto@igalia.com> Signed-off-by: Max Reitz <mreitz@redhat.com>
-rw-r--r--block/qcow2-cluster.c24
1 files changed, 14 insertions, 10 deletions
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.