diff --git a/doc/Doxyfile b/doc/Doxyfile index 67ae879a5..d8611bc05 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -760,7 +760,7 @@ WARN_LOGFILE = INPUT = ../include/spdk \ index.md \ - directory_structure.txt \ + directory_structure.md \ ioat/index.txt \ nvme/index.txt \ nvme/async_completion.txt \ diff --git a/doc/directory_structure.md b/doc/directory_structure.md new file mode 100644 index 000000000..c474f9ea5 --- /dev/null +++ b/doc/directory_structure.md @@ -0,0 +1,120 @@ +# SPDK Directory Structure {#directory_structure} + +# Overview {#dir_overview} + +SPDK is primarily a collection of C libraries intended to be consumed directly by +applications, but the repository also contains many examples and full-fledged applications. +This will provide a general overview of what is where in the repository. + +## Applications {#dir_app} + +The `app` top-level directory contains four applications: + - `app/iscsi_tgt`: An iSCSI target + - `app/nvmf_tgt`: An NVMe-oF target + - `app/iscsi_top`: Informational tool (like `top`) that tracks activity in the + iSCSI target. + - `app/trace`: A tool for processing trace points output from the iSCSI and + NVMe-oF targets. + +The application binaries will be in their respective directories after compiling and all +can be run with no arguments to print out their command line arguments. For the iSCSI +and NVMe-oF targets, they both need a configuration file (-c option). Fully commented +examples of the configuration files live in the `etc/spdk` directory. + +## Build Collateral {#dir_build} + +The `build` directory contains all of the static libraries constructed during +the build process. The `lib` directory combined with the `include/spdk` +directory are the official outputs of an SPDK release, if it were to be packaged. + +## Documentation {#dir_doc} + +The `doc` top-level directory contains all of SPDK's documentation. API Documentation +is created using Doxygen directly from the code, but more general articles and longer +explanations reside in this directory, as well as the Doxygen config file. + +To build the documentation, just type `make` within the doc directory. + +## Examples {#dir_examples} + +The `examples` top-level directory contains a set of examples intended to be used +for reference. These are different than the applications, which are doing a "real" +task that could reasonably be deployed. The examples are instead either heavily +contrived to demonstrate some facet of SPDK, or aren't considered complete enough +to warrant tagging them as a full blown SPDK application. + +This is a great place to learn about how SPDK works. In particular, check out +`examples/nvme/hello_world`. + +## Include {#dir_include} + +The `include` directory is where all of the header files are located. The public API +is all placed in the `spdk` subdirectory of `include` and we highly +recommend that applications set their include path to the top level `include` +directory and include the headers by prefixing `spdk/` like this: + +~~~{.c} +#include "spdk/nvme.h" +~~~ + +Most of the headers here correspond with a library in the `lib` directory and will be +covered in that section. There are a few headers that stand alone, however. They are: + + - `assert.h` + - `barrier.h` + - `endian.h` + - `fd.h` + - `mmio.h` + - `queue.h` and `queue_extras.h` + - `string.h` + +There is also an `spdk_internal` directory that contains header files widely included +by libraries within SPDK, but that are not part of the public API and would not be +installed on a user's system. + +## Libraries {#dir_lib} + +The `lib` directory contains the real heart of SPDK. Each component is a C library with +its own directory under `lib`. + +### Block Device Abstraction Layer {#dir_bdev} + +The `bdev` directory contains a block device abstraction layer that is currently used +within the iSCSI and NVMe-oF targets. The public interface is `include/spdk/bdev.h`. +This library lacks clearly defined responsibilities as of this writing and instead does a +number of +things: + - Translates from a common `block` protocol to specific protocols like NVMe or to system + calls like libaio. There are currently three block device backend modules that can be + plugged in - libaio, SPDK NVMe, CephRBD, and a RAM-based backend called malloc. + - Provides a mechanism for composing virtual block devices from physical devices (to do + RAID and the like). + - Handles some memory allocation for data buffers. + +This layer also could be made to do I/O queueing or splitting in a general way. We're open +to design ideas and discussion here. + +### Configuration File Parser {#dir_conf} + +The `conf` directory contains configuration file parser. The public header +is `include/spdk/conf.h`. The configuration file format is kind of like INI, +except that the directives are are "Name Value" instead of "Name = Value". This is +the configuration format for both the iSCSI and NVMe-oF targets. + +... Lots more libraries that need to be described ... + +## Makefile Fragments {#dir_mk} + +The `mk` directory contains a number of shared Makefile fragments used in the build system. + +## Scripts {#dir_scripts} + +The `scripts` directory contains convenient scripts for a number of operations. The two most +important are `check_format.sh`, which will use astyle and pep8 to check C, C++, and Python +coding style against our defined conventions, and `setup.sh` which binds and unbinds devices +from kernel drivers. + +## Tests {#dir_tests} + +The `test` directory contains all of the tests for SPDK's components and the subdirectories mirror +the structure of the entire repository. The tests are a mixture of unit tests and functional tests. diff --git a/doc/directory_structure.txt b/doc/directory_structure.txt deleted file mode 100644 index c271e6f4f..000000000 --- a/doc/directory_structure.txt +++ /dev/null @@ -1,152 +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 directory_structure SPDK Directory Structure - -SPDK is primarily a collection of C libraries intended to be consumed directly by -applications, but the repository also contains many examples and full-fledged applications. -This will provide a general overview of what is where in the repository. - -\section dir_app Applications - -The \c app top-level directory contains four applications: - - \c app/iscsi_tgt: An iSCSI target - - \c app/nvmf_tgt: An NVMe-oF target - - \c app/iscsi_top: Informational tool (like \c top) that tracks activity in the - iSCSI target. - - \c app/trace: A tool for processing trace points output from the iSCSI and - NVMe-oF targets. - -The application binaries will be in their respective directories after compiling and all -can be run with no arguments to print out their command line arguments. For the iSCSI -and NVMe-oF targets, they both need a configuration file (-c option). Fully commented -examples of the configuration files live in the \c etc/spdk directory. - -\section dir_build Build Collateral - -The \c build directory contains all of the static libraries constructed during -the build process. The \c lib directory combined with the \c include/spdk -directory are the official outputs of an SPDK release, if it were to be packaged. - -\section dir_doc Documentation - -The \c doc top-level directory contains all of SPDK's documentation. API Documentation -is created using Doxygen directly from the code, but more general articles and longer -explanations reside in this directory, as well as the Doxygen config file. - -To build the documentation, just type `make` within the doc directory. - -\section dir_examples Examples - -The \c examples top-level directory contains a set of examples intended to be used -for reference. These are different than the applications, which are doing a "real" -task that could reasonably be deployed. The examples are instead either heavily -contrived to demonstrate some facet of SPDK, or aren't considered complete enough -to warrant tagging them as a full blown SPDK application. - -This is a great place to learn about how SPDK works. In particular, check out -\c examples/nvme/hello_world. - -\section dir_include Include - -The \c include directory is where all of the header files are located. The public API -is all placed in the \c spdk subdirectory of \c include and we highly -recommend that applications set their include path to the top level \c include -directory and include the headers by prefixing \c spdk/ like this: - -\code #include "spdk/nvme.h" \endcode - -Most of the headers here correspond with a library in the \c lib directory and will be -covered in that section. There are a few headers that stand alone, however. They are: - - - \c assert.h - - \c barrier.h - - \c endian.h - - \c fd.h - - \c mmio.h - - \c queue.h and \c queue_extras.h - - \c string.h - -There is also an \c spdk_internal directory that contains header files widely included -by libraries within SPDK, but that are not part of the public API and would not be -installed on a user's system. - -\section dir_lib Libraries - -The \c lib directory contains the real heart of SPDK. Each component is a C library with -its own directory under \c lib. - -\subsection dir_bdev Block Device Abstraction Layer - -The \c bdev directory contains a block device abstraction layer that is currently used -within the iSCSI and NVMe-oF targets. The public interface is \c include/spdk/bdev.h. -This library lacks clearly defined responsibilities as of this writing and instead does a -number of -things: - - Translates from a common \c block protocol to specific protocols like NVMe or to system - calls like libaio. There are currently three block device backend modules that can be - plugged in - libaio, SPDK NVMe, CephRBD, and a RAM-based backend called malloc. - - Provides a mechanism for composing virtual block devices from physical devices (to do - RAID and the like). - - Handles some memory allocation for data buffers. - -This layer also could be made to do I/O queueing or splitting in a general way. We're open -to design ideas and discussion here. - -\subsection dir_conf Configuration File Parser - -The \c conf directory contains configuration file parser. The public header -is \c include/spdk/conf.h. The configuration file format is kind of like INI, -except that the directives are are "Name Value" instead of "Name = Value". This is -the configuration format for both the iSCSI and NVMe-oF targets. - -... Lots more libraries that need to be described ... - -\section dir_mk Makefile Fragments - -The \c mk directory contains a number of shared Makefile fragments used in the build system. - -\section dir_scripts Scripts - -The \c scripts directory contains convenient scripts for a number of operations. The two most -important are \c check_format.sh, which will use astyle and pep8 to check C, C++, and Python -coding style against our defined conventions, and \c setup.sh which binds and unbinds devices -from kernel drivers. - -\section dir_tests Tests - -The \c test directory contains all of the tests for SPDK's components and the subdirectories mirror -the structure of the entire repository. The tests are a mixture of unit tests and functional tests. -*/ diff --git a/doc/index.md b/doc/index.md index 2130a122b..a100c6a97 100644 --- a/doc/index.md +++ b/doc/index.md @@ -13,7 +13,7 @@ which avoids kernel context switches and eliminates interrupt handling overhead. ## General Information {#general} - - \ref directory_structure + - @ref directory_structure ## Modules {#modules}