From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47985) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XWolO-00074m-CH for qemu-devel@nongnu.org; Wed, 24 Sep 2014 11:46:00 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XWolI-0003oA-5l for qemu-devel@nongnu.org; Wed, 24 Sep 2014 11:45:54 -0400 Received: from lputeaux-656-01-25-125.w80-12.abo.wanadoo.fr ([80.12.84.125]:56452 helo=paradis.irqsave.net) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XWolH-0003nX-Aa for qemu-devel@nongnu.org; Wed, 24 Sep 2014 11:45:47 -0400 Date: Wed, 24 Sep 2014 17:43:31 +0200 From: =?iso-8859-1?Q?Beno=EEt?= Canet Message-ID: <20140924154330.GC18261@irqsave.net> References: <1411551854-23025-1-git-send-email-stefanha@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline In-Reply-To: <1411551854-23025-1-git-send-email-stefanha@redhat.com> Content-Transfer-Encoding: quoted-printable Subject: Re: [Qemu-devel] [PATCH v3] docs: add blkdebug block driver documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Stefan Hajnoczi Cc: Kevin Wolf , Paolo Bonzini , John Snow , qemu-devel@nongnu.org, Max Reitz The Wednesday 24 Sep 2014 =E0 10:44:14 (+0100), Stefan Hajnoczi wrote : > The blkdebug block driver is undocumented. Documenting it is worthwhil= e > since it offers powerful error injection features that are used by > qemu-iotests test cases. >=20 > This document will make it easier for people to learn about and use > blkdebug. >=20 > Signed-off-by: Stefan Hajnoczi > --- > v3: > * Fix tab space damage [Eric] > * Rephrase event_names[] as full list of events [Eric] > * Explain that blkdebug state is not observable from outside [Eric] > * Clarify state 0 and state 1 [Eric] >=20 > v2: > * Added GPL v2 or later license and Red Hat copyright [Eric] > * Expanded ini rules file explanation [Paolo] > * Added note that errno values depend on the host [Eric] >=20 > docs/blkdebug.txt | 161 ++++++++++++++++++++++++++++++++++++++++++++++= ++++++++ > 1 file changed, 161 insertions(+) > create mode 100644 docs/blkdebug.txt >=20 > diff --git a/docs/blkdebug.txt b/docs/blkdebug.txt > new file mode 100644 > index 0000000..5dde072 > --- /dev/null > +++ b/docs/blkdebug.txt > @@ -0,0 +1,161 @@ > +Block I/O error injection using blkdebug > +---------------------------------------- > +Copyright (C) 2014 Red Hat Inc > + > +This work is licensed under the terms of the GNU GPL, version 2 or lat= er. See > +the COPYING file in the top-level directory. > + > +The blkdebug block driver is a rule-based error injection engine. It = can be > +used to exercise error code paths in block drivers including ENOSPC (o= ut of > +space) and EIO. > + > +This document gives an overview of the features available in blkdebug. > + > +Background > +---------- > +Block drivers have many error code paths that handle I/O errors. Imag= e formats > +are especially complex since metadata I/O errors during cluster alloca= tion or > +while updating tables happen halfway through request processing and re= quire > +discipline to keep image files consistent. > + > +Error injection allows test cases to trigger I/O errors at specific po= ints. > +This way, all error paths can be tested to make sure they are correct. > + > +Rules > +----- > +The blkdebug block driver takes a list of "rules" that tell the error = injection > +engine when to fail an I/O request. > + > +Each I/O request is evaluated against the rules. If a rule matches th= e request > +then its "action" is executed. > + > +Rules can be placed in a configuration file; the configuration file > +follows the same .ini-like format used by QEMU's -readconfig option, a= nd > +each section of the file represents a rule. > + > +The following configuration file defines a single rule: > + > + $ cat blkdebug.conf > + [inject-error] > + event =3D "read_aio" > + errno =3D "28" > + > +This rule fails all aio read requests with ENOSPC (28). Note that the= errno > +value depends on the host. On Linux, see > +/usr/include/asm-generic/errno-base.h for errno values. > + > +Invoke QEMU as follows: > + > + $ qemu-system-x86_64 > + -drive if=3Dnone,cache=3Dnone,file=3Dblkdebug:blkdebug.conf:te= st.img,id=3Ddrive0 \ > + -device virtio-blk-pci,drive=3Ddrive0,id=3Dvirtio-blk-pci0 > + > +Rules support the following attributes: > + > + event - which type of operation to match (e.g. read_aio, write_aio, > + flush_to_os, flush_to_disk). See the "Events" section for > + information on events. > + > + state - (optional) the engine must be in this state number in order = for this > + rule to match. See the "State transitions" section for info= rmation > + on states. > + > + errno - the numeric errno value to return when a request matches thi= s rule. > + The errno values depend on the host since the numeric values= are not > + standarized in the POSIX specification. > + > + sector - (optional) a sector number that the request must overlap in= order to > + match this rule > + > + once - (optional, default "off") only execute this action on the fir= st > + matching request > + > + immediately - (optional, default "off") return a NULL BlockDriverAIO= CB > + pointer and fail without an errno instead. This exerc= ises the > + code path where BlockDriverAIOCB fails and the caller'= s > + BlockDriverCompletionFunc is not invoked. > + > +Events > +------ > +Block drivers provide information about the type of I/O request they a= re about > +to make so rules can match specific types of requests. For example, t= he qcow2 > +block driver tells blkdebug when it accesses the L1 table so rules can= match > +only L1 table accesses and not other metadata or guest data requests. > + > +The core events are: > + > + read_aio - guest data read > + > + write_aio - guest data write > + > + flush_to_os - write out unwritten block driver state (e.g. cached me= tadata) > + > + flush_to_disk - flush the host block device's disk cache > + > +See block/blkdebug.c:event_names[] for the full list of events. You m= ay need > +to grep block driver source code to understand the meaning of specific= events. > + > +State transitions > +----------------- > +There are cases where more power is needed to match a particular I/O r= equest in > +a longer sequence of requests. For example: > + > + write_aio > + flush_to_disk > + write_aio > + > +How do we match the 2nd write_aio but not the first? This is where st= ate > +transitions come in. > + > +The error injection engine has an integer called the "state" that alwa= ys starts > +initialized to 1. The state integer is internal to blkdebug and canno= t be > +observed from outside but rules can interact with it for powerful matc= hing > +behavior. > + > +Rules can be conditional on the current state and they can transition = to a new > +state. > + > +When a rule's "state" attribute is non-zero then the current state mus= t equal > +the attribute in order for the rule to match. > + > +For example, to match the 2nd write_aio: > + > + [set-state] > + event =3D "write_aio" > + state =3D "1" > + new_state =3D "2" > + > + [inject-error] > + event =3D "write_aio" > + state =3D "2" > + errno =3D "5" > + > +The first write_aio request matches the set-state rule and transitions= from > +state 1 to state 2. Once state 2 has been entered, the set-state rule= no > +longer matches since it requires state 1. But the inject-error rule n= ow > +matches the next write_aio request and injects EIO (5). > + > +State transition rules support the following attributes: > + > + event - which type of operation to match (e.g. read_aio, write_aio, > + flush_to_os, flush_to_disk). See the "Events" section for > + information on events. > + > + state - (optional) the engine must be in this state number in order = for this > + rule to match > + > + new_state - transition to this state number > + > +Suspend and resume > +------------------ > +Exercising code paths in block drivers may require specific ordering a= mongst > +concurrent requests. The "breakpoint" feature allows requests to be h= alted on > +a blkdebug event and resumed later. This makes it possible to achieve > +deterministic ordering when multiple requests are in flight. > + > +Breakpoints on blkdebug events are associated with a user-defined "tag= " string. > +This tag serves as an identifier by which the request can be resumed a= t a later > +point. > + > +See the qemu-io(1) break, resume, remove_break, and wait_break command= s for > +details. > --=20 > 1.9.3 >=20 >=20 I won't be able to spellcheck and help clarify it better than Eric but it= 's nice that it is getting documented since it's a powerfull and useful feat= ure. Best regards Beno=EEt