Commit be820971 authored by Alberto Garcia's avatar Alberto Garcia Committed by Kevin Wolf
Browse files

docs: document how to use the l2-cache-entry-size parameter 

This patch updates docs/qcow2-cache.txt explaining how to use the new
l2-cache-entry-size parameter.

Here's a more detailed technical description of this feature:

   https://lists.gnu.org/archive/html/qemu-block/2017-09/msg00635.html

And here are some performance numbers:

   https://lists.gnu.org/archive/html/qemu-block/2017-12/msg00507.html



Signed-off-by: default avatarAlberto Garcia <berto@igalia.com>
Reviewed-by: default avatarEric Blake <eblake@redhat.com>
Signed-off-by: default avatarKevin Wolf <kwolf@redhat.com>
parent 156b46de

docs/qcow2-cache.txt

+43 −3
Original line number Diff line number Diff line 
qcow2 L2/refcount cache configuration

=====================================

Copyright (C) 2015 Igalia, S.L.

Copyright (C) 2015, 2018 Igalia, S.L.

Author: Alberto Garcia <berto@igalia.com>



This work is licensed under the terms of the GNU GPL, version 2 or
@@ -118,8 +118,8 @@ There are three options available, and all of them take bytes: 


There are two things that need to be taken into account:



 - Both caches must have a size that is a multiple of the cluster

   size.

 - 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
@@ -143,6 +143,46 @@ much less often than the L2 cache, so it's perfectly reasonable to 
keep it small.





Using smaller cache entries

---------------------------

The qcow2 L2 cache stores complete tables by default. This means that

if QEMU needs an entry from an L2 table then the whole table is read

from disk and is kept in the cache. If the cache is full then a

complete table needs to be evicted first.



This can be inefficient with large cluster sizes since it results in

more disk I/O and wastes more cache memory.



Since QEMU 2.12 you can change the size of the L2 cache entry and make

it smaller than the cluster size. This can be configured using the

"l2-cache-entry-size" parameter:



   -drive file=hd.qcow2,l2-cache-size=2097152,l2-cache-entry-size=4096



Some things to take into account:



 - The L2 cache entry size has the same restrictions as the cluster

   size (power of two, at least 512 bytes).



 - Smaller entry sizes generally improve the cache efficiency and make

   disk I/O faster. This is particularly true with solid state drives

   so it's a good idea to reduce the entry size in those cases. With

   rotating hard drives the situation is a bit more complicated so you

   should test it first and stay with the default size if unsure.



 - Try different entry sizes to see which one gives faster performance

   in your case. The block size of the host filesystem is generally a

   good default (usually 4096 bytes in the case of ext4).



 - Only the L2 cache can be configured this way. The refcount cache

   always uses the cluster size as the entry size.



 - If the L2 cache is big enough to hold all of the image's L2 tables

   (as explained in the "Choosing the right cache sizes" section

   earlier in this document) then none of this is necessary and you

   can omit the "l2-cache-entry-size" parameter altogether.





Reducing the memory usage

-------------------------

It is possible to clean unused cache entries in order to reduce the