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 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.Ss identify 209The identify commands reports information from the drive's 210.Dv IDENTIFY_CONTROLLER 211if a 212.Ar device-id 213is specified. 214It reports 215.Dv IDENTIFY_NAMESPACE 216data if a 217.Ar namespace-id 218is specified. 219When used with disk names, the 220.Dv IDENTIFY_NAMESPACE 221data is reported, unless the namespace 222.Ar nsid 223is overridden with the 224.Fl n 225flag. 226Then that namespace's data is reported, if it exists. 227The command accepts the following parameters: 228.Bl -tag -width 6n 229.It Fl n 230The namespace 231.Aq nsid 232to use instead of the namespace associated with the device. 233A 234.Ar nsid 235of 236.Dq 0 237is used to retrieve the 238.Dv IDENTIFY_CONTROLLER 239data associated with that drive. 240.El 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 the NVMe Standard for details. 486.Bl -tag -width 16n 487.It Fl o -opcode Ar opcode 488Opcode to send. 489.It Fl 2 -cdw2 Ar value 49032-bit value for CDW2. 491.It Fl 3 -cdw3 Ar value 49232-bit value for CDW3. 493.It Fl 4 -cdw10 Ar value 49432-bit value for CDW10. 495.It Fl 5 -cdw11 Ar value 49632-bit value for CDW11. 497.It Fl 6 -cdw12 Ar value 49832-bit value for CDW12. 499.It Fl 7 -cdw13 Ar value 50032-bit value for CDW13. 501.It Fl 8 -cdw14 Ar value 50232-bit value for CDW14. 503.It Fl 9 -cdw15 Ar value 50432-bit value for CDW15. 505.It Fl l -data-len 506Length of the data for I/O (bytes). 507.It Fl m -metadata-len 508Length of the metadata segment for command (bytes). 509This is ignored and not implemented in 510.Xr nvme 4 . 511.It Fl f -flags 512Nvme command flags. 513.It Fl n -namespace-id 514Namespace ID for command (Ignored). 515.It Fl p -prefill 516Value to prefill payload with. 517.It Fl b -raw-binary 518Output in binary format (otherwise a hex dump is produced). 519.It Fl d -dry-run 520Do not actually execute the command, but perform sanity checks on it. 521.It Fl r -read 522Command reads data from the device. 523.It Fl s -show-command 524Show all the command values on stdout. 525.It Fl w -write 526Command writes data to the device. 527.El 528Send arbitrary commands to the device. 529Can be used to extract vendor specific logs. 530Transfers to/from the device possible, but limited to 531.Dv MAXPHYS 532bytes. 533Commands either read data or write it, but not both. 534Commands needing metadata are not supported by the 535.Xr nvme 4 536drive. 537.Sh DEVICE NAMES 538Where 539.Aq Ar namespace-id 540is required, you can use either the 541.Pa nvmeXnsY 542device, or the disk device such as 543.Pa ndaZ 544or 545.Pa nvdZ . 546The leading 547.Pa /dev/ 548is omitted. 549Where 550.Aq Ar device-id 551is required, you can use either the 552.Pa nvmeX 553device, or the disk device such as 554.Pa nda Z 555or 556.Pa nvdZ . 557For commands that take an optional 558.Aq nsid 559you can use it to get information on other namespaces, or to query the 560drive itself. 561A 562.Aq nsid 563of 564.Dq 0 565means query the drive itself. 566.Sh EXAMPLES 567.Dl nvmecontrol devlist 568.Pp 569Display a list of NVMe controllers and namespaces along with their device nodes. 570.Pp 571.Dl nvmecontrol identify nvme0 572.Dl nvmecontrol identify -n 0 nvd0 573.Pp 574Display a human-readable summary of the nvme0 575.Dv IDENTIFY_CONTROLLER 576data. 577In this example, nvd0 is connected to nvme0. 578.Pp 579.Dl nvmecontrol identify -x -v nvme0ns1 580.Dl nvmecontrol identify -x -v -n 1 nvme0 581.Pp 582Display an hexadecimal dump of the nvme0 583.Dv IDENTIFY_NAMESPACE 584data for namespace 1. 585.Pp 586.Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1 587.Pp 588Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds. 589Each thread will issue a single 512 byte read command. 590Results are printed to stdout when 30 seconds expires. 591.Pp 592.Dl nvmecontrol reset nvme0 593.Dl nvmecontrol reset nda4 594.Pp 595Perform a controller-level reset of the nvme0 controller. 596In this example, nda4 is wired to nvme0. 597.Pp 598.Dl nvmecontrol logpage -p 1 nvme0 599.Pp 600Display a human-readable summary of the nvme0 controller's Error Information Log. 601Log pages defined by the NVMe specification include Error Information Log (ID=1), 602SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3). 603.Pp 604.Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0 605.Pp 606Display a human-readable summary of the nvme0's wdc-specific advanced 607SMART data. 608.Pp 609.Dl nvmecontrol logpage -p 1 -x nvme0 610.Pp 611Display a hexadecimal dump of the nvme0 controller's Error Information Log. 612.Pp 613.Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin 614.Pp 615Print the contents of vendor specific page 0xcb as binary data on 616standard out. 617Redirect it to a temporary file. 618.Pp 619.Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0 620.Pp 621Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the 622nvme0 controller, but do not activate the image. 623.Pp 624.Dl nvmecontrol firmware -s 4 -a nvme0 625.Pp 626Activate the firmware in slot 4 of the nvme0 controller on the next reset. 627.Pp 628.Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0 629.Pp 630Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the 631nvme0 controller and activate it on the next reset. 632.Pp 633.Dl nvmecontrol power -l nvme0 634.Pp 635List all the current power modes. 636.Pp 637.Dl nvmecontrol power -p 3 nvme0 638.Pp 639Set the current power mode. 640.Pp 641.Dl nvmecontrol power nvme0 642.Pp 643Get the current power mode. 644.Pp 645.Dl nvmecontrol identify -n 0 nda0 646.Pp 647Identify the drive data associated with the 648.Pa nda0 649device. 650The corresponding 651.Pa nvmeX 652devices is used automatically. 653.Pp 654.Dl nvmecontrol identify nda0 655.Pp 656Get the namespace parameters associated with the 657.Pa nda0 658device. 659The corresponding 660.Pa nvmeXnsY 661device is used automatically. 662.Sh DYNAMIC LOADING 663The directories 664.Pa /lib/nvmecontrol 665and 666.Pa /usr/local/lib/nvmecontrol 667are scanned for any .so files. 668These files are loaded. 669The members of the 670.Va top 671linker set are added to the top-level commands. 672The members of the 673.Va logpage 674linker set are added to the logpage parsers. 675.Sh SEE ALSO 676.Rs 677.%T The NVM Express Base Specification 678.%D June 10, 2019 679.%U https://nvmexpress.org/wp-content/uploads/NVM-Express-1_4-2019.06.10-Ratified.pdf 680.Re 681.Sh HISTORY 682The 683.Nm 684utility appeared in 685.Fx 9.2 . 686.Sh AUTHORS 687.An -nosplit 688.Nm 689was developed by Intel and originally written by 690.An Jim Harris Aq Mt jimharris@FreeBSD.org . 691.Pp 692This man page was written by 693.An Jim Harris Aq Mt jimharris@FreeBSD.org . 694