nvme-format(1)

SYNOPSIS

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

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

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

+nvme-format(1) Manual Page +

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLES

NVME