Merge remote-tracking branch 'remotes/maxreitz/tags/pull-block-2021-05-14' into staging

Block patches:
- drop block/io write notifiers
- qemu-iotests enhancements to make debugging easier
- rbd parsing fix
- HMP qemu-io fix (for iothreads)
- mirror job cancel relaxation (do not cancel in-flight requests when a
  READY mirror job is canceled with force=false)
- document qcow2's data_file and data_file_raw features
- fix iotest 297 for pylint 2.8
- block/copy-on-read refactoring

# gpg: Signature made Fri 14 May 2021 17:43:40 BST
# gpg:                using RSA key 91BEB60A30DB3E8857D11829F407DB0061D5CF40
# gpg:                issuer "mreitz@redhat.com"
# gpg: Good signature from "Max Reitz <mreitz@redhat.com>" [full]
# Primary key fingerprint: 91BE B60A 30DB 3E88 57D1  1829 F407 DB00 61D5 CF40

* remotes/maxreitz/tags/pull-block-2021-05-14:
  write-threshold: deal with includes
  test-write-threshold: drop extra TestStruct structure
  test-write-threshold: drop extra tests
  block/write-threshold: drop extra APIs
  test-write-threshold: rewrite test_threshold_(not_)trigger tests
  block: drop write notifiers
  block/write-threshold: don't use write notifiers
  qemu-iotests: fix pylint 2.8 consider-using-with error
  block/copy-on-read: use bdrv_drop_filter() and drop s->active
  Document qemu-img options data_file and data_file_raw
  qemu-iotests: fix case of SOCK_DIR already in the environment
  qemu-iotests: let "check" spawn an arbitrary test command
  qemu-iotests: move command line and environment handling from TestRunner to TestEnv
  qemu-iotests: allow passing unittest.main arguments to the test scripts
  qemu-iotests: do not buffer the test output
  mirror: stop cancelling in-flight requests on non-force cancel in READY
  monitor: hmp_qemu_io: acquire aio contex, fix crash
  block/rbd: Add an escape-aware strchr helper
  iotests/231: Update expected deprecation message

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

1 files changed, 31 insertions, 0 deletions

diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst
index c9efcfaefc..cfe1147879 100644
--- a/docs/tools/qemu-img.rst
+++ b/docs/tools/qemu-img.rst
@@ -866,6 +866,37 @@ Supported image file formats:
     issue ``lsattr filename`` to check if the NOCOW flag is set or not
     (Capital 'C' is NOCOW flag).
 
+  ``data_file``
+    Filename where all guest data will be stored. If this option is used,
+    the qcow2 file will only contain the image's metadata.
+
+    Note: Data loss will occur if the given filename already exists when
+    using this option with ``qemu-img create`` since ``qemu-img`` will create
+    the data file anew, overwriting the file's original contents. To simply
+    update the reference to point to the given pre-existing file, use
+    ``qemu-img amend``.
+
+  ``data_file_raw``
+    If this option is set to ``on``, QEMU will always keep the external data
+    file consistent as a standalone read-only raw image.
+
+    It does this by forwarding all write accesses to the qcow2 file through to
+    the raw data file, including their offsets. Therefore, data that is visible
+    on the qcow2 node (i.e., to the guest) at some offset is visible at the same
+    offset in the raw data file. This results in a read-only raw image. Writes
+    that bypass the qcow2 metadata may corrupt the qcow2 metadata because the
+    out-of-band writes may result in the metadata falling out of sync with the
+    raw image.
+
+    If this option is ``off``, QEMU will use the data file to store data in an
+    arbitrary manner. The file’s content will not make sense without the
+    accompanying qcow2 metadata. Where data is written will have no relation to
+    its offset as seen by the guest, and some writes (specifically zero writes)
+    may not be forwarded to the data file at all, but will only be handled by
+    modifying qcow2 metadata.
+
+    This option can only be enabled if ``data_file`` is set.
+
 ``Other``
 
   QEMU also supports various other image file formats for