Re: [PATCH v2 0/8] qemu-img, qemu-trace-stap, virtfs-proxy-helper: convert to rST

[Peter Maydell]

On Fri, 24 Jan 2020 at 16:26, Peter Maydell <address@hidden> wrote:
>
> This patchset converts the following documentation to rST format:
>  * qemu-img
>  * qemu-trace-stap
>  * virtfs-proxy-helper
>
> (That means everything in step 3 in the plan:
> https://wiki.qemu.org/Features/Documentation#3:_Convert_things_which_are_mostly_standalone_manpages
> will be done except for qemu-cpu-models.texi. That
> should be a straightforward conversion but I haven't
> touched it yet because I know there's an on-list patch
> that updates the texi and wanted to avoid a conflict.)
>
> The patchset includes a new Sphinx extension which handles parsing
> the .hx files which provide documentation fragments for the qemu-img
> manual.
>

I'm going to send out a pullreq today with this in.
I'm squashing in these trivial fixups that deal with a
conflict with commit cdd267749a3ab787e8b, which added
a new qemu-img option and its documentation:

--- a/docs/interop/qemu-img.rst
+++ b/docs/interop/qemu-img.rst
@@ -247,7 +247,7 @@ Command description:
   Amends the image format specific *OPTIONS* for the image file
   *FILENAME*. Not all file formats support this operation.

-.. option:: bench [-c COUNT] [-d DEPTH] [-f FMT]
[--flush-interval=FLUSH_INTERVAL] [-n] [--no-drain] [-o OFFSET]
[--pattern=PATTERN] [-q] [-s BUFFER_SIZE] [-S STEP_SIZE] [-t CACHE]
[-w] [-U] FILENAME
+.. option:: bench [-c COUNT] [-d DEPTH] [-f FMT]
[--flush-interval=FLUSH_INTERVAL] [-n] [-i AIO] [--no-drain] [-o
OFFSET] [--pattern=PATTERN] [-q] [-s BUFFER_SIZE] [-S STEP_SIZE] [-t
CACHE] [-w] [-U] FILENAME

   Run a simple sequential I/O benchmark on the specified image. If ``-w`` is
   specified, a write test is performed, otherwise a read test is performed.
@@ -268,6 +268,9 @@ Command description:
   Linux, this option only works if ``-t none`` or ``-t directsync`` is
   specified as well.

+  if ``-i`` is specified, *AIO* option can be used to specify different
+  AIO backends: ``threads``, ``native`` or ``io_uring``.
+
   For write tests, by default a buffer filled with zeros is written.
This can be
   overridden with a pattern byte specified by *PATTERN*.


--- a/qemu-img-cmds.hx
+++ b/qemu-img-cmds.hx
@@ -28,7 +28,7 @@ STEXI
 @item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}]
[--flush-interval=@var{flush_interval}] [-n] [--no-drain] [-o
@var{offset}] [--pattern=@var{pattern}] [-q] [-s @var{buffer_size}]
[-S @var{step_size}] [-t @var{cache}] [-i @var{aio}] [-w] [-U]
@var{filename}
 ETEXI
 SRST
-.. option:: bench [-c COUNT] [-d DEPTH] [-f FMT]
[--flush-interval=FLUSH_INTERVAL] [-n] [--no-drain] [-o OFFSET]
[--pattern=PATTERN] [-q] [-s BUFFER_SIZE] [-S STEP_SIZE] [-t CACHE]
[-w] [-U] FILENAME
+.. option:: bench [-c COUNT] [-d DEPTH] [-f FMT]
[--flush-interval=FLUSH_INTERVAL] [-n] [--no-drain] [-o OFFSET]
[--pattern=PATTERN] [-q] [-s BUFFER_SIZE] [-S STEP_SIZE] [-t CACHE]
[-i AIO] [-w] [-U] FILENAME
 ERST
 DEF("check", img_check,
     "check [--object objectdef] [--image-opts] [-q] [-f fmt]
[--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename")

thanks
-- PMM