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