doc/nvme: move pages to separate text files

This makes it easier to find the larger doc comments that produce separate
pages.

It also allows removing the lib/nvme directory from the Doxyfile, so
only the public API headers are used to generate documentation.

Change-Id: I8c46edb8067a91dda5b23fb0864efd3dd8aaeba5
Signed-off-by: Daniel Verkamp <daniel.verkamp@intel.com>

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

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.
+
+*/

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="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
+
+*/

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
+
+*/

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="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
-
- */
-
 static struct spdk_nvme_ctrlr *
 nvme_attach(void *devhandle)
 {

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);
 

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;

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,

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)
 {