nvme-format(1)
==============

NAME
----
nvme-format - Format an NVMe device

SYNOPSIS
--------
[verse]
'nvme format' <device> [--namespace-id=<nsid> | -n <nsid>]
		    [--lbaf=<lbaf> | -l <lbaf>]
		    [--ses=<ses> | -s <ses>]
		    [--pil=<pil> | -p <pil>]
		    [--pi=<pi> | -i <pi>]
		    [--ms=<ms> | -m <ms>]
		    [--reset | -r ]
		    [--timeout | -t ]

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, the namespace identifier will default
to 0xffffffff to send the format to all namespace, but can be overridden
to any namespace with the 'namespace-id' option. 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.

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.

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
	(0xffffffff) 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. Defaults to 0.

-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.

-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
