SPDK NVMe Driver

最新推荐文章于 2025-03-28 09:47:44 发布

CDerL

最新推荐文章于 2025-03-28 09:47:44 发布

阅读量837

点赞数 1

分类专栏： SPDK 文章标签： linux SPDK

本文链接：https://blog.csdn.net/lincolnjunior_lj/article/details/131439432

版权

SPDK 专栏收录该内容

12 篇文章

订阅专栏

Introduction
Examples
Public Interface
NVMe Driver Design
NVMe over Fabrics Host Support
NVMe Multi Process
NVMe Hotplug
NVMe Character Devices
NVMe LED management

Introduction

NVMe 驱动程序是一个 C 库，可以直接链接到应用程序，该应用程序提供与NVMe SSD之间的直接零复制数据传输。它完全是被动的，这意味着它不生成任何线程，并且仅执行响应应用程序本身的函数调用的操作。
该库通过直接将PCI BAR映射到本地进程并执行MMIO来控制NVMe设备。I/O通过队列对异步提交，一般流程与 Linux 的libaio并没有完全不同。

最近，该库经过改进，还可以通过NVMe over Fabrics连接到远程 NVMe 设备。用户现在可以在本地PCI总线和远程NVMe over Fabrics 发现服务上调用|spdk_nvme_probe()|。API 在其他方面没有变化。

HelloWorld

SDPK仓库中提供了许多示例来演示如何使用NVMe库。它们都位于存储库的Examples/nvme目录中。

helloworld main 函数

/*   SPDX-License-Identifier: BSD-3-Clause
 *   Copyright (C) 2016 Intel Corporation.
 *   All rights reserved.
 */

#include "spdk/stdinc.h"

#include "spdk/nvme.h"
#include "spdk/vmd.h"
#include "spdk/nvme_zns.h"
#include "spdk/env.h"
#include "spdk/string.h"
#include "spdk/log.h"


int
main(int argc, char **argv)
{
	int rc;
	struct spdk_env_opts opts;

	/*
	 * SPDK relies on an abstraction around the local environment
	 * named env that handles memory allocation and PCI device operations.
	 * This library must be initialized first.
	 *
	 */
	spdk_env_opts_init(&opts);
	rc = parse_args(argc, argv, &opts);
	if (rc != 0) {
		return rc;
	}

	opts.name = "hello_world";
	if (spdk_env_init(&opts) < 0) {
		fprintf(stderr, "Unable to initialize SPDK env\n");
		return 1;
	}

	printf("Initializing NVMe Controllers\n");

	if (g_vmd && spdk_vmd_init()|) {
		fprintf(stderr, "Failed to initialize VMD."
			" Some NVMe devices can be unavailable.\n");
	}

	/*
	 * Start the SPDK NVMe enumeration process.  probe_cb will be called
	 *  for each NVMe controller found, giving our application a choice on
	 *  whether to attach to each controller.  attach_cb will then be
	 *  called for each controller after the SPDK NVMe driver has completed
	 *  initializing the controller we chose to attach.
	 */
	rc = |spdk_nvme_probe(&g_trid, NULL, probe_cb, attach_cb, NULL);
	if (rc != 0) {
		fprintf(stderr, "|spdk_nvme_probe()| failed\n");
		rc = 1;
		goto exit;
	}

	if (TAILQ_EMPTY(&g_controllers)) {
		fprintf(stderr, "no NVMe controllers found\n");
		rc = 1;
		goto exit;
	}

	printf("Initialization complete.\n");
	hello_world()|;
	cleanup()|;
	if (g_vmd) {
		spdk_vmd_fini()|;
	}

exit:
	cleanup()|;
	spdk_env_fini()|;
	return rc;
}

上述代码一个使用SPDK（Storage Performance Development Kit）的helloworld示例代码，它展示了如何初始化SPDK环境、初始化NVMe控制器并执行一些操作。下面是代码的主要逻辑：

导入所需的头文件和定义变量。
初始化SPDK环境选项并解析命令行参数。
初始化SPDK环境。
打印初始化NVMe控制器的消息。
如果启用了虚拟化VMD（Virtualization Management Device），则初始化VMD。
调用|spdk_nvme_probe函数开始NVMe控制器的枚举过程。probe_cb函数将在每个找到的NVMe控制器上调用，以给应用程序选择是否连接到每个控制器。然后，在我们选择连接的控制器上，attach_cb函数将在SPDK NVMe驱动程序完成控制器初始化后被调用。
检查是否找到了NVMe控制器。如果未找到，则输出错误消息并退出。
执行初始化完成的操作（在示例中为hello_world函数）。
清理资源。
如果启用了VMD，则关闭VMD。
执行最后的清理操作。
关闭SPDK环境。

这段代码展示了一个简单的SPDK应用程序的基本结构和初始化过程。它初始化SPDK环境、枚举NVMe控制器，并通过回调函数进行控制器的选择和初始化。你可以根据实际需求，编写更多的操作和功能来与NVMe控制器进行交互和管理。

hello_world 函数及相关数据结构代码

