ivampiresp/Spdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc/nvme: move pages to separate text files

Browse Source 
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>
This commit is contained in:
Daniel Verkamp 2016-03-29 10:46:55 -07:00
parent 6d13f8d555
commit 149ee30ee8
9 changed files with 176 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
doc/Doxyfile
View File

@ -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

70
doc/nvme/async_completion.txt Normal file
View File

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

52
doc/nvme/initialization.txt Normal file
View File

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

47
doc/nvme/io_submission.txt Normal file
View File

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

25
lib/nvme/nvme.c
View File

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

5
lib/nvme/nvme_ctrlr.c
View File

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

5
lib/nvme/nvme_intel.c
View File

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

5
lib/nvme/nvme_ns_cmd.c
View File

@ -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,

53
lib/nvme/nvme_qpair.c
View File

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