1.. _virtio-blk:
2
3Virtio-BLK
4##########
5
6The virtio-blk device is a simple virtual block device. The FE driver
7(in the User VM space) places read, write, and other requests onto the
8virtqueue, so that the BE driver (in the Service VM space) can process them
9accordingly.  Communication between the FE and BE is based on the virtio
10kick and notify mechanism.
11
12The virtio device ID of the virtio-blk is ``2``, and it supports one
13virtqueue, the size of which is 64, configurable in the source code.
14
15.. figure:: images/virtio-blk-image01.png
16   :align: center
17   :width: 900px
18   :name: virtio-blk-arch
19
20   Virtio-blk Architecture
21
22The feature bits supported by the BE device are shown as follows:
23
24``VIRTIO_BLK_F_SEG_MAX``
25  Maximum number of segments in a request is in seg_max.
26``VIRTIO_BLK_F_BLK_SIZE``
27  Block size of disk is in blk_size.
28``VIRTIO_BLK_F_TOPOLOGY``
29  Device exports information on optimal I/O alignment.
30``VIRTIO_RING_F_INDIRECT_DESC``
31  Support for indirect descriptors
32``VIRTIO_BLK_F_FLUSH``
33  Cache flush command support.
34``VIRTIO_BLK_F_CONFIG_WCE``
35  Device can toggle its cache between writeback and writethrough modes.
36
37
38Virtio-BLK BE Design
39********************
40
41.. figure:: images/virtio-blk-image02.png
42   :align: center
43   :width: 900px
44   :name: virtio-blk-be
45
46   Virtio-BLK BE Design
47
48The virtio-blk BE device is implemented as a legacy virtio device. Its
49backend media could be a file or a partition. The virtio-blk device
50supports writeback and writethrough cache mode. In writeback mode,
51virtio-blk has good write and read performance. To be safer,
52writethrough is set as the default mode, as it can make sure every write
53operation queued to the virtio-blk FE driver layer is submitted to
54hardware storage.
55
56During initialization, virtio-blk will allocate 64 ioreq buffers in a
57shared ring used to store the I/O requests.  The freeq, busyq, and pendq
58shown in :numref:`virtio-blk-be` are used to manage requests. Each
59virtio-blk device starts 8 worker threads to process request
60asynchronously.
61
62
63Usage:
64******
65
66The Device Model configuration command syntax for virtio-blk is::
67
68   -s <slot>,virtio-blk,<filepath>[,options]
69
70- ``filepath`` is the path of a file or disk partition
71- ``options`` include:
72
73  - ``writethru``: write operation is reported completed only when the
74    data has been written to physical storage.
75  - ``writeback``: write operation is reported completed when data is
76    placed in the page cache. Needs to be flushed to the physical storage.
77  - ``ro``: open file with readonly mode.
78  - ``sectorsize``: configured as either
79    ``sectorsize=<sector size>/<physical sector size>`` or
80    ``sectorsize=<sector size>``.
81    The default values for sector size and physical sector size are 512
82  - ``range``: configured as ``range=<start lba in file>/<sub file size>``
83    meaning the virtio-blk will only access part of the file, from the
84    ``<start lba in file>`` to ``<start lba in file> + <sub file size>``.
85
86A simple example for virtio-blk:
87
881. Prepare a file in Service VM folder::
89
90      dd if=/dev/zero of=test.img bs=1M count=1024
91      mkfs.ext4 test.img
92
93#. Add virtio-blk in the DM cmdline, slot number should not duplicate
94   another device::
95
96      -s 9,virtio-blk,/root/test.img
97
98#. Launch User VM, you can find ``/dev/vdx`` in User VM.
99
100   The ``x`` in ``/dev/vdx`` is related to the slot number used.  If
101   If you start DM with two virtio-blks, and the slot numbers are 9 and 10,
102   then, the device with slot 9 will be recognized as ``/dev/vda``, and
103   the device with slot 10 will be ``/dev/vdb``
104
105#. Mount ``/dev/vdx`` to a folder in the User VM, and then you can access it.
106
107
108Successful booting of the User VM verifies the correctness of the
109device.
110