diff --git a/doc/Doxyfile b/doc/Doxyfile index 1265a108b..fc1d867eb 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -758,11 +758,14 @@ WARN_LOGFILE = # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = ../lib/nvme \ +INPUT = ../lib/nvme/nvme_impl.h \ ../include/spdk \ mainpage.txt \ ioat/index.txt \ - nvme/index.txt + nvme/index.txt \ + nvme/async_completion.txt \ + nvme/initialization.txt \ + nvme/io_submission.txt # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/doc/nvme/async_completion.txt b/doc/nvme/async_completion.txt new file mode 100644 index 000000000..82ffdea43 --- /dev/null +++ b/doc/nvme/async_completion.txt @@ -0,0 +1,70 @@ +/*- + * 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/initialization.txt b/doc/nvme/initialization.txt new file mode 100644 index 000000000..5d929abfa --- /dev/null +++ b/doc/nvme/initialization.txt @@ -0,0 +1,52 @@ +/*- + * 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.txt b/doc/nvme/io_submission.txt new file mode 100644 index 000000000..77b8e0e80 --- /dev/null +++ b/doc/nvme/io_submission.txt @@ -0,0 +1,47 @@ +/*- + * 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_deallocate, +spdk_nvme_ns_cmd_flush, spdk_nvme_qpair_process_completions + +*/ diff --git a/lib/nvme/nvme.c b/lib/nvme/nvme.c index 8fea59615..d33f2bbe5 100644 --- a/lib/nvme/nvme.c +++ b/lib/nvme/nvme.c @@ -33,10 +33,6 @@ #include "nvme_internal.h" -/** \file - * - */ - struct nvme_driver g_nvme_driver = { .lock = NVME_MUTEX_INITIALIZER, .init_ctrlrs = TAILQ_HEAD_INITIALIZER(g_nvme_driver.init_ctrlrs), @@ -45,27 +41,6 @@ struct nvme_driver g_nvme_driver = { int32_t spdk_nvme_retry_count; - -/** - * \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 - - */ - static struct spdk_nvme_ctrlr * nvme_attach(void *devhandle) { diff --git a/lib/nvme/nvme_ctrlr.c b/lib/nvme/nvme_ctrlr.c index cbc3a4a46..b6b204fa2 100644 --- a/lib/nvme/nvme_ctrlr.c +++ b/lib/nvme/nvme_ctrlr.c @@ -34,11 +34,6 @@ #include "nvme_internal.h" #include "spdk/pci.h" -/** - * \file - * - */ - static int nvme_ctrlr_construct_and_submit_aer(struct spdk_nvme_ctrlr *ctrlr, struct nvme_async_event_request *aer); diff --git a/lib/nvme/nvme_intel.c b/lib/nvme/nvme_intel.c index 0cb433754..7c577f8d1 100644 --- a/lib/nvme/nvme_intel.c +++ b/lib/nvme/nvme_intel.c @@ -33,9 +33,8 @@ #include "nvme_internal.h" -/** \file - * Intel specific data structures and functions. - */ +/* Intel specific data structures and functions. */ + struct nvme_intel_quirk { struct pci_id id; uint64_t flags; diff --git a/lib/nvme/nvme_ns_cmd.c b/lib/nvme/nvme_ns_cmd.c index 1cda88998..cb6d12bc4 100644 --- a/lib/nvme/nvme_ns_cmd.c +++ b/lib/nvme/nvme_ns_cmd.c @@ -33,11 +33,6 @@ #include "nvme_internal.h" -/** - * \file - * - */ - static struct nvme_request *_nvme_ns_cmd_rw(struct spdk_nvme_ns *ns, const struct nvme_payload *payload, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, diff --git a/lib/nvme/nvme_qpair.c b/lib/nvme/nvme_qpair.c index 6afdfaa8c..b78da586b 100644 --- a/lib/nvme/nvme_qpair.c +++ b/lib/nvme/nvme_qpair.c @@ -33,11 +33,6 @@ #include "nvme_internal.h" -/** - * \file - * - */ - static inline bool nvme_qpair_is_admin_queue(struct spdk_nvme_qpair *qpair) { return qpair->id == 0; @@ -418,42 +413,6 @@ nvme_qpair_check_enabled(struct spdk_nvme_qpair *qpair) return qpair->is_enabled; } -/** - * \page nvme_async_completion NVMe Asynchronous Completion - * - * The userspace NVMe driver follows an asynchronous polled model for - * I/O completion. - * - * \section 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 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. - */ - int32_t spdk_nvme_qpair_process_completions(struct spdk_nvme_qpair *qpair, uint32_t max_completions) { @@ -624,18 +583,6 @@ nvme_qpair_destroy(struct spdk_nvme_qpair *qpair) nvme_free(qpair->tr); } -/** - * \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 nvme_qpair associated with - * the logical core that submits the I/O. - * - * \sa nvme_ns_cmd_read, nvme_ns_cmd_write, nvme_ns_cmd_deallocate, - * nvme_ns_cmd_flush, nvme_get_ioq_idx - */ - static void _nvme_fail_request_bad_vtophys(struct spdk_nvme_qpair *qpair, struct nvme_tracker *tr) {