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>
41 .Nd NVM Express control utility
51 .Aq Ar device-id | Ar namespace-id
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
72 .Aq Ar device-id | Ar namespace-id
120 .Aq Ar device-id | Ar namespace-id
151 .Op Fl f Ar path_to_firmware
162 .Aq Ar device-id | Ar namespace-id
177 .Op Fl w workload_hint
181 .Aq Ar device-id | Ar namespace-id
184 .Op Fl o path_template
188 .Op Fl o path_template
191 .Ic wdc get-crash-dump
192 .Op Fl o path_template
198 .\" .Ic wdc purge-monitor
209 NVM Express (NVMe) is a storage protocol standard, for SSDs and other
210 high-speed storage devices over PCI Express.
212 List all NVMe controllers and namespaces along with their device nodes.
215 argument, use unit suffixes: Byte, Kibibyte, Mebibyte, Gibibyte, Tebibyte
216 and Pebibyte (based on powers of 1024) when showing the disk space.
217 By default, uses Mebibyte.
219 The identify commands reports information from the drive's
220 .Dv IDENTIFY_CONTROLLER
225 .Dv IDENTIFY_NAMESPACE
229 When used with disk names, the
230 .Dv IDENTIFY_NAMESPACE
231 data is reported, unless the namespace
233 is overridden with the
236 Then that namespace's data is reported, if it exists.
237 The command accepts the following parameters:
242 to use instead of the namespace associated with the device.
247 is used to retrieve the
248 .Dv IDENTIFY_CONTROLLER
249 data associated with that drive.
252 The logpage command knows how to print log pages of various types.
253 It also knows about vendor specific log pages from hgst/wdc, samsung and intel.
254 Note that some vendors use the same log page numbers for different data.
256 .Bl -tag -compact -width "Page 0x00"
264 Changed Namespace List
266 Commands Supported and Effects
270 Reservation Notification
274 Advanced SMART information (WDC/HGST)
276 Read latency stats (Intel)
278 Wite latency stats (Intel)
280 Temperature stats (Intel)
282 Advanced SMART information (Intel)
284 Extended SMART information (Samsung)
290 will list all valid vendors and pages.
292 will print the page as hex.
294 will print the binary data for the page.
296 will set Log Specific Field.
298 will set Log Specific Identifier.
300 will set Retain Asynchronous Event.
302 Various namespace management commands.
303 If namespace management is supported by device, allow list, create and delete
304 namespaces, list, attach and detach controllers to namespaces.
305 Each NVM device consists of one or more NVM subsystems.
306 Each NVM subsystem has one or more NVM ports.
307 Each NVM port is attached to one or more NVM controllers (though typically 1).
308 Each NVM controller is attached to one or more namespaces.
310 After a namespace is created, it is considered
312 All namespaces that have not been created are unallocated.
313 An allocated namespace may be active or inactive.
314 An active namespace is attached to the controller and may be interacted with.
315 A namespace can move from active to inactive when detached.
316 An allocated namespace may be deleted to become unallocated.
317 For more details on the nuances of NVM namespaces, please see section 2
318 .Em Theory of Operation
320 .Em NVM Express Architecture
321 of the latest NVM standard.
323 Provide a list of active namespace identifiers for the givne NVM controller.
325 Provide a list of allocated namespace identifiers for the givne NVM controller.
327 Attach an nsid to a controller.
328 The primary controller is used if one is not specified.
330 Provide a list of controllers attached to a nsid.
331 If only a nvme controller argument is provided, a nsid must also be specified.
333 Provide a list of all controllers in the NVM subsystem.
335 Creates a new namespace.
338 It must be currently inactive.
340 Detach a namespace from a controller.
341 The namespace will become inaccessible, but its contents will remain if it is
345 Print detailed information about the namespace.
347 Reports the namespace id and controller device associated with the
353 Acquire or preempt namespace reservation, using specified parameters:
357 .Bl -tag -compact -width 6n
366 Current reservation key.
368 Preempt reservation key.
371 .Bl -tag -compact -width 6n
377 Write Exclusive - Registrants Only
379 Exclusive Access - Registrants Only
381 Write Exclusive - All Registrants
383 Exclusive Access - All Registrants
387 Register, unregister or replace reservation key, using specified parameters:
390 Current reservation key.
395 .Bl -tag -compact -width 6n
406 Change Persist Through Power Loss State:
407 .Bl -tag -compact -width 6n
409 No change to PTPL state
411 Set PTPL state to ‘0’.
412 Reservations are released and registrants are cleared on a power on.
414 Set PTPL state to ‘1’.
415 Reservations and registrants persist across a power loss.
419 Release or clear reservation, using specified parameters:
422 Current reservation key.
427 .Bl -tag -compact -width 6n
435 Print reservation status, using specified parameters:
438 Print reservation status in hex.
440 Use Extended Data Structure.
443 Format either specified namespace, or all namespaces of specified controller,
444 using specified parameters:
450 Protection Information,
452 Protection Information Location.
453 When formatting specific namespace, existing values are used as defaults.
454 When formatting all namespaces, all parameters should be specified.
455 Some controllers may not support formatting or erasing specific or all
459 enables User Data Erase during format.
462 enables Cryptographic Erase during format.
464 Sanitize NVM subsystem of specified controller,
465 using specified parameters:
467 .It Fl a Ar operation
468 Specify the sanitize operation to perform.
471 Perform an overwrite operation by writing a user supplied
472 data pattern to the device one or more times.
473 The pattern is given by the
476 The number of times is given by the
480 Perform a block erase operation.
481 All the device's blocks are set to a vendor defined
482 value, typically zero.
484 Perform a cryptographic erase operation.
485 The encryption keys are changed to prevent the decryption
488 Exits a previously failed sanitize operation.
489 A failed sanitize operation can only be exited if it was
490 run in the unrestricted completion mode, as provided by the
495 The number of passes when performing an
498 Valid values are between 1 and 16.
501 No Deallocate After Sanitize.
505 operation, the pattern is inverted between consecutive passes.
507 32 bits of pattern to use when performing an
510 The pattern is repeated as needed to fill each block.
512 Perform the sanitize in the unrestricted completion mode.
513 If the operation fails, it can later be exited with the
520 This will report status on a sanitize that is already running on the drive.
523 Manage the power modes of the NVMe controller.
526 List all supported power modes.
528 Set the power mode to
530 This must be a mode listed with the
531 .Dl nvmecontrol power -l
534 Set the workload hint for automatic power mode control.
535 .Bl -tag -compact -width 6n
537 No workload hint is provided.
539 Extended idle period workload.
540 The device is often idle for minutes at a time.
541 A burst of write commands comes in over a period of seconds.
542 Then the device returns to being idle.
544 Heavy sequential writes.
545 A huge number of sequential writes will be submitted, filling the submission queues.
547 All other values are reserved and have no standard meaning.
550 .Dq NVM Subsystem Workloads
551 section of the relevant NVM Express Base Standard for details.
554 Start the specified device self-test:
557 Specify the device self-test command code.
559 .Bl -tag -compact -width 6n
561 Start a short device self-test operation
563 Start an extended device self-test operation
565 Start a vendor specific device self-test operation
567 Abort the device self-test operation
571 The various wdc command retrieve log data from the wdc/hgst drives.
574 flag specifies a path template to use to output the files.
575 Each file takes the path template (which defaults to nothing), appends
576 the drive's serial number and the type of dump it is followed
578 These logs must be sent to the vendor for analysis.
579 This tool only provides a way to extract them.
585 commands send NVMe commands to
586 either the administrative or the data part of the device.
587 These commands are expected to be compatible with nvme-cli.
588 Please see the NVM Express Base Standard for details.
590 .It Fl o -opcode Ar opcode
592 .It Fl 2 -cdw2 Ar value
593 32-bit value for CDW2.
594 .It Fl 3 -cdw3 Ar value
595 32-bit value for CDW3.
596 .It Fl 4 -cdw10 Ar value
597 32-bit value for CDW10.
598 .It Fl 5 -cdw11 Ar value
599 32-bit value for CDW11.
600 .It Fl 6 -cdw12 Ar value
601 32-bit value for CDW12.
602 .It Fl 7 -cdw13 Ar value
603 32-bit value for CDW13.
604 .It Fl 8 -cdw14 Ar value
605 32-bit value for CDW14.
606 .It Fl 9 -cdw15 Ar value
607 32-bit value for CDW15.
609 Length of the data for I/O (bytes).
610 .It Fl m -metadata-len
611 Length of the metadata segment for command (bytes).
612 This is ignored and not implemented in
616 .It Fl n -namespace-id
617 Namespace ID for command (Ignored).
619 Value to prefill payload with.
621 Output in binary format (otherwise a hex dump is produced).
623 Do not actually execute the command, but perform sanity checks on it.
625 Command reads data from the device.
626 .It Fl s -show-command
627 Show all the command values on stdout.
629 Command writes data to the device.
632 Send arbitrary commands to the device.
633 Can be used to extract vendor specific logs.
634 Transfers to/from the device possible, but limited to
637 Commands either read data or write it, but not both.
638 Commands needing metadata are not supported by the
644 is required, you can use either the
646 device, or the disk device such as
655 is required, you can use either the
657 device, or the disk device such as
661 For commands that take an optional
663 you can use it to get information on other namespaces, or to query the
669 means query the drive itself.
671 .Dl nvmecontrol devlist
673 Display a list of NVMe controllers and namespaces along with their device nodes.
675 .Dl nvmecontrol identify nvme0
676 .Dl nvmecontrol identify -n 0 nvd0
678 Display a human-readable summary of the nvme0
679 .Dv IDENTIFY_CONTROLLER
681 In this example, nvd0 is connected to nvme0.
683 .Dl nvmecontrol identify -x -v nvme0ns1
684 .Dl nvmecontrol identify -x -v -n 1 nvme0
686 Display an hexadecimal dump of the nvme0
687 .Dv IDENTIFY_NAMESPACE
688 data for namespace 1.
690 .Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1
692 Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds.
693 Each thread will issue a single 512 byte read command.
694 Results are printed to stdout when 30 seconds expires.
696 .Dl nvmecontrol reset nvme0
697 .Dl nvmecontrol reset nda4
699 Perform a controller-level reset of the nvme0 controller.
700 In this example, nda4 is wired to nvme0.
702 .Dl nvmecontrol logpage -p 1 nvme0
704 Display a human-readable summary of the nvme0 controller's Error Information Log.
705 Log pages defined by the NVMe specification include Error Information Log (ID=1),
706 SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3).
708 .Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0
710 Display a human-readable summary of the nvme0's wdc-specific advanced
713 .Dl nvmecontrol logpage -p 1 -x nvme0
715 Display a hexadecimal dump of the nvme0 controller's Error Information Log.
717 .Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin
719 Print the contents of vendor specific page 0xcb as binary data on
721 Redirect it to a temporary file.
723 .Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0
725 Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the
726 nvme0 controller, but do not activate the image.
728 .Dl nvmecontrol firmware -s 4 -a nvme0
730 Activate the firmware in slot 4 of the nvme0 controller on the next reset.
732 .Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0
734 Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the
735 nvme0 controller and activate it on the next reset.
737 .Dl nvmecontrol power -l nvme0
739 List all the current power modes.
741 .Dl nvmecontrol power -p 3 nvme0
743 Set the current power mode.
745 .Dl nvmecontrol power nvme0
747 Get the current power mode.
749 .Dl nvmecontrol identify -n 0 nda0
751 Identify the drive data associated with the
756 devices is used automatically.
758 .Dl nvmecontrol identify nda0
760 Get the namespace parameters associated with the
765 device is used automatically.
770 .Pa /usr/local/lib/nvmecontrol
771 are scanned for any .so files.
772 These files are loaded.
775 linker set are added to the top-level commands.
778 linker set are added to the logpage parsers.
781 .%T The NVM Express Base Specification
783 .%U https://nvmexpress.org/wp-content/uploads/NVM-Express-1_4-2019.06.10-Ratified.pdf
793 was developed by Intel and originally written by
794 .An Jim Harris Aq Mt jimharris@FreeBSD.org .
796 This man page was written by
797 .An Jim Harris Aq Mt jimharris@FreeBSD.org .
projects / FreeBSD / FreeBSD.git / blob