1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2024 Oxide Computer Company 13.\" Copyright 2022 Tintri by DDN, Inc. All rights reserved. 14.\" 15.Dd September 21, 2024 16.Dt NVMEADM 8 17.Os 18.Sh NAME 19.Nm nvmeadm 20.Nd NVMe administration utility 21.Sh SYNOPSIS 22.Nm 23.Fl h 24.Op Ar command 25.Nm 26.Op Fl dv 27.Cm list 28.Oo 29.Fl c 30.Oc 31.Oo 32.Fl p o Ar field Ns [,...] 33.Oc 34.Op Ar ctl[/ns] Ns [,...] 35.Nm 36.Op Fl dv 37.Cm identify 38.Op Fl C | c | d | Oo Fl a Oc Fl n 39.Ar ctl[/ns] Ns [,...] 40.Nm 41.Op Fl dv 42.Cm identify-controller 43.Op Fl C | c | Oo Fl a Oc Fl n 44.Ar ctl Ns [,...] 45.Nm 46.Op Fl dv 47.Cm identify-namespace 48.Op Fl c | d 49.Ar ctl/ns Ns [,...] 50.Nm 51.Op Fl dv 52.Cm list-logpages 53.Op Fl a 54.Op Fl H 55.Op Fl o Ar field Ns [,...] Op Fl p 56.Op Fl s Ar scope Ns [,...] 57.Ar ctl[/ns] Ns [,...] 58.Op Ar logpage... 59.Nm 60.Op Fl dv 61.Cm get-logpage 62.Op Fl O Ar output-file 63.Ar ctl[/ns] Ns [,...] 64.Ar logpage 65.Nm 66.Op Fl dv 67.Cm list-features 68.Op Fl a 69.Op Fl H 70.Op Fl o Ar field Ns [,...] Op Fl p 71.Ar ctl[/ns] Ns [,...] 72.Op Ar feature... 73.Nm 74.Op Fl dv 75.Cm get-features 76.Ar ctl[/ns] Ns [,...] 77.Op Ar feature-list 78.Nm 79.Op Fl dv 80.Cm format 81.Ar ctl[/ns] 82.Op Ar lba-format 83.Nm 84.Op Fl dv 85.Cm secure-erase 86.Op Fl c 87.Ar ctl[/ns] 88.Nm 89.Op Fl dv 90.Cm detach 91.Ar ctl[/ns] 92.Nm 93.Op Fl dv 94.Cm attach 95.Ar ctl[/ns] 96.Nm 97.Op Fl dv 98.Cm list-firmware 99.Ar ctl 100.Nm 101.Op Fl dv 102.Cm load-firmware 103.Ar ctl 104.Ar firmware-file 105.Op Ar offset 106.Nm 107.Op Fl dv 108.Cm commit-firmware 109.Ar ctl 110.Ar slot 111.Nm 112.Op Fl dv 113.Cm activate-firmware 114.Ar ctl 115.Ar slot 116.Nm 117.Op Fl dv 118.Cm wdc/e6dump 119.Fl o Ar output 120.Ar ctl 121.Nm 122.Op Fl dv 123.Cm wdc/resize 124.Fl s Ar size | Fl g 125.Ar ctl 126.Nm 127.Op Fl dv 128.Cm wdc/clear-assert 129.Ar ctl 130.Nm 131.Op Fl dv 132.Cm wdc/inject-assert 133.Ar ctl 134.Sh DESCRIPTION 135The 136.Nm 137utility can be used to enumerate the NVMe controllers and their 138namespaces, query hardware information from a NVMe controller or 139namespace, and to format or secure-erase a NVMe controller or 140namespace. 141.Pp 142The information returned by the hardware is printed by 143.Nm 144in a human-readable form were applicable. 145Generally all 0-based counts are normalized and values may be 146converted to human-readable units such as MB (megabytes), W (watts), 147or C (degrees Celsius). 148.Sh OPTIONS 149The following options are supported: 150.Bl -tag -width Ds 151.It Fl h 152Print a short help text for 153.Nm , 154or for an optionally specified 155.Nm 156command. 157.It Fl d 158Enable debugging output. 159.It Fl v 160Enable verbose output. 161.El 162.Sh ARGUMENTS 163.Nm 164expects the following kinds of arguments: 165.Bl -tag -width "ctl[/ns]" 166.It Ar command 167Any command 168.Nm 169understands. 170See section 171.Sx COMMANDS . 172.It Ar ctl[/ns] 173Specifies a NVMe controller and optionally a namespace within that 174controller. 175The controller name consists of the driver name 176.Qq nvme 177followed by an instance number. 178A namespace is specified by appending a single 179.Qq / 180to the controller name, followed by either the namespace ID or the namespace 181EUI64 or NGUID as reported by the 182.Cm identify 183command. 184The namespace ID is a positive non-zero decimal number. 185For commands that don't change the device state multiple controllers 186and namespaces can be specified as a comma-separated list. 187.Pp 188The list of controllers and namespaces present in the system can be 189queried with the 190.Cm list 191command without any arguments. 192.It Ar logpage 193Specifies the log page name for the 194.Cm get-logpage 195command. 196.It Ar feature-list 197A comma-separated list of feature names for the 198.Cm get-features 199command. 200Feature names can be specified in upper or lower case. 201All features can be specified either by a short name listed below or by 202the full name that the specification uses. 203.It Ar lba-format 204A non-zero integer specifying the LBA format for the 205.Cm format 206command. 207The list of supported LBA formats on a namespace can be retrieved 208with the 209.Nm 210.Cm identify 211command. 212.It Ar firmware-file 213Specifies the name of a firmware file to be loaded into the controller 214using the 215.Cm load-firmware 216command. 217.It Ar offset 218Specifies the byte offset at which to load 219.It Ar output-file 220Specifies a file system location to write raw binary data out to. 221.Ar firmware-file 222within the controller's upload buffer. 223Vendors may require multiple images to be loaded at different offsets 224before a firmware set is committed to a 225.Ar slot . 226.It Ar scope 227Specifies the scope of a given type of thing to look at, such as a log 228page. 229Scopes can either be specified by their full name or a shortened form. 230For log pages, the following scopes are supported: 231.Bl -tag -width Ds 232.It Sy controller 233Indicates that the log is scoped to the controller. 234The short form is 235.Dq ctrl . 236.It Sy nvm 237Indicates that the log is scoped to the NVM subsystem. 238There is no short form. 239.It Sy namespace 240Indicates that the log is scoped to the namespace. 241The short form is 242.Dq ns . 243.El 244.Pp 245For more information on the differences between these, please see the 246NVMe specification. 247.It Ar slot 248Specifies the firmware slot into which a firmware set is committed 249using the 250.Cm commit-firmware 251command, and subsequently activated with the 252.Cm activate-firmware 253command. 254Slots and their contents can be printed using the 255.Nm 256.Cm list-firmware 257command. 258.El 259.Sh COMMANDS 260.Bl -tag -width "" 261.It Xo 262.Nm 263.Cm list 264.Oo 265.Fl c 266.Oc 267.Oo 268.Fl p o Ar field Ns [,...] 269.Oc 270.Op Ar ctl[/ns] Ns [,...] 271.Xc 272Lists the NVMe controllers and by default also their active 273namespaces, printing a 1-line summary of their basic properties for each. 274If a list of controllers and/or namespaces is given then the listing 275is limited to those devices. 276If no controllers or namespaces are given as arguments, then all controllers 277in the system and their respective active namespaces are listed. 278When using the 279.Fl v 280option 281to 282.Nm , 283all possible namespaces of the controllers will be listed. 284.Pp 285The 286.Nm 287.Cm list 288command supports the following options: 289.Bl -tag -width Fl 290.It Fl c 291List controllers only and not their namespaces. 292.It Fl p 293Produce parsable output rather than human-readable output. 294This option requires that output fields be selected with the 295.Fl o 296option. 297.It Fl o Ar field Ns [,...] 298A comma-separated list of one or more output fields to be used. 299Fields are listed below and the name is case insensitive. 300.El 301.Pp 302The following fields can be specified when using the parsable form: 303.Bl -tag -width UNALLOCATED 304.It Sy MODEL 305The model number of the device, generally containing information about 306both the manufacturer and the product. 307.It Sy SERIAL 308The NVMe controller's serial number. 309.It Sy FWREV 310The controller's firmware revision. 311.It Sy VERSION 312The version of the NVMe specification the controller supports. 313.It Sy INSTANCE 314The name of the device node and instance of it. 315.El 316.Pp 317In addition, the following fields can be specified when listing namespaces, not 318using the 319.Fl c 320option: 321.Bl -tag -width UNALLOCATED 322.It Sy CAPACITY 323The amount of logical bytes that the namespace may actually have allocated at 324any time. 325This may be different than size due to the use of thin provisioning or due to 326administrative action. 327.It Sy SIZE 328The logical size in bytes of the namespace. 329.It Sy USED 330The number of bytes used in the namespace. 331.It Sy NAMESPACE 332The numerical value of the namespace which can be used as part of other 333.Nm 334operations. 335.It Sy DISK 336The name of the disk device that corresponds to the namespace, if any. 337.El 338.Pp 339When using the 340.Fl c 341option to list controllers, the following additional fields are supported: 342.Bl -tag -width UNALLOCATED 343.It Sy CAPACITY 344The total raw capacity of the NVMe controller in bytes. 345.It Sy UNALLOCATED 346The number of bytes not currently assigned to any namespace in the controller. 347.El 348.It Xo 349.Nm 350.Cm identify-controller 351.Op Fl C | c | Oo Fl a Oc Fl n 352.Ar ctl Ns [,...] 353.Xc 354Print detailed information about the specified controllers. 355For an explanation of the data printed by this command refer to the description 356of the 357.Qq IDENTIFY 358admin command in the NVMe specification. 359.Pp 360By default, a relevant subset of the 361.Qq IDENTIFY CONTROLLER 362data structure is printed. 363The full data structure is only printed when verbose output is requested. 364.Pp 365The following options can be used to print other 366.Qq IDENTIFY 367information: 368.Bl -tag -width Fl 369.It Fl C 370Print the Common Namespace Identification of the controller. 371.It Fl a 372Alter the output of the 373.Fl n 374option to print the list allocated namespace identifiers. 375Can only be specified together with the 376.Fl n 377option. 378.It Fl c 379Print the list of all unique controller identifiers in the NVMe subsystem the 380specified controller belongs to. 381.It Fl n 382Print the list of active namespace identifiers of the controller. 383.El 384.It Xo 385.Nm 386.Cm identify-namespace 387.Op Fl c | d 388.Ar ctl/ns Ns [,...] 389.Xc 390Print detailed information about the specified namespace. 391For an explanation of the data printed by this command refer to the description 392of the 393.Qq IDENTIFY 394admin command in the NVMe specification. 395.Pp 396By default, a relevant subset of the 397.Qq IDENTIFY NAMESPACE 398data structure is printed. 399The full data structure is only printed when verbose output is requested. 400.Pp 401The following options can be used to print other 402.Qq IDENTIFY 403information: 404.Bl -tag -width Fl 405.It Fl c 406Print the list of all unique controller identifiers in the NVMe subsystem the 407specified namespace belongs to and which are currently attached to this 408namespace. 409.It Fl d 410Print the list of namespace identification descriptors of the namespace. 411.El 412.It Xo 413.Nm 414.Cm identify 415.Op Fl C | c | d | Oo Fl a Oc Fl n 416.Ar ctl[/ns] Ns [,...] 417.Xc 418Short-hand for the 419.Cm identify-controller 420and 421.Cm identify-namespace 422commands, prints the same information about the specified controllers and/or 423namespaces, depending on whether a controller or a namespace was specified. 424.Pp 425For a description of the various optional flags refer to the above description 426of the 427.Cm identify-controller 428and 429.Cm identify-namespace 430commands. 431.It Xo 432.Nm 433.Op Fl dv 434.Cm list-logpages 435.Op Fl a 436.Op Fl H 437.Op Fl o Ar field Ns [,...] Op Fl p 438.Op Fl s Ar scope Ns [,...] 439.Ar ctl[/ns] Ns [,...] 440.Op Ar logpage... 441.Xc 442Prints the list of log pages and information about them specific to the 443given controller or namespace. 444This is intended as a discovery mechanism and will print information 445about mandatory, optional, and vendor-specific log pages as well as all 446the information that is useful for retrieving information about them. 447.Pp 448The 449.Nm 450.Cm list-logpages 451command supports the following options: 452.Bl -tag -width Fl 453.It Fl a 454Print all log pages. 455By default, only logs that are implemented are printed. 456.It Fl H 457Omit the output header columns. 458.It Fl o Ar field Ns [,...] 459A comma-separated list of one or more output fields to be used. 460Fields are listed below and the name is case insensitive. 461.It Fl p 462Produce parsable output rather than human-readable output. 463This option requires that output fields be selected with the 464.Fl o 465option. 466.It Fl s Ar scope Ns [,...] 467Print log pages that match the specified scope. 468If no 469.Ar scope 470arguments are specified, then the scope will be set to 471.Dq ctrl,nvm 472when the device is a controller and 473.Dq ns 474when the device refers to a namespace. 475.El 476.Pp 477The following fields are supported: 478.Bl -tag -width MINSIZE 479.It Sy DEVICE 480Prints the name of the controller or namespace. 481.It Sy NAME 482Prints the name of the log page. 483This is the name that can be used to get the log page with the 484.Cm get-logpage 485command. 486This is a shortened form from the NVMe or vendor-specific documentation. 487.It Sy DESC 488This is a description of the log page and generally corresponds to 489information from the specification the log page is drawn from. 490.It Sy SCOPE 491This is the set of scopes that the log page is applicable to. 492As described earlier in the manual, valid scopes include 493.Dq ctrl , 494.Dq nvm , 495and 496.Dq ns . 497This indicates whether a controller 498.Po 499.Dq ctrl 500and 501.Dq nvm 502.Pc 503or a namespace 504.Po 505.Dq ns 506.Pc 507will work for this log page when running the 508.Cm get-logpage 509command to get the log. 510.It Sy FIELDS 511This indicates the command fields that are accepted when retrieving the 512log page from the controller. 513The fields include: 514.Bl -tag -width lsp 515.It Sy lsp 516Indicates that a log specific parameter is accepted for this page. 517.It Sy lsi 518Indicates that a log specific identifier is accepted for this page. 519.It Sy rae 520Indicates that one can control whether or not an asynchronous event is 521retained when retrieving the log page. 522By default, asynchronous events are cleared when certain log pages are 523fetched such as the health log page. 524.El 525For more information on these fields, please see the NVMe specification. 526.It Sy CSI 527Indicates the log page's command set interface. 528.It Sy LID 529Indicates the log page's numeric ID. 530This when combined with the log page's CSI is the unique identifier that 531identifies the log page to the controller. 532.It Sy IMPL 533Indicates whether or not the system believes that the log page is 534implemented. 535.It Sy SIZE 536Indicates the size of the log page. 537Not all log pages have a fixed size and in such cases this field will 538not contain a value. 539.It Sy MINSIZE 540When a log page is known to have a variable size, this indicates the 541minimum amount of the log page to read to determine the full size of the 542log page. 543.It Sy SOURCES 544This is a comma separated list of values that indicates where 545information about this log page and its support came from primarily. 546These include the following: 547.Bl -tag -width identify-controller 548.It Dq spec 549This comes from the NVMe specification. 550Generally this refers to mandatory log pages that are not dependent on 551any information in the identify controller data structure. 552.It Dq identify-controller 553Information about this log page comes from the identify controller data 554structure. 555Many log pages are described by the standard but are optional and their 556support is indicated through that. 557.It Dq internal-db 558This indicates that information about this log page comes from our 559internal databases in libnvme. 560Most vendor-specific logs are described in datasheets whose information 561is encoded into the library and system and there is not always a way to 562discover that it is supported or not. 563.It Dq command 564This indicates that information about this log page came from another 565command that was issued to the controller which indicates what was 566implemented and present. 567.El 568.It Sy KIND 569This indicates the kind of log page that this is. 570Valid options are: 571.Bl -tag -width vendor-specific 572.It Dq mandatory 573Indicates that the NVMe specification considers this mandatory for all 574controllers of a given version. 575.It Dq optional 576Indicates that the NVMe specification considers this log page optional. 577Some items may be mandatory if a device implements an optional feature 578like namespace management, but they will still be considered optional as 579the underlying feature is. 580.It Dq vendor-specific 581Indicates that this log is a vendor-specific log page. 582These log pages are not part of the NVMe standard and are generally 583described in their own device's datasheets or a separate standard such 584as the 585.%T OCP Datacenter NVMe SSD Specification . 586.El 587.El 588.Pp 589The 590.Cm list-logpages 591command supports a series of operands which can be used to filter the 592list of log pages that information is printed out about. 593Each 594.Ar logpage 595operand is the name of a log page. 596Only matching log pages will be printed and if no log pages match a 597given operand argument or not log pages are printed at all 598.Pq which can happen due to a log being unsupported 599then the command will generate an error. 600.It Xo 601.Nm 602.Cm get-logpage 603.Op Fl O Ar output-file 604.Ar ctl[/ns] Ns [,...] 605.Ar logpage 606.Xc 607Print the specified log page of the specified controllers and/or namespaces. 608If 609.Fl O 610is specified, rather than print the contents of the log, the raw binary payload 611of the log will be written to 612.Ar output-file . 613Most log pages are only available on a per-controller basis. 614Known log pages are: 615.Bl -tag -width "firmware" 616.It suplog 617Supported Log Pages. 618Lists information about log pages that the device supports. 619Available starting in NVMe 2.0 devices. 620.It error 621Error Information 622.It health 623SMART/Health Information. 624A controller may support this log page on a per-namespace basis. 625.It firmware 626Firmware Slot Information 627.It changens 628Changed Namespaces. 629.It cmdeff 630Commands Supported and Effects. 631An optional log page added in NVMe 1.2 that indicates what commands 632the controller itself actually supports. 633.It pev 634Persistent Event Log. 635An optional log page added in NVMe 1.4 that contains a series of events 636that have occurred on the device. 637.El 638.Pp 639The following vendor-specific log pages are supported. 640Not all devices from a vendor support every log page. 641Use the 642.Cm list-logpages 643command to determine which are supported for a given device and whether 644they operate on a controller or namespace. 645.Bl -tag -width "solidigm/outlier" 646.It kioxia/extsmart 647Kioxia Extended SMART. 648.It micron/smart 649Micron Vendor Unique SMART. 650.It micron/extsmart 651Micron Extended SMART. 652.It ocp/smart 653Open Compute Datacenter NVMe SSD specification SMART / Health information. 654.It ocp/errrec 655Open Compute Datacenter NVMe SSD specification error recovery log. 656.It ocp/fwact 657Open Compute Datacenter NVMe SSD specification firmware activation log. 658.It ocp/latency 659Open Compute Datacenter NVMe SSD specification latency monitor. 660.It ocp/devcap 661Open Compute Datacenter NVMe SSD specification device capabilities. 662.It ocp/unsup 663Open Compute Datacenter NVMe SSD specification unsupported requirements. 664.It solidigm/rlat 665Solidigm/Intel read command latency statistics. 666.It solidigm/wlat 667Solidigm/Intel write command latency statistics. 668.It solidigm/temp 669Solidigm/Intel temperature statistics. 670.It solidigm/smart 671Solidigm/Intel vendor unique SMART log. 672.It solidigm/ioqueue 673Solidigm/Intel I/O queue metrics. 674.It solidigm/name 675Solidigm/Intel drive marketing name. 676.It solidigm/power 677Solidigm/Intel power usage. 678.It solidigm/gc 679Solidigm/Intel garbage collection. 680.It solidigm/outlier 681Solidigm/Intel latency outlier. 682.It wdc/eol 683Western Digital end-of-life. 684.It wdc/devmgmt 685Western Digital device manageability. 686.It wdc/pciesi 687Western Digital PCIe signal integrity. 688.It wdc/power 689Western Digital power samples. 690.It wdc/temp 691Western Digital temperature samples. 692.It wdc/fwact 693Western Digital firmware activation history. 694.It wdc/ccds 695Western Digital CCDS build information. 696.It wdc/cusmart 697Western Digital customer unique SMART data. 698.El 699.Pp 700For an explanation of the contents of the log pages refer to the 701description of the 702.Qq GET LOGPAGE 703admin command in the NVMe specification. 704.It Xo 705.Nm 706.Cm list-features 707.Op Fl a 708.Op Fl H 709.Op Fl o Ar field Ns [,...] Op Fl p 710.Ar ctl[/ns] Ns [,...] 711.Op Ar feature Ns [,...] 712.Xc 713Prints the list of features and information about them specific to the 714given controller or namespace. 715This is intended as a discovery mechanism and will print information 716about known mandatory, optional, and vendor-specific features as well as 717the information that is useful for retrieving information about them. 718.Pp 719The 720.Nm 721.Cm list-features 722command supports the following options: 723.Bl -tag -width Fl 724.It Fl a 725Print all features, regardless of whether or not the controller is known 726to implement them. 727By default unimplemented features are not printed, but implemented and 728unknown ones are. 729.It Fl H 730Omit the output header columns. 731.It Fl o Ar field Ns [,...] 732A comma-separated list of one or more output fields to be used. 733Fields are listed below and the name is case insensitive. 734.It Fl p 735Produce parsable output rather than human-readable output. 736This option requires that output fields be selected with the 737.Fl o 738option. 739.El 740.Pp 741The following fields are supported: 742.Bl -tag -width DATALEN 743.It Sy DEVICE 744Prints the name of the controller or namespace. 745.It Sy SHORT 746This is a shortened name for a feature which can be used to identify it. 747These short names are unique to illumos and not part of the NVMe 748specification. 749.It Sy SPEC 750This is the specification's name for a given feature. 751.It Sy FID 752This is the numeric ID that can be used to uniquely identify a feature. 753.It Sy SCOPE 754This is a comma separated list of values that identifies what scopes 755this feature covers. 756The supported scopes are 757.Dq controller , 758which indicates that it impacts the entire controller and 759.Dq namespace , 760which indicates that it impacts just a single namespace. 761.It Sy KIND 762This indicates the kind of feature that this is. 763Valid options are: 764.Bl -tag -width vendor-specific 765.It Dq mandatory 766Indicates that the NVMe specification considers this mandatory for all 767controllers of a given version. 768.It Dq optional 769Indicates that the NVMe specification considers this feature optional. 770Some items may be mandatory if a device implements an optional feature 771like namespace management, but they will still be considered optional as 772the underlying feature is. 773.It Dq vendor-specific 774Indicates that this log is a vendor-specific feature. 775These features are not part of the NVMe standard and are generally 776described in their own device's datasheets or a separate standard such 777as the 778.%T OCP Datacenter NVMe SSD Specification . 779.El 780.It Sy CSI 781The command set interface that the feature is specific to. 782Most features are not specific to a CSI. 783.It Sy FLAGS 784The flags are a series of comma separated strings which describe 785properties of the feature. 786The following flags are currently supported: 787.Bl -tag -width "get-bcastns" 788.It Dq get-bcastns 789Indicates that the broadcast namespace is supported when getting this 790feature. 791.It Dq set-bcastns 792Indicates that the broadcast namespace is supported when setting this 793feature. 794Using the broadcast namespace indicates that all namespace are impacted. 795.El 796.It Sy GET-IN 797A series of comma separated values indicating what is required to get 798this feature. 799The following values are supported: 800.Bl -tag -width cdw11 801.It cdw11 802Indicates that the feature requires an argument in the cdw11 field of 803the command. 804This is generally a selector of some kind. 805For example, for the temperature threshold feature, it selects which of 806several sensors may be referred to. 807.It data 808Indicates that a data buffer is required when getting this feature. 809Its size is indicated by the DATALEN field. 810.It nsid 811Indicates that a namespace ID is required when getting this feature. 812.El 813.It Sy SET-IN 814A series of comma separated values indicating what is required to get 815this feature. 816The following values are supported: 817.Bl -tag -width cdw11 818.It cdw11 819Indicates that the feature uses information in cdw11 to set the feature. 820.It cdw12 821Indicates that the feature uses information in cdw12 to set the feature. 822.It cdw13 823Indicates that the feature uses information in cdw13 to set the feature. 824.It cdw14 825Indicates that the feature uses information in cdw14 to set the feature. 826.It cdw15 827Indicates that the feature uses information in cdw15 to set the feature. 828.It data 829Indicates that the feature takes a data payload to set the feature. 830Its size is indicated by the DATALEN field. 831.It nsid 832Indicates that the feature requires a valid namespace identifier. 833.El 834.It Sy GET-OUT 835A series of comma separated values indicating what the controller will 836return information about this feature in. 837The following values are supported: 838.Bl -tag -width cdw0 839.It cdw0 840Indicates that the controller will give information about the feature in 841the command output 32-bit value. 842.It data 843Indicates that the controller will output information about the feature 844into the output buffer. 845.El 846.It Sy SET-OUT 847A series of comma separated values indicating what the controller will 848update following the successful completion of setting the feature. 849These values are the same as with the GET-OUT field. 850.It Sy DATALEN 851Indicates the length of data for the feature. 852.It Sy IMPL 853Indicates whether or not the feature is known to be implemented or not. 854The following values are possible: 855.Bl -tag -width unknown 856.It Dq unknown 857Indicates that it is unknown as to whether or not the feature is 858implemented. 859Some features are optional and there is no way to determine this short 860of issuing an attempt to get the feature itself. 861.It Dq yes 862Indicates that we know the feature is implemented by the controller. 863.It Dq no 864Indicates that we know the feature is not implemented by the controller. 865.El 866.El 867.Pp 868The 869.Cm list-features 870command supports a series of operands which can be used to filter the 871list of features that information is printed out about. 872Each 873.Ar feature 874operand is either the short name or the specification's name for a given 875feature. 876In addition, the numeric feature ID can also be used as a filter. 877If no features match a given operand or no features are printed at all 878then the command will generate an error. 879.It Xo 880.Nm 881.Cm get-features 882.Ar ctl[/ns] Ns [,...] 883.Op Ar feature-list 884.Xc 885Prints information about the specified features, or all features if 886none are given, of the specified controllers and/or namespaces. 887Feature names are case-insensitive, and they can be shortened as long 888as they remain unique. 889Some features also have alternative short names to which the same 890rules apply. 891The following features are supported: 892.Pp 893.TS 894tab(:); 895l l l. 896FULL NAME:SHORT NAME:CONTROLLER/NAMESPACE 897Arbitration:arb:controller 898Power Management:pm:controller 899LBA Range Type:range:namespace 900Temperature Threshold:temp:controller 901Error Recovery:errec:controller 902Volatile Write Cache:cache:controller 903Number of Queues:queues:controller 904Interrupt Coalescing:coalescing:controller 905Interrupt Vector Configuration:vector:controller 906Write Atomicity:atomicity:controller 907Asynchronous Event Configuration:event:controller 908Autonomous Power State Transition:apst:controller 909Software Progress Marker:progress:controller 910.TE 911.Pp 912For an explanation of the individual features refer to the description 913of the 914.Qq SET FEATURES 915admin command in the NVMe specification. 916.It Xo 917.Nm 918.Cm format 919.Ar ctl[/ns] 920.Op Ar lba-format 921.Xc 922Formats the specified namespace or all namespaces of the specified 923controller. 924This command implies a 925.Nm 926.Cm detach 927and subsequent 928.Nm 929.Cm attach 930of the specified namespace(s), which will cause a changed LBA format 931to be detected. 932If no LBA format is specified the LBA format currently used by the 933namespace will be used. 934When formatting all namespaces without specifying a LBA format the LBA 935format of namespace 1 will be used. 936A list of LBA formats supported by a namespace can be queried with the 937.Nm 938.Cm identify 939command. 940.Pp 941Note that not all devices support formatting individual or all 942namespaces, or support formatting at all. 943.Pp 944LBA formats using a non-zero metadata size are not supported by 945.Nm 946or 947.Xr nvme 4D . 948.Pp 949The list of supported LBA formats on a namespace can be retrieved 950with the 951.Nm 952.Cm identify 953command. 954.It Xo 955.Nm 956.Cm secure-erase 957.Op Fl c 958.Ar ctl[/ns] 959.Xc 960Erases the specified namespace or all namespaces of the controller. 961The flag 962.Fl c 963will cause a cryptographic erase instead of a normal erase. 964This command implies a 965.Nm 966.Cm detach 967and 968.Nm 969.Cm attach 970of the specified namespace(s). 971.Pp 972Note that not all devices support erasing individual or all 973namespaces, or support erasing at all. 974.It Xo 975.Nm 976.Cm detach 977.Ar ctl[/ns] 978.Xc 979Temporarily detaches the 980.Xr blkdev 4D 981instance from the specified namespace or all namespaces of the controller. 982This will prevent I/O access to the affected namespace(s). 983Detach will only succeed if the affected namespace(s) are not 984currently opened. 985The detached state will not persist across reboots or reloads of the 986.Xr nvme 4D 987driver. 988.Pp 989It is not an error to detach a namespace that is already detached, any such 990request will be silently ignored. 991.It Xo 992.Nm 993.Cm attach 994.Ar ctl[/ns] 995.Xc 996Attaches the 997.Xr blkdev 4D 998instance to the specified namespace or all namespaces of the controller. 999This will make I/O accesses to the namespace(s) possible again after a 1000previous 1001.Nm 1002.Cm detach 1003command. 1004.Pp 1005It is not an error to attach a namespace that is already attached, any such 1006request will be silently ignored. 1007.It Xo 1008.Nm 1009.Cm list-firmware 1010.Ar ctl 1011.Xc 1012List currently active firmware slot, the next active firmware slot, and the 1013current contents of all firmware slots of an NVMe controller. 1014This is a synonym for the 1015.Nm 1016.Cm get-logpage 1017.Ar ctl 1018.Cm firmware 1019command. 1020.It Xo 1021.Nm 1022.Cm load-firmware 1023.Ar ctl 1024.Ar firmware-file 1025.Op Ar offset 1026.Xc 1027Loads 1028.Ar firmware-file 1029into the controller's upload memory at 1030.Ar offset , 1031the default is 0. A vendor may require multiple files to be loaded 1032at different offsets before the firmware is committed to a 1033.Ar slot . 1034.It Xo 1035.Nm 1036.Cm commit-firmware 1037.Ar ctl 1038.Ar slot 1039.Xc 1040Commits firmware previously loaded by the 1041.Cm load-firmware 1042command to 1043.Ar slot . 1044.It Xo 1045.Nm 1046.Cm activate-firmware 1047.Ar ctl 1048.Ar slot 1049.Xc 1050Activates the firmware in slot 1051.Ar slot . 1052The firmware image in 1053.Ar slot 1054is activated at the next NVM controller reset. 1055.It Xo 1056.Nm 1057.Cm wdc/e6dump 1058.Fl o Ar output 1059.Ar ctl 1060.Xc 1061This vendor-specific command performs a diagnostic dump of device data 1062to the file specified by 1063.Ar output . 1064The device remains in full service while this is occurring. 1065.It Xo 1066.Nm 1067.Cm wdc/resize 1068.Fl s Ar size | Fl g 1069.Ar ctl 1070.Xc 1071This vendor-specific command will get the current over provisioning size 1072or set it. 1073This command operates using power of 10 bytes, that is in terms of 1074gigabytes and not gibibytes. 1075The sizes that are used here will be different from those that the 1076operating system will report for the drive. 1077.Pp 1078The following options are supported: 1079.Bl -tag -width Fl 1080.It Fl g 1081Returns the current size of the device in gigabytes 1082.Pq powers of 10 . 1083.It Fl s Ar size 1084Sets the size of the device to 1085.Ar size 1086which is in gigabytes 1087.Pq powers of 10 . 1088This can be used to adjust the over provisioning ratio on the device. 1089The valid points are device-specific. 1090Please consult WDC datasheets for more information. 1091.Pp 1092When performing a resize 1093.Em all data and namespace will be erased ! 1094All namespaces must be detached prior to issuing this. 1095.El 1096.It Xo 1097.Nm 1098.Op Fl dv 1099.Cm wdc/clear-assert 1100.Ar ctl 1101.Xc 1102This clears an internal assertion record from a WDC device. 1103Prior to running this any such internal assertion should be saved by using the 1104.Cm wdc/e6dump 1105command. 1106This command should only be used if instructed to do so as part of a 1107troubleshooting process. 1108.It Xo 1109.Nm 1110.Op Fl dv 1111.Cm wdc/inject-assert 1112.Ar ctl 1113.Xc 1114This injects a device assertion into a WDC NVMe device. 1115The behavior of doing so is device specific; however, all I/O will be 1116interrupted and the device may be retired. 1117Unless explicitly instructed as part of debugging a device or as part of 1118internal development, this command should not be used. 1119.El 1120.Sh EXIT STATUS 1121.Ex -std 1122.Sh EXAMPLES 1123.Bl -tag -width "" 1124.It Sy Example 1: List all NVMe controllers and namespaces 1125.Bd -literal 1126# nvmeadm list 1127nvme1: model: INTEL SSDPEDMD800G4, serial: CVFT4134001R800CGN, FW rev: 8DV10049, NVMe v1.0 1128 nvme1/1 (c1t1d0): Size = 763097 MB, Capacity = 763097 MB, Used = 763097 MB 1129nvme4: model: SAMSUNG MZVPV128HDGM-00000, serial: S1XVNYAGA00640, FW rev: BXW7300Q, NVMe v1.1 1130 nvme4/1 (c2t2d0): Size = 122104 MB, Capacity = 122104 MB, Used = 5127 MB 1131.Ed 1132.It Sy Example 2: Identify a namespace 1133.Bd -literal 1134# nvmeadm identify nvme4/1 1135nvme4/1: Identify Namespace 1136 Namespace Capabilities and Features 1137 Namespace Size: 122104MB 1138 Namespace Capacity: 122104MB 1139 Namespace Utilization: 5127MB 1140 Namespace Features 1141 Thin Provisioning: unsupported 1142 Number of LBA Formats: 1 1143 Formatted LBA Size 1144 LBA Format: 1 1145 Extended Data LBA: no 1146 Metadata Capabilities 1147 Extended Data LBA: unsupported 1148 Separate Metadata: unsupported 1149 End-to-End Data Protection Capabilities 1150 Protection Information Type 1: unsupported 1151 Protection Information Type 2: unsupported 1152 Protection Information Type 3: unsupported 1153 Protection Information first: unsupported 1154 Protection Information last: unsupported 1155 End-to-End Data Protection Settings 1156 Protection Information: disabled 1157 Protection Information in Metadata: last 8 bytes 1158 LBA Format 1 1159 Metadata Size: 0 bytes 1160 LBA Data Size: 512 bytes 1161 Relative Performance: Best 1162.Ed 1163.It Sy Example 3: Get SMART/Health information (verbose) 1164.Bd -literal 1165# nvmeadm -v get-logpage nvme4/1 health 1166nvme4/1: SMART/Health Information 1167 Critical Warnings 1168 Available Space: OK 1169 Temperature: OK 1170 Device Reliability: OK 1171 Media: OK 1172 Volatile Memory Backup: OK 1173 Temperature: 37C 1174 Available Spare Capacity: 100% 1175 Available Spare Threshold: 10% 1176 Device Life Used: 0% 1177 Data Read: 0GB 1178 Data Written: 64GB 1179 Read Commands: 52907 1180 Write Commands: 567874 1181 Controller Busy: 1min 1182 Power Cycles: 6 1183 Power On: 141h 1184 Unsafe Shutdowns: 1 1185 Uncorrectable Media Errors: 0 1186 Errors Logged: 1 1187.Ed 1188.It Sy Example 4: Get Asynchronous Event Configuration information 1189.Bd -literal 1190# nvmeadm get-features nvme0,nvme4 event,power 1191nvme0: Get Features 1192 Asynchronous Event Configuration 1193 Available Space below threshold: disabled 1194 Temperature above threshold: disabled 1195 Device Reliability compromised: disabled 1196 Media read-only: disabled 1197 Power Management 1198 Power State: 0 1199nvme4: Get Features 1200 Asynchronous Event Configuration 1201 Available Space below threshold: disabled 1202 Temperature above threshold: disabled 1203 Device Reliability compromised: disabled 1204 Media read-only: disabled 1205 Volatile Memory Backup failed: disabled 1206 Power Management 1207 Power State: 0 1208.Ed 1209.It Sy Example 5: Load and activate firmware 1210.Bd -literal 1211# nvmeadm list-firmware nvme3 1212nvme3: Firmware Slot Information 1213 Active Firmware Slot: 4 1214 Next Firmware Slot: 4 1215 Firmware Revision for Slot 1: KNGND110 (read-only) 1216 Firmware Revision for Slot 2: KNGND110 1217 Firmware Revision for Slot 3: KNGND110 1218 Firmware Revision for Slot 4: KNGND112 1219 Firmware Revision for Slot 5: KNGND110 1220 1221# nvmeadm -v load-firmware nvme3 KNGND113.bin 12221740544 bytes downloaded. 1223 1224# nvmeadm -v commit-firmware nvme3 5 1225Firmware committed to slot 5. 1226 1227# nvmeadm -v activate-firmware nvme3 5 1228Slot 5 activated: NVM subsystem reset required - power cycle your system. 1229 1230# nvmeadm list-firmware nvme3 1231nvme3: Firmware Slot Information 1232 Active Firmware Slot: 4 1233 Next Firmware Slot: 5 1234 Firmware Revision for Slot 1: KNGND110 (read-only) 1235 Firmware Revision for Slot 2: KNGND110 1236 Firmware Revision for Slot 3: KNGND110 1237 Firmware Revision for Slot 4: KNGND112 1238 Firmware Revision for Slot 5: KNGND113 1239.Ed 1240.It Sy Example 6: Listing Log Pages 1241.Bd -literal 1242# nvmeadm list-logpages nvme8 1243DEVICE NAME SCOPE FIELDS DESC 1244nvme8 error controller rae Error information 1245nvme8 health controller, rae SMART / Health information 1246 namespace 1247nvme8 firmware nvm -- Firmware Slot Information 1248nvme8 changens controller rae changed namespaces 1249nvme8 wdc/eol nvm -- EOL 1250nvme8 wdc/devmgmt controller, -- Device Manageability 1251 namespace 1252nvme8 wdc/pciesi controller lsp PCIe Signal Integrity 1253nvme8 wdc/power controller -- Power Samples 1254nvme8 wdc/temp controller -- Temperature Samples 1255nvme8 wdc/fwact controller -- Firmware Activation 1256nvme8 wdc/ccds controller -- CCDS Build Information 1257# nvmeadm list-logpages -p -o name,impl nvme8 firmware 1258firmware:yes 1259.Ed 1260.El 1261.Sh INTERFACE STABILITY 1262The command line interface of 1263.Nm 1264is 1265.Sy Evolving . 1266The output of 1267.Nm 1268is 1269.Sy Not-an-Interface 1270and may change any time. 1271.Sh SEE ALSO 1272.Xr nvme 4D 1273.Pp 1274.Lk http://www.nvmexpress.org/specifications/ "NVMe specifications" 1275