[PATCH 0/5] docs: expand block driver documentation

[PATCH 0/5] docs: expand block driver documentation

[Stefan Hajnoczi]

During an IRC discussion Michael Tokarev pointed out that block drivers are not
well-documented.

This patch series tries to improve the situation. It's a small step, but any
improvement will help.

Stefan Hajnoczi (5):
  docs: expand introduction to disk images
  docs: differentiate between block driver create and runtime opts
  docs: flesh out raw format driver description
  docs: flesh out qcow2 format driver description
  docs: add throttle filter description

 docs/system/images.rst                 |  35 +++-
 docs/system/qemu-block-drivers.rst.inc | 259 +++++++++++++++++++++----
 2 files changed, 253 insertions(+), 41 deletions(-)

-- 
2.39.1

[PATCH 1/5] docs: expand introduction to disk images

[Stefan Hajnoczi]

Explain --blockdev, the graph, protocols, formats, and filters. Also
mention the relationship between --blockdev and --drive, since new users
are likely to hit both syntaxes.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/system/images.rst | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/docs/system/images.rst b/docs/system/images.rst
index d000bd6b6f..dc73acf8c9 100644
--- a/docs/system/images.rst
+++ b/docs/system/images.rst
@@ -3,9 +3,38 @@
 Disk Images
 -----------
 
-QEMU supports many disk image formats, including growable disk images
-(their size increase as non empty sectors are written), compressed and
-encrypted disk images.
+QEMU supports many different types of storage protocols, disk image file
+formats, and filter block drivers. *Protocols* provide access to storage such
+as local files or NBD exports. *Formats* implement file formats that are useful
+for sharing disk image files and add functionality like snapshots. *Filters*
+add behavior like I/O throttling.
+
+These features are composable in a graph. Each graph node is called a
+*blockdev*. This makes it possible to construct many different storage
+configurations. The simplest example is accessing a raw image file::
+
+   --blockdev file,filename=test.img,node-name=drive0
+
+A qcow2 image file throttled to 10 MB/s is specified like this::
+
+   --object throttle-group,x-bps-total=10485760,id=tg0 \
+   --blockdev file,filename=vm.qcow2,node-name=file0 \
+   --blockdev qcow2,file=file0,node-name=qcow0 \
+   --blockdev throttle,file=qcow0,throttle-group=tg0,node-name=drive0
+
+Blockdevs are not directly visible to guests. Guests use emulated storage
+controllers like a virtio-blk device to access a blockdev::
+
+   --device virtio-blk-pci,drive=drive0
+
+Note that QEMU has an older ``--drive`` syntax that is somewhat similar to
+``--blockdev``. ``--blockdev`` is preferred because ``--drive`` mixes storage
+controller and blockdev definitions in a single option that cannot express
+everything. When a "drive" or "device" is required by a command-line option or
+QMP command, a blockdev node-name can be used.
+
+The remainder of this chapter covers the block drivers and how to work with
+disk images.
 
 .. _disk_005fimages_005fquickstart:
 
-- 
2.39.1

Re: [PATCH 1/5] docs: expand introduction to disk images

[Eric Blake]

On Wed, Feb 01, 2023 at 04:12:30PM -0500, Stefan Hajnoczi wrote:
> Explain --blockdev, the graph, protocols, formats, and filters. Also
> mention the relationship between --blockdev and --drive, since new users
> are likely to hit both syntaxes.
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/system/images.rst | 35 ++++++++++++++++++++++++++++++++---
>  1 file changed, 32 insertions(+), 3 deletions(-)
> 
> diff --git a/docs/system/images.rst b/docs/system/images.rst
> index d000bd6b6f..dc73acf8c9 100644
> --- a/docs/system/images.rst
> +++ b/docs/system/images.rst
> @@ -3,9 +3,38 @@
>  Disk Images
>  -----------
>  
> -QEMU supports many disk image formats, including growable disk images
> -(their size increase as non empty sectors are written), compressed and
> -encrypted disk images.
> +QEMU supports many different types of storage protocols, disk image file
> +formats, and filter block drivers. *Protocols* provide access to storage such
> +as local files or NBD exports. *Formats* implement file formats that are useful

