2 .\" Copyright (c) 2020 Warner Losh <imp@FreeBSD.org>
3 .\" Copyright (c) 2018-2019 Alexander Motin <mav@FreeBSD.org>
4 .\" Copyright (c) 2012 Intel Corporation
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions, and the following disclaimer,
12 .\" without modification.
13 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
14 .\" substantially similar to the "NO WARRANTY" disclaimer below
15 .\" ("Disclaimer") and any redistribution must be conditioned upon
16 .\" including a substantially similar Disclaimer requirement for further
17 .\" binary redistribution.
20 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
23 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
28 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
29 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30 .\" POSSIBILITY OF SUCH DAMAGES.
32 .\" nvmecontrol man page.
34 .\" Author: Jim Harris <jimharris@FreeBSD.org>
43 .Nd NVM Express control utility
52 .Aq Ar device-id | Ar namespace-id
55 .Aq Fl n Ar num_threads
56 .Aq Fl o Ar read|write
58 .Aq Fl s Ar size_in_bytes
59 .Aq Fl t Ar time_in_sec
68 .Op Fl v Ar vendor-string
73 .Aq Ar device-id | Ar namespace-id
121 .Aq Ar device-id | Ar namespace-id
152 .Op Fl f Ar path_to_firmware
163 .Aq Ar device-id | Ar namespace-id
178 .Op Fl w workload_hint
181 .Op Fl o path_template
185 .Op Fl o path_template
188 .Ic wdc get-crash-dump
189 .Op Fl o path_template
195 .\" .Ic wdc purge-monitor
206 NVM Express (NVMe) is a storage protocol standard, for SSDs and other
207 high-speed storage devices over PCI Express.
209 The identify commands reports information from the drive's
210 .Dv IDENTIFY_CONTROLLER
215 .Dv IDENTIFY_NAMESPACE
219 When used with disk names, the
220 .Dv IDENTIFY_NAMESPACE
221 data is reported, unless the namespace
223 is overridden with the
226 Then that namespace's data is reported, if it exists.
227 The command accepts the following parameters:
232 to use instead of the namespace associated with the device.
237 is used to retrieve the
238 .Dv IDENTIFY_CONTROLLER
239 data associated with that drive.
242 The logpage command knows how to print log pages of various types.
243 It also knows about vendor specific log pages from hgst/wdc and intel.
244 Note that some vendors use the same log page numbers for different data.
246 .Bl -tag -compact -width "Page 0x00"
254 Changed Namespace List
256 Commands Supported and Effects
258 Reservation Notification
262 Advanced SMART information (WDC/HGST)
264 Read latency stats (Intel)
266 Wite latency stats (Intel)
268 Temperature stats (Intel)
270 Advanced SMART information (Intel)
276 will list all valid vendors and pages.
278 will print the page as hex.
280 will print the binary data for the page.
282 will set Log Specific Field.
284 will set Log Specific Identifier.
286 will set Retain Asynchronous Event.
288 Various namespace management commands.
289 If namespace management is supported by device, allow list, create and delete
290 namespaces, list, attach and detach controllers to namespaces.
292 Reports the namespace id and controller device associated with the
298 Acquire or preempt namespace reservation, using specified parameters:
302 .Bl -tag -compact -width 6n
311 Current reservation key.
313 Preempt reservation key.
316 .Bl -tag -compact -width 6n
322 Write Exclusive - Registrants Only
324 Exclusive Access - Registrants Only
326 Write Exclusive - All Registrants
328 Exclusive Access - All Registrants
332 Register, unregister or replace reservation key, using specified parameters:
335 Current reservation key.
340 .Bl -tag -compact -width 6n
351 Change Persist Through Power Loss State:
352 .Bl -tag -compact -width 6n
354 No change to PTPL state
356 Set PTPL state to ‘0’.
357 Reservations are released and registrants are cleared on a power on.
359 Set PTPL state to ‘1’.
360 Reservations and registrants persist across a power loss.
364 Release or clear reservation, using specified parameters:
367 Current reservation key.
372 .Bl -tag -compact -width 6n
380 Print reservation status, using specified parameters:
383 Print reservation status in hex.
385 Use Extended Data Structure.
388 Format either specified namespace, or all namespaces of specified controller,
389 using specified parameters:
395 Protection Information,
397 Protection Information Location.
398 When formatting specific namespace, existing values are used as defaults.
399 When formatting all namespaces, all parameters should be specified.
400 Some controllers may not support formatting or erasing specific or all
404 enables User Data Erase during format.
407 enables Cryptographic Erase during format.
409 Sanitize NVM subsystem of specified controller,
410 using specified parameters:
412 .It Fl a Ar operation
413 Specify the sanitize operation to perform.
416 Perform an overwrite operation by writing a user supplied
417 data pattern to the device one or more times.
418 The pattern is given by the
421 The number of times is given by the
425 Perform a block erase operation.
426 All the device's blocks are set to a vendor defined
427 value, typically zero.
429 Perform a cryptographic erase operation.
430 The encryption keys are changed to prevent the decryption
433 Exits a previously failed sanitize operation.
434 A failed sanitize operation can only be exited if it was
435 run in the unrestricted completion mode, as provided by the
440 The number of passes when performing an
443 Valid values are between 1 and 16.
446 No Deallocate After Sanitize.
450 operation, the pattern is inverted between consecutive passes.
452 32 bits of pattern to use when performing an
455 The pattern is repeated as needed to fill each block.
457 Perform the sanitize in the unrestricted completion mode.
458 If the operation fails, it can later be exited with the
465 This will report status on a sanitize that is already running on the drive.
468 The various wdc command retrieve log data from the wdc/hgst drives.
471 flag specifies a path template to use to output the files.
472 Each file takes the path template (which defaults to nothing), appends
473 the drive's serial number and the type of dump it is followed
475 These logs must be sent to the vendor for analysis.
476 This tool only provides a way to extract them.
482 commands send NVMe commands to
483 either the administrative or the data part of the device.
484 These commands are expected to be compatible with nvme-cli.
485 Please see the NVMe Standard for details.
487 .It Fl o -opcode Ar opcode
489 .It Fl 2 -cdw2 Ar value
490 32-bit value for CDW2.
491 .It Fl 3 -cdw3 Ar value
492 32-bit value for CDW3.
493 .It Fl 4 -cdw10 Ar value
494 32-bit value for CDW10.
495 .It Fl 5 -cdw11 Ar value
496 32-bit value for CDW11.
497 .It Fl 6 -cdw12 Ar value
498 32-bit value for CDW12.
499 .It Fl 7 -cdw13 Ar value
500 32-bit value for CDW13.
501 .It Fl 8 -cdw14 Ar value
502 32-bit value for CDW14.
503 .It Fl 9 -cdw15 Ar value
504 32-bit value for CDW15.
506 Length of the data for I/O (bytes).
507 .It Fl m -metadata-len
508 Length of the metadata segment for command (bytes).
509 This is ignored and not implemented in
513 .It Fl n -namespace-id
514 Namespace ID for command (Ignored).
516 Value to prefill payload with.
518 Output in binary format (otherwise a hex dump is produced).
520 Do not actually execute the command, but perform sanity checks on it.
522 Command reads data from the device.
523 .It Fl s -show-command
524 Show all the command values on stdout.
526 Command writes data to the device.
528 Send arbitrary commands to the device.
529 Can be used to extract vendor specific logs.
530 Transfers to/from the device possible, but limited to
533 Commands either read data or write it, but not both.
534 Commands needing metadata are not supported by the
540 is required, you can use either the
542 device, or the disk device such as
551 is required, you can use either the
553 device, or the disk device such as
557 For commands that take an optional
559 you can use it to get information on other namespaces, or to query the
565 means query the drive itself.
567 .Dl nvmecontrol devlist
569 Display a list of NVMe controllers and namespaces along with their device nodes.
571 .Dl nvmecontrol identify nvme0
572 .Dl nvmecontrol identify -n 0 nvd0
574 Display a human-readable summary of the nvme0
575 .Dv IDENTIFY_CONTROLLER
577 In this example, nvd0 is connected to nvme0.
579 .Dl nvmecontrol identify -x -v nvme0ns1
580 .Dl nvmecontrol identify -x -v -n 1 nvme0
582 Display an hexadecimal dump of the nvme0
583 .Dv IDENTIFY_NAMESPACE
584 data for namespace 1.
586 .Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1
588 Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds.
589 Each thread will issue a single 512 byte read command.
590 Results are printed to stdout when 30 seconds expires.
592 .Dl nvmecontrol reset nvme0
593 .Dl nvmecontrol reset nda4
595 Perform a controller-level reset of the nvme0 controller.
596 In this example, nda4 is wired to nvme0.
598 .Dl nvmecontrol logpage -p 1 nvme0
600 Display a human-readable summary of the nvme0 controller's Error Information Log.
601 Log pages defined by the NVMe specification include Error Information Log (ID=1),
602 SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3).
604 .Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0
606 Display a human-readable summary of the nvme0's wdc-specific advanced
609 .Dl nvmecontrol logpage -p 1 -x nvme0
611 Display a hexadecimal dump of the nvme0 controller's Error Information Log.
613 .Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin
615 Print the contents of vendor specific page 0xcb as binary data on
617 Redirect it to a temporary file.
619 .Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0
621 Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the
622 nvme0 controller, but do not activate the image.
624 .Dl nvmecontrol firmware -s 4 -a nvme0
626 Activate the firmware in slot 4 of the nvme0 controller on the next reset.
628 .Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0
630 Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the
631 nvme0 controller and activate it on the next reset.
633 .Dl nvmecontrol power -l nvme0
635 List all the current power modes.
637 .Dl nvmecontrol power -p 3 nvme0
639 Set the current power mode.
641 .Dl nvmecontrol power nvme0
643 Get the current power mode.
645 .Dl nvmecontrol identify -n 0 nda0
647 Identify the drive data associated with the
652 devices is used automatically.
654 .Dl nvmecontrol identify nda0
656 Get the namespace parameters associated with the
661 device is used automatically.
666 .Pa /usr/local/lib/nvmecontrol
667 are scanned for any .so files.
668 These files are loaded.
671 linker set are added to the top-level commands.
674 linker set are added to the logpage parsers.
677 .%T The NVM Express Base Specification
679 .%U https://nvmexpress.org/wp-content/uploads/NVM-Express-1_4-2019.06.10-Ratified.pdf
689 was developed by Intel and originally written by
690 .An Jim Harris Aq Mt jimharris@FreeBSD.org .
692 This man page was written by
693 .An Jim Harris Aq Mt jimharris@FreeBSD.org .