doc: Convert directory structure to markdown
Change-Id: I3af62591658ccd2ae664d73ab5a680a9725469e7 Signed-off-by: Ben Walker <benjamin.walker@intel.com>
This commit is contained in:
Ben Walker
Jim Harris
parent
98149ec0a7
commit
55ca1581d6
@ -760,7 +760,7 @@ WARN_LOGFILE =
|
|||||||
|
|
||||||
INPUT = ../include/spdk \
|
INPUT = ../include/spdk \
|
||||||
index.md \
|
index.md \
|
||||||
directory_structure.txt \
|
directory_structure.md \
|
||||||
ioat/index.txt \
|
ioat/index.txt \
|
||||||
nvme/index.txt \
|
nvme/index.txt \
|
||||||
nvme/async_completion.txt \
|
nvme/async_completion.txt \
|
||||||
|
|||||||
120
doc/directory_structure.md
Normal file
120
doc/directory_structure.md
Normal file
@ -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.
|
||||||
@ -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.
|
|
||||||
*/
|
|
||||||
@ -13,7 +13,7 @@ which avoids kernel context switches and eliminates interrupt handling overhead.
|
|||||||
|
|
||||||
## General Information {#general}
|
## General Information {#general}
|
||||||
|
|
||||||
- \ref directory_structure
|
- @ref directory_structure
|
||||||
|
|
||||||
## Modules {#modules}
|
## Modules {#modules}
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user