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 <benjamin.walker@intel.com>
Reviewed-on: https://review.gerrithub.io/421551
Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
Chandler-Test-Pool: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Dariusz Stojaczyk <dariuszx.stojaczyk@intel.com>
Reviewed-by: Changpeng Liu <changpeng.liu@intel.com>
Reviewed-by: Shuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com>
Reviewed-by: Jim Harris <james.r.harris@intel.com>

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 \

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:

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