Do we want to spell out "Network Block Device" for those unfamiliar
with the acronym?

> +for sharing disk image files and add functionality like snapshots. *Filters*
> +add behavior like I/O throttling.
> +
> +These features are composable in a graph. Each graph node is called a
> +*blockdev*. This makes it possible to construct many different storage
> +configurations. The simplest example is accessing a raw image file::
> +
> +   --blockdev file,filename=test.img,node-name=drive0
> +
> +A qcow2 image file throttled to 10 MB/s is specified like this::
> +
> +   --object throttle-group,x-bps-total=10485760,id=tg0 \

Per block-core.json on ThrottleGroupProperties, x-bps-total is an
unstable alias for the @limits object; we should prefer the stable
spelling here.

> +   --blockdev file,filename=vm.qcow2,node-name=file0 \
> +   --blockdev qcow2,file=file0,node-name=qcow0 \
> +   --blockdev throttle,file=qcow0,throttle-group=tg0,node-name=drive0
> +
> +Blockdevs are not directly visible to guests. Guests use emulated storage
> +controllers like a virtio-blk device to access a blockdev::
> +
> +   --device virtio-blk-pci,drive=drive0
> +
> +Note that QEMU has an older ``--drive`` syntax that is somewhat similar to
> +``--blockdev``. ``--blockdev`` is preferred because ``--drive`` mixes storage
> +controller and blockdev definitions in a single option that cannot express
> +everything. When a "drive" or "device" is required by a command-line option or
> +QMP command, a blockdev node-name can be used.
> +
> +The remainder of this chapter covers the block drivers and how to work with
> +disk images.

Otherwise looks like a nice addition.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

[PATCH 2/5] docs: differentiate between block driver create and runtime opts

[Stefan Hajnoczi]

Options available with qemu-img create -o ... are called create options.
They affect how the image file is created on disk.

Options available with --blockdev ... are called runtime options. They
affect how the open blockdev behaves.

The documentation makes no distinction is made between the two. For
example, the preallocation filter driver talks about the runtime options
while the image format drivers talk about the create options.

Be explicit about create vs runtime options.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/system/qemu-block-drivers.rst.inc | 26 ++++++++++++++------------
 1 file changed, 14 insertions(+), 12 deletions(-)

diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
index dfe5d2293d..be6eec1eb6 100644
--- a/docs/system/qemu-block-drivers.rst.inc
+++ b/docs/system/qemu-block-drivers.rst.inc
@@ -6,9 +6,11 @@ any of the tools (like ``qemu-img``). This includes the preferred formats
 raw and qcow2 as well as formats that are supported for compatibility with
 older QEMU versions or other hypervisors.
 
-Depending on the image format, different options can be passed to
-``qemu-img create`` and ``qemu-img convert`` using the ``-o`` option.
-This section describes each format and the options that are supported for it.
+Depending on the image format, different options can be passed to ``qemu-img
+create`` and ``qemu-img convert`` using the ``-o`` option. These are called
+*create options*. Image formats also support different ``--blockdev`` options.
+These are called *runtime options*. This section describes each format and the
+options that are supported for it.
 
 .. program:: image-formats
 .. option:: raw
@@ -20,7 +22,7 @@ This section describes each format and the options that are supported for it.
   space. Use ``qemu-img info`` to know the real size used by the
   image or ``ls -ls`` on Unix/Linux.
 
-  Supported options:
+  Supported create options:
 
   .. program:: raw
   .. option:: preallocation
@@ -181,7 +183,7 @@ This section describes each format and the options that are supported for it.
    When converting QED images to qcow2, you might want to consider using the
    ``lazy_refcounts=on`` option to get a more QED-like behaviour.
 
