From fb5e59bde66e2a011ad0a41df3c76dddf5061846 Mon Sep 17 00:00:00 2001 From: Ben Walker Date: Tue, 7 Aug 2018 14:40:54 -0700 Subject: [PATCH] doc: Make the application command page an application overview Add a brief section outlining what applications are available. Also word-wrap and do some minor grammar corrections on the rest of the text in the document. Change-Id: I4a3064e7a47e09a28a7b998955768f54a8a9cf9a Signed-off-by: Ben Walker Reviewed-on: https://review.gerrithub.io/421551 Tested-by: SPDK CI Jenkins Chandler-Test-Pool: SPDK Automated Test System Reviewed-by: Dariusz Stojaczyk Reviewed-by: Changpeng Liu Reviewed-by: Shuhei Matsumoto Reviewed-by: Jim Harris --- doc/Doxyfile | 2 +- ...{user_guides_common.md => applications.md} | 68 +++++++++++++------ doc/user_guides.md | 2 +- 3 files changed, 48 insertions(+), 24 deletions(-) rename doc/{user_guides_common.md => applications.md} (50%) diff --git a/doc/Doxyfile b/doc/Doxyfile index 7a38c1032..9490bb8dc 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -795,6 +795,7 @@ INPUT = ../include/spdk \ performance_reports.md \ \ about.md \ + applications.md \ changelog.md \ concurrency.md \ directory_structure.md \ @@ -818,7 +819,6 @@ INPUT = ../include/spdk \ peer_2_peer.md \ spdkcli.md \ ssd_internals.md \ - user_guides_common.md \ userspace.md \ vagrant.md \ vhost.md \ diff --git a/doc/user_guides_common.md b/doc/applications.md similarity index 50% rename from doc/user_guides_common.md rename to doc/applications.md index 25ab260fd..5f37de6b3 100644 --- a/doc/user_guides_common.md +++ b/doc/applications.md @@ -1,12 +1,28 @@ -# Configuring SPDK Applications {#user_guides_common} +# An Overview of SPDK Applications {#app_overview} -# Overview {#user_guides_common_overview} +SPDK is primarily a development kit that delivers libraries and header files for +use in other applications. However, SPDK also contains a number of applications. +These applications are primarily used to test the libraries, but many are full +featured and high quality. The major applications in SPDK are: -This guide covers topics common to all applications that leverage SPDK's application framework. +- @ref iscsi +- @ref nvmf +- @ref vhost +- SPDK Target (a unified application combining the above three) -## Command Line Parameters {#common_cmd_line_args} +There are also a number of tools and examples in the `examples` directory. -The SPDK application framework defines a set of base command line flags for all applications that use it. Specific applications may implement additional flags. +The SPDK targets are all based on a common framework so they have much in +common. The framework defines a concept called a `subsystem` and all +functionality is implemented in various subsystems. Subsystems have a unified +initialization and teardown path. + +# Configuring SPDK Applications {#app_config} + +## Command Line Parameters {#app_cmd_line_args} + +The SPDK application framework defines a set of base command line flags for all +applications that use it. Specific applications may implement additional flags. Param | Type | Default | Description -------- | -------- | ---------------------- | ----------- @@ -31,42 +47,51 @@ Param | Type | Default | Description ### Configuration file {#cmd_arg_config_file} -Historically, the SPDK application framework was configured using a configuration file. This is still supported, but is -considered deprecated in favor of JSON RPC configuration. See @ref jsonrpc for details. +Historically, the SPDK applications were configured using a configuration file. +This is still supported, but is considered deprecated in favor of JSON RPC +configuration. See @ref jsonrpc for details. Note that `-c` and `-w` cannot be used at the same time. ### Deferred initialization {#cmd_arg_deferred_initialization} -SPDK applications progress through a set of states, including `STARTUP` and `RUNTIME`. +SPDK applications progress through a set of states beginning with `STARTUP` and +ending with `RUNTIME`. -If `-w` parameter is provided SPDK will pause just before starting subsystem initialization. This state is called `STARTUP`. -The JSON RPC server is ready but list of commands is limited to only those that are needed to set application global parameters. -Those parameters can't be changed after SPDK application enters `RUNTIME` state. When client finishes preconfiguring SPDK subsystems -it needs to issue @ref rpc_start_subsystem_init RPC command to continue initialization process. After `rpc_start_subsystem_init` -returns `true` the SPDK will enter `RUNTIME` state and list of available commands will change again. From now on SPDK is ready -for further configuration. +If the `-w` parameter is provided SPDK will pause just before starting subsystem +initialization. This state is called `STARTUP`. The JSON RPC server is ready but +only a small subsystem of commands are available to set up initialization +parameters. Those parameters can't be changed after the SPDK application enters +`RUNTIME` state. When the client finishes configuring the SPDK subsystems it +needs to issue the @ref rpc_start_subsystem_init RPC command to begin the +initialization process. After `rpc_start_subsystem_init` returns `true` SPDK +will enter the `RUNTIME` state and the list of available commands becomes much +larger. -To know what RPC methods are valid in current state issue `get_rpc_methods` with parameter `current` set to `true`. +To see which RPC methods are available in the current state, issue the +`get_rpc_methods` with the parameter `current` set to `true`. For more details see @ref jsonrpc documentation. ### Disable PCI access {#cmd_arg_disable_pci_access} -If SPDK is run with PCI access disabled it won't detect any PCI devices, including NVMe, IOAT, NICs etc. Also VFIO and UIO -kernel modules are not needed anymore. +If SPDK is run with PCI access disabled it won't detect any PCI devices. This +includes primarily NVMe and IOAT devices. Also, the VFIO and UIO kernel modules +are not required in this mode. ### PCI address blacklist and whitelist {#cmd_arg_pci_blacklist_whitelist} Note that `-B` and `-W` cannot be used at the same time. -If blacklist is used all devices with provided PCI address will be ignored. If whitelist is used only those -devices will be probed. You can used `-B` or `-W` more than once to add more than one device to list. +If a blacklist is used all devices with the provided PCI address will be +ignored. If a whitelist is used only those devices will be probed. You can used +`-B` or `-W` more than once to add more than one device to list. ### Debug log flags {#cmd_arg_debug_log_flags} -Use comma separated list of flags or use `-L all` to enable all debug flags. Run SPDK application with `-h` to get a list -of all valid flags. Debug flags are only available in debug builds of SPDK. +Use a comma separated list of flags or use `-L all` to enable all debug flags. +Run SPDK application with `-h` to get a list of all valid flags. Debug flags are +only available in debug builds of SPDK. ## CPU mask {#cpu_mask} @@ -75,7 +100,6 @@ Whenever the `CPU mask` is mentioned it is a string in one of the following form - Case insensitive hexadecimal string with or without "0x" prefix. - Comma separated list of CPUs or list of CPU ranges. Use '-' to define range. - ### Example The following CPU masks are equal and correspond to CPUs 0, 1, 2, 8, 9, 10, 11 and 12: diff --git a/doc/user_guides.md b/doc/user_guides.md index 832761363..77793a584 100644 --- a/doc/user_guides.md +++ b/doc/user_guides.md @@ -1,6 +1,6 @@ # User Guides {#user_guides} -- @subpage user_guides_common +- @subpage app_overview - @subpage iscsi - @subpage nvmf - @subpage vhost