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