-   Supported options:
+   Supported create options:
 
    .. program:: qed
    .. option:: backing_file
@@ -212,7 +214,7 @@ This section describes each format and the options that are supported for it.
   Old QEMU image format with support for backing files, compact image files,
   encryption and compression.
 
-  Supported options:
+  Supported create options:
 
    .. program:: qcow
    .. option:: backing_file
@@ -248,7 +250,7 @@ This section describes each format and the options that are supported for it.
 
   LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
 
-  Supported options:
+  Supported create options:
 
   .. program:: luks
   .. option:: key-secret
@@ -289,7 +291,7 @@ This section describes each format and the options that are supported for it.
 
   VirtualBox 1.1 compatible image format.
 
-  Supported options:
+  Supported create options:
 
   .. program:: vdi
   .. option:: static
@@ -302,7 +304,7 @@ This section describes each format and the options that are supported for it.
 
   VMware 3 and 4 compatible image format.
 
-  Supported options:
+  Supported create options:
 
   .. program: vmdk
   .. option:: backing_file
@@ -332,7 +334,7 @@ This section describes each format and the options that are supported for it.
 
   VirtualPC compatible image format (VHD).
 
-  Supported options:
+  Supported create options:
 
   .. program:: vpc
   .. option:: subformat
@@ -345,7 +347,7 @@ This section describes each format and the options that are supported for it.
 
   Hyper-V compatible image format (VHDX).
 
-  Supported options:
+  Supported create options:
 
   .. program:: VHDX
   .. option:: subformat
@@ -920,7 +922,7 @@ some additional tasks, hooking io requests.
   (expanding the protocol file) when writing past the file’s end. This can be
   useful for file-systems with slow allocation.
 
-  Supported options:
+  Supported runtime options:
 
   .. program:: preallocate
   .. option:: prealloc-align
-- 
2.39.1

Re: [PATCH 2/5] docs: differentiate between block driver create and runtime opts

[Eric Blake]

On Wed, Feb 01, 2023 at 04:12:31PM -0500, Stefan Hajnoczi wrote:
> Options available with qemu-img create -o ... are called create options.
> They affect how the image file is created on disk.
> 
> Options available with --blockdev ... are called runtime options. They
> affect how the open blockdev behaves.
> 
> The documentation makes no distinction is made between the two. For

s/is made //

> example, the preallocation filter driver talks about the runtime options
> while the image format drivers talk about the create options.
> 
> Be explicit about create vs runtime options.
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/system/qemu-block-drivers.rst.inc | 26 ++++++++++++++------------
>  1 file changed, 14 insertions(+), 12 deletions(-)
> 
> diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
> index dfe5d2293d..be6eec1eb6 100644
> --- a/docs/system/qemu-block-drivers.rst.inc
> +++ b/docs/system/qemu-block-drivers.rst.inc
> @@ -6,9 +6,11 @@ any of the tools (like ``qemu-img``). This includes the preferred formats
>  raw and qcow2 as well as formats that are supported for compatibility with
>  older QEMU versions or other hypervisors.
>  
> -Depending on the image format, different options can be passed to
> -``qemu-img create`` and ``qemu-img convert`` using the ``-o`` option.
> -This section describes each format and the options that are supported for it.
> +Depending on the image format, different options can be passed to ``qemu-img
> +create`` and ``qemu-img convert`` using the ``-o`` option. These are called
> +*create options*. Image formats also support different ``--blockdev`` options.
> +These are called *runtime options*. This section describes each format and the
> +options that are supported for it.
>  

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

[PATCH 3/5] docs: flesh out raw format driver description

[Stefan Hajnoczi]

Modernize the description and document the size=/offset= runtime
options.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/system/qemu-block-drivers.rst.inc | 32 ++++++++++++++++++++++----
 1 file changed, 27 insertions(+), 5 deletions(-)

diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
index be6eec1eb6..ec9ebb2066 100644
--- a/docs/system/qemu-block-drivers.rst.inc
+++ b/docs/system/qemu-block-drivers.rst.inc
@@ -16,11 +16,11 @@ options that are supported for it.
 .. option:: raw
 
   Raw disk image format. This format has the advantage of
-  being simple and easily exportable to all other emulators. If your
-  file system supports *holes* (for example in ext2 or ext3 on
-  Linux or NTFS on Windows), then only the written sectors will reserve
-  space. Use ``qemu-img info`` to know the real size used by the
-  image or ``ls -ls`` on Unix/Linux.
+  being simple and easily exportable to all other emulators. Modern
+  file systems support *holes* (for example in btrfs/XFS/ext4 on
+  Linux or NTFS on Windows) where space is allocated on demand as sectors are
+  written. Use ``qemu-img info`` to know the real size used by the image or
+  ``ls -ls`` on Unix/Linux.
 
   Supported create options:
 
@@ -33,6 +33,28 @@ options that are supported for it.
     for image by writing data to underlying storage. This data may or
     may not be zero, depending on the storage location.
 
+  Supported runtime options:
+
+  .. program:: raw
+  .. option:: offset
+
+    The byte position in the underlying file where the virtual disk starts.
+    This is handy when you want to present just a single partition from a
+    physical disk as the virtual disk. This option is usually used in
+    conjunction with the ``size`` option.
+
+  .. option:: size
+
+    Limit the virtual disk size to the given number of bytes, regardless of how
+    large the underlying file is. This option is usually used in conjunction
+    with the ``offset`` option.
+
+  Note the raw format can be omitted when no runtime options are being used. In
+  that case the raw format does nothing besides forwarding I/O requests to the
+  protocol blockdev. You can improve performance slightly by eliminating
+  ``--blockdev raw,file=file0,node-name=drive0`` and renaming the "file0"
+  blockdev to "drive0".
+
 .. program:: image-formats
 .. option:: qcow2
 
-- 
2.39.1

Re: [PATCH 3/5] docs: flesh out raw format driver description

[Daniel P. Berrangé]

On Wed, Feb 01, 2023 at 04:12:32PM -0500, Stefan Hajnoczi wrote:
> Modernize the description and document the size=/offset= runtime
> options.
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/system/qemu-block-drivers.rst.inc | 32 ++++++++++++++++++++++----
>  1 file changed, 27 insertions(+), 5 deletions(-)
> 
> diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
> index be6eec1eb6..ec9ebb2066 100644
> --- a/docs/system/qemu-block-drivers.rst.inc
> +++ b/docs/system/qemu-block-drivers.rst.inc
> @@ -16,11 +16,11 @@ options that are supported for it.
>  .. option:: raw
>  
>    Raw disk image format. This format has the advantage of
> -  being simple and easily exportable to all other emulators. If your
> -  file system supports *holes* (for example in ext2 or ext3 on
> -  Linux or NTFS on Windows), then only the written sectors will reserve
> -  space. Use ``qemu-img info`` to know the real size used by the
> -  image or ``ls -ls`` on Unix/Linux.
> +  being simple and easily exportable to all other emulators. Modern
> +  file systems support *holes* (for example in btrfs/XFS/ext4 on
> +  Linux or NTFS on Windows) where space is allocated on demand as sectors are
> +  written. Use ``qemu-img info`` to know the real size used by the image or
> +  ``ls -ls`` on Unix/Linux.
>  
>    Supported create options:
>  
> @@ -33,6 +33,28 @@ options that are supported for it.
>      for image by writing data to underlying storage. This data may or
>      may not be zero, depending on the storage location.
>  
> +  Supported runtime options:
> +
> +  .. program:: raw
> +  .. option:: offset
> +
> +    The byte position in the underlying file where the virtual disk starts.
> +    This is handy when you want to present just a single partition from a
> +    physical disk as the virtual disk. This option is usually used in
> +    conjunction with the ``size`` option.
> +
> +  .. option:: size
> +
> +    Limit the virtual disk size to the given number of bytes, regardless of how
> +    large the underlying file is. This option is usually used in conjunction
> +    with the ``offset`` option.
> +
> +  Note the raw format can be omitted when no runtime options are being used. In
> +  that case the raw format does nothing besides forwarding I/O requests to the
> +  protocol blockdev. You can improve performance slightly by eliminating
> +  ``--blockdev raw,file=file0,node-name=drive0`` and renaming the "file0"
> +  blockdev to "drive0".