struct ctrlr_entry {
	struct |spdk_nvme_ctrlr		*ctrlr;
	TAILQ_ENTRY(ctrlr_entry)	link;
	char				name[1024];
};

struct ns_entry {
	struct |spdk_nvme_ctrlr	*ctrlr;
	struct |spdk_nvme_ns	*ns;
	TAILQ_ENTRY(ns_entry)	link;
	struct |spdk_nvme_qpair	*qpair;
};

static TAILQ_HEAD(, ctrlr_entry) g_controllers = TAILQ_HEAD_INITIALIZER(g_controllers);
static TAILQ_HEAD(, ns_entry) g_namespaces = TAILQ_HEAD_INITIALIZER(g_namespaces);
static struct |spdk_nvme_transport_id g_trid = {};

static bool g_vmd = false;

struct hello_world_sequence {
	struct ns_entry	*ns_entry;
	char		*buf;
	unsigned        using_cmb_io;
	int		is_completed;
};


static void
read_complete(void *arg, const struct |spdk_nvme_cpl *completion)
{
	struct hello_world_sequence *sequence = arg;

	/* Assume the I/O was successful */
	sequence->is_completed = 1;
	/* See if an error occurred. If so, display information
	 * about it, and set completion value so that I/O
	 * caller is aware that an error occurred.
	 */
	if (|spdk_nvme_cpl_is_error(completion)) {
		|spdk_nvme_qpair_print_completion(sequence->ns_entry->qpair, (struct |spdk_nvme_cpl *)completion);
		fprintf(stderr, "I/O error status: %s\n", |spdk_nvme_cpl_get_status_string(&completion->status));
		fprintf(stderr, "Read I/O failed, aborting run\n");
		sequence->is_completed = 2;
		exit(1);
	}

	/*
	 * The read I/O has completed.  Print the contents of the
	 *  buffer, free the buffer, then mark the sequence as
	 *  completed.  This will trigger the hello_world()| function
	 *  to exit its polling loop.
	 */
	printf("%s", sequence->buf);
	spdk_free(sequence->buf);
}

static void
write_complete(void *arg, const struct |spdk_nvme_cpl *completion)
{
	struct hello_world_sequence	*sequence = arg;
	struct ns_entry			*ns_entry = sequence->ns_entry;
	int				rc;

	/* See if an error occurred. If so, display information
	 * about it, and set completion value so that I/O
	 * caller is aware that an error occurred.
	 */
	if (|spdk_nvme_cpl_is_error(completion)) {
		|spdk_nvme_qpair_print_completion(sequence->ns_entry->qpair, (struct |spdk_nvme_cpl *)completion);
		fprintf(stderr, "I/O error status: %s\n", |spdk_nvme_cpl_get_status_string(&completion->status));
		fprintf(stderr, "Write I/O failed, aborting run\n");
		sequence->is_completed = 2;
		exit(1);
	}
	/*
	 * The write I/O has completed.  Free the buffer associated with
	 *  the write I/O and allocate a new zeroed buffer for reading
	 *  the data back from the NVMe namespace.
	 */
	if (sequence->using_cmb_io) {
		|spdk_nvme_ctrlr_unmap_cmb(ns_entry->ctrlr);
	} else {
		spdk_free(sequence->buf);
	}
	sequence->buf = spdk_zmalloc(0x1000, 0x1000, NULL, SPDK_ENV_SOCKET_ID_ANY, SPDK_MALLOC_DMA);

	rc = |spdk_nvme_ns_cmd_read(ns_entry->ns, ns_entry->qpair, sequence->buf,
				   0, /* LBA start */
				   1, /* number of LBAs */
				   read_complete, (void *)sequence, 0);
	if (rc != 0) {
		fprintf(stderr, "starting read I/O failed\n");
		exit(1);
	}
}

static void
reset_zone_complete(void *arg, const struct |spdk_nvme_cpl *completion)
{
	struct hello_world_sequence *sequence = arg;

	/* Assume the I/O was successful */
	sequence->is_completed = 1;
	/* See if an error occurred. If so, display information
	 * about it, and set completion value so that I/O
	 * caller is aware that an error occurred.
	 */
	if (|spdk_nvme_cpl_is_error(completion)) {
		|spdk_nvme_qpair_print_completion(sequence->ns_entry->qpair, (struct |spdk_nvme_cpl *)completion);
		fprintf(stderr, "I/O error status: %s\n", |spdk_nvme_cpl_get_status_string(&completion->status));
		fprintf(stderr, "Reset zone I/O failed, aborting run\n");
		sequence->is_completed = 2;
		exit(1);
	}
}

static void
reset_zone_and_wait_for_completion(struct hello_world_sequence *sequence)
{
	if (|spdk_nvme_zns_reset_zone(sequence->ns_entry->ns, sequence->ns_entry->qpair,
				     0, /* starting LBA of the zone to reset */
				     false, /* don't reset all zones */
				     reset_zone_complete,
				     sequence)) {
		fprintf(stderr, "starting reset zone I/O failed\n");
		exit(1);
	}
	while (!sequence->is_completed) {
		|spdk_nvme_qpair_process_completions(sequence->ns_entry->qpair, 0);
	}
	sequence->is_completed = 0;
}

