1NVME-FORMAT(1) NVMe Manual NVME-FORMAT(1)
2
6 nvme-format - Format an NVMe device
7
9 nvme format <device> [--namespace-id=<nsid> | -n <nsid>]
10 [--lbaf=<lbaf> | -l <lbaf>]
11 [--block-size=<block size | -b <block size>]
12 [--ses=<ses> | -s <ses>]
13 [--pil=<pil> | -p <pil>]
14 [--pi=<pi> | -i <pi>]
15 [--ms=<ms> | -m <ms>]
16 [--reset | -r ]
17 [--force ]
18 [--timeout=<timeout> | -t <timeout> ]
19
21 For the NVMe device given, send an nvme Format Namespace admin command
22 and provides the results.
23 The <device> parameter is mandatory and may be either the NVMe
25 character device (ex: /dev/nvme0), or a namespace block device (ex:
26 /dev/nvme0n1). If the character device is given, and the controller
27 does not support formatting of particular namespaces (ID_CTRL.FNA bit 0
28 enabled), then all namespaces will be formatted. If FNA is disabled,
29 then the namespace identifier must be specified with the namespace-id
30 option; specify a value of 0xffffffff to send the format to all
31 namespaces. If the block device is given, the namespace identifier will
32 default to the namespace ID of the block device given, but can be
33 overridden with the same option.
34 Note, the numeric suffix on the character device, for example the 0 in
36 /dev/nvme0, does NOT indicate this device handle is the parent
37 controller of any namespaces with the same suffix. The namespace
38 handle’s numeral may be coming from the subsystem identifier, which is
39 independent of the controller’s identifier. Do not assume any
40 particular device relationship based on their names. If you do, you may
41 irrevocably erase data on an unintended device.
42 On success, the program will automatically issue BLKRRPART ioctl to
44 force rescanning the namespaces. If the driver is recent enough, this
45 will automatically update the physical block size. If it is not recent
46 enough, you will need to remove and rescan your device some other way
47 for the new block size to be visible, if the size was changed with this
48 command.
49
51 -n <nsid>, --namespace-id=<nsid>
52 Send the format command for the specified nsid. This can be used to
53 override the default value for either character device
54 (unspecified) or the block device (result from NVME_IOCTL_ID).
55 -l <lbaf>, --lbaf=<lbaf>
57 LBA Format: This field specifies the LBA format to apply to the NVM
58 media. This corresponds to the LBA formats indicated in the
59 Identify Namespace command. Conflicts with --block-size argument.
60 Defaults to 0.
61 -b <block size>, --block-size=<block size>
63 Block Size: This field is used to specify the target block size to
64 format to. Potential lbaf values will be scanned and the lowest
65 numbered will be selected for the format operation. Conflicts with
66 --lbaf argument.
67 -s <ses>, --ses=<ses>
69 Secure Erase Settings: This field specifies whether a secure erase
70 should be performed as part of the format and the type of the
71 secure erase operation. The erase applies to all user data,
72 regardless of location (e.g., within an exposed LBA, within a
73 cache, within deallocated LBAs, etc). Defaults to 0.
74 ┌──────┬────────────────────────────┐
76 │Value │ Definition │
77 ├──────┼────────────────────────────┤
78 │0 │ No secure erase operation │
79 │ │ requested │
80 ├──────┼────────────────────────────┤
81 │1 │ User Data Erase: All user │
82 │ │ data shall be erased, │
83 │ │ contents of the user data │
84 │ │ after the erase is │
85 │ │ indeterminate (e.g., the │
86 │ │ user data may be zero │
87 │ │ filled, one filled, etc). │
88 │ │ The controller may perform │
89 │ │ a cryptographic erase when │
90 │ │ a User Data Erase is │
91 │ │ requested if all user data │
92 │ │ is encrypted. │
93 ├──────┼────────────────────────────┤
94 │2 │ Cryptographic Erase: All │
95 │ │ user data shall be erased │
96 │ │ cryptographically. This is │
97 │ │ accomplished by deleting │
98 │ │ the encryption key. │
99 ├──────┼────────────────────────────┤
100 │3–7 │ Reserved │
101 └──────┴────────────────────────────┘
102 -p <pil>, --pil=<pil>
104 Protection Information Location: If set to ‘1’ and protection
105 information is enabled, then protection information is transferred
106 as the first eight bytes of metadata. If cleared to ‘0’ and
107 protection information is enabled, then protection information is
108 transferred as the last eight bytes of metadata. Defaults to 0.
109 -i <pi>, --pi=<pi>
111 Protection Information: This field specifies whether end-to-end
112 data protection is enabled and the type of protection information.
113 Defaults to 0.
114 ┌──────┬───────────────────────────┐
116 │Value │ Definition │
117 ├──────┼───────────────────────────┤
118 │0 │ Protection information is │
119 │ │ not enabled │
120 ├──────┼───────────────────────────┤
121 │1 │ Protection information is │
122 │ │ enabled, Type 1 │
123 ├──────┼───────────────────────────┤
124 │2 │ Protection information is │
125 │ │ enabled, Type 2 │
126 ├──────┼───────────────────────────┤
127 │3 │ Protection information is │
128 │ │ enabled, Type 3 │
129 ├──────┼───────────────────────────┤
130 │4–7 │ Reserved │
131 └──────┴───────────────────────────┘
132 -m <ms>, --ms=<ms>
134 Metadata Settings: This field is set to ‘1’ if the metadata is
135 transferred as part of an extended data LBA. This field is cleared
136 to ‘0’ if the metadata is transferred as part of a separate buffer.
137 The metadata may include protection information, based on the
138 Protection Information (PI) field. Defaults to 0.
139 -r, --reset
141 Issue a reset after successful format. Must use the character
142 device for this.
143 --force
145 Just send the command immediately without warning of the
146 implications.
147 -t <timeout>, --timeout=<timeout>
149 Override default timeout value. In milliseconds.
150
152 • Format the device using all defaults:
153 # nvme format /dev/nvme0n1
155 • Format namespace 1 with user data secure erase settings and
157 protection information:
158 # nvme format /dev/nvme0 --namespace-id=1 --ses=1 --pi=1
160
162 Part of the nvme-user suite
163NVMe 10/06/2023 NVME-FORMAT(1)