NVMEADM(1M) Maintenance Commands NVMEADM(1M)

nvmeadm
NVMe administration utility

nvmeadm -h [command]

nvmeadm [-dv] list [-p -o field[,...]] [ctl[/ns][,...]]

nvmeadm [-dv] identify ctl[/ns][,...]

nvmeadm [-dv] get-logpage ctl[/ns][,...] logpage

nvmeadm [-dv] get-features ctl[/ns][,...] [feature-list]

nvmeadm [-dv] format ctl[/ns] [lba-format]

nvmeadm [-dv] secure-erase ctl[/ns] [-c]

nvmeadm [-dv] detach ctl[/ns]

nvmeadm [-dv] attach ctl[/ns]

nvmeadm [-dv] load-firmware ctl firmware-file [offset]

nvmeadm [-dv] commit-firmware ctl slot

nvmeadm [-dv] activate-firmware ctl slot

The nvmeadm utility can be used to enumerate the NVMe controllers and their namespaces, query hardware information from a NVMe controller or namespace, and to format or secure-erase a NVMe controller or namespace.

The information returned by the hardware is printed by nvmeadm in a human-readable form were applicable. Generally all 0-based counts are normalized and values may be converted to human-readable units such as MB (megabytes), W (watts), or C (degrees Celsius).

The following options are supported:
Print a short help text for nvmeadm, or for an optionally specified nvmeadm command.
Enable debugging output.
Enable verbose output.

nvmeadm expects the following kinds of arguments:
command
Any command nvmeadm understands. See section COMMANDS.
ctl[/ns]
Specifies a NVMe controller and optionally a namespace within that controller. The controller name consists of the driver name “nvme” followed by an instance number. A namespace is specified by appending a single “/” followed by the namespace ID to the controller name. The namespace ID is the EUI64 of the namespace, or a positive non-zero decimal number if the namespace doesn't have an EUI64. For commands that don't change the device state multiple controllers and namespaces can be specified as a comma-separated list.

The list of controllers and namespaces present in the system can be queried with the list command without any arguments.

logpage
Specifies the log page name for the get-logpage command.
feature-list
A comma-separated list of feature names for the get-features command. Feature names can be specified in upper or lower case and can be shortened the shortest unique name. Some features may also have an alternative short name.
lba-format
A non-zero integer specifying the LBA format for the format command. The list of supported LBA formats on a namespace can be retrieved with the nvmeadm identify command.
firmware-file
Specifies the name of a firmware file to be loaded into the controller using the load-firmware command.
offset
Specifies the byte offset at which to load firmware-file within the controller's upload buffer. Vendors may require multiple images to be loaded at different offsets before a firmware set is committed to a slot.
slot
Specifies the firmware slot into which a firmware set is committed using the commit-firmware command, and subsequently activated with the activate-firmware command. Slots and their contents can be printed using nvmeadm get-logpage to request the firmware logpage.

nvmeadm list [-p -o field[,...]] [ctl[/ns][,...]]
Lists the NVMe controllers and their namespaces in the system and prints a 1-line summary of their basic properties for each. If a list of controllers and/or namespaces is given then the listing is limited to those devices. By default, output is human-readable; however, a parsable form can controlled by using the following options:
Rather than printing human-readable output, outputs an entry for each of the specified controllers and namespaces. If no controllers or namespaces are given as arguments, then the primary namespace of each controller is listed and if the -v option is specified, then all of the namespaces for a controller are listed. This option requires that output fields be selected with the -o option.
field[,...]
A comma-separated list of one or more output fields to be used. Fields are listed below and the name is case insensitive.

The following fields can be specified when using the parsable form:

MODEL
The model number of the device, generally containing information about both the manufacturer and the product.
SERIAL
The NVMe controller's serial number.
FWREV
The controller's firmware revision.
VERSION
The version of the NVMe specification the controller supports.
SIZE
The logical size in bytes of the namespace.
CAPACITY
The amount of logical bytes that the namespace may actually have allocated at any time. This may be different than size due to the use of thin provisioning or due to administrative action.
USED
The number of bytes used in the namespace.
INSTANCE
The name of the device node and instance of it.
NAMESPACE
The numerical value of the namespace which can be used as part of other nvmeadm operations.
DISK
The name of the disk device that corresponds to the namespace, if any.
nvmeadm identify ctl[/ns][,...]
Print detailed information about the specified controllers and/or namespaces. The information returned differs depending on whether a controller or a namespace is specified. For an explanation of the data printed by this command refer to the description of the “IDENTIFY” admin command in the NVMe specification.
nvmeadm get-logpage ctl[/ns][,...] logpage
Print the specified log page of the specified controllers and/or namespaces. Most log pages are only available on a per-controller basis. Known log pages are:
error
Error Information
health
SMART/Health Information. A controller may support this log page on a per-namespace basis.
firmware
Firmware Slot Information

