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
57 -------------------
60 snapshots. The data is stored in a two-level structure similar to the
71    qemu-img create -f qcow2 -o refcount_bits=8 hd.qcow2 4G
78 ------------------------------
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
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
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"
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
189  - Try different entry sizes to see which one gives faster performance
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"
206 -------------------------
210 The parameter "cache-clean-interval" defines an interval (in seconds),
217    -drive file=hd.qcow2,cache-clean-interval=900
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.