From 71ea82650745faa9f799c3b5a5256adf4e43306b Mon Sep 17 00:00:00 2001 From: Dariusz Stojaczyk Date: Mon, 2 Oct 2017 19:31:06 +0200 Subject: [PATCH] bdev_virtio: added doc page Change-Id: Ia88ae52117068ac395dad9ad3d7ac818e41077fb Signed-off-by: Dariusz Stojaczyk Reviewed-on: https://review.gerrithub.io/380956 Tested-by: SPDK Automated Test System Reviewed-by: Paul Luse Reviewed-by: Daniel Verkamp --- README.md | 1 + doc/Doxyfile | 3 ++- doc/bdev.md | 32 ++++++++++++++++++++++++++++++++ doc/index.md | 1 + doc/virtio.md | 41 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 77 insertions(+), 1 deletion(-) create mode 100644 doc/virtio.md diff --git a/README.md b/README.md index b611e7e5b8..a277abf5d0 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ The development kit currently includes: * [NVMe over Fabrics target](http://www.spdk.io/doc/nvmf.html) * [iSCSI target](http://www.spdk.io/doc/iscsi.html) * [vhost target](http://www.spdk.io/doc/vhost.html) +* [Virtio-SCSI driver](http://www.spdk.io/doc/virtio.html) # In this readme: diff --git a/doc/Doxyfile b/doc/Doxyfile index 62f3350c1c..a6cdc7e65f 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -799,7 +799,8 @@ INPUT = ../include/spdk \ nvme-cli.md \ nvmf.md \ vagrant.md \ - vhost.md + vhost.md \ + virtio.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/doc/bdev.md b/doc/bdev.md index 1236aee7d7..41e0141ac7 100644 --- a/doc/bdev.md +++ b/doc/bdev.md @@ -142,6 +142,38 @@ Configuration file syntax: This exports 1 rbd block device, named Ceph0. +## Virtio SCSI {#bdev_config_virtio_scsi} + +The SPDK Virtio SCSI driver allows creating SPDK block devices from Virtio SCSI LUNs. + +Use the following configuration file snippet to bind all available Virtio-SCSI PCI +devices on a virtual machine. The driver will perform a target scan on each device +and automatically create block device for each LUN. + +~~~ +[VirtioPci] + # If enabled, the driver will automatically use all available Virtio-SCSI PCI + # devices. Disabled by default. + Enable Yes +~~~ + +The driver also supports connecting to vhost-user devices exposed on the same host. +In the following case, the host app has created a vhost-scsi controller which is +accessible through the /tmp/vhost.0 domain socket. + +~~~ +[VirtioUser0] + # Path to the Unix domain socket using vhost-user protocol. + Path /tmp/vhost.0 + # Maximum number of request queues to use. Default value is 1. + Queues 1 + +#[VirtioUser1] + #Path /tmp/vhost.1 +~~~ + +Each Virtio-SCSI device may export up to 64 block devices named VirtioScsi0t0 ~ VirtioScsi0t63. + ## GPT (GUID Partition Table) {#bdev_config_gpt} The GPT virtual bdev driver examines all bdevs as they are added and exposes partitions diff --git a/doc/index.md b/doc/index.md index c91287d1bb..82686cbbbe 100644 --- a/doc/index.md +++ b/doc/index.md @@ -31,6 +31,7 @@ - @ref blob - @ref blobfs - @ref vhost +- @ref virtio # Tools {#tools} diff --git a/doc/virtio.md b/doc/virtio.md new file mode 100644 index 0000000000..478e6d2cd7 --- /dev/null +++ b/doc/virtio.md @@ -0,0 +1,41 @@ +# Virtio SCSI driver {#virtio} + +# Introduction {#virtio_intro} + +Virtio SCSI driver is an initiator for SPDK @ref vhost application. The +driver allows any SPDK app to connect to another SPDK instance exposing +a vhost-scsi device. The driver will enumerate targets on the device (which acts +as a SCSI controller) and create *virtual* bdevs usable by any SPDK application. +Sending an I/O request to the Virtio SCSI bdev will put the request data into +a Virtio queue that is processed by the host SPDK app exposing the +controller. The host, after sending I/O to the real drive, will put the response +back into the Virtio queue. Then, the response is received by the Virtio SCSI +driver. + +The driver, just like the SPDK @ref vhost, is using pollers instead of standard +interrupts to check for an I/O response. It bypasses kernel interrupt and context +switching overhead of QEMU and guest kernel, significantly boosting the overall +I/O performance. + +Virtio SCSI driver supports two different usage models: +* PCI - This is the standard mode of operation when used in a guest virtual +machine, where QEMU has presented the virtio-scsi controller as a virtual +PCI device. +* User vhost - Can be used to connect to a vhost-scsi socket directly on the +same host. + +# Multiqueue {#virtio_multiqueue} + +The Virtio SCSI controller will automatically manage virtio queue distribution. +Currently each thread doing an I/O on a single bdev will get an exclusive queue. +Multi-threaded I/O on bdevs from a single Virtio-SCSI controller is not supported. + +# Limitations {#virtio_limitations} + +The Virtio SCSI driver is still experimental. Current implementation has many +limitations: + * supports only up to 8 hugepages (implies only 1GB sized pages are practical) + * single LUN per target + * only SPDK vhost-scsi controllers supported + * no RPC + * no multi-threaded I/O for single-queue virtio devices