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.El 576.It Fl c Ar passes 577The number of passes when performing an 578.Sq overwrite 579operation. 580Valid values are between 1 and 16. 581The default is 1. 582.It Fl d 583No Deallocate After Sanitize. 584.It Fl I 585When performing an 586.Sq overwrite 587operation, the pattern is inverted between consecutive passes. 588.It Fl p Ar pattern 58932 bits of pattern to use when performing an 590.Sq overwrite 591operation. 592The pattern is repeated as needed to fill each block. 593.It Fl U 594Perform the sanitize in the unrestricted completion mode. 595If the operation fails, it can later be exited with the 596.Sq exitfailure 597operation. 598.It Fl r 599Run in 600.Dq report only 601mode. 602This will report status on a sanitize that is already running on the drive. 603.El 604.Ss power 605Manage the power modes of the NVMe controller. 606.Bl -tag -width 6n 607.It Fl l 608List all supported power modes. 609.It Fl p Ar mode 610Set the power mode to 611.Ar mode . 612This must be a mode listed with the 613.Dl nvmecontrol power -l 614command. 615.It Fl w Ar hint 616Set the workload hint for automatic power mode control. 617.Bl -tag -compact -width 6n 618.It 0 619No workload hint is provided. 620.It 1 621Extended idle period workload. 622The device is often idle for minutes at a time. 623A burst of write commands comes in over a period of seconds. 624Then the device returns to being idle. 625.It 2 626Heavy sequential writes. 627A huge number of sequential writes will be submitted, filling the submission queues. 628.It Other 629All other values are reserved and have no standard meaning. 630.El 631Please see the 632.Dq NVM Subsystem Workloads 633section of the relevant NVM Express Base Standard for details. 634.El 635.Ss selftest 636Start the specified device self-test: 637.Bl -tag -width 6n 638.It Fl c Ar code 639Specify the device self-test command code. 640Common codes are: 641.Bl -tag -compact -width 6n 642.It Dv 0x1 643Start a short device self-test operation 644.It Dv 0x2 645Start an extended device self-test operation 646.It Dv 0xe 647Start a vendor specific device self-test operation 648.It Dv 0xf 649Abort the device self-test operation 650.El 651.El 652.Ss wdc 653The various wdc command retrieve log data from the wdc/hgst drives. 654The 655.Fl o 656flag specifies a path template to use to output the files. 657Each file takes the path template (which defaults to nothing), appends 658the drive's serial number and the type of dump it is followed 659by .bin. 660These logs must be sent to the vendor for analysis. 661This tool only provides a way to extract them. 662.Ss passthru 663The 664.Dq admin-passthru 665and 666.Dq io-passthru 667commands send NVMe commands to 668either the administrative or the data part of the device. 669These commands are expected to be compatible with nvme-cli. 670Please see the NVM Express Base Standard for details. 671.Bl -tag -width 16n 672.It Fl o -opcode Ar opcode 673Opcode to send. 674.It Fl 2 -cdw2 Ar value 67532-bit value for CDW2. 676.It Fl 3 -cdw3 Ar value 67732-bit value for CDW3. 678.It Fl 4 -cdw10 Ar value 67932-bit value for CDW10. 680.It Fl 5 -cdw11 Ar value 68132-bit value for CDW11. 682.It Fl 6 -cdw12 Ar value 68332-bit value for CDW12. 684.It Fl 7 -cdw13 Ar value 68532-bit value for CDW13. 686.It Fl 8 -cdw14 Ar value 68732-bit value for CDW14. 688.It Fl 9 -cdw15 Ar value 68932-bit value for CDW15. 690.It Fl l -data-len 691Length of the data for I/O (bytes). 692.It Fl m -metadata-len 693Length of the metadata segment for command (bytes). 694This is ignored and not implemented in 695.Xr nvme 4 . 696.It Fl f -flags 697Nvme command flags. 698.It Fl n -namespace-id 699Namespace ID for command (Ignored). 700.It Fl p -prefill 701Value to prefill payload with. 702.It Fl b -raw-binary 703Output in binary format (otherwise a hex dump is produced). 704.It Fl d -dry-run 705Do not actually execute the command, but perform sanity checks on it. 706.It Fl r -read 707Command reads data from the device. 708.It Fl s -show-command 709Show all the command values on stdout. 710.It Fl w -write 711Command writes data to the device. 712.El 713.Pp 714Send arbitrary commands to the device. 715Can be used to extract vendor specific logs. 716Transfers to/from the device possible, but limited to 717.Dv MAXPHYS 718bytes. 719Commands either read data or write it, but not both. 720Commands needing metadata are not supported by the 721.Xr nvme 4 722drive. 723.Ss discover 724List the remote controllers advertised by a remote Discovery Controller: 725.Bl -tag -width 6n 726.It Fl t Ar transport 727Transport to use. 728The default is 729.It Fl q Ar HostNQN 730NVMe Qualified Name to use for this host. 731By default an NQN is auto-generated from the current host's UUID. 732.Ar tcp . 733.It Fl v 734Display the 735.Dv IDENTIFY_CONTROLLER 736data for the Discovery Controller. 737.El 738.Ss connect 739Establish an association with the I/O controller named 740.Ar SubNQN 741at 742.Ar address . 743The address must include a port. 744.Pp 745An admin queue pair and one or more I/O queue pairs are created and handed 746off to the kernel to create a new controller device. 747.Bl -tag -width 6n 748.It Fl c Ar cntl-id 749Remote controller ID to request: 750.Bl -tag 751.It dynamic 752Request a dynamic controller ID for controllers using the dynamic 753controller model. 754This is the default. 755.It static 756Request a dynamic controller ID for controllers using the static 757controller model. 758.It Ar number 759Request a specific controller ID for controllers using the static 760controller model. 761.El 762.It Fl F 763Request submission queue flow control. 764By default submission queue flow control is disabled unless the remote 765controller requires it. 766.It Fl g 767Enable TCP PDU header digests. 768.It Fl G 769Enable TCP PDU data digests. 770.It Fl i Ar queues 771Number of I/O queue pairs to create. 772The default is 1. 773.It Fl k Ar seconds 774Keep Alive timer duration in seconds. 775The default is 120. 776.It Fl t Ar transport 777Transport to use. 778The default is 779.Ar tcp . 780.It Fl q Ar HostNQN 781NVMe Qualified Name to use for this host. 782By default an NQN is auto-generated from the current host's UUID. 783.It Fl Q Ar entries 784Number of entries in each I/O queue. 785By default the maximum queue size reported by the MQES field 786of the remote host's CAP property is used. 787.El 788.Ss connect-all 789Query the Discovery Controller at 790.Ar address 791and establish an association for each advertised I/O controller. 792The 793.Fl t 794flag determines the transport used for the initial association with 795the Discovery Controller and defaults to 796.Ar tcp . 797All other flags are used to control properties of each I/O assocation as 798described above for the 799.Cm connect 800command. 801.Ss disconnect 802Delete the controller device associated with a remote I/O controller 803including any active association and open queues. 804.Ss reconnect 805Reestablish an association for the remote I/O controller associated with 806.Ar device-id 807at 808.Ar address . 809The address must include a port. 810The flags have the same meaning for the new association as described above 811for the 812.Cm connect 813command. 814.Ss telemetry-log 815Extract the telemetry log associated with 816.Ar device-id , 817using the specified parameters: 818.Bl -tag -width 6n 819.It Fl O Ar output-file 820Output file for the data. 821This parameter is mandatory. 822.It Fl d Ar data-area 823The data area is either 1, 2 or 3. 824.El 825.Sh DEVICE NAMES 826Where 827.Aq Ar namespace-id 828is required, you can use either the 829.Pa nvmeXnsY 830device, or the disk device such as 831.Pa ndaZ 832or 833.Pa nvdZ . 834The leading 835.Pa /dev/ 836may be omitted. 837Where 838.Aq Ar device-id 839is required, you can use either the 840.Pa nvmeX 841device, or the disk device such as 842.Pa ndaZ 843or 844.Pa nvdZ . 845For commands that take an optional 846.Aq nsid 847you can use it to get information on other namespaces, or to query the 848drive itself. 849A 850.Aq nsid 851of 852.Dq 0 853means query the drive itself. 854.Sh FABRICS TRANSPORTS 855The following NVM Express over Fabrics transports are supported for 856accessing remote controllers: 857.Bl -tag 858.It tcp 859TCP transport 860.El 861.Sh NETWORK ADDRESSES 862Network addresses for remote controllers can use one of the following formats: 863.Bl -bullet 864.It 865.Bq Ar IPv6 address 866.Ns : Ns Ar port 867.It 868.Ar IPv4 address 869.Ns : Ns Ar port 870.It 871.Ar hostname Ns : Ns Ar port 872.It 873.Bq Ar IPv6 address 874.It 875.Ar IPv6 address 876.It 877.Ar IPv4 address 878.It 879.Ar hostname 880.El 881.Pp 882If a 883.Ar port 884is not provided, a default value is used if possible. 885.Sh EXAMPLES 886.Dl nvmecontrol devlist 887.Pp 888Display a list of NVMe controllers and namespaces along with their device nodes. 889.Pp 890.Dl nvmecontrol identify nvme0 891.Dl nvmecontrol identify -n 0 nvd0 892.Pp 893Display a human-readable summary of the nvme0 894.Dv IDENTIFY_CONTROLLER 895data. 896In this example, nvd0 is connected to nvme0. 897.Pp 898.Dl nvmecontrol identify -x -v nvme0ns1 899.Dl nvmecontrol identify -x -v -n 1 nvme0 900.Pp 901Display an hexadecimal dump of the nvme0 902.Dv IDENTIFY_NAMESPACE 903data for namespace 1. 904.Pp 905.Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1 906.Pp 907Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds. 908Each thread will issue a single 512 byte read command. 909Results are printed to stdout when 30 seconds expires. 910.Pp 911.Dl nvmecontrol reset nvme0 912.Dl nvmecontrol reset nda4 913.Pp 914Perform a controller-level reset of the nvme0 controller. 915In this example, nda4 is wired to nvme0. 916.Pp 917.Dl nvmecontrol logpage -p 1 nvme0 918.Pp 919Display a human-readable summary of the nvme0 controller's Error Information Log. 920Log pages defined by the NVMe specification include Error Information Log (ID=1), 921SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3). 922.Pp 923.Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0 924.Pp 925Display a human-readable summary of the nvme0's wdc-specific advanced 926SMART data. 927.Pp 928.Dl nvmecontrol logpage -p 1 -x nvme0 929.Pp 930Display a hexadecimal dump of the nvme0 controller's Error Information Log. 931.Pp 932.Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin 933.Pp 934Print the contents of vendor specific page 0xcb as binary data on 935standard out. 936Redirect it to a temporary file. 937.Pp 938.Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0 939.Pp 940Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the 941nvme0 controller, but do not activate the image. 942.Pp 943.Dl nvmecontrol firmware -s 4 -a nvme0 944.Pp 945Activate the firmware in slot 4 of the nvme0 controller on the next reset. 946.Pp 947.Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0 948.Pp 949Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the 950nvme0 controller and activate it on the next reset. 951.Pp 952.Dl nvmecontrol power -l nvme0 953.Pp 954List all the current power modes. 955.Pp 956.Dl nvmecontrol power -p 3 nvme0 957.Pp 958Set the current power mode. 959.Pp 960.Dl nvmecontrol power nvme0 961.Pp 962Get the current power mode. 963.Pp 964.Dl nvmecontrol identify -n 0 nda0 965.Pp 966Identify the drive data associated with the 967.Pa nda0 968device. 969The corresponding 970.Pa nvmeX 971devices is used automatically. 972.Pp 973.Dl nvmecontrol identify nda0 974.Pp 975Get the namespace parameters associated with the 976.Pa nda0 977device. 978The corresponding 979.Pa nvmeXnsY 980device is used automatically. 981.Pp 982.Dl nvmecontrol format -f 2 -m 0 -p 0 -l 0 -C nvme2 983.Pp 984Format all the name spaces on nvme2 using parameters from 985.Dq LBA Format #2 986with no metadata or protection data using cryptographic erase. 987If the 988.Dq nvmecontrol identify -n 1 nvme2 989command ended with 990.Pp 991.Bl -verbatim 992LBA Format #00: Data Size: 512 Metadata Size: 0 Performance: Good 993LBA Format #01: Data Size: 512 Metadata Size: 8 Performance: Good 994LBA Format #02: Data Size: 4096 Metadata Size: 0 Performance: Good 995LBA Format #03: Data Size: 4096 Metadata Size: 8 Performance: Good 996LBA Format #04: Data Size: 4096 Metadata Size: 64 Performance: Good 997.El 998.Pp 999then this would give a 4k data format for at least namespace 1, with no 1000metadata. 1001.Pp 1002.Sh DYNAMIC LOADING 1003The directories 1004.Pa /lib/nvmecontrol 1005and 1006.Pa /usr/local/lib/nvmecontrol 1007are scanned for any .so files. 1008These files are loaded. 1009The members of the 1010.Va top 1011linker set are added to the top-level commands. 1012The members of the 1013.Va logpage 1014linker set are added to the logpage parsers. 1015.Sh SEE ALSO 1016.Rs 1017.%T The NVM Express Base Specification 1018.%D June 10, 2019 1019.%U https://nvmexpress.org/wp-content/uploads/NVM-Express-1_4-2019.06.10-Ratified.pdf 1020.Re 1021.Sh HISTORY 1022The 1023.Nm 1024utility appeared in 1025.Fx 9.2 . 1026.Sh AUTHORS 1027.An -nosplit 1028.Nm 1029was developed by Intel and originally written by 1030.An Jim Harris Aq Mt jimharris@FreeBSD.org . 1031.Pp 1032This man page was written by 1033.An Jim Harris Aq Mt jimharris@FreeBSD.org . 1034