From 1e1fd9ac219da3e52bc166c9d2bb2376c62c113d Mon Sep 17 00:00:00 2001 From: wawryk Date: Mon, 2 Aug 2021 14:27:54 +0200 Subject: [PATCH] markdownlint: enable rule MD025 MD025 - Multiple top level headers in the same document Fixed all errors Update check_format.sh to fit new header style in jsonrpc.md Signed-off-by: Maciej Wawryk Change-Id: Ib5f832c549880771c99c15b89affe1e82acd3fa4 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/9045 Reviewed-by: Tomasz Zawadzki Reviewed-by: Jim Harris Reviewed-by: Ben Walker Community-CI: Broadcom CI Community-CI: Mellanox Build Bot Tested-by: SPDK CI Jenkins --- README.md | 2 +- deprecation.md | 8 +- doc/README.md | 6 +- doc/accel_fw.md | 16 +- doc/bdev.md | 58 +- doc/blob.md | 2 +- doc/blobfs.md | 8 +- doc/concurrency.md | 8 +- doc/containers.md | 6 +- doc/event.md | 14 +- doc/ftl.md | 18 +- doc/gdb_macros.md | 14 +- doc/getting_started.md | 10 +- doc/idxd.md | 6 +- doc/index.md | 20 +- doc/ioat.md | 4 +- doc/iscsi.md | 6 +- doc/jsonrpc.md | 1346 ++++++++++++++-------------- doc/libraries.md | 24 +- doc/lvol.md | 20 +- doc/memory.md | 2 +- doc/notify.md | 10 +- doc/nvme.md | 54 +- doc/nvmf.md | 2 +- doc/nvmf_tracing.md | 10 +- doc/overview.md | 2 +- doc/peer_2_peer.md | 12 +- doc/rpm.md | 4 +- doc/shfmt.md | 10 +- doc/spdk_top.md | 12 +- doc/system_configuration.md | 14 +- doc/template_pg.md | 2 +- doc/userspace.md | 6 +- doc/vagrant.md | 6 +- doc/vhost.md | 50 +- doc/vhost_processing.md | 12 +- doc/virtio.md | 4 +- doc/vmd.md | 16 +- examples/bdev/fio_plugin/README.md | 14 +- examples/nvme/fio_plugin/README.md | 22 +- mdl_rules.rb | 1 - scripts/check_format.sh | 2 +- test/app/fuzz/iscsi_fuzz/README.md | 4 +- test/app/fuzz/nvme_fuzz/README.md | 6 +- test/app/fuzz/vhost_fuzz/README.md | 4 +- 45 files changed, 939 insertions(+), 938 deletions(-) diff --git a/README.md b/README.md index 10499a761..ceedc7307 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ The development kit currently includes: * [vhost target](http://www.spdk.io/doc/vhost.html) * [Virtio-SCSI driver](http://www.spdk.io/doc/virtio.html) -# In this readme +## In this readme * [Documentation](#documentation) * [Prerequisites](#prerequisites) diff --git a/deprecation.md b/deprecation.md index 72e9b1cad..47e4d475c 100644 --- a/deprecation.md +++ b/deprecation.md @@ -1,4 +1,6 @@ -# ABI and API Deprecation {#deprecation} +# Deprecation + +## ABI and API Deprecation {#deprecation} This document details the policy for maintaining stability of SPDK ABI and API. @@ -10,9 +12,9 @@ Each entry must describe what will be removed and can suggest the future use or Specific future SPDK release for the removal must be provided. ABI cannot be removed without providing deprecation notice for at least single SPDK release. -# Deprecation Notices {#deprecation-notices} +## Deprecation Notices {#deprecation-notices} -## bdev +### bdev Deprecated `spdk_bdev_module_finish_done()` API, which will be removed in SPDK 22.01. Bdev modules should use `spdk_bdev_module_fini_done()` instead. diff --git a/doc/README.md b/doc/README.md index c5c03b287..acd12908f 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,11 +1,9 @@ -SPDK Documentation -================== +# SPDK Documentation The current version of the SPDK documentation can be found online at http://www.spdk.io/doc/ -Building the Documentation -========================== +## Building the Documentation To convert the documentation into HTML run `make` in the `doc` directory. The output will be located in `doc/output/html`. Before diff --git a/doc/accel_fw.md b/doc/accel_fw.md index 3decb9936..5af91dbc5 100644 --- a/doc/accel_fw.md +++ b/doc/accel_fw.md @@ -15,12 +15,12 @@ For the software module, all capabilities will be reported as supported. For the accelerated by hardware will be reported however any function can still be called, it will just be backed by software if it is not reported as a supported capability. -# Acceleration Framework Functions {#accel_functions} +## Acceleration Framework Functions {#accel_functions} Functions implemented via the framework can be found in the DoxyGen documentation of the framework public header file here [accel_engine.h](https://spdk.io/doc/accel__engine_8h.html) -# Acceleration Framework Design Considerations {#accel_dc} +## Acceleration Framework Design Considerations {#accel_dc} The general interface is defined by `/include/accel_engine.h` and implemented in `/lib/accel`. These functions may be called by an SPDK application and in @@ -35,7 +35,7 @@ optimized implementation. For example, IOAT does not support the dualcast funct in hardware but if the IOAT module has been initialized and the public dualcast API is called, it will actually be done via software behind the scenes. -# Acceleration Low Level Libraries {#accel_libs} +## Acceleration Low Level Libraries {#accel_libs} Low level libraries provide only the most basic functions that are specific to the hardware. Low level libraries are located in the '/lib' directory with the @@ -51,7 +51,7 @@ way needs to be certain that the underlying hardware exists everywhere that it r The low level library for IOAT is located in `/lib/ioat`. The low level library for DSA is in `/liv/idxd` (IDXD stands for Intel(R) Data Acceleration Driver). -# Acceleration Plug-In Modules {#accel_modules} +## Acceleration Plug-In Modules {#accel_modules} Plug-in modules depend on low level libraries to interact with the hardware and add additional functionality such as queueing during busy conditions or flow @@ -60,11 +60,11 @@ the complete implementation of the acceleration component. A module must be selected via startup RPC when the application is started. Otherwise, if no startup RPC is provided, the framework is available and will use the software plug-in module. -## IOAT Module {#accel_ioat} +### IOAT Module {#accel_ioat} To use the IOAT engine, use the RPC [`ioat_scan_accel_engine`](https://spdk.io/doc/jsonrpc.html) before starting the application. -## IDXD Module {#accel_idxd} +### IDXD Module {#accel_idxd} To use the DSA engine, use the RPC [`idxd_scan_accel_engine`](https://spdk.io/doc/jsonrpc.html) with an optional parameter of `-c` and provide a configuration number of either 0 or 1. These pre-defined configurations determine how the DSA engine @@ -86,14 +86,14 @@ of service parameters on the work queues that are not currently utilized by the module. Specialized use of DSA may require different configurations that can be added to the module as needed. -## Software Module {#accel_sw} +### Software Module {#accel_sw} The software module is enabled by default. If no hardware engine is explicitly enabled via startup RPC as discussed earlier, the software module will use ISA-L if available for functions such as CRC32C. Otherwise, standard glibc calls are used to back the framework API. -## Batching {#batching} +### Batching {#batching} Batching is exposed by the acceleration framework and provides an interface to batch sets of commands up and then submit them with a single command. The public diff --git a/doc/bdev.md b/doc/bdev.md index a7ccb92f2..a7e38c6cb 100644 --- a/doc/bdev.md +++ b/doc/bdev.md @@ -1,11 +1,11 @@ # Block Device User Guide {#bdev} -# Target Audience {#bdev_ug_targetaudience} +## Target Audience {#bdev_ug_targetaudience} This user guide is intended for software developers who have knowledge of block storage, storage drivers, issuing JSON-RPC commands and storage services such as RAID, compression, crypto, and others. -# Introduction {#bdev_ug_introduction} +## Introduction {#bdev_ug_introduction} 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 @@ -27,7 +27,7 @@ device underneath (please refer to @ref bdev_module for details). SPDK provides also vbdev modules which creates block devices on existing bdev. For example @ref bdev_ug_logical_volumes or @ref bdev_ug_gpt -# Prerequisites {#bdev_ug_prerequisites} +## Prerequisites {#bdev_ug_prerequisites} This guide assumes that you can already build the standard SPDK distribution on your platform. The block device layer is a C library with a single public @@ -40,14 +40,14 @@ directly from SPDK application by running `scripts/rpc.py rpc_get_methods`. Detailed help for each command can be displayed by adding `-h` flag as a command parameter. -# Configuring Block Device Modules {#bdev_ug_general_rpcs} +## Configuring Block Device Modules {#bdev_ug_general_rpcs} Block devices can be configured using JSON RPCs. A complete list of available RPC commands with detailed information can be found on the @ref jsonrpc_components_bdev page. -# Common Block Device Configuration Examples +## Common Block Device Configuration Examples -# Ceph RBD {#bdev_config_rbd} +## Ceph RBD {#bdev_config_rbd} The SPDK RBD bdev driver provides SPDK block layer access to Ceph RADOS block devices (RBD). Ceph RBD devices are accessed via librbd and librados libraries @@ -70,7 +70,7 @@ To resize a bdev use the bdev_rbd_resize command. This command will resize the Rbd0 bdev to 4096 MiB. -# Compression Virtual Bdev Module {#bdev_config_compress} +## Compression Virtual Bdev Module {#bdev_config_compress} The compression bdev module can be configured to provide compression/decompression services for an underlying thinly provisioned logical volume. Although the underlying @@ -134,7 +134,7 @@ all volumes, if used it will return the name or an error that the device does no `rpc.py bdev_compress_get_orphans --name COMP_Nvme0n1` -# Crypto Virtual Bdev Module {#bdev_config_crypto} +## Crypto Virtual Bdev Module {#bdev_config_crypto} The crypto virtual bdev module can be configured to provide at rest data encryption for any underlying bdev. The module relies on the DPDK CryptoDev Framework to provide @@ -171,7 +171,7 @@ To remove the vbdev use the bdev_crypto_delete command. `rpc.py bdev_crypto_delete CryNvmeA` -# Delay Bdev Module {#bdev_config_delay} +## Delay Bdev Module {#bdev_config_delay} The delay vbdev module is intended to apply a predetermined additional latency on top of a lower level bdev. This enables the simulation of the latency characteristics of a device during the functional @@ -202,13 +202,13 @@ Example command: `rpc.py bdev_delay_delete delay0` -# GPT (GUID Partition Table) {#bdev_config_gpt} +## GPT (GUID Partition Table) {#bdev_config_gpt} The GPT virtual bdev driver is enabled by default and does not require any configuration. It will automatically detect @ref bdev_ug_gpt on any attached bdev and will create possibly multiple virtual bdevs. -## SPDK GPT partition table {#bdev_ug_gpt} +### SPDK GPT partition table {#bdev_ug_gpt} The SPDK partition type GUID is `7c5222bd-8f5d-4087-9c00-bf9843c7b58c`. Existing SPDK bdevs can be exposed as Linux block devices via NBD and then can be partitioned with @@ -234,7 +234,7 @@ Example command `rpc.py nbd_stop_disk -n /dev/nbd0` -## Creating a GPT partition table using NBD {#bdev_ug_gpt_create_part} +### Creating a GPT partition table using NBD {#bdev_ug_gpt_create_part} ~~~ # Expose bdev Nvme0n1 as kernel block device /dev/nbd0 by JSON-RPC @@ -258,7 +258,7 @@ rpc.py nbd_stop_disk /dev/nbd0 # Nvme0n1p1 in SPDK applications. ~~~ -# iSCSI bdev {#bdev_config_iscsi} +## iSCSI bdev {#bdev_config_iscsi} The SPDK iSCSI bdev driver depends on libiscsi and hence is not enabled by default. In order to use it, build SPDK with an extra `--with-iscsi-initiator` configure option. @@ -271,7 +271,7 @@ with `iqn.2016-06.io.spdk:init` as the reported initiator IQN. The URL is in the following format: `iscsi://[[%]@][:]//` -# Linux AIO bdev {#bdev_config_aio} +## Linux AIO bdev {#bdev_config_aio} The SPDK AIO bdev driver provides SPDK block layer access to Linux kernel block devices or a file on a Linux filesystem via Linux AIO. Note that O_DIRECT is @@ -294,7 +294,7 @@ To delete an aio bdev use the bdev_aio_delete command. `rpc.py bdev_aio_delete aio0` -# OCF Virtual bdev {#bdev_config_cas} +## OCF Virtual bdev {#bdev_config_cas} OCF virtual bdev module is based on [Open CAS Framework](https://github.com/Open-CAS/ocf) - a high performance block storage caching meta-library. @@ -321,7 +321,7 @@ During removal OCF-cache will be stopped and all cached data will be written to Note that OCF has a per-device RAM requirement. More details can be found in the [OCF documentation](https://open-cas.github.io/guide_system_requirements.html). -# Malloc bdev {#bdev_config_malloc} +## Malloc bdev {#bdev_config_malloc} Malloc bdevs are ramdisks. Because of its nature they are volatile. They are created from hugepage memory given to SPDK application. @@ -334,7 +334,7 @@ Example command for removing malloc bdev: `rpc.py bdev_malloc_delete Malloc0` -# Null {#bdev_config_null} +## Null {#bdev_config_null} The SPDK null bdev driver is a dummy block I/O target that discards all writes and returns undefined data for reads. It is useful for benchmarking the rest of the bdev I/O stack with minimal block @@ -351,7 +351,7 @@ To delete a null bdev use the bdev_null_delete command. `rpc.py bdev_null_delete Null0` -# NVMe bdev {#bdev_config_nvme} +## NVMe bdev {#bdev_config_nvme} There are two ways to create block device based on NVMe device in SPDK. First way is to connect local PCIe drive and second one is to connect NVMe-oF device. @@ -373,7 +373,7 @@ To remove an NVMe controller use the bdev_nvme_detach_controller command. This command will remove NVMe bdev named Nvme0. -## NVMe bdev character device {#bdev_config_nvme_cuse} +### NVMe bdev character device {#bdev_config_nvme_cuse} This feature is considered as experimental. You must configure with --with-nvme-cuse option to enable this RPC. @@ -397,14 +397,14 @@ with command: `rpc.py bdev_nvme_cuse_unregister -n Nvme0` -# Logical volumes {#bdev_ug_logical_volumes} +## Logical volumes {#bdev_ug_logical_volumes} The Logical Volumes library is a flexible storage space management system. It allows creating and managing virtual block devices with variable size on top of other bdevs. The SPDK Logical Volume library is built on top of @ref blob. For detailed description please refer to @ref lvol. -## Logical volume store {#bdev_ug_lvol_store} +### Logical volume store {#bdev_ug_lvol_store} Before creating any logical volumes (lvols), an lvol store has to be created first on selected block device. Lvol store is lvols vessel responsible for managing underlying @@ -443,7 +443,7 @@ Example commands `rpc.py bdev_lvol_delete_lvstore -l lvs` -## Lvols {#bdev_ug_lvols} +### Lvols {#bdev_ug_lvols} To create lvols on existing lvol store user should use `bdev_lvol_create` RPC command. Each created lvol will be represented by new bdev. @@ -454,7 +454,7 @@ Example commands `rpc.py bdev_lvol_create lvol2 25 -u 330a6ab2-f468-11e7-983e-001e67edf35d` -# Passthru {#bdev_config_passthru} +## Passthru {#bdev_config_passthru} The SPDK Passthru virtual block device module serves as an example of how to write a virtual block device module. It implements the required functionality of a vbdev module @@ -466,7 +466,7 @@ Example commands `rpc.py bdev_passthru_delete pt` -# Pmem {#bdev_config_pmem} +## Pmem {#bdev_config_pmem} The SPDK pmem bdev driver uses pmemblk pool as the target for block I/O operations. For details on Pmem memory please refer to PMDK documentation on http://pmem.io website. @@ -503,7 +503,7 @@ To remove a block device representation use the bdev_pmem_delete command. `rpc.py bdev_pmem_delete pmem` -# RAID {#bdev_ug_raid} +## RAID {#bdev_ug_raid} RAID virtual bdev module provides functionality to combine any SPDK bdevs into one RAID bdev. Currently SPDK supports only RAID 0. RAID functionality does not @@ -523,7 +523,7 @@ Example commands `rpc.py bdev_raid_delete Raid0` -# Split {#bdev_ug_split} +## Split {#bdev_ug_split} The split block device module takes an underlying block device and splits it into several smaller equal-sized virtual block devices. This serves as an example to create @@ -545,7 +545,7 @@ To remove the split bdevs, use the `bdev_split_delete` command with th `rpc.py bdev_split_delete bdev_b0` -# Uring {#bdev_ug_uring} +## Uring {#bdev_ug_uring} The uring bdev module issues I/O to kernel block devices using the io_uring Linux kernel API. This module requires liburing. For more information on io_uring refer to kernel [IO_uring] (https://kernel.dk/io_uring.pdf) @@ -562,7 +562,7 @@ To remove a uring bdev use the `bdev_uring_delete` RPC. `rpc.py bdev_uring_delete bdev_u0` -# Virtio Block {#bdev_config_virtio_blk} +## Virtio Block {#bdev_config_virtio_blk} The Virtio-Block driver allows creating SPDK bdevs from Virtio-Block devices. @@ -583,7 +583,7 @@ Virtio-Block devices can be removed with the following command `rpc.py bdev_virtio_detach_controller VirtioBlk0` -# Virtio SCSI {#bdev_config_virtio_scsi} +## Virtio SCSI {#bdev_config_virtio_scsi} The Virtio-SCSI driver allows creating SPDK block devices from Virtio-SCSI LUNs. diff --git a/doc/blob.md b/doc/blob.md index c7949e193..88293e159 100644 --- a/doc/blob.md +++ b/doc/blob.md @@ -1,6 +1,6 @@ # Blobstore Programmer's Guide {#blob} -# In this document {#blob_pg_toc} +## In this document {#blob_pg_toc} * @ref blob_pg_audience * @ref blob_pg_intro diff --git a/doc/blobfs.md b/doc/blobfs.md index c20c18827..f630f094c 100644 --- a/doc/blobfs.md +++ b/doc/blobfs.md @@ -1,8 +1,8 @@ # BlobFS (Blobstore Filesystem) {#blobfs} -# BlobFS Getting Started Guide {#blobfs_getting_started} +## BlobFS Getting Started Guide {#blobfs_getting_started} -# RocksDB Integration {#blobfs_rocksdb} +## RocksDB Integration {#blobfs_rocksdb} Clone and build the SPDK repository as per https://github.com/spdk/spdk @@ -68,7 +68,7 @@ At this point, RocksDB is ready for testing with SPDK. Three `db_bench` paramet SPDK has a set of scripts which will run `db_bench` against a variety of workloads and capture performance and profiling data. The primary script is `test/blobfs/rocksdb/rocksdb.sh`. -# FUSE +## FUSE BlobFS provides a FUSE plug-in to mount an SPDK BlobFS as a kernel filesystem for inspection or debug purposes. The FUSE plug-in requires fuse3 and will be built automatically when fuse3 is detected on the system. @@ -79,7 +79,7 @@ test/blobfs/fuse/fuse /usr/local/etc/spdk/rocksdb.json Nvme0n1 /mnt/fuse Note that the FUSE plug-in has some limitations - see the list below. -# Limitations +## Limitations * BlobFS has primarily been tested with RocksDB so far, so any use cases different from how RocksDB uses a filesystem may run into issues. BlobFS will be tested in a broader range of use cases after this initial release. diff --git a/doc/concurrency.md b/doc/concurrency.md index 47009e85d..3f734ae83 100644 --- a/doc/concurrency.md +++ b/doc/concurrency.md @@ -1,6 +1,6 @@ # Message Passing and Concurrency {#concurrency} -# Theory +## Theory One of the primary aims of SPDK is to scale linearly with the addition of hardware. This can mean many things in practice. For instance, moving from one @@ -56,7 +56,7 @@ data isn't mutated very often, but is read very frequently, and is often employed in the I/O path. This of course trades memory size for computational efficiency, so it is used in only the most critical code paths. -# Message Passing Infrastructure +## Message Passing Infrastructure SPDK provides several layers of message passing infrastructure. The most fundamental libraries in SPDK, for instance, don't do any message passing on @@ -110,7 +110,7 @@ repeatedly call `spdk_thread_poll()` on each `spdk_thread()` that exists. This makes SPDK very portable to a wide variety of asynchronous, event-based frameworks such as [Seastar](https://www.seastar.io) or [libuv](https://libuv.org/). -# The event Framework +## The event Framework The SPDK project didn't want to officially pick an asynchronous, event-based framework for all of the example applications it shipped with, in the interest @@ -122,7 +122,7 @@ signal handlers to cleanly shutdown, and basic command line option parsing. Only established applications should consider directly integrating the lower level libraries. -# Limitations of the C Language +## Limitations of the C Language Message passing is efficient, but it results in asynchronous code. Unfortunately, asynchronous code is a challenge in C. It's often implemented by diff --git a/doc/containers.md b/doc/containers.md index 756b5728a..7fd787587 100644 --- a/doc/containers.md +++ b/doc/containers.md @@ -4,12 +4,12 @@ This is a living document as there are many ways to use containers with SPDK. As new usages are identified and tested, they will be documented here. -# In this document {#containers_toc} +## In this document {#containers_toc} * @ref kata_containers_with_spdk_vhost * @ref spdk_in_docker -# Using SPDK vhost target to provide volume service to Kata Containers and Docker {#kata_containers_with_spdk_vhost} +## Using SPDK vhost target to provide volume service to Kata Containers and Docker {#kata_containers_with_spdk_vhost} [Kata Containers](https://katacontainers.io) can build a secure container runtime with lightweight virtual machines that feel and perform like @@ -23,7 +23,7 @@ In addition, a container manager like Docker, can be configured easily to launch a Kata container with an SPDK vhost-user block device. For operating details, visit Kata containers use-case [Setup to run SPDK vhost-user devices with Kata Containers and Docker](https://github.com/kata-containers/documentation/blob/master/use-cases/using-SPDK-vhostuser-and-kata.md#host-setup-for-vhost-user-devices) -# Containerizing an SPDK Application for Docker {#spdk_in_docker} +## Containerizing an SPDK Application for Docker {#spdk_in_docker} There are no SPDK specific changes needed to run an SPDK based application in a docker container, however this quick start guide should help you as you diff --git a/doc/event.md b/doc/event.md index c0eb975e3..41140d2b2 100644 --- a/doc/event.md +++ b/doc/event.md @@ -14,7 +14,7 @@ concurrency. The event framework public interface is defined in event.h. -# Event Framework Design Considerations {#event_design} +## Event Framework Design Considerations {#event_design} Simple server applications can be written in a single-threaded fashion. This allows for straightforward code that can maintain state without any locking or @@ -27,9 +27,9 @@ synchronization. Unfortunately, in many real-world cases, the connections are not entirely independent and cross-thread shared state is necessary. SPDK provides an event framework to help solve this problem. -# SPDK Event Framework Components {#event_components} +## SPDK Event Framework Components {#event_components} -## Events {#event_component_events} +### Events {#event_component_events} To accomplish cross-thread communication while minimizing synchronization overhead, the framework provides message passing in the form of events. The @@ -45,7 +45,7 @@ asynchronous operations to achieve concurrency. Asynchronous I/O may be issued with a non-blocking function call, and completion is typically signaled using a callback function. -## Reactors {#event_component_reactors} +### Reactors {#event_component_reactors} Each reactor has a lock-free queue for incoming events to that core, and threads from any core may insert events into the queue of any other core. The @@ -54,7 +54,7 @@ in first-in, first-out order as they are received. Event functions should never block and should preferably execute very quickly, since they are called directly from the event loop on the destination core. -## Pollers {#event_component_pollers} +### Pollers {#event_component_pollers} The framework also defines another type of function called a poller. Pollers may be registered with the spdk_poller_register() function. Pollers, like @@ -66,7 +66,7 @@ intended to poll hardware as a replacement for interrupts. Normally, pollers are executed on every iteration of the main event loop. Pollers may also be scheduled to execute periodically on a timer if low latency is not required. -## Application Framework {#event_component_app} +### Application Framework {#event_component_app} The framework itself is bundled into a higher level abstraction called an "app". Once spdk_app_start() is called, it will block the current thread until the application @@ -74,7 +74,7 @@ terminates by calling spdk_app_stop() or an error condition occurs during the initialization code within spdk_app_start(), itself, before invoking the caller's supplied function. -## Custom shutdown callback {#event_component_shutdown} +### Custom shutdown callback {#event_component_shutdown} When creating SPDK based application user may add custom shutdown callback which will be called before the application framework starts the shutdown process. diff --git a/doc/ftl.md b/doc/ftl.md index 955ccf592..4bcb6efaa 100644 --- a/doc/ftl.md +++ b/doc/ftl.md @@ -5,9 +5,9 @@ implementing bdev_zone interface. It handles the logical to physical address mapping, responds to the asynchronous media management events, and manages the defragmentation process. -# Terminology {#ftl_terminology} +## Terminology {#ftl_terminology} -## Logical to physical address map +### Logical to physical address map - Shorthand: L2P @@ -17,7 +17,7 @@ are calculated during device formation and are subtracted from the available add spare blocks account for zones going offline throughout the lifespan of the device as well as provide necessary buffer for data [defragmentation](#ftl_reloc). -## Band {#ftl_band} +### Band {#ftl_band} A band describes a collection of zones, each belonging to a different parallel unit. All writes to a band follow the same pattern - a batch of logical blocks is written to one zone, another batch @@ -64,7 +64,7 @@ is being written. Then the band moves to the `OPEN` state and actual user data c band. Once the whole available space is filled, tail metadata is written and the band transitions to `CLOSING` state. When that finishes the band becomes `CLOSED`. -## Ring write buffer {#ftl_rwb} +### Ring write buffer {#ftl_rwb} - Shorthand: RWB @@ -97,7 +97,7 @@ After that operation is completed the whole batch can be freed. For the whole ti the `rwb`, the L2P points at the buffer entry instead of a location on the SSD. This allows for servicing read requests from the buffer. -## Defragmentation and relocation {#ftl_reloc} +### Defragmentation and relocation {#ftl_reloc} - Shorthand: defrag, reloc @@ -133,14 +133,14 @@ index of its zones (3) (how many times the band was written to). The lower the r higher its age (2) and the lower its write count (3), the higher the chance the band will be chosen for defrag. -# Usage {#ftl_usage} +## Usage {#ftl_usage} -## Prerequisites {#ftl_prereq} +### Prerequisites {#ftl_prereq} In order to use the FTL module, a device capable of zoned interface is required e.g. `zone_block` bdev or OCSSD `nvme` bdev. -## FTL bdev creation {#ftl_create} +### FTL bdev creation {#ftl_create} Similar to other bdevs, the FTL bdevs can be created either based on JSON config files or via RPC. Both interfaces require the same arguments which are described by the `--help` option of the @@ -150,7 +150,7 @@ Both interfaces require the same arguments which are described by the `--help` o - base bdev's name (base bdev must implement bdev_zone API) - UUID of the FTL device (if the FTL is to be restored from the SSD) -## FTL usage with OCSSD nvme bdev {#ftl_ocssd} +### FTL usage with OCSSD nvme bdev {#ftl_ocssd} This option requires an Open Channel SSD, which can be emulated using QEMU. diff --git a/doc/gdb_macros.md b/doc/gdb_macros.md index 6fc65aed7..fe61d5fd4 100644 --- a/doc/gdb_macros.md +++ b/doc/gdb_macros.md @@ -1,6 +1,6 @@ # GDB Macros User Guide {#gdb_macros} -# Introduction +## Introduction When debugging an spdk application using gdb we may need to view data structures in lists, e.g. information about bdevs or threads. @@ -125,7 +125,7 @@ nqn "nqn.2016-06.io.spdk.umgmt:cnode1", '\000' ID 1 ~~~ -# Loading The gdb Macros +## Loading The gdb Macros Copy the gdb macros to the host where you are about to debug. It is best to copy the file either to somewhere within the PYTHONPATH, or to add @@ -146,7 +146,7 @@ the PYTHONPATH, so I had to manually add the directory to the path. (gdb) spdk_load_macros ~~~ -# Using the gdb Data Directory +## Using the gdb Data Directory On most systems, the data directory is /usr/share/gdb. The python script should be copied into the python/gdb/function (or python/gdb/command) directory under @@ -155,7 +155,7 @@ the data directory, e.g. /usr/share/gdb/python/gdb/function. If the python script is in there, then the only thing you need to do when starting gdb is type "spdk_load_macros". -# Using .gdbinit To Load The Macros +## Using .gdbinit To Load The Macros .gdbinit can also be used in order to run automatically run the manual steps above prior to starting gdb. @@ -168,7 +168,7 @@ source /opt/km/install/tools/gdb_macros/gdb_macros.py When starting gdb you still have to call spdk_load_macros. -# Why Do We Need to Explicitly Call spdk_load_macros +## Why Do We Need to Explicitly Call spdk_load_macros The reason is that the macros need to use globals provided by spdk in order to iterate the spdk lists and build iterable representations of the list objects. @@ -196,7 +196,7 @@ Error occurred in Python command: No symbol table is loaded. Use the "file" command. ~~~ -# Macros available +## Macros available - spdk_load_macros: load the macros (use --reload in order to reload them) - spdk_print_bdevs: information about bdevs @@ -205,7 +205,7 @@ command. - spdk_print_nvmf_subsystems: information about nvmf subsystems - spdk_print_threads: information about threads -# Adding New Macros +## Adding New Macros The list iteration macros are usually built from 3 layers: diff --git a/doc/getting_started.md b/doc/getting_started.md index 7dadaae20..980b2e9eb 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -1,6 +1,6 @@ # Getting Started {#getting_started} -# Getting the Source Code {#getting_started_source} +## Getting the Source Code {#getting_started_source} ~~~{.sh} git clone https://github.com/spdk/spdk @@ -8,7 +8,7 @@ cd spdk git submodule update --init ~~~ -# Installing Prerequisites {#getting_started_prerequisites} +## Installing Prerequisites {#getting_started_prerequisites} The `scripts/pkgdep.sh` script will automatically install the bare minimum dependencies required to build SPDK. @@ -24,7 +24,7 @@ Option --all will install all dependencies needed by SPDK features. sudo scripts/pkgdep.sh --all ~~~ -# Building {#getting_started_building} +## Building {#getting_started_building} Linux: @@ -57,7 +57,7 @@ can enable it by doing the following: make ~~~ -# Running the Unit Tests {#getting_started_unittests} +## Running the Unit Tests {#getting_started_unittests} It's always a good idea to confirm your build worked by running the unit tests. @@ -70,7 +70,7 @@ You will see several error messages when running the unit tests, but they are part of the test suite. The final message at the end of the script indicates success or failure. -# Running the Example Applications {#getting_started_examples} +## Running the Example Applications {#getting_started_examples} Before running an SPDK application, some hugepages must be allocated and any NVMe and I/OAT devices must be unbound from the native kernel drivers. diff --git a/doc/idxd.md b/doc/idxd.md index 8c33770ef..9a688caed 100644 --- a/doc/idxd.md +++ b/doc/idxd.md @@ -1,10 +1,10 @@ # IDXD Driver {#idxd} -# Public Interface {#idxd_interface} +## Public Interface {#idxd_interface} - spdk/idxd.h -# Key Functions {#idxd_key_functions} +## Key Functions {#idxd_key_functions} Function | Description --------------------------------------- | ----------- @@ -19,7 +19,7 @@ spdk_idxd_submit_crc32c() | @copybrief spdk_idxd_submit_crc32c() spdk_idxd_submit_dualcast | @copybrief spdk_idxd_submit_dualcast() spdk_idxd_submit_fill() | @copybrief spdk_idxd_submit_fill() -# Pre-defined configurations {#idxd_configs} +## Pre-defined configurations {#idxd_configs} The RPC `idxd_scan_accel_engine` is used to both enable IDXD and set it's configuration to one of two pre-defined configs: diff --git a/doc/index.md b/doc/index.md index fd81b0fd9..4b9156051 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,41 +1,41 @@ # Storage Performance Development Kit {#mainpage} -# Introduction +## Introduction @copydoc intro -# Concepts +## Concepts @copydoc concepts -# User Guides +## User Guides @copydoc user_guides -# Programmer Guides +## Programmer Guides @copydoc prog_guides -# General Information +## General Information @copydoc general -# Miscellaneous +## Miscellaneous @copydoc misc -# Driver Modules +## Driver Modules @copydoc driver_modules -# Tools +## Tools @copydoc tools -# CI Tools +## CI Tools @copydoc ci_tools -# Performance Reports +## Performance Reports @copydoc performance_reports diff --git a/doc/ioat.md b/doc/ioat.md index 1eb4a27f7..8585002c1 100644 --- a/doc/ioat.md +++ b/doc/ioat.md @@ -1,10 +1,10 @@ # I/OAT Driver {#ioat} -# Public Interface {#ioat_interface} +## Public Interface {#ioat_interface} - spdk/ioat.h -# Key Functions {#ioat_key_functions} +## Key Functions {#ioat_key_functions} Function | Description --------------------------------------- | ----------- diff --git a/doc/iscsi.md b/doc/iscsi.md index 4acd51ada..29b4c99d8 100644 --- a/doc/iscsi.md +++ b/doc/iscsi.md @@ -1,6 +1,6 @@ # iSCSI Target {#iscsi} -# iSCSI Target Getting Started Guide {#iscsi_getting_started} +## iSCSI Target Getting Started Guide {#iscsi_getting_started} The Storage Performance Development Kit iSCSI target application is named `iscsi_tgt`. This following section describes how to run iscsi from your cloned package. @@ -269,7 +269,7 @@ sdd sde ~~~ -# iSCSI Hotplug {#iscsi_hotplug} +## iSCSI Hotplug {#iscsi_hotplug} At the iSCSI level, we provide the following support for Hotplug: @@ -293,7 +293,7 @@ return back; after all the commands return back, the LUN will be deleted. @sa spdk_nvme_probe -# iSCSI Login Redirection {#iscsi_login_redirection} +## iSCSI Login Redirection {#iscsi_login_redirection} The SPDK iSCSI target application supports iSCSI login redirection feature. diff --git a/doc/jsonrpc.md b/doc/jsonrpc.md index 327288695..90f7bbc49 100644 --- a/doc/jsonrpc.md +++ b/doc/jsonrpc.md @@ -1,6 +1,6 @@ # JSON-RPC {#jsonrpc} -# Overview {#jsonrpc_overview} +## Overview {#jsonrpc_overview} SPDK implements a [JSON-RPC 2.0](http://www.jsonrpc.org/specification) server to allow external management tools to dynamically configure SPDK components. @@ -218,19 +218,19 @@ file can be converted to JSON-RPC using python tool: ./scripts/config_converter.py < config.ini > config.json ~~~ -# App Framework {#jsonrpc_components_app} +## App Framework {#jsonrpc_components_app} -## spdk_kill_instance {#rpc_spdk_kill_instance} +### spdk_kill_instance {#rpc_spdk_kill_instance} Send a signal to the application. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- sig_name | Required | string | Signal to send (SIGINT, SIGTERM, SIGQUIT, SIGHUP, or SIGKILL) -### Example +#### Example Example request: @@ -255,23 +255,23 @@ Example response: } ~~~ -## framework_monitor_context_switch {#rpc_framework_monitor_context_switch} +### framework_monitor_context_switch {#rpc_framework_monitor_context_switch} Query, enable, or disable the context switch monitoring functionality. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- enabled | Optional | boolean | Enable (`true`) or disable (`false`) monitoring (omit this parameter to query the current state) -### Response +#### Response Name | Type | Description ----------------------- | ----------- | ----------- enabled | boolean | The current state of context switch monitoring -### Example +#### Example Example request: @@ -298,21 +298,21 @@ Example response: } ~~~ -## framework_start_init {#rpc_framework_start_init} +### framework_start_init {#rpc_framework_start_init} Start initialization of SPDK subsystems when it is deferred by starting SPDK application with option -w. During its deferral some RPCs can be used to set global parameters for SPDK subsystems. This RPC can be called only once. -### Parameters +#### Parameters This method has no parameters. -### Response +#### Response Completion status of SPDK subsystem initialization is returned as a boolean. -### Example +#### Example Example request: @@ -334,20 +334,20 @@ Example response: } ~~~ -## framework_wait_init {#rpc_framework_wait_init} +### framework_wait_init {#rpc_framework_wait_init} Do not return until all subsystems have been initialized and the RPC system state is running. If the application is already running, this call will return immediately. This RPC can be called at any time. -### Parameters +#### Parameters This method has no parameters. -### Response +#### Response Returns True when subsystems have been initialized. -### Example +#### Example Example request: @@ -369,21 +369,21 @@ Example response: } ~~~ -## rpc_get_methods {#rpc_rpc_get_methods} +### rpc_get_methods {#rpc_rpc_get_methods} Get an array of supported RPC methods. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- current | Optional | boolean | Get an array of RPC methods only callable in the current state. -### Response +#### Response The response is an array of supported RPC methods. -### Example +#### Example Example request: @@ -482,19 +482,19 @@ Example response: } ~~~ -## framework_get_subsystems {#rpc_framework_get_subsystems} +### framework_get_subsystems {#rpc_framework_get_subsystems} Get an array of name and dependency relationship of SPDK subsystems in initialization order. -### Parameters +#### Parameters None -### Response +#### Response The response is an array of name and dependency relationship of SPDK subsystems in initialization order. -### Example +#### Example Example request: @@ -567,22 +567,22 @@ Example response: } ~~~ -## framework_get_config {#rpc_framework_get_config} +### framework_get_config {#rpc_framework_get_config} Get current configuration of the specified SPDK framework -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | SPDK subsystem name -### Response +#### Response The response is current configuration of the specified SPDK subsystem. Null is returned if it is not retrievable by the framework_get_config method and empty array is returned if it is empty. -### Example +#### Example Example request: @@ -650,19 +650,19 @@ Example response: } ~~~ -## framework_get_reactors {#rpc_framework_get_reactors} +### framework_get_reactors {#rpc_framework_get_reactors} Retrieve an array of all reactors. -### Parameters +#### Parameters This method has no parameters. -### Response +#### Response The response is an array of all reactors. -### Example +#### Example Example request: ~~~ @@ -699,23 +699,23 @@ Example response: } ~~~ -## framework_set_scheduler {#rpc_framework_set_scheduler} +### framework_set_scheduler {#rpc_framework_set_scheduler} Select thread scheduler that will be activated. This feature is considered as experimental. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Name of a scheduler period | Optional | number | Scheduler period -### Response +#### Response Completion status of the operation is returned as a boolean. -### Example +#### Example Example request: @@ -741,15 +741,15 @@ Example response: } ~~~ -## framework_get_scheduler {#rpc_framework_get_scheduler} +### framework_get_scheduler {#rpc_framework_get_scheduler} Retrieve currently set scheduler name and period, along with current governor name. -### Parameters +#### Parameters This method has no parameters. -### Response +#### Response Name | Description ------------------------| ----------- @@ -757,7 +757,7 @@ scheduler_name | Current scheduler name scheduler_period | Currently set scheduler period in microseconds governor_name | Governor name -### Example +#### Example Example request: @@ -783,19 +783,19 @@ Example response: } ~~~ -## thread_get_stats {#rpc_thread_get_stats} +### thread_get_stats {#rpc_thread_get_stats} Retrieve current statistics of all the threads. -### Parameters +#### Parameters This method has no parameters. -### Response +#### Response The response is an array of objects containing threads statistics. -### Example +#### Example Example request: ~~~ @@ -830,23 +830,23 @@ Example response: } ~~~ -## thread_set_cpumask {#rpc_thread_set_cpumask} +### thread_set_cpumask {#rpc_thread_set_cpumask} Set the cpumask of the thread to the specified value. The thread may be migrated to one of the specified CPUs. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- id | Required | string | Thread ID cpumask | Required | string | Cpumask for this thread -### Response +#### Response Completion status of the operation is returned as a boolean. -### Example +#### Example Example request: @@ -872,18 +872,18 @@ Example response: } ~~~ -## trace_enable_tpoint_group {#rpc_trace_enable_tpoint_group} +### trace_enable_tpoint_group {#rpc_trace_enable_tpoint_group} Enable trace on a specific tpoint group. For example "bdev" for bdev trace group, "all" for all trace groups. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl, all -### Example +#### Example Example request: @@ -908,18 +908,18 @@ Example response: } ~~~ -## trace_disable_tpoint_group {#rpc_trace_disable_tpoint_group} +### trace_disable_tpoint_group {#rpc_trace_disable_tpoint_group} Disable trace on a specific tpoint group. For example "bdev" for bdev trace group, "all" for all trace groups. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, all -### Example +#### Example Example request: @@ -944,15 +944,15 @@ Example response: } ~~~ -## trace_get_tpoint_group_mask {#rpc_trace_get_tpoint_group_mask} +### trace_get_tpoint_group_mask {#rpc_trace_get_tpoint_group_mask} Display mask info for every group. -### Parameters +#### Parameters No parameters required -### Example +#### Example Example request: @@ -1000,18 +1000,18 @@ Example response: } ~~~ -## log_set_print_level {#rpc_log_set_print_level} +### log_set_print_level {#rpc_log_set_print_level} Set the current level at which output will additionally be sent to the current console. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- level | Required | string | ERROR, WARNING, NOTICE, INFO, DEBUG -### Example +#### Example Example request: @@ -1036,12 +1036,12 @@ Example response: } ~~~ -## log_get_print_level {#rpc_log_get_print_level} +### log_get_print_level {#rpc_log_get_print_level} Get the current level at which output will additionally be sent to the current console. -### Example +#### Example Example request: @@ -1063,17 +1063,17 @@ Example response: } ~~~ -## log_set_level {#rpc_log_set_level} +### log_set_level {#rpc_log_set_level} Set the current logging level output by the `log` module. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- level | Required | string | ERROR, WARNING, NOTICE, INFO, DEBUG -### Example +#### Example Example request: @@ -1098,11 +1098,11 @@ Example response: } ~~~ -## log_get_level {#rpc_log_get_level} +### log_get_level {#rpc_log_get_level} Get the current logging level output by the `log` module. -### Example +#### Example Example request: @@ -1124,19 +1124,19 @@ Example response: } ~~~ -## log_set_flag {#rpc_log_set_flag} +### log_set_flag {#rpc_log_set_flag} Enable logging for specific portions of the application. The list of possible log flags can be obtained using the `log_get_flags` RPC and may be different for each application. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- flag | Required | string | A log flag, or 'all' -### Example +#### Example Example request: @@ -1161,19 +1161,19 @@ Example response: } ~~~ -## log_clear_flag {#rpc_log_clear_flag} +### log_clear_flag {#rpc_log_clear_flag} Disable logging for specific portions of the application. The list of possible log flags can be obtained using the `log_get_flags` RPC and may be different for each application. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- flag | Required | string | A log flag, or 'all' -### Example +#### Example Example request: @@ -1198,12 +1198,12 @@ Example response: } ~~~ -## log_get_flags {#rpc_log_get_flags} +### log_get_flags {#rpc_log_get_flags} Get the list of valid flags for this application and whether they are currently enabled. -### Example +#### Example Example request: @@ -1230,17 +1230,17 @@ Example response: } ~~~ -## log_enable_timestamps {#rpc_log_enable_timestamps} +### log_enable_timestamps {#rpc_log_enable_timestamps} Enable or disable timestamps. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- enabled | Required | boolean | on or off -### Example +#### Example Example request: @@ -1265,11 +1265,11 @@ Example response: } ~~~ -## thread_get_pollers {#rpc_thread_get_pollers} +### thread_get_pollers {#rpc_thread_get_pollers} Retrieve current pollers of all the threads. -### Parameters +#### Parameters This method has no parameters. @@ -1277,7 +1277,7 @@ This method has no parameters. The response is an array of objects containing pollers of all the threads. -### Example +#### Example Example request: ~~~ @@ -1316,19 +1316,19 @@ Example response: } ~~~ -## thread_get_io_channels {#rpc_thread_get_io_channels} +### thread_get_io_channels {#rpc_thread_get_io_channels} Retrieve current IO channels of all the threads. -### Parameters +#### Parameters This method has no parameters. -### Response +#### Response The response is an array of objects containing IO channels of all the threads. -### Example +#### Example Example request: ~~~ @@ -1361,19 +1361,19 @@ Example response: } ~~~ -## env_dpdk_get_mem_stats {#rpc_env_dpdk_get_mem_stats} +### env_dpdk_get_mem_stats {#rpc_env_dpdk_get_mem_stats} Write the dpdk memory stats to a file. -### Parameters +#### Parameters This method has no parameters. -### Response +#### Response The response is a pathname to a text file containing the memory stats. -### Example +#### Example Example request: @@ -1397,21 +1397,21 @@ Example response: } ~~~ -# Acceleration Framework Layer {#jsonrpc_components_accel_fw} +## Acceleration Framework Layer {#jsonrpc_components_accel_fw} -## idxd_scan_accel_engine {#rpc_idxd_scan_accel_engine} +### idxd_scan_accel_engine {#rpc_idxd_scan_accel_engine} Set config and enable idxd accel engine offload. This feature is considered as experimental. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- config_number | Required | number | Pre-defined config # to use (ie 0, 1). See [docs.](https://spdk.io/doc/idxd.html) config_kernel_mode | Optional | Boolean | If set, will use kernel idxd driver. -### Example +#### Example Example request: @@ -1437,15 +1437,15 @@ Example response: } ~~~ -## ioat_scan_accel_engine {#rpc_ioat_scan_accel_engine} +### ioat_scan_accel_engine {#rpc_ioat_scan_accel_engine} Enable ioat accel engine offload. -### Parameters +#### Parameters None -### Example +#### Example Example request: @@ -1467,14 +1467,14 @@ Example response: } ~~~ -# Block Device Abstraction Layer {#jsonrpc_components_bdev} +## Block Device Abstraction Layer {#jsonrpc_components_bdev} -## bdev_set_options {#rpc_bdev_set_options} +### bdev_set_options {#rpc_bdev_set_options} Set global parameters for the block device (bdev) subsystem. This RPC may only be called before SPDK subsystems have been initialized. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -1482,7 +1482,7 @@ bdev_io_pool_size | Optional | number | Number of spdk_bdev_io struct bdev_io_cache_size | Optional | number | Maximum number of spdk_bdev_io structures cached per thread bdev_auto_examine | Optional | boolean | If set to false, the bdev layer will not examine every disks automatically -### Example +#### Example Example request: @@ -1508,11 +1508,11 @@ Example response: } ~~~ -## bdev_get_bdevs {#rpc_bdev_get_bdevs} +### bdev_get_bdevs {#rpc_bdev_get_bdevs} Get information about block devices (bdevs). -### Parameters +#### Parameters The user may specify no parameters in order to list all block devices, or a block device may be specified by name. @@ -1521,11 +1521,11 @@ Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Optional | string | Block device name -### Response +#### Response The response is an array of objects containing information about the requested block devices. -### Example +#### Example Example request: @@ -1570,24 +1570,24 @@ Example response: } ~~~ -## bdev_examine {#rpc_bdev_examine} +### bdev_examine {#rpc_bdev_examine} Request that the bdev layer examines the given bdev for metadata and creates new bdevs if metadata is found. This is only necessary if `auto_examine` has been set to false using `bdev_set_options`. By default, `auto_examine` is true and bdev examination is automatic. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Block device name -### Response +#### Response The response is an array of objects containing I/O statistics of the requested block devices. -### Example +#### Example Example request: @@ -1612,19 +1612,19 @@ Example response: } ~~~ -## bdev_wait_for_examine {#rpc_bdev_wait_for_examine} +### bdev_wait_for_examine {#rpc_bdev_wait_for_examine} Report when all bdevs have been examined by every bdev module. -### Parameters +#### Parameters None -### Response +#### Response The response is sent when all bdev modules had a chance to examine every bdev. -### Example +#### Example Example request: @@ -1646,11 +1646,11 @@ Example response: } ~~~ -## bdev_get_iostat {#rpc_bdev_get_iostat} +### bdev_get_iostat {#rpc_bdev_get_iostat} Get I/O statistics of block devices (bdevs). -### Parameters +#### Parameters The user may specify no parameters in order to list all block devices, or a block device may be specified by name. @@ -1659,11 +1659,11 @@ Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Optional | string | Block device name -### Response +#### Response The response is an array of objects containing I/O statistics of the requested block devices. -### Example +#### Example Example request: @@ -1708,18 +1708,18 @@ Example response: } ~~~ -## bdev_enable_histogram {#rpc_bdev_enable_histogram} +### bdev_enable_histogram {#rpc_bdev_enable_histogram} Control whether collecting data for histogram is enabled for specified bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Block device name enable | Required | boolean | Enable or disable histogram on specified device -### Example +#### Example Example request: @@ -1745,17 +1745,17 @@ Example response: } ~~~ -## bdev_get_histogram {#rpc_bdev_get_histogram} +### bdev_get_histogram {#rpc_bdev_get_histogram} Get latency histogram for specified bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Block device name -### Result +#### Result Name | Description ------------------------| ----------- @@ -1763,7 +1763,7 @@ histogram | Base64 encoded histogram bucket_shift | Granularity of the histogram buckets tsc_rate | Ticks per second -### Example +#### Example Example request: @@ -1793,11 +1793,11 @@ Note that histogram field is trimmed, actual encoded histogram length is ~80kb. } ~~~ -## bdev_set_qos_limit {#rpc_bdev_set_qos_limit} +### bdev_set_qos_limit {#rpc_bdev_set_qos_limit} Set the quality of service rate limit on a bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -1807,7 +1807,7 @@ rw_mbytes_per_sec | Optional | number | Number of R/W megabytes per s r_mbytes_per_sec | Optional | number | Number of Read megabytes per second to allow. 0 means unlimited. w_mbytes_per_sec | Optional | number | Number of Write megabytes per second to allow. 0 means unlimited. -### Example +#### Example Example request: @@ -1836,18 +1836,18 @@ Example response: } ~~~ -## bdev_set_qd_sampling_period {#rpc_bdev_set_qd_sampling_period} +### bdev_set_qd_sampling_period {#rpc_bdev_set_qd_sampling_period} Enable queue depth tracking on a specified bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Block device name period | Required | int | period (in microseconds).If set to 0, polling will be disabled. -### Example +#### Example Example request: @@ -1873,11 +1873,11 @@ Example response: } ~~~ -## bdev_compress_create {#rpc_bdev_compress_create} +### bdev_compress_create {#rpc_bdev_compress_create} Create a new compress bdev on a given base bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -1885,11 +1885,11 @@ base_bdev_name | Required | string | Name of the base bdev pm_path | Required | string | Path to persistent memory lb_size | Optional | int | Compressed vol logical block size (512 or 4096) -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request: @@ -1906,17 +1906,17 @@ Example request: } ~~~ -## bdev_compress_delete {#rpc_bdev_compress_delete} +### bdev_compress_delete {#rpc_bdev_compress_delete} Delete a compressed bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Name of the compress bdev -### Example +#### Example Example request: @@ -1941,17 +1941,17 @@ Example response: } ~~~ -## bdev_compress_get_orphans {#rpc_bdev_compress_get_orphans} +### bdev_compress_get_orphans {#rpc_bdev_compress_get_orphans} Get a list of compressed volumes that are missing their pmem metadata. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Name of the compress bdev -### Example +#### Example Example request: @@ -1976,18 +1976,18 @@ Example response: } ~~~ -## bdev_compress_set_pmd {#rpc_bdev_compress_set_pmd} +### bdev_compress_set_pmd {#rpc_bdev_compress_set_pmd} Select the DPDK polled mode driver (pmd) for a compressed bdev, 0 = auto-select, 1= QAT only, 2 = ISAL only, 3 = mlx5_pci only. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- pmd | Required | int | pmd selection -### Example +#### Example Example request: @@ -2012,11 +2012,11 @@ Example response: } ~~~ -## bdev_crypto_create {#rpc_bdev_crypto_create} +### bdev_crypto_create {#rpc_bdev_crypto_create} Create a new crypto bdev on a given base bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -2027,11 +2027,11 @@ key | Required | string | Key cipher | Required | string | Cipher to use, AES_CBC or AES_XTS (QAT only) key2 | Required | string | 2nd key only required for cipher AET_XTS -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request: @@ -2061,17 +2061,17 @@ Example response: } ~~~ -## bdev_crypto_delete {#rpc_bdev_crypto_delete} +### bdev_crypto_delete {#rpc_bdev_crypto_delete} Delete a crypto bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Name of the crypto bdev -### Example +#### Example Example request: @@ -2096,13 +2096,13 @@ Example response: } ~~~ -## bdev_ocf_create {#rpc_bdev_ocf_create} +### bdev_ocf_create {#rpc_bdev_ocf_create} Construct new OCF bdev. Command accepts cache mode that is going to be used. You can find more details about supported cache modes in the [OCF documentation](https://open-cas.github.io/cache_configuration.html#cache-mode) -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -2112,11 +2112,11 @@ cache_line_size | Optional | int | OCF cache line size in KiB: 4 cache_bdev_name | Required | string | Name of underlying cache bdev core_bdev_name | Required | string | Name of underlying core bdev -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request: @@ -2145,17 +2145,17 @@ Example response: } ~~~ -## bdev_ocf_delete {#rpc_bdev_ocf_delete} +### bdev_ocf_delete {#rpc_bdev_ocf_delete} Delete the OCF bdev -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name -### Example +#### Example Example request: @@ -2180,21 +2180,21 @@ Example response: } ~~~ -## bdev_ocf_get_stats {#rpc_bdev_ocf_get_stats} +### bdev_ocf_get_stats {#rpc_bdev_ocf_get_stats} Get statistics of chosen OCF block device. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Block device name -### Response +#### Response Statistics as json object. -### Example +#### Example Example request: @@ -2384,21 +2384,21 @@ Example response: } ~~~ -## bdev_ocf_get_bdevs {#rpc_bdev_ocf_get_bdevs} +### bdev_ocf_get_bdevs {#rpc_bdev_ocf_get_bdevs} Get list of OCF devices including unregistered ones. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Optional | string | Name of OCF vbdev or name of cache device or name of core device -### Response +#### Response Array of OCF devices with their current status, along with core and cache bdevs. -### Example +#### Example Example request: @@ -2433,22 +2433,22 @@ Example response: } ~~~ -## bdev_ocf_set_cache_mode {#rpc_bdev_ocf_set_cache_mode} +### bdev_ocf_set_cache_mode {#rpc_bdev_ocf_set_cache_mode} Set new cache mode on OCF bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name mode | Required | string | OCF cache mode: wb, wt, pt, wa, wi, wo -### Response +#### Response New cache mode name. -### Example +#### Example Example request: @@ -2474,11 +2474,11 @@ Example response: } ~~~ -## bdev_malloc_create {#rpc_bdev_malloc_create} +### bdev_malloc_create {#rpc_bdev_malloc_create} Construct @ref bdev_config_malloc -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -2487,11 +2487,11 @@ block_size | Required | number | Block size in bytes -must be num_blocks | Required | number | Number of blocks uuid | Optional | string | UUID of new bdev -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request: @@ -2519,17 +2519,17 @@ Example response: } ~~~ -## bdev_malloc_delete {#rpc_bdev_malloc_delete} +### bdev_malloc_delete {#rpc_bdev_malloc_delete} Delete @ref bdev_config_malloc -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name -### Example +#### Example Example request: @@ -2554,11 +2554,11 @@ Example response: } ~~~ -## bdev_null_create {#rpc_bdev_null_create} +### bdev_null_create {#rpc_bdev_null_create} Construct @ref bdev_config_null -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -2570,11 +2570,11 @@ md_size | Optional | number | Metadata size for this bdev. dif_type | Optional | number | Protection information type. Parameter --md-size needs to be set along --dif-type. Default=0 - no protection. dif_is_head_of_md | Optional | boolean | Protection information is in the first 8 bytes of metadata. Default=false. -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request: @@ -2605,17 +2605,17 @@ Example response: } ~~~ -## bdev_null_delete {#rpc_bdev_null_delete} +### bdev_null_delete {#rpc_bdev_null_delete} Delete @ref bdev_config_null. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name -### Example +#### Example Example request: @@ -2640,18 +2640,18 @@ Example response: } ~~~ -## bdev_null_resize {#rpc_bdev_null_resize} +### bdev_null_resize {#rpc_bdev_null_resize} Resize @ref bdev_config_null. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name new_size | Required | number | Bdev new capacity in MB -### Example +#### Example Example request: @@ -2677,11 +2677,11 @@ Example response: } ~~~ -## bdev_aio_create {#rpc_bdev_aio_create} +### bdev_aio_create {#rpc_bdev_aio_create} Construct @ref bdev_config_aio. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -2689,11 +2689,11 @@ name | Required | string | Bdev name to use filename | Required | number | Path to device or file block_size | Optional | number | Block size in bytes -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request: @@ -2720,17 +2720,17 @@ Example response: } ~~~ -## bdev_aio_delete {#rpc_bdev_aio_delete} +### bdev_aio_delete {#rpc_bdev_aio_delete} Delete @ref bdev_config_aio. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name -### Example +#### Example Example request: @@ -2755,12 +2755,12 @@ Example response: } ~~~ -## bdev_nvme_set_options {#rpc_bdev_nvme_set_options} +### bdev_nvme_set_options {#rpc_bdev_nvme_set_options} Set global parameters for all bdev NVMe. This RPC may only be called before SPDK subsystems have been initialized or any bdev NVMe has been created. -### Parameters +#### Parameters Name | Optional | Type | Description -------------------------- | -------- | ----------- | ----------- @@ -2778,7 +2778,7 @@ nvme_ioq_poll_period_us | Optional | number | How often I/O queues are p io_queue_requests | Optional | number | The number of requests allocated for each NVMe I/O queue. Default: 512. delay_cmd_submit | Optional | boolean | Enable delaying NVMe command submission to allow batching of multiple commands. Default: `true`. -### Example +#### Example Example request: @@ -2815,19 +2815,19 @@ Example response: } ~~~ -## bdev_nvme_set_hotplug {#rpc_bdev_nvme_set_hotplug} +### bdev_nvme_set_hotplug {#rpc_bdev_nvme_set_hotplug} Change settings of the NVMe hotplug feature. If enabled, PCIe NVMe bdevs will be automatically discovered on insertion and deleted on removal. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- enabled | Required | string | True to enable, false to disable period_us | Optional | number | How often to poll for hot-insert and hot-remove events. Values: 0 - reset/use default or 1 to 10000000. -### Example +#### Example Example request: @@ -2854,18 +2854,18 @@ Example response: } ~~~ -## bdev_nvme_attach_controller {#rpc_bdev_nvme_attach_controller} +### bdev_nvme_attach_controller {#rpc_bdev_nvme_attach_controller} Construct @ref bdev_config_nvme. This RPC can also be used to add additional paths to an existing controller to enable multipathing. This is done by specifying the `name` parameter as an existing controller. When adding an additional path, the hostnqn, hostsvcid, hostaddr, prchk_reftag, and prchk_guard_arguments must not be specified and are assumed to have the same value as the existing path. -### Result +#### Result Array of names of newly created bdevs. -### Parameters +#### Parameters Name | Optional | Type | Description -------------------------- | -------- | ----------- | ----------- @@ -2884,7 +2884,7 @@ hdgst | Optional | bool | Enable TCP header digest ddgst | Optional | bool | Enable TCP data digest fabrics_connect_timeout_us | Optional | bool | Timeout for fabrics connect (in microseconds) -### Example +#### Example Example request: @@ -2913,11 +2913,11 @@ Example response: } ~~~ -## bdev_nvme_get_controllers {#rpc_bdev_nvme_get_controllers} +### bdev_nvme_get_controllers {#rpc_bdev_nvme_get_controllers} Get information about NVMe controllers. -### Parameters +#### Parameters The user may specify no parameters in order to list all NVMe controllers, or one NVMe controller may be specified by name. @@ -2926,11 +2926,11 @@ Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Optional | string | NVMe controller name -### Response +#### Response The response is an array of objects containing information about the requested NVMe controllers. -### Example +#### Example Example request: @@ -2963,7 +2963,7 @@ Example response: } ~~~ -## bdev_nvme_detach_controller {#rpc_bdev_nvme_detach_controller} +### bdev_nvme_detach_controller {#rpc_bdev_nvme_detach_controller} Detach NVMe controller and delete any associated bdevs. Optionally, If all of the transport ID options are specified, only remove that @@ -2974,7 +2974,7 @@ controller being detached and the associated bdevs being deleted. returns true if the controller and bdevs were successfully destroyed or the address was properly removed, false otherwise. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -2985,7 +2985,7 @@ adrfam | Optional | string | NVMe-oF target adrfam: ipv4, trsvcid | Optional | string | NVMe-oF target trsvcid: port number subnqn | Optional | string | NVMe-oF target subnqn -### Example +#### Example Example requests: @@ -3010,19 +3010,19 @@ Example response: } ~~~ -## bdev_nvme_reset_controller {#rpc_bdev_nvme_reset_controller} +### bdev_nvme_reset_controller {#rpc_bdev_nvme_reset_controller} Reset NVMe controller. Returns true if the controller reset was successful, false otherwise. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | NVMe controller name -### Example +#### Example Example request: @@ -3047,19 +3047,19 @@ Example response: } ~~~ -## bdev_nvme_cuse_register {#rpc_bdev_nvme_cuse_register} +### bdev_nvme_cuse_register {#rpc_bdev_nvme_cuse_register} Register CUSE device on NVMe controller. This feature is considered as experimental. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Name of the NVMe controller dev_path | Required | string | Path to the CUSE controller device, e.g. spdk/nvme0 -### Example +#### Example Example request: @@ -3085,18 +3085,18 @@ Example response: } ~~~ -## bdev_nvme_cuse_unregister {#rpc_bdev_nvme_cuse_unregister} +### bdev_nvme_cuse_unregister {#rpc_bdev_nvme_cuse_unregister} Unregister CUSE device on NVMe controller. This feature is considered as experimental. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Name of the NVMe controller -### Example +#### Example Example request: @@ -3121,11 +3121,11 @@ Example response: } ~~~ -## bdev_zone_block_create {#rpc_bdev_zone_block_create} +### bdev_zone_block_create {#rpc_bdev_zone_block_create} Creates a virtual zone device on top of existing non-zoned bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -3134,7 +3134,7 @@ base_bdev | Required | string | Name of the Base bdev zone_capacity | Required | number | Zone capacity in blocks optimal_open_zones | Required | number | Number of zones required to reach optimal write speed -### Example +#### Example Example request: @@ -3162,17 +3162,17 @@ Example response: } ~~~ -## bdev_zone_block_delete {#rpc_bdev_zone_block_delete} +### bdev_zone_block_delete {#rpc_bdev_zone_block_delete} Deletes a virtual zone device. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Name of the Zone device -### Example +#### Example Example request: @@ -3197,18 +3197,18 @@ Example response: } ~~~ -## bdev_nvme_apply_firmware {#rpc_bdev_nvme_apply_firmware} +### bdev_nvme_apply_firmware {#rpc_bdev_nvme_apply_firmware} Download and commit firmware to NVMe device. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- filename | Required | string | filename of the firmware to download bdev_name | Required | string | Name of the NVMe block device -### Example +#### Example Example request: @@ -3224,19 +3224,19 @@ Example request: } ~~~ -## bdev_nvme_get_transport_statistics {#rpc_bdev_nvme_get_transport_statistics} +### bdev_nvme_get_transport_statistics {#rpc_bdev_nvme_get_transport_statistics} Get bdev_nvme poll group transport statistics. -### Parameters +#### Parameters This RPC method accepts no parameters -### Response +#### Response The response is an array of objects containing information about transport statistics per NVME poll group. -### Example +#### Example Example request: @@ -3345,21 +3345,21 @@ Example response: } ~~~ -## bdev_nvme_get_controller_health_info {#rpc_bdev_nvme_get_controller_health_info} +### bdev_nvme_get_controller_health_info {#rpc_bdev_nvme_get_controller_health_info} Display health log of the required NVMe bdev device. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Name of the NVMe bdev controller -### Response +#### Response The response is the object containing information about health log of the NVMe controller. -### Example +#### Example Example request: @@ -3401,11 +3401,11 @@ Example response: } ~~~ -## bdev_rbd_register_cluster {#rpc_bdev_rbd_register_cluster} +### bdev_rbd_register_cluster {#rpc_bdev_rbd_register_cluster} This method is available only if SPDK was build with Ceph RBD support. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -3428,11 +3428,11 @@ secret key stored in Ceph keyrings) are enough. When accessing the Ceph cluster as some user other than "admin" (the default), the "user_id" has to be set. -### Result +#### Result Name of newly created Rados cluster object. -### Example +#### Example Example request with `key` from `/etc/ceph/ceph.client.admin.keyring`: @@ -3462,23 +3462,23 @@ response: } ~~ -## bdev_rbd_unregister_cluster {#rpc_bdev_rbd_unregister_cluster} +### bdev_rbd_unregister_cluster {#rpc_bdev_rbd_unregister_cluster} This method is available only if SPDK was build with Ceph RBD support. If there is still rbd bdev using this cluster, the unregisteration operation will fail. -### Result +#### Result `true` if Rados cluster object with provided name was deleted or `false` otherwise. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ------------------------- name | Required | string | Rados cluster object name -### Example +#### Example Example request: @@ -3503,22 +3503,22 @@ Example response: } ~~ -## bdev_rbd_get_clusters_info {#rpc_bdev_rbd_get_clusters_info} +### bdev_rbd_get_clusters_info {#rpc_bdev_rbd_get_clusters_info} This method is available only if SPDK was build with Ceph RBD support. -### Result +#### Result Returns the cluster info of the Rados Cluster name if provided. Otherwise, it returns the cluster info of every registered Raods Cluster name. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ------------------------- name | Optional | string | Rados cluster object name -### Example +#### Example Example request: @@ -3542,13 +3542,13 @@ Example response: } ~~ -## bdev_rbd_create {#rpc_bdev_rbd_create} +### bdev_rbd_create {#rpc_bdev_rbd_create} Create @ref bdev_config_rbd bdev This method is available only if SPDK was build with Ceph RBD support. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -3574,11 +3574,11 @@ If provided with cluster_name option, it will use the Rados cluster object referenced by the name (created by bdev_rbd_register_cluster RPC) and ignores "user_id + config" combination to create its own Rados cluster. -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request with `key` from `/etc/ceph/ceph.client.admin.keyring`: @@ -3637,23 +3637,23 @@ response: } ~~ -## bdev_rbd_delete {#rpc_bdev_rbd_delete} +### bdev_rbd_delete {#rpc_bdev_rbd_delete} Delete @ref bdev_config_rbd bdev This method is available only if SPDK was build with Ceph RBD support. -### Result +#### Result `true` if bdev with provided name was deleted or `false` otherwise. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name -### Example +#### Example Example request: @@ -3678,24 +3678,24 @@ Example response: } ~~~ -## bdev_rbd_resize {#rpc_bdev_rbd_resize} +### bdev_rbd_resize {#rpc_bdev_rbd_resize} Resize @ref bdev_config_rbd bdev This method is available only if SPDK was build with Ceph RBD support. -### Result +#### Result `true` if bdev with provided name was resized or `false` otherwise. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name new_size | Required | int | New bdev size for resize operation in MiB -### Example +#### Example Example request: @@ -3721,12 +3721,12 @@ Example response: } ~~~ -## bdev_delay_create {#rpc_bdev_delay_create} +### bdev_delay_create {#rpc_bdev_delay_create} Create delay bdev. This bdev type redirects all IO to it's base bdev and inserts a delay on the completion path to create an artificial drive latency. All latency values supplied to this bdev should be in microseconds. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -3737,11 +3737,11 @@ p99_read_latency | Required | number | p99 read latency (us) avg_write_latency | Required | number | average write latency (us) p99_write_latency | Required | number | p99 write latency (us) -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request: @@ -3771,17 +3771,17 @@ Example response: } ~~~ -## bdev_delay_delete {#rpc_bdev_delay_delete} +### bdev_delay_delete {#rpc_bdev_delay_delete} Delete delay bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name -### Example +#### Example Example request: @@ -3807,12 +3807,12 @@ Example response: } ~~~ -## bdev_delay_update_latency {#rpc_bdev_delay_update_latency} +### bdev_delay_update_latency {#rpc_bdev_delay_update_latency} Update a target latency value associated with a given delay bdev. Any currently outstanding I/O will be completed with the old latency. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -3820,11 +3820,11 @@ delay_bdev_name | Required | string | Name of the delay bdev latency_type | Required | string | One of: avg_read, avg_write, p99_read, p99_write latency_us | Required | number | The new latency value in microseconds -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request: @@ -3849,17 +3849,17 @@ Example response: } ~~~ -## bdev_error_create {#rpc_bdev_error_create} +### bdev_error_create {#rpc_bdev_error_create} Construct error bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- base_name | Required | string | Base bdev name -### Example +#### Example Example request: @@ -3884,21 +3884,21 @@ Example response: } ~~~ -## bdev_error_delete {#rpc_bdev_error_delete} +### bdev_error_delete {#rpc_bdev_error_delete} Delete error bdev -### Result +#### Result `true` if bdev with provided name was deleted or `false` otherwise. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Error bdev name -### Example +#### Example Example request: @@ -3923,12 +3923,12 @@ Example response: } ~~~ -## bdev_error_inject_error {#rpc_bdev_error_inject_error} +### bdev_error_inject_error {#rpc_bdev_error_inject_error} Inject an error via an error bdev. Create an error bdev on base bdev first. Default 'num' value is 1 and if 'num' is set to zero, the specified injection is disabled. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -3937,7 +3937,7 @@ io_type | Required | string | io type 'clear' 'read' 'write error_type | Required | string | error type 'failure' 'pending' num | Optional | int | the number of commands you want to fail.(default:1) -### Example +#### Example Example request: @@ -3965,13 +3965,13 @@ Example response: } ~~~ -## bdev_iscsi_create {#rpc_bdev_iscsi_create} +### bdev_iscsi_create {#rpc_bdev_iscsi_create} Connect to iSCSI target and create bdev backed by this connection. This method is available only if SPDK was build with iSCSI initiator support. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -3979,11 +3979,11 @@ name | Required | string | Bdev name initiator_iqn | Required | string | IQN name used during connection url | Required | string | iSCSI resource URI -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request: @@ -4010,19 +4010,19 @@ Example response: } ~~~ -## bdev_iscsi_delete {#rpc_bdev_iscsi_delete} +### bdev_iscsi_delete {#rpc_bdev_iscsi_delete} Delete iSCSI bdev and terminate connection to target. This method is available only if SPDK was built with iSCSI initiator support. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name -### Example +#### Example Example request: @@ -4047,13 +4047,13 @@ Example response: } ~~~ -## bdev_ftl_create {#rpc_bdev_ftl_create} +### bdev_ftl_create {#rpc_bdev_ftl_create} Create FTL bdev. This RPC is subject to change. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -4064,11 +4064,11 @@ punits | Required | string | Parallel unit range in the fo uuid | Optional | string | UUID of restored bdev (not applicable when creating new instance) cache | Optional | string | Name of the bdev to be used as a write buffer cache -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request: @@ -4100,19 +4100,19 @@ Example response: } ~~~ -## bdev_ftl_delete {#rpc_bdev_ftl_delete} +### bdev_ftl_delete {#rpc_bdev_ftl_delete} Delete FTL bdev. This RPC is subject to change. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name -### Example +#### Example Example request: @@ -4137,11 +4137,11 @@ Example response: } ~~~ -## bdev_ocssd_create {#rpc_bdev_ocssd_create} +### bdev_ocssd_create {#rpc_bdev_ocssd_create} Create Open Channel zoned bdev on specified Open Channel controller. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -4149,7 +4149,7 @@ ctrlr_name | Required | string | OC NVMe controller name | Required | string | Bdev name to create nsid | Optional | string | namespace ID -### Example +#### Example Example request: @@ -4175,17 +4175,17 @@ Example response: } ~~~ -## bdev_ocssd_delete {#rpc_bdev_ocssd_delete} +### bdev_ocssd_delete {#rpc_bdev_ocssd_delete} Delete Open Channel zoned bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name to delete -### Example +#### Example Example request: @@ -4210,7 +4210,7 @@ Example response: } ~~~ -## bdev_pmem_create_pool {#rpc_bdev_pmem_create_pool} +### bdev_pmem_create_pool {#rpc_bdev_pmem_create_pool} Create a @ref bdev_config_pmem blk pool file. It is equivalent of following `pmempool create` command: @@ -4220,7 +4220,7 @@ pmempool create -s $((num_blocks * block_size)) blk $block_size $pmem_file This method is available only if SPDK was built with PMDK support. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -4228,7 +4228,7 @@ pmem_file | Required | string | Path to new pmem file num_blocks | Required | number | Number of blocks block_size | Required | number | Size of each block in bytes -### Example +#### Example Example request: @@ -4255,19 +4255,19 @@ Example response: } ~~~ -## bdev_pmem_get_pool_info {#rpc_bdev_pmem_get_pool_info} +### bdev_pmem_get_pool_info {#rpc_bdev_pmem_get_pool_info} Retrieve basic information about PMDK memory pool. This method is available only if SPDK was built with PMDK support. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- pmem_file | Required | string | Path to existing pmem file -### Result +#### Result Array of objects describing memory pool: @@ -4276,7 +4276,7 @@ Name | Type | Description num_blocks | number | Number of blocks block_size | number | Size of each block in bytes -### Example +#### Example Example request: @@ -4307,20 +4307,20 @@ Example response: } ~~~ -## bdev_pmem_delete_pool {#rpc_bdev_pmem_delete_pool} +### bdev_pmem_delete_pool {#rpc_bdev_pmem_delete_pool} Delete pmem pool by removing file `pmem_file`. This method will fail if `pmem_file` is not a valid pmem pool file. This method is available only if SPDK was built with PMDK support. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- pmem_file | Required | string | Path to new pmem file -### Example +#### Example Example request: @@ -4345,24 +4345,24 @@ Example response: } ~~~ -## bdev_pmem_create {#rpc_bdev_pmem_create} +### bdev_pmem_create {#rpc_bdev_pmem_create} Construct @ref bdev_config_pmem bdev. This method is available only if SPDK was built with PMDK support. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name pmem_file | Required | string | Path to existing pmem blk pool file -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request: @@ -4388,23 +4388,23 @@ Example response: } ~~~ -## bdev_pmem_delete {#rpc_bdev_pmem_delete} +### bdev_pmem_delete {#rpc_bdev_pmem_delete} Delete @ref bdev_config_pmem bdev. This call will not remove backing pool files. This method is available only if SPDK was built with PMDK support. -### Result +#### Result `true` if bdev with provided name was deleted or `false` otherwise. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name -### Example +#### Example Example request: @@ -4429,23 +4429,23 @@ Example response: } ~~~ -## bdev_passthru_create {#rpc_bdev_passthru_create} +### bdev_passthru_create {#rpc_bdev_passthru_create} Create passthru bdev. This bdev type redirects all IO to it's base bdev. It has no other purpose than being an example and a starting point in development of new bdev type. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name base_bdev_name | Required | string | Base bdev name -### Result +#### Result Name of newly created bdev. -### Example +#### Example Example request: @@ -4471,17 +4471,17 @@ Example response: } ~~~ -## bdev_passthru_delete {#rpc_bdev_passthru_delete} +### bdev_passthru_delete {#rpc_bdev_passthru_delete} Delete passthru bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Bdev name -### Example +#### Example Example request: @@ -4507,11 +4507,11 @@ Example response: } ~~~ -## bdev_virtio_attach_controller {#rpc_bdev_virtio_attach_controller} +### bdev_virtio_attach_controller {#rpc_bdev_virtio_attach_controller} Create new initiator @ref bdev_config_virtio_scsi or @ref bdev_config_virtio_blk and expose all found bdevs. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -4527,11 +4527,11 @@ name of created bdev. `vq_count` and `vq_size` parameters are valid only if `trtype` is `user`. -### Result +#### Result Array of names of newly created bdevs. -### Example +#### Example Example request: @@ -4561,19 +4561,19 @@ Example response: } ~~~ -## bdev_virtio_scsi_get_devices {#rpc_bdev_virtio_scsi_get_devices} +### bdev_virtio_scsi_get_devices {#rpc_bdev_virtio_scsi_get_devices} Show information about all available Virtio SCSI devices. -### Parameters +#### Parameters This method has no parameters. -### Result +#### Result Array of Virtio SCSI information objects. -### Example +#### Example Example request: @@ -4605,17 +4605,17 @@ Example response: } ~~~ -## bdev_virtio_detach_controller {#rpc_bdev_virtio_detach_controller} +### bdev_virtio_detach_controller {#rpc_bdev_virtio_detach_controller} Remove a Virtio device. This command can be used to remove any type of virtio device. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | Virtio name -### Example +#### Example Example request: @@ -4641,11 +4641,11 @@ Example response: } ~~~ -## bdev_virtio_blk_set_hotplug {#rpc_bdev_virtio_blk_set_hotplug} +### bdev_virtio_blk_set_hotplug {#rpc_bdev_virtio_blk_set_hotplug} Enable/Disable the virtio blk hotplug monitor or change the monitor period time -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -4655,11 +4655,11 @@ period-us | Optional | number | The period time of the monito When the enable is true then the period-us is optional. If user don't set the period time then use the default value. When the enable is false then the period-us is not required. -### Result +#### Result True the rpc is successful otherwise false -### Example +#### Example Example request: @@ -4685,15 +4685,15 @@ Example response: } ~~~ -# iSCSI Target {#jsonrpc_components_iscsi_tgt} +## iSCSI Target {#jsonrpc_components_iscsi_tgt} -## iscsi_set_options method {#rpc_iscsi_set_options} +### iscsi_set_options method {#rpc_iscsi_set_options} Set global parameters for iSCSI targets. This RPC may only be called before SPDK subsystems have been initialized. This RPC can be called only once. -### Parameters +#### Parameters Name | Optional | Type | Description ------------------------------- | -------- | ------- | ----------- @@ -4726,7 +4726,7 @@ Parameters `disable_chap` and `require_chap` are mutually exclusive. Parameters `req_discovery_auth_mutual`, and `discovery_auth_group` are still available instead of `disable_chap`, `require_chap`, `mutual_chap`, and `chap_group`, respectivey but will be removed in future releases. -### Example +#### Example Example request: @@ -4761,15 +4761,15 @@ Example response: } ~~~ -## iscsi_get_options method {#rpc_iscsi_get_options} +### iscsi_get_options method {#rpc_iscsi_get_options} Show global parameters of iSCSI targets. -### Parameters +#### Parameters This method has no parameters. -### Example +#### Example Example request: @@ -4812,15 +4812,15 @@ Example response: } ~~~ -## scsi_get_devices {#rpc_scsi_get_devices} +### scsi_get_devices {#rpc_scsi_get_devices} Display SCSI devices -### Parameters +#### Parameters This method has no parameters. -### Example +#### Example Example request: @@ -4847,11 +4847,11 @@ Example response: } ~~~ -## iscsi_set_discovery_auth method {#rpc_iscsi_set_discovery_auth} +### iscsi_set_discovery_auth method {#rpc_iscsi_set_discovery_auth} Set CHAP authentication for sessions dynamically. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -4862,7 +4862,7 @@ chap_group | Optional | number | CHAP group ID for discovery s Parameters `disable_chap` and `require_chap` are mutually exclusive. -### Example +#### Example Example request: @@ -4890,18 +4890,18 @@ Example response: } ~~~ -## iscsi_create_auth_group method {#rpc_iscsi_create_auth_group} +### iscsi_create_auth_group method {#rpc_iscsi_create_auth_group} Create an authentication group for CHAP authentication. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- tag | Required | number | Authentication group tag (unique, integer > 0) secrets | Optional | array | Array of @ref rpc_iscsi_create_auth_group_secret objects -### secret {#rpc_iscsi_create_auth_group_secret} +#### secret {#rpc_iscsi_create_auth_group_secret} Name | Optional | Type | Description --------------------------- | ---------| --------| ----------- @@ -4910,7 +4910,7 @@ secret | Required | string | Unidirectional CHAP secret muser | Optional | string | Bidirectional CHAP name msecret | Optional | string | Bidirectional CHAP secret -### Example +#### Example Example request: @@ -4943,17 +4943,17 @@ Example response: } ~~~ -## iscsi_delete_auth_group method {#rpc_iscsi_delete_auth_group} +### iscsi_delete_auth_group method {#rpc_iscsi_delete_auth_group} Delete an existing authentication group for CHAP authentication. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- tag | Required | number | Authentication group tag (unique, integer > 0) -### Example +#### Example Example request: @@ -4978,15 +4978,15 @@ Example response: } ~~~ -## iscsi_get_auth_groups {#rpc_iscsi_get_auth_groups} +### iscsi_get_auth_groups {#rpc_iscsi_get_auth_groups} Show information about all existing authentication group for CHAP authentication. -### Parameters +#### Parameters This method has no parameters. -### Result +#### Result Array of objects describing authentication group. @@ -4995,7 +4995,7 @@ Name | Type | Description tag | number | Authentication group tag secrets | array | Array of @ref rpc_iscsi_create_auth_group_secret objects -### Example +#### Example Example request: @@ -5037,11 +5037,11 @@ Example response: } ~~~ -## iscsi_auth_group_add_secret {#rpc_iscsi_auth_group_add_secret} +### iscsi_auth_group_add_secret {#rpc_iscsi_auth_group_add_secret} Add a secret to an existing authentication group for CHAP authentication. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -5051,7 +5051,7 @@ secret | Required | string | Unidirectional CHAP secret muser | Optional | string | Bidirectional CHAP name msecret | Optional | string | Bidirectional CHAP secret -### Example +#### Example Example request: @@ -5080,18 +5080,18 @@ Example response: } ~~~ -## iscsi_auth_group_remove_secret {#rpc_iscsi_auth_group_remove_secret} +### iscsi_auth_group_remove_secret {#rpc_iscsi_auth_group_remove_secret} Remove a secret from an existing authentication group for CHAP authentication. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- tag | Required | number | Authentication group tag (unique, integer > 0) user | Required | string | Unidirectional CHAP name -### Example +#### Example Example request: @@ -5117,15 +5117,15 @@ Example response: } ~~~ -## iscsi_get_initiator_groups method {#rpc_iscsi_get_initiator_groups} +### iscsi_get_initiator_groups method {#rpc_iscsi_get_initiator_groups} Show information about all available initiator groups. -### Parameters +#### Parameters This method has no parameters. -### Result +#### Result Array of objects describing initiator groups. @@ -5135,7 +5135,7 @@ tag | number | Initiator group tag initiators | array | Array of initiator hostnames or IP addresses netmasks | array | Array of initiator netmasks -### Example +#### Example Example request: @@ -5168,11 +5168,11 @@ Example response: } ~~~ -## iscsi_create_initiator_group method {#rpc_iscsi_create_initiator_group} +### iscsi_create_initiator_group method {#rpc_iscsi_create_initiator_group} Add an initiator group. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -5180,7 +5180,7 @@ tag | Required | number | Initiator group tag (unique, initiators | Required | array | Not empty array of initiator hostnames or IP addresses netmasks | Required | array | Not empty array of initiator netmasks -### Example +#### Example Example request: @@ -5213,17 +5213,17 @@ response: } ~~~ -## iscsi_delete_initiator_group method {#rpc_iscsi_delete_initiator_group} +### iscsi_delete_initiator_group method {#rpc_iscsi_delete_initiator_group} Delete an existing initiator group. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- tag | Required | number | Initiator group tag (unique, integer > 0) -### Example +#### Example Example request: @@ -5248,11 +5248,11 @@ Example response: } ~~~ -## iscsi_initiator_group_add_initiators method {#rpc_iscsi_initiator_group_add_initiators} +### iscsi_initiator_group_add_initiators method {#rpc_iscsi_initiator_group_add_initiators} Add initiators to an existing initiator group. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -5260,7 +5260,7 @@ tag | Required | number | Existing initiator group tag. initiators | Optional | array | Array of initiator hostnames or IP addresses netmasks | Optional | array | Array of initiator netmasks -### Example +#### Example Example request: @@ -5293,11 +5293,11 @@ response: } ~~~ -## iscsi_initiator_group_remove_initiators method {#rpc_iscsi_initiator_group_remove_initiators} +### iscsi_initiator_group_remove_initiators method {#rpc_iscsi_initiator_group_remove_initiators} Remove initiators from an initiator group. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -5305,7 +5305,7 @@ tag | Required | number | Existing initiator group tag. initiators | Optional | array | Array of initiator hostnames or IP addresses netmasks | Optional | array | Array of initiator netmasks -### Example +#### Example Example request: @@ -5338,15 +5338,15 @@ response: } ~~~ -## iscsi_get_target_nodes method {#rpc_iscsi_get_target_nodes} +### iscsi_get_target_nodes method {#rpc_iscsi_get_target_nodes} Show information about all available iSCSI target nodes. -### Parameters +#### Parameters This method has no parameters. -### Result +#### Result Array of objects describing target node. @@ -5364,7 +5364,7 @@ chap_group | number | Authentication group ID for this target header_digest | boolean | Header Digest should be required for this target node data_digest | boolean | Data Digest should be required for this target node -### Example +#### Example Example request: @@ -5410,11 +5410,11 @@ Example response: } ~~~ -## iscsi_create_target_node method {#rpc_iscsi_create_target_node} +### iscsi_create_target_node method {#rpc_iscsi_create_target_node} Add an iSCSI target node. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -5432,7 +5432,7 @@ data_digest | Optional | boolean | Data Digest should be require Parameters `disable_chap` and `require_chap` are mutually exclusive. -### Example +#### Example Example request: @@ -5479,11 +5479,11 @@ Example response: } ~~~ -## iscsi_target_node_set_auth method {#rpc_iscsi_target_node_set_auth} +### iscsi_target_node_set_auth method {#rpc_iscsi_target_node_set_auth} Set CHAP authentication to an existing iSCSI target node. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -5495,7 +5495,7 @@ chap_group | Optional | number | Authentication group ID for t Parameters `disable_chap` and `require_chap` are mutually exclusive. -### Example +#### Example Example request: @@ -5523,11 +5523,11 @@ Example response: } ~~~ -## iscsi_target_node_add_pg_ig_maps method {#rpc_iscsi_target_node_add_pg_ig_maps} +### iscsi_target_node_add_pg_ig_maps method {#rpc_iscsi_target_node_add_pg_ig_maps} Add initiator group to portal group mappings to an existing iSCSI target node. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -5541,7 +5541,7 @@ Name | Optional | Type | Description ig_tag | Required | number | Existing initiator group tag pg_tag | Required | number | Existing portal group tag -### Example +#### Example Example request: @@ -5580,11 +5580,11 @@ Example response: } ~~~ -## iscsi_target_node_remove_pg_ig_maps method {#rpc_iscsi_target_node_remove_pg_ig_maps} +### iscsi_target_node_remove_pg_ig_maps method {#rpc_iscsi_target_node_remove_pg_ig_maps} Delete initiator group to portal group mappings from an existing iSCSI target node. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -5598,7 +5598,7 @@ Name | Optional | Type | Description ig_tag | Required | number | Existing initiator group tag pg_tag | Required | number | Existing portal group tag -### Example +#### Example Example request: @@ -5637,17 +5637,17 @@ Example response: } ~~~ -## iscsi_delete_target_node method {#rpc_iscsi_delete_target_node} +### iscsi_delete_target_node method {#rpc_iscsi_delete_target_node} Delete an iSCSI target node. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- name | Required | string | Target node name (ASCII) -### Example +#### Example Example request: @@ -5672,15 +5672,15 @@ Example response: } ~~~ -## iscsi_get_portal_groups method {#rpc_iscsi_get_portal_groups} +### iscsi_get_portal_groups method {#rpc_iscsi_get_portal_groups} Show information about all available portal groups. -### Parameters +#### Parameters This method has no parameters. -### Example +#### Example Example request: @@ -5714,11 +5714,11 @@ Example response: } ~~~ -## iscsi_create_portal_group method {#rpc_iscsi_create_portal_group} +### iscsi_create_portal_group method {#rpc_iscsi_create_portal_group} Add a portal group. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -5734,7 +5734,7 @@ Name | Optional | Type | Description host | Required | string | Hostname or IP address port | Required | string | Port number -### Example +#### Example Example request: @@ -5765,18 +5765,18 @@ Example response: } ~~~ -## iscsi_start_portal_group method {#rpc_iscsi_start_portal_group} +### iscsi_start_portal_group method {#rpc_iscsi_start_portal_group} Start listening on portals if the portal group is not started yet, or do nothing if the portal group already started. Return a success response for both cases. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- tag | Required | number | Existing portal group tag -### Example +#### Example Example request: @@ -5801,17 +5801,17 @@ Example response: } ~~~ -## iscsi_delete_portal_group method {#rpc_iscsi_delete_portal_group} +### iscsi_delete_portal_group method {#rpc_iscsi_delete_portal_group} Delete an existing portal group. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- tag | Required | number | Existing portal group tag -### Example +#### Example Example request: @@ -5836,12 +5836,12 @@ Example response: } ~~~ -## iscsi_portal_group_set_auth method {#rpc_iscsi_portal_group_set_auth} +### iscsi_portal_group_set_auth method {#rpc_iscsi_portal_group_set_auth} Set CHAP authentication for discovery sessions specific for the existing iSCSI portal group. This RPC overwrites the setting by the global parameters for the iSCSI portal group. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -5852,7 +5852,7 @@ chap_group | Optional | number | CHAP group ID for discovery s Parameters `disable_chap` and `require_chap` are mutually exclusive. -### Example +#### Example Example request: @@ -5881,15 +5881,15 @@ Example response: } ~~~ -## iscsi_get_connections method {#rpc_iscsi_get_connections} +### iscsi_get_connections method {#rpc_iscsi_get_connections} Show information about all active connections. -### Parameters +#### Parameters This method has no parameters. -### Results +#### Results Array of objects describing iSCSI connection. @@ -5903,7 +5903,7 @@ initiator_addr | string | Initiator address target_addr | string | Target address target_node_name | string | Target node name (ASCII) without prefix -### Example +#### Example Example request: @@ -5935,11 +5935,11 @@ Example response: } ~~~ -## iscsi_target_node_add_lun method {#rpc_iscsi_target_node_add_lun} +### iscsi_target_node_add_lun method {#rpc_iscsi_target_node_add_lun} Add an LUN to an existing iSCSI target node. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -5947,7 +5947,7 @@ name | Required | string | Target node name (ASCII) bdev_name | Required | string | bdev name to be added as a LUN lun_id | Optional | number | LUN ID (default: first free ID) -### Example +#### Example Example request: @@ -5974,11 +5974,11 @@ Example response: } ~~~ -## iscsi_target_node_set_redirect method {#rpc_iscsi_target_node_set_redirect} +### iscsi_target_node_set_redirect method {#rpc_iscsi_target_node_set_redirect} Update redirect portal of the primary portal group for the target node, -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -5989,7 +5989,7 @@ redirect_port | Optional | string | Numeric TCP port to which the If both redirect_host and redirect_port are omitted, clear the redirect portal. -### Example +#### Example Example request: @@ -6017,19 +6017,19 @@ Example response: } ~~~ -## iscsi_target_node_request_logout method {#rpc_iscsi_target_node_request_logout} +### iscsi_target_node_request_logout method {#rpc_iscsi_target_node_request_logout} For the target node, request connections whose portal group tag match to logout, or request all connections to logout if portal group tag is omitted. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- name | Required | string | Target node name (ASCII) pg_tag | Optional | number | Existing portal group tag -### Example +#### Example Example request: @@ -6055,13 +6055,13 @@ Example response: } ~~~ -# NVMe-oF Target {#jsonrpc_components_nvmf_tgt} +## NVMe-oF Target {#jsonrpc_components_nvmf_tgt} -## nvmf_create_transport method {#rpc_nvmf_create_transport} +### nvmf_create_transport method {#rpc_nvmf_create_transport} Initialize an NVMe-oF transport with the given options. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | --------| ----------- @@ -6086,7 +6086,7 @@ acceptor_backlog | Optional | number | The number of pending connect abort_timeout_sec | Optional | number | Abort execution timeout value, in seconds no_wr_batching | Optional | boolean | Disable work requests batching (RDMA only) -### Example +#### Example Example request: @@ -6112,15 +6112,15 @@ Example response: } ~~~ -## nvmf_get_subsystems method {#rpc_nvmf_get_subsystems} +### nvmf_get_subsystems method {#rpc_nvmf_get_subsystems} -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | ------------| ----------- tgt_name | Optional | string | Parent NVMe-oF target name. -### Example +#### Example Example request: @@ -6172,11 +6172,11 @@ Example response: } ~~~ -## nvmf_create_subsystem method {#rpc_nvmf_create_subsystem} +### nvmf_create_subsystem method {#rpc_nvmf_create_subsystem} Construct an NVMe over Fabrics target subsystem. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6190,7 +6190,7 @@ ana_reporting | Optional | boolean | Enable ANA reporting feature min_cntlid | Optional | number | Minimum controller ID. Default: 1 max_cntlid | Optional | number | Maximum controller ID. Default: 0xffef -### Example +#### Example Example request: @@ -6218,18 +6218,18 @@ Example response: } ~~~ -## nvmf_delete_subsystem method {#rpc_nvmf_delete_subsystem} +### nvmf_delete_subsystem method {#rpc_nvmf_delete_subsystem} Delete an existing NVMe-oF subsystem. -### Parameters +#### Parameters Parameter | Optional | Type | Description ---------------------- | -------- | ----------- | ----------- nqn | Required | string | Subsystem NQN to delete. tgt_name | Optional | string | Parent NVMe-oF target name. -### Example +#### Example Example request: @@ -6254,11 +6254,11 @@ Example response: } ~~~ -## nvmf_subsystem_add_listener method {#rpc_nvmf_subsystem_add_listener} +### nvmf_subsystem_add_listener method {#rpc_nvmf_subsystem_add_listener} Add a new listen address to an NVMe-oF subsystem. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6266,7 +6266,7 @@ nqn | Required | string | Subsystem NQN tgt_name | Optional | string | Parent NVMe-oF target name. listen_address | Required | object | @ref rpc_nvmf_listen_address object -### listen_address {#rpc_nvmf_listen_address} +#### listen_address {#rpc_nvmf_listen_address} Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6275,7 +6275,7 @@ adrfam | Required | string | Address family ("IPv4", "IPv6 traddr | Required | string | Transport address trsvcid | Optional | string | Transport service ID (required for RDMA or TCP) -### Example +#### Example Example request: @@ -6306,11 +6306,11 @@ Example response: } ~~~ -## nvmf_subsystem_remove_listener method {#rpc_nvmf_subsystem_remove_listener} +### nvmf_subsystem_remove_listener method {#rpc_nvmf_subsystem_remove_listener} Remove a listen address from an NVMe-oF subsystem. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6318,7 +6318,7 @@ nqn | Required | string | Subsystem NQN tgt_name | Optional | string | Parent NVMe-oF target name. listen_address | Required | object | @ref rpc_nvmf_listen_address object -### Example +#### Example Example request: @@ -6349,11 +6349,11 @@ Example response: } ~~~ -## nvmf_subsystem_listener_set_ana_state method {#rpc_nvmf_subsystem_listener_set_ana_state} +### nvmf_subsystem_listener_set_ana_state method {#rpc_nvmf_subsystem_listener_set_ana_state} Set ANA state of a listener for an NVMe-oF subsystem. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6362,7 +6362,7 @@ tgt_name | Optional | string | Parent NVMe-oF target name. listen_address | Required | object | @ref rpc_nvmf_listen_address object ana_state | Required | string | ANA state to set ("optimized", "non_optimized", or "inaccessible") -### Example +#### Example Example request: @@ -6394,7 +6394,7 @@ Example response: } ~~~ -## nvmf_subsystem_add_ns method {#rpc_nvmf_subsystem_add_ns} +### nvmf_subsystem_add_ns method {#rpc_nvmf_subsystem_add_ns} Add a namespace to a subsystem. The namespace ID is returned as the result. @@ -6406,7 +6406,7 @@ nqn | Required | string | Subsystem NQN namespace | Required | object | @ref rpc_nvmf_namespace object tgt_name | Optional | string | Parent NVMe-oF target name. -### namespace {#rpc_nvmf_namespace} +#### namespace {#rpc_nvmf_namespace} Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6417,7 +6417,7 @@ eui64 | Optional | string | 8-byte namespace EUI-64 in he uuid | Optional | string | RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5") ptpl_file | Optional | string | File path to save/restore persistent reservation information -### Example +#### Example Example request: @@ -6447,11 +6447,11 @@ Example response: } ~~~ -## nvmf_subsystem_remove_ns method {#rpc_nvmf_subsystem_remove_ns} +### nvmf_subsystem_remove_ns method {#rpc_nvmf_subsystem_remove_ns} Remove a namespace from a subsystem. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6459,7 +6459,7 @@ nqn | Required | string | Subsystem NQN nsid | Required | number | Namespace ID tgt_name | Optional | string | Parent NVMe-oF target name. -### Example +#### Example Example request: @@ -6485,11 +6485,11 @@ Example response: } ~~~ -## nvmf_subsystem_add_host method {#rpc_nvmf_subsystem_add_host} +### nvmf_subsystem_add_host method {#rpc_nvmf_subsystem_add_host} Add a host NQN to the list of allowed hosts. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6497,7 +6497,7 @@ nqn | Required | string | Subsystem NQN host | Required | string | Host NQN to add to the list of allowed host NQNs tgt_name | Optional | string | Parent NVMe-oF target name. -### Example +#### Example Example request: @@ -6523,11 +6523,11 @@ Example response: } ~~~ -## nvmf_subsystem_remove_host method {#rpc_nvmf_subsystem_remove_host} +### nvmf_subsystem_remove_host method {#rpc_nvmf_subsystem_remove_host} Remove a host NQN from the list of allowed hosts. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6535,7 +6535,7 @@ nqn | Required | string | Subsystem NQN host | Required | string | Host NQN to remove from the list of allowed host NQNs tgt_name | Optional | string | Parent NVMe-oF target name. -### Example +#### Example Example request: @@ -6561,11 +6561,11 @@ Example response: } ~~~ -## nvmf_subsystem_allow_any_host method {#rpc_nvmf_subsystem_allow_any_host} +### nvmf_subsystem_allow_any_host method {#rpc_nvmf_subsystem_allow_any_host} Configure a subsystem to allow any host to connect or to enforce the host NQN list. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6573,7 +6573,7 @@ nqn | Required | string | Subsystem NQN allow_any_host | Required | boolean | Allow any host (`true`) or enforce allowed host list (`false`). tgt_name | Optional | string | Parent NVMe-oF target name. -### Example +#### Example Example request: @@ -6599,16 +6599,16 @@ Example response: } ~~~ -## nvmf_subsystem_get_controllers {#rpc_nvmf_subsystem_get_controllers} +### nvmf_subsystem_get_controllers {#rpc_nvmf_subsystem_get_controllers} -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- nqn | Required | string | Subsystem NQN tgt_name | Optional | string | Parent NVMe-oF target name. -### Example +#### Example Example request: @@ -6640,16 +6640,16 @@ Example response: } ~~~ -## nvmf_subsystem_get_qpairs {#rpc_nvmf_subsystem_get_qpairs} +### nvmf_subsystem_get_qpairs {#rpc_nvmf_subsystem_get_qpairs} -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- nqn | Required | string | Subsystem NQN tgt_name | Optional | string | Parent NVMe-oF target name. -### Example +#### Example Example request: @@ -6697,16 +6697,16 @@ Example response: } ~~~ -## nvmf_subsystem_get_listeners {#rpc_nvmf_subsystem_get_listeners} +### nvmf_subsystem_get_listeners {#rpc_nvmf_subsystem_get_listeners} -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- nqn | Required | string | Subsystem NQN tgt_name | Optional | string | Parent NVMe-oF target name. -### Example +#### Example Example request: @@ -6741,18 +6741,18 @@ Example response: } ~~~ -## nvmf_set_max_subsystems {#rpc_nvmf_set_max_subsystems} +### nvmf_set_max_subsystems {#rpc_nvmf_set_max_subsystems} Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called before SPDK subsystems have been initialized. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- max_subsystems | Required | number | Maximum number of NVMe-oF subsystems -### Example +#### Example Example request: @@ -6777,12 +6777,12 @@ Example response: } ~~~ -## nvmf_set_config {#rpc_nvmf_set_config} +### nvmf_set_config {#rpc_nvmf_set_config} Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems have been initialized. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6790,13 +6790,13 @@ acceptor_poll_rate | Optional | number | Polling interval of the accep admin_cmd_passthru | Optional | object | Admin command passthru configuration poll_groups_mask | Optional | string | Set cpumask for NVMf poll groups -### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf} +#### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf} Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- identify_ctrlr | Required | bool | If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive -### Example +#### Example Example request: @@ -6821,15 +6821,15 @@ Example response: } ~~~ -## nvmf_get_transports method {#rpc_nvmf_get_transports} +### nvmf_get_transports method {#rpc_nvmf_get_transports} -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | ------------| ----------- tgt_name | Optional | string | Parent NVMe-oF target name. -### Example +#### Example Example request: @@ -6861,23 +6861,23 @@ Example response: } ~~~ -## nvmf_get_stats method {#rpc_nvmf_get_stats} +### nvmf_get_stats method {#rpc_nvmf_get_stats} Retrieve current statistics of the NVMf subsystem. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | ------------| ----------- tgt_name | Optional | string | Parent NVMe-oF target name. -### Response +#### Response The response is an object containing NVMf subsystem statistics. In the response, `admin_qpairs` and `io_qpairs` are reflecting cumulative queue pair counts while `current_admin_qpairs` and `current_io_qpairs` are showing the current number. -### Example +#### Example Example request: ~~~ @@ -6945,7 +6945,7 @@ Example response: } ~~~ -## nvmf_set_crdt {#rpc_nvmf_set_crdt} +### nvmf_set_crdt {#rpc_nvmf_set_crdt} Set the 3 CRDT (Command Retry Delay Time) values. For details about CRDT, please refer to the NVMe specification. Currently all the @@ -6953,7 +6953,7 @@ SPDK nvmf subsystems share the same CRDT values. The default values are 0. This rpc can only be invoked in STARTUP stage. All values are in units of 100 milliseconds (same as the NVMe specification). -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6961,7 +6961,7 @@ crdt1 | Optional | number | Command Retry Delay Time 1 crdt2 | Optional | number | Command Retry Delay Time 2 crdt3 | Optional | number | Command Retry Delay Time 3 -# Vhost Target {#jsonrpc_components_vhost_tgt} +## Vhost Target {#jsonrpc_components_vhost_tgt} The following common preconditions need to be met in all target types. @@ -6971,14 +6971,14 @@ directory path needs to be valid UNIX socket name. @ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. It must be a subset of application CPU mask. Default value is CPU mask of the application. -## vhost_controller_set_coalescing {#rpc_vhost_controller_set_coalescing} +### vhost_controller_set_coalescing {#rpc_vhost_controller_set_coalescing} Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 32 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower than 150us. To disable coalescing set `delay_base_us` to 0. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -6986,7 +6986,7 @@ ctrlr | Required | string | Controller name delay_base_us | Required | number | Base (minimum) coalescing time in microseconds iops_threshold | Required | number | Coalescing activation level greater than 0 in IO per second -### Example +#### Example Example request: @@ -7013,18 +7013,18 @@ Example response: } ~~~ -## vhost_create_scsi_controller {#rpc_vhost_create_scsi_controller} +### vhost_create_scsi_controller {#rpc_vhost_create_scsi_controller} Construct vhost SCSI target. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- ctrlr | Required | string | Controller name cpumask | Optional | string | @ref cpu_mask for this controller -### Example +#### Example Example request: @@ -7050,11 +7050,11 @@ Example response: } ~~~ -## vhost_scsi_controller_add_target {#rpc_vhost_scsi_controller_add_target} +### vhost_scsi_controller_add_target {#rpc_vhost_scsi_controller_add_target} In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -7062,11 +7062,11 @@ ctrlr | Required | string | Controller name scsi_target_num | Required | number | SCSI target ID between 0 and 7 or -1 to use first free ID. bdev_name | Required | string | Name of bdev to expose as a LUN 0 -### Response +#### Response SCSI target ID. -### Example +#### Example Example request: @@ -7094,20 +7094,20 @@ response: } ~~~ -## vhost_scsi_controller_remove_target {#rpc_vhost_scsi_controller_remove_target} +### vhost_scsi_controller_remove_target {#rpc_vhost_scsi_controller_remove_target} Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`. This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated). -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- ctrlr | Required | string | Controller name scsi_target_num | Required | number | SCSI target ID between 0 and 7 -### Example +#### Example Example request: @@ -7134,14 +7134,14 @@ Example response: } ~~~ -## vhost_create_blk_controller {#rpc_vhost_create_blk_controller} +### vhost_create_blk_controller {#rpc_vhost_create_blk_controller} Create vhost block controller If `readonly` is `true` then vhost block target will be created as read only and fail any write requests. The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -7150,7 +7150,7 @@ bdev_name | Required | string | Name of bdev to expose block readonly | Optional | boolean | If true, this target will be read only (default: false) cpumask | Optional | string | @ref cpu_mask for this controller -### Example +#### Example Example request: @@ -7176,11 +7176,11 @@ Example response: } ~~~ -## vhost_get_controllers {#rpc_vhost_get_controllers} +### vhost_get_controllers {#rpc_vhost_get_controllers} Display information about all or specific vhost controller(s). -### Parameters +#### Parameters The user may specify no parameters in order to list all controllers, or a controller may be specified by name. @@ -7189,7 +7189,7 @@ Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Optional | string | Vhost controller name -### Response {#rpc_vhost_get_controllers_response} +#### Response {#rpc_vhost_get_controllers_response} Response is an array of objects describing requested controller(s). Common fields are: @@ -7239,7 +7239,7 @@ Name | Type | Description nsid | number | Namespace ID bdev | string | Backing bdev name -### Example +#### Example Example request: @@ -7324,20 +7324,20 @@ Example response: } ~~~ -## vhost_delete_controller {#rpc_vhost_delete_controller} +### vhost_delete_controller {#rpc_vhost_delete_controller} Remove vhost target. This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_vhost_scsi_controller_remove_target. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- ctrlr | Required | string | Controller name -### Example +#### Example Example request: @@ -7362,7 +7362,7 @@ Example response: } ~~~ -# Logical Volume {#jsonrpc_components_lvol} +## Logical Volume {#jsonrpc_components_lvol} Identification of logical volume store and logical volume is explained first. @@ -7378,11 +7378,11 @@ The alias of the logical volume takes the format _lvs_name/lvol_name_ where: * _lvs_name_ is the name of the logical volume store. * _lvol_name_ is specified on creation and can be renamed. -## bdev_lvol_create_lvstore {#rpc_bdev_lvol_create_lvstore} +### bdev_lvol_create_lvstore {#rpc_bdev_lvol_create_lvstore} Construct a logical volume store. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -7391,11 +7391,11 @@ lvs_name | Required | string | Name of the logical volume st cluster_sz | Optional | number | Cluster size of the logical volume store in bytes clear_method | Optional | string | Change clear method for data region. Available: none, unmap (default), write_zeroes -### Response +#### Response UUID of the created logical volume store is returned. -### Example +#### Example Example request: @@ -7422,11 +7422,11 @@ Example response: } ~~~ -## bdev_lvol_delete_lvstore {#rpc_bdev_lvol_delete_lvstore} +### bdev_lvol_delete_lvstore {#rpc_bdev_lvol_delete_lvstore} Destroy a logical volume store. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -7435,7 +7435,7 @@ lvs_name | Optional | string | Name of the logical volume st Either uuid or lvs_name must be specified, but not both. -### Example +#### Example Example request: @@ -7460,11 +7460,11 @@ Example response: } ~~~ -## bdev_lvol_get_lvstores {#rpc_bdev_lvol_get_lvstores} +### bdev_lvol_get_lvstores {#rpc_bdev_lvol_get_lvstores} Get a list of logical volume stores. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -7474,7 +7474,7 @@ lvs_name | Optional | string | Name of the logical volume st Either uuid or lvs_name may be specified, but not both. If both uuid and lvs_name are omitted, information about all logical volume stores is returned. -### Example +#### Example Example request: @@ -7509,18 +7509,18 @@ Example response: } ~~~ -## bdev_lvol_rename_lvstore {#rpc_bdev_lvol_rename_lvstore} +### bdev_lvol_rename_lvstore {#rpc_bdev_lvol_rename_lvstore} Rename a logical volume store. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- old_name | Required | string | Existing logical volume store name new_name | Required | string | New logical volume store name -### Example +#### Example Example request: @@ -7546,11 +7546,11 @@ Example response: } ~~~ -## bdev_lvol_create {#rpc_bdev_lvol_create} +### bdev_lvol_create {#rpc_bdev_lvol_create} Create a logical volume on a logical volume store. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -7564,11 +7564,11 @@ clear_method | Optional | string | Change default data clusters Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. lvol_name will be used in the alias of the created logical volume. -### Response +#### Response UUID of the created logical volume is returned. -### Example +#### Example Example request: @@ -7597,22 +7597,22 @@ Example response: } ~~~ -## bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} +### bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} Capture a snapshot of the current state of a logical volume. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from snapshot_name | Required | string | Name for the newly created snapshot -### Response +#### Response UUID of the created logical volume snapshot is returned. -### Example +#### Example Example request: @@ -7638,22 +7638,22 @@ Example response: } ~~~ -## bdev_lvol_clone {#rpc_bdev_lvol_clone} +### bdev_lvol_clone {#rpc_bdev_lvol_clone} Create a logical volume based on a snapshot. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- snapshot_name | Required | string | UUID or alias of the snapshot to clone clone_name | Required | string | Name for the logical volume to create -### Response +#### Response UUID of the created logical volume clone is returned. -### Example +#### Example Example request: @@ -7679,18 +7679,18 @@ Example response: } ~~~ -## bdev_lvol_rename {#rpc_bdev_lvol_rename} +### bdev_lvol_rename {#rpc_bdev_lvol_rename} Rename a logical volume. New name will rename only the alias of the logical volume. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- old_name | Required | string | UUID or alias of the existing logical volume new_name | Required | string | New logical volume name -### Example +#### Example Example request: @@ -7716,18 +7716,18 @@ Example response: } ~~~ -## bdev_lvol_resize {#rpc_bdev_lvol_resize} +### bdev_lvol_resize {#rpc_bdev_lvol_resize} Resize a logical volume. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | UUID or alias of the logical volume to resize size | Required | number | Desired size of the logical volume in bytes -### Example +#### Example Example request: @@ -7753,17 +7753,17 @@ Example response: } ~~~ -## bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} +### bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} Mark logical volume as read only. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | UUID or alias of the logical volume to set as read only -### Example +#### Example Example request: @@ -7788,17 +7788,17 @@ Example response: } ~~~ -## bdev_lvol_delete {#rpc_bdev_lvol_delete} +### bdev_lvol_delete {#rpc_bdev_lvol_delete} Destroy a logical volume. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | UUID or alias of the logical volume to destroy -### Example +#### Example Example request: @@ -7823,7 +7823,7 @@ Example response: } ~~~ -## bdev_lvol_inflate {#rpc_bdev_lvol_inflate} +### bdev_lvol_inflate {#rpc_bdev_lvol_inflate} Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled if not allocated in the parent. Then all dependencies on the parent are removed. @@ -7834,7 +7834,7 @@ Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | UUID or alias of the logical volume to inflate -### Example +#### Example Example request: @@ -7859,19 +7859,19 @@ Example response: } ~~~ -## bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} +### bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, they are kept thin provisioned. Then all dependencies on the parent are removed. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | UUID or alias of the logical volume to decouple the parent of it -### Example +#### Example Example request: @@ -7896,9 +7896,9 @@ Example response: } ~~~ -# RAID +## RAID -## bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} +### bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} This is used to list all the raid bdev names based on the input category requested. Category should be one of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or @@ -7907,13 +7907,13 @@ the raid bdev which does not have full configuration discovered yet. 'offline' i not registered with bdev as of now and it has encountered any error or user has requested to offline the raid bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- category | Required | string | all or online or configuring or offline -### Example +#### Example Example request: @@ -7940,11 +7940,11 @@ Example response: } ~~~ -## bdev_raid_create {#rpc_bdev_raid_create} +### bdev_raid_create {#rpc_bdev_raid_create} Constructs new RAID bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -7953,7 +7953,7 @@ strip_size_kb | Required | number | Strip size in KB raid_level | Required | string | RAID level base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes -### Example +#### Example Example request: @@ -7986,17 +7986,17 @@ Example response: } ~~~ -## bdev_raid_delete {#rpc_bdev_raid_delete} +### bdev_raid_delete {#rpc_bdev_raid_delete} Removes RAID bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | RAID bdev name -### Example +#### Example Example request: @@ -8021,13 +8021,13 @@ Example response: } ~~~ -# SPLIT +## SPLIT -## bdev_split_create {#rpc_bdev_split_create} +### bdev_split_create {#rpc_bdev_split_create} This is used to split an underlying block device and create several smaller equal-sized vbdevs. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -8035,7 +8035,7 @@ base_bdev | Required | string | base bdev name split_count | Required | number | number of splits split_size_mb | Optional | number | size in MB to restrict the size -### Example +#### Example Example request: @@ -8066,17 +8066,17 @@ Example response: } ~~~ -## bdev_split_delete {#rpc_bdev_split_delete} +### bdev_split_delete {#rpc_bdev_split_delete} This is used to remove the split vbdevs. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- base_bdev | Required | string | base bdev name -### Example +#### Example Example request: @@ -8101,13 +8101,13 @@ Example response: } ~~~ -# Uring +## Uring -## bdev_uring_create {#rpc_bdev_uring_create} +### bdev_uring_create {#rpc_bdev_uring_create} Create a bdev with io_uring backend. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -8115,7 +8115,7 @@ filename | Required | string | path to device or file (ex: / name | Required | string | name of bdev block_size | Optional | number | block size of device (If omitted, get the block size from the file) -### Example +#### Example Example request: @@ -8142,17 +8142,17 @@ Example response: } ~~~ -## bdev_uring_delete {#rpc_bdev_uring_delete} +### bdev_uring_delete {#rpc_bdev_uring_delete} Remove a uring bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- name | Required | string | name of uring bdev to delete -### Example +#### Example Example request: @@ -8177,20 +8177,20 @@ Example response: } ~~~ -# OPAL +## OPAL -## bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} +### bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- nvme_ctrlr_name | Required | string | name of nvme ctrlr password | Required | string | admin password of OPAL -### Example +#### Example Example request: @@ -8216,18 +8216,18 @@ Example response: } ~~~ -## bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} +### bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} This is used to revert OPAL to its factory settings. Erase all user configuration and data. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- nvme_ctrlr_name | Required | string | name of nvme ctrlr password | Required | string | admin password of OPAL -### Example +#### Example Example request: @@ -8253,11 +8253,11 @@ Example response: } ~~~ -## bdev_opal_create {#rpc_bdev_opal_create} +### bdev_opal_create {#rpc_bdev_opal_create} This is used to create an OPAL virtual bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -8268,11 +8268,11 @@ range_start | Required | number | locking range start LBA range_length | Required | number | locking range length password | Required | string | admin password of OPAL -### Response +#### Response The response is the name of created OPAL virtual bdev. -### Example +#### Example Example request: @@ -8302,22 +8302,22 @@ Example response: } ~~~ -## bdev_opal_get_info {#rpc_bdev_opal_get_info} +### bdev_opal_get_info {#rpc_bdev_opal_get_info} This is used to get information of a given OPAL bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- bdev_name | Required | string | name of OPAL vbdev password | Required | string | admin password -### Response +#### Response The response is the locking info of OPAL virtual bdev. -### Example +#### Example Example request: @@ -8351,18 +8351,18 @@ Example response: } ~~~ -## bdev_opal_delete {#rpc_bdev_opal_delete} +### bdev_opal_delete {#rpc_bdev_opal_delete} This is used to delete OPAL vbdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- bdev_name | Required | string | name of OPAL vbdev password | Required | string | admin password -### Example +#### Example Example request: @@ -8388,12 +8388,12 @@ Example response: } ~~~ -## bdev_opal_new_user {#rpc_bdev_opal_new_user} +### bdev_opal_new_user {#rpc_bdev_opal_new_user} This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. Recalling this for the same opal bdev, only the newest user will have the privilege. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -8402,7 +8402,7 @@ admin_password | Required | string | admin password user_id | Required | number | user ID user_password | Required | string | user password -### Example +#### Example Example request: @@ -8430,11 +8430,11 @@ Example response: } ~~~ -## bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} +### bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} This is used to lock/unlock specific opal bdev providing user ID and password. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -8443,7 +8443,7 @@ user_id | Required | number | user ID password | Required | string | user password lock_state | Required | string | lock state -### Example +#### Example Example request: @@ -8471,21 +8471,21 @@ Example response: } ~~~ -# Notifications +## Notifications -## notify_get_types {#rpc_notify_get_types} +### notify_get_types {#rpc_notify_get_types} Return list of all supported notification types. -### Parameters +#### Parameters None -### Response +#### Response The response is an array of strings - supported RPC notification types. -### Example +#### Example Example request: @@ -8510,21 +8510,21 @@ Example response: } ~~~ -## notify_get_notifications {#notify_get_notifications} +### notify_get_notifications {#notify_get_notifications} Request notifications. Returns array of notifications that happend since the specified id (or first that is available). Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccesible due to being overwritten by new ones. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- id | Optional | number | First Event ID to fetch (default: first available). max | Optional | number | Maximum number of event to return (default: no limit). -### Response +#### Response Response is an array of event objects. @@ -8534,7 +8534,7 @@ id | Optional | number | Event ID. type | Optional | number | Type of the event. ctx | Optional | string | Event context. -### Example +#### Example Example request: @@ -8572,29 +8572,29 @@ Example response: } ~~~ -# Linux Network Block Device (NBD) {#jsonrpc_components_nbd} +## Linux Network Block Device (NBD) {#jsonrpc_components_nbd} SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices and can be accessed using standard utilities like fdisk. In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'. -## nbd_start_disk {#rpc_nbd_start_disk} +### nbd_start_disk {#rpc_nbd_start_disk} Start to export one SPDK bdev as NBD disk -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- bdev_name | Required | string | Bdev name to export nbd_device | Optional | string | NBD device name to assign -### Response +#### Response Path of exported NBD disk -### Example +#### Example Example request: @@ -8620,17 +8620,17 @@ Example response: } ~~~ -## nbd_stop_disk {#rpc_nbd_stop_disk} +### nbd_stop_disk {#rpc_nbd_stop_disk} Stop one NBD disk which is based on SPDK bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- nbd_device | Required | string | NBD device name to stop -### Example +#### Example Example request: @@ -8655,21 +8655,21 @@ Example response: } ~~~ -## nbd_get_disks {#rpc_nbd_get_disks} +### nbd_get_disks {#rpc_nbd_get_disks} Display all or specified NBD device list -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- nbd_device | Optional | string | NBD device name to display -### Response +#### Response The response is an array of exported NBD devices and their corresponding SPDK bdev. -### Example +#### Example Example request: @@ -8700,23 +8700,23 @@ Example response: } ~~~ -# Blobfs {#jsonrpc_components_blobfs} +## Blobfs {#jsonrpc_components_blobfs} -## blobfs_detect {#rpc_blobfs_detect} +### blobfs_detect {#rpc_blobfs_detect} Detect whether a blobfs exists on bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- bdev_name | Required | string | Block device name to detect blobfs -### Response +#### Response True if a blobfs exists on the bdev; False otherwise. -### Example +#### Example Example request: @@ -8741,18 +8741,18 @@ Example response: } ~~~ -## blobfs_create {#rpc_blobfs_create} +### blobfs_create {#rpc_blobfs_create} Build blobfs on bdev. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- bdev_name | Required | string | Block device name to create blobfs cluster_sz | Optional | number | Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M. -### Example +#### Example Example request: @@ -8778,18 +8778,18 @@ Example response: } ~~~ -## blobfs_mount {#rpc_blobfs_mount} +### blobfs_mount {#rpc_blobfs_mount} Mount a blobfs on bdev to one host path through FUSE -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- bdev_name | Required | string | Block device name where the blobfs is mountpoint | Required | string | Mountpoint path in host to mount blobfs -### Example +#### Example Example request: @@ -8815,24 +8815,24 @@ Example response: } ~~~ -## blobfs_set_cache_size {#rpc_blobfs_set_cache_size} +### blobfs_set_cache_size {#rpc_blobfs_set_cache_size} Set cache pool size for blobfs filesystems. This RPC is only permitted when the cache pool is not already initialized. The cache pool is initialized when the first blobfs filesystem is initialized or loaded. It is freed when the all initialized or loaded filesystems are unloaded. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- size_in_mb | Required | number | Cache size in megabytes -### Response +#### Response True if cache size is set successfully; False if failed to set. -### Example +#### Example Example request: @@ -8857,23 +8857,23 @@ Example response: } ~~~ -# Socket layer {#jsonrpc_components_sock} +## Socket layer {#jsonrpc_components_sock} -## sock_impl_get_options {#rpc_sock_impl_get_options} +### sock_impl_get_options {#rpc_sock_impl_get_options} Get parameters for the socket layer implementation. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- impl_name | Required | string | Name of socket implementation, e.g. posix -### Response +#### Response Response is an object with current socket layer options for requested implementation. -### Example +#### Example Example request: @@ -8906,11 +8906,11 @@ Example response: } ~~~ -## sock_impl_set_options {#rpc_sock_impl_set_options} +### sock_impl_set_options {#rpc_sock_impl_set_options} Set parameters for the socket layer implementation. -### Parameters +#### Parameters Name | Optional | Type | Description --------------------------- | -------- | ----------- | ----------- @@ -8923,11 +8923,11 @@ enable_placement_id | Optional | number | Enable or disable placeme enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets -### Response +#### Response True if socket layer options were set successfully. -### Example +#### Example Example request: @@ -8959,21 +8959,21 @@ Example response: } ~~~ -## sock_set_default_impl {#rpc_sock_set_default_impl} +### sock_set_default_impl {#rpc_sock_set_default_impl} Set the default sock implementation. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- impl_name | Required | string | Name of socket implementation, e.g. posix -### Response +#### Response True if the default socket layer configuration was set successfully. -### Example +#### Example Example request: @@ -8998,16 +8998,16 @@ Example response: } ~~~ -# Miscellaneous RPC commands +## Miscellaneous RPC commands -## bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} +### bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. Notice: bdev_nvme_send_cmd requires user to guarentee the correctness of NVMe command itself, and also optional parameters. Illegal command contents or mismatching buffer size may result in unpredictable behavior. -### Parameters +#### Parameters Name | Optional | Type | Description ----------------------- | -------- | ----------- | ----------- @@ -9021,7 +9021,7 @@ data_len | Optional | number | Data length required to trans metadata_len | Optional | number | Metadata length required to transfer from controller to host timeout_ms | Optional | number | Command execution timeout value, in milliseconds -### Response +#### Response Name | Type | Description ----------------------- | ----------- | ----------- @@ -9029,7 +9029,7 @@ cpl | string | NVMe completion queue entry, encoded by data | string | Data transferred from controller to host, encoded by base64 urlsafe metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe -### Example +#### Example Example request: @@ -9062,15 +9062,15 @@ Example response: } ~~~ -## enable_vmd {#rpc_enable_vmd} +### enable_vmd {#rpc_enable_vmd} Enable VMD enumeration. -### Parameters +#### Parameters This method has no parameters. -### Response +#### Response Completion status of enumeration is returned as a boolean. @@ -9096,19 +9096,19 @@ Example response: } ~~~ -## spdk_get_version {#rpc_spdk_get_version} +### spdk_get_version {#rpc_spdk_get_version} Get the version info of the running SPDK application. -### Parameters +#### Parameters This method has no parameters. -### Response +#### Response The response is the version number including major version number, minor version number, patch level number and suffix string. -### Example +#### Example Example request: ~~ diff --git a/doc/libraries.md b/doc/libraries.md index 98d199f7e..10bb5c0a0 100644 --- a/doc/libraries.md +++ b/doc/libraries.md @@ -9,7 +9,7 @@ mixing of SPDK event framework dependent code and lower level libraries. This do is aimed at explaining the structure, naming conventions, versioning scheme, and use cases of the libraries contained in these two directories. -# Directory Structure {#structure} +## Directory Structure {#structure} The SPDK libraries are divided into two directories. The `lib` directory contains the base libraries that compose SPDK. Some of these base libraries define plug-in systems. Instances of those plug-ins are called @@ -17,7 +17,7 @@ modules and are located in the `module` directory. For example, the `spdk_sock` `lib` directory while the implementations of socket abstractions, `sock_posix` and `sock_uring` are contained in the `module` directory. -## lib {#lib} +### lib {#lib} The libraries in the `lib` directory can be readily divided into four categories: @@ -48,7 +48,7 @@ Much like the `spdk_event` library, the `spdk_env_dpdk` library has been archite can be readily replaced by an alternate environment shim. More information on replacing the `spdk_env_dpdk` module and the underlying `dpdk` environment can be found in the [environment](#env_replacement) section. -## module {#module} +### module {#module} The component libraries in the `module` directory represent specific implementations of the base libraries in the `lib` directory. As with the `lib` directory, much care has been taken to avoid dependencies on the @@ -77,11 +77,11 @@ explicitly registered to that library via a constructor. The libraries in the `b directories fall into this category. None of the libraries in this category depend explicitly on the `spdk_event` library. -# Library Conventions {#conventions} +## Library Conventions {#conventions} The SPDK libraries follow strict conventions for naming functions, logging, versioning, and header files. -## Headers {#headers} +### Headers {#headers} All public SPDK header files exist in the `include` directory of the SPDK repository. These headers are divided into two sub-directories. @@ -105,7 +105,7 @@ Other header files contained directly in the `lib` and `module` directories are by source files of their corresponding library. Any symbols intended to be used across libraries need to be included in a header in the `include/spdk_internal` directory. -## Naming Conventions {#naming} +### Naming Conventions {#naming} All public types and functions in SPDK libraries begin with the prefix `spdk_`. They are also typically further namespaced using the spdk library name. The rest of the function or type name describes its purpose. @@ -114,15 +114,15 @@ There are no internal library functions that begin with the `spdk_` prefix. This enforced by the SPDK continuous Integration testing. Functions not intended for use outside of their home library should be namespaced with the name of the library only. -## Map Files {#map} +### Map Files {#map} SPDK libraries can be built as both static and shared object files. To facilitate building libraries as shared objects, each one has a corresponding map file (e.g. `spdk_nvmf` relies on `spdk_nvmf.map`). SPDK libraries not exporting any symbols rely on a blank map file located at `mk/spdk_blank.map`. -# SPDK Shared Objects {#shared_objects} +## SPDK Shared Objects {#shared_objects} -## Shared Object Versioning {#versioning} +### Shared Object Versioning {#versioning} SPDK shared objects follow a semantic versioning pattern with a major and minor version. Any changes which break backwards compatibility (symbol removal or change) will cause a shared object major increment and @@ -141,7 +141,7 @@ Shared objects are versioned independently of one another. This means that `libs with the same suffix are not necessarily compatible with each other. It is important to source all of your SPDK libraries from the same repository and version to ensure inter-library compatibility. -## Linking to Shared Objects {#so_linking} +### Linking to Shared Objects {#so_linking} Shared objects in SPDK are created on a per-library basis. There is a top level `libspdk.so` object which is a linker script. It simply contains references to all of the other spdk shared objects. @@ -172,7 +172,7 @@ itself need to be supplied to the linker. In the examples above, these are `spdk respectively. This was intentional and allows one to easily swap out both the environment and the environment shim. -## Replacing the env abstraction {#env_replacement} +### Replacing the env abstraction {#env_replacement} SPDK depends on an environment abstraction that provides crucial pinned memory management and PCIe bus management operations. The interface for this environment abstraction is defined in the @@ -193,7 +193,7 @@ shim/implementation library system. gcc -o my_app ./my_app.c -lspdk -lcustom_env_shim -lcustom_env_implementation ~~~ -# SPDK Static Objects {#static_objects} +## SPDK Static Objects {#static_objects} SPDK static objects are compiled by default even when no parameters are supplied to the build system. Unlike SPDK shared objects, the filename does not contain any versioning semantics. Linking against diff --git a/doc/lvol.md b/doc/lvol.md index 604240e45..cdfd110e4 100644 --- a/doc/lvol.md +++ b/doc/lvol.md @@ -3,9 +3,9 @@ The Logical Volumes library is a flexible storage space management system. It provides creating and managing virtual block devices with variable size. The SPDK Logical Volume library is built on top of @ref blob. -# Terminology {#lvol_terminology} +## Terminology {#lvol_terminology} -## Logical volume store {#lvs} +### Logical volume store {#lvs} * Shorthand: lvolstore, lvs * Type name: struct spdk_lvol_store @@ -16,7 +16,7 @@ creation, so that it can be uniquely identified from other lvolstores. By default when creating lvol store data region is unmapped. Optional --clear-method parameter can be passed on creation to change that behavior to writing zeroes or performing no operation. -## Logical volume {#lvol} +### Logical volume {#lvol} * Shorthand: lvol * Type name: struct spdk_lvol @@ -24,7 +24,7 @@ on creation to change that behavior to writing zeroes or performing no operation A logical volume is implemented as an SPDK blob created from an lvolstore. An lvol is uniquely identified by its UUID. Lvol additional can have alias name. -## Logical volume block device {#lvol_bdev} +### Logical volume block device {#lvol_bdev} * Shorthand: lvol_bdev * Type name: struct spdk_lvol_bdev @@ -39,7 +39,7 @@ option is enabled, no space is taken from lvol store until data is written to lv By default when deleting lvol bdev or resizing down, allocated clusters are unmapped. Optional --clear-method parameter can be passed on creation to change that behavior to writing zeroes or performing no operation. -## Thin provisioning {#lvol_thin_provisioning} +### Thin provisioning {#lvol_thin_provisioning} Thin provisioned lvols rely on dynamic cluster allocation (e.g. when the first write operation on a cluster is performed), only space required to store data is used and unallocated clusters are obtained from underlying device (e.g. zeroes_dev). @@ -52,7 +52,7 @@ Sample read operations and the structure of thin provisioned blob are shown on t ![Reading clusters from thin provisioned blob](lvol_thin_provisioning.svg) -## Snapshots and clone {#lvol_snapshots} +### Snapshots and clone {#lvol_snapshots} Logical volumes support snapshots and clones functionality. User may at any given time create snapshot of existing logical volume to save a backup of current volume state. When creating snapshot original volume becomes thin provisioned @@ -74,26 +74,26 @@ A snapshot can be removed only if there is a single clone on top of it. The rela The cluster map of clone and snapshot will be merged and entries for unallocated clusters in the clone will be updated with addresses from the snapshot cluster map. The entire operation modifies metadata only - no data is copied during this process. -## Inflation {#lvol_inflation} +### Inflation {#lvol_inflation} Blobs can be inflated to copy data from backing devices (e.g. snapshots) and allocate all remaining clusters. As a result of this operation all dependencies for the blob are removed. ![Removing backing blob and bdevs relations using inflate call](lvol_inflate_clone_snapshot.svg) -## Decoupling {#lvol_decoupling} +### Decoupling {#lvol_decoupling} Blobs can be decoupled from their parent blob by copying data from backing devices (e.g. snapshots) for all allocated clusters. Remaining unallocated clusters are kept thin provisioned. Note: When decouple is performed, only single dependency is removed. To remove all dependencies in a chain of blobs depending on each other, multiple calls need to be issued. -# Configuring Logical Volumes +## Configuring Logical Volumes There is no static configuration available for logical volumes. All configuration is done trough RPC. Information about logical volumes is kept on block devices. -# RPC overview {#lvol_rpc} +## RPC overview {#lvol_rpc} RPC regarding lvolstore: diff --git a/doc/memory.md b/doc/memory.md index f18af4717..65a6b045d 100644 --- a/doc/memory.md +++ b/doc/memory.md @@ -92,7 +92,7 @@ SPDK must be allocated using spdk_dma_malloc() or its siblings. The buffers must be allocated specifically so that they are pinned and so that physical addresses are known. -# IOMMU Support +## IOMMU Support Many platforms contain an extra piece of hardware called an I/O Memory Management Unit (IOMMU). An IOMMU is much like a regular MMU, except it diff --git a/doc/notify.md b/doc/notify.md index 7c52244e3..75fcf4cfa 100644 --- a/doc/notify.md +++ b/doc/notify.md @@ -9,32 +9,32 @@ do not poll frequently enough, events may be lost. All events are identified by monotonically increasing integer, so missing events may be detected, although not recovered. -# Register event types {#notify_register} +## Register event types {#notify_register} During initialization the sender library should register its own event types using `spdk_notify_type_register(const char *type)`. Parameter 'type' is the name of notification type. -# Get info about events {#notify_get_info} +## Get info about events {#notify_get_info} A consumer can get information about the available event types during runtime using `spdk_notify_foreach_type`, which iterates over registered notification types and calls a callback on each of them, so that user can produce detailed information about notification. -# Get new events {#notify_listen} +## Get new events {#notify_listen} A consumer can get events by calling function `spdk_notify_foreach_event`. The caller should specify last received event and the maximum number of invocations. There might be multiple consumers of each event. The event bus is implemented as a circular buffer, so older events may be overwritten by newer ones. -# Send events {#notify_send} +## Send events {#notify_send} When an event occurs, a library can invoke `spdk_notify_send` with two strings. One containing the type of the event, like "spdk_bdev_register", second with context, for example "Nvme0n1" -# RPC Calls {#rpc_calls} +## RPC Calls {#rpc_calls} See [JSON-RPC documentation](jsonrpc.md/#rpc_notify_get_types) diff --git a/doc/nvme.md b/doc/nvme.md index 45c6aa4ba..5536589c3 100644 --- a/doc/nvme.md +++ b/doc/nvme.md @@ -1,6 +1,6 @@ # NVMe Driver {#nvme} -# In this document {#nvme_toc} +## In this document {#nvme_toc} - @ref nvme_intro - @ref nvme_examples @@ -11,7 +11,7 @@ - @ref nvme_hotplug - @ref nvme_cuse -# Introduction {#nvme_intro} +## Introduction {#nvme_intro} The NVMe driver is a C library that may be linked directly into an application that provides direct, zero-copy data transfer to and from @@ -29,23 +29,23 @@ devices via NVMe over Fabrics. Users may now call spdk_nvme_probe() on both local PCI busses and on remote NVMe over Fabrics discovery services. The API is otherwise unchanged. -# Examples {#nvme_examples} +## Examples {#nvme_examples} -## Getting Start with Hello World {#nvme_helloworld} +### Getting Start with Hello World {#nvme_helloworld} There are a number of examples provided that demonstrate how to use the NVMe library. They are all in the [examples/nvme](https://github.com/spdk/spdk/tree/master/examples/nvme) directory in the repository. The best place to start is [hello_world](https://github.com/spdk/spdk/blob/master/examples/nvme/hello_world/hello_world.c). -## Running Benchmarks with Fio Plugin {#nvme_fioplugin} +### Running Benchmarks with Fio Plugin {#nvme_fioplugin} SPDK provides a plugin to the very popular [fio](https://github.com/axboe/fio) tool for running some basic benchmarks. See the fio start up [guide](https://github.com/spdk/spdk/blob/master/examples/nvme/fio_plugin/) for more details. -## Running Benchmarks with Perf Tool {#nvme_perf} +### Running Benchmarks with Perf Tool {#nvme_perf} NVMe perf utility in the [examples/nvme/perf](https://github.com/spdk/spdk/tree/master/examples/nvme/perf) is one of the examples which also can be used for performance tests. The fio @@ -79,7 +79,7 @@ perf -q 1 -o 4096 -w write -r 'trtype:PCIe traddr:0000:04:00.0' -t 300 -e 'PRACT perf -q 1 -o 4096 -w read -r 'trtype:PCIe traddr:0000:04:00.0' -t 200 -e 'PRACT=0,PRCKH=GUARD' ~~~ -# Public Interface {#nvme_interface} +## Public Interface {#nvme_interface} - spdk/nvme.h @@ -103,9 +103,9 @@ spdk_nvme_ctrlr_process_admin_completions() | @copybrief spdk_nvme_ctrlr_process spdk_nvme_ctrlr_cmd_io_raw() | @copybrief spdk_nvme_ctrlr_cmd_io_raw() spdk_nvme_ctrlr_cmd_io_raw_with_md() | @copybrief spdk_nvme_ctrlr_cmd_io_raw_with_md() -# NVMe Driver Design {#nvme_design} +## NVMe Driver Design {#nvme_design} -## NVMe I/O Submission {#nvme_io_submission} +### NVMe I/O Submission {#nvme_io_submission} I/O is submitted to an NVMe namespace using nvme_ns_cmd_xxx functions. The NVMe driver submits the I/O request as an NVMe submission queue entry on the queue @@ -117,7 +117,7 @@ spdk_nvme_qpair_process_completions(). @sa 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 -### Fused operations {#nvme_fuses} +#### Fused operations {#nvme_fuses} To "fuse" two commands, the first command should have the SPDK_NVME_IO_FLAGS_FUSE_FIRST io flag set, and the next one should have the SPDK_NVME_IO_FLAGS_FUSE_SECOND. @@ -149,7 +149,7 @@ The NVMe specification currently defines compare-and-write as a fused operation. Support for compare-and-write is reported by the controller flag SPDK_NVME_CTRLR_COMPARE_AND_WRITE_SUPPORTED. -### Scaling Performance {#nvme_scaling} +#### Scaling Performance {#nvme_scaling} NVMe queue pairs (struct spdk_nvme_qpair) provide parallel submission paths for I/O. I/O may be submitted on multiple queue pairs simultaneously from different @@ -182,7 +182,7 @@ require that data should be done by sending a request to the owning thread. This results in a message passing architecture, as opposed to a locking architecture, and will result in superior scaling across CPU cores. -## NVMe Driver Internal Memory Usage {#nvme_memory_usage} +### NVMe Driver Internal Memory Usage {#nvme_memory_usage} The SPDK NVMe driver provides a zero-copy data transfer path, which means that there are no data buffers for I/O commands. However, some Admin commands have @@ -202,12 +202,12 @@ Each submission queue entry (SQE) and completion queue entry (CQE) consumes 64 b and 16 bytes respectively. Therefore, the maximum memory used for each I/O queue pair is (MQES + 1) * (64 + 16) Bytes. -# NVMe over Fabrics Host Support {#nvme_fabrics_host} +## NVMe over Fabrics Host Support {#nvme_fabrics_host} The NVMe driver supports connecting to remote NVMe-oF targets and interacting with them in the same manner as local NVMe SSDs. -## Specifying Remote NVMe over Fabrics Targets {#nvme_fabrics_trid} +### Specifying Remote NVMe over Fabrics Targets {#nvme_fabrics_trid} The method for connecting to a remote NVMe-oF target is very similar to the normal enumeration process for local PCIe-attached NVMe devices. @@ -228,11 +228,11 @@ single NVM subsystem directly, the NVMe library will call `probe_cb` for just that subsystem; this allows the user to skip the discovery step and connect directly to a subsystem with a known address. -## RDMA Limitations +### RDMA Limitations Please refer to NVMe-oF target's @ref nvmf_rdma_limitations -# NVMe Multi Process {#nvme_multi_process} +## NVMe Multi Process {#nvme_multi_process} This capability enables the SPDK NVMe driver to support multiple processes accessing the same NVMe device. The NVMe driver allocates critical structures from shared memory, so @@ -243,7 +243,7 @@ The primary motivation for this feature is to support management tools that can to long running applications, perform some maintenance work or gather information, and then detach. -## Configuration {#nvme_multi_process_configuration} +### Configuration {#nvme_multi_process_configuration} DPDK EAL allows different types of processes to be spawned, each with different permissions on the hugepage memory used by the applications. @@ -269,7 +269,7 @@ Example: identical shm_id and non-overlapping core masks ./perf -q 8 -o 131072 -w write -c 0x10 -t 60 -i 1 ~~~ -## Limitations {#nvme_multi_process_limitations} +### Limitations {#nvme_multi_process_limitations} 1. Two processes sharing memory may not share any cores in their core mask. 2. If a primary process exits while secondary processes are still running, those processes @@ -280,7 +280,7 @@ Example: identical shm_id and non-overlapping core masks @sa spdk_nvme_probe, spdk_nvme_ctrlr_process_admin_completions -# NVMe Hotplug {#nvme_hotplug} +## NVMe Hotplug {#nvme_hotplug} At the NVMe driver level, we provide the following support for Hotplug: @@ -300,11 +300,11 @@ At the NVMe driver level, we provide the following support for Hotplug: @sa spdk_nvme_probe -# NVMe Character Devices {#nvme_cuse} +## NVMe Character Devices {#nvme_cuse} This feature is considered as experimental. -## Design +### Design ![NVMe character devices processing diagram](nvme_cuse.svg) @@ -326,9 +326,9 @@ immediate response, without passing them through the ring. This interface reserves one additional qpair for sending down the I/O for each controller. -## Usage +### Usage -### Enabling cuse support for NVMe +#### Enabling cuse support for NVMe Cuse support is disabled by default. To enable support for NVMe-CUSE devices first install required dependencies @@ -337,7 +337,7 @@ sudo scripts/pkgdep.sh --fuse ~~~ Then compile SPDK with "./configure --with-nvme-cuse". -### Creating NVMe-CUSE device +#### Creating NVMe-CUSE device First make sure to prepare the environment (see @ref getting_started). This includes loading CUSE kernel module. @@ -367,7 +367,7 @@ $ ls /dev/spdk/ nvme0 nvme0n1 ~~~ -### Example of using nvme-cli +#### Example of using nvme-cli Most nvme-cli commands can point to specific controller or namespace by providing a path to it. This can be leveraged to issue commands to the SPDK NVMe-CUSE devices. @@ -381,7 +381,7 @@ sudo nvme id-ns /dev/spdk/nvme0n1 Note: `nvme list` command does not display SPDK NVMe-CUSE devices, see nvme-cli [PR #773](https://github.com/linux-nvme/nvme-cli/pull/773). -### Examples of using smartctl +#### Examples of using smartctl smartctl tool recognizes device type based on the device path. If none of expected patterns match, SCSI translation layer is used to identify device. @@ -395,7 +395,7 @@ the NVMe device. ... ~~~ -## Limitations +### Limitations NVMe namespaces are created as character devices and their use may be limited for tools expecting block devices. diff --git a/doc/nvmf.md b/doc/nvmf.md index e7b0fea70..34fecae58 100644 --- a/doc/nvmf.md +++ b/doc/nvmf.md @@ -3,7 +3,7 @@ @sa @ref nvme_fabrics_host @sa @ref nvmf_tgt_tracepoints -# NVMe-oF Target Getting Started Guide {#nvmf_getting_started} +## NVMe-oF Target Getting Started Guide {#nvmf_getting_started} The SPDK NVMe over Fabrics target is a user space application that presents block devices over a fabrics such as Ethernet, Infiniband or Fibre Channel. SPDK currently supports RDMA and TCP transports. diff --git a/doc/nvmf_tracing.md b/doc/nvmf_tracing.md index 71d540724..da19ad7ac 100644 --- a/doc/nvmf_tracing.md +++ b/doc/nvmf_tracing.md @@ -1,6 +1,6 @@ # NVMe-oF Target Tracepoints {#nvmf_tgt_tracepoints} -# Introduction {#tracepoints_intro} +## Introduction {#tracepoints_intro} SPDK has a tracing framework for capturing low-level event information at runtime. Tracepoints provide a high-performance tracing mechanism that is accessible at runtime. @@ -9,7 +9,7 @@ processes. The NVMe-oF target is instrumented with tracepoints to enable analysi both performance and application crashes. (Note: the SPDK tracing framework should still be considered experimental. Work to formalize and document the framework is in progress.) -# Enabling Tracepoints {#enable_tracepoints} +## Enabling Tracepoints {#enable_tracepoints} Tracepoints are placed in groups. They are enabled and disabled as a group. To enable the instrumentation of all the tracepoints group in an SPDK target application, start the @@ -41,7 +41,7 @@ exits. This ensures the file can be used for analysis after the application exi shared memory files are in /dev/shm, and can be deleted manually to free shm space if needed. A system reboot will also free all of the /dev/shm files. -# Capturing a snapshot of events {#capture_tracepoints} +## Capturing a snapshot of events {#capture_tracepoints} Send I/Os to the SPDK target application to generate events. The following is an example usage of perf to send I/Os to the NVMe-oF target over an RDMA network @@ -124,7 +124,7 @@ the same I/O. 28: 6033.056 ( 12669500) RDMA_REQ_COMPLETED id: r3564 time: 100.211 ~~~ -# Capturing sufficient trace events {#capture_trace_events} +## Capturing sufficient trace events {#capture_trace_events} Since the tracepoint file generated directly by SPDK application is a circular buffer in shared memory, the trace events captured by it may be insufficient for further analysis. @@ -150,7 +150,7 @@ To analyze the tracepoints output file from spdk_trace_record, simply run spdk_t build/bin/spdk_trace -f /tmp/spdk_nvmf_record.trace ~~~ -# Adding New Tracepoints {#add_tracepoints} +## Adding New Tracepoints {#add_tracepoints} SPDK applications and libraries provide several trace points. You can add new tracepoints to the existing trace groups. For example, to add a new tracepoints diff --git a/doc/overview.md b/doc/overview.md index a34bc25fb..2e3cb2737 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -1,6 +1,6 @@ # SPDK Structural Overview {#overview} -# Overview {#dir_overview} +## Overview {#dir_overview} SPDK is composed of a set of C libraries residing in `lib` with public interface header files in `include/spdk`, plus a set of applications built out of those diff --git a/doc/peer_2_peer.md b/doc/peer_2_peer.md index 11fdc77e6..82165f908 100644 --- a/doc/peer_2_peer.md +++ b/doc/peer_2_peer.md @@ -3,14 +3,14 @@ Please note that the functionality discussed in this document is currently tagged as experimental. -# In this document {#p2p_toc} +## In this document {#p2p_toc} * @ref p2p_overview * @ref p2p_nvme_api * @ref p2p_cmb_copy * @ref p2p_issues -# Overview {#p2p_overview} +## Overview {#p2p_overview} Peer-2-Peer (P2P) is the concept of DMAing data directly from one PCI End Point (EP) to another without using a system memory buffer. The @@ -22,7 +22,7 @@ In this section of documentation we outline how to perform P2P operations in SPDK and outline some of the issues that can occur when performing P2P operations. -# The P2P API for NVMe {#p2p_nvme_api} +## The P2P API for NVMe {#p2p_nvme_api} The functions that provide access to the NVMe CMBs for P2P capabilities are given in the table below. @@ -33,7 +33,7 @@ spdk_nvme_ctrlr_map_cmb() | @copybrief spdk_nvme_ctrlr_map_cmb spdk_nvme_ctrlr_unmap_cmb() | @copybrief spdk_nvme_ctrlr_unmap_cmb() spdk_nvme_ctrlr_get_regs_cmbsz() | @copybrief spdk_nvme_ctrlr_get_regs_cmbsz() -# Determining device support {#p2p_support} +## Determining device support {#p2p_support} SPDK's identify example application displays whether a device has a controller memory buffer and which operations it supports. Run it as follows: @@ -42,7 +42,7 @@ memory buffer and which operations it supports. Run it as follows: ./build/examples/identify -r traddr: ~~~ -# cmb_copy: An example P2P Application {#p2p_cmb_copy} +## cmb_copy: An example P2P Application {#p2p_cmb_copy} Run the cmb_copy example application. @@ -53,7 +53,7 @@ This should copy a single LBA (LBA 0) from namespace 1 on the read NVMe SSD to LBA 0 on namespace 1 on the write SSD using the CMB as the DMA buffer. -# Issues with P2P {#p2p_issues} +## Issues with P2P {#p2p_issues} * In some systems when performing peer-2-peer DMAs between PCIe EPs that are directly connected to the Root Complex (RC) the DMA may diff --git a/doc/rpm.md b/doc/rpm.md index 503198716..a8b38c789 100644 --- a/doc/rpm.md +++ b/doc/rpm.md @@ -1,10 +1,10 @@ # RPMs {#rpms} -# In this document {#rpms_toc} +## In this document {#rpms_toc} * @ref building_rpms -# Building SPDK RPMs {#building_rpms} +## Building SPDK RPMs {#building_rpms} To build basic set of RPM packages out of the SPDK repo simply run: diff --git a/doc/shfmt.md b/doc/shfmt.md index 31cc4dae4..c4aae79ad 100644 --- a/doc/shfmt.md +++ b/doc/shfmt.md @@ -1,13 +1,13 @@ # shfmt {#shfmt} -# In this document {#shfmt_toc} +## In this document {#shfmt_toc} * @ref shfmt_overview * @ref shfmt_usage * @ref shfmt_installation * @ref shfmt_examples -# Overview {#shfmt_overview} +## Overview {#shfmt_overview} The majority of tests (and scripts overall) in the SPDK repo are written in Bash (with a quite significant emphasis on "Bashism"), thus a style @@ -15,7 +15,7 @@ formatter, shfmt, was introduced to help keep the .sh code consistent across the entire repo. For more details on the tool itself, please see [shfmt](https://github.com/mvdan/sh). -# Usage {#shfmt_usage} +## Usage {#shfmt_usage} On the CI pool, the shfmt is run against all the updated .sh files that have been committed but not merged yet. Additionally, shfmt will pick @@ -36,7 +36,7 @@ Please, see ./scripts/check_format.sh for all the arguments the shfmt is run with. Additionally, @ref shfmt_examples has more details on how each of the arguments behave. -# Installation {#shfmt_installation} +## Installation {#shfmt_installation} The shfmt can be easily installed via pkgdep.sh: @@ -55,7 +55,7 @@ SHFMT_DIR_OUT=/and_link_it_here \ ./scripts/pkgdep.sh -d ~~~ -# Examples {#shfmt_examples} +## Examples {#shfmt_examples} ~~~{.sh} ####################################### diff --git a/doc/spdk_top.md b/doc/spdk_top.md index 9d2b497b7..3d15a970c 100644 --- a/doc/spdk_top.md +++ b/doc/spdk_top.md @@ -15,7 +15,7 @@ spdk_top utility gets the fine grained metrics from the pollers, analyzes and re This information enables users to identify CPU cores that are busy doing real work so that they can determine if the application needs more or less CPU resources. -# Run spdk_top +## Run spdk_top Before running spdk_top you need to run the SPDK application whose performance you want to analyze using spdk_top. @@ -25,7 +25,7 @@ Run the spdk_top application ./build/bin/spdk_top ~~~ -# Bottom menu +## Bottom menu Menu at the bottom of SPDK top window shows many options for changing displayed data. Each menu item has a key associated with it in square brackets. @@ -36,7 +36,7 @@ of all available pages. * Item details - displays details pop-up window for highlighted data row. Selection is changed by pressing UP and DOWN arrow keys. * Help - displays help pop-up window. -# Threads Tab +## Threads Tab The threads tab displays a line item for each spdk thread. The information displayed shows: @@ -52,7 +52,7 @@ Pop-up then can be closed by pressing ESC key. To learn more about spdk threads see @ref concurrency. -# Pollers Tab +## Pollers Tab The pollers tab displays a line item for each poller. The information displayed shows: @@ -67,7 +67,7 @@ The pollers tab displays a line item for each poller. The information displayed Poller pop-up window can be displayed by pressing ENTER on a selected data row and displays above information. Pop-up can be closed by pressing ESC key. -# Cores Tab +## Cores Tab The cores tab provides insights into how the application is using the CPU cores assigned to it. The information displayed for each core shows: @@ -81,6 +81,6 @@ The cores tab provides insights into how the application is using the CPU cores Pressing ENTER key makes a pop-up window appear, showing above information, along with a list of threads running on selected core. Cores details window allows to select a thread and display thread details pop-up on top of it. To close both pop-ups use ESC key. -# Help Window +## Help Window Help window pop-up can be invoked by pressing H key inside any tab. It contains explanations for each key used inside the spdk_top application. diff --git a/doc/system_configuration.md b/doc/system_configuration.md index 6a3c08a43..7c594368d 100644 --- a/doc/system_configuration.md +++ b/doc/system_configuration.md @@ -2,7 +2,7 @@ This system configuration guide describes how to configure a system for use with SPDK. -# IOMMU configuration {#iommu_config} +## IOMMU configuration {#iommu_config} An IOMMU may be present and enabled on many platforms. When an IOMMU is present and enabled, it is recommended that SPDK applications are deployed with the `vfio-pci` kernel driver. SPDK's @@ -21,7 +21,7 @@ version they are using has a bug where `uio_pci_generic` [fails to bind to NVMe In these cases, users can build the `igb_uio` kernel module which can be found in dpdk-kmods repository. To ensure that the driver is properly bound, users should specify `DRIVER_OVERRIDE=/path/to/igb_uio.ko`. -# Running SPDK as non-priviledged user {#system_configuration_nonroot} +## Running SPDK as non-priviledged user {#system_configuration_nonroot} One of the benefits of using the `VFIO` Linux kernel driver is the ability to perform DMA operations with peripheral devices as unprivileged user. The @@ -29,7 +29,7 @@ permissions to access particular devices still need to be granted by the system administrator, but only on a one-time basis. Note that this functionality is supported with DPDK starting from version 18.11. -## Hugetlbfs access +### Hugetlbfs access Make sure the target user has RW access to at least one hugepage mount. A good idea is to create a new mount specifically for SPDK: @@ -44,7 +44,7 @@ Then start SPDK applications with an additional parameter `--huge-dir /mnt/spdk_ Full guide on configuring hugepage mounts is available in the [Linux Hugetlbpage Documentation](https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt) -## Device access {#system_configuration_nonroot_device_access} +### Device access {#system_configuration_nonroot_device_access} `VFIO` device access is protected with sysfs file permissions and can be configured with chown/chmod. @@ -86,7 +86,7 @@ devices, use the following: # chown spdk /dev/vfio/5 ~~~ -## Memory constraints {#system_configuration_nonroot_memory_constraints} +### Memory constraints {#system_configuration_nonroot_memory_constraints} As soon as the first device is attached to SPDK, all of SPDK memory will be mapped to the IOMMU through the VFIO APIs. VFIO will try to mlock that memory and @@ -111,7 +111,7 @@ try to map not only its reserved hugepages, but also all the memory that's shared by its vhost clients as described in the [Vhost processing guide](https://spdk.io/doc/vhost_processing.html#vhost_processing_init). -### Increasing the memlock limit permanently +#### Increasing the memlock limit permanently Open the `/etc/security/limits.conf` file as root and append the following: @@ -122,7 +122,7 @@ spdk soft memlock unlimited Then logout from the target user account. The changes will take effect after the next login. -### Increasing the memlock for a specific process +#### Increasing the memlock for a specific process Linux offers a `prlimit` utility that can override limits of any given process. On Ubuntu, it is a part of the `util-linux` package. diff --git a/doc/template_pg.md b/doc/template_pg.md index 535a980c3..93c29a959 100644 --- a/doc/template_pg.md +++ b/doc/template_pg.md @@ -1,6 +1,6 @@ # ComponentName Programmer's Guide {#componentname_pg} -# In this document {#componentname_pg_toc} +## In this document {#componentname_pg_toc} @ref componentname_pg_audience @ref componentname_pg_intro diff --git a/doc/userspace.md b/doc/userspace.md index 54ba1bdfa..df138a2cd 100644 --- a/doc/userspace.md +++ b/doc/userspace.md @@ -1,6 +1,6 @@ # User Space Drivers {#userspace} -# Controlling Hardware From User Space {#userspace_control} +## Controlling Hardware From User Space {#userspace_control} Much of the documentation for SPDK talks about _user space drivers_, so it's important to understand what that means at a technical level. First and @@ -53,7 +53,7 @@ with the [NVMe Specification](http://nvmexpress.org/wp-content/uploads/NVM_Express_Revision_1.3.pdf) to initialize the device, create queue pairs, and ultimately send I/O. -# Interrupts {#userspace_interrupts} +## Interrupts {#userspace_interrupts} SPDK polls devices for completions instead of waiting for interrupts. There are a number of reasons for doing this: 1) practically speaking, routing an @@ -69,7 +69,7 @@ technologies such as Intel's will ensure that the host memory being checked is present in the CPU cache after an update by the device. -# Threading {#userspace_threading} +## Threading {#userspace_threading} NVMe devices expose multiple queues for submitting requests to the hardware. Separate queues can be accessed without coordination, so software can send diff --git a/doc/vagrant.md b/doc/vagrant.md index f362a89d2..0c450e18b 100644 --- a/doc/vagrant.md +++ b/doc/vagrant.md @@ -1,6 +1,6 @@ # Vagrant Development Environment {#vagrant} -# Introduction {#vagrant_intro} +## Introduction {#vagrant_intro} [Vagrant](https://www.vagrantup.com/) provides a quick way to get a basic NVMe enabled virtual machine sandbox running without the need for any @@ -22,7 +22,7 @@ vagrant plugin install vagrant-proxyconf In case you want use kvm/libvirt you should also install `vagrant-libvirt` -# VM Configuration {#vagrant_config} +## VM Configuration {#vagrant_config} To create a configured VM with vagrant you need to run `create_vbox.sh` script. @@ -47,7 +47,7 @@ world example application. vagrant --help ~~~ -# Running An Example {#vagrant_example} +## Running An Example {#vagrant_example} The following shows sample output from starting up a Ubuntu18 VM, compiling SPDK on it and running the NVMe sample application `hello_world`. diff --git a/doc/vhost.md b/doc/vhost.md index 6282bbc2d..52e777d5d 100644 --- a/doc/vhost.md +++ b/doc/vhost.md @@ -1,6 +1,6 @@ # vhost Target {#vhost} -# Table of Contents {#vhost_toc} +## Table of Contents {#vhost_toc} - @ref vhost_intro - @ref vhost_prereqs @@ -11,7 +11,7 @@ - @ref vhost_advanced_topics - @ref vhost_bugs -# Introduction {#vhost_intro} +## Introduction {#vhost_intro} A vhost target provides a local storage service as a process running on a local machine. It is capable of exposing virtualized block devices to QEMU instances or other arbitrary @@ -28,12 +28,12 @@ techniques as other components in SPDK. Since SPDK is polling for vhost submiss it can signal the VM to skip notifications on submission. This avoids VMEXITs on I/O submission and can significantly reduce CPU usage in the VM on heavy I/O workloads. -# Prerequisites {#vhost_prereqs} +## Prerequisites {#vhost_prereqs} This guide assumes the SPDK has been built according to the instructions in @ref getting_started. The SPDK vhost target is built with the default configure options. -## Vhost Command Line Parameters {#vhost_cmd_line_args} +### Vhost Command Line Parameters {#vhost_cmd_line_args} Additional command line flags are available for Vhost target. @@ -41,7 +41,7 @@ Param | Type | Default | Description -------- | -------- | ---------------------- | ----------- -S | string | $PWD | directory where UNIX domain sockets will be created -## Supported Guest Operating Systems +### Supported Guest Operating Systems The guest OS must contain virtio-scsi or virtio-blk drivers. Most Linux and FreeBSD distributions include virtio drivers. @@ -49,7 +49,7 @@ distributions include virtio drivers. installed separately. The SPDK vhost target has been tested with recent versions of Ubuntu, Fedora, and Windows -## QEMU +### QEMU Userspace vhost-scsi target support was added to upstream QEMU in v2.10.0. Run the following command to confirm your QEMU supports userspace vhost-scsi. @@ -74,7 +74,7 @@ Run the following command to confirm your QEMU supports userspace vhost-nvme. qemu-system-x86_64 -device vhost-user-nvme,help ~~~ -# Starting SPDK vhost target {#vhost_start} +## Starting SPDK vhost target {#vhost_start} First, run the SPDK setup.sh script to setup some hugepages for the SPDK vhost target application. This will allocate 4096MiB (4GiB) of hugepages, enough for the SPDK @@ -100,9 +100,9 @@ To list all available vhost options use the following command. build/bin/vhost -h ~~~ -# SPDK Configuration {#vhost_config} +## SPDK Configuration {#vhost_config} -## Create bdev (block device) {#vhost_bdev_create} +### Create bdev (block device) {#vhost_bdev_create} SPDK bdevs are block devices which will be exposed to the guest OS. For vhost-scsi, bdevs are exposed as SCSI LUNs on SCSI devices attached to the @@ -121,9 +121,9 @@ will create a 64MB malloc bdev with 512-byte block size. scripts/rpc.py bdev_malloc_create 64 512 -b Malloc0 ~~~ -## Create a vhost device {#vhost_vdev_create} +### Create a vhost device {#vhost_vdev_create} -### Vhost-SCSI +#### Vhost-SCSI The following RPC will create a vhost-scsi controller which can be accessed by QEMU via /var/tmp/vhost.0. At the time of creation the controller will be @@ -152,7 +152,7 @@ To remove a bdev from a vhost-scsi controller use the following RPC: scripts/rpc.py vhost_scsi_controller_remove_target vhost.0 0 ~~~ -### Vhost-BLK +#### Vhost-BLK The following RPC will create a vhost-blk device exposing Malloc0 bdev. The device will be accessible to QEMU via /var/tmp/vhost.1. All the I/O polling @@ -171,7 +171,7 @@ extra `-r` or `--readonly` parameter. scripts/rpc.py vhost_create_blk_controller --cpumask 0x1 -r vhost.1 Malloc0 ~~~ -## QEMU {#vhost_qemu_config} +### QEMU {#vhost_qemu_config} Now the virtual machine can be started with QEMU. The following command-line parameters must be added to connect the virtual machine to its vhost controller. @@ -195,21 +195,21 @@ SPDK malloc block device by specifying bootindex=0 for the boot image. Finally, specify the SPDK vhost devices: -### Vhost-SCSI +#### Vhost-SCSI ~~~{.sh} -chardev socket,id=char0,path=/var/tmp/vhost.0 -device vhost-user-scsi-pci,id=scsi0,chardev=char0 ~~~ -### Vhost-BLK +#### Vhost-BLK ~~~{.sh} -chardev socket,id=char1,path=/var/tmp/vhost.1 -device vhost-user-blk-pci,id=blk0,chardev=char1 ~~~ -## Example output {#vhost_example} +### Example output {#vhost_example} This example uses an NVMe bdev alongside Mallocs. SPDK vhost application is started on CPU cores 0 and 1, QEMU on cores 2 and 3. @@ -310,9 +310,9 @@ vhost.c:1006:session_shutdown: *NOTICE*: Exiting We can see that `sdb` and `sdc` are SPDK vhost-scsi LUNs, and `vda` is SPDK a vhost-blk disk. -# Advanced Topics {#vhost_advanced_topics} +## Advanced Topics {#vhost_advanced_topics} -## Multi-Queue Block Layer (blk-mq) {#vhost_multiqueue} +### Multi-Queue Block Layer (blk-mq) {#vhost_multiqueue} For best performance use the Linux kernel block multi-queue feature with vhost. To enable it on Linux, it is required to modify kernel options inside the @@ -335,7 +335,7 @@ Some Linux distributions report a kernel panic when starting the VM if the numbe specified via the `num-queues` parameter is greater than number of vCPUs. If you need to use more I/O queues than vCPUs, check that your OS image supports that configuration. -## Hot-attach/hot-detach {#vhost_hotattach} +### Hot-attach/hot-detach {#vhost_hotattach} Hotplug/hotremove within a vhost controller is called hot-attach/detach. This is to distinguish it from SPDK bdev hotplug/hotremove. E.g. if an NVMe bdev is attached @@ -348,7 +348,7 @@ to hot-attach/detach the bdev from a Vhost-BLK device. If Vhost-BLK device expos an NVMe bdev that is hotremoved, all the I/O traffic on that Vhost-BLK device will be aborted - possibly flooding a VM with syslog warnings and errors. -### Hot-attach +#### Hot-attach Hot-attach is done by simply attaching a bdev to a vhost controller with a QEMU VM already started. No other extra action is necessary. @@ -357,7 +357,7 @@ already started. No other extra action is necessary. scripts/rpc.py vhost_scsi_controller_add_target vhost.0 0 Malloc0 ~~~ -### Hot-detach +#### Hot-detach Just like hot-attach, the hot-detach is done by simply removing bdev from a controller when QEMU VM is already started. @@ -372,22 +372,22 @@ Removing an entire bdev will hot-detach it from a controller as well. scripts/rpc.py bdev_malloc_delete Malloc0 ~~~ -# Known bugs and limitations {#vhost_bugs} +## Known bugs and limitations {#vhost_bugs} -## Vhost-NVMe (experimental) can only be supported with latest Linux kernel +### Vhost-NVMe (experimental) can only be supported with latest Linux kernel Vhost-NVMe target was designed for one new feature of NVMe 1.3 specification, Doorbell Buffer Config Admin command, which is used for emulated NVMe controller only. Linux 4.12 added this feature, so a new Guest kernel later than 4.12 is required to test this feature. -## Windows virtio-blk driver before version 0.1.130-1 only works with 512-byte sectors +### Windows virtio-blk driver before version 0.1.130-1 only works with 512-byte sectors The Windows `viostor` driver before version 0.1.130-1 is buggy and does not correctly support vhost-blk devices with non-512-byte block size. See the [bug report](https://bugzilla.redhat.com/show_bug.cgi?id=1411092) for more information. -## QEMU vhost-user-blk +### QEMU vhost-user-blk QEMU [vhost-user-blk](https://git.qemu.org/?p=qemu.git;a=commit;h=00343e4b54ba) is supported from version 2.12. diff --git a/doc/vhost_processing.md b/doc/vhost_processing.md index b37725359..bdf85756a 100644 --- a/doc/vhost_processing.md +++ b/doc/vhost_processing.md @@ -1,6 +1,6 @@ # Virtualized I/O with Vhost-user {#vhost_processing} -# Table of Contents {#vhost_processing_toc} +## Table of Contents {#vhost_processing_toc} - @ref vhost_processing_intro - @ref vhost_processing_qemu @@ -8,7 +8,7 @@ - @ref vhost_processing_io_path - @ref vhost_spdk_optimizations -# Introduction {#vhost_processing_intro} +## Introduction {#vhost_processing_intro} This document is intended to provide an overview of how Vhost works behind the scenes. Code snippets used in this document might have been simplified for the @@ -68,7 +68,7 @@ in the socket communication. SPDK vhost is a Vhost-user slave server. It exposes Unix domain sockets and allows external applications to connect. -# QEMU {#vhost_processing_qemu} +## QEMU {#vhost_processing_qemu} One of major Vhost-user use cases is networking (DPDK) or storage (SPDK) offload in QEMU. The following diagram presents how QEMU-based VM @@ -76,7 +76,7 @@ communicates with SPDK Vhost-SCSI device. ![QEMU/SPDK vhost data flow](img/qemu_vhost_data_flow.svg) -# Device initialization {#vhost_processing_init} +## Device initialization {#vhost_processing_init} All initialization and management information is exchanged using Vhost-user messages. The connection always starts with the feature negotiation. Both @@ -118,7 +118,7 @@ If multiqueue feature has been negotiated, the driver has to send a specific *ENABLE* message for each extra queue it wants to be polled. Other queues are polled as soon as they're initialized. -# I/O path {#vhost_processing_io_path} +## I/O path {#vhost_processing_io_path} The Master sends I/O by allocating proper buffers in shared memory, filling the request data, and putting guest addresses of those buffers into virtqueues. @@ -186,7 +186,7 @@ proper data and interrupts the guest by doing an eventfd_write on the call descriptor for proper virtqueue. There are multiple interrupt coalescing features involved, but they are not be discussed in this document. -## SPDK optimizations {#vhost_spdk_optimizations} +### SPDK optimizations {#vhost_spdk_optimizations} Due to its poll-mode nature, SPDK vhost removes the requirement for I/O submission notifications, drastically increasing the vhost server throughput and decreasing diff --git a/doc/virtio.md b/doc/virtio.md index ae498f23e..95ab1de62 100644 --- a/doc/virtio.md +++ b/doc/virtio.md @@ -1,6 +1,6 @@ # Virtio driver {#virtio} -# Introduction {#virtio_intro} +## Introduction {#virtio_intro} SPDK Virtio driver is a C library that allows communicating with Virtio devices. It allows any SPDK application to become an initiator for (SPDK) vhost targets. @@ -20,7 +20,7 @@ This Virtio library is currently used to implement two bdev modules: @ref bdev_config_virtio_scsi and @ref bdev_config_virtio_blk. These modules will export generic SPDK block devices usable by any SPDK application. -# 2MB hugepages {#virtio_2mb} +## 2MB hugepages {#virtio_2mb} vhost-user specification puts a limitation on the number of "memory regions" used (8). Each region corresponds to one file descriptor, and DPDK - as SPDK's memory allocator - diff --git a/doc/vmd.md b/doc/vmd.md index 4cac5b0e0..464241e06 100644 --- a/doc/vmd.md +++ b/doc/vmd.md @@ -1,6 +1,6 @@ # VMD driver {#vmd} -# In this document {#vmd_toc} +## In this document {#vmd_toc} * @ref vmd_intro * @ref vmd_interface @@ -10,7 +10,7 @@ * @ref vmd_app * @ref vmd_led -# Introduction {#vmd_intro} +## Introduction {#vmd_intro} Intel Volume Management Device is a hardware logic inside processor's Root Complex responsible for management of PCIe NVMe SSDs. It provides robust Hot Plug support @@ -19,11 +19,11 @@ and Status LED management. The driver is responsible for enumeration and hooking NVMe devices behind VMD into SPDK PCIe subsystem. It also provides API for LED management and hot plug. -# Public Interface {#vmd_interface} +## Public Interface {#vmd_interface} - spdk/vmd.h -# Key Functions {#vmd_key_functions} +## Key Functions {#vmd_key_functions} Function | Description --------------------------------------- | ----------- @@ -33,7 +33,7 @@ spdk_vmd_set_led_state() | @copybrief spdk_vmd_set_led_state() spdk_vmd_get_led_state() | @copybrief spdk_vmd_get_led_state() spdk_vmd_hotplug_monitor() | @copybrief spdk_vmd_hotplug_monitor() -# Configuration {#vmd_config} +## Configuration {#vmd_config} To enable VMD driver enumeration, the following steps are required: @@ -75,7 +75,7 @@ Example: $ ./scripts/rpc.py bdev_nvme_attach_controller -b NVMe1 -t PCIe -a 5d0505:01:00.0 ``` -# Application framework {#vmd_app_frame} +## Application framework {#vmd_app_frame} When application framework is used, VMD section needs to be added to the configuration file: @@ -98,7 +98,7 @@ $ ./build/bin/spdk_tgt --wait_for_rpc $ ./scripts/rpc.py enable_vmd $ ./scripts/rpc.py framework_start_init ``` -# Applications w/o application framework {#vmd_app} +## Applications w/o application framework {#vmd_app} To enable VMD enumeration in SPDK application that are not using application framework e.g nvme/perf, nvme/identify -V flag is required - please refer to app help if it supports VMD. @@ -107,7 +107,7 @@ Applications need to call spdk_vmd_init() to enumerate NVMe devices behind the V spdk_nvme_(probe|connect). To support hot plugs spdk_vmd_hotplug_monitor() needs to be called periodically. -# LED management {#vmd_led} +## LED management {#vmd_led} VMD LED utility in the [examples/vmd/led](https://github.com/spdk/spdk/tree/master/examples/vmd/led) could be used to set LED states. diff --git a/examples/bdev/fio_plugin/README.md b/examples/bdev/fio_plugin/README.md index aaa65e64e..84ef213bb 100644 --- a/examples/bdev/fio_plugin/README.md +++ b/examples/bdev/fio_plugin/README.md @@ -4,7 +4,7 @@ This directory contains a plug-in module for fio to enable use with SPDK. Fio is free software published under version 2 of the GPL license. -# Compiling fio +## Compiling fio Clone the fio source repository from https://github.com/axboe/fio @@ -16,7 +16,7 @@ Compile the fio code and install: make make install -# Compiling SPDK +## Compiling SPDK Clone the SPDK source repository from https://github.com/spdk/spdk @@ -39,7 +39,7 @@ with -fPIC by modifying your DPDK configuration file and adding the line: EXTRA_CFLAGS=-fPIC -# Usage +## Usage To use the SPDK fio plugin with fio, specify the plugin binary using LD_PRELOAD when running fio and set ioengine=spdk_bdev in the fio configuration file (see example_config.fio in the same @@ -72,7 +72,7 @@ When testing random workloads, it is recommended to set norandommap=1. fio's ra processing consumes extra CPU cycles which will degrade performance over time with the fio_plugin since all I/O are submitted and completed on a single CPU core. -# Zoned Block Devices +## Zoned Block Devices SPDK has a zoned block device API (bdev_zone.h) which currently supports Open-channel SSDs, NVMe Zoned Namespaces (ZNS), and the virtual zoned block device SPDK module. @@ -86,7 +86,7 @@ If using --numjobs=1, fio version >= 3.23 should suffice. See zbd_example.fio in this directory for a zoned block device example config. -## Maximum Open Zones +### Maximum Open Zones Most zoned block devices have a resource constraint on the amount of zones which can be in an opened state at any point in time. It is very important to not exceed this limit. @@ -97,7 +97,7 @@ You can control how many zones fio will keep in an open state by using the If you use a fio version newer than 3.26, fio will automatically detect and set the proper value. If you use an old version of fio, make sure to provide the proper --max_open_zones value yourself. -## Maximum Active Zones +### Maximum Active Zones Zoned block devices may also have a resource constraint on the number of zones that can be active at any point in time. Unlike ``max_open_zones``, fio currently does not manage this constraint, and @@ -110,7 +110,7 @@ starts running its jobs by using the engine option: --initial_zone_reset=1 -## Zone Append +### Zone Append When running fio against a zoned block device you need to specify --iodepth=1 to avoid "Zone Invalid Write: The write to a zone was not at the write pointer." I/O errors. diff --git a/examples/nvme/fio_plugin/README.md b/examples/nvme/fio_plugin/README.md index 4242c7404..91e725846 100644 --- a/examples/nvme/fio_plugin/README.md +++ b/examples/nvme/fio_plugin/README.md @@ -1,4 +1,6 @@ -# Compiling fio +# FIO plugin + +## Compiling fio First, clone the fio source repository from https://github.com/axboe/fio @@ -8,7 +10,7 @@ Then check out the latest fio version and compile the code: make -# Compiling SPDK +## Compiling SPDK First, clone the SPDK source repository from https://github.com/spdk/spdk @@ -30,7 +32,7 @@ with -fPIC by modifying your DPDK configuration file and adding the line: EXTRA_CFLAGS=-fPIC -# Usage +## Usage To use the SPDK fio plugin with fio, specify the plugin binary using LD_PRELOAD when running fio and set ioengine=spdk in the fio configuration file (see example_config.fio in the same @@ -76,7 +78,7 @@ multiple jobs for FIO test, the performance of FIO is similiar with SPDK perf. A think that is caused by the FIO architecture. Mainly FIO can scale with multiple threads (i.e., using CPU cores), but it is not good to use one thread against many I/O devices. -# End-to-end Data Protection (Optional) +## End-to-end Data Protection (Optional) Running with PI setting, following settings steps are required. First, format device namespace with proper PI setting. For example: @@ -102,13 +104,13 @@ Expose two options 'apptag' and 'apptag_mask', users can change them in the conf application tag and application tag mask in end-to-end data protection. Application tag and application tag mask are set to 0x1234 and 0xFFFF by default. -# VMD (Optional) +## VMD (Optional) To enable VMD enumeration add enable_vmd flag in fio configuration file: enable_vmd=1 -# ZNS +## ZNS To use Zoned Namespaces then build the io-engine against, and run using, a fio version >= 3.23 and add: @@ -119,7 +121,7 @@ To your fio-script, also have a look at script-examples provided with fio: fio/examples/zbd-seq-read.fio fio/examples/zbd-rand-write.fio -## Maximum Open Zones +### Maximum Open Zones Zoned Namespaces has a resource constraint on the amount of zones which can be in an opened state at any point in time. You can control how many zones fio will keep in an open state by using the @@ -128,7 +130,7 @@ any point in time. You can control how many zones fio will keep in an open state If you use a fio version newer than 3.26, fio will automatically detect and set the proper value. If you use an old version of fio, make sure to provide the proper --max_open_zones value yourself. -## Maximum Active Zones +### Maximum Active Zones Zoned Namespaces has a resource constraint on the number of zones that can be active at any point in time. Unlike ``max_open_zones``, then fio currently do not manage this constraint, and there is thus @@ -140,7 +142,7 @@ then you can reset all zones before fio start running its jobs by using the engi --initial_zone_reset=1 -## Zone Append +### Zone Append When running FIO against a Zoned Namespace you need to specify --iodepth=1 to avoid "Zone Invalid Write: The write to a zone was not at the write pointer." I/O errors. @@ -151,7 +153,7 @@ However, if your controller supports Zone Append, you can use the engine option: To send zone append commands instead of write commands to the controller. When using zone append, you will be able to specify a --iodepth greater than 1. -## Shared Memory Increase +### Shared Memory Increase If your device has a lot of zones, fio can give you errors such as: diff --git a/mdl_rules.rb b/mdl_rules.rb index 4398b1b44..1a93ea45f 100644 --- a/mdl_rules.rb +++ b/mdl_rules.rb @@ -4,7 +4,6 @@ exclude_rule 'MD004' exclude_rule 'MD010' rule 'MD013', :line_length => 170 exclude_rule 'MD024' -exclude_rule 'MD025' exclude_rule 'MD026' exclude_rule 'MD027' exclude_rule 'MD028' diff --git a/scripts/check_format.sh b/scripts/check_format.sh index 2236d005d..1ae3f8c02 100755 --- a/scripts/check_format.sh +++ b/scripts/check_format.sh @@ -573,7 +573,7 @@ function check_json_rpc() { local rc=1 while IFS='"' read -r _ rpc _; do - if ! grep -q "^## $rpc" doc/jsonrpc.md; then + if ! grep -q "^### $rpc" doc/jsonrpc.md; then echo "Missing JSON-RPC documentation for ${rpc}" rc=1 continue diff --git a/test/app/fuzz/iscsi_fuzz/README.md b/test/app/fuzz/iscsi_fuzz/README.md index c9ef02e6a..3bcb23a02 100644 --- a/test/app/fuzz/iscsi_fuzz/README.md +++ b/test/app/fuzz/iscsi_fuzz/README.md @@ -3,7 +3,7 @@ This application is intended to fuzz test the iSCSI target by submitting randomized PDU commands through a simulated iSCSI initiator. -# Input +## Input 1. iSCSI initiator send a login request PDU to iSCSI Target. Once a session is connected, 2. iSCSI initiator send huge amount and random PDUs continuously to iSCSI Target. @@ -12,7 +12,7 @@ Especially, iSCSI initiator need to build different bhs according to different b Then iSCSI initiator will receive all kinds of responsed opcodes from iSCSI Target. The application will terminate when run time expires (see the -t flag). -# Output +## Output By default, the fuzzer will print commands that: 1. Complete successfully back from the target, or diff --git a/test/app/fuzz/nvme_fuzz/README.md b/test/app/fuzz/nvme_fuzz/README.md index 2f188b5b8..c07bd69d4 100644 --- a/test/app/fuzz/nvme_fuzz/README.md +++ b/test/app/fuzz/nvme_fuzz/README.md @@ -12,7 +12,7 @@ application will terminate under three conditions: 2. One of the target controllers stops completing I/O operations back to the fuzzer i.e. controller timeout. 3. The user specified a json file containing operations to run and the fuzzer has received valid completions for all of them. -# Output +## Output By default, the fuzzer will print commands that: @@ -30,7 +30,7 @@ At the end of each test run, a summary is printed for each namespace in the foll NS: 0x200079262300 admin qp, Total commands completed: 462459, total successful commands: 1960, random_seed: 4276918833 ~~~ -# Debugging +## Debugging If a controller hangs when processing I/O generated by the fuzzer, the fuzzer will stop submitting I/O and dump out all outstanding I/O on the qpair that timed out. The I/O are @@ -42,7 +42,7 @@ structures. Please note that you can also craft your own custom command values by using the output from the fuzzer as a template. -# JSON Format +## JSON Format Most of the variables in the spdk_nvme_cmd structure are represented as numbers in JSON. The only exception to this rule is the dptr union. This is a 16 byte union structure that diff --git a/test/app/fuzz/vhost_fuzz/README.md b/test/app/fuzz/vhost_fuzz/README.md index ab9656c5b..029ad203e 100644 --- a/test/app/fuzz/vhost_fuzz/README.md +++ b/test/app/fuzz/vhost_fuzz/README.md @@ -8,7 +8,7 @@ queue or the scsi admin queue. Please see the NVMe fuzzer readme for information on how output is generated, debugging procedures, and the JSON format expected when supplying preconstructed values to the fuzzer. -# Request Types +## Request Types Like the NVMe fuzzer, there is an example json file showing the types of requests that the application accepts. Since the vhost application accepts both vhost block @@ -33,7 +33,7 @@ the request will no longer point to a valid memory location. It is possible to supply all three types of requests in a single array to the application. They will be parsed and submitted to the proper block devices. -# RPC +## RPC The vhost fuzzer differs from the NVMe fuzzer in that it expects devices to be configured via rpc. The fuzzer should always be started with the --wait-for-rpc argument. Please see below for an example of starting the fuzzer.