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 \
|
||||
directory_structure.md \
|
||||
ioat/index.txt \
|
||||
nvme/index.txt \
|
||||
nvme/async_completion.txt \
|
||||
nvme/initialization.txt \
|
||||
nvme/io_submission.txt \
|
||||
nvme/index.md \
|
||||
nvme/async_completion.md \
|
||||
nvme/initialization.md \
|
||||
nvme/io_submission.md \
|
||||
nvmf/index.txt \
|
||||
nvmf/getting_started.txt \
|
||||
iscsi/index.txt \
|
||||
|
||||
@ -17,7 +17,7 @@ which avoids kernel context switches and eliminates interrupt handling overhead.
|
||||
|
||||
## Modules {#modules}
|
||||
|
||||
- \ref nvme
|
||||
- @ref nvme
|
||||
- \ref nvmf
|
||||
- \ref ioat
|
||||
- \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