nvmf: Update the getting started guide

Change-Id: Iec2e19f487f5f0da141f0615be0aff9b7f9c3f2e
Signed-off-by: Ben Walker <benjamin.walker@intel.com>

doc/nvmf/getting_started.txt

@@ -34,10 +34,29 @@
 /**
  * \page nvmf_getting_started NVMf Getting Started Guide
 
+The NVMe over Fabrics target is a user space application that presents block devices over the
+network using RDMA. It requires an RDMA-capable NIC with its corresponding OFED software package
+installed to run. The target should work on all flavors of RDMA, but it is currently tested against
+Mellanox NICs (RoCEv2) and Chelsio NICs (iWARP).
+
+The NVMe over Fabrics specification defines subsystems that can be exported over the network. SPDK
+has chosen to call the software that exports these subsystems a "target", which is the term used
+for iSCSI. The specification refers to the "client" that connects to the target as a "host". Many
+people will also refer to the host as an "initiator", which is the equivalent thing in iSCSI
+parlance. SPDK will try to stick to the terms "target" and "host" to match the specification.
+
+There will be both a target and a host implemented in the Linux kernel, and these are available
+today as a set of patches against the kernel 4.8 release candidate. All of the testing against th
+SPDK target has been against the proposed Linux kernel host. This means that for at least the host
+machine, the kernel will need to be a release candidate until the code is actually merged. For the
+system running the SPDK target, however, you can run any modern flavor of Linux as required by your
+NIC vendor's OFED distribution.
 
 \section nvmf_prereqs Prerequisites
 
-To build nvmf there are some package dependencies.
+This guide starts by assuming that you can already build the standard SPDK distribution on your
+platform. By default, the NVMf target is not built. To build NVMf there are some additional
+dependencies.
 
 Fedora:
 \verbatim
@@ -49,43 +68,27 @@ Ubuntu:
 apt-get install libibverbs-dev librdmacm-dev
 \endverbatim
 
-Then build SPDK with the NVMf target enabled, either by editing CONFIG
+Then build SPDK with the NVMf target enabled, either by editing CONFIG to enable CONFIG_RDMA or
-to enable CONFIG_RDMA or enabling it on the `make` command line:
+enabling it on the `make` command line:
 
 \verbatim
 make CONFIG_RDMA=y <other config parameters>
 \endverbatim
 
+Once built, the binary will be in `app/nvmf_tgt`.
+
 \section nvmf_config Configuring NVMf
 
-An NVMf specific configuration file is used to configure, or 'provision',
+An NVMf specific configuration file is used to configure, or 'provision', the NVMf target. This 
-the NVMf target. This file defines the following:
+file's primary purpose is to define subsystems. A fully documented example configuration file is
+located at `etc/spdk/nvmf.conf.in`.
 
- - general application parameters
+You should make a copy of the example configuration file, modify it to suit your environment, and
- - global NVMf parameters
+then run the nvmf_tgt application and pass it the configuration file using the -c option. Right now,
- - ports that define local RDMA interface ports the nvmf target will
+the target requires elevated privileges (root) to run.
-     use for network access
- - initiator groups with names and addresses to allow access to nvmf target
-     subsystems
- - list of NVMe HW device candidates to share via NVMf
- - NVMf target subsystem(s) that define the provision mappings between remote
-     initiator groups and local target ports, and NVMe device
-     namespaces
 
-An example nvmf configuration file included with this package at
+\verbatim
-`etc/spdk/nvmf.conf.in`.
+app/nvmf_tgt/nvmf_tgt -c /path/to/nvmf.conf
-
+\endverbatim
-You must edit a version of this file for use in your environment and copy it
-to /usr/local/etc/spdk/nvmf.conf.  Alternatively, you may also specify the
-configuration file explicitly using `-c /path/to/nvmf.conf` when starting `nvmf_tgt`.
-
-The `Port` and `Host` sections must be updated in all cases to
-match the IP addresses in your network environment.
-
-The `Nvme` section must also be updated with a the list of NVMe devices
-that will be exported.  Each device is identified by a PCI bus, device, and function.
-The NVMf target will display a list of NVMe devices discovered
-in the system.  This information can then be used to select the list of devices
-to populate this configuration file section.
 
 */