summaryrefslogtreecommitdiffstats
path: root/Documentation/nvme-format.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/nvme-format.txt')
-rw-r--r--Documentation/nvme-format.txt163
1 files changed, 163 insertions, 0 deletions
diff --git a/Documentation/nvme-format.txt b/Documentation/nvme-format.txt
new file mode 100644
index 0000000..e4623f1
--- /dev/null
+++ b/Documentation/nvme-format.txt
@@ -0,0 +1,163 @@
+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]
+ [--timeout=<timeout> | -t <timeout>]
+ [--output-format=<fmt> | -o <fmt>] [--verbose | -v]
+
+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.
+
+--force::
+ Just send the command immediately without warning of the implications.
+
+-t <timeout>::
+--timeout=<timeout>::
+ Override default timeout value. In milliseconds.
+
+-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
+--------
+* 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