This paragraphs reads a bit softly. I would word this such that we
explicitly and strongly recommend against using the 'raw' format
driver. Almost no one will have a need for this.

All the protocol drivers expose a raw format, which can be consumed
directly. So the 'raw' format driver should NEVER be used unless the
user needs to apply a limited window over the underlying disk capacity,
which is pretty rare.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

[PATCH 4/5] docs: flesh out qcow2 format driver description

[Stefan Hajnoczi]

Put the create options in alphabetical order, add compression_type and
extended_l2, and also mention the common runtime options. I did not add
rarely-used runtime options because I think it's too much information.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/system/qemu-block-drivers.rst.inc | 91 ++++++++++++++++++++------
 1 file changed, 70 insertions(+), 21 deletions(-)

diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
index ec9ebb2066..af72817763 100644
--- a/docs/system/qemu-block-drivers.rst.inc
+++ b/docs/system/qemu-block-drivers.rst.inc
@@ -59,13 +59,27 @@ options that are supported for it.
 .. option:: qcow2
 
   QEMU image format, the most versatile format. Use it to have smaller
-  images (useful if your filesystem does not supports holes, for example
-  on Windows), zlib based compression and support of multiple VM
+  images (useful if your filesystem does not support holes, for example
+  on Windows), zlib/zstd compression and support of multiple VM
   snapshots.
 
-  Supported options:
+  Supported create options:
 
   .. program:: qcow2
+  .. option:: backing_file
+
+    File name of a base image (see ``create`` subcommand)
+
+  .. option:: backing_fmt
+
+    Image format of the base image
+
+  .. option:: cluster_size
+
+    Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
+    sizes can improve the image file size whereas larger cluster sizes generally
+    provide better performance.
+
   .. option:: compat
 
     Determines the qcow2 version to use. ``compat=0.10`` uses the
@@ -74,13 +88,9 @@ options that are supported for it.
     newer understand (this is the default). Amongst others, this includes
     zero clusters, which allow efficient copy-on-read for sparse images.
 
-  .. option:: backing_file
+  .. option:: compression_type
 
-    File name of a base image (see ``create`` subcommand)
-
-  .. option:: backing_fmt
-
-    Image format of the base image
+    Selects the compression algorithm (zlib or zstd).
 
   .. option:: encryption
 
@@ -150,19 +160,11 @@ options that are supported for it.
     Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
     Defaults to ``2000``. Only used when ``encrypt.format=luks``.
 
-  .. option:: cluster_size
+  .. option:: extended_l2
 
-    Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
-    sizes can improve the image file size whereas larger cluster sizes generally
-    provide better performance.
-
-  .. option:: preallocation
-
-    Preallocation mode (allowed values: ``off``, ``metadata``, ``falloc``,
-    ``full``). An image with preallocated metadata is initially larger but can
-    improve performance when the image needs to grow. ``falloc`` and ``full``
-    preallocations are like the same options of ``raw`` format, but sets up
-    metadata also.
+    Enables the Extended L2 Entries feature that divides each cluster into 32
+    separately allocated sub-clusters. A larger cluster size can be used, thus
+    reducing metadata overhead, while still allowing fine-grained allocation.
 
   .. option:: lazy_refcounts
 