static void
hello_world(void)
{
	struct ns_entry			*ns_entry;
	struct hello_world_sequence	sequence;
	int				rc;
	size_t				sz;

	TAILQ_FOREACH(ns_entry, &g_namespaces, link) {
		/*
		 * Allocate an I/O qpair that we can use to submit read/write requests
		 *  to namespaces on the controller.  NVMe controllers typically support
		 *  many qpairs per controller.  Any I/O qpair allocated for a controller
		 *  can submit I/O to any namespace on that controller.
		 *
		 * The SPDK NVMe driver provides no synchronization for qpair accesses -
		 *  the application must ensure only a single thread submits I/O to a
		 *  qpair, and that same thread must also check for completions on that
		 *  qpair.  This enables extremely efficient I/O processing by making all
		 *  I/O operations completely lockless.
		 */
		ns_entry->qpair = |spdk_nvme_ctrlr_alloc_io_qpair(ns_entry->ctrlr, NULL, 0);
		if (ns_entry->qpair == NULL) {
			printf("ERROR: |spdk_nvme_ctrlr_alloc_io_qpair()| failed\n");
			return;
		}

		/*
		 * Use spdk_dma_zmalloc to allocate a 4KB zeroed buffer.  This memory
		 * will be pinned, which is required for data buffers used for SPDK NVMe
		 * I/O operations.
		 */
		sequence.using_cmb_io = 1;
		sequence.buf = |spdk_nvme_ctrlr_map_cmb(ns_entry->ctrlr, &sz);
		if (sequence.buf == NULL || sz < 0x1000) {
			sequence.using_cmb_io = 0;
			sequence.buf = spdk_zmalloc(0x1000, 0x1000, NULL, SPDK_ENV_SOCKET_ID_ANY, SPDK_MALLOC_DMA);
		}
		if (sequence.buf == NULL) {
			printf("ERROR: write buffer allocation failed\n");
			return;
		}
		if (sequence.using_cmb_io) {
			printf("INFO: using controller memory buffer for IO\n");
		} else {
			printf("INFO: using host memory buffer for IO\n");
		}
		sequence.is_completed = 0;
		sequence.ns_entry = ns_entry;

		/*
		 * If the namespace is a Zoned Namespace, rather than a regular
		 * NVM namespace, we need to reset the first zone, before we
		 * write to it. This not needed for regular NVM namespaces.
		 */
		if (|spdk_nvme_ns_get_csi(ns_entry->ns) == |spdk_nvme_CSI_ZNS) {
			reset_zone_and_wait_for_completion(&sequence);
		}

		/*
		 * Print "Hello world!" to sequence.buf.  We will write this data to LBA
		 *  0 on the namespace, and then later read it back into a separate buffer
		 *  to demonstrate the full I/O path.
		 */
		snprintf(sequence.buf, 0x1000, "%s", "Hello world!\n");

		/*
		 * Write the data buffer to LBA 0 of this namespace.  "write_complete" and
		 *  "&sequence" are specified as the completion callback function and
		 *  argument respectively.  write_complete()| will be called with the
		 *  value of &sequence as a parameter when the write I/O is completed.
		 *  This allows users to potentially specify different completion
		 *  callback routines for each I/O, as well as pass a unique handle
		 *  as an argument so the application knows which I/O has completed.
		 *
		 * Note that the SPDK NVMe driver will only check for completions
		 *  when the application calls |spdk_nvme_qpair_process_completions()|.
		 *  It is the responsibility of the application to trigger the polling
		 *  process.
		 */
		rc = |spdk_nvme_ns_cmd_write(ns_entry->ns, ns_entry->qpair, sequence.buf,
					    0, /* LBA start */
					    1, /* number of LBAs */
					    write_complete, &sequence, 0);
		if (rc != 0) {
			fprintf(stderr, "starting write I/O failed\n");
			exit(1);
		}

		/*
		 * Poll for completions.  0 here means process all available completions.
		 *  In certain usage models, the caller may specify a positive integer
		 *  instead of 0 to signify the maximum number of completions it should
		 *  process.  This function will never block - if there are no
		 *  completions pending on the specified qpair, it will return immediately.
		 *
		 * When the write I/O completes, write_complete()| will submit a new I/O
		 *  to read LBA 0 into a separate buffer, specifying read_complete()| as its
		 *  completion routine.  When the read I/O completes, read_complete()| will
		 *  print the buffer contents and set sequence.is_completed = 1.  That will
		 *  break this loop and then exit the program.
		 */
		while (!sequence.is_completed) {
			|spdk_nvme_qpair_process_completions(ns_entry->qpair, 0);
		}

		/*
		 * Free the I/O qpair.  This typically is done when an application exits.
		 *  But SPDK does support freeing and then reallocating qpairs during
		 *  operation.  It is the responsibility of the caller to ensure all
		 *  pending I/O are completed before trying to free the qpair.
		 */
		|spdk_nvme_ctrlr_free_io_qpair(ns_entry->qpair);
	}
}

