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