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