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