1# SPDK Structural Overview {#overview} 2 3# Overview {#dir_overview} 4 5SPDK is composed of a set of C libraries residing in `lib` with public interface 6header files in `include/spdk`, plus a set of applications built out of those 7libraries in `app`. Users can use the C libraries in their software or deploy 8the full SPDK applications. 9 10SPDK is designed around message passing instead of locking, and most of the SPDK 11libraries make several assumptions about the underlying threading model of the 12application they are embedded into. However, SPDK goes to great lengths to remain 13agnostic to the specific message passing, event, co-routine, or light-weight 14threading framework actually in use. To accomplish this, all SPDK libraries 15interact with an abstraction library in `lib/thread` (public interface at 16`include/spdk/thread.h`). Any framework can initialize the threading abstraction 17and provide callbacks to implement the functionality that the SPDK libraries 18need. For more information on this abstraction, see @ref concurrency. 19 20SPDK is built on top of POSIX for most operations. To make porting to non-POSIX 21environments easier, all POSIX headers are isolated into 22`include/spdk/stdinc.h`. However, SPDK requires a number of operations that 23POSIX does not provide, such as enumerating the PCI devices on the system or 24allocating memory that is safe for DMA. These additional operations are all 25abstracted in a library called `env` whose public header is at 26`include/spdk/env.h`. By default, SPDK implements the `env` interface using a 27library based on DPDK. However, that implementation can be swapped out. See @ref 28porting for additional information. 29 30## Applications {#dir_app} 31 32The `app` top-level directory contains full-fledged applications, built out of the SPDK 33components. For a full overview, see @ref app_overview. 34 35SPDK applications can typically be started with a small number of configuration 36options. Full configuration of the applications is then performed using 37JSON-RPC. See @ref jsonrpc for additional information. 38 39## Libraries {#dir_lib} 40 41The `lib` directory contains the real heart of SPDK. Each component is a C library with 42its own directory under `lib`. Some of the key libraries are: 43 44- @ref bdev 45- @ref nvme 46 47## Documentation {#dir_doc} 48 49The `doc` top-level directory contains all of SPDK's documentation. API Documentation 50is created using Doxygen directly from the code, but more general articles and longer 51explanations reside in this directory, as well as the Doxygen config file. 52 53To build the documentation, just type `make` within the doc directory. 54 55## Examples {#dir_examples} 56 57The `examples` top-level directory contains a set of examples intended to be used 58for reference. These are different than the applications, which are doing a "real" 59task that could reasonably be deployed. The examples are instead either heavily 60contrived to demonstrate some facet of SPDK, or aren't considered complete enough 61to warrant tagging them as a full blown SPDK application. 62 63This is a great place to learn about how SPDK works. In particular, check out 64`examples/nvme/hello_world`. 65 66## Include {#dir_include} 67 68The `include` directory is where all of the header files are located. The public API 69is all placed in the `spdk` subdirectory of `include` and we highly 70recommend that applications set their include path to the top level `include` 71directory and include the headers by prefixing `spdk/` like this: 72 73~~~{.c} 74#include "spdk/nvme.h" 75~~~ 76 77Most of the headers here correspond with a library in the `lib` directory. There 78are a few headers that stand alone, however. They are: 79 80 - `assert.h` 81 - `barrier.h` 82 - `endian.h` 83 - `fd.h` 84 - `mmio.h` 85 - `queue.h` and `queue_extras.h` 86 - `string.h` 87 88There is also an `spdk_internal` directory that contains header files widely included 89by libraries within SPDK, but that are not part of the public API and would not be 90installed on a user's system. 91 92## Scripts {#dir_scripts} 93 94The `scripts` directory contains convenient scripts for a number of operations. The two most 95important are `check_format.sh`, which will use astyle and pep8 to check C, C++, and Python 96coding style against our defined conventions, and `setup.sh` which binds and unbinds devices 97from kernel drivers. 98 99## Tests {#dir_tests} 100 101The `test` directory contains all of the tests for SPDK's components and the subdirectories mirror 102the structure of the entire repository. The tests are a mixture of unit tests and functional tests. 103