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