For an explanation of the contents of the log pages refer to the description of the “GET LOGPAGE” admin command in the NVMe specification.

nvmeadm get-features ctl[/ns][,...] [feature-list]
Prints information about the specified features, or all features if none are given, of the specified controllers and/or namespaces. Feature names are case-insensitive, and they can be shortened as long as they remain unique. Some features also have alternative short names to which the same rules apply. The following features are supported:

FULL NAME SHORT NAME CONTROLLER/NAMESPACE
Arbitration controller
Power Management controller
LBA Range Type range namespace
Temperature Threshold controller
Error Recovery controller
Volatile Write Cache cache controller
Number of Queues queues controller
Interrupt Coalescing coalescing controller
Interrupt Vector Configuration vector controller
Write Atomicity atomicity controller
Asynchronous Event Configuration event controller
Autonomous Power State Transition controller
Software Progress Marker progress controller

For an explanation of the individual features refer to the description of the “SET FEATURES” admin command in the NVMe specification.

nvmeadm format ctl[/ns] [lba-format]
Formats the specified namespace or all namespaces of the specified controller. This command implies a nvmeadm detach and subsequent nvmeadm attach of the specified namespace(s), which will cause a changed LBA format to be detected. If no LBA format is specified the LBA format currently used by the namespace will be used. When formatting all namespaces without specifying a LBA format the LBA format of namespace 1 will be used. A list of LBA formats supported by a namespace can be queried with the nvmeadm identify command.

Note that not all devices support formatting individual or all namespaces, or support formatting at all.

LBA formats using a non-zero metadata size are not supported by nvmeadm or nvme(7D).

The list of supported LBA formats on a namespace can be retrieved with the nvmeadm identify command.

nvmeadm secure-erase ctl[/ns] [-c]
Erases the specified namespace or all namespaces of the controller. The flag -c will cause a cryptographic erase instead of a normal erase. This command implies a nvmeadm detach and nvmeadm attach of the specified namespace(s).

Note that not all devices support erasing individual or all namespaces, or support erasing at all.

nvmeadm detach ctl[/ns]
Temporarily detaches the blkdev(7D) instance from the specified namespace or all namespaces of the controller. This will prevent I/O access to the affected namespace(s). Detach will only succeed if the affected namespace(s) are not currently opened. The detached state will not persist across reboots or reloads of the nvme(7D) driver.
nvmeadm attach ctl[/ns]
Attaches the blkdev(7D) instance to the specified namespace or all namespaces of the controller. This will make I/O accesses to the namespace(s) possible again after a previous nvmeadm detach command.
nvmeadm load-firmware ctl firmware-file [offset]
Loads firmware-file into the controller's upload memory at offset, the default is 0. A vendor may require multiple files to be loaded at different offsets before the firmware is committed to a slot.
nvmeadm commit-firmware ctl slot
Commits firmware previously loaded by the load-firmware command to slot.
nvmeadm activate-firmware ctl slot
Activates the firmware in slot slot. The firmware image in slot is activated at the next NVM controller reset.

The nvmeadm utility exits 0 on success, and >0 if an error occurs.

Example 1: List all NVMe controllers and namespaces
# nvmeadm list
nvme1: model: INTEL SSDPEDMD800G4, serial: CVFT4134001R800CGN, FW rev: 8DV10049, NVMe v1.0
  nvme1/1 (c1t1d0): Size = 763097 MB, Capacity = 763097 MB, Used = 763097 MB
nvme4: model: SAMSUNG MZVPV128HDGM-00000, serial: S1XVNYAGA00640, FW rev: BXW7300Q, NVMe v1.1
  nvme4/1 (c2t2d0): Size = 122104 MB, Capacity = 122104 MB, Used = 5127 MB
    
