163 lines
5.5 KiB
Text
163 lines
5.5 KiB
Text
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
|