[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