Adding upstream version 1.12.upstream/1.12

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

1 files changed, 157 insertions, 0 deletions

diff --git a/Documentation/nvme-format.txt b/Documentation/nvme-format.txt
new file mode 100644
index 0000000..9ef788a
--- /dev/null
+++ b/Documentation/nvme-format.txt
@@ -0,0 +1,157 @@
+nvme-format(1)
+==============
+
+NAME
+----
+nvme-format - Format an NVMe device
+
+SYNOPSIS
+--------
+[verse]
+'nvme format' <device> [--namespace-id=<nsid> | -n <nsid>]
+		    [--lbaf=<lbaf> | -l <lbaf>]
+		    [--block-size=<block size | -b <block size>]
+		    [--ses=<ses> | -s <ses>]
+		    [--pil=<pil> | -p <pil>]
+		    [--pi=<pi> | -i <pi>]
+		    [--ms=<ms> | -m <ms>]
+		    [--reset | -r ]
+		    [--force | -f ]
+		    [--timeout=<timeout> | -t <timeout> ]
+
+DESCRIPTION
+-----------
+For the NVMe device given, send an nvme Format Namespace admin command
+and provides the results.
+
+The <device> parameter is mandatory and may be either the NVMe character
+device (ex: /dev/nvme0), or a namespace block device (ex: /dev/nvme0n1).
+If the character device is given, and the controller does not support
+formatting of particular namespaces (ID_CTRL.FNA bit 0 enabled), then all
+namespaces will be formatted. If FNA is disabled, then the namespace
+identifier must be specified with the 'namespace-id' option; specify a
+value of 0xffffffff to send the format to all namespaces. If the block
+device is given, the namespace identifier will default to the namespace
+ID of the block device given, but can be overridden with the same option.
+
+Note, the numeric suffix on the character device, for example the '0' in
+/dev/nvme0, does NOT indicate this device handle is the parent controller
+of any namespaces with the same suffix. The namespace handle's numeral
+may be coming from the subsystem identifier, which is independent of the
+controller's identifier. Do not assume any particular device relationship
+based on their names. If you do, you may irrevocably erase data on an
+unintended device.
+
+On success, the program will automatically issue BLKRRPART ioctl to
+force rescanning the namespaces. If the driver is recent enough, this will
+automatically update the physical block size. If it is not recent enough,
+you will need to remove and rescan your device some other way for the
+new block size to be visible, if the size was changed with this command.
+
+OPTIONS
+-------
+-n <nsid>::
+--namespace-id=<nsid>::
+	Send the format command for the specified nsid. This can be
+	used to override the default value for either character device
+	(unspecified) or the block device (result from NVME_IOCTL_ID).
+
+-l <lbaf>::
+--lbaf=<lbaf>::
+	LBA Format: This field specifies the LBA format to apply to the NVM
+	media. This corresponds to the LBA formats indicated in the
+	Identify Namespace command. Conflicts with --block-size argument.
+	Defaults to 0.
+
+-b <block size>::
+--block-size=<block size>::
+	Block Size: This field is used to specify the target block size to
+	format to. Potential lbaf values will be scanned and the lowest
+	numbered will be selected for the format operation. Conflicts with
+	--lbaf argument.
+
+-s <ses>::
+--ses=<ses>::
+	Secure Erase Settings: This field specifies whether a secure
+	erase should be performed as part of the format and the type of
+	the secure erase operation. The erase applies to all user data,
+	regardless of location (e.g., within an exposed LBA, within a
+	cache, within deallocated LBAs, etc). Defaults to 0.
++
+[]
+|=================
+|Value|Definition
+|0|No secure erase operation requested
+|1|User Data Erase: All user data shall be erased, contents of the user
+data after the erase is indeterminate (e.g., the user data may be zero
+filled, one filled, etc). The controller may perform a cryptographic
+erase when a User Data Erase is requested if all user data is encrypted.
+|2|Cryptographic Erase: All user data shall be erased
+cryptographically. This is accomplished by deleting the encryption key.
+|3–7|Reserved
+|=================
+ 
+-p <pil>::
+--pil=<pil>::
+	Protection Information Location: If set to ‘1’ and protection
+	information is enabled, then protection information is transferred
+	as the first eight bytes of metadata. If cleared to ‘0’ and
+	protection information is enabled, then protection information
+	is transferred as the last eight bytes of metadata. Defaults to 0.
+
+-i <pi>::
+--pi=<pi>::
+	Protection Information: This field specifies whether end-to-end
+	data protection is enabled and the type of protection
+	information. Defaults to 0.
++
+[]
+|=================
+|Value|Definition
+|0|Protection information is not enabled
+|1|Protection information is enabled, Type 1
+|2|Protection information is enabled, Type 2
+|3|Protection information is enabled, Type 3
+|4–7|Reserved
+|=================
+
+-m <ms>::
+--ms=<ms>::
+	Metadata Settings: This field is set to ‘1’ if the metadata
+	is transferred as part of an extended data LBA. This field is
+	cleared to ‘0’ if the metadata is transferred as part of a
+	separate buffer. The metadata may include protection information,
+	based on the Protection Information (PI) field. Defaults to 0.
+
+-r::
+--reset::
+	Issue a reset after successful format. Must use the character
+	device for this.
+
+-f::
+--force::
+	Just send the command immediately without warning of the implications.
+
+-t <timeout>::
+--timeout=<timeout>::
+	Override default timeout value. In milliseconds.
+
+EXAMPLES
+--------
+* Format the device using all defaults:
++
+------------
+# nvme format /dev/nvme0n1
+------------
++
+
+* Format namespace 1 with user data secure erase settings and protection
+information:
++
+------------
+# nvme format /dev/nvme0 --namespace-id=1 --ses=1 --pi=1
+------------
+
+NVME
+----
+Part of the nvme-user suite