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
17 ----------
27 -----
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
62 ``state``
63   (optional) the engine must be in this state number in order for this
64   rule to match.  See `State transitions`_ for information
77   (optional, default ``off``) only execute this action on the first
81   (optional, default ``off``) return a NULL ``BlockAIOCB``
87 ------
102   write out unwritten block driver state (e.g. cached metadata)
107 See ``qapi/block-core.json:BlkdebugEvent`` for the full list of events.
111 State transitions
112 -----------------
120 How do we match the 2nd ``write_aio`` but not the first?  This is where state
123 The error injection engine has an integer called the "state" that always starts
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
129 state.
131 When a rule's "state" attribute is non-zero then the current state must equal
136   [set-state]
138   state = "1"
141   [inject-error]
143   state = "2"
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
151 State transition rules support the following attributes:
158 ``state``
159   (optional) the engine must be in this state number in order for this
163   transition to this state number
166 ------------------
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``