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