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