1 files changed, 102 insertions, 0 deletions
diff --git a/src/spdk/doc/overview.md b/src/spdk/doc/overview.md
new file mode 100644
index 000000000..7407a2026
--- /dev/null
+++ b/src/spdk/doc/overview.md
@@ -0,0 +1,102 @@
+# SPDK Structural Overview {#overview}
+
+# Overview {#dir_overview}
+
+SPDK is composed of a set of C libraries residing in `lib` with public interface
+header files in `include/spdk`, plus a set of applications built out of those
+libraries in `app`. Users can use the C libraries in their software or deploy
+the full SPDK applications.
+
+SPDK is designed around message passing instead of locking, and most of the SPDK
+libraries make several assumptions about the underlying threading model of the
+application they are embedded into. However, SPDK goes to great lengths to remain
+agnostic to the specific message passing, event, co-routine, or light-weight
+threading framework actually in use. To accomplish this, all SPDK libraries
+interact with an abstraction library in `lib/thread` (public interface at
+`include/spdk/thread.h`). Any framework can initialize the threading abstraction
+and provide callbacks to implement the functionality that the SPDK libraries
+need. For more information on this abstraction, see @ref concurrency.
+
+SPDK is built on top of POSIX for most operations. To make porting to non-POSIX
+environments easier, all POSIX headers are isolated into
+`include/spdk/stdinc.h`. However, SPDK requires a number of operations that
+POSIX does not provide, such as enumerating the PCI devices on the system or
+allocating memory that is safe for DMA. These additional operations are all
+abstracted in a library called `env` whose public header is at
+`include/spdk/env.h`. By default, SPDK implements the `env` interface using a
+library based on DPDK. However, that implementation can be swapped out. See @ref
+porting for additional information.
+
+## Applications {#dir_app}
+
+The `app` top-level directory contains full-fledged applications, built out of the SPDK
+components. For a full overview, see @ref app_overview.
+
+SPDK applications can typically be started with a small number of configuration
+options. Full configuration of the applications is then performed using
+JSON-RPC. See @ref jsonrpc for additional information.
+
+## Libraries {#dir_lib}
+
+The `lib` directory contains the real heart of SPDK. Each component is a C library with
+its own directory under `lib`. Some of the key libraries are:
+
+- @ref bdev
+- @ref nvme
+
+## 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. 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.
+
+## 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.