|
Packit Service |
b7b338 |
'\" t
|
|
Packit Service |
b7b338 |
.\" Title: nvme-format
|
|
Packit Service |
b7b338 |
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
|
|
Packit Service |
b7b338 |
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
|
|
Packit Service |
b7b338 |
.\" Date: 04/24/2020
|
|
Packit Service |
b7b338 |
.\" Manual: NVMe Manual
|
|
Packit Service |
b7b338 |
.\" Source: NVMe
|
|
Packit Service |
b7b338 |
.\" Language: English
|
|
Packit Service |
b7b338 |
.\"
|
|
Packit Service |
b7b338 |
.TH "NVME\-FORMAT" "1" "04/24/2020" "NVMe" "NVMe Manual"
|
|
Packit Service |
b7b338 |
.\" -----------------------------------------------------------------
|
|
Packit Service |
b7b338 |
.\" * Define some portability stuff
|
|
Packit Service |
b7b338 |
.\" -----------------------------------------------------------------
|
|
Packit Service |
b7b338 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Packit Service |
b7b338 |
.\" http://bugs.debian.org/507673
|
|
Packit Service |
b7b338 |
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
|
Packit Service |
b7b338 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Packit Service |
b7b338 |
.ie \n(.g .ds Aq \(aq
|
|
Packit Service |
b7b338 |
.el .ds Aq '
|
|
Packit Service |
b7b338 |
.\" -----------------------------------------------------------------
|
|
Packit Service |
b7b338 |
.\" * set default formatting
|
|
Packit Service |
b7b338 |
.\" -----------------------------------------------------------------
|
|
Packit Service |
b7b338 |
.\" disable hyphenation
|
|
Packit Service |
b7b338 |
.nh
|
|
Packit Service |
b7b338 |
.\" disable justification (adjust text to left margin only)
|
|
Packit Service |
b7b338 |
.ad l
|
|
Packit Service |
b7b338 |
.\" -----------------------------------------------------------------
|
|
Packit Service |
b7b338 |
.\" * MAIN CONTENT STARTS HERE *
|
|
Packit Service |
b7b338 |
.\" -----------------------------------------------------------------
|
|
Packit Service |
b7b338 |
.SH "NAME"
|
|
Packit Service |
b7b338 |
nvme-format \- Format an NVMe device
|
|
Packit Service |
b7b338 |
.SH "SYNOPSIS"
|
|
Packit Service |
b7b338 |
.sp
|
|
Packit Service |
b7b338 |
.nf
|
|
Packit Service |
b7b338 |
\fInvme format\fR <device> [\-\-namespace\-id=<nsid> | \-n <nsid>]
|
|
Packit Service |
b7b338 |
[\-\-lbaf=<lbaf> | \-l <lbaf>]
|
|
Packit Service |
b7b338 |
[\-\-block\-size=<block size | \-b <block size>]
|
|
Packit Service |
b7b338 |
[\-\-ses=<ses> | \-s <ses>]
|
|
Packit Service |
b7b338 |
[\-\-pil=<pil> | \-p <pil>]
|
|
Packit Service |
b7b338 |
[\-\-pi=<pi> | \-i <pi>]
|
|
Packit Service |
b7b338 |
[\-\-ms=<ms> | \-m <ms>]
|
|
Packit Service |
b7b338 |
[\-\-reset | \-r ]
|
|
Packit Service |
b7b338 |
[\-\-force | \-f ]
|
|
Packit Service |
b7b338 |
[\-\-timeout=<timeout> | \-t <timeout> ]
|
|
Packit Service |
b7b338 |
.fi
|
|
Packit Service |
b7b338 |
.SH "DESCRIPTION"
|
|
Packit Service |
b7b338 |
.sp
|
|
Packit Service |
b7b338 |
For the NVMe device given, send an nvme Format Namespace admin command and provides the results\&.
|
|
Packit Service |
b7b338 |
.sp
|
|
Packit Service |
b7b338 |
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 \fInamespace\-id\fR 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\&.
|
|
Packit Service |
b7b338 |
.sp
|
|
Packit Service |
b7b338 |
Note, the numeric suffix on the character device, for example the \fI0\fR in /dev/nvme0, does NOT indicate this device handle is the parent controller of any namespaces with the same suffix\&. The namespace handle\(cqs numeral may be coming from the subsystem identifier, which is independent of the controller\(cqs identifier\&. Do not assume any particular device relationship based on their names\&. If you do, you may irrevocably erase data on an unintended device\&.
|
|
Packit Service |
b7b338 |
.sp
|
|
Packit Service |
b7b338 |
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\&.
|
|
Packit Service |
b7b338 |
.SH "OPTIONS"
|
|
Packit Service |
b7b338 |
.PP
|
|
Packit Service |
b7b338 |
\-n <nsid>, \-\-namespace\-id=<nsid>
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
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)\&.
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.PP
|
|
Packit Service |
b7b338 |
\-l <lbaf>, \-\-lbaf=<lbaf>
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
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\&.
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.PP
|
|
Packit Service |
b7b338 |
\-b <block size>, \-\-block\-size=<block size>
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
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\&.
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.PP
|
|
Packit Service |
b7b338 |
\-s <ses>, \-\-ses=<ses>
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
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\&.
|
|
Packit Service |
b7b338 |
.TS
|
|
Packit Service |
b7b338 |
allbox tab(:);
|
|
Packit Service |
b7b338 |
lt lt
|
|
Packit Service |
b7b338 |
lt lt
|
|
Packit Service |
b7b338 |
lt lt
|
|
Packit Service |
b7b338 |
lt lt
|
|
Packit Service |
b7b338 |
lt lt.
|
|
Packit Service |
b7b338 |
T{
|
|
Packit Service |
b7b338 |
Value
|
|
Packit Service |
b7b338 |
T}:T{
|
|
Packit Service |
b7b338 |
Definition
|
|
Packit Service |
b7b338 |
T}
|
|
Packit Service |
b7b338 |
T{
|
|
Packit Service |
b7b338 |
0
|
|
Packit Service |
b7b338 |
T}:T{
|
|
Packit Service |
b7b338 |
No secure erase operation requested
|
|
Packit Service |
b7b338 |
T}
|
|
Packit Service |
b7b338 |
T{
|
|
Packit Service |
b7b338 |
1
|
|
Packit Service |
b7b338 |
T}:T{
|
|
Packit Service |
b7b338 |
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\&.
|
|
Packit Service |
b7b338 |
T}
|
|
Packit Service |
b7b338 |
T{
|
|
Packit Service |
b7b338 |
2
|
|
Packit Service |
b7b338 |
T}:T{
|
|
Packit Service |
b7b338 |
Cryptographic Erase: All user data shall be erased cryptographically\&. This is accomplished by deleting the encryption key\&.
|
|
Packit Service |
b7b338 |
T}
|
|
Packit Service |
b7b338 |
T{
|
|
Packit Service |
b7b338 |
3\(en7
|
|
Packit Service |
b7b338 |
T}:T{
|
|
Packit Service |
b7b338 |
Reserved
|
|
Packit Service |
b7b338 |
T}
|
|
Packit Service |
b7b338 |
.TE
|
|
Packit Service |
b7b338 |
.sp 1
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.PP
|
|
Packit Service |
b7b338 |
\-p <pil>, \-\-pil=<pil>
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
Protection Information Location: If set to \(oq1\(cq and protection information is enabled, then protection information is transferred as the first eight bytes of metadata\&. If cleared to \(oq0\(cq and protection information is enabled, then protection information is transferred as the last eight bytes of metadata\&. Defaults to 0\&.
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.PP
|
|
Packit Service |
b7b338 |
\-i <pi>, \-\-pi=<pi>
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
Protection Information: This field specifies whether end\-to\-end data protection is enabled and the type of protection information\&. Defaults to 0\&.
|
|
Packit Service |
b7b338 |
.TS
|
|
Packit Service |
b7b338 |
allbox tab(:);
|
|
Packit Service |
b7b338 |
lt lt
|
|
Packit Service |
b7b338 |
lt lt
|
|
Packit Service |
b7b338 |
lt lt
|
|
Packit Service |
b7b338 |
lt lt
|
|
Packit Service |
b7b338 |
lt lt
|
|
Packit Service |
b7b338 |
lt lt.
|
|
Packit Service |
b7b338 |
T{
|
|
Packit Service |
b7b338 |
Value
|
|
Packit Service |
b7b338 |
T}:T{
|
|
Packit Service |
b7b338 |
Definition
|
|
Packit Service |
b7b338 |
T}
|
|
Packit Service |
b7b338 |
T{
|
|
Packit Service |
b7b338 |
0
|
|
Packit Service |
b7b338 |
T}:T{
|
|
Packit Service |
b7b338 |
Protection information is not enabled
|
|
Packit Service |
b7b338 |
T}
|
|
Packit Service |
b7b338 |
T{
|
|
Packit Service |
b7b338 |
1
|
|
Packit Service |
b7b338 |
T}:T{
|
|
Packit Service |
b7b338 |
Protection information is enabled, Type 1
|
|
Packit Service |
b7b338 |
T}
|
|
Packit Service |
b7b338 |
T{
|
|
Packit Service |
b7b338 |
2
|
|
Packit Service |
b7b338 |
T}:T{
|
|
Packit Service |
b7b338 |
Protection information is enabled, Type 2
|
|
Packit Service |
b7b338 |
T}
|
|
Packit Service |
b7b338 |
T{
|
|
Packit Service |
b7b338 |
3
|
|
Packit Service |
b7b338 |
T}:T{
|
|
Packit Service |
b7b338 |
Protection information is enabled, Type 3
|
|
Packit Service |
b7b338 |
T}
|
|
Packit Service |
b7b338 |
T{
|
|
Packit Service |
b7b338 |
4\(en7
|
|
Packit Service |
b7b338 |
T}:T{
|
|
Packit Service |
b7b338 |
Reserved
|
|
Packit Service |
b7b338 |
T}
|
|
Packit Service |
b7b338 |
.TE
|
|
Packit Service |
b7b338 |
.sp 1
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.PP
|
|
Packit Service |
b7b338 |
\-m <ms>, \-\-ms=<ms>
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
Metadata Settings: This field is set to \(oq1\(cq if the metadata is transferred as part of an extended data LBA\&. This field is cleared to \(oq0\(cq 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\&.
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.PP
|
|
Packit Service |
b7b338 |
\-r, \-\-reset
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
Issue a reset after successful format\&. Must use the character device for this\&.
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.PP
|
|
Packit Service |
b7b338 |
\-f, \-\-force
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
Just send the command immediately without warning of the implications\&.
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.PP
|
|
Packit Service |
b7b338 |
\-t <timeout>, \-\-timeout=<timeout>
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
Override default timeout value\&. In milliseconds\&.
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.SH "EXAMPLES"
|
|
Packit Service |
b7b338 |
.sp
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
.ie n \{\
|
|
Packit Service |
b7b338 |
\h'-04'\(bu\h'+03'\c
|
|
Packit Service |
b7b338 |
.\}
|
|
Packit Service |
b7b338 |
.el \{\
|
|
Packit Service |
b7b338 |
.sp -1
|
|
Packit Service |
b7b338 |
.IP \(bu 2.3
|
|
Packit Service |
b7b338 |
.\}
|
|
Packit Service |
b7b338 |
Format the device using all defaults:
|
|
Packit Service |
b7b338 |
.sp
|
|
Packit Service |
b7b338 |
.if n \{\
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
.\}
|
|
Packit Service |
b7b338 |
.nf
|
|
Packit Service |
b7b338 |
# nvme format /dev/nvme0n1
|
|
Packit Service |
b7b338 |
.fi
|
|
Packit Service |
b7b338 |
.if n \{\
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.\}
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.sp
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
.ie n \{\
|
|
Packit Service |
b7b338 |
\h'-04'\(bu\h'+03'\c
|
|
Packit Service |
b7b338 |
.\}
|
|
Packit Service |
b7b338 |
.el \{\
|
|
Packit Service |
b7b338 |
.sp -1
|
|
Packit Service |
b7b338 |
.IP \(bu 2.3
|
|
Packit Service |
b7b338 |
.\}
|
|
Packit Service |
b7b338 |
Format namespace 1 with user data secure erase settings and protection information:
|
|
Packit Service |
b7b338 |
.sp
|
|
Packit Service |
b7b338 |
.if n \{\
|
|
Packit Service |
b7b338 |
.RS 4
|
|
Packit Service |
b7b338 |
.\}
|
|
Packit Service |
b7b338 |
.nf
|
|
Packit Service |
b7b338 |
# nvme format /dev/nvme0 \-\-namespace\-id=1 \-\-ses=1 \-\-pi=1
|
|
Packit Service |
b7b338 |
.fi
|
|
Packit Service |
b7b338 |
.if n \{\
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.\}
|
|
Packit Service |
b7b338 |
.RE
|
|
Packit Service |
b7b338 |
.SH "NVME"
|
|
Packit Service |
b7b338 |
.sp
|
|
Packit Service |
b7b338 |
Part of the nvme\-user suite
|