[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 1/5] docs: expand introduction to disk images
From: |
Eric Blake |
Subject: |
Re: [PATCH 1/5] docs: expand introduction to disk images |
Date: |
Fri, 3 Feb 2023 16:52:16 -0600 |
User-agent: |
NeoMutt/20220429 |
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 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
- Re: [PATCH 1/5] docs: expand introduction to disk images,
Eric Blake <=
- [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
- [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