这段代码是SPDK示例代码中的一个函数，名为hello_world。它展示了如何使用SPDK进行基本的NVMe控制器操作，包括初始化I/O队列、分配内存缓冲区、写入数据、读取数据以及处理完成事件等。

以下是代码的主要逻辑：

遍历所有的命名空间（g_namespaces）。
为每个命名空间分配一个I/O队列（qpair），用于提交读/写请求到该命名空间所属的控制器。通过调用|spdk_nvme_ctrlr_alloc_io_qpair函数来完成分配。
分配一个大小为4KB的零填充缓冲区，用于存储数据。通过调用|spdk_nvme_ctrlr_map_cmb函数来获取控制器的CMB（Controller Memory Buffer）缓冲区，如果CMB不可用或不足4KB，则使用主机内存缓冲区。这些缓冲区是用于SPDK NVMe的I/O操作的数据缓冲区。
如果使用了CMB缓冲区，则打印相关信息；否则，打印另一组相关信息。
创建一个hello_world_sequence结构体，并设置相关属性，用于跟踪完成事件。
如果命名空间是一个Zoned Namespace（区域命名空间），则在写入数据之前需要重置第一个区域。
将字符串"Hello world!\n"写入到数据缓冲区。
调用|spdk_nvme_ns_cmd_write函数将数据缓冲区的内容写入到命名空间的LBA 0处，并指定一个回调函数write_complete来处理写入操作的完成事件。
使用|spdk_nvme_qpair_process_completions函数轮询完成事件。该函数将处理所有可用的完成事件，直到读操作完成并设置sequence.is_completed = 1。
释放I/O队列（qpair）。

该示例代码演示了如何使用SPDK进行基本的NVMe控制器操作，包括初始化环境、初始化控制器、分配/释放I/O队列、分配/释放内存缓冲区、写入数据、读取数据以及处理完成事件。你可以根据实际需求和具体的应用场景，扩展和修改代码以满足你的需求。

其他相关代码

static bool
probe_cb(void *cb_ctx, const struct |spdk_nvme_transport_id *trid,
	 struct |spdk_nvme_ctrlr_opts *opts)
{
	printf("Attaching to %s\n", trid->traddr);

	return true;
}

static void
attach_cb(void *cb_ctx, const struct |spdk_nvme_transport_id *trid,
	  struct |spdk_nvme_ctrlr *ctrlr, const struct |spdk_nvme_ctrlr_opts *opts)
{
	int nsid;
	struct ctrlr_entry *entry;
	struct |spdk_nvme_ns *ns;
	const struct |spdk_nvme_ctrlr_data *cdata;

	entry = malloc(sizeof(struct ctrlr_entry));
	if (entry == NULL) {
		perror("ctrlr_entry malloc");
		exit(1);
	}

	printf("Attached to %s\n", trid->traddr);

	/*
	 * |spdk_nvme_ctrlr is the logical abstraction in SPDK for an NVMe
	 *  controller.  During initialization, the IDENTIFY data for the
	 *  controller is read using an NVMe admin command, and that data
	 *  can be retrieved using |spdk_nvme_ctrlr_get_data()| to get
	 *  detailed information on the controller.  Refer to the NVMe
	 *  specification for more details on IDENTIFY for NVMe controllers.
	 */
	cdata = |spdk_nvme_ctrlr_get_data(ctrlr);

	snprintf(entry->name, sizeof(entry->name), "%-20.20s (%-20.20s)", cdata->mn, cdata->sn);

	entry->ctrlr = ctrlr;
	TAILQ_INSERT_TAIL(&g_controllers, entry, link);

	/*
	 * Each controller has one or more namespaces.  An NVMe namespace is basically
	 *  equivalent to a SCSI LUN.  The controller's IDENTIFY data tells us how
	 *  many namespaces exist on the controller.  For Intel(R) P3X00 controllers,
	 *  it will just be one namespace.
	 *
	 * Note that in NVMe, namespace IDs start at 1, not 0.
	 */
	for (nsid = |spdk_nvme_ctrlr_get_first_active_ns(ctrlr); nsid != 0;
	     nsid = |spdk_nvme_ctrlr_get_next_active_ns(ctrlr, nsid)) {
		ns = |spdk_nvme_ctrlr_get_ns(ctrlr, nsid);
		if (ns == NULL) {
			continue;
		}
		register_ns(ctrlr, ns);
	}
}

static void
cleanup(void)
{
	struct ns_entry *ns_entry, *tmp_ns_entry;
	struct ctrlr_entry *ctrlr_entry, *tmp_ctrlr_entry;
	struct |spdk_nvme_detach_ctx *detach_ctx = NULL;

	TAILQ_FOREACH_SAFE(ns_entry, &g_namespaces, link, tmp_ns_entry) {
		TAILQ_REMOVE(&g_namespaces, ns_entry, link);
		free(ns_entry);
	}

	TAILQ_FOREACH_SAFE(ctrlr_entry, &g_controllers, link, tmp_ctrlr_entry) {
		TAILQ_REMOVE(&g_controllers, ctrlr_entry, link);
		|spdk_nvme_detach_async(ctrlr_entry->ctrlr, &detach_ctx);
		free(ctrlr_entry);
	}

	if (detach_ctx) {
		|spdk_nvme_detach_poll(detach_ctx);
	}
}

