qemu/docs/qcow2-cache.txt

1 qcow2 L2/refcount cache configuration
3 Copyright (C) 2015, 2018-2020 Igalia, S.L.
7 later. See the COPYING file in the top-level directory.
10 ------------
12 performance significantly. However, setting the right cache sizes is
15 This document attempts to give an overview of the L2 and refcount
18 Please refer to the docs/interop/qcow2.txt 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
36 The L2 tables
37 -------------
38 The qcow2 format uses a two-level structure to map the virtual disk as
40 called the L1 and L2 tables.
45 There can be many L2 tables, depending on how much space has been
48 corresponding L2 table to find out where that data is located. Since
50 an L2 cache in memory to speed up disk access.
52 The size of the L2 cache can be configured, and setting the right
57 -------------------
60 snapshots. The data is stored in a two-level structure similar to the
61 L1/L2 tables described above.
71    qemu-img create -f qcow2 -o refcount_bits=8 hd.qcow2 4G
73 QEMU keeps a refcount cache to speed up I/O much like the
74 aforementioned L2 cache, and its size can also be configured.
77 Choosing the right cache sizes
78 ------------------------------
79 In order to choose the cache sizes we need to know how they relate to
82 The part of the virtual disk that can be mapped by the L2 and refcount
100 For example, 1MB of L2 cache is needed to cover every 8 GB of the virtual
105 The refcount cache is 4 times the cluster size by default. With the default
112 How to configure the cache sizes
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
126    (or the cache entry size: see "Using smaller cache sizes" below).
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
131    more memory than needed to hold all of the image's L2 tables, regardless
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).
136    The minimal L2 cache size is 2 clusters (or 2 cache entries, 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
141    memory as possible to the L2 cache before increasing the refcount
142    cache size.
144  - At most two of "l2-cache-size", "refcount-cache-size", and "cache-size"
147 Unlike L2 tables, refcount blocks are not used during normal I/O but
150 refcount cache size won't have any measurable effect in performance
152 to think about increasing the cache size if you use them heavily).
154 Before QEMU 2.12 the refcount cache had a default size of 1/4 of the
155 L2 cache size. This resulted in unnecessarily large caches, so now the
156 refcount cache is as small as possible unless overridden by the user.
159 Using smaller cache entries
160 ---------------------------
161 The qcow2 L2 cache can store complete tables. This means that if QEMU
162 needs an entry from an L2 table then the whole table is read from disk
163 and is kept in the cache. If the cache is full then a complete table
167 more disk I/O and wastes more cache memory.
169 Since QEMU 2.12 you can change the size of the L2 cache entry and make
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
198    (as explained in the "Choosing the right cache sizes" and "How to
199    configure the cache sizes" sections in this document) then none of
200    this is necessary and you can omit the "l2-cache-entry-size"
206 -------------------------
207 It is possible to clean unused cache entries in order to reduce the
210 The parameter "cache-clean-interval" defines an interval (in seconds),
211 after which all the cache entries that haven't been accessed during the
215 The following example removes all unused cache entries every 15 minutes:
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.
227 Extended L2 Entries
228 -------------------
230 64-bit L2 entries.
232 Images with extended L2 entries need twice as much L2 metadata, so the L2
233 cache size must be twice as large for the same disk space.