1.\" 2.\" Copyright (c) 2018-2019 Alexander Motin <mav@FreeBSD.org> 3.\" Copyright (c) 2012 Intel Corporation 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions, and the following disclaimer, 11.\" without modification. 12.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer 13.\" substantially similar to the "NO WARRANTY" disclaimer below 14.\" ("Disclaimer") and any redistribution must be conditioned upon 15.\" including a substantially similar Disclaimer requirement for further 16.\" binary redistribution. 17.\" 18.\" NO WARRANTY 19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR 22.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 27.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 28.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGES. 30.\" 31.\" nvmecontrol man page. 32.\" 33.\" Author: Jim Harris <jimharris@FreeBSD.org> 34.\" 35.\" $FreeBSD$ 36.\" 37.Dd August 5, 2019 38.Dt NVMECONTROL 8 39.Os 40.Sh NAME 41.Nm nvmecontrol 42.Nd NVM Express control utility 43.Sh SYNOPSIS 44.Nm 45.Ic devlist 46.Nm 47.Ic identify 48.Op Fl v 49.Op Fl x 50.Aq device id 51.Aq namespace id 52.Nm 53.Ic perftest 54.Aq Fl n Ar num_threads 55.Aq Fl o Ar read|write 56.Op Fl p 57.Aq Fl s Ar size_in_bytes 58.Aq Fl t Ar time_in_sec 59.Aq namespace id 60.Nm 61.Ic reset 62.Aq controller id 63.Nm 64.Ic logpage 65.Aq Fl p Ar page_id 66.Op Fl x 67.Op Fl v Ar vendor-string 68.Op Fl b 69.Op Fl f Ar LSP 70.Op Fl i Ar LSI 71.Op Fl r 72.Aq device id 73.Aq namespace id 74.Nm 75.Ic ns active 76.Aq device id 77.Nm 78.Ic ns allocated 79.Aq device id 80.Nm 81.Ic ns attach 82.Aq Fl n Ar nsid 83.Aq Fl c Ar cntid 84.Aq device id 85.Nm 86.Ic ns attached 87.Aq Fl n Ar nsid 88.Aq device id 89.Nm 90.Ic ns controllers 91.Aq 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 device id 104.Nm 105.Ic ns delete 106.Aq Fl n Ar nsid 107.Aq device id 108.Nm 109.Ic ns detach 110.Aq Fl n Ar nsid 111.Aq Fl c Ar cntid 112.Aq device id 113.Nm 114.Ic ns identify 115.Op Fl v 116.Op Fl x 117.Aq Fl n Ar nsid 118.Aq device id 119.Nm 120.Ic nsid 121.Aq device id 122.Aq 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 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 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 namespace id 144.Nm 145.Ic resv report 146.Op Fl e 147.Op Fl v 148.Op Fl x 149.Aq 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 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 device id 165.Aq namespace id 166.Nm 167.Ic sanitize 168.Aq Fl a Ar sanact 169.Op Fl c Ar owpass 170.Op Fl d 171.Op Fl p Ar ovrpat 172.Op Fl r 173.Op Fl I 174.Op Fl U 175.Aq device id 176.Nm 177.Ic power 178.Op Fl l 179.Op Fl p power_state 180.Op Fl w workload_hint 181.Nm 182.Ic wdc cap-diag 183.Op Fl o path_template 184.Aq device id 185.Nm 186.Ic wdc drive-log 187.Op Fl o path_template 188.Aq device id 189.Nm 190.Ic wdc get-crash-dump 191.Op Fl o path_template 192.Aq device id 193.\" .Nm 194.\" .Ic wdc purge 195.\" .Aq device id 196.\" .Nm 197.\" .Ic wdc purge-monitor 198.\" .Aq device id 199.Sh DESCRIPTION 200NVM Express (NVMe) is a storage protocol standard, for SSDs and other 201high-speed storage devices over PCI Express. 202.Pp 203.Ss logpage 204The logpage command knows how to print log pages of various types. 205It also knows about vendor specific log pages from hgst/wdc and intel. 206Note that some vendors use the same log page numbers for different data. 207.Pp 208.Bl -tag -compact -width "Page 0x00" 209.It Dv Page 0x01 210Drive Error Log 211.It Dv Page 0x02 212Health/SMART Data 213.It Dv Page 0x03 214Firmware Information 215.It Dv Page 0x04 216Changed Namespace List 217.It Dv Page 0x05 218Commands Supported and Effects 219.It Dv Page 0x80 220Reservation Notification 221.It Dv Page 0x81 222Sanitize Status 223.It Dv Page 0xc1 224Advanced SMART information (WDC/HGST) 225.It Dv Page 0xc1 226Read latency stats (Intel) 227.It Dv Page 0xc2 228Wite latency stats (Intel) 229.It Dv Page 0xc5 230Temperature stats (Intel) 231.It Dv Page 0xca 232Advanced SMART information (Intel) 233.El 234.Pp 235Specifying 236.Fl v 237.Ic help 238will list all valid vendors and pages. 239.Fl x 240will print the page as hex. 241.Fl b 242will print the binary data for the page. 243.Fl s 244will set Log Specific Field. 245.Fl i 246will set Log Specific Identifier. 247.Fl r 248will set Retain Asynchronous Event. 249.Ss ns 250Various namespace management commands. 251If namespace management is supported by device, allow list, create and delete 252namespaces, list, attach and detach controllers to namespaces. 253.Ss resv acquire 254Acquire or preempt namespace reservation, using specified parameters: 255.Bl -tag -width 6n 256.It Fl a 257Acquire action: 258.Bl -tag -compact -width 6n 259.It Dv 0 260Acquire 261.It Dv 1 262Preempt 263.It Dv 2 264Preempt and abort 265.El 266.It Fl c 267Current reservation key. 268.It Fl p 269Preempt reservation key. 270.It Fl t 271Reservation type: 272.Bl -tag -compact -width 6n 273.It Dv 1 274Write Exclusive 275.It Dv 2 276Exclusive Access 277.It Dv 3 278Write Exclusive - Registrants Only 279.It Dv 4 280Exclusive Access - Registrants Only 281.It Dv 5 282Write Exclusive - All Registrants 283.It Dv 6 284Exclusive Access - All Registrants 285.El 286.El 287.Ss resv register 288Register, unregister or replace reservation key, using specified parameters: 289.Bl -tag -width 6n 290.It Fl c 291Current reservation key. 292.It Fl k 293New reservation key. 294.It Fl r 295Register action: 296.Bl -tag -compact -width 6n 297.It Dv 0 298Register 299.It Dv 1 300Unregister 301.It Dv 2 302Replace 303.El 304.It Fl i 305Ignore Existing Key 306.It Fl p 307Change Persist Through Power Loss State: 308.Bl -tag -compact -width 6n 309.It Dv 0 310No change to PTPL state 311.It Dv 2 312Set PTPL state to ‘0’. 313Reservations are released and registrants are cleared on a power on. 314.It Dv 3 315Set PTPL state to ‘1’. 316Reservations and registrants persist across a power loss. 317.El 318.El 319.Ss resv release 320Release or clear reservation, using specified parameters: 321.Bl -tag -width 6n 322.It Fl c 323Current reservation key. 324.It Fl t 325Reservation type. 326.It Fl a 327Release action: 328.Bl -tag -compact -width 6n 329.It Dv 0 330Release 331.It Dv 1 332Clean 333.El 334.El 335.Ss resv report 336Print reservation status, using specified parameters: 337.Bl -tag -width 6n 338.It Fl x 339Print reservation status in hex. 340.It Fl e 341Use Extended Data Structure. 342.El 343.Ss format 344Format either specified namespace, or all namespaces of specified controller, 345using specified parameters: 346.Ar fmt 347LBA Format, 348.Ar mset 349Metadata Settings, 350.Ar pi 351Protection Information, 352.Ar pil 353Protection Information Location. 354When formatting specific namespace, existing values are used as defaults. 355When formatting all namespaces, all parameters should be specified. 356Some controllers may not support formatting or erasing specific or all 357namespaces. 358Option 359.Fl E 360enables User Data Erase during format. 361Option 362.Fl C 363enables Cryptographic Erase during format. 364.Ss sanitize 365Sanitize NVM subsystem of specified controller, 366using specified parameters: 367.Bl -tag -width 6n 368.It Fl a Ar operation 369Specify the sanitize operation to perform. 370.Bl -tag -width 16n 371.It overwrite 372Perform an overwrite operation by writing a user supplied 373data pattern to the device one or more times. 374The pattern is given by the 375.Fl p 376argument. 377The number of times is given by the 378.Fl c 379argument. 380.It block 381Perform a block erase operation. 382All the device's blocks are set to a vendor defined 383value, typically zero. 384.It crypto 385Perform a cryptographic erase operation. 386The encryption keys are changed to prevent the decryption 387of the data. 388.It exitfailure 389Exits a previously failed sanitize operation. 390A failed sanitize operation can only be exited if it was 391run in the unrestricted completion mode, as provided by the 392.Fl U 393argument. 394.El 395.It Fl c Ar passes 396The number of passes when performing an 397.Sq overwrite 398operation. 399Valid values are between 1 and 16. 400The default is 1. 401.It Fl d 402No Deallocate After Sanitize. 403.It Fl I 404When performing an 405.Sq overwrite 406operation, the pattern is inverted between consecutive passes. 407.It Fl p Ar pattern 40832 bits of pattern to use when performing an 409.Sq overwrite 410operation. 411The pattern is repeated as needed to fill each block. 412.It Fl U 413Perform the sanitize in the unrestricted completion mode. 414If the operation fails, it can later be exited with the 415.Sq exitfailure 416operation. 417.It Fl r 418Run in 419.Dq report only 420mode. 421This will report status on a sanitize that is already running on the drive. 422.El 423.Ss wdc 424The various wdc command retrieve log data from the wdc/hgst drives. 425The 426.Fl o 427flag specifies a path template to use to output the files. 428Each file takes the path template (which defaults to nothing), appends 429the drive's serial number and the type of dump it is followed 430by .bin. 431These logs must be sent to the vendor for analysis. 432This tool only provides a way to extract them. 433.Sh EXAMPLES 434.Dl nvmecontrol devlist 435.Pp 436Display a list of NVMe controllers and namespaces along with their device nodes. 437.Pp 438.Dl nvmecontrol identify nvme0 439.Pp 440Display a human-readable summary of the nvme0 IDENTIFY_CONTROLLER data. 441.Pp 442.Dl nvmecontrol identify -x -v nvme0ns1 443.Pp 444Display an hexadecimal dump of the nvme0 IDENTIFY_NAMESPACE data for namespace 4451. 446.Pp 447.Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1 448.Pp 449Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds. 450Each thread will issue a single 512 byte read command. 451Results are printed to stdout when 30 seconds expires. 452.Pp 453.Dl nvmecontrol reset nvme0 454.Pp 455Perform a controller-level reset of the nvme0 controller. 456.Pp 457.Dl nvmecontrol logpage -p 1 nvme0 458.Pp 459Display a human-readable summary of the nvme0 controller's Error Information Log. 460Log pages defined by the NVMe specification include Error Information Log (ID=1), 461SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3). 462.Pp 463.Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0 464.Pp 465Display a human-readable summary of the nvme0's wdc-specific advanced 466SMART data. 467.Pp 468.Dl nvmecontrol logpage -p 1 -x nvme0 469.Pp 470Display a hexadecimal dump of the nvme0 controller's Error Information Log. 471.Pp 472.Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin 473.Pp 474Print the contents of vendor specific page 0xcb as binary data on 475standard out. 476Redirect it to a temporary file. 477.Pp 478.Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0 479.Pp 480Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the 481nvme0 controller, but do not activate the image. 482.Pp 483.Dl nvmecontrol firmware -s 4 -a nvme0 484.Pp 485Activate the firmware in slot 4 of the nvme0 controller on the next reset. 486.Pp 487.Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0 488.Pp 489Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the 490nvme0 controller and activate it on the next reset. 491.Pp 492.Dl nvmecontrol power -l nvme0 493.Pp 494List all the current power modes. 495.Pp 496.Dl nvmecontrol power -p 3 nvme0 497.Pp 498Set the current power mode. 499.Pp 500.Dl nvmecontrol power nvme0 501.Pp 502Get the current power mode. 503.Sh DYNAMIC LOADING 504The directories 505.Pa /lib/nvmecontrol 506and 507.Pa /usr/local/lib/nvmecontrol 508are scanned for any .so files. 509These files are loaded. 510The members of the 511.Va top 512linker set are added to the top-level commands. 513The members of the 514.Va logpage 515linker set are added to the logpage parsers. 516.Sh HISTORY 517The 518.Nm 519utility appeared in 520.Fx 9.2 . 521.Sh AUTHORS 522.An -nosplit 523.Nm 524was developed by Intel and originally written by 525.An Jim Harris Aq Mt jimharris@FreeBSD.org . 526.Pp 527This man page was written by 528.An Jim Harris Aq Mt jimharris@FreeBSD.org . 529