static void
usage(const char *program_name)
{
	printf("%s [options]", program_name);
	printf("\t\n");
	printf("options:\n");
	printf("\t[-d DPDK huge memory size in MB]\n");
	printf("\t[-g use single file descriptor for DPDK memory segments]\n");
	printf("\t[-i shared memory group ID]\n");
	printf("\t[-r remote NVMe over Fabrics target address]\n");
	printf("\t[-V enumerate VMD]\n");
#ifdef DEBUG
	printf("\t[-L enable debug logging]\n");
#else
	printf("\t[-L enable debug logging (flag disabled, must reconfigure with --enable-debug)]\n");
#endif
}

static int
parse_args(int argc, char **argv, struct spdk_env_opts *env_opts)
{
	int op, rc;

	|spdk_nvme_trid_populate_transport(&g_trid, |spdk_nvme_TRANSPORT_PCIE);
	snprintf(g_trid.subnqn, sizeof(g_trid.subnqn), "%s", SPDK_NVMF_DISCOVERY_NQN);

	while ((op = getopt(argc, argv, "d:gi:r:L:V")) != -1) {
		switch (op) {
		case 'V':
			g_vmd = true;
			break;
		case 'i':
			env_opts->shm_id = spdk_strtol(optarg, 10);
			if (env_opts->shm_id < 0) {
				fprintf(stderr, "Invalid shared memory ID\n");
				return env_opts->shm_id;
			}
			break;
		case 'g':
			env_opts->hugepage_single_segments = true;
			break;
		case 'r':
			if (|spdk_nvme_transport_id_parse(&g_trid, optarg) != 0) {
				fprintf(stderr, "Error parsing transport address\n");
				return 1;
			}
			break;
		case 'd':
			env_opts->mem_size = spdk_strtol(optarg, 10);
			if (env_opts->mem_size < 0) {
				fprintf(stderr, "Invalid DPDK memory size\n");
				return env_opts->mem_size;
			}
			break;
		case 'L':
			rc = spdk_log_set_flag(optarg);
			if (rc < 0) {
				fprintf(stderr, "unknown flag\n");
				usage(argv[0]);
				exit(EXIT_FAILURE);
			}
#ifdef DEBUG
			spdk_log_set_print_level(SPDK_LOG_DEBUG);
#endif
			break;
		default:
			usage(argv[0]);
			return 1;
		}
	}

	return 0;
}

run hello_world

in build/example/ dir:

export LD_LIBRARY_PATH=./../lib:./../../dpdk/build/lib/$LD_LIBRARY_PATH

/spdk/build/examples$ ./hello_world -h
./hello_world: invalid option -- 'h'
./hello_world [options]
options:
        [-d DPDK huge memory size in MB]
        [-g use single file descriptor for DPDK memory segments]
        [-i shared memory group ID]
        [-r remote NVMe over Fabrics target address]
        [-V enumerate VMD]
        [-L enable debug logging (flag disabled, must reconfigure with --enable-debug)]

使用 Fio 插件运行基准测试

SPDK 为非常流行的fio工具提供了一个插件，用于运行一些基本的基准测试<link>

使用 Perf 工具运行基准测试

example/nvme/perf中的 NVMe perf 实用程序是也可用于性能测试的示例之一。fio工具因其非常灵活而被广泛使用。然而，这种灵活性增加了开销并降低了SPDK的效率。因此，
SPDK提供了一个性能基准测试工具，该工具在基准测试期间具有最小的开销。我们测量到，在4K 100%随机读取工作负载下使用perf与fio时，每个核心的IOPS提高了2.6倍。
perf 基准测试工具提供了多个运行时选项来支持最常见的工作负载。以下示例演示了如何使用 perf。
示例：使用 perf 对本地 NVMe SSD 进行 4K 100% 随机读取工作负载 300 秒

perf  -q 128 -o 4096 -w randread -r 'trtype:PCIe traddr:0000:04:00.0' -t 300

示例：使用 perf 将 4K 100% 随机读取工作负载传输到通过 NVMe-oF 通过网络导出的远程 NVMe SSD

perf -q 128 -o 4096 -w randread -r 'trtype:RDMA adrfam:IPv4 traddr:192.168.100.8 trsvcid:4420' -t 300

示例：使用 perf 对所有本地 NVMe SSD 执行 4K 70/30 随机读/写混合工作负载 300 秒

perf -q 128 -o 4096 -w randrw -M 70 -t 300

示例：使用 perf 对本地 NVMe SSD 进行扩展 LBA 格式 CRC 保护测试，用户必须先写入 SSD，然后再从 SSD 读取 LBA

perf -q 1 -o 4096 -w write -r 'trtype:PCIe traddr:0000:04:00.0' -t 300 -e 'PRACT=0，PRCKH=GUARD'
perf -q 1 -o 4096 -w 读 -r 'trtype:PCIe traddr:0000:04:00.0' -t 200 -e 'PRACT=0,PRCKH=GUARD'

