1NVME-FORMAT(1)                    NVMe Manual                   NVME-FORMAT(1)
2
3
4

NAME

6       nvme-format - Format an NVMe device
7

SYNOPSIS

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 | -f ]
18                           [--timeout=<timeout> | -t <timeout> ]
19

DESCRIPTION

21       For the NVMe device given, send an nvme Format Namespace admin command
22       and provides the results.
23
24       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
35       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
43       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

OPTIONS

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
56       -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
62       -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
68       -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
75           ┌──────┬────────────────────────────┐
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
103       -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
110       -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
115           ┌──────┬───────────────────────────┐
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
133       -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
140       -r, --reset
141           Issue a reset after successful format. Must use the character
142           device for this.
143
144       -f, --force
145           Just send the command immediately without warning of the
146           implications.
147
148       -t <timeout>, --timeout=<timeout>
149           Override default timeout value. In milliseconds.
150

EXAMPLES

152       ·   Format the device using all defaults:
153
154               # nvme format /dev/nvme0n1
155
156       ·   Format namespace 1 with user data secure erase settings and
157           protection information:
158
159               # nvme format /dev/nvme0 --namespace-id=1 --ses=1 --pi=1
160

NVME

162       Part of the nvme-user suite
163
164
165
166NVMe                              04/24/2020                    NVME-FORMAT(1)
Impressum