1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
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
|