Public Interface

spdk/nvme.h

Key Functions	Description
	spdk_nvme_probe()
spdk_nvme_ctrlr_alloc_io_qpair()	Allocate an I/O queue pair (submission and completion queue).
spdk_nvme_ctrlr_get_ns()	Get a handle to a namespace for the given controller.
spdk_nvme_ns_cmd_read()	Submits a read I/O to the specified NVMe namespace.
spdk_nvme_ns_cmd_readv()	Submit a read I/O to the specified NVMe namespace.
spdk_nvme_ns_cmd_read_with_md()	Submits a read I/O to the specified NVMe namespace.
spdk_nvme_ns_cmd_write()	Submit a write I/O to the specified NVMe namespace.
spdk_nvme_ns_cmd_writev()	Submit a write I/O to the specified NVMe namespace.
spdk_nvme_ns_cmd_write_with_md()	Submit a write I/O to the specified NVMe namespace.
spdk_nvme_ns_cmd_write_zeroes()	Submit a write zeroes I/O to the specified NVMe namespace.
spdk_nvme_ns_cmd_dataset_management()	Submit a data set management request to the specified NVMe namespace.
spdk_nvme_ns_cmd_flush()	Submit a flush request to the specified NVMe namespace.
spdk_nvme_qpair_process_completions()	Process any outstanding completions for I/O submitted on a queue pair.
spdk_nvme_ctrlr_cmd_admin_raw()	Send the given admin command to the NVMe controller.
spdk_nvme_ctrlr_process_admin_completions()	Process any outstanding completions for admin commands.
spdk_nvme_ctrlr_cmd_io_raw()	Send the given NVM I/O command to the NVMe controller.
spdk_nvme_ctrlr_cmd_io_raw_with_md()	Send the given NVM I/O command with metadata to the NVMe controller.

NVMe Driver Design

NVMe I/O 提交

使用 nvme_ns_cmd_xxx 函数将 I/O 提交到 NVMe 命名空间。NVMe 驱动程序将 I/O 请求作为命令中指定的队列对上的 NVMe 提交队列条目提交。该函数在命令完成之前立即返回。
应用程序必须轮询具有未完成 I/O 的每个队列对上的 I/O 完成情况，以通过调用spdk_nvme_qpair_process_completions()接收完成回调。

spdk_nvme_ns_cmd_read、
spdk_nvme_ns_cmd_write、
spdk_nvme_ns_cmd_dataset_management、
spdk_nvme_ns_cmd_flush、
spdk_nvme_qpair_process_completions

融合操作

要“融合”两个命令，第一个命令应设置 SPDK_NVME_IO_FLAGS_FUSE_FIRST io 标志，下一个命令应设置 SPDK_NVME_IO_FLAGS_FUSE_SECOND。

此外，要将两个命令作为一个原子单元执行，必须满足以下规则：

命令应相邻插入同一提交队列中。
两个命令的 LBA 范围应该相同。
例如，要发送融合的比较和写入操作，用户必须调用 spdk_nvme_ns_cmd_compare，然后调用 spdk_nvme_ns_cmd_write，并确保同一队列上没有其他操作提交，如下例所示：


rc = spdk_nvme_ns_cmd_compare(ns, qpair, cmp_buf, 0, 1, nvme_fused_first_cpl_cb,
                NULL, SPDK_NVME_CMD_FUSE_FIRST);
if (rc != 0) {
        ...
}
 
rc = spdk_nvme_ns_cmd_write(ns, qpair, write_buf, 0, 1, nvme_fused_second_cpl_cb,
                NULL, SPDK_NVME_CMD_FUSE_SECOND);
if (rc != 0) {
        ...
}

NVMe 规范当前将比较和写入定义为融合操作。对比较和写入的支持由控制器标志 SPDK_NVME_CTRLR_COMPARE_AND_WRITE_SUPPORTED 报告。

扩展性能

NVMe 队列对（struct spdk_nvme_qpair）为 I/O 提供并行提交路径。I/O 可以同时从不同线程提交到多个队列对上。然而，队列对不包含锁或原子，因此给定的队列对一次只能由单个线程使用。
NVMe 驱动程序不强制执行此要求（这样做需要锁定），违反此要求会导致未定义的行为。

允许的队列对数量由 NVMe SSD 本身决定。该规范允许数千个，但大多数设备支持 32 到 128 个。该规范不保证每个队列对的可用性能，但实际上，仅使用一个队列对几乎总是可以实现设备的全部性能。
例如，如果设备声称能够在队列深度 128 下每秒处理 450,000 个 I/O，则实际上，驱动程序使用 4 个队列对（每个队列对的队列深度为 32）或单个队列对（队列深度为 128）并不重要.

鉴于上述情况，使用 SPDK 的应用程序最简单的线程模型是在池中生成固定数量的线程，并为每个线程专用一个 NVMe 队列对。进一步的改进是将每个线程固定到一个单独的 CPU 核心，并且SPDK文档
通常会互换使用“CPU 核心”和“线程”，因为我们考虑到了这种线程模型。

