| Message ID | 20230201211234.301918-4-stefanha@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | docs: expand block driver documentation | expand |
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
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
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(-)