qemu/docs/qcow2-cache.txt

3 Copyright (C) 2015, 2018-2020 Igalia, S.L.
7 later. See the COPYING file in the top-level directory.
10 ------------
18 Please refer to the docs/interop/qcow2.rst file for an in-depth
23 --------
30 The 'qemu-img create' command supports specifying the size using the
33    qemu-img create -f qcow2 -o cluster_size=128K hd.qcow2 4G
37 -------------
38 The qcow2 format uses a two-level structure to map the virtual disk as
45 There can be many L2 tables, depending on how much space has been
57 -------------------
60 snapshots. The data is stored in a two-level structure similar to the
64 cluster in size and the number is also variable and dependent on the
71    qemu-img create -f qcow2 -o refcount_bits=8 hd.qcow2 4G
78 ------------------------------
88 With the default values for cluster_size (64KB) and refcount_bits
94 So in order to cover n GB of disk space with the default values we
101 image size (given that the default cluster size is used):
105 The refcount cache is 4 times the cluster size by default. With the default
113 --------------------------------
114 Cache sizes can be configured using the -drive option in the
115 command-line, or the 'blockdev-add' QMP command.
119 "l2-cache-size":         maximum size of the L2 table cache
120 "refcount-cache-size":   maximum size of the refcount block cache
121 "cache-size":            maximum size of both caches combined
125  - Both caches must have a size that is a multiple of the cluster size
128  - The maximum L2 cache size is 32 MB by default on Linux platforms (enough
129    for full coverage of 256 GB images, with the default cluster size). This
130    value can be modified using the "l2-cache-size" option. QEMU will not use
133    On non-Linux platforms the maximal value is smaller by default (8 MB) and
134    this difference stems from the fact that on Linux the cache can be cleared
135    periodically if needed, using the "cache-clean-interval" option (see below).
138  - The default (and minimum) refcount cache size is 4 clusters.
140  - If only "cache-size" is specified then QEMU will assign as much
144  - At most two of "l2-cache-size", "refcount-cache-size", and "cache-size"
154 Before QEMU 2.12 the refcount cache had a default size of 1/4 of the
160 ---------------------------
171 "l2-cache-entry-size" parameter:
173    -drive file=hd.qcow2,l2-cache-size=2097152,l2-cache-entry-size=4096
175 Since QEMU 4.0 the value of l2-cache-entry-size defaults to 4KB (or
180  - The L2 cache entry size has the same restrictions as the cluster
183  - Smaller entry sizes generally improve the cache efficiency and make
187    should test it first and stay with the default size if unsure.
189  - Try different entry sizes to see which one gives faster performance
191    good default (usually 4096 bytes in the case of ext4, hence the
192    default).
194  - Only the L2 cache can be configured this way. The refcount cache
197  - If the L2 cache is big enough to hold all of the image's L2 tables
200    this is necessary and you can omit the "l2-cache-entry-size"
202    equal to the cluster size by default.
206 -------------------------
210 The parameter "cache-clean-interval" defines an interval (in seconds),
217    -drive file=hd.qcow2,cache-clean-interval=900
219 If unset, the default value for this parameter is 600 on platforms which
220 support this functionality, and is 0 (disabled) on other platforms.
222 This functionality currently relies on the MADV_DONTNEED argument for
223 madvise() to actually free the memory. This is a Linux-specific feature,
224 so cache-clean-interval is not supported on other systems.
228 -------------------
230 64-bit L2 entries.