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

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 :|