Example 2: Identify a namespace
# nvmeadm identify nvme4/1
nvme4/1: Identify Namespace
  Namespace Capabilities and Features
    Namespace Size:                         122104MB
    Namespace Capacity:                     122104MB
    Namespace Utilization:                  5127MB
    Namespace Features
      Thin Provisioning:                    unsupported
    Number of LBA Formats:                  1
    Formatted LBA Size
      LBA Format:                           1
      Extended Data LBA:                    no
    Metadata Capabilities
      Extended Data LBA:                    unsupported
      Separate Metadata:                    unsupported
    End-to-End Data Protection Capabilities
      Protection Information Type 1:        unsupported
      Protection Information Type 2:        unsupported
      Protection Information Type 3:        unsupported
      Protection Information first:         unsupported
      Protection Information last:          unsupported
    End-to-End Data Protection Settings
      Protection Information:               disabled
      Protection Information in Metadata:   last 8 bytes
    LBA Format 1
      Metadata Size:                        0 bytes
      LBA Data Size:                        512 bytes
      Relative Performance:                 Best
    
Example 3: Get SMART/Health information (verbose)
# nvmeadm -v get-logpage nvme4/1 health
nvme4/1: SMART/Health Information
  Critical Warnings
    Available Space:                        OK
    Temperature:                            OK
    Device Reliability:                     OK
    Media:                                  OK
    Volatile Memory Backup:                 OK
  Temperature:                              37C
  Available Spare Capacity:                 100%
  Available Spare Threshold:                10%
  Device Life Used:                         0%
  Data Read:                                0GB
  Data Written:                             64GB
  Read Commands:                            52907
  Write Commands:                           567874
  Controller Busy:                          1min
  Power Cycles:                             6
  Power On:                                 141h
  Unsafe Shutdowns:                         1
  Uncorrectable Media Errors:               0
  Errors Logged:                            1
    
Example 4: Get Asynchronous Event Configuration information
# nvmeadm get-features nvme0,nvme4 event,power
nvme0: Get Features
  Asynchronous Event Configuration
    Available Space below threshold:        disabled
    Temperature above threshold:            disabled
    Device Reliability compromised:         disabled
    Media read-only:                        disabled
  Power Management
    Power State:                            0
nvme4: Get Features
  Asynchronous Event Configuration
    Available Space below threshold:        disabled
    Temperature above threshold:            disabled
    Device Reliability compromised:         disabled
    Media read-only:                        disabled
    Volatile Memory Backup failed:          disabled
  Power Management
    Power State:                            0
    
Example 5: Load and activate firmware
# nvmeadm get-logpage nvme3 firmware
nvme3: Firmware Slot Information
  Active Firmware Slot:                     4
  Next Firmware Slot:                       4
  Firmware Revision for Slot 1:             KNGND110
  Firmware Revision for Slot 2:             KNGND110
  Firmware Revision for Slot 3:             KNGND110
  Firmware Revision for Slot 4:             KNGND112
  Firmware Revision for Slot 5:             KNGND110
  Firmware Revision for Slot 6:             <Unused>
  Firmware Revision for Slot 7:             <Unused>

# nvmeadm -v load-firmware nvme3 KNGND113.bin
1740544 bytes downloaded.

# nvmeadm -v commit-firmware nvme3 5
Firmware committed to slot 5.

# nvmeadm -v activate-firmware nvme3 5
Slot 5 activated: NVM subsystem reset required - power cycle your system.

# nvmeadm get-logpage nvme3 firmware
nvme3: Firmware Slot Information
  Active Firmware Slot:                     4
  Next Firmware Slot:                       5
  Firmware Revision for Slot 1:             KNGND110
  Firmware Revision for Slot 2:             KNGND110
  Firmware Revision for Slot 3:             KNGND110
  Firmware Revision for Slot 4:             KNGND112
  Firmware Revision for Slot 5:             KNGND113
  Firmware Revision for Slot 6:             <Unused>
  Firmware Revision for Slot 7:             <Unused>
    

The command line interface of nvmeadm is Evolving. The output of nvmeadm is Not-an-Interface and may change any time.

nvme(7D)

NVMe specifications

March 24, 2021 OmniOS