@@ -196,6 +198,53 @@ options that are supported for it.
     filename`` to check if the NOCOW flag is set or not (Capital 'C' is
     NOCOW flag).
 
+  .. option:: preallocation
+
+    Preallocation mode (allowed values: ``off``, ``metadata``, ``falloc``,
+    ``full``). An image with preallocated metadata is initially larger but can
+    improve performance when the image needs to grow. ``falloc`` and ``full``
+    preallocations are like the same options of ``raw`` format, but sets up
+    metadata also.
+
+  Supported runtime options:
+
+  .. program:: qcow2
+  .. option:: cache-clean-interval
+
+    Clean unused cache entries after this time (in seconds).
+
+  .. option:: cache-size
+
+    Maximum combined metadata (L2 tables and refcount blocks) cache size.
+
+  .. option:: encrypt.key-secret
+
+    ID of secret providing qcow2 AES key or LUKS passphrase.
+
+  .. option:: l2-cache-size
+
+    Maximum L2 table cache size.
+
+  .. option:: l2-cache-entry-size
+
+    Size of each entry in the L2 cache.
+
+  .. option:: pass-discard-request
+
+    Pass guest discard requests to the layer below (on/off).
+
+  .. option:: pass-discard-snapshot
+
+    Generate discard requests when snapshot related space is freed (on/off).
+
+  .. option:: pass-discard-other
+
+    Generate discard requests when other clusters are freed (on/off).
+
+  .. option:: refcount-cache-size
+
+    Maximum refcount block cache size.
+
 .. program:: image-formats
 .. option:: qed
 
-- 
2.39.1

Re: [PATCH 4/5] docs: flesh out qcow2 format driver description

[Eric Blake]

On Wed, Feb 01, 2023 at 04:12:33PM -0500, Stefan Hajnoczi wrote:
> Put the create options in alphabetical order, add compression_type and
> extended_l2, and also mention the common runtime options. I did not add
> rarely-used runtime options because I think it's too much information.
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/system/qemu-block-drivers.rst.inc | 91 ++++++++++++++++++++------
>  1 file changed, 70 insertions(+), 21 deletions(-)
> 
> diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
> index ec9ebb2066..af72817763 100644
> --- a/docs/system/qemu-block-drivers.rst.inc
> +++ b/docs/system/qemu-block-drivers.rst.inc
> @@ -59,13 +59,27 @@ options that are supported for it.
>  .. option:: qcow2
>  
>    QEMU image format, the most versatile format. Use it to have smaller
> -  images (useful if your filesystem does not supports holes, for example
> -  on Windows), zlib based compression and support of multiple VM
> +  images (useful if your filesystem does not support holes, for example
> +  on Windows), zlib/zstd compression and support of multiple VM

And sneaking in a grammar fix for "support", I see ;)

Reviewed-by: Eric Blake <eblake@Redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

[PATCH 5/5] docs: add throttle filter description

[Stefan Hajnoczi]

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/system/qemu-block-drivers.rst.inc | 110 +++++++++++++++++++++++++
 1 file changed, 110 insertions(+)

diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
index af72817763..ea4be5c210 100644
--- a/docs/system/qemu-block-drivers.rst.inc
+++ b/docs/system/qemu-block-drivers.rst.inc
@@ -1004,3 +1004,113 @@ some additional tasks, hooking io requests.
   .. option:: prealloc-size
 
     How much to preallocate (in bytes), default 128M.
