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 12, 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 beginning in NVMe 1.2 that indicates what commands 632the controller itself actually supports. 633.El 634.Pp 635The following vendor-specific log pages are supported. 636Not all devices from a vendor support every log page. 637Use the 638.Cm list-logpages 639command to determine which are supported for a given device and whether 640they operate on a controller or namespace. 641.Bl -tag -width "wdc/devmgm" 642.It micron/smart 643Micron Vendor Unique SMART. 644.It micron/extsmart 645Micron Extended SMART. 646.It ocp/smart 647Open Compute Datacenter NVMe SSD specification SMART / Health information. 648.It ocp/errrec 649Open Compute Datacenter NVMe SSD specification error recovery log. 650.It ocp/fwact 651Open Compute Datacenter NVMe SSD specification firmware activation log. 652.It ocp/latency 653Open Compute Datacenter NVMe SSD specification latency monitor. 654.It ocp/devcap 655Open Compute Datacenter NVMe SSD specification device capabilities. 656.It ocp/unsup 657Open Compute Datacenter NVMe SSD specification unsupported requirements. 658.It solidigm/rlat 659Solidigm/Intel read command latency statistics. 660.It solidigm/wlat 661Solidigm/Intel write command latency statistics. 662.It solidigm/temp 663Solidigm/Intel temperature statistics. 664.It solidigm/smart 665Solidigm/Intel vendor unique SMART log. 666.It solidigm/ioqueue 667Solidigm/Intel I/O queue metrics. 668.It solidigm/name 669Solidigm/Intel drive marketing name. 670.It solidigm/power 671Solidigm/Intel power usage. 672.It solidigm/gc 673Solidigm/Intel garbage collection. 674.It solidigm/outlier 675Solidigm/Intel latency outlier. 676.It wdc/eol 677Western Digital end-of-life. 678.It wdc/devmgmt 679Western Digital device manageability. 680.It wdc/pciesi 681Western Digital PCIe signal integrity. 682.It wdc/power 683Western Digital power samples. 684.It wdc/temp 685Western Digital temperature samples. 686.It wdc/fwact 687Western Digital firmware activation history. 688.It wdc/ccds 689Western Digital CCDS build information. 690.It wdc/cusmart 691Western Digital customer unique SMART data. 692.El 693.Pp 694For an explanation of the contents of the log pages refer to the 695description of the 696.Qq GET LOGPAGE 697admin command in the NVMe specification. 698.It Xo 699.Nm 700.Cm list-features 701.Op Fl a 702.Op Fl H 703.Op Fl o Ar field Ns [,...] Op Fl p 704.Ar ctl[/ns] Ns [,...] 705.Op Ar feature Ns [,...] 706.Xc 707Prints the list of features and information about them specific to the 708given controller or namespace. 709This is intended as a discovery mechanism and will print information 710about known mandatory, optional, and vendor-specific features as well as 711the information that is useful for retrieving information about them. 712.Pp 713The 714.Nm 715.Cm list-features 716command supports the following options: 717.Bl -tag -width Fl 718.It Fl a 719Print all features, regardless of whether or not the controller is known 720to implement them. 721By default unimplemented features are not printed, but implemented and 722unknown ones are. 723.It Fl H 724Omit the output header columns. 725.It Fl o Ar field Ns [,...] 726A comma-separated list of one or more output fields to be used. 727Fields are listed below and the name is case insensitive. 728.It Fl p 729Produce parsable output rather than human-readable output. 730This option requires that output fields be selected with the 731.Fl o 732option. 733.El 734.Pp 735The following fields are supported: 736.Bl -tag -width DATALEN 737.It Sy DEVICE 738Prints the name of the controller or namespace. 739.It Sy SHORT 740This is a shortened name for a feature which can be used to identify it. 741These short names are unique to illumos and not part of the NVMe 742specification. 743.It Sy SPEC 744This is the specification's name for a given feature. 745.It Sy FID 746This is the numeric ID that can be used to uniquely identify a feature. 747.It Sy SCOPE 748This is a comma separated list of values that identifies what scopes 749this feature covers. 750The supported scopes are 751.Dq controller , 752which indicates that it impacts the entire controller and 753.Dq namespace , 754which indicates that it impacts just a single namespace. 755.It Sy KIND 756This indicates the kind of feature that this is. 757Valid options are: 758.Bl -tag -width vendor-specific 759.It Dq mandatory 760Indicates that the NVMe specification considers this mandatory for all 761controllers of a given version. 762.It Dq optional 763Indicates that the NVMe specification considers this feature optional. 764Some items may be mandatory if a device implements an optional feature 765like namespace management, but they will still be considered optional as 766the underlying feature is. 767.It Dq vendor-specific 768Indicates that this log is a vendor-specific feature. 769These features are not part of the NVMe standard and are generally 770described in their own device's datasheets or a separate standard such 771as the 772.%T OCP Datacenter NVMe SSD Specification . 773.El 774.It Sy CSI 775The command set interface that the feature is specific to. 776Most features are not specific to a CSI. 777.It Sy FLAGS 778The flags are a series of comma separated strings which describe 779properties of the feature. 780The following flags are currently supported: 781.Bl -tag -width "get-bcastns" 782.It Dq get-bcastns 783Indicates that the broadcast namespace is supported when getting this 784feature. 785.It Dq set-bcastns 786Indicates that the broadcast namespace is supported when setting this 787feature. 788Using the broadcast namespace indicates that all namespace are impacted. 789.El 790.It Sy GET-IN 791A series of comma separated values indicating what is required to get 792this feature. 793The following values are supported: 794.Bl -tag -width cdw11 795.It cdw11 796Indicates that the feature requires an argument in the cdw11 field of 797the command. 798This is generally a selector of some kind. 799For example, for the temperature threshold feature, it selects which of 800several sensors may be referred to. 801.It data 802Indicates that a data buffer is required when getting this feature. 803Its size is indicated by the DATALEN field. 804.It nsid 805Indicates that a namespace ID is required when getting this feature. 806.El 807.It Sy SET-IN 808A series of comma separated values indicating what is required to get 809this feature. 810The following values are supported: 811.Bl -tag -width cdw11 812.It cdw11 813Indicates that the feature uses information in cdw11 to set the feature. 814.It cdw12 815Indicates that the feature uses information in cdw12 to set the feature. 816.It cdw13 817Indicates that the feature uses information in cdw13 to set the feature. 818.It cdw14 819Indicates that the feature uses information in cdw14 to set the feature. 820.It cdw15 821Indicates that the feature uses information in cdw15 to set the feature. 822.It data 823Indicates that the feature takes a data payload to set the feature. 824Its size is indicated by the DATALEN field. 825.It nsid 826Indicates that the feature requires a valid namespace identifier. 827.El 828.It Sy GET-OUT 829A series of comma separated values indicating what the controller will 830return information about this feature in. 831The following values are supported: 832.Bl -tag -width cdw0 833.It cdw0 834Indicates that the controller will give information about the feature in 835the command output 32-bit value. 836.It data 837Indicates that the controller will output information about the feature 838into the output buffer. 839.El 840.It Sy SET-OUT 841A series of comma separated values indicating what the controller will 842update following the successful completion of setting the feature. 843These values are the same as with the GET-OUT field. 844.It Sy DATALEN 845Indicates the length of data for the feature. 846.It Sy IMPL 847Indicates whether or not the feature is known to be implemented or not. 848The following values are possible: 849.Bl -tag -width unknown 850.It Dq unknown 851Indicates that it is unknown as to whether or not the feature is 852implemented. 853Some features are optional and there is no way to determine this short 854of issuing an attempt to get the feature itself. 855.It Dq yes 856Indicates that we know the feature is implemented by the controller. 857.It Dq no 858Indicates that we know the feature is not implemented by the controller. 859.El 860.El 861.Pp 862The 863.Cm list-features 864command supports a series of operands which can be used to filter the 865list of features that information is printed out about. 866Each 867.Ar feature 868operand is either the short name or the specification's name for a given 869feature. 870In addition, the numeric feature ID can also be used as a filter. 871If no features match a given operand or no features are printed at all 872then the command will generate an error. 873.It Xo 874.Nm 875.Cm get-features 876.Ar ctl[/ns] Ns [,...] 877.Op Ar feature-list 878.Xc 879Prints information about the specified features, or all features if 880none are given, of the specified controllers and/or namespaces. 881Feature names are case-insensitive, and they can be shortened as long 882as they remain unique. 883Some features also have alternative short names to which the same 884rules apply. 885The following features are supported: 886.Pp 887.TS 888tab(:); 889l l l. 890FULL NAME:SHORT NAME:CONTROLLER/NAMESPACE 891Arbitration:arb:controller 892Power Management:pm:controller 893LBA Range Type:range:namespace 894Temperature Threshold:temp:controller 895Error Recovery:errec:controller 896Volatile Write Cache:cache:controller 897Number of Queues:queues:controller 898Interrupt Coalescing:coalescing:controller 899Interrupt Vector Configuration:vector:controller 900Write Atomicity:atomicity:controller 901Asynchronous Event Configuration:event:controller 902Autonomous Power State Transition:apst:controller 903Software Progress Marker:progress:controller 904.TE 905.Pp 906For an explanation of the individual features refer to the description 907of the 908.Qq SET FEATURES 909admin command in the NVMe specification. 910.It Xo 911.Nm 912.Cm format 913.Ar ctl[/ns] 914.Op Ar lba-format 915.Xc 916Formats the specified namespace or all namespaces of the specified 917controller. 918This command implies a 919.Nm 920.Cm detach 921and subsequent 922.Nm 923.Cm attach 924of the specified namespace(s), which will cause a changed LBA format 925to be detected. 926If no LBA format is specified the LBA format currently used by the 927namespace will be used. 928When formatting all namespaces without specifying a LBA format the LBA 929format of namespace 1 will be used. 930A list of LBA formats supported by a namespace can be queried with the 931.Nm 932.Cm identify 933command. 934.Pp 935Note that not all devices support formatting individual or all 936namespaces, or support formatting at all. 937.Pp 938LBA formats using a non-zero metadata size are not supported by 939.Nm 940or 941.Xr nvme 4D . 942.Pp 943The list of supported LBA formats on a namespace can be retrieved 944with the 945.Nm 946.Cm identify 947command. 948.It Xo 949.Nm 950.Cm secure-erase 951.Op Fl c 952.Ar ctl[/ns] 953.Xc 954Erases the specified namespace or all namespaces of the controller. 955The flag 956.Fl c 957will cause a cryptographic erase instead of a normal erase. 958This command implies a 959.Nm 960.Cm detach 961and 962.Nm 963.Cm attach 964of the specified namespace(s). 965.Pp 966Note that not all devices support erasing individual or all 967namespaces, or support erasing at all. 968.It Xo 969.Nm 970.Cm detach 971.Ar ctl[/ns] 972.Xc 973Temporarily detaches the 974.Xr blkdev 4D 975instance from the specified namespace or all namespaces of the controller. 976This will prevent I/O access to the affected namespace(s). 977Detach will only succeed if the affected namespace(s) are not 978currently opened. 979The detached state will not persist across reboots or reloads of the 980.Xr nvme 4D 981driver. 982.Pp 983It is not an error to detach a namespace that is already detached, any such 984request will be silently ignored. 985.It Xo 986.Nm 987.Cm attach 988.Ar ctl[/ns] 989.Xc 990Attaches the 991.Xr blkdev 4D 992instance to the specified namespace or all namespaces of the controller. 993This will make I/O accesses to the namespace(s) possible again after a 994previous 995.Nm 996.Cm detach 997command. 998.Pp 999It is not an error to attach a namespace that is already attached, any such 1000request will be silently ignored. 1001.It Xo 1002.Nm 1003.Cm list-firmware 1004.Ar ctl 1005.Xc 1006List currently active firmware slot, the next active firmware slot, and the 1007current contents of all firmware slots of an NVMe controller. 1008This is a synonym for the 1009.Nm 1010.Cm get-logpage 1011.Ar ctl 1012.Cm firmware 1013command. 1014.It Xo 1015.Nm 1016.Cm load-firmware 1017.Ar ctl 1018.Ar firmware-file 1019.Op Ar offset 1020.Xc 1021Loads 1022.Ar firmware-file 1023into the controller's upload memory at 1024.Ar offset , 1025the default is 0. A vendor may require multiple files to be loaded 1026at different offsets before the firmware is committed to a 1027.Ar slot . 1028.It Xo 1029.Nm 1030.Cm commit-firmware 1031.Ar ctl 1032.Ar slot 1033.Xc 1034Commits firmware previously loaded by the 1035.Cm load-firmware 1036command to 1037.Ar slot . 1038.It Xo 1039.Nm 1040.Cm activate-firmware 1041.Ar ctl 1042.Ar slot 1043.Xc 1044Activates the firmware in slot 1045.Ar slot . 1046The firmware image in 1047.Ar slot 1048is activated at the next NVM controller reset. 1049.It Xo 1050.Nm 1051.Cm wdc/e6dump 1052.Fl o Ar output 1053.Ar ctl 1054.Xc 1055This vendor-specific command performs a diagnostic dump of device data 1056to the file specified by 1057.Ar output . 1058The device remains in full service while this is occurring. 1059.It Xo 1060.Nm 1061.Cm wdc/resize 1062.Fl s Ar size | Fl g 1063.Ar ctl 1064.Xc 1065This vendor-specific command will get the current over provisioning size 1066or set it. 1067This command operates using power of 10 bytes, that is in terms of 1068gigabytes and not gibibytes. 1069The sizes that are used here will be different from those that the 1070operating system will report for the drive. 1071.Pp 1072The following options are supported: 1073.Bl -tag -width Fl 1074.It Fl g 1075Returns the current size of the device in gigabytes 1076.Pq powers of 10 . 1077.It Fl s Ar size 1078Sets the size of the device to 1079.Ar size 1080which is in gigabytes 1081.Pq powers of 10 . 1082This can be used to adjust the over provisioning ratio on the device. 1083The valid points are device-specific. 1084Please consult WDC datasheets for more information. 1085.Pp 1086When performing a resize 1087.Em all data and namespace will be erased ! 1088All namespaces must be detached prior to issuing this. 1089.El 1090.It Xo 1091.Nm 1092.Op Fl dv 1093.Cm wdc/clear-assert 1094.Ar ctl 1095.Xc 1096This clears an internal assertion record from a WDC device. 1097Prior to running this any such internal assertion should be saved by using the 1098.Cm wdc/e6dump 1099command. 1100This command should only be used if instructed to do so as part of a 1101troubleshooting process. 1102.It Xo 1103.Nm 1104.Op Fl dv 1105.Cm wdc/inject-assert 1106.Ar ctl 1107.Xc 1108This injects a device assertion into a WDC NVMe device. 1109The behavior of doing so is device specific; however, all I/O will be 1110interrupted and the device may be retired. 1111Unless explicitly instructed as part of debugging a device or as part of 1112internal development, this command should not be used. 1113.El 1114.Sh EXIT STATUS 1115.Ex -std 1116.Sh EXAMPLES 1117.Bl -tag -width "" 1118.It Sy Example 1: List all NVMe controllers and namespaces 1119.Bd -literal 1120# nvmeadm list 1121nvme1: model: INTEL SSDPEDMD800G4, serial: CVFT4134001R800CGN, FW rev: 8DV10049, NVMe v1.0 1122 nvme1/1 (c1t1d0): Size = 763097 MB, Capacity = 763097 MB, Used = 763097 MB 1123nvme4: model: SAMSUNG MZVPV128HDGM-00000, serial: S1XVNYAGA00640, FW rev: BXW7300Q, NVMe v1.1 1124 nvme4/1 (c2t2d0): Size = 122104 MB, Capacity = 122104 MB, Used = 5127 MB 1125.Ed 1126.It Sy Example 2: Identify a namespace 1127.Bd -literal 1128# nvmeadm identify nvme4/1 1129nvme4/1: Identify Namespace 1130 Namespace Capabilities and Features 1131 Namespace Size: 122104MB 1132 Namespace Capacity: 122104MB 1133 Namespace Utilization: 5127MB 1134 Namespace Features 1135 Thin Provisioning: unsupported 1136 Number of LBA Formats: 1 1137 Formatted LBA Size 1138 LBA Format: 1 1139 Extended Data LBA: no 1140 Metadata Capabilities 1141 Extended Data LBA: unsupported 1142 Separate Metadata: unsupported 1143 End-to-End Data Protection Capabilities 1144 Protection Information Type 1: unsupported 1145 Protection Information Type 2: unsupported 1146 Protection Information Type 3: unsupported 1147 Protection Information first: unsupported 1148 Protection Information last: unsupported 1149 End-to-End Data Protection Settings 1150 Protection Information: disabled 1151 Protection Information in Metadata: last 8 bytes 1152 LBA Format 1 1153 Metadata Size: 0 bytes 1154 LBA Data Size: 512 bytes 1155 Relative Performance: Best 1156.Ed 1157.It Sy Example 3: Get SMART/Health information (verbose) 1158.Bd -literal 1159# nvmeadm -v get-logpage nvme4/1 health 1160nvme4/1: SMART/Health Information 1161 Critical Warnings 1162 Available Space: OK 1163 Temperature: OK 1164 Device Reliability: OK 1165 Media: OK 1166 Volatile Memory Backup: OK 1167 Temperature: 37C 1168 Available Spare Capacity: 100% 1169 Available Spare Threshold: 10% 1170 Device Life Used: 0% 1171 Data Read: 0GB 1172 Data Written: 64GB 1173 Read Commands: 52907 1174 Write Commands: 567874 1175 Controller Busy: 1min 1176 Power Cycles: 6 1177 Power On: 141h 1178 Unsafe Shutdowns: 1 1179 Uncorrectable Media Errors: 0 1180 Errors Logged: 1 1181.Ed 1182.It Sy Example 4: Get Asynchronous Event Configuration information 1183.Bd -literal 1184# nvmeadm get-features nvme0,nvme4 event,power 1185nvme0: Get Features 1186 Asynchronous Event Configuration 1187 Available Space below threshold: disabled 1188 Temperature above threshold: disabled 1189 Device Reliability compromised: disabled 1190 Media read-only: disabled 1191 Power Management 1192 Power State: 0 1193nvme4: Get Features 1194 Asynchronous Event Configuration 1195 Available Space below threshold: disabled 1196 Temperature above threshold: disabled 1197 Device Reliability compromised: disabled 1198 Media read-only: disabled 1199 Volatile Memory Backup failed: disabled 1200 Power Management 1201 Power State: 0 1202.Ed 1203.It Sy Example 5: Load and activate firmware 1204.Bd -literal 1205# nvmeadm list-firmware nvme3 1206nvme3: Firmware Slot Information 1207 Active Firmware Slot: 4 1208 Next Firmware Slot: 4 1209 Firmware Revision for Slot 1: KNGND110 (read-only) 1210 Firmware Revision for Slot 2: KNGND110 1211 Firmware Revision for Slot 3: KNGND110 1212 Firmware Revision for Slot 4: KNGND112 1213 Firmware Revision for Slot 5: KNGND110 1214 1215# nvmeadm -v load-firmware nvme3 KNGND113.bin 12161740544 bytes downloaded. 1217 1218# nvmeadm -v commit-firmware nvme3 5 1219Firmware committed to slot 5. 1220 1221# nvmeadm -v activate-firmware nvme3 5 1222Slot 5 activated: NVM subsystem reset required - power cycle your system. 1223 1224# nvmeadm list-firmware nvme3 1225nvme3: Firmware Slot Information 1226 Active Firmware Slot: 4 1227 Next Firmware Slot: 5 1228 Firmware Revision for Slot 1: KNGND110 (read-only) 1229 Firmware Revision for Slot 2: KNGND110 1230 Firmware Revision for Slot 3: KNGND110 1231 Firmware Revision for Slot 4: KNGND112 1232 Firmware Revision for Slot 5: KNGND113 1233.Ed 1234.It Sy Example 6: Listing Log Pages 1235.Bd -literal 1236# nvmeadm list-logpages nvme8 1237DEVICE NAME SCOPE FIELDS DESC 1238nvme8 error controller rae Error information 1239nvme8 health controller, rae SMART / Health information 1240 namespace 1241nvme8 firmware nvm -- Firmware Slot Information 1242nvme8 changens controller rae changed namespaces 1243nvme8 wdc/eol nvm -- EOL 1244nvme8 wdc/devmgmt controller, -- Device Manageability 1245 namespace 1246nvme8 wdc/pciesi controller lsp PCIe Signal Integrity 1247nvme8 wdc/power controller -- Power Samples 1248nvme8 wdc/temp controller -- Temperature Samples 1249nvme8 wdc/fwact controller -- Firmware Activation 1250nvme8 wdc/ccds controller -- CCDS Build Information 1251# nvmeadm list-logpages -p -o name,impl nvme8 firmware 1252firmware:yes 1253.Ed 1254.El 1255.Sh INTERFACE STABILITY 1256The command line interface of 1257.Nm 1258is 1259.Sy Evolving . 1260The output of 1261.Nm 1262is 1263.Sy Not-an-Interface 1264and may change any time. 1265.Sh SEE ALSO 1266.Xr nvme 4D 1267.Pp 1268.Lk http://www.nvmexpress.org/specifications/ "NVMe specifications" 1269