From 4163a275620e7e7992c1d058148ee4560aa6b74f Mon Sep 17 00:00:00 2001 From: Ben Walker Date: Tue, 26 Dec 2017 14:37:58 -0700 Subject: [PATCH] doc: Expand the intro section of the bdev documentation. Change-Id: I2077133fc8f98d1fc1020d617e50867871d8e841 Signed-off-by: Ben Walker Reviewed-on: https://review.gerrithub.io/392986 Tested-by: SPDK Automated Test System Reviewed-by: Jim Harris Reviewed-by: Daniel Verkamp --- doc/bdev.md | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/doc/bdev.md b/doc/bdev.md index 113e49db5..2af8e10cd 100644 --- a/doc/bdev.md +++ b/doc/bdev.md @@ -1,24 +1,29 @@ -# Block Device Abstraction Layer {#bdev} +# Block Device Layer {#bdev} -# SPDK bdev Getting Started Guide {#bdev_getting_started} +# Introduction {#bdev_getting_started} -Block storage in SPDK applications is provided by the SPDK bdev layer. SPDK bdev consists of: +The SPDK block device layer, often simply called *bdev*, is a C library +intended to be equivalent to the operating system block storage layer that +often sits immediately above the device drivers in a traditional kernel +storage stack. Specifically, this library provides the following +functionality: -* a driver module API for implementing bdev drivers -* an application API for enumerating and claiming SPDK block devices and performance operations -(read, write, unmap, etc.) on those devices -* bdev drivers for NVMe, malloc (ramdisk), Linux AIO and Ceph RBD -* configuration via SPDK configuration files or JSON RPC +* A pluggable module API for implementing block devices that interface with different types of block storage devices. +* Driver modules for NVMe, malloc (ramdisk), Linux AIO, virtio-scsi, Ceph RBD, and more. +* An application API for enumerating and claiming SPDK block devices and then performing operations (read, write, unmap, etc.) on those devices. +* Facilities to stack block devices to create complex I/O pipelines, including logical volume management (lvol) and partition support (GPT). +* Configuration of block devices via JSON-RPC and a configuration file. +* Request queueing, timeout, and reset handling. +* Multiple, lockless queues for sending I/O to block devices. # Configuring block devices {#bdev_config} -SPDK block devices are typically configured via an SPDK configuration file. These block devices -can then be associated with higher level abstractions such as iSCSI target nodes, NVMe-oF namespaces -or vhost-scsi controllers. This section will describe how to configure block devices for the -SPDK bdev drivers included with SPDK. - -The SPDK configuration file is typically passed to your SPDK-based application via the command line. -Refer to the help facility of your application for more details. +The block device layer is a C library with a single public header file named +bdev.h. Upon initialization, the library will read in a configuration file that +defines the block devices it will expose. The configuration file is a text +format containing sections denominated by square brackets followed by keys with +optional values. It is often passed as a command line argument to the +application. Refer to the help facility of your application for more details. ## NVMe {#bdev_config_nvme}