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