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 14, 2022 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 i 133.Op Fl c Ar crkey 134.Aq Fl k Ar nrkey 135.Aq Fl r Ar rrega 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 592.Pp 593Send arbitrary commands to the device. 594Can be used to extract vendor specific logs. 595Transfers to/from the device possible, but limited to 596.Dv MAXPHYS 597bytes. 598Commands either read data or write it, but not both. 599Commands needing metadata are not supported by the 600.Xr nvme 4 601drive. 602.Sh DEVICE NAMES 603Where 604.Aq Ar namespace-id 605is required, you can use either the 606.Pa nvmeXnsY 607device, or the disk device such as 608.Pa ndaZ 609or 610.Pa nvdZ . 611The leading 612.Pa /dev/ 613is omitted. 614Where 615.Aq Ar device-id 616is required, you can use either the 617.Pa nvmeX 618device, or the disk device such as 619.Pa ndaZ 620or 621.Pa nvdZ . 622For commands that take an optional 623.Aq nsid 624you can use it to get information on other namespaces, or to query the 625drive itself. 626A 627.Aq nsid 628of 629.Dq 0 630means query the drive itself. 631.Sh EXAMPLES 632.Dl nvmecontrol devlist 633.Pp 634Display a list of NVMe controllers and namespaces along with their device nodes. 635.Pp 636.Dl nvmecontrol identify nvme0 637.Dl nvmecontrol identify -n 0 nvd0 638.Pp 639Display a human-readable summary of the nvme0 640.Dv IDENTIFY_CONTROLLER 641data. 642In this example, nvd0 is connected to nvme0. 643.Pp 644.Dl nvmecontrol identify -x -v nvme0ns1 645.Dl nvmecontrol identify -x -v -n 1 nvme0 646.Pp 647Display an hexadecimal dump of the nvme0 648.Dv IDENTIFY_NAMESPACE 649data for namespace 1. 650.Pp 651.Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1 652.Pp 653Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds. 654Each thread will issue a single 512 byte read command. 655Results are printed to stdout when 30 seconds expires. 656.Pp 657.Dl nvmecontrol reset nvme0 658.Dl nvmecontrol reset nda4 659.Pp 660Perform a controller-level reset of the nvme0 controller. 661In this example, nda4 is wired to nvme0. 662.Pp 663.Dl nvmecontrol logpage -p 1 nvme0 664.Pp 665Display a human-readable summary of the nvme0 controller's Error Information Log. 666Log pages defined by the NVMe specification include Error Information Log (ID=1), 667SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3). 668.Pp 669.Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0 670.Pp 671Display a human-readable summary of the nvme0's wdc-specific advanced 672SMART data. 673.Pp 674.Dl nvmecontrol logpage -p 1 -x nvme0 675.Pp 676Display a hexadecimal dump of the nvme0 controller's Error Information Log. 677.Pp 678.Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin 679.Pp 680Print the contents of vendor specific page 0xcb as binary data on 681standard out. 682Redirect it to a temporary file. 683.Pp 684.Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0 685.Pp 686Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the 687nvme0 controller, but do not activate the image. 688.Pp 689.Dl nvmecontrol firmware -s 4 -a nvme0 690.Pp 691Activate the firmware in slot 4 of the nvme0 controller on the next reset. 692.Pp 693.Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0 694.Pp 695Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the 696nvme0 controller and activate it on the next reset. 697.Pp 698.Dl nvmecontrol power -l nvme0 699.Pp 700List all the current power modes. 701.Pp 702.Dl nvmecontrol power -p 3 nvme0 703.Pp 704Set the current power mode. 705.Pp 706.Dl nvmecontrol power nvme0 707.Pp 708Get the current power mode. 709.Pp 710.Dl nvmecontrol identify -n 0 nda0 711.Pp 712Identify the drive data associated with the 713.Pa nda0 714device. 715The corresponding 716.Pa nvmeX 717devices is used automatically. 718.Pp 719.Dl nvmecontrol identify nda0 720.Pp 721Get the namespace parameters associated with the 722.Pa nda0 723device. 724The corresponding 725.Pa nvmeXnsY 726device is used automatically. 727.Sh DYNAMIC LOADING 728The directories 729.Pa /lib/nvmecontrol 730and 731.Pa /usr/local/lib/nvmecontrol 732are scanned for any .so files. 733These files are loaded. 734The members of the 735.Va top 736linker set are added to the top-level commands. 737The members of the 738.Va logpage 739linker set are added to the logpage parsers. 740.Sh SEE ALSO 741.Rs 742.%T The NVM Express Base Specification 743.%D June 10, 2019 744.%U https://nvmexpress.org/wp-content/uploads/NVM-Express-1_4-2019.06.10-Ratified.pdf 745.Re 746.Sh HISTORY 747The 748.Nm 749utility appeared in 750.Fx 9.2 . 751.Sh AUTHORS 752.An -nosplit 753.Nm 754was developed by Intel and originally written by 755.An Jim Harris Aq Mt jimharris@FreeBSD.org . 756.Pp 757This man page was written by 758.An Jim Harris Aq Mt jimharris@FreeBSD.org . 759