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