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 Message Passing and 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 SPDK Porting Guide for additional information.
The app top-level directory contains full-fledged applications, built out of the SPDK components. For a full overview, see An Overview of SPDK Applications.
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 JSON-RPC for additional information.
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:
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.
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.
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:
Most of the headers here correspond with a library in the lib directory. There are a few headers that stand alone, however. They are:
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.
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.
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.