[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 3/5] docs: flesh out raw format driver description
From: |
Daniel P . Berrangé |
Subject: |
Re: [PATCH 3/5] docs: flesh out raw format driver description |
Date: |
Thu, 2 Feb 2023 09:17:33 +0000 |
User-agent: |
Mutt/2.2.9 (2022-11-12) |
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 0/5] docs: expand block driver documentation, Stefan Hajnoczi, 2023/02/01
- [PATCH 1/5] docs: expand introduction to disk images, Stefan Hajnoczi, 2023/02/01
- [PATCH 2/5] docs: differentiate between block driver create and runtime opts, Stefan Hajnoczi, 2023/02/01
- [PATCH 3/5] docs: flesh out raw format driver description, Stefan Hajnoczi, 2023/02/01
- Re: [PATCH 3/5] docs: flesh out raw format driver description,
Daniel P . Berrangé <=
- [PATCH 4/5] docs: flesh out qcow2 format driver description, Stefan Hajnoczi, 2023/02/01
- [PATCH 5/5] docs: add throttle filter description, Stefan Hajnoczi, 2023/02/01