qemu/docs
Nir Soffer 916372e48f qemu-nbd: Change default cache mode to writeback
Both qemu and qemu-img use writeback cache mode by default, which is
already documented in qemu(1). qemu-nbd uses writethrough cache mode by
default, and the default cache mode is not documented.

According to the qemu-nbd(8):

   --cache=CACHE
          The  cache  mode  to be used with the file.  See the
          documentation of the emulator's -drive cache=... option for
          allowed values.

qemu(1) says:

    The default mode is cache=writeback.

So users have no reason to assume that qemu-nbd is using writethough
cache mode. The only hint is the painfully slow writing when using the
defaults.

Looking in git history, it seems that qemu used writethrough in the past
to support broken guests that did not flush data properly, or could not
flush due to limitations in qemu. But qemu-nbd clients can use
NBD_CMD_FLUSH to flush data, so using writethrough does not help anyone.

Change the default cache mode to writback, and document the default and
available values properly in the online help and manual.

With this change converting image via qemu-nbd is 3.5 times faster.

    $ qemu-img create dst.img 50g
    $ qemu-nbd -t -f raw -k /tmp/nbd.sock dst.img

Before this change:

    $ hyperfine -r3 "./qemu-img convert -p -f raw -O raw -T none -W fedora34.img nbd+unix:///?socket=/tmp/nbd.sock"
    Benchmark #1: ./qemu-img convert -p -f raw -O raw -T none -W fedora34.img nbd+unix:///?socket=/tmp/nbd.sock
      Time (mean ± σ):     83.639 s ±  5.970 s    [User: 2.733 s, System: 6.112 s]
      Range (min … max):   76.749 s … 87.245 s    3 runs

After this change:

    $ hyperfine -r3 "./qemu-img convert -p -f raw -O raw -T none -W fedora34.img nbd+unix:///?socket=/tmp/nbd.sock"
    Benchmark #1: ./qemu-img convert -p -f raw -O raw -T none -W fedora34.img nbd+unix:///?socket=/tmp/nbd.sock
      Time (mean ± σ):     23.522 s ±  0.433 s    [User: 2.083 s, System: 5.475 s]
      Range (min … max):   23.234 s … 24.019 s    3 runs

Users can avoid the issue by using --cache=writeback[1] but the defaults
should give good performance for the common use case.

[1] https://bugzilla.redhat.com/1990656

