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