Re: [Qemu-devel] [PATCH] docs: add blkdebug block driver documentation

[Paolo Bonzini <pbonzini@redhat.com>]

Il 22/09/2014 11:20, Stefan Hajnoczi ha scritto:
> The blkdebug block driver is undocumented.  Documenting it is worthwhile
> since it offers powerful error injection features that are used by
> qemu-iotests test cases.
> 
> This document will make it easier for people to learn about and use
> blkdebug.

Just one small comment below...

> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/blkdebug.txt | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 142 insertions(+)
>  create mode 100644 docs/blkdebug.txt
> 
> diff --git a/docs/blkdebug.txt b/docs/blkdebug.txt
> new file mode 100644
> index 0000000..7e616e0
> --- /dev/null
> +++ b/docs/blkdebug.txt
> @@ -0,0 +1,142 @@
> +Block I/O error injection using blkdebug
> +----------------------------------------
> +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 (out 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.  Image formats
> +are especially complex since metadata I/O errors during cluster allocation or
> +while updating tables happen halfway through request processing and require
> +discipline to keep image files consistent.
> +
> +Error injection allows test cases to trigger I/O errors at specific points.
> +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 the request
> +then its "action" is executed.
> +
> +Rules can be placed in a .ini file:

Rules can be placed in a configuration file; the configuration file
follows the same .ini-like format used by QEMU's -readconfig option, and
each section of the file represents a rule.

The following configuration file defines a single rule:

> 
> +
> +  $ cat blkdebug.conf
> +  [inject-error]
> +  event = "read_aio"
> +  errno = "28"
> +


Paolo