2 .\" Copyright (c) 2018-2019 Alexander Motin <mav@FreeBSD.org>
3 .\" Copyright (c) 2012 Intel Corporation
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions, and the following disclaimer,
11 .\" without modification.
12 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
13 .\" substantially similar to the "NO WARRANTY" disclaimer below
14 .\" ("Disclaimer") and any redistribution must be conditioned upon
15 .\" including a substantially similar Disclaimer requirement for further
16 .\" binary redistribution.
19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
22 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
27 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
28 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 .\" POSSIBILITY OF SUCH DAMAGES.
31 .\" nvmecontrol man page.
33 .\" Author: Jim Harris <jimharris@FreeBSD.org>
42 .Nd NVM Express control utility
54 .Aq Fl n Ar num_threads
55 .Aq Fl o Ar read|write
57 .Aq Fl s Ar size_in_bytes
58 .Aq Fl t Ar time_in_sec
67 .Op Fl v Ar vendor-string
153 .Op Fl f Ar path_to_firmware
180 .Op Fl w workload_hint
183 .Op Fl o path_template
187 .Op Fl o path_template
190 .Ic wdc get-crash-dump
191 .Op Fl o path_template
197 .\" .Ic wdc purge-monitor
200 NVM Express (NVMe) is a storage protocol standard, for SSDs and other
201 high-speed storage devices over PCI Express.
204 The logpage command knows how to print log pages of various types.
205 It also knows about vendor specific log pages from hgst/wdc and intel.
206 Note that some vendors use the same log page numbers for different data.
208 .Bl -tag -compact -width "Page 0x00"
216 Changed Namespace List
218 Commands Supported and Effects
220 Reservation Notification
224 Advanced SMART information (WDC/HGST)
226 Read latency stats (Intel)
228 Wite latency stats (Intel)
230 Temperature stats (Intel)
232 Advanced SMART information (Intel)
238 will list all valid vendors and pages.
240 will print the page as hex.
242 will print the binary data for the page.
244 will set Log Specific Field.
246 will set Log Specific Identifier.
248 will set Retain Asynchronous Event.
250 Various namespace management commands.
251 If namespace management is supported by device, allow list, create and delete
252 namespaces, list, attach and detach controllers to namespaces.
254 Acquire or preempt namespace reservation, using specified parameters:
258 .Bl -tag -compact -width 6n
267 Current reservation key.
269 Preempt reservation key.
272 .Bl -tag -compact -width 6n
278 Write Exclusive - Registrants Only
280 Exclusive Access - Registrants Only
282 Write Exclusive - All Registrants
284 Exclusive Access - All Registrants
288 Register, unregister or replace reservation key, using specified parameters:
291 Current reservation key.
296 .Bl -tag -compact -width 6n
307 Change Persist Through Power Loss State:
308 .Bl -tag -compact -width 6n
310 No change to PTPL state
312 Set PTPL state to ‘0’.
313 Reservations are released and registrants are cleared on a power on.
315 Set PTPL state to ‘1’.
316 Reservations and registrants persist across a power loss.
320 Release or clear reservation, using specified parameters:
323 Current reservation key.
328 .Bl -tag -compact -width 6n
336 Print reservation status, using specified parameters:
339 Print reservation status in hex.
341 Use Extended Data Structure.
344 Format either specified namespace, or all namespaces of specified controller,
345 using specified parameters:
351 Protection Information,
353 Protection Information Location.
354 When formatting specific namespace, existing values are used as defaults.
355 When formatting all namespaces, all parameters should be specified.
356 Some controllers may not support formatting or erasing specific or all
360 enables User Data Erase during format.
363 enables Cryptographic Erase during format.
365 Sanitize NVM subsystem of specified controller,
366 using specified parameters:
368 .It Fl a Ar operation
369 Specify the sanitize operation to perform.
372 Perform an overwrite operation by writing a user supplied
373 data pattern to the device one or more times.
374 The pattern is given by the
377 The number of times is given by the
381 Perform a block erase operation.
382 All the device's blocks are set to a vendor defined
383 value, typically zero.
385 Perform a cryptographic erase operation.
386 The encryption keys are changed to prevent the decryption
389 Exits a previously failed sanitize operation.
390 A failed sanitize operation can only be exited if it was
391 run in the unrestricted completion mode, as provided by the
396 The number of passes when performing an
399 Valid values are between 1 and 16.
402 No Deallocate After Sanitize.
406 operation, the pattern is inverted between consecutive passes.
408 32 bits of pattern to use when performing an
411 The pattern is repeated as needed to fill each block.
413 Perform the sanitize in the unrestricted completion mode.
414 If the operation fails, it can later be exited with the
421 This will report status on a sanitize that is already running on the drive.
424 The various wdc command retrieve log data from the wdc/hgst drives.
427 flag specifies a path template to use to output the files.
428 Each file takes the path template (which defaults to nothing), appends
429 the drive's serial number and the type of dump it is followed
431 These logs must be sent to the vendor for analysis.
432 This tool only provides a way to extract them.
434 .Dl nvmecontrol devlist
436 Display a list of NVMe controllers and namespaces along with their device nodes.
438 .Dl nvmecontrol identify nvme0
440 Display a human-readable summary of the nvme0 IDENTIFY_CONTROLLER data.
442 .Dl nvmecontrol identify -x -v nvme0ns1
444 Display an hexadecimal dump of the nvme0 IDENTIFY_NAMESPACE data for namespace
447 .Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1
449 Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds.
450 Each thread will issue a single 512 byte read command.
451 Results are printed to stdout when 30 seconds expires.
453 .Dl nvmecontrol reset nvme0
455 Perform a controller-level reset of the nvme0 controller.
457 .Dl nvmecontrol logpage -p 1 nvme0
459 Display a human-readable summary of the nvme0 controller's Error Information Log.
460 Log pages defined by the NVMe specification include Error Information Log (ID=1),
461 SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3).
463 .Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0
465 Display a human-readable summary of the nvme0's wdc-specific advanced
468 .Dl nvmecontrol logpage -p 1 -x nvme0
470 Display a hexadecimal dump of the nvme0 controller's Error Information Log.
472 .Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin
474 Print the contents of vendor specific page 0xcb as binary data on
476 Redirect it to a temporary file.
478 .Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0
480 Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the
481 nvme0 controller, but do not activate the image.
483 .Dl nvmecontrol firmware -s 4 -a nvme0
485 Activate the firmware in slot 4 of the nvme0 controller on the next reset.
487 .Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0
489 Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the
490 nvme0 controller and activate it on the next reset.
492 .Dl nvmecontrol power -l nvme0
494 List all the current power modes.
496 .Dl nvmecontrol power -p 3 nvme0
498 Set the current power mode.
500 .Dl nvmecontrol power nvme0
502 Get the current power mode.
507 .Pa /usr/local/lib/nvmecontrol
508 are scanned for any .so files.
509 These files are loaded.
512 linker set are added to the top-level commands.
515 linker set are added to the logpage parsers.
524 was developed by Intel and originally written by
525 .An Jim Harris Aq Mt jimharris@FreeBSD.org .
527 This man page was written by
528 .An Jim Harris Aq Mt jimharris@FreeBSD.org .