Merge remote-tracking branch 'remotes/hreitz/tags/pull-block-2021-09-01' into staging

Block patches:
- Make the backup-top filter driver available for user-created block
  nodes (i.e. via blockdev-add)
- Allow running iotests with gdb or valgrind being attached to qemu
  instances
- Fix the raw format driver's permissions: There is no metadata, so we
  only need WRITE or RESIZE when the parent needs it
- Basic reopen implementation for win32 files (file-win32.c) so that
  qemu-img commit can work
- uclibc/musl build fix for the FUSE export code
- Some iotests delinting
- block-hmp-cmds.c refactoring

# gpg: Signature made Wed 01 Sep 2021 16:01:54 BST
# gpg:                using RSA key CB62D7A0EE3829E45F004D34A1FA40D098019CDF
# gpg:                issuer "hreitz@redhat.com"
# gpg: Good signature from "Hanna Reitz <hreitz@redhat.com>" [marginal]
# gpg: WARNING: This key is not certified with sufficiently trusted signatures!
# gpg:          It is not certain that the signature belongs to the owner.
# Primary key fingerprint: CB62 D7A0 EE38 29E4 5F00  4D34 A1FA 40D0 9801 9CDF

* remotes/hreitz/tags/pull-block-2021-09-01: (56 commits)
  block/file-win32: add reopen handlers
  block/export/fuse.c: fix fuse-lseek on uclibc or musl
  block/block-copy: block_copy_state_new(): drop extra arguments
  iotests/image-fleecing: add test-case for copy-before-write filter
  iotests/image-fleecing: prepare for adding new test-case
  iotests/image-fleecing: rename tgt_node
  iotests/image-fleecing: proper source device
  iotests.py: hmp_qemu_io: support qdev
  iotests: move 222 to tests/image-fleecing
  iotests/222: constantly use single quotes for strings
  iotests/222: fix pylint and mypy complains
  python:QEMUMachine: template typing for self returning methods
  python/qemu/machine: QEMUMachine: improve qmp() method
  python/qemu/machine.py: refactor _qemu_args()
  qapi: publish copy-before-write filter
  block/copy-before-write: make public block driver
  block/block-copy: make setting progress optional
  block/copy-before-write: initialize block-copy bitmap
  block/copy-before-write: cbw_init(): use options
  block/copy-before-write: bdrv_cbw_append(): drop unused compress arg
  ...

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

1 files changed, 29 insertions, 0 deletions

diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst
index 8a9cda33a5..4a0abbf23d 100644
--- a/docs/devel/testing.rst
+++ b/docs/devel/testing.rst
@@ -224,6 +224,35 @@ another application on the host may have locked the file, possibly leading to a
 test failure.  If using such devices are explicitly desired, consider adding
 ``locking=off`` option to disable image locking.
 
+Debugging a test case
+-----------------------
+The following options to the ``check`` script can be useful when debugging
+a failing test:
+
+* ``-gdb`` wraps every QEMU invocation in a ``gdbserver``, which waits for a
+  connection from a gdb client.  The options given to ``gdbserver`` (e.g. the
+  address on which to listen for connections) are taken from the ``$GDB_OPTIONS``
+  environment variable.  By default (if ``$GDB_OPTIONS`` is empty), it listens on
+  ``localhost:12345``.
+  It is possible to connect to it for example with
+  ``gdb -iex "target remote $addr"``, where ``$addr`` is the address
+  ``gdbserver`` listens on.
+  If the ``-gdb`` option is not used, ``$GDB_OPTIONS`` is ignored,
+  regardless of whether it is set or not.
+
+* ``-valgrind`` attaches a valgrind instance to QEMU. If it detects
+  warnings, it will print and save the log in
+  ``$TEST_DIR/<valgrind_pid>.valgrind``.
+  The final command line will be ``valgrind --log-file=$TEST_DIR/
+  <valgrind_pid>.valgrind --error-exitcode=99 $QEMU ...``
+
+* ``-d`` (debug) just increases the logging verbosity, showing
+  for example the QMP commands and answers.
+
+* ``-p`` (print) redirects QEMU’s stdout and stderr to the test output,
+  instead of saving it into a log file in
+  ``$TEST_DIR/qemu-machine-<random_string>``.
+
 Test case groups
 ----------------