+
+.. program:: filter-drivers
+.. option:: throttle
+
+  The throttle filter driver rate limits I/O requests so that the given IOPS
+  and bandwidth values are not exceeded. Limits are specified using the
+  following syntax::
+
+     --object '{"driver":"throttle-group","id":"tg0","limits":{"iops-total":2048,"bps-total":10485760}}'
+
+  The following throttle group limits are available:
+
+  .. program:: throttle-group
+  .. option:: iops-total
+
+    Limit total I/O operations per second.
+
+  .. option:: iops-total-max
+
+    I/O operations burst.
+
+  .. option:: iops-total-max-length
+
+    Length of the ``iops-total-max`` burst period, in seconds. It must only be
+    set if ``iops-total-max`` is set as well.
+
+  .. option:: iops-read
+
+    Limit read operations per second.
+
+  .. option:: iops-read-max
+
+     I/O operations read burst.
+
+  .. option:: iops-read-max-length
+
+    Length of the ``iops-read-max`` burst period, in seconds. It must only be
+    set if ``iops-read-max`` is set as well.
+
+  .. option:: iops-write
+
+    Limit write operations per second.
+
+  .. option:: iops-write-max
+
+    I/O operations write burst.
+
+  .. option:: iops-write-max-length
+
+    Length of the ``iops-write-max`` burst period, in seconds. It must only be
+    set if ``iops-write-max`` is set as well.
+
+  .. option:: bps-total
+
+    Limit total bytes per second.
+
+  .. option:: bps-total-max
+
+    Total bytes burst.
+
+  .. option:: bps-total-max-length
+
+    Length of the ``bps-total-max`` burst period, in seconds. It must only be
+    set if ``bps-total-max`` is set as well.
+
+  .. option:: bps-read
+
+    Limit read bytes per second.
+
+  .. option:: bps-read-max
+
+    Total bytes read burst.
+
+  .. option:: bps-read-max-length
+
+    Length of the ``bps-read-max`` burst period, in seconds. It must only be
+    set if ``bps-read-max`` is set as well.
+
+  .. option:: bps-write
+
+    Limit write bytes per second.
+
+  .. option:: bps-write-max
+
+    Total bytes write burst.
+
+  .. option:: bps-write-max-length
+
+    Length of the ``bps-write-max`` burst period, in seconds. It must only be
+    set if ``bps-write-max`` is set as well.
+
+  .. option:: iops-size
+
+    IOPS are counted as a multiple of this value, in bytes. For example, a 16
+    KB read request is counted as 4 IOPS when ``iops-size`` is 4 KB.
+
+  Throttle groups are defined separately from throttle blockdevs so they can be
+  shared by multiple blockdevs.
+
+  Note that the location of the throttle blockdev in the graph is significant.
+  Usually it will be one of the topmost nodes so that guest I/O requests are
+  throttled. When the throttle blockdev is located below a format driver it may
+  see a different I/O pattern due to image format metadata I/O.
+
+  Supported runtime options:
+
+  .. program:: throttle
+  .. option:: throttle-group
+
+    The id of the throttle group object that defines the I/O limits.
-- 
2.39.1

Re: [PATCH 5/5] docs: add throttle filter description

[Eric Blake]

On Wed, Feb 01, 2023 at 04:12:34PM -0500, Stefan Hajnoczi wrote:
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/system/qemu-block-drivers.rst.inc | 110 +++++++++++++++++++++++++
>  1 file changed, 110 insertions(+)

Reviewed-by: Eric Blake <eblake@redhat.com>

> 
> diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
> index af72817763..ea4be5c210 100644
> --- a/docs/system/qemu-block-drivers.rst.inc
> +++ b/docs/system/qemu-block-drivers.rst.inc
> @@ -1004,3 +1004,113 @@ some additional tasks, hooking io requests.
>    .. option:: prealloc-size
>  
>      How much to preallocate (in bytes), default 128M.
> +
> +.. program:: filter-drivers
> +.. option:: throttle
> +
> +  The throttle filter driver rate limits I/O requests so that the given IOPS
> +  and bandwidth values are not exceeded. Limits are specified using the
> +  following syntax::
> +
> +     --object '{"driver":"throttle-group","id":"tg0","limits":{"iops-total":2048,"bps-total":10485760}}'

Is it worth adding spaces after the commas, since JSON permits that,
to make the line a bit less cluttered?


-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org