devel/testing/blkdebug.rst

5    Copyright (C) 2014-2015 Red Hat Inc
8    the COPYING file in the top-level directory.
10 The ``blkdebug`` block driver is a rule-based error injection engine.  It can be
11 used to exercise error code paths in block drivers including ``ENOSPC`` (out of
17 ----------
21 discipline to keep image files consistent.
23 Error injection allows test cases to trigger I/O errors at specific points.
24 This way, all error paths can be tested to make sure they are correct.
27 -----
29 engine when to fail an I/O request.
35 follows the same .ini-like format used by QEMU's ``-readconfig`` option, and
41   [inject-error]
47 ``/usr/include/asm-generic/errno-base.h`` for errno values.
51   $ qemu-system-x86_64
52         -drive if=none,cache=none,file=blkdebug:blkdebug.conf:test.img,id=drive0 \
53         -device virtio-blk-pci,drive=drive0,id=virtio-blk-pci0
58   which type of operation to match (e.g. ``read_aio``, ``write_aio``,
64   rule to match.  See `State transitions`_ for information
68   the numeric errno value to return when a request matches this rule.
73   (optional) a sector number that the request must overlap in order to
87 ------
89 to make so rules can match specific types of requests.  For example, the ``qcow2``
105   flush the host block device's disk cache
107 See ``qapi/block-core.json:BlkdebugEvent`` for the full list of events.
108 You may need to grep block driver source code to understand the
112 -----------------
113 There are cases where more power is needed to match a particular I/O request in
124 initialized to 1.  The state integer is internal to ``blkdebug`` and cannot be
128 Rules can be conditional on the current state and they can transition to a new
131 When a rule's "state" attribute is non-zero then the current state must equal
132 the attribute in order for the rule to match.
134 For example, to match the 2nd write_aio::
136   [set-state]
141   [inject-error]
146 The first ``write_aio`` request matches the ``set-state`` rule and transitions from
147 state 1 to state 2.  Once state 2 has been entered, the ``set-state`` rule no
148 longer matches since it requires state 1.  But the ``inject-error`` rule now
154   which type of operation to match (e.g. ``read_aio``, ``write_aio``,
160   rule to match
163   transition to this state number
165 Suspend and resume
166 ------------------
168 concurrent requests.  The "breakpoint" feature allows requests to be halted on
169 a ``blkdebug`` event and resumed later.  This makes it possible to achieve
172 Breakpoints on ``blkdebug`` events are associated with a user-defined ``tag`` string.
176 See the ``qemu-io(1)`` ``break``, ``resume``, ``remove_break``, and ``wait_break``