Browse files

docs: Document the new default sizes of the qcow2 caches

We have just reduced the refcount cache size to the minimum unless
the user explicitly requests a larger one, so we have to update the
documentation to reflect this change.

Signed-off-by: Alberto Garcia <>
Reviewed-by: Eric Blake <>
Signed-off-by: Max Reitz <>
  • Loading branch information...
bertogg authored and XanClic committed Apr 17, 2018
1 parent 5225399 commit 603790ef3aec6a19b1c095188a1d2171934a27de
Showing with 16 additions and 17 deletions.
  1. +16 −17 docs/qcow2-cache.txt
@@ -116,31 +116,30 @@ There are three options available, and all of them take bytes:
"refcount-cache-size": maximum size of the refcount block cache
"cache-size": maximum size of both caches combined
There are two things that need to be taken into account:
There are a few things that need to be taken into account:
- Both caches must have a size that is a multiple of the cluster size
(or the cache entry size: see "Using smaller cache sizes" below).
- If you only set one of the options above, QEMU will automatically
adjust the others so that the L2 cache is 4 times bigger than the
refcount cache.
- The default L2 cache size is 8 clusters or 1MB (whichever is more),
and the minimum is 2 clusters (or 2 cache entries, see below).
This means that these options are equivalent:
- The default (and minimum) refcount cache size is 4 clusters.
-drive file=hd.qcow2,l2-cache-size=2097152
-drive file=hd.qcow2,refcount-cache-size=524288
-drive file=hd.qcow2,cache-size=2621440
- If only "cache-size" is specified then QEMU will assign as much
memory as possible to the L2 cache before increasing the refcount
cache size.
The reason for this 1/4 ratio is to ensure that both caches cover the
same amount of disk space. Note however that this is only valid with
the default value of refcount_bits (16). If you are using a different
value you might want to calculate both cache sizes yourself since QEMU
will always use the same 1/4 ratio.
Unlike L2 tables, refcount blocks are not used during normal I/O but
only during allocations and internal snapshots. In most cases they are
accessed sequentially (even during random guest I/O) so increasing the
refcount cache size won't have any measurable effect in performance
(this can change if you are using internal snapshots, so you may want
to think about increasing the cache size if you use them heavily).
It's also worth mentioning that there's no strict need for both caches
to cover the same amount of disk space. The refcount cache is used
much less often than the L2 cache, so it's perfectly reasonable to
keep it small.
Before QEMU 2.12 the refcount cache had a default size of 1/4 of the
L2 cache size. This resulted in unnecessarily large caches, so now the
refcount cache is as small as possible unless overridden by the user.
Using smaller cache entries

0 comments on commit 603790e

Please sign in to comment.