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
53 .Aq Ar device-id | Ar namespace-id
56 .Aq Fl n Ar num_threads
57 .Aq Fl o Ar read|write
59 .Aq Fl s Ar size_in_bytes
60 .Aq Fl t Ar time_in_sec
69 .Op Fl v Ar vendor-string
74 .Aq Ar device-id | Ar namespace-id
122 .Aq Ar device-id | Ar namespace-id
153 .Op Fl f Ar path_to_firmware
164 .Aq Ar device-id | Ar namespace-id
179 .Op Fl w workload_hint
183 .Aq Ar device-id | Ar namespace-id
186 .Op Fl o path_template
190 .Op Fl o path_template
193 .Ic wdc get-crash-dump
194 .Op Fl o path_template
200 .\" .Ic wdc purge-monitor
211 NVM Express (NVMe) is a storage protocol standard, for SSDs and other
212 high-speed storage devices over PCI Express.
214 List all NVMe controllers and namespaces along with their device nodes.
217 argument, use unit suffixes: Byte, Kibibyte, Mebibyte, Gibibyte, Tebibyte
218 and Pebibyte (based on powers of 1024) when showing the disk space.
219 By default, uses Mebibyte.
221 The identify commands reports information from the drive's
222 .Dv IDENTIFY_CONTROLLER
227 .Dv IDENTIFY_NAMESPACE
231 When used with disk names, the
232 .Dv IDENTIFY_NAMESPACE
233 data is reported, unless the namespace
235 is overridden with the
238 Then that namespace's data is reported, if it exists.
239 The command accepts the following parameters:
244 to use instead of the namespace associated with the device.
249 is used to retrieve the
250 .Dv IDENTIFY_CONTROLLER
251 data associated with that drive.
254 The logpage command knows how to print log pages of various types.
255 It also knows about vendor specific log pages from hgst/wdc, samsung and intel.
256 Note that some vendors use the same log page numbers for different data.
258 .Bl -tag -compact -width "Page 0x00"
266 Changed Namespace List
268 Commands Supported and Effects
272 Reservation Notification
276 Advanced SMART information (WDC/HGST)
278 Read latency stats (Intel)
280 Wite latency stats (Intel)
282 Temperature stats (Intel)
284 Advanced SMART information (Intel)
286 Extended SMART information (Samsung)
292 will list all valid vendors and pages.
294 will print the page as hex.
296 will print the binary data for the page.
298 will set Log Specific Field.
300 will set Log Specific Identifier.
302 will set Retain Asynchronous Event.
304 Various namespace management commands.
305 If namespace management is supported by device, allow list, create and delete
306 namespaces, list, attach and detach controllers to namespaces.
308 Reports the namespace id and controller device associated with the
314 Acquire or preempt namespace reservation, using specified parameters:
318 .Bl -tag -compact -width 6n
327 Current reservation key.
329 Preempt reservation key.
332 .Bl -tag -compact -width 6n
338 Write Exclusive - Registrants Only
340 Exclusive Access - Registrants Only
342 Write Exclusive - All Registrants
344 Exclusive Access - All Registrants
348 Register, unregister or replace reservation key, using specified parameters:
351 Current reservation key.
356 .Bl -tag -compact -width 6n
367 Change Persist Through Power Loss State:
368 .Bl -tag -compact -width 6n
370 No change to PTPL state
372 Set PTPL state to ‘0’.
373 Reservations are released and registrants are cleared on a power on.
375 Set PTPL state to ‘1’.
376 Reservations and registrants persist across a power loss.
380 Release or clear reservation, using specified parameters:
383 Current reservation key.
388 .Bl -tag -compact -width 6n
396 Print reservation status, using specified parameters:
399 Print reservation status in hex.
401 Use Extended Data Structure.
404 Format either specified namespace, or all namespaces of specified controller,
405 using specified parameters:
411 Protection Information,
413 Protection Information Location.
414 When formatting specific namespace, existing values are used as defaults.
415 When formatting all namespaces, all parameters should be specified.
416 Some controllers may not support formatting or erasing specific or all
420 enables User Data Erase during format.
423 enables Cryptographic Erase during format.
425 Sanitize NVM subsystem of specified controller,
426 using specified parameters:
428 .It Fl a Ar operation
429 Specify the sanitize operation to perform.
432 Perform an overwrite operation by writing a user supplied
433 data pattern to the device one or more times.
434 The pattern is given by the
437 The number of times is given by the
441 Perform a block erase operation.
442 All the device's blocks are set to a vendor defined
443 value, typically zero.
445 Perform a cryptographic erase operation.
446 The encryption keys are changed to prevent the decryption
449 Exits a previously failed sanitize operation.
450 A failed sanitize operation can only be exited if it was
451 run in the unrestricted completion mode, as provided by the
456 The number of passes when performing an
459 Valid values are between 1 and 16.
462 No Deallocate After Sanitize.
466 operation, the pattern is inverted between consecutive passes.
468 32 bits of pattern to use when performing an
471 The pattern is repeated as needed to fill each block.
473 Perform the sanitize in the unrestricted completion mode.
474 If the operation fails, it can later be exited with the
481 This will report status on a sanitize that is already running on the drive.
484 Manage the power modes of the NVMe controller.
487 List all supported power modes.
489 Set the power mode to
491 This must be a mode listed with the
492 .Dl nvmecontrol power -l
495 Set the workload hint for automatic power mode control.
496 .Bl -tag -compact -width 6n
498 No workload hint is provided.
500 Extended idle period workload.
501 The device is often idle for minutes at a time.
502 A burst of write commands comes in over a period of seconds.
503 Then the device returns to being idle.
505 Heavy sequential writes.
506 A huge number of sequential writes will be submitted, filling the submission queues.
508 All other values are reserved and have no standard meaning.
511 .Dq NVM Subsystem Workloads
512 section of the relevant NVM Express Base Standard for details.
515 Start the specified device self-test:
518 Specify the device self-test command code.
520 .Bl -tag -compact -width 6n
522 Start a short device self-test operation
524 Start an extended device self-test operation
526 Start a vendor specific device self-test operation
528 Abort the device self-test operation
532 The various wdc command retrieve log data from the wdc/hgst drives.
535 flag specifies a path template to use to output the files.
536 Each file takes the path template (which defaults to nothing), appends
537 the drive's serial number and the type of dump it is followed
539 These logs must be sent to the vendor for analysis.
540 This tool only provides a way to extract them.
546 commands send NVMe commands to
547 either the administrative or the data part of the device.
548 These commands are expected to be compatible with nvme-cli.
549 Please see the NVM Express Base Standard for details.
551 .It Fl o -opcode Ar opcode
553 .It Fl 2 -cdw2 Ar value
554 32-bit value for CDW2.
555 .It Fl 3 -cdw3 Ar value
556 32-bit value for CDW3.
557 .It Fl 4 -cdw10 Ar value
558 32-bit value for CDW10.
559 .It Fl 5 -cdw11 Ar value
560 32-bit value for CDW11.
561 .It Fl 6 -cdw12 Ar value
562 32-bit value for CDW12.
563 .It Fl 7 -cdw13 Ar value
564 32-bit value for CDW13.
565 .It Fl 8 -cdw14 Ar value
566 32-bit value for CDW14.
567 .It Fl 9 -cdw15 Ar value
568 32-bit value for CDW15.
570 Length of the data for I/O (bytes).
571 .It Fl m -metadata-len
572 Length of the metadata segment for command (bytes).
573 This is ignored and not implemented in
577 .It Fl n -namespace-id
578 Namespace ID for command (Ignored).
580 Value to prefill payload with.
582 Output in binary format (otherwise a hex dump is produced).
584 Do not actually execute the command, but perform sanity checks on it.
586 Command reads data from the device.
587 .It Fl s -show-command
588 Show all the command values on stdout.
590 Command writes data to the device.
592 Send arbitrary commands to the device.
593 Can be used to extract vendor specific logs.
594 Transfers to/from the device possible, but limited to
597 Commands either read data or write it, but not both.
598 Commands needing metadata are not supported by the
604 is required, you can use either the
606 device, or the disk device such as
615 is required, you can use either the
617 device, or the disk device such as
621 For commands that take an optional
623 you can use it to get information on other namespaces, or to query the
629 means query the drive itself.
631 .Dl nvmecontrol devlist
633 Display a list of NVMe controllers and namespaces along with their device nodes.
635 .Dl nvmecontrol identify nvme0
636 .Dl nvmecontrol identify -n 0 nvd0
638 Display a human-readable summary of the nvme0
639 .Dv IDENTIFY_CONTROLLER
641 In this example, nvd0 is connected to nvme0.
643 .Dl nvmecontrol identify -x -v nvme0ns1
644 .Dl nvmecontrol identify -x -v -n 1 nvme0
646 Display an hexadecimal dump of the nvme0
647 .Dv IDENTIFY_NAMESPACE
648 data for namespace 1.
650 .Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1
652 Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds.
653 Each thread will issue a single 512 byte read command.
654 Results are printed to stdout when 30 seconds expires.
656 .Dl nvmecontrol reset nvme0
657 .Dl nvmecontrol reset nda4
659 Perform a controller-level reset of the nvme0 controller.
660 In this example, nda4 is wired to nvme0.
662 .Dl nvmecontrol logpage -p 1 nvme0
664 Display a human-readable summary of the nvme0 controller's Error Information Log.
665 Log pages defined by the NVMe specification include Error Information Log (ID=1),
666 SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3).
668 .Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0
670 Display a human-readable summary of the nvme0's wdc-specific advanced
673 .Dl nvmecontrol logpage -p 1 -x nvme0
675 Display a hexadecimal dump of the nvme0 controller's Error Information Log.
677 .Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin
679 Print the contents of vendor specific page 0xcb as binary data on
681 Redirect it to a temporary file.
683 .Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0
685 Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the
686 nvme0 controller, but do not activate the image.
688 .Dl nvmecontrol firmware -s 4 -a nvme0
690 Activate the firmware in slot 4 of the nvme0 controller on the next reset.
692 .Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0
694 Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the
695 nvme0 controller and activate it on the next reset.
697 .Dl nvmecontrol power -l nvme0
699 List all the current power modes.
701 .Dl nvmecontrol power -p 3 nvme0
703 Set the current power mode.
705 .Dl nvmecontrol power nvme0
707 Get the current power mode.
709 .Dl nvmecontrol identify -n 0 nda0
711 Identify the drive data associated with the
716 devices is used automatically.
718 .Dl nvmecontrol identify nda0
720 Get the namespace parameters associated with the
725 device is used automatically.
730 .Pa /usr/local/lib/nvmecontrol
731 are scanned for any .so files.
732 These files are loaded.
735 linker set are added to the top-level commands.
738 linker set are added to the logpage parsers.
741 .%T The NVM Express Base Specification
743 .%U https://nvmexpress.org/wp-content/uploads/NVM-Express-1_4-2019.06.10-Ratified.pdf
753 was developed by Intel and originally written by
754 .An Jim Harris Aq Mt jimharris@FreeBSD.org .
756 This man page was written by
757 .An Jim Harris Aq Mt jimharris@FreeBSD.org .
projects / FreeBSD / FreeBSD.git / blob