1.\" 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. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 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. 18.\" 19.\" NO WARRANTY 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. 31.\" 32.\" nvmecontrol man page. 33.\" 34.\" Author: Jim Harris <jimharris@FreeBSD.org> 35.\" 36.\" $FreeBSD$ 37.\" 38.Dd December 19, 2020 39.Dt NVMECONTROL 8 40.Os 41.Sh NAME 42.Nm nvmecontrol 43.Nd NVM Express control utility 44.Sh SYNOPSIS 45.Nm 46.Ic devlist 47.Op Fl h 48.Nm 49.Ic identify 50.Op Fl v 51.Op Fl x 52.Op Fl n Ar nsid 53.Aq Ar device-id | Ar namespace-id 54.Nm 55.Ic perftest 56.Aq Fl n Ar num_threads 57.Aq Fl o Ar read|write 58.Op Fl p 59.Aq Fl s Ar size_in_bytes 60.Aq Fl t Ar time_in_sec 61.Aq Ar namespace-id 62.Nm 63.Ic reset 64.Aq Ar device-id 65.Nm 66.Ic logpage 67.Aq Fl p Ar page_id 68.Op Fl x 69.Op Fl v Ar vendor-string 70.Op Fl b 71.Op Fl f Ar LSP 72.Op Fl i Ar LSI 73.Op Fl r 74.Aq Ar device-id | Ar namespace-id 75.Nm 76.Ic ns active 77.Aq Ar device-id 78.Nm 79.Ic ns allocated 80.Aq Ar device-id 81.Nm 82.Ic ns attach 83.Aq Fl n Ar nsid 84.Aq Fl c Ar cntid 85.Aq Ar device-id 86.Nm 87.Ic ns attached 88.Aq Fl n Ar nsid 89.Aq Ar device-id 90.Nm 91.Ic ns controllers 92.Aq Ar device-id 93.Nm 94.Ic ns create 95.Aq Fl s Ar nsze 96.Op Fl c Ar ncap 97.Op Fl f Ar lbaf 98.Op Fl m Ar mset 99.Op Fl n Ar nmic 100.Op Fl p Ar pi 101.Op Fl l Ar pil 102.Op Fl L Ar flbas 103.Op Fl d Ar dps 104.Aq Ar device-id 105.Nm 106.Ic ns delete 107.Aq Fl n Ar nsid 108.Aq Ar device-id 109.Nm 110.Ic ns detach 111.Aq Fl n Ar nsid 112.Aq Fl c Ar cntid 113.Aq Ar device-id 114.Nm 115.Ic ns identify 116.Op Fl v 117.Op Fl x 118.Aq Fl n Ar nsid 119.Aq Ar device-id 120.Nm 121.Ic nsid 122.Aq Ar device-id | Ar namespace-id 123.Nm 124.Ic resv acquire 125.Aq Fl c Ar crkey 126.Op Fl p Ar prkey 127.Aq Fl t Ar rtype 128.Aq Fl a Ar racqa 129.Aq Ar namespace-id 130.Nm 131.Ic resv register 132.Op Fl c Ar crkey 133.Aq Fl k Ar nrkey 134.Aq Fl r Ar rrega 135.Op Fl i Ar iekey 136.Op Fl p Ar cptpl 137.Aq Ar namespace-id 138.Nm 139.Ic resv release 140.Aq Fl c Ar crkey 141.Aq Fl t Ar rtype 142.Aq Fl a Ar rrela 143.Aq Ar namespace-id 144.Nm 145.Ic resv report 146.Op Fl e 147.Op Fl v 148.Op Fl x 149.Aq Ar namespace-id 150.Nm 151.Ic firmware 152.Op Fl s Ar slot 153.Op Fl f Ar path_to_firmware 154.Op Fl a 155.Aq Ar device-id 156.Nm 157.Ic format 158.Op Fl f Ar fmt 159.Op Fl m Ar mset 160.Op Fl o Ar pi 161.Op Fl l Ar pil 162.Op Fl E 163.Op Fl C 164.Aq Ar device-id | Ar namespace-id 165.Nm 166.Ic sanitize 167.Aq Fl a Ar sanact 168.Op Fl c Ar owpass 169.Op Fl d 170.Op Fl p Ar ovrpat 171.Op Fl r 172.Op Fl I 173.Op Fl U 174.Aq Ar device-id 175.Nm 176.Ic power 177.Op Fl l 178.Op Fl p power_state 179.Op Fl w workload_hint 180.Nm 181.Ic selftest 182.Aq Fl c Ar code 183.Aq Ar device-id | Ar namespace-id 184.Nm 185.Ic wdc cap-diag 186.Op Fl o path_template 187.Aq Ar device-id 188.Nm 189.Ic wdc drive-log 190.Op Fl o path_template 191.Aq Ar device-id 192.Nm 193.Ic wdc get-crash-dump 194.Op Fl o path_template 195.Aq Ar device-id 196.\" .Nm 197.\" .Ic wdc purge 198.\" .Aq device-id 199.\" .Nm 200.\" .Ic wdc purge-monitor 201.\" .Aq device-id 202.Nm 203.Ic admin-passthru 204.Op args 205.Aq Ar device-id 206.Nm 207.Ic io-passthru 208.Op args 209.Aq Ar namespace-id 210.Sh DESCRIPTION 211NVM Express (NVMe) is a storage protocol standard, for SSDs and other 212high-speed storage devices over PCI Express. 213.Ss devlist 214List all NVMe controllers and namespaces along with their device nodes. 215With the 216.Fl h 217argument, use unit suffixes: Byte, Kibibyte, Mebibyte, Gibibyte, Tebibyte 218and Pebibyte (based on powers of 1024) when showing the disk space. 219By default, uses Mebibyte. 220.Ss identify 221The identify commands reports information from the drive's 222.Dv IDENTIFY_CONTROLLER 223if a 224.Ar device-id 225is specified. 226It reports 227.Dv IDENTIFY_NAMESPACE 228data if a 229.Ar namespace-id 230is specified. 231When used with disk names, the 232.Dv IDENTIFY_NAMESPACE 233data is reported, unless the namespace 234.Ar nsid 235is overridden with the 236.Fl n 237flag. 238Then that namespace's data is reported, if it exists. 239The command accepts the following parameters: 240.Bl -tag -width 6n 241.It Fl n 242The namespace 243.Aq nsid 244to use instead of the namespace associated with the device. 245A 246.Ar nsid 247of 248.Dq 0 249is used to retrieve the 250.Dv IDENTIFY_CONTROLLER 251data associated with that drive. 252.El 253.Ss logpage 254The logpage command knows how to print log pages of various types. 255It also knows about vendor specific log pages from hgst/wdc, samsung and intel. 256Note that some vendors use the same log page numbers for different data. 257.Pp 258.Bl -tag -compact -width "Page 0x00" 259.It Dv Page 0x01 260Drive Error Log 261.It Dv Page 0x02 262Health/SMART Data 263.It Dv Page 0x03 264Firmware Information 265.It Dv Page 0x04 266Changed Namespace List 267.It Dv Page 0x05 268Commands Supported and Effects 269.It Dv Page 0x06 270Device Self-test 271.It Dv Page 0x80 272Reservation Notification 273.It Dv Page 0x81 274Sanitize Status 275.It Dv Page 0xc1 276Advanced SMART information (WDC/HGST) 277.It Dv Page 0xc1 278Read latency stats (Intel) 279.It Dv Page 0xc2 280Wite latency stats (Intel) 281.It Dv Page 0xc5 282Temperature stats (Intel) 283.It Dv Page 0xca 284Advanced SMART information (Intel) 285.It Dv Page 0xca 286Extended SMART information (Samsung) 287.El 288.Pp 289Specifying 290.Fl v 291.Ic help 292will list all valid vendors and pages. 293.Fl x 294will print the page as hex. 295.Fl b 296will print the binary data for the page. 297.Fl s 298will set Log Specific Field. 299.Fl i 300will set Log Specific Identifier. 301.Fl r 302will set Retain Asynchronous Event. 303.Ss ns 304Various namespace management commands. 305If namespace management is supported by device, allow list, create and delete 306namespaces, list, attach and detach controllers to namespaces. 307.Ss nsid 308Reports the namespace id and controller device associated with the 309.Aq Ar namespace-id 310or 311.Aq Ar device-id 312argument. 313.Ss resv acquire 314Acquire or preempt namespace reservation, using specified parameters: 315.Bl -tag -width 6n 316.It Fl a 317Acquire action: 318.Bl -tag -compact -width 6n 319.It Dv 0 320Acquire 321.It Dv 1 322Preempt 323.It Dv 2 324Preempt and abort 325.El 326.It Fl c 327Current reservation key. 328.It Fl p 329Preempt reservation key. 330.It Fl t 331Reservation type: 332.Bl -tag -compact -width 6n 333.It Dv 1 334Write Exclusive 335.It Dv 2 336Exclusive Access 337.It Dv 3 338Write Exclusive - Registrants Only 339.It Dv 4 340Exclusive Access - Registrants Only 341.It Dv 5 342Write Exclusive - All Registrants 343.It Dv 6 344Exclusive Access - All Registrants 345.El 346.El 347.Ss resv register 348Register, unregister or replace reservation key, using specified parameters: 349.Bl -tag -width 6n 350.It Fl c 351Current reservation key. 352.It Fl k 353New reservation key. 354.It Fl r 355Register action: 356.Bl -tag -compact -width 6n 357.It Dv 0 358Register 359.It Dv 1 360Unregister 361.It Dv 2 362Replace 363.El 364.It Fl i 365Ignore Existing Key 366.It Fl p 367Change Persist Through Power Loss State: 368.Bl -tag -compact -width 6n 369.It Dv 0 370No change to PTPL state 371.It Dv 2 372Set PTPL state to ‘0’. 373Reservations are released and registrants are cleared on a power on. 374.It Dv 3 375Set PTPL state to ‘1’. 376Reservations and registrants persist across a power loss. 377.El 378.El 379.Ss resv release 380Release or clear reservation, using specified parameters: 381.Bl -tag -width 6n 382.It Fl c 383Current reservation key. 384.It Fl t 385Reservation type. 386.It Fl a 387Release action: 388.Bl -tag -compact -width 6n 389.It Dv 0 390Release 391.It Dv 1 392Clean 393.El 394.El 395.Ss resv report 396Print reservation status, using specified parameters: 397.Bl -tag -width 6n 398.It Fl x 399Print reservation status in hex. 400.It Fl e 401Use Extended Data Structure. 402.El 403.Ss format 404Format either specified namespace, or all namespaces of specified controller, 405using specified parameters: 406.Ar fmt 407LBA Format, 408.Ar mset 409Metadata Settings, 410.Ar pi 411Protection Information, 412.Ar pil 413Protection Information Location. 414When formatting specific namespace, existing values are used as defaults. 415When formatting all namespaces, all parameters should be specified. 416Some controllers may not support formatting or erasing specific or all 417namespaces. 418Option 419.Fl E 420enables User Data Erase during format. 421Option 422.Fl C 423enables Cryptographic Erase during format. 424.Ss sanitize 425Sanitize NVM subsystem of specified controller, 426using specified parameters: 427.Bl -tag -width 6n 428.It Fl a Ar operation 429Specify the sanitize operation to perform. 430.Bl -tag -width 16n 431.It overwrite 432Perform an overwrite operation by writing a user supplied 433data pattern to the device one or more times. 434The pattern is given by the 435.Fl p 436argument. 437The number of times is given by the 438.Fl c 439argument. 440.It block 441Perform a block erase operation. 442All the device's blocks are set to a vendor defined 443value, typically zero. 444.It crypto 445Perform a cryptographic erase operation. 446The encryption keys are changed to prevent the decryption 447of the data. 448.It exitfailure 449Exits a previously failed sanitize operation. 450A failed sanitize operation can only be exited if it was 451run in the unrestricted completion mode, as provided by the 452.Fl U 453argument. 454.El 455.It Fl c Ar passes 456The number of passes when performing an 457.Sq overwrite 458operation. 459Valid values are between 1 and 16. 460The default is 1. 461.It Fl d 462No Deallocate After Sanitize. 463.It Fl I 464When performing an 465.Sq overwrite 466operation, the pattern is inverted between consecutive passes. 467.It Fl p Ar pattern 46832 bits of pattern to use when performing an 469.Sq overwrite 470operation. 471The pattern is repeated as needed to fill each block. 472.It Fl U 473Perform the sanitize in the unrestricted completion mode. 474If the operation fails, it can later be exited with the 475.Sq exitfailure 476operation. 477.It Fl r 478Run in 479.Dq report only 480mode. 481This will report status on a sanitize that is already running on the drive. 482.El 483.Ss power 484Manage the power modes of the NVMe controller. 485.Bl -tag -width 6n 486.It Fl l 487List all supported power modes. 488.It Fl p Ar mode 489Set the power mode to 490.Ar mode . 491This must be a mode listed with the 492.Dl nvmecontrol power -l 493command. 494.It Fl w Ar hint 495Set the workload hint for automatic power mode control. 496.Bl -tag -compact -width 6n 497.It 0 498No workload hint is provided. 499.It 1 500Extended idle period workload. 501The device is often idle for minutes at a time. 502A burst of write commands comes in over a period of seconds. 503Then the device returns to being idle. 504.It 2 505Heavy sequential writes. 506A huge number of sequential writes will be submitted, filling the submission queues. 507.It Other 508All other values are reserved and have no standard meaning. 509.El 510Please see the 511.Dq NVM Subsystem Workloads 512section of the relevant NVM Express Base Standard for details. 513.El 514.Ss selftest 515Start the specified device self-test: 516.Bl -tag -width 6n 517.It Fl c Ar code 518Specify the device self-test command code. 519Common codes are: 520.Bl -tag -compact -width 6n 521.It Dv 0x1 522Start a short device self-test operation 523.It Dv 0x2 524Start an extended device self-test operation 525.It Dv 0xe 526Start a vendor specific device self-test operation 527.It Dv 0xf 528Abort the device self-test operation 529.El 530.El 531.Ss wdc 532The various wdc command retrieve log data from the wdc/hgst drives. 533The 534.Fl o 535flag specifies a path template to use to output the files. 536Each file takes the path template (which defaults to nothing), appends 537the drive's serial number and the type of dump it is followed 538by .bin. 539These logs must be sent to the vendor for analysis. 540This tool only provides a way to extract them. 541.Ss passthru 542The 543.Dq admin-passthru 544and 545.Dq io-passthru 546commands send NVMe commands to 547either the administrative or the data part of the device. 548These commands are expected to be compatible with nvme-cli. 549Please see the NVM Express Base Standard for details. 550.Bl -tag -width 16n 551.It Fl o -opcode Ar opcode 552Opcode to send. 553.It Fl 2 -cdw2 Ar value 55432-bit value for CDW2. 555.It Fl 3 -cdw3 Ar value 55632-bit value for CDW3. 557.It Fl 4 -cdw10 Ar value 55832-bit value for CDW10. 559.It Fl 5 -cdw11 Ar value 56032-bit value for CDW11. 561.It Fl 6 -cdw12 Ar value 56232-bit value for CDW12. 563.It Fl 7 -cdw13 Ar value 56432-bit value for CDW13. 565.It Fl 8 -cdw14 Ar value 56632-bit value for CDW14. 567.It Fl 9 -cdw15 Ar value 56832-bit value for CDW15. 569.It Fl l -data-len 570Length of the data for I/O (bytes). 571.It Fl m -metadata-len 572Length of the metadata segment for command (bytes). 573This is ignored and not implemented in 574.Xr nvme 4 . 575.It Fl f -flags 576Nvme command flags. 577.It Fl n -namespace-id 578Namespace ID for command (Ignored). 579.It Fl p -prefill 580Value to prefill payload with. 581.It Fl b -raw-binary 582Output in binary format (otherwise a hex dump is produced). 583.It Fl d -dry-run 584Do not actually execute the command, but perform sanity checks on it. 585.It Fl r -read 586Command reads data from the device. 587.It Fl s -show-command 588Show all the command values on stdout. 589.It Fl w -write 590Command writes data to the device. 591.El 592Send arbitrary commands to the device. 593Can be used to extract vendor specific logs. 594Transfers to/from the device possible, but limited to 595.Dv MAXPHYS 596bytes. 597Commands either read data or write it, but not both. 598Commands needing metadata are not supported by the 599.Xr nvme 4 600drive. 601.Sh DEVICE NAMES 602Where 603.Aq Ar namespace-id 604is required, you can use either the 605.Pa nvmeXnsY 606device, or the disk device such as 607.Pa ndaZ 608or 609.Pa nvdZ . 610The leading 611.Pa /dev/ 612is omitted. 613Where 614.Aq Ar device-id 615is required, you can use either the 616.Pa nvmeX 617device, or the disk device such as 618.Pa nda Z 619or 620.Pa nvdZ . 621For commands that take an optional 622.Aq nsid 623you can use it to get information on other namespaces, or to query the 624drive itself. 625A 626.Aq nsid 627of 628.Dq 0 629means query the drive itself. 630.Sh EXAMPLES 631.Dl nvmecontrol devlist 632.Pp 633Display a list of NVMe controllers and namespaces along with their device nodes. 634.Pp 635.Dl nvmecontrol identify nvme0 636.Dl nvmecontrol identify -n 0 nvd0 637.Pp 638Display a human-readable summary of the nvme0 639.Dv IDENTIFY_CONTROLLER 640data. 641In this example, nvd0 is connected to nvme0. 642.Pp 643.Dl nvmecontrol identify -x -v nvme0ns1 644.Dl nvmecontrol identify -x -v -n 1 nvme0 645.Pp 646Display an hexadecimal dump of the nvme0 647.Dv IDENTIFY_NAMESPACE 648data for namespace 1. 649.Pp 650.Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1 651.Pp 652Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds. 653Each thread will issue a single 512 byte read command. 654Results are printed to stdout when 30 seconds expires. 655.Pp 656.Dl nvmecontrol reset nvme0 657.Dl nvmecontrol reset nda4 658.Pp 659Perform a controller-level reset of the nvme0 controller. 660In this example, nda4 is wired to nvme0. 661.Pp 662.Dl nvmecontrol logpage -p 1 nvme0 663.Pp 664Display a human-readable summary of the nvme0 controller's Error Information Log. 665Log pages defined by the NVMe specification include Error Information Log (ID=1), 666SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3). 667.Pp 668.Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0 669.Pp 670Display a human-readable summary of the nvme0's wdc-specific advanced 671SMART data. 672.Pp 673.Dl nvmecontrol logpage -p 1 -x nvme0 674.Pp 675Display a hexadecimal dump of the nvme0 controller's Error Information Log. 676.Pp 677.Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin 678.Pp 679Print the contents of vendor specific page 0xcb as binary data on 680standard out. 681Redirect it to a temporary file. 682.Pp 683.Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0 684.Pp 685Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the 686nvme0 controller, but do not activate the image. 687.Pp 688.Dl nvmecontrol firmware -s 4 -a nvme0 689.Pp 690Activate the firmware in slot 4 of the nvme0 controller on the next reset. 691.Pp 692.Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0 693.Pp 694Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the 695nvme0 controller and activate it on the next reset. 696.Pp 697.Dl nvmecontrol power -l nvme0 698.Pp 699List all the current power modes. 700.Pp 701.Dl nvmecontrol power -p 3 nvme0 702.Pp 703Set the current power mode. 704.Pp 705.Dl nvmecontrol power nvme0 706.Pp 707Get the current power mode. 708.Pp 709.Dl nvmecontrol identify -n 0 nda0 710.Pp 711Identify the drive data associated with the 712.Pa nda0 713device. 714The corresponding 715.Pa nvmeX 716devices is used automatically. 717.Pp 718.Dl nvmecontrol identify nda0 719.Pp 720Get the namespace parameters associated with the 721.Pa nda0 722device. 723The corresponding 724.Pa nvmeXnsY 725device is used automatically. 726.Sh DYNAMIC LOADING 727The directories 728.Pa /lib/nvmecontrol 729and 730.Pa /usr/local/lib/nvmecontrol 731are scanned for any .so files. 732These files are loaded. 733The members of the 734.Va top 735linker set are added to the top-level commands. 736The members of the 737.Va logpage 738linker set are added to the logpage parsers. 739.Sh SEE ALSO 740.Rs 741.%T The NVM Express Base Specification 742.%D June 10, 2019 743.%U https://nvmexpress.org/wp-content/uploads/NVM-Express-1_4-2019.06.10-Ratified.pdf 744.Re 745.Sh HISTORY 746The 747.Nm 748utility appeared in 749.Fx 9.2 . 750.Sh AUTHORS 751.An -nosplit 752.Nm 753was developed by Intel and originally written by 754.An Jim Harris Aq Mt jimharris@FreeBSD.org . 755.Pp 756This man page was written by 757.An Jim Harris Aq Mt jimharris@FreeBSD.org . 758