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.Dd July 9, 2025 37.Dt NVMECONTROL 8 38.Os 39.Sh NAME 40.Nm nvmecontrol 41.Nd NVM Express control utility 42.Sh SYNOPSIS 43.Nm 44.Ic devlist 45.Op Fl h 46.Nm 47.Ic identify 48.Op Fl v 49.Op Fl x 50.Op Fl n Ar nsid 51.Aq Ar device-id | Ar 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 Ar namespace-id 60.Nm 61.Ic reset 62.Aq Ar device-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 Ar device-id | Ar namespace-id 73.Nm 74.Ic ns active 75.Aq Ar device-id 76.Nm 77.Ic ns allocated 78.Aq Ar device-id 79.Nm 80.Ic ns attach 81.Aq Fl n Ar nsid 82.Aq Fl c Ar cntid 83.Aq Ar device-id 84.Nm 85.Ic ns attached 86.Aq Fl n Ar nsid 87.Aq Ar device-id 88.Nm 89.Ic ns controllers 90.Aq Ar device-id 91.Nm 92.Ic ns create 93.Aq Fl s Ar nsze 94.Op Fl c Ar ncap 95.Op Fl f Ar lbaf 96.Op Fl m Ar mset 97.Op Fl n Ar nmic 98.Op Fl p Ar pi 99.Op Fl l Ar pil 100.Op Fl L Ar flbas 101.Op Fl d Ar dps 102.Aq Ar device-id 103.Nm 104.Ic ns delete 105.Aq Fl n Ar nsid 106.Aq Ar device-id 107.Nm 108.Ic ns detach 109.Aq Fl n Ar nsid 110.Aq Fl c Ar cntid 111.Aq Ar device-id 112.Nm 113.Ic ns identify 114.Op Fl v 115.Op Fl x 116.Aq Fl n Ar nsid 117.Aq Ar device-id 118.Nm 119.Ic nsid 120.Aq Ar device-id | Ar namespace-id 121.Nm 122.Ic resv acquire 123.Aq Fl c Ar crkey 124.Op Fl p Ar prkey 125.Aq Fl t Ar rtype 126.Aq Fl a Ar racqa 127.Aq Ar namespace-id 128.Nm 129.Ic resv register 130.Op Fl i 131.Op Fl c Ar crkey 132.Aq Fl k Ar nrkey 133.Aq Fl r Ar rrega 134.Op Fl p Ar cptpl 135.Aq Ar namespace-id 136.Nm 137.Ic resv release 138.Aq Fl c Ar crkey 139.Aq Fl t Ar rtype 140.Aq Fl a Ar rrela 141.Aq Ar namespace-id 142.Nm 143.Ic resv report 144.Op Fl e 145.Op Fl v 146.Op Fl x 147.Aq Ar namespace-id 148.Nm 149.Ic firmware 150.Op Fl s Ar slot 151.Op Fl f Ar path_to_firmware 152.Op Fl a 153.Aq Ar device-id 154.Nm 155.Ic format 156.Op Fl f Ar fmt 157.Op Fl m Ar mset 158.Op Fl p Ar pi 159.Op Fl l Ar pil 160.Op Fl E 161.Op Fl C 162.Aq Ar device-id | Ar namespace-id 163.Nm 164.Ic sanitize 165.Aq Fl a Ar sanact 166.Op Fl c Ar owpass 167.Op Fl d 168.Op Fl p Ar ovrpat 169.Op Fl r 170.Op Fl I 171.Op Fl U 172.Aq Ar device-id 173.Nm 174.Ic power 175.Op Fl l 176.Op Fl p power_state 177.Op Fl w workload_hint 178.Nm 179.Ic selftest 180.Aq Fl c Ar code 181.Aq Ar device-id | Ar namespace-id 182.Nm 183.Ic wdc cap-diag 184.Op Fl o path_template 185.Aq Ar device-id 186.Nm 187.Ic wdc drive-log 188.Op Fl o path_template 189.Aq Ar device-id 190.Nm 191.Ic wdc get-crash-dump 192.Op Fl o path_template 193.Aq Ar device-id 194.\" .Nm 195.\" .Ic wdc purge 196.\" .Aq device-id 197.\" .Nm 198.\" .Ic wdc purge-monitor 199.\" .Aq device-id 200.Nm 201.Ic admin-passthru 202.Op args 203.Aq Ar device-id 204.Nm 205.Ic io-passthru 206.Op args 207.Aq Ar namespace-id 208.Nm 209.Ic discover 210.Op Fl v 211.Op Fl t Ar transport 212.Op Fl q Ar HostNQN 213.Nm 214.Ic connect 215.Op Fl FGg 216.Op Fl c Ar cntl-id 217.Op Fl i Ar queues 218.Op Fl k Ar seconds 219.Op Fl l Ar seconds 220.Op Fl r Ar seconds 221.Op Fl t Ar transport 222.Op Fl q Ar HostNQN 223.Op Fl Q Ar entries 224.Aq Ar address 225.Aq Ar SubNQN 226.Nm 227.Ic connect-all 228.Op Fl FGg 229.Op Fl i Ar queues 230.Op Fl k Ar seconds 231.Op Fl l Ar seconds 232.Op Fl r Ar seconds 233.Op Fl t Ar transport 234.Op Fl q Ar HostNQN 235.Op Fl Q Ar entries 236.Aq Ar address 237.Nm 238.Ic disconnect 239.Aq Ar device-id | Ar namespace-id | Ar SubNQN 240.Nm 241.Ic reconnect 242.Aq Ar device-id 243.Nm 244.Ic reconnect 245.Op Fl FGg 246.Op Fl i Ar queues 247.Op Fl k Ar seconds 248.Op Fl l Ar seconds 249.Op Fl r Ar seconds 250.Op Fl t Ar transport 251.Op Fl q Ar HostNQN 252.Op Fl Q Ar entries 253.Aq Ar device-id 254.Aq Ar address 255.Nm 256.Ic telemetry-log 257.Fl O Ar output-file 258.Op Fl d Ar data-area 259.Aq Ar device-id 260.Sh DESCRIPTION 261NVM Express (NVMe) is a storage protocol standard for SSDs and other 262high-speed storage devices over PCI Express as well as remote storage 263devices accessed via a network fabric. 264.Ss devlist 265List all NVMe controllers and namespaces along with their device nodes. 266With the 267.Fl h 268argument, use unit suffixes: Byte, Kibibyte, Mebibyte, Gibibyte, Tebibyte 269and Pebibyte (based on powers of 1024) when showing the disk space. 270By default, uses Mebibyte. 271.Ss identify 272The identify commands reports information from the drive's 273.Dv IDENTIFY_CONTROLLER 274if a 275.Ar device-id 276is specified. 277It reports 278.Dv IDENTIFY_NAMESPACE 279data if a 280.Ar namespace-id 281is specified. 282When used with disk names, the 283.Dv IDENTIFY_NAMESPACE 284data is reported, unless the namespace 285.Ar nsid 286is overridden with the 287.Fl n 288flag. 289Then that namespace's data is reported, if it exists. 290The command accepts the following parameters: 291.Bl -tag -width 6n 292.It Fl n 293The namespace 294.Aq nsid 295to use instead of the namespace associated with the device. 296A 297.Ar nsid 298of 299.Dq 0 300is used to retrieve the 301.Dv IDENTIFY_CONTROLLER 302data associated with that drive. 303.El 304.Ss logpage 305The logpage command knows how to print log pages of various types. 306It also knows about vendor specific log pages from HGST/WDC, Samsung, 307Micron and Intel. 308Note that some vendors use the same log page numbers for different data. 309.Pp 310.Bl -tag -compact -width "Page 0x00" 311.It Dv Page 0x01 312Drive Error Log 313.It Dv Page 0x02 314Health/SMART Data 315.It Dv Page 0x03 316Firmware Information 317.It Dv Page 0x04 318Changed Namespace List 319.It Dv Page 0x05 320Commands Supported and Effects 321.It Dv Page 0x06 322Device Self-test 323.It Dv Page 0x80 324Reservation Notification 325.It Dv Page 0x81 326Sanitize Status 327.It Dv Page 0xc1 328Advanced SMART information (WDC/HGST) 329.It Dv Page 0xc1 330Read latency stats (Intel) 331.It Dv Page 0xc2 332Write latency stats (Intel) 333.It Dv Page 0xc5 334Temperature stats (Intel) 335.It Dv Page 0xca 336Advanced SMART information (Intel) 337.It Dv Page 0xca 338Extended SMART information (Samsung) 339.It Dv Page 0xca 340Vendor Unique SMART information (Micron) 341.El 342.Pp 343Specifying 344.Fl v 345.Ic help 346will list all valid vendors and pages. 347.Fl x 348will print the page as hex. 349.Fl b 350will print the binary data for the page. 351.Fl s 352will set Log Specific Field. 353.Fl i 354will set Log Specific Identifier. 355.Fl r 356will set Retain Asynchronous Event. 357.Ss ns 358Various namespace management commands. 359If namespace management is supported by device, allow list, create and delete 360namespaces, list, attach and detach controllers to namespaces. 361Each NVM device consists of one or more NVM subsystems. 362Each NVM subsystem has one or more NVM ports. 363Each NVM port is attached to one or more NVM controllers (though typically 1). 364Each NVM controller is attached to one or more namespaces. 365.Pp 366After a namespace is created, it is considered 367.Dq allocated . 368All namespaces that have not been created are unallocated. 369An allocated namespace may be active or inactive. 370An active namespace is attached to the controller and may be interacted with. 371A namespace can move from active to inactive when detached. 372An allocated namespace may be deleted to become unallocated. 373For more details on the nuances of NVM namespaces, please see section 2 374.Em Theory of Operation 375and section 3 376.Em NVM Express Architecture 377of the latest NVM standard. 378.Ss ns active 379Provide a list of active namespace identifiers for the givne NVM controller. 380.Ss ns allocated 381Provide a list of allocated namespace identifiers for the givne NVM controller. 382.Ss ns attach 383Attach an nsid to a controller. 384The primary controller is used if one is not specified. 385.Ss ns attached 386Provide a list of controllers attached to a nsid. 387If only a nvme controller argument is provided, a nsid must also be specified. 388.Ss ns controllers 389Provide a list of all controllers in the NVM subsystem. 390.Ss ns create 391Creates a new namespace. 392.Ss ns delete 393Delete a namespace. 394It must be currently inactive. 395.Ss ns detach 396Detach a namespace from a controller. 397The namespace will become inaccessible, but its contents will remain if it is 398.Em activated 399again. 400.Ss ns identify 401Print detailed information about the namespace. 402.Ss nsid 403Reports the namespace id and controller device associated with the 404.Aq Ar namespace-id 405or 406.Aq Ar device-id 407argument. 408.Ss resv acquire 409Acquire or preempt namespace reservation, using specified parameters: 410.Bl -tag -width 6n 411.It Fl a 412Acquire action: 413.Bl -tag -compact -width 6n 414.It Dv 0 415Acquire 416.It Dv 1 417Preempt 418.It Dv 2 419Preempt and abort 420.El 421.It Fl c 422Current reservation key. 423.It Fl p 424Preempt reservation key. 425.It Fl t 426Reservation type: 427.Bl -tag -compact -width 6n 428.It Dv 1 429Write Exclusive 430.It Dv 2 431Exclusive Access 432.It Dv 3 433Write Exclusive - Registrants Only 434.It Dv 4 435Exclusive Access - Registrants Only 436.It Dv 5 437Write Exclusive - All Registrants 438.It Dv 6 439Exclusive Access - All Registrants 440.El 441.El 442.Ss resv register 443Register, unregister or replace reservation key, using specified parameters: 444.Bl -tag -width 6n 445.It Fl c 446Current reservation key. 447.It Fl k 448New reservation key. 449.It Fl r 450Register action: 451.Bl -tag -compact -width 6n 452.It Dv 0 453Register 454.It Dv 1 455Unregister 456.It Dv 2 457Replace 458.El 459.It Fl i 460Ignore Existing Key 461.It Fl p 462Change Persist Through Power Loss State: 463.Bl -tag -compact -width 6n 464.It Dv 0 465No change to PTPL state 466.It Dv 2 467Set PTPL state to ‘0’. 468Reservations are released and registrants are cleared on a power on. 469.It Dv 3 470Set PTPL state to ‘1’. 471Reservations and registrants persist across a power loss. 472.El 473.El 474.Ss resv release 475Release or clear reservation, using specified parameters: 476.Bl -tag -width 6n 477.It Fl c 478Current reservation key. 479.It Fl t 480Reservation type. 481.It Fl a 482Release action: 483.Bl -tag -compact -width 6n 484.It Dv 0 485Release 486.It Dv 1 487Clean 488.El 489.El 490.Ss resv report 491Print reservation status, using specified parameters: 492.Bl -tag -width 6n 493.It Fl x 494Print reservation status in hex. 495.It Fl e 496Use Extended Data Structure. 497.El 498.Ss format 499Format either specified namespace, or all namespaces of specified controller, 500using specified parameters: 501.Bl -tag -width 8n 502.It Fl f Ar fmt 503The index 504.Ar fmt 505of the parameters to use. 506LBA Format #, as specified in the identification of the namespace using 507.Dq nvmecontrol identify 508command with a namespace specified maps this index into these parameters. 509.It Fl m Ar mset 510Metadata Setting. 511.Ar mset 512.Bl -tag -compact -width 6n 513.It Dv 0 514do not transfer metadata with LBA information 515.It Dv 1 516Transfer the metadata as part of the extended LBA information. 517.El 518.It Fl p Ar pi 519Protection Information. 520.Bl -tag -compact -width 6n 521.It Dv 0 522Protection Information not enabled. 523.It Dv 1 524Type 1 information protection enabled. 525.It Dv 2 526Type 2 information protection enabled. 527.It Dv 3 528Type 3 information protection enabled. 529.El 530.It Fl l Ar pil 531Protection Information Location. 532.Bl -tag -compact -width 6n 533.It Dv 0 534Transfer the protection metadata as the last N bytes of the transfer. 535.It Dv 1 536Transfer the protection metadata as the first N bytes of the transfer. 537.El 538.It Fl E 539Enables User Data Erase during format. 540All users data is erased and subsequent reads are indeterminate. 541The drive may implement this as a cryptographic erase or it may 542physically erase the underlying media. 543.It Fl C 544Enables Cryptographic Erase during format. 545All user data is erased cryptographically by deleting the encryption key, 546rendering it unintelligible. 547.El 548.Pp 549When formatting specific namespace, existing values are used as defaults. 550When formatting all namespaces, all parameters should be specified. 551Some controllers may not support formatting or erasing specific or all 552namespaces. 553The 554.Xr nvme 4 555driver does not currently support metadata and protection information 556transfers. 557.Ss sanitize 558Sanitize NVM subsystem of specified controller, 559using specified parameters: 560.Bl -tag -width 6n 561.It Fl a Ar operation 562Specify the sanitize operation to perform. 563.Bl -tag -width 16n 564.It overwrite 565Perform an overwrite operation by writing a user supplied 566data pattern to the device one or more times. 567The pattern is given by the 568.Fl p 569argument. 570The number of times is given by the 571.Fl c 572argument. 573.It block 574Perform a block erase operation. 575All the device's blocks are set to a vendor defined 576value, typically zero. 577.It crypto 578Perform a cryptographic erase operation. 579The encryption keys are changed to prevent the decryption 580of the data. 581.It exitfailure 582Exits a previously failed sanitize operation. 583A failed sanitize operation can only be exited if it was 584run in the unrestricted completion mode, as provided by the 585.Fl U 586argument. 587.It 1, 2, 3, 4 588nvme-cli compatible 589.Fl a 590values for 591.Dq exitfailure , 592.Dq block , 593.Dq overwrite , 594and 595.Dq crypto 596respectively. 597.El 598.It Fl c Ar passes 599The number of passes when performing an 600.Sq overwrite 601operation. 602Valid values are between 1 and 16. 603The default is 1. 604.It Fl d 605No Deallocate After Sanitize. 606.It Fl I 607When performing an 608.Sq overwrite 609operation, the pattern is inverted between consecutive passes. 610.It Fl p Ar pattern 61132 bits of pattern to use when performing an 612.Sq overwrite 613operation. 614The pattern is repeated as needed to fill each block. 615.It Fl U 616Perform the sanitize in the unrestricted completion mode. 617If the operation fails, it can later be exited with the 618.Sq exitfailure 619operation. 620.It Fl r 621Run in 622.Dq report only 623mode. 624This will report status on a sanitize that is already running on the drive. 625.El 626.Ss power 627Manage the power modes of the NVMe controller. 628.Bl -tag -width 6n 629.It Fl l 630List all supported power modes. 631.It Fl p Ar mode 632Set the power mode to 633.Ar mode . 634This must be a mode listed with the 635.Dl nvmecontrol power -l 636command. 637.It Fl w Ar hint 638Set the workload hint for automatic power mode control. 639.Bl -tag -compact -width 6n 640.It 0 641No workload hint is provided. 642.It 1 643Extended idle period workload. 644The device is often idle for minutes at a time. 645A burst of write commands comes in over a period of seconds. 646Then the device returns to being idle. 647.It 2 648Heavy sequential writes. 649A huge number of sequential writes will be submitted, filling the submission queues. 650.It Other 651All other values are reserved and have no standard meaning. 652.El 653Please see the 654.Dq NVM Subsystem Workloads 655section of the relevant NVM Express Base Standard for details. 656.El 657.Ss selftest 658Start the specified device self-test: 659.Bl -tag -width 6n 660.It Fl c Ar code 661Specify the device self-test command code. 662Common codes are: 663.Bl -tag -compact -width 6n 664.It Dv 0x1 665Start a short device self-test operation 666.It Dv 0x2 667Start an extended device self-test operation 668.It Dv 0xe 669Start a vendor specific device self-test operation 670.It Dv 0xf 671Abort the device self-test operation 672.El 673.El 674.Ss wdc 675The various wdc command retrieve log data from the wdc/hgst drives. 676The 677.Fl o 678flag specifies a path template to use to output the files. 679Each file takes the path template (which defaults to nothing), appends 680the drive's serial number and the type of dump it is followed 681by .bin. 682These logs must be sent to the vendor for analysis. 683This tool only provides a way to extract them. 684.Ss passthru 685The 686.Dq admin-passthru 687and 688.Dq io-passthru 689commands send NVMe commands to 690either the administrative or the data part of the device. 691These commands are expected to be compatible with nvme-cli. 692Please see the NVM Express Base Standard for details. 693.Bl -tag -width 16n 694.It Fl o -opcode Ar opcode 695Opcode to send. 696.It Fl 2 -cdw2 Ar value 69732-bit value for CDW2. 698.It Fl 3 -cdw3 Ar value 69932-bit value for CDW3. 700.It Fl 4 -cdw10 Ar value 70132-bit value for CDW10. 702.It Fl 5 -cdw11 Ar value 70332-bit value for CDW11. 704.It Fl 6 -cdw12 Ar value 70532-bit value for CDW12. 706.It Fl 7 -cdw13 Ar value 70732-bit value for CDW13. 708.It Fl 8 -cdw14 Ar value 70932-bit value for CDW14. 710.It Fl 9 -cdw15 Ar value 71132-bit value for CDW15. 712.It Fl l -data-len 713Length of the data for I/O (bytes). 714.It Fl m -metadata-len 715Length of the metadata segment for command (bytes). 716This is ignored and not implemented in 717.Xr nvme 4 . 718.It Fl f -flags 719Nvme command flags. 720.It Fl n -namespace-id 721Namespace ID for command (Ignored). 722.It Fl p -prefill 723Value to prefill payload with. 724.It Fl b -raw-binary 725Output in binary format (otherwise a hex dump is produced). 726.It Fl d -dry-run 727Do not actually execute the command, but perform sanity checks on it. 728.It Fl r -read 729Command reads data from the device. 730.It Fl s -show-command 731Show all the command values on stdout. 732.It Fl w -write 733Command writes data to the device. 734.El 735.Pp 736Send arbitrary commands to the device. 737Can be used to extract vendor specific logs. 738Transfers to/from the device possible, but limited to 739.Dv MAXPHYS 740bytes. 741Commands either read data or write it, but not both. 742Commands needing metadata are not supported by the 743.Xr nvme 4 744drive. 745.Ss discover 746List the remote controllers advertised by a remote Discovery Controller: 747.Bl -tag -width 6n 748.It Fl t Ar transport 749Transport to use. 750The default is 751.Ar tcp . 752.It Fl q Ar HostNQN 753NVMe Qualified Name to use for this host. 754By default an NQN is auto-generated from the current host's UUID. 755.It Fl v 756Display the 757.Dv IDENTIFY_CONTROLLER 758data for the Discovery Controller. 759.El 760.Ss connect 761Establish an association with the I/O controller named 762.Ar SubNQN 763at 764.Ar address . 765The address must include a port. 766.Pp 767An admin queue pair and one or more I/O queue pairs are created and handed 768off to the kernel to create a new controller device. 769.Bl -tag -width 6n 770.It Fl c Ar cntl-id 771Remote controller ID to request: 772.Bl -tag 773.It dynamic 774Request a dynamic controller ID for controllers using the dynamic 775controller model. 776This is the default. 777.It static 778Request a dynamic controller ID for controllers using the static 779controller model. 780.It Ar number 781Request a specific controller ID for controllers using the static 782controller model. 783.El 784.It Fl F 785Request submission queue flow control. 786By default submission queue flow control is disabled unless the remote 787controller requires it. 788.It Fl g 789Enable TCP PDU header digests. 790.It Fl G 791Enable TCP PDU data digests. 792.It Fl i Ar queues 793Number of I/O queue pairs to create. 794The default is 1. 795.It Fl k Ar seconds 796Keep Alive timer duration in seconds. 797The default is 120. 798.It Fl l Ar seconds 799Controller Loss timer duration in seconds. 800The default is 600. 801.Pp 802This timer starts when an association is lost with a remote I/O controller 803and is cancelled when a new association is established. 804If the timer expires, the controller device is deleted. 805A setting of zero disables this timer. 806.It Fl r Ar seconds 807Reconnect timer duration in seconds. 808The default is 10. 809.Pp 810When an association is lost with a remote I/O controller, 811the controller device will request reconnection via periodic 812.Xr devctl 4 813notifications until either a new association is established or the controller 814device is deleted. 815This timer sets the interval between each 816.Xr devctl 4 817notification. 818Note that the first notification is triggered immediately after an association 819is lost. 820A setting of zero disables this timer. 821.It Fl t Ar transport 822Transport to use. 823The default is 824.Ar tcp . 825.It Fl q Ar HostNQN 826NVMe Qualified Name to use for this host. 827By default an NQN is auto-generated from the current host's UUID. 828.It Fl Q Ar entries 829Number of entries in each I/O queue. 830By default the maximum queue size reported by the MQES field 831of the remote host's CAP property is used. 832.El 833.Ss connect-all 834Query the Discovery Controller at 835.Ar address 836and establish an association for each advertised I/O controller. 837The 838.Fl t 839flag determines the transport used for the initial association with 840the Discovery Controller and defaults to 841.Ar tcp . 842All other flags are used to control properties of each I/O assocation as 843described above for the 844.Cm connect 845command. 846.Ss disconnect 847Delete the controller device associated with a remote I/O controller 848including any active association and open queues. 849.Ss reconnect 850Reestablish an association for the remote I/O controller associated with 851.Ar device-id . 852If an 853.Ar address 854is not provided, 855the resolved address and settings from the previous association are used 856to establish a new association. 857If an 858.Ar address 859is provided, 860the supplied address and command line flags are used to establish a new 861association. 862In this case, 863the address must include a port and 864the flags have the same meaning for the new association as described above 865for the 866.Cm connect 867command. 868.Ss telemetry-log 869Extract the telemetry log associated with 870.Ar device-id , 871using the specified parameters: 872.Bl -tag -width 6n 873.It Fl O Ar output-file 874Output file for the data. 875This parameter is mandatory. 876.It Fl d Ar data-area 877The data area is either 1, 2 or 3. 878.El 879.Sh DEVICE NAMES 880Where 881.Aq Ar namespace-id 882is required, you can use either the 883.Pa nvmeXnsY 884device, or the disk device such as 885.Pa ndaZ 886or 887.Pa nvdZ . 888The leading 889.Pa /dev/ 890may be omitted. 891Where 892.Aq Ar device-id 893is required, you can use either the 894.Pa nvmeX 895device, or the disk device such as 896.Pa ndaZ 897or 898.Pa nvdZ . 899For commands that take an optional 900.Aq nsid 901you can use it to get information on other namespaces, or to query the 902drive itself. 903A 904.Aq nsid 905of 906.Dq 0 907means query the drive itself. 908.Sh FABRICS TRANSPORTS 909The following NVM Express over Fabrics transports are supported for 910accessing remote controllers: 911.Bl -tag 912.It tcp 913TCP transport 914.El 915.Sh NETWORK ADDRESSES 916Network addresses for remote controllers can use one of the following formats: 917.Bl -bullet 918.It 919.Bq Ar IPv6 address 920.Ns : Ns Ar port 921.It 922.Ar IPv4 address 923.Ns : Ns Ar port 924.It 925.Ar hostname Ns : Ns Ar port 926.It 927.Bq Ar IPv6 address 928.It 929.Ar IPv6 address 930.It 931.Ar IPv4 address 932.It 933.Ar hostname 934.El 935.Pp 936If a 937.Ar port 938is not provided, a default value is used if possible. 939.Sh EXAMPLES 940.Dl nvmecontrol devlist 941.Pp 942Display a list of NVMe controllers and namespaces along with their device nodes. 943.Pp 944.Dl nvmecontrol identify nvme0 945.Dl nvmecontrol identify -n 0 nvd0 946.Pp 947Display a human-readable summary of the nvme0 948.Dv IDENTIFY_CONTROLLER 949data. 950In this example, nvd0 is connected to nvme0. 951.Pp 952.Dl nvmecontrol identify -x -v nvme0ns1 953.Dl nvmecontrol identify -x -v -n 1 nvme0 954.Pp 955Display an hexadecimal dump of the nvme0 956.Dv IDENTIFY_NAMESPACE 957data for namespace 1. 958.Pp 959.Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1 960.Pp 961Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds. 962Each thread will issue a single 512 byte read command. 963Results are printed to stdout when 30 seconds expires. 964.Pp 965.Dl nvmecontrol reset nvme0 966.Dl nvmecontrol reset nda4 967.Pp 968Perform a controller-level reset of the nvme0 controller. 969In this example, nda4 is wired to nvme0. 970.Pp 971.Dl nvmecontrol logpage -p 1 nvme0 972.Pp 973Display a human-readable summary of the nvme0 controller's Error Information Log. 974Log pages defined by the NVMe specification include Error Information Log (ID=1), 975SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3). 976.Pp 977.Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0 978.Pp 979Display a human-readable summary of the nvme0's wdc-specific advanced 980SMART data. 981.Pp 982.Dl nvmecontrol logpage -p 1 -x nvme0 983.Pp 984Display a hexadecimal dump of the nvme0 controller's Error Information Log. 985.Pp 986.Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin 987.Pp 988Print the contents of vendor specific page 0xcb as binary data on 989standard out. 990Redirect it to a temporary file. 991.Pp 992.Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0 993.Pp 994Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the 995nvme0 controller, but do not activate the image. 996.Pp 997.Dl nvmecontrol firmware -s 4 -a nvme0 998.Pp 999Activate the firmware in slot 4 of the nvme0 controller on the next reset. 1000.Pp 1001.Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0 1002.Pp 1003Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the 1004nvme0 controller and activate it on the next reset. 1005.Pp 1006.Dl nvmecontrol power -l nvme0 1007.Pp 1008List all the current power modes. 1009.Pp 1010.Dl nvmecontrol power -p 3 nvme0 1011.Pp 1012Set the current power mode. 1013.Pp 1014.Dl nvmecontrol power nvme0 1015.Pp 1016Get the current power mode. 1017.Pp 1018.Dl nvmecontrol identify -n 0 nda0 1019.Pp 1020Identify the drive data associated with the 1021.Pa nda0 1022device. 1023The corresponding 1024.Pa nvmeX 1025devices is used automatically. 1026.Pp 1027.Dl nvmecontrol identify nda0 1028.Pp 1029Get the namespace parameters associated with the 1030.Pa nda0 1031device. 1032The corresponding 1033.Pa nvmeXnsY 1034device is used automatically. 1035.Pp 1036.Dl nvmecontrol format -f 2 -m 0 -p 0 -l 0 -C nvme2 1037.Pp 1038Format all the name spaces on nvme2 using parameters from 1039.Dq LBA Format #2 1040with no metadata or protection data using cryptographic erase. 1041If the 1042.Dq nvmecontrol identify -n 1 nvme2 1043command ended with 1044.Pp 1045.Bd -literal 1046LBA Format #00: Data Size: 512 Metadata Size: 0 Performance: Good 1047LBA Format #01: Data Size: 512 Metadata Size: 8 Performance: Good 1048LBA Format #02: Data Size: 4096 Metadata Size: 0 Performance: Good 1049LBA Format #03: Data Size: 4096 Metadata Size: 8 Performance: Good 1050LBA Format #04: Data Size: 4096 Metadata Size: 64 Performance: Good 1051.Ed 1052.Pp 1053then this would give a 4k data format for at least namespace 1, with no 1054metadata. 1055.Pp 1056.Sh DYNAMIC LOADING 1057The directories 1058.Pa /lib/nvmecontrol 1059and 1060.Pa /usr/local/lib/nvmecontrol 1061are scanned for any .so files. 1062These files are loaded. 1063The members of the 1064.Va top 1065linker set are added to the top-level commands. 1066The members of the 1067.Va logpage 1068linker set are added to the logpage parsers. 1069.Sh SEE ALSO 1070.Rs 1071.%T The NVM Express Base Specification 1072.%D June 10, 2019 1073.%U https://nvmexpress.org/wp-content/uploads/NVM-Express-1_4-2019.06.10-Ratified.pdf 1074.Re 1075.Sh HISTORY 1076The 1077.Nm 1078utility appeared in 1079.Fx 9.2 . 1080.Sh AUTHORS 1081.An -nosplit 1082.Nm 1083was developed by Intel and originally written by 1084.An Jim Harris Aq Mt jimharris@FreeBSD.org . 1085.Pp 1086This man page was written by 1087.An Jim Harris Aq Mt jimharris@FreeBSD.org . 1088