OpenE2K/qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

qcow2: Document the Extended L2 Entries feature

Browse Source 
Subcluster allocation in qcow2 is implemented by extending the
existing L2 table entries and adding additional information to
indicate the allocation status of each subcluster.

This patch documents the changes to the qcow2 format and how they
affect the calculation of the L2 cache size.

Signed-off-by: Alberto Garcia <berto@igalia.com>
Reviewed-by: Max Reitz <mreitz@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <5199f2e1c717bcaa58b48142c9062b803145ff7f.1594396418.git.berto@igalia.com>
Signed-off-by: Max Reitz <mreitz@redhat.com>
This commit is contained in:
Alberto Garcia 2020-07-10 18:12:49 +02:00 committed by Max Reitz
parent 12c6aebedf
commit 30afc12085
2 changed files with 83 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/interop/qcow2.txt
View File

@ -42,6 +42,9 @@ The first cluster of a qcow2 image contains the file header:
as the maximum cluster size and won't be able to open images
with larger cluster sizes.
Note: if the image has Extended L2 Entries then cluster_bits
must be at least 14 (i.e. 16384 byte clusters).
24 - 31: size
Virtual disk size in bytes.
@ -117,7 +120,12 @@ the next fields through header_length.
clusters. The compression_type field must be
present and not zero.
Bits 4-63: Reserved (set to 0)
Bit 4: Extended L2 Entries. If this bit is set then
L2 table entries use an extended format that
allows subcluster-based allocation. See the
Extended L2 Entries section for more details.
Bits 5-63: Reserved (set to 0)
80 - 87: compatible_features
Bitmask of compatible features. An implementation can
@ -498,7 +506,7 @@ cannot be relaxed without an incompatible layout change).
Given an offset into the virtual disk, the offset into the image file can be
obtained as follows:
l2_entries = (cluster_size / sizeof(uint64_t))
l2_entries = (cluster_size / sizeof(uint64_t)) [*]
l2_index = (offset / cluster_size) % l2_entries
l1_index = (offset / cluster_size) / l2_entries
@ -508,6 +516,8 @@ obtained as follows:
return cluster_offset + (offset % cluster_size)
[*] this changes if Extended L2 Entries are enabled, see next section
L1 table entry:
Bit 0 - 8: Reserved (set to 0)
@ -548,7 +558,8 @@ Standard Cluster Descriptor:
nor is data read from the backing file if the cluster is
unallocated.
With version 2, this is always 0.
With version 2 or with extended L2 entries (see the next
section), this is always 0.
1 - 8: Reserved (set to 0)
@ -585,6 +596,57 @@ file (except if bit 0 in the Standard Cluster Descriptor is set). If there is
no backing file or the backing file is smaller than the image, they shall read
zeros for all parts that are not covered by the backing file.
== Extended L2 Entries ==
An image uses Extended L2 Entries if bit 4 is set on the incompatible_features
field of the header.
In these images standard data clusters are divided into 32 subclusters of the
same size. They are contiguous and start from the beginning of the cluster.
Subclusters can be allocated independently and the L2 entry contains information
indicating the status of each one of them. Compressed data clusters don't have
subclusters so they are treated the same as in images without this feature.
The size of an extended L2 entry is 128 bits so the number of entries per table
is calculated using this formula:
l2_entries = (cluster_size / (2 * sizeof(uint64_t)))
The first 64 bits have the same format as the standard L2 table entry described
in the previous section, with the exception of bit 0 of the standard cluster
descriptor.
The last 64 bits contain a subcluster allocation bitmap with this format:
Subcluster Allocation Bitmap (for standard clusters):
Bit 0 - 31: Allocation status (one bit per subcluster)
1: the subcluster is allocated. In this case the
host cluster offset field must contain a valid
offset.
0: the subcluster is not allocated. In this case
read requests shall go to the backing file or
return zeros if there is no backing file data.
Bits are assigned starting from the least significant
one (i.e. bit x is used for subcluster x).
32 - 63 Subcluster reads as zeros (one bit per subcluster)
1: the subcluster reads as zeros. In this case the
allocation status bit must be unset. The host
cluster offset field may or may not be set.
0: no effect.
Bits are assigned starting from the least significant
one (i.e. bit x is used for subcluster x - 32).
Subcluster Allocation Bitmap (for compressed clusters):
Bit 0 - 63: Reserved (set to 0)
Compressed clusters don't have subclusters,
so this field is not used.
== Snapshots ==

19
docs/qcow2-cache.txt
View File

@ -1,6 +1,6 @@
qcow2 L2/refcount cache configuration
=====================================
Copyright (C) 2015, 2018 Igalia, S.L.
Copyright (C) 2015, 2018-2020 Igalia, S.L.
Author: Alberto Garcia <berto@igalia.com>
This work is licensed under the terms of the GNU GPL, version 2 or
@ -222,3 +222,20 @@ support this functionality, and is 0 (disabled) on other platforms.
This functionality currently relies on the MADV_DONTNEED argument for
madvise() to actually free the memory. This is a Linux-specific feature,
so cache-clean-interval is not supported on other systems.
Extended L2 Entries
-------------------
All numbers shown in this document are valid for qcow2 images with normal
64-bit L2 entries.
Images with extended L2 entries need twice as much L2 metadata, so the L2
cache size must be twice as large for the same disk space.
disk_size = l2_cache_size * cluster_size / 16
i.e.
l2_cache_size = disk_size * 16 / cluster_size
Refcount blocks are not affected by this.