NVMe 驱动程序在 I/O 路径中不加锁，因此只要队列对和 CPU 核心专用于每个新线程，它就会在每个线程的性能方面线性扩展。为了充分利用这种扩展，应用程序应该考虑组织其内部数据结构，以便将
数据专门分配给单个线程。所有需要数据的操作都应该通过向所属线程发送请求来完成。这会产生消息传递架构，而不是锁定架构，并将导致跨 CPU 内核的卓越扩展。

NVMe驱动程序内部存储器使用情况

SPDK NVMe驱动程序提供零复制数据传输路径，这意味着I/O命令没有数据缓冲区。但是，某些管理命令具有数据副本，具体取决于用户使用的API。

每个队列对都有许多跟踪器，用于跟踪调用者提交的命令。I/O 队列的数量跟踪器取决于用户输入的队列大小以及从控制器功能寄存器字段支持的最大队列条目（MQES，基于 0 的值）读取的值。每个跟踪器
的固定大小为 4096 字节，因此每个 I/O 队列使用的最大内存为：(MQES + 1) * 4 KiB。

I/O 队列对可以分配在主机内存中，这用于大多数 NVMe 控制器，一些支持控制器内存缓冲区的 NVMe 控制器可能会将 I/O 队列对放在控制器的 PCI BAR 空间，SPDK NVMe 驱动程序可以将 I/ O 提交队
列到控制器内存缓冲区，这取决于用户的输入和控制器的能力。每个提交队列条目（SQE）和完成队列条目（CQE）分别消耗64字节和16字节。因此，每个 I/O 队列对使用的最大内存为 (MQES + 1) * (64 + 16) 字节。

NVMe over Fabrics 主机支持

VMe 驱动程序支持连接到远程 NVMe-oF 目标并以与本地 NVMe SSD 相同的方式与它们交互。

指定远程 NVMe over Fabrics 目标

连接到远程 NVMe-oF 目标的方法与本地PCIe连接的NVMe设备的正常枚举过程非常相似。要连接到远程NVMe over Fabrics子系统，用户可以使用指定NVMe-oF目标地址的参数trid来调用spdk_nvme_probe() 。

调用者可以手动填写spdk_nvme_transport_id结构或使用spdk_nvme_transport_id_parse()函数将字符串表示形式转换为所需的结构。

spdk_nvme_transport_id可以包含发现服务或单个NVM子系统的地址。如果指定了发现服务地址，NVMe 库将为每个发现的NVM子系统调用 spdk_nvme_probe().probe_cb，这允许用户选择要附加
的所需子系统。或者，如果地址直接指定单个NVM子系统，则NVMe库将probe_cb仅调用该子系统；这允许用户跳过发现步骤并直接连接到具有已知地址的子系统。

RDMA Limitations

由于 RDMA NIC 对注册的内存区域数量进行了限制，因此 SPDK NVMe-oF 目标应用程序最终可能会开始无法分配更多支持 DMA 的内存。这是 DPDK 动态内存管理的缺陷，并且最有可能在运行时保留太多 2MB 大页面时发生。
一种类型的内存瓶颈是NIC内存区域的数量，例如，一些NIC报告内存区域的最大数量多达2048个。这给了我们 4GB 内存限制，总内存区域有 2MB 大页。可以通过使用 1GB 大页面或在应用程序启动时使用–mem-size或-s选
项预先保留内存来克服这个问题。所有预先保留的内存将被注册为单个区域，但在 SPDK 应用程序终止之前不会返回到系统。

在 RoCE 模式下使用 E810 NIC 时会出现另一个已知问题。具体来说，NVMe-oF 目标有时无法销毁 qpair，因为其发布的工作请求不会被刷新。它可能导致 NVMe-oF 目标应用程序无法干净终止。

NVMe 多进程

此功能使 SPDK NVMe 驱动程序能够支持访问同一 NVMe 设备的多个进程。NVMe 驱动程序从共享内存中分配关键结构，以便每个进程都可以映射该内存并创建自己的队列对或共享管理队列。每个 NVMe 控制器的 I/O 队列对数量有限。
此功能的主要动机是支持管理工具，这些工具可以附加到长时间运行的应用程序，执行一些维护工作或收集信息，然后分离

配置

DPDK EAL 允许生成不同类型的进程，每个进程对应用程序使用的大页内存具有不同的权限。

有两种类型的流程：
1. 初始化共享内存并拥有完全权限的主进程
2. 辅助进程，可以通过映射其共享内存区域来附加到主进程并执行 NVMe 操作，包括创建队列对。
该功能默认启用，并通过选择共享内存组ID的值来控制。该ID是正整数，具有相同共享内存组ID的两个应用程序将共享内存。具有给定共享内存组ID的第一个应用程序将被视为主要应用程序，所有其他应用程序将被视为次要应用程序。

示例：identical shm_id and non-overlapping core masks

./perf options [AIO device(s)]...
        [-c core mask for I/O submission/completion]
        [-i shared memory group ID]
 
./perf -q 1 -o 4096 -w randread -c 0x1 -t 60 -i 1
./perf -q 8 -o 131072 -w write -c 0x10 -t 60 -i 1

