diff options
Diffstat (limited to 'Documentation/nvme-format.txt')
| -rw-r--r-- | Documentation/nvme-format.txt | 163 |
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 |