From dc597ce8df5ae6efd2728a2d7ba7d92486028f79 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 2 Jul 2021 22:40:30 +0200 Subject: Adding upstream version 1.12. Signed-off-by: Daniel Baumann --- Documentation/nvme-format.txt | 157 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 Documentation/nvme-format.txt (limited to 'Documentation/nvme-format.txt') diff --git a/Documentation/nvme-format.txt b/Documentation/nvme-format.txt new file mode 100644 index 0000000..9ef788a --- /dev/null +++ b/Documentation/nvme-format.txt @@ -0,0 +1,157 @@ +nvme-format(1) +============== + +NAME +---- +nvme-format - Format an NVMe device + +SYNOPSIS +-------- +[verse] +'nvme format' [--namespace-id= | -n ] + [--lbaf= | -l ] + [--block-size=] + [--ses= | -s ] + [--pil= | -p ] + [--pi= | -i ] + [--ms= | -m ] + [--reset | -r ] + [--force | -f ] + [--timeout= | -t ] + +DESCRIPTION +----------- +For the NVMe device given, send an nvme Format Namespace admin command +and provides the results. + +The 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 :: +--namespace-id=:: + 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=:: + 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: 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=:: + 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=:: + 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=:: + 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=:: + 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. + +-f:: +--force:: + Just send the command immediately without warning of the implications. + +-t :: +--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 -- cgit v1.2.3