局限性

共享内存的两个进程可能不会共享其核心掩码中的任何核心。
如果主进程退出而辅助进程仍在运行，则这些进程将继续运行。但是，无法创建新的主进程。
应用程序负责协调对逻辑块的访问。
如果进程意外退出，则分配的内存将在最后一个进程退出时释放。

NVMe 热插拔

在 NVMe 驱动程序级别，我们为 Hotplug 提供以下支持：

热插拔事件检测：NVMe库的用户可以定期调用spdk_nvme_probe()来检测热插拔事件。对于检测到的每个新设备，将调用probe_cb，然后调用attach_cb。
用户还可以选择提供一个remove_cb，如果系统上不再存在先前连接的NVMe设备，将调用该remove_cb。对已删除设备的所有后续 I/O 将返回错误。
带 IO 负载的热移除 NVMe：当 I/O 发生时热移除设备时，对 PCI BAR 的所有访问都将导致 SIGBUS 错误。NVMe 驱动程序通过安装 SIGBUS 处理程序
并将 PCI BAR 重新映射到新的占位符内存位置来自动处理这种情况。这意味着热删除期间运行中的 I/O 将完成并带有适当的错误代码，并且不会使应用程序崩溃。

NVMe 字符设备

设计

请添加图片描述

对于每个控制器和命名空间，字符设备是在以下位置创建的：

/dev/spdk/nvmeX
/dev/spdk/nvmeXnY
...

其中 X 是唯一的 SPDK NVMe 控制器索引，Y 是命名空间 ID。

创建控制器和命名空间时，来自 CUSE 的请求由 pthread 处理。它们通过环将 I/O 或管理命令传递到使用 nvme_io_msg_process() 处理它们的线程。

连接 NVMe 控制器时请求获取信息的 Ioctl 会立即收到响应，而无需通过环传递它们。

该接口保留一个额外的 qpair，用于为每个控制器发送 I/O。

用法

启用 NVMe 的 cuse 支持

默认情况下禁用 Cuse 支持。要启用对 NVMe-CUSE 设备的支持，请首先安装所需的依赖项

sudo scripts/pkgdep.sh --fuse

Then compile SPDK with “./configure --with-nvme-cuse”.

创建 NVMe-CUSE 设备

首先确保准备好环境（请参阅入门）。这包括加载 CUSE 内核模块。连接到正在运行的 SPDK 应用程序的任何 NVMe 控制器都可以通过 NVMe-CUSE 接口公开。
关闭 SPDK 应用程序时，NVMe-CUSE 设备将被取消注册。

$ sudo scripts/setup.sh
$ sudo modprobe cuse
$ sudo build/bin/spdk_tgt
# Continue in another session
$ sudo scripts/rpc.py bdev_nvme_attach_controller -b Nvme0 -t PCIe -a 0000:82:00.0
Nvme0n1
$ sudo scripts/rpc.py bdev_nvme_get_controllers
[
  {
    "name": "Nvme0",
    "trid": {
      "trtype": "PCIe",
      "traddr": "0000:82:00.0"
    }
  }
]
$ sudo scripts/rpc.py bdev_nvme_cuse_register -n Nvme0
$ ls /dev/spdk/
nvme0  nvme0n1

Example of using nvme-cli

大多数 nvme-cli 命令可以通过提供路径来指向特定的控制器或命名空间。可以利用它向 SPDK NVMe-CUSE 设备发出命令。

sudo nvme id-ctrl /dev/spdk/nvme0
sudo nvme smart-log /dev/spdk/nvme0
sudo nvme id-ns /dev/spdk/nvme0n1

注意：nvme list命令不显示 SPDK NVMe-CUSE 设备，请参阅 nvme-cli PR #773

使用 smartctl 的示例

smartctl 工具根据设备路径识别设备类型。如果没有任何预期模式匹配，则使用 SCSI 转换层来识别设备。

要使用 smartctl，除了 NVMe 设备的完整路径之外，还必须使用“-d nvme”参数。

smartctl -d nvme -i /dev/spdk/nvme0
smartctl -d nvme -H /dev/spdk/nvme1
...

局限性

NVMe 命名空间被创建为字符设备，其使用可能仅限于需要块设备的工具。

Sysfs 不由 SPDK 更新。

SPDK NVMe CUSE 在“/dev/spdk/”目录中创建节点以明确区别于其他设备。仅在“/dev”目录中搜索的工具可能不适用于 SPDK NVMe CUSE。

未实现 SCSI 到 NVMe 转换层。使用此层来识别、管理或操作设备的工具可能无法正常工作或其使用可能受到限制。

NVMe LED 管理

即使 NVMe 设备由 SPDK 控制，也可以使用 ledctl(8) 实用程序来控制支持 NPEM（本机 PCIe 机箱管理）的系统中 LED 的状态。然而，在这
种情况下，由于块设备不可用，因此需要确定槽设备号。ledctl.sh脚本可用于帮助解决此问题。它采用 nvme bdev 的名称并使用适当的选项调用 ledctl。