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

DESCRIPTION

20       For the NVMe device given, send an nvme Format Namespace admin command
21       and provides the results.
22
23       The <device> parameter is mandatory and may be either the NVMe
24       character device (ex: /dev/nvme0), or a namespace block device (ex:
25       /dev/nvme0n1). If the character device is given, the namespace
26       identifier will default to 0xffffffff to send the format to all
27       namespace, but can be overridden to any namespace with the namespace-id
28       option. If the block device is given, the namespace identifier will
29       default to the namespace id of the block device given, but can be
30       overridden with the same option.
31
32       On success, the program will automatically issue BLKRRPART ioctl to
33       force rescanning the namespaces. If the driver is recent enough, this
34       will automatically update the physical block size. If it is not recent
35       enough, you will need to remove and rescan your device some other way
36       for the new block size to be visible.
37

OPTIONS

39       -n <nsid>, --namespace-id=<nsid>
40           Send the format command for the specified nsid. This can be used to
41           override the default value for either character device (0xffffffff)
42           or the block device (result from NVME_IOCTL_ID).
43
44       -l <lbaf>, --lbaf=<lbaf>
45           LBA Format: This field specifies the LBA format to apply to the NVM
46           media. This corresponds to the LBA formats indicated in the
47           Identify Namespace command. Conflicts with --block-size argument.
48           Defaults to 0.
49
50       -b <block size>, --block-size=<block size>
51           Block Size: This field is used to specify the target block size to
52           format to. Potential lbaf values will be scanned and the lowest
53           numbered will be selected for the format operation. Conflicts with
54           --lbaf argument.
55
56       -s <ses>, --ses=<ses>
57           Secure Erase Settings: This field specifies whether a secure erase
58           should be performed as part of the format and the type of the
59           secure erase operation. The erase applies to all user data,
60           regardless of location (e.g., within an exposed LBA, within a
61           cache, within deallocated LBAs, etc). Defaults to 0.
62
63           ┌──────┬────────────────────────────┐
64           │Value │ Definition                 │
65           ├──────┼────────────────────────────┤
66           │0     │ No secure erase operation  │
67           │      │ requested                  │
68           ├──────┼────────────────────────────┤
69           │1     │ User Data Erase: All user  │
70           │      │ data shall be erased,      │
71           │      │ contents of the user data  │
72           │      │ after the erase is         │
73           │      │ indeterminate (e.g., the   │
74           │      │ user data may be zero      │
75           │      │ filled, one filled, etc).  │
76           │      │ The controller may perform │
77           │      │ a cryptographic erase when │
78           │      │ a User Data Erase is       │
79           │      │ requested if all user data │
80           │      │ is encrypted.              │
81           ├──────┼────────────────────────────┤
82           │2     │ Cryptographic Erase: All   │
83           │      │ user data shall be erased  │
84           │      │ cryptographically. This is │
85           │      │ accomplished by deleting   │
86           │      │ the encryption key.        │
87           ├──────┼────────────────────────────┤
88           │3–7   │ Reserved                   │
89           └──────┴────────────────────────────┘
90
91       -p <pil>, --pil=<pil>
92           Protection Information Location: If set to ‘1’ and protection
93           information is enabled, then protection information is transferred
94           as the first eight bytes of metadata. If cleared to ‘0’ and
95           protection information is enabled, then protection information is
96           transferred as the last eight bytes of metadata. Defaults to 0.
97
98       -i <pi>, --pi=<pi>
99           Protection Information: This field specifies whether end-to-end
100           data protection is enabled and the type of protection information.
101           Defaults to 0.
102
103           ┌──────┬───────────────────────────┐
104           │Value │ Definition                │
105           ├──────┼───────────────────────────┤
106           │0     │ Protection information is │
107           │      │ not enabled               │
108           ├──────┼───────────────────────────┤
109           │1     │ Protection information is │
110           │      │ enabled, Type 1           │
111           ├──────┼───────────────────────────┤
112           │2     │ Protection information is │
113           │      │ enabled, Type 2           │
114           ├──────┼───────────────────────────┤
115           │3     │ Protection information is │
116           │      │ enabled, Type 3           │
117           ├──────┼───────────────────────────┤
118           │4–7   │ Reserved                  │
119           └──────┴───────────────────────────┘
120
121       -m <ms>, --ms=<ms>
122           Metadata Settings: This field is set to ‘1’ if the metadata is
123           transferred as part of an extended data LBA. This field is cleared
124           to ‘0’ if the metadata is transferred as part of a separate buffer.
125           The metadata may include protection information, based on the
126           Protection Information (PI) field. Defaults to 0.
127
128       -r, --reset
129           Issue a reset after successful format. Must use the character
130           device for this.
131
132       -t <timeout>, --timeout=<timeout>
133           Override default timeout value. In milliseconds.
134

EXAMPLES

136       ·   Format the device using all defaults:
137
138               # nvme format /dev/nvme0n1
139
140       ·   Format namespace 1 with user data secure erase settings and
141           protection information:
142
143               # nvme format /dev/nvme0 --namespace-id=1 --ses=1 --pi=1
144

NVME

146       Part of the nvme-user suite
147
148
149
150NVMe                              01/08/2019                    NVME-FORMAT(1)
Impressum