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