diff --git a/doc/Doxyfile b/doc/Doxyfile index d8611bc05..5ecab3be6 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -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 \ diff --git a/doc/index.md b/doc/index.md index a100c6a97..11ff39730 100644 --- a/doc/index.md +++ b/doc/index.md @@ -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 diff --git a/doc/nvme/async_completion.md b/doc/nvme/async_completion.md new file mode 100644 index 000000000..bcee6f492 --- /dev/null +++ b/doc/nvme/async_completion.md @@ -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. diff --git a/doc/nvme/async_completion.txt b/doc/nvme/async_completion.txt deleted file mode 100644 index 82ffdea43..000000000 --- a/doc/nvme/async_completion.txt +++ /dev/null @@ -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. - -*/ diff --git a/doc/nvme/index.md b/doc/nvme/index.md new file mode 100644 index 000000000..2e6e87abc --- /dev/null +++ b/doc/nvme/index.md @@ -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 diff --git a/doc/nvme/index.txt b/doc/nvme/index.txt deleted file mode 100644 index a8cf943cd..000000000 --- a/doc/nvme/index.txt +++ /dev/null @@ -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 - -*/ diff --git a/doc/nvme/initialization.md b/doc/nvme/initialization.md new file mode 100644 index 000000000..02ae9fffa --- /dev/null +++ b/doc/nvme/initialization.md @@ -0,0 +1,16 @@ +# NVMe Initialization {#nvme_initialization} + +\msc + + app [label="Application"], nvme [label="NVMe Driver"]; + app=>nvme [label="nvme_probe()"]; + app<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<app [label="create block devices based on controller's namespaces"]; + +\endmsc diff --git a/doc/nvme/initialization.txt b/doc/nvme/initialization.txt deleted file mode 100644 index 5d929abfa..000000000 --- a/doc/nvme/initialization.txt +++ /dev/null @@ -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="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<app [label="create block devices based on controller's namespaces"]; - -\endmsc - -*/ diff --git a/doc/nvme/io_submission.md b/doc/nvme/io_submission.md new file mode 100644 index 000000000..1d936d02d --- /dev/null +++ b/doc/nvme/io_submission.md @@ -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 diff --git a/doc/nvme/io_submission.txt b/doc/nvme/io_submission.txt deleted file mode 100644 index 991079363..000000000 --- a/doc/nvme/io_submission.txt +++ /dev/null @@ -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 - -*/