Adding upstream version 2.8.upstream/2.8

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 267 insertions, 0 deletions

diff --git a/Documentation/nvme-connect-all.txt b/Documentation/nvme-connect-all.txt
new file mode 100644
index 0000000..4cd1873
--- /dev/null
+++ b/Documentation/nvme-connect-all.txt
@@ -0,0 +1,267 @@
+nvme-connect-all(1)
+===================
+
+NAME
+----
+nvme-connect-all - Discover and Connect to Fabrics controllers.
+
+SYNOPSIS
+--------
+[verse]
+'nvme connect-all' [--transport=<trtype> | -t <trtype>]
+			[--nqn=<subnqn> | -n <subnqn>]
+			[--traddr=<traddr> | -a <traddr>]
+			[--trsvcid=<trsvcid> | -s <trsvcid>]
+			[--host-traddr=<traddr> | -w <traddr>]
+			[--host-iface=<iface> | -f <iface>]
+			[--hostnqn=<hostnqn> | -q <hostnqn>]
+			[--hostid=<hostid> | -I <hostid>]
+			[--raw=<filename> | -r <filename>]
+			[--device=<device> | -d <device>]
+			[--config=<filename> | -J <cfg>]
+			[--keep-alive-tmo=<sec> | -k <sec>]
+			[--reconnect-delay=<#> | -c <#>]
+			[--ctrl-loss-tmo=<#>	 | -l <#>]
+			[--nr-io-queues=<#> | -i <#>]
+			[--nr-write-queues=<#> | -W <#>]
+			[--nr-poll-queues=<#> | -P <#>]
+			[--queue-size=<#> | -Q <#>] [--keyring=<#>]
+			[--tls_key=<#>] [--hdr-digest | -g] [--data-digest | -G]
+			[--persistent | -p] [--tls] [--concat] [--quiet | -S]
+			[--dump-config | -O] [--nbft] [--no-nbft]
+			[--nbft-path=<STR>] [--context=<STR>]
+			[--output-format=<fmt> | -o <fmt>] [--verbose | -v]
+
+DESCRIPTION
+-----------
+Send one or more Discovery requests to a NVMe over Fabrics Discovery
+Controller, and create controllers for the returned discovery records.
+
+If no parameters are given, then 'nvme connect-all' will attempt to
+find a @SYSCONFDIR@/nvme/discovery.conf file to use to supply a list of
+connect-all commands to run. If no @SYSCONFDIR@/nvme/discovery.conf file
+exists, the command will quit with an error.
+
+Otherwise a specific Discovery Controller should be specified using the
+--transport, --traddr and if necessary the --trsvcid and a Discovery
+request will be sent to the specified Discovery Controller.
+
+See the documentation for the nvme-discover(1) command for further
+background.
+
+OPTIONS
+-------
+-t <trtype>::
+--transport=<trtype>::
+	This field specifies the network fabric being used for
+	a NVMe-over-Fabrics network. Current string values include:
++
+[]
+|=================
+|Value|Definition
+|rdma|The network fabric is an rdma network (RoCE, iWARP, Infiniband, basic rdma, etc)
+|fc |*WIP* The network fabric is a Fibre Channel network.
+|tcp |The network fabric is a TCP/IP network.
+|loop|Connect to a NVMe over Fabrics target on the local host
+|=================
+
+-n <subnqn>::
+--nqn <subnqn>::
+	This field specifies the name for the NVMe subsystem to connect to.
+
+-a <traddr>::
+--traddr=<traddr>::
+	This field specifies the network address of the Discovery Controller.
+	For transports using IP addressing (e.g. rdma) this should be an
+	IP-based address (ex. IPv4).
+
+-s <trsvcid>::
+--trsvcid=<trsvcid>::
+	This field specifies the transport service id. For transports using IP
+	addressing (e.g. rdma) this field is the port number. By default, the IP
+	port number for the RDMA transport is 4420.
+
+-w <traddr>::
+--host-traddr=<traddr>::
+	This field specifies the network address used on the host to connect
+	to the Controller. For TCP, this sets the source address on the socket.
+
+-f <iface>::
+--host-iface=<iface>::
+	This field specifies the network interface used on the host to connect
+	to the Controller (e.g. IP eth1, enp2s0, enx78e7d1ea46da). This forces
+	the connection to be made on a specific interface instead of letting
+	the system decide.
+
+-q <hostnqn>::
+--hostnqn=<hostnqn>::
+	Overrides the default Host NQN that identifies the NVMe Host.
+	If this option is not specified, the default is read from
+	@SYSCONFDIR@/nvme/hostnqn first. If that does not exist, the
+	autogenerated NQN value from the NVMe Host kernel module is used next.
+	The Host NQN uniquely identifies the NVMe Host, and may be used by the
+	the Discovery Controller to control what NVMe Target resources are
+	allocated to the NVMe Host for a connection.
+
+-I <hostid>::
+--hostid=<hostid>::
+	UUID(Universally Unique Identifier) to be discovered which should be
+	formatted.
+
+-r <filename>::
+--raw=<filename>::
+	This field will take the output of the 'nvme connect-all' command
+	and dump it to a raw binary file. By default 'nvme connect-all' will
+	dump the output to stdout.
+
+-d <device>::
+--device=<device>::
+	This field takes a device as input. It must be a persistent device
+	associated with a Discovery Controller previously created by the
+	command "connect-all" or "discover". <device> follows the format
+	nvme*, eg. nvme0, nvme1.
+
+-J <filename>::
+--config=<filename>::
+	Use the specified JSON configuration file instead of the
+	default @SYSCONFDIR@/nvme/config.json file or 'none' to not read in
+	an existing configuration file. The JSON configuration file
+	format is documented in
+	https://github.com/linux-nvme/libnvme/blob/master/doc/config-schema.json
+
+-k <#>::
+--keep-alive-tmo=<#>::
+	Overrides the default keep alive timeout (in seconds). This
+	option will be ignored for discovery, but will be passed on to
+	the subsequent connect call.
+
+-c <#>::
+--reconnect-delay=<#>::
+	Overrides the default delay (in seconds) before reconnect is attempted
+	after a connect loss.
+
+-l <#>::
+--ctrl-loss-tmo=<#>::
+	Overrides the default controller loss timeout period (in seconds).
+
+-i <#>::
+--nr-io-queues=<#>::
+	Overrides the default number of I/O queues create by the driver.
+	This option will be ignored for discovery, but will be passed on
+	to the subsequent connect call.
+
+-W <#>::
+--nr-write-queues=<#>::
+	Adds additional queues that will be used for write I/O.
+
+-P <#>::
+--nr-poll-queues=<#>::
+	Adds additional queues that will be used for polling latency sensitive I/O.
+
+-Q <#>::
+--queue-size=<#>::
+	Overrides the default number of elements in the I/O queues created
+	by the driver. This option will be ignored for discovery, but will be
+	passed on to the subsequent connect call.
+
+--keyring=<#>::
+	Keyring for TLS key lookup.
+
+--tls_key=<#>::
+	TLS key for the connection (TCP).
+
+-g::
+--hdr-digest::
+	Generates/verifies header digest (TCP).
+
+-G::
+--data-digest::
+	Generates/verifies data digest (TCP).
+
+-p::
+--persistent::
+	Don't remove the discovery controller after retrieving the discovery
+	log page.
+
+--tls::
+	Enable TLS encryption (TCP).
+
+--concat::
+	Enable secure concatenation (TCP).
+
+-S::
+--quiet::
+	Suppress error messages.
+
+-O::
+--dump-config::
+	Print out resulting JSON configuration file to stdout.
+
+--nbft::
+	Only look at NBFT tables
+
+--no-nbft::
+	Do not look at NBFT tables
+
+--nbft-path=<STR>::
+	Use a user-defined path to the NBFT tables
+
+--context <STR>::
+	Set the execution context to <STR>. This allows to coordinate
+	the management of the global resources.
+
+-o <fmt>::
+--output-format=<fmt>::
+	Set the reporting format to 'normal', 'json' or 'binary'. Only one
+	output format can be used at a time.
+
+-v::
+--verbose::
+	Increase the information detail in the output.
+
+EXAMPLES
+--------
+* Connect to all records returned by the Discover Controller with IP4 address
+192.168.1.3 for all resources allocated for NVMe Host name host1-rogue-nqn on
+the RDMA network. Port 4420 is used by default:
++
+------------
+# nvme connect-all --transport=rdma --traddr=192.168.1.3 \
+--hostnqn=host1-rogue-nqn
+------------
++
+* Issue a 'nvme connect-all' command using the default system defined NBFT tables:
++
+-----------
+# nvme connect-all --nbft
+------------
++
+* Issue a 'nvme connect-all' command with a user-defined path for the NBFT table:
++
+-----------
+# nvme connet-all --nbft-path=/sys/firmware/acpi/tables/NBFT1
+------------
++
+* Issue a 'nvme connect-all' command using a @SYSCONFDIR@/nvme/discovery.conf file:
++
+-----------
+# Machine default 'nvme discover' commands. Query the
+# Discovery Controller's two ports (some resources may only
+# be accessible on a single port). Note an official
+# nqn (Host) name defined in the NVMe specification is being used
+# in this example.
+-t rdma -a 192.168.69.33 -s 4420 -q nqn.2014-08.com.example:nvme:nvm-subsystem-sn-d78432
+-t rdma -a 192.168.1.4   -s 4420 -q nqn.2014-08.com.example:nvme:nvm-subsystem-sn-d78432
+
+At the prompt type "nvme connect-all".
+
+------------
+
+SEE ALSO
+--------
+nvme-discover(1)
+nvme-connect(1)
+
+NVME
+----
+Part of the nvme-user suite