From 156b46ded3853dfc6b34c5afae019ff61798491b Mon Sep 17 00:00:00 2001 From: Alberto Garcia Date: Wed, 21 Feb 2018 16:08:49 +0200 Subject: specs/qcow2: Fix documentation of the compressed cluster descriptor This patch fixes several mistakes in the documentation of the compressed cluster descriptor: 1) the documentation claims that the cluster descriptor contains the number of sectors used to store the compressed data, but what it actually contains is the number of sectors *minus one* or, in other words, the number of additional sectors after the first one. 2) the width of the fields is incorrectly specified. The number of bits used by each field is x = 62 - (cluster_bits - 8) for the offset field y = (cluster_bits - 8) for the size field So the offset field's location is [0, x-1], not [0, x] as stated. 3) the size field does not contain the size of the compressed data, but rather the number of sectors where that data is stored. The compressed data starts at the exact point specified in the offset field and ends when there's enough data to produce a cluster of decompressed data. Both points can be in the middle of a sector, allowing several compressed clusters to be stored next to one another, sharing sectors if necessary. Cc: qemu-stable@nongnu.org Signed-off-by: Alberto Garcia Reviewed-by: Eric Blake Signed-off-by: Kevin Wolf --- docs/interop/qcow2.txt | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/interop/qcow2.txt b/docs/interop/qcow2.txt index d7fdb1f..feb711f 100644 --- a/docs/interop/qcow2.txt +++ b/docs/interop/qcow2.txt @@ -426,10 +426,20 @@ Standard Cluster Descriptor: Compressed Clusters Descriptor (x = 62 - (cluster_bits - 8)): - Bit 0 - x: Host cluster offset. This is usually _not_ aligned to a - cluster boundary! + Bit 0 - x-1: Host cluster offset. This is usually _not_ aligned to a + cluster or sector boundary! - x+1 - 61: Compressed size of the images in sectors of 512 bytes + x - 61: Number of additional 512-byte sectors used for the + compressed data, beyond the sector containing the offset + in the previous field. Some of these sectors may reside + in the next contiguous host cluster. + + Note that the compressed data does not necessarily occupy + all of the bytes in the final sector; rather, decompression + stops when it has produced a cluster of data. + + Another compressed cluster may map to the tail of the final + sector used by this compressed cluster. If a cluster is unallocated, read requests shall read the data from the backing file (except if bit 0 in the Standard Cluster Descriptor is set). If there is -- cgit v1.1 From be820971ff6f88c156233eec8a50cdf8c70c0938 Mon Sep 17 00:00:00 2001 From: Alberto Garcia Date: Mon, 19 Feb 2018 16:54:59 +0200 Subject: 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: Alberto Garcia Reviewed-by: Eric Blake Signed-off-by: Kevin Wolf --- docs/qcow2-cache.txt | 46 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 43 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/qcow2-cache.txt b/docs/qcow2-cache.txt index b0571de..170191a 100644 --- a/docs/qcow2-cache.txt +++ b/docs/qcow2-cache.txt @@ -1,6 +1,6 @@ qcow2 L2/refcount cache configuration ===================================== -Copyright (C) 2015 Igalia, S.L. +Copyright (C) 2015, 2018 Igalia, S.L. Author: Alberto Garcia 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 -- cgit v1.1