doc: Convert nvme docs to markdown
Change-Id: Ifc9c79886f05c6a3abd1553021a65724e53dd5c0 Signed-off-by: Ben Walker <benjamin.walker@intel.com>
This commit is contained in:
Ben Walker
Jim Harris
parent
55ca1581d6
commit
0be12ad7da
@ -762,10 +762,10 @@ INPUT = ../include/spdk \
|
|||||||
index.md \
|
index.md \
|
||||||
directory_structure.md \
|
directory_structure.md \
|
||||||
ioat/index.txt \
|
ioat/index.txt \
|
||||||
nvme/index.txt \
|
nvme/index.md \
|
||||||
nvme/async_completion.txt \
|
nvme/async_completion.md \
|
||||||
nvme/initialization.txt \
|
nvme/initialization.md \
|
||||||
nvme/io_submission.txt \
|
nvme/io_submission.md \
|
||||||
nvmf/index.txt \
|
nvmf/index.txt \
|
||||||
nvmf/getting_started.txt \
|
nvmf/getting_started.txt \
|
||||||
iscsi/index.txt \
|
iscsi/index.txt \
|
||||||
|
|||||||
@ -17,7 +17,7 @@ which avoids kernel context switches and eliminates interrupt handling overhead.
|
|||||||
|
|
||||||
## Modules {#modules}
|
## Modules {#modules}
|
||||||
|
|
||||||
- \ref nvme
|
- @ref nvme
|
||||||
- \ref nvmf
|
- \ref nvmf
|
||||||
- \ref ioat
|
- \ref ioat
|
||||||
- \ref iscsi
|
- \ref iscsi
|
||||||
|
|||||||
33
doc/nvme/async_completion.md
Normal file
33
doc/nvme/async_completion.md
Normal file
@ -0,0 +1,33 @@
|
|||||||
|
# NVMe Asynchronous Completion {#nvme_async_completion}
|
||||||
|
|
||||||
|
The userspace NVMe driver follows an asynchronous polled model for
|
||||||
|
I/O completion.
|
||||||
|
|
||||||
|
# I/O commands {#nvme_async_io}
|
||||||
|
|
||||||
|
The application may submit I/O from one or more threads on one or more queue pairs
|
||||||
|
and must call spdk_nvme_qpair_process_completions()
|
||||||
|
for each queue pair that submitted I/O.
|
||||||
|
|
||||||
|
When the application calls spdk_nvme_qpair_process_completions(),
|
||||||
|
if the NVMe driver detects completed I/Os that were submitted on that queue,
|
||||||
|
it will invoke the registered callback function
|
||||||
|
for each I/O within the context of spdk_nvme_qpair_process_completions().
|
||||||
|
|
||||||
|
# Admin commands {#nvme_async_admin}
|
||||||
|
|
||||||
|
The application may submit admin commands from one or more threads
|
||||||
|
and must call spdk_nvme_ctrlr_process_admin_completions()
|
||||||
|
from at least one thread to receive admin command completions.
|
||||||
|
The thread that processes admin completions need not be the same thread that submitted the
|
||||||
|
admin commands.
|
||||||
|
|
||||||
|
When the application calls spdk_nvme_ctrlr_process_admin_completions(),
|
||||||
|
if the NVMe driver detects completed admin commands submitted from any thread,
|
||||||
|
it will invote the registered callback function
|
||||||
|
for each command within the context of spdk_nvme_ctrlr_process_admin_completions().
|
||||||
|
|
||||||
|
It is the application's responsibility to manage the order of submitted admin commands.
|
||||||
|
If certain admin commands must be submitted while no other commands are outstanding,
|
||||||
|
it is the application's responsibility to enforce this rule
|
||||||
|
using its own synchronization method.
|
||||||
@ -1,70 +0,0 @@
|
|||||||
/*-
|
|
||||||
* BSD LICENSE
|
|
||||||
*
|
|
||||||
* Copyright (c) Intel Corporation.
|
|
||||||
* All rights reserved.
|
|
||||||
*
|
|
||||||
* Redistribution and use in source and binary forms, with or without
|
|
||||||
* modification, are permitted provided that the following conditions
|
|
||||||
* are met:
|
|
||||||
*
|
|
||||||
* * Redistributions of source code must retain the above copyright
|
|
||||||
* notice, this list of conditions and the following disclaimer.
|
|
||||||
* * Redistributions in binary form must reproduce the above copyright
|
|
||||||
* notice, this list of conditions and the following disclaimer in
|
|
||||||
* the documentation and/or other materials provided with the
|
|
||||||
* distribution.
|
|
||||||
* * Neither the name of Intel Corporation nor the names of its
|
|
||||||
* contributors may be used to endorse or promote products derived
|
|
||||||
* from this software without specific prior written permission.
|
|
||||||
*
|
|
||||||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
||||||
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
||||||
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
||||||
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
||||||
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
||||||
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
||||||
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
||||||
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
||||||
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
||||||
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
||||||
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/**
|
|
||||||
|
|
||||||
\page nvme_async_completion NVMe Asynchronous Completion
|
|
||||||
|
|
||||||
The userspace NVMe driver follows an asynchronous polled model for
|
|
||||||
I/O completion.
|
|
||||||
|
|
||||||
\section nvme_async_io I/O commands
|
|
||||||
|
|
||||||
The application may submit I/O from one or more threads on one or more queue pairs
|
|
||||||
and must call spdk_nvme_qpair_process_completions()
|
|
||||||
for each queue pair that submitted I/O.
|
|
||||||
|
|
||||||
When the application calls spdk_nvme_qpair_process_completions(),
|
|
||||||
if the NVMe driver detects completed I/Os that were submitted on that queue,
|
|
||||||
it will invoke the registered callback function
|
|
||||||
for each I/O within the context of spdk_nvme_qpair_process_completions().
|
|
||||||
|
|
||||||
\section nvme_async_admin Admin commands
|
|
||||||
|
|
||||||
The application may submit admin commands from one or more threads
|
|
||||||
and must call spdk_nvme_ctrlr_process_admin_completions()
|
|
||||||
from at least one thread to receive admin command completions.
|
|
||||||
The thread that processes admin completions need not be the same thread that submitted the
|
|
||||||
admin commands.
|
|
||||||
|
|
||||||
When the application calls spdk_nvme_ctrlr_process_admin_completions(),
|
|
||||||
if the NVMe driver detects completed admin commands submitted from any thread,
|
|
||||||
it will invote the registered callback function
|
|
||||||
for each command within the context of spdk_nvme_ctrlr_process_admin_completions().
|
|
||||||
|
|
||||||
It is the application's responsibility to manage the order of submitted admin commands.
|
|
||||||
If certain admin commands must be submitted while no other commands are outstanding,
|
|
||||||
it is the application's responsibility to enforce this rule
|
|
||||||
using its own synchronization method.
|
|
||||||
|
|
||||||
*/
|
|
||||||
22
doc/nvme/index.md
Normal file
22
doc/nvme/index.md
Normal file
@ -0,0 +1,22 @@
|
|||||||
|
# NVMe Driver {#nvme}
|
||||||
|
|
||||||
|
# Public Interface {#nvme_interface}
|
||||||
|
|
||||||
|
- spdk/nvme.h
|
||||||
|
|
||||||
|
# Key Functions {#nvme_key_functions}
|
||||||
|
|
||||||
|
Function | Description
|
||||||
|
--------------------------------------- | -----------
|
||||||
|
spdk_nvme_probe() | @copybrief spdk_nvme_probe()
|
||||||
|
spdk_nvme_ns_cmd_read() | @copybrief spdk_nvme_ns_cmd_read()
|
||||||
|
spdk_nvme_ns_cmd_write() | @copybrief spdk_nvme_ns_cmd_write()
|
||||||
|
spdk_nvme_ns_cmd_dataset_management() | @copybrief spdk_nvme_ns_cmd_dataset_management()
|
||||||
|
spdk_nvme_ns_cmd_flush() | @copybrief spdk_nvme_ns_cmd_flush()
|
||||||
|
spdk_nvme_qpair_process_completions() | @copybrief spdk_nvme_qpair_process_completions()
|
||||||
|
|
||||||
|
# Key Concepts {#nvme_key_concepts}
|
||||||
|
|
||||||
|
- @ref nvme_initialization
|
||||||
|
- @ref nvme_io_submission
|
||||||
|
- @ref nvme_async_completion
|
||||||
@ -1,59 +0,0 @@
|
|||||||
/*-
|
|
||||||
* BSD LICENSE
|
|
||||||
*
|
|
||||||
* Copyright (c) Intel Corporation.
|
|
||||||
* All rights reserved.
|
|
||||||
*
|
|
||||||
* Redistribution and use in source and binary forms, with or without
|
|
||||||
* modification, are permitted provided that the following conditions
|
|
||||||
* are met:
|
|
||||||
*
|
|
||||||
* * Redistributions of source code must retain the above copyright
|
|
||||||
* notice, this list of conditions and the following disclaimer.
|
|
||||||
* * Redistributions in binary form must reproduce the above copyright
|
|
||||||
* notice, this list of conditions and the following disclaimer in
|
|
||||||
* the documentation and/or other materials provided with the
|
|
||||||
* distribution.
|
|
||||||
* * Neither the name of Intel Corporation nor the names of its
|
|
||||||
* contributors may be used to endorse or promote products derived
|
|
||||||
* from this software without specific prior written permission.
|
|
||||||
*
|
|
||||||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
||||||
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
||||||
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
||||||
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
||||||
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
||||||
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
||||||
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
||||||
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
||||||
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
||||||
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
||||||
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/*!
|
|
||||||
|
|
||||||
\page nvme NVMe Driver
|
|
||||||
|
|
||||||
\section nvme_interface Public Interface
|
|
||||||
|
|
||||||
- spdk/nvme.h
|
|
||||||
|
|
||||||
\section nvme_key_functions Key Functions
|
|
||||||
|
|
||||||
Function | Description
|
|
||||||
--------------------------------------- | -----------
|
|
||||||
spdk_nvme_probe() | \copybrief spdk_nvme_probe()
|
|
||||||
spdk_nvme_ns_cmd_read() | \copybrief spdk_nvme_ns_cmd_read()
|
|
||||||
spdk_nvme_ns_cmd_write() | \copybrief spdk_nvme_ns_cmd_write()
|
|
||||||
spdk_nvme_ns_cmd_dataset_management() | \copybrief spdk_nvme_ns_cmd_dataset_management()
|
|
||||||
spdk_nvme_ns_cmd_flush() | \copybrief spdk_nvme_ns_cmd_flush()
|
|
||||||
spdk_nvme_qpair_process_completions() | \copybrief spdk_nvme_qpair_process_completions()
|
|
||||||
|
|
||||||
\section nvme_key_concepts Key Concepts
|
|
||||||
|
|
||||||
- \ref nvme_initialization
|
|
||||||
- \ref nvme_io_submission
|
|
||||||
- \ref nvme_async_completion
|
|
||||||
|
|
||||||
*/
|
|
||||||
16
doc/nvme/initialization.md
Normal file
16
doc/nvme/initialization.md
Normal file
@ -0,0 +1,16 @@
|
|||||||
|
# NVMe Initialization {#nvme_initialization}
|
||||||
|
|
||||||
|
\msc
|
||||||
|
|
||||||
|
app [label="Application"], nvme [label="NVMe Driver"];
|
||||||
|
app=>nvme [label="nvme_probe()"];
|
||||||
|
app<<nvme [label="probe_cb(pci_dev)"];
|
||||||
|
nvme=>nvme [label="nvme_attach(devhandle)"];
|
||||||
|
nvme=>nvme [label="nvme_ctrlr_start(nvme_controller ptr)"];
|
||||||
|
nvme=>nvme [label="identify controller"];
|
||||||
|
nvme=>nvme [label="create queue pairs"];
|
||||||
|
nvme=>nvme [label="identify namespace(s)"];
|
||||||
|
app<<nvme [label="attach_cb(pci_dev, nvme_controller)"];
|
||||||
|
app=>app [label="create block devices based on controller's namespaces"];
|
||||||
|
|
||||||
|
\endmsc
|
||||||
@ -1,52 +0,0 @@
|
|||||||
/*-
|
|
||||||
* BSD LICENSE
|
|
||||||
*
|
|
||||||
* Copyright (c) Intel Corporation.
|
|
||||||
* All rights reserved.
|
|
||||||
*
|
|
||||||
* Redistribution and use in source and binary forms, with or without
|
|
||||||
* modification, are permitted provided that the following conditions
|
|
||||||
* are met:
|
|
||||||
*
|
|
||||||
* * Redistributions of source code must retain the above copyright
|
|
||||||
* notice, this list of conditions and the following disclaimer.
|
|
||||||
* * Redistributions in binary form must reproduce the above copyright
|
|
||||||
* notice, this list of conditions and the following disclaimer in
|
|
||||||
* the documentation and/or other materials provided with the
|
|
||||||
* distribution.
|
|
||||||
* * Neither the name of Intel Corporation nor the names of its
|
|
||||||
* contributors may be used to endorse or promote products derived
|
|
||||||
* from this software without specific prior written permission.
|
|
||||||
*
|
|
||||||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
||||||
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
||||||
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
||||||
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
||||||
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
||||||
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
||||||
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
||||||
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
||||||
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
||||||
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
||||||
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/**
|
|
||||||
* \page nvme_initialization NVMe Initialization
|
|
||||||
|
|
||||||
\msc
|
|
||||||
|
|
||||||
app [label="Application"], nvme [label="NVMe Driver"];
|
|
||||||
app=>nvme [label="nvme_probe()"];
|
|
||||||
app<<nvme [label="probe_cb(pci_dev)"];
|
|
||||||
nvme=>nvme [label="nvme_attach(devhandle)"];
|
|
||||||
nvme=>nvme [label="nvme_ctrlr_start(nvme_controller ptr)"];
|
|
||||||
nvme=>nvme [label="identify controller"];
|
|
||||||
nvme=>nvme [label="create queue pairs"];
|
|
||||||
nvme=>nvme [label="identify namespace(s)"];
|
|
||||||
app<<nvme [label="attach_cb(pci_dev, nvme_controller)"];
|
|
||||||
app=>app [label="create block devices based on controller's namespaces"];
|
|
||||||
|
|
||||||
\endmsc
|
|
||||||
|
|
||||||
*/
|
|
||||||
10
doc/nvme/io_submission.md
Normal file
10
doc/nvme/io_submission.md
Normal file
@ -0,0 +1,10 @@
|
|||||||
|
# NVMe I/O Submission {#nvme_io_submission}
|
||||||
|
|
||||||
|
I/O is submitted to an NVMe namespace using nvme_ns_cmd_xxx functions
|
||||||
|
defined in nvme_ns_cmd.c. The NVMe driver submits the I/O request
|
||||||
|
as an NVMe submission queue entry on the queue pair specified in the command.
|
||||||
|
The application must poll for I/O completion on each queue pair with outstanding I/O
|
||||||
|
to receive completion callbacks.
|
||||||
|
|
||||||
|
@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
|
||||||
@ -1,47 +0,0 @@
|
|||||||
/*-
|
|
||||||
* BSD LICENSE
|
|
||||||
*
|
|
||||||
* Copyright (c) Intel Corporation.
|
|
||||||
* All rights reserved.
|
|
||||||
*
|
|
||||||
* Redistribution and use in source and binary forms, with or without
|
|
||||||
* modification, are permitted provided that the following conditions
|
|
||||||
* are met:
|
|
||||||
*
|
|
||||||
* * Redistributions of source code must retain the above copyright
|
|
||||||
* notice, this list of conditions and the following disclaimer.
|
|
||||||
* * Redistributions in binary form must reproduce the above copyright
|
|
||||||
* notice, this list of conditions and the following disclaimer in
|
|
||||||
* the documentation and/or other materials provided with the
|
|
||||||
* distribution.
|
|
||||||
* * Neither the name of Intel Corporation nor the names of its
|
|
||||||
* contributors may be used to endorse or promote products derived
|
|
||||||
* from this software without specific prior written permission.
|
|
||||||
*
|
|
||||||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
||||||
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
||||||
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
||||||
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
||||||
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
||||||
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
||||||
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
||||||
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
||||||
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
||||||
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
||||||
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/**
|
|
||||||
|
|
||||||
\page nvme_io_submission NVMe I/O Submission
|
|
||||||
|
|
||||||
I/O is submitted to an NVMe namespace using nvme_ns_cmd_xxx functions
|
|
||||||
defined in nvme_ns_cmd.c. The NVMe driver submits the I/O request
|
|
||||||
as an NVMe submission queue entry on the queue pair specified in the command.
|
|
||||||
The application must poll for I/O completion on each queue pair with outstanding I/O
|
|
||||||
to receive completion callbacks.
|
|
||||||
|
|
||||||
\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
|
|
||||||
|
|
||||||
*/
|
|
||||||
Loading…
Reference in New Issue
Block a user