Signed-off-by: Nir Soffer <nsoffer@redhat.com>
Message-Id: <20210813205519.50518-1-nsoffer@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
CC: qemu-stable@nongnu.org
Signed-off-by: Eric Blake <eblake@redhat.com>
(cherry picked from commit 0961525705)
Signed-off-by: Michael Roth <michael.roth@amd.com>
2021-10-15 17:50:57 -05:00
..
_templates docs: add "page source" link to sphinx documentation 2020-11-10 08:51:30 +01:00
config docs: Grammar and spelling fixes 2018-07-13 10:16:04 +01:00
devel * Updates for the MAINTAINERS file 2021-04-01 23:34:16 +01:00
interop docs: simplify each section title 2021-04-01 15:27:44 +04:00
specs docs: add nvme emulation documentation 2021-04-12 07:05:31 +02:00
sphinx sphinx: qapidoc: Wrap "If" section body in a paragraph node 2021-04-13 10:14:58 +01:00
spin docs: create config/, devel/ and spin/ subdirectories 2017-06-07 18:22:03 +02:00
system docs/system: Document the removal of "compat" property for POWER CPUs 2021-10-13 11:22:35 -05:00
tools qemu-nbd: Change default cache mode to writeback 2021-10-15 17:50:57 -05:00
user docs: simplify each section title 2021-04-01 15:27:44 +04:00
amd-memory-encryption.txt confidential guest support: Update documentation 2021-02-08 16:57:38 +11:00
barrier.txt ui: add an embedded Barrier client 2019-09-17 13:43:22 +02:00
block-replication.txt colo: Update Documentation for continuous replication 2020-03-03 18:04:47 +08:00
bootindex.txt docs qemu-doc: Avoid ide-drive, it's deprecated 2017-06-04 18:42:55 +03:00
can.txt docs: Fix some typos (found by codespell) 2020-11-18 09:29:41 +01:00
ccid.txt docs: update to show preferred boolean syntax for -chardev 2021-02-25 14:14:33 +01:00
COLO-FT.txt docs: update to show preferred boolean syntax for -cpu 2021-02-25 14:14:33 +01:00
colo-proxy.txt docs: update to show preferred boolean syntax for -chardev 2021-02-25 14:14:33 +01:00
conf.py docs: Build and install all the docs in a single manual 2021-01-19 15:45:14 +00:00
confidential-guest-support.txt s390: Recognize confidential-guest-support option 2021-02-08 16:57:38 +11:00
defs.rst.inc docs: Fix typo in the default name of the qemu-system-x86_64 binary 2021-04-01 14:28:39 +02:00
hyperv.txt i386: Make migration fail when Hyper-V reenlightenment was enabled but 'user_tsc_khz' is unset 2021-03-19 08:48:18 -04:00
igd-assign.txt vfio/pci: Add IGD documentation 2016-05-26 11:12:05 -06:00
image-fuzzer.txt docs: List all image elements currently supported by the fuzzer 2014-09-22 11:39:35 +01:00
index.rst docs/index.rst, docs/index.html.in: Reorder manuals 2020-03-12 11:14:06 +00:00
memory-hotplug.txt docs: Grammar and spelling fixes 2018-07-13 10:16:04 +01:00
meson.build docs: don't install corresponding man page if guest agent is disabled 2021-02-08 14:43:55 +01:00
multi-thread-compression.txt Replace '-enable-kvm' with '-accel kvm' in docs and help texts 2018-06-28 19:05:32 +02:00
multiseat.txt tests/docker/test-mingw and docs: Remove --with-sdlabi=2.0 2019-02-04 15:25:21 +00:00
nvdimm.txt nvdimm: check -object memory-backend-file, readonly=on option 2021-02-01 17:07:34 -05:00
papr-pef.txt spapr: Add PEF based confidential guest support 2021-02-08 16:57:38 +11:00
pci_expander_bridge.txt pxb: cleanup 2016-03-11 16:59:12 +02:00
pcie_pci_bridge.txt pci: removed the is_express field since a uniform interface was inserted 2018-02-08 21:06:41 +02:00
pcie.txt docs: pcie: Spell out machine type needs for PCIe features 2018-03-01 16:25:37 +02:00
pvrdma.txt docs: Fix broken links 2020-09-01 09:31:33 +02:00
qcow2-cache.txt qcow2: Document the Extended L2 Entries feature 2020-08-25 08:33:20 +02:00
qdev-device-use.txt hw/ide: remove 'ide-drive' device 2021-03-18 09:22:55 +00:00
qemu_logo.pdf docs: add qemu logo to pdf 2017-01-16 10:11:43 +01:00
qemu-option-trace.rst.inc qemu-option-trace.rst.inc: Don't use option:: markup 2020-11-02 16:52:18 +00:00
qemupciserial.inf docs: Grammar and spelling fixes 2018-07-13 10:16:04 +01:00
rdma.txt migrate: remove QMP/HMP commands for speed, downtime and cache size 2021-03-18 09:22:55 +00:00
replay.txt docs: Fix some typos (found by codespell) 2020-11-18 09:29:41 +01:00
spice-port-fqdn.txt docs: add spice-port-fqdn.txt 2012-12-17 14:01:41 +01:00
throttle.txt docs: Document the throttle block filter 2020-10-02 15:46:40 +02:00
u2f.txt hw/usb: Add U2F device autoscan to passthru mode 2020-08-31 08:23:39 +02:00
usb2.txt docs/usb2.txt: ehci has six ports 2018-08-21 10:22:03 +02:00
usb-storage.txt usb: Fix typo in documentation 2017-01-24 23:26:52 +03:00
virtio-balloon-stats.txt Remove the deprecated -balloon option 2018-08-31 09:52:13 +02:00
xbzrle.txt migrate: remove QMP/HMP commands for speed, downtime and cache size 2021-03-18 09:22:55 +00:00
xen-save-devices-state.txt Fix up dangling references to qmp-commands.* in comment and doc 2018-03-02 13:48:26 -06:00