NVMEADM(8) Maintenance Commands and Procedures NVMEADM(8)
nvmeadm - NVMe administration utility
nvmeadm -h [command]
nvmeadm [-dv] list [-c | -L] [-p -o field[,...]] [ctl[/ns][,...]]
nvmeadm [-dv] identify [-C | -c | -d | [-a] -n] ctl[/ns][,...]
nvmeadm [-dv] identify-controller [-C | -c | [-a] -n] ctl[,...]
nvmeadm [-dv] identify-namespace [-c | -d] ctl/ns[,...]
nvmeadm [-dv] list-logpages [-a] [-H] [-o field[,...] [-p]]
[-s scope[,...]] ctl[/ns][,...] [logpage...]
nvmeadm [-dv] get-logpage [-O output-file | -x |
-p -o field[,...] [-H]] ctl[/ns][,...] logpage [filter...]
nvmeadm [-dv] print-logpage -f file [-x | -p -o field[,...] [-H]]
logpage [filter...]
nvmeadm [-dv] list-features [-a] [-H] [-o field[,...] [-p]]
ctl[/ns][,...] [feature...]
nvmeadm [-dv] get-features ctl[/ns][,...] [feature-list]
nvmeadm [-dv] format ctl[/ns] [lba-format]
nvmeadm [-dv] secure-erase [-c] ctl[/ns]
nvmeadm [-dv] create-namespace -b block-size | -f flbas [-c cap]
[-n nmic] [-t type] ctl size
nvmeadm [-dv] delete-namespace ctl/ns
nvmeadm [-dv] attach-namespace ctl/ns
nvmeadm [-dv] detach-namespace ctl/ns
nvmeadm [-dv] attach ctl[/ns]
nvmeadm [-dv] detach ctl[/ns]
nvmeadm [-dv] list-firmware ctl
nvmeadm [-dv] load-firmware ctl firmware-file [offset]
nvmeadm [-dv] commit-firmware ctl slot
nvmeadm [-dv] activate-firmware ctl slot
nvmeadm [-dv] measure-phyeye -o output [-Q good | better | best] ctl
nvmeadm [-dv] report-phyeye -f file [-l lane] [-e eye] [-m mode]
nvmeadm [-dv] vendor-cmd -O opcode [-n nsid] [--cdw12 cdw12]
[--cdw13 cdw13] [--cdw14 cdw14] [--cdw15 cdw15]
[-l length [-i file | -o file]] [-L lock] [-I impact[,...]]
[-t timeout] ctl[/ns]
nvmeadm [-dv] sandisk/hwrev ctl
nvmeadm [-dv] sandisk/pci-eye -l lane -o output ctl
nvmeadm [-dv] wdc/e6dump -o output ctl
nvmeadm [-dv] wdc/resize -s size | -g ctl
nvmeadm [-dv] wdc/clear-assert ctl
nvmeadm [-dv] wdc/inject-assert ctl
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:
-h Print a short help text for nvmeadm, or for an optionally
specified nvmeadm command.
-d Enable debugging output.
-v 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 "/" to the controller name,
followed by either the namespace ID or the namespace EUI64 or
NGUID as reported by the identify command. The namespace ID
is a positive non-zero decimal number. 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 and
print-logpage command. Valid names are listed in the
discussion of the get-logpage command below. Log pages both
the system and controller support can be determined with the
list-logpages command.
filter Various commands take a filter to print out portions of a
data structure such as a log page. A filter is a series of
dot delineated (".") strings that define which portion of the
data structure to list. Short names for fields come from the
relevant NVMe specifications and are treated as a committed
interface (aliases will be provided in the face of changes in
the spec).
The matching behavior varies between parsable and non-
parsable output. Consider the filter "eom.od.pefp". This
prints the Printable Eye Field Present member, from the
Optional Data Present Field, from the EOM Header that is part
of the phyeye log page. In non-parsable mode, the filter
"eom" would match the entire contents of the EOM header.
However, in parsable mode, only an exact match fires to
ensure that the contents are stable across changes to the
specification which add members to reserved fields.
When using filters, the program will exit non-zero if any
filter does not match.
feature-list
A comma-separated list of feature names for the get-features
command. Feature names can be specified in upper or lower
case. All features can be specified either by a short name
listed below or by the full name that the specification uses.
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
output-file
Specifies a file system location to write raw binary data out
to. 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.
scope Specifies the scope of a given type of thing to look at, such
as a log page. Scopes can either be specified by their full
name or a shortened form. For log pages, the following
scopes are supported:
controller
Indicates that the log is scoped to the controller.
The short form is "ctrl".
nvm Indicates that the log is scoped to the NVM
subsystem. There is no short form.
namespace
Indicates that the log is scoped to the namespace.
The short form is "ns".
For more information on the differences between these, please
see the NVMe specification.
size Indicates a size in bytes. The size may be specified in base
10 or in hexadecimal. An optional binary prefix may follow
the string. For example, a size of 10G would indicate 10 GiB
(Gibibytes) or 10,737,418,240 bytes. Valid binary prefixes
include:
b, B The size is in bytes. It is not adjusted.
k, K The size is in KiB. It will be multiplied by 2^10.
m, M The size is in MiB. It will be multiplied by 2^20.
g, G The size is in GiB. It will be multiplied by 2^30.
t, T The size is in TiB. It will be multiplied by 2^40.
p, P The size is in PiB. It will be multiplied by 2^50.
This is used by the create-namespace command.
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 the nvmeadm list-firmware
command.
nvmeadm list [-c | -L] [-p -o field[,...]] [ctl[/ns][,...]]
Lists the NVMe controllers and by default also their active
namespaces, printing 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. If no controllers or namespaces
are given as arguments, then all controllers in the system and their
respective active namespaces are listed. When using the -v option to
nvmeadm, all possible namespaces of the controllers will be listed.
The nvmeadm list command supports the following options:
-c List controllers only and not their namespaces.
-L List information about controller location and
controlling attachment points.
-p Produce parsable output rather than human-readable
output. This option requires that output fields be
selected with the -o option.
-o 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.
INSTANCE The name of the device node and instance of it.
CTRLPATH The /devices path of the controller.
In addition, the following fields can be specified when listing
namespaces, not using the -c option:
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.
SIZE The logical size in bytes of the namespace.
USED The number of bytes used in the namespace.
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.
NS-STATE The current state of the namespace. This is one of the
following:
"unallocated"
the namesapce is currently unallocated. There
is no non-volatile memory assosciated with it.
"allocated"
The namespace has non-volatile memory allocated
to it, but it is not currently attached to the
controller.
"active"
The namespace is currently attached to the local
controller; however, the kernel cannot actively
attach a block device to the driver.
"active-usable"
The namespace is currently attached to the local
controller and the kernel can use the namespace
with blkdev(4D).
"blkdev"
The namespace is exposing a block device and is
actively attached to blkdev(4D).
FORMAT The current LBA format of the namespace printed as a
string comprised of the data section and the metadata
section generally structured as `data+meta'. For
example, a 4K formatted namespace with no metadata
sectors would be shown as `4096+0'. A 512-byte
formatted namespace with 16 bytes of metadata (perhaps
for end-to-end data protection) would be formatted as
`4096+16'.
FMTID The numerical ID of the namespace's LBA format. This
may be used as the lba-format argument to the format
subcommand.
FMTDS The data size, in bytes, of the namespace's LBA format.
FMTMS The metadata size, in bytes, of the namespace's LBA
format.
When using the -c or -L option to list controllers, the following
additional fields are supported:
CAPACITY The total raw capacity of the NVMe controller in bytes.
UNALLOCATED The number of bytes not currently assigned to any
namespace in the controller.
When using the -L option, the following additional fields are
supported:
LOCATION A string that indicates its physical location, derived from
system topology.
CTLAP The name of the parent attachment point, if any, that
controls this device. Usable with cfgadm(8).
nvmeadm identify-controller [-C | -c | [-a] -n] ctl[,...]
Print detailed information about the specified controllers. For an
explanation of the data printed by this command refer to the
description of the "IDENTIFY" admin command in the NVMe
specification.
By default, a relevant subset of the "IDENTIFY CONTROLLER" data
structure is printed. The full data structure is only printed when
verbose output is requested.
The following options can be used to print other "IDENTIFY"
information:
-C Print the Common Namespace Identification of the
controller.
-a Alter the output of the -n option to print the list
allocated namespace identifiers. Can only be specified
together with the -n option.
-c Print the list of all unique controller identifiers in
the NVMe subsystem the specified controller belongs to.
-n Print the list of active namespace identifiers of the
controller.
nvmeadm identify-namespace [-c | -d] ctl/ns[,...]
Print detailed information about the specified namespace. For an
explanation of the data printed by this command refer to the
description of the "IDENTIFY" admin command in the NVMe
specification.
By default, a relevant subset of the "IDENTIFY NAMESPACE" data
structure is printed. The full data structure is only printed when
verbose output is requested.
The following options can be used to print other "IDENTIFY"
information:
-c Print the list of all unique controller identifiers in
the NVMe subsystem the specified namespace belongs to and
which are currently attached to this namespace.
-d Print the list of namespace identification descriptors of
the namespace.
nvmeadm identify [-C | -c | -d | [-a] -n] ctl[/ns][,...]
Short-hand for the identify-controller and identify-namespace
commands, prints the same information about the specified controllers
and/or namespaces, depending on whether a controller or a namespace
was specified.
For a description of the various optional flags refer to the above
description of the identify-controller and identify-namespace
commands.
nvmeadm [-dv] list-logpages [-a] [-H] [-o field[,...] [-p]] [-s
scope[,...]] ctl[/ns][,...] [logpage...]
Prints the list of log pages and information about them specific to
the given controller or namespace. This is intended as a discovery
mechanism and will print information about mandatory, optional, and
vendor-specific log pages as well as all the information that is
useful for retrieving information about them.
The nvmeadm list-logpages command supports the following options:
-a Print all log pages. By default, only logs that are
implemented are printed.
-H Omit the output header columns.
-o field[,...]
A comma-separated list of one or more output fields to be
used. Fields are listed below and the name is case
insensitive.
-p Produce parsable output rather than human-readable
output. This option requires that output fields be
selected with the -o option.
-s scope[,...]
Print log pages that match the specified scope. If no
scope arguments are specified, then the scope will be set
to "ctrl,nvm" when the device is a controller and "ns"
when the device refers to a namespace.
The following fields are supported:
DEVICE Prints the name of the controller or namespace.
NAME Prints the name of the log page. This is the name that can
be used to get the log page with the get-logpage command.
This is a shortened form from the NVMe or vendor-specific
documentation.
DESC This is a description of the log page and generally
corresponds to information from the specification the log
page is drawn from.
SCOPE This is the set of scopes that the log page is applicable
to. As described earlier in the manual, valid scopes
include "ctrl", "nvm", and "ns". This indicates whether a
controller ("ctrl" and "nvm") or a namespace ("ns") will
work for this log page when running the get-logpage command
to get the log.
FIELDS This indicates the command fields that are accepted when
retrieving the log page from the controller. The fields
include:
lsp Indicates that a log specific parameter is accepted for
this page.
lsi Indicates that a log specific identifier is accepted
for this page.
rae Indicates that one can control whether or not an
asynchronous event is retained when retrieving the log
page. By default, asynchronous events are cleared when
certain log pages are fetched such as the health log
page.
For more information on these fields, please see the NVMe
specification.
CSI Indicates the log page's command set interface.
LID Indicates the log page's numeric ID. This when combined
with the log page's CSI is the unique identifier that
identifies the log page to the controller.
IMPL Indicates whether or not the system believes that the log
page is implemented.
SIZE Indicates the size of the log page. Not all log pages have
a fixed size and in such cases this field will not contain a
value.
MINSIZE When a log page is known to have a variable size, this
indicates the minimum amount of the log page to read to
determine the full size of the log page.
SOURCES This is a comma separated list of values that indicates
where information about this log page and its support came
from primarily. These include the following:
"spec" This comes from the NVMe specification.
Generally this refers to mandatory log
pages that are not dependent on any
information in the identify controller
data structure.
"identify-controller"
Information about this log page comes
from the identify controller data
structure. Many log pages are
described by the standard but are
optional and their support is indicated
through that.
"internal-db" This indicates that information about
this log page comes from our internal
databases in libnvme. Most vendor-
specific logs are described in
datasheets whose information is encoded
into the library and system and there
is not always a way to discover that it
is supported or not.
"command" This indicates that information about
this log page came from another command
that was issued to the controller which
indicates what was implemented and
present.
KIND This indicates the kind of log page that this is. Valid
options are:
"mandatory" Indicates that the NVMe specification
considers this mandatory for all
controllers of a given version.
"optional" Indicates that the NVMe specification
considers this log page optional. Some
items may be mandatory if a device
implements an optional feature like
namespace management, but they will still
be considered optional as the underlying
feature is.
"vendor-specific"
Indicates that this log is a vendor-
specific log page. These log pages are not
part of the NVMe standard and are generally
described in their own device's datasheets
or a separate standard such as the OCP
Datacenter NVMe SSD Specification.
The list-logpages command supports a series of operands which can be
used to filter the list of log pages that information is printed out
about. Each logpage operand is the name of a log page. Only
matching log pages will be printed and if no log pages match a given
operand argument or not log pages are printed at all (which can
happen due to a log being unsupported) then the command will generate
an error.
nvmeadm get-logpage -O output-file | -x | -p -o field[,...] [-H]
ctl[/ns][,...] logpage [filter...]
Print the specified log page of the specified controllers and/or
namespaces.
The nvmeadm get-logpage command supports the following options:
-H Omit the output header columns when using parsable
output.
-O output-file
Write the raw contents of the binary payload to
output-file. Its contents will not be interpreted or
printed out otherwise. Filters may not be used when
writing raw data out.
-o field[,...]
A comma-separated list of one or more output fields to be
used. Fields are listed below and the name is case
insensitive.
-p Produce parsable output rather than human-readable
output. This option requires that output fields be
selected with the -o option.
-x Print the raw output of logpage as a series of human-
readable hexadecimal output with the log page address and
ASCII decoding. Filters may not be used with the -x
option.
The following fields are supported:
SHORT This is the full dot-delineated short name that refers to a
specific field in a log page. For items from the NVMe
specification, this is the field's abbreviation found in the
specification. The short form is used in filters and its
value is considered a committed interface.
DESC This is a description of a field for a log page. This value
comes from the NVMe specification or vendor specification.
The description string for a field may change over time.
VALUE This is the underlying binary value found inside of a log
page's field printed in hexadecimal. The value is not
interpreted or adjusted. For example, many values in the
NVMe specification are 0s based values, meaning to get the
actual value one has to add one to it.
HUMAN This is a human-readable version of the field's value. The
human-readable output of a field may change over time due to
changes in the specification, bugs, or improvements to
nvmeadm.
OFFSET This is the offset to the start of the field in bytes. The
additional sub-byte bit offset to the start of the field is
communicated with the BITOFF field.
BITOFF This is the additional offset to the start of the field in
bits. This field will only ever be in the range of 0-7 and
must be combined with the OFFSET field to get the total
length.
LENGTH This is the length of the field in bytes. The additional
sub-byte bit length is communicated with the BITOFF field.
BITLEN This is the additional length of the field in bits. This
field will only ever be in the range of 0-7 and must be
combined with the LENGTH field to get the total length.
Most log pages are only available on a per-controller basis. For an
explanation of the contents of the log pages refer to the description
of the "GET LOGPAGE" admin command in the NVMe specification.
One or more filter operands may be supplied to a subset of log pages.
These filters will limit the fields that are printed in both parsable
and human-readable mode. Log pages the system does not know how to
decode are printed in a hexadecimal dump and filters are not
supported.
Known log pages are:
suplog Supported Log Pages. Lists information about log pages
that the device supports. Available starting in NVMe 2.0
devices.
error Error Information
health SMART/Health Information. A controller may support this
log page on a per-namespace basis.
firmware Firmware Slot Information
changens Changed Namespaces.
supcmd Commands Supported and Effects. An optional log page
added in NVMe 1.2 that indicates what commands the
controller itself actually supports.
pev Persistent Event Log. An optional log page added in NVMe
1.4 that contains a series of events that have occurred on
the device.
telemetry Host-initiated telemetry log. Contains vendor-specific
diagnostic information about the controller. This log
page requires that the -O option be specified.
supfeat Feature Identifiers Supported and Effects. A mandatory
log page added in NVMe 2.0 that indicates which features
are supported and their corresponding effects.
supmicmd NVMe-MI Commands Supported and Effects. A mandatory log
page added in NVMe 2.0 that indicates which management
interface commands are supported and their corresponding
effects.
phyeye Physical Interface Receiver Eye Opening Measurement. An
optional log page that provides a way of measuring the eye
of the controller's PHY, generally meaning all lanes of a
PCIe device. See the measure-phyeye and report-phyeye
commands for specialized subcommands dedicated to this.
The following vendor-specific log pages are supported. Not all
devices from a vendor support every log page. Use the list-logpages
command to determine which are supported for a given device and
whether they operate on a controller or namespace.
kioxia/extsmart Kioxia Extended SMART.
micron/smart Micron Vendor Unique SMART.
micron/extsmart Micron Extended SMART.
ocp/smart Open Compute Datacenter NVMe SSD specification
SMART / Health information.
ocp/errrec Open Compute Datacenter NVMe SSD specification
error recovery log.
ocp/fwact Open Compute Datacenter NVMe SSD specification
firmware activation log.
ocp/latency Open Compute Datacenter NVMe SSD specification
latency monitor.
ocp/devcap Open Compute Datacenter NVMe SSD specification
device capabilities.
ocp/unsup Open Compute Datacenter NVMe SSD specification
unsupported requirements.
solidigm/rlat Solidigm/Intel read command latency statistics.
solidigm/wlat Solidigm/Intel write command latency statistics.
solidigm/temp Solidigm/Intel temperature statistics.
solidigm/smart Solidigm/Intel vendor unique SMART log.
solidigm/ioqueue Solidigm/Intel I/O queue metrics.
solidigm/name Solidigm/Intel drive marketing name.
solidigm/power Solidigm/Intel power usage.
solidigm/gc Solidigm/Intel garbage collection.
solidigm/outlier Solidigm/Intel latency outlier.
wdc/eol Western Digital end-of-life.
wdc/devmgmt Western Digital device manageability.
wdc/pciesi Western Digital PCIe signal integrity.
wdc/power Western Digital power samples.
wdc/temp Western Digital temperature samples.
wdc/fwact Western Digital firmware activation history.
wdc/ccds Western Digital CCDS build information.
wdc/cusmart Western Digital customer unique SMART data.
nvmeadm print-logpage -f file [-x | -p -o field[,...] [-H]] logpage
[filter...]
Print and decode the specified log page contents from a file. Where
the get-logpage command retrieves an individual log page from a
device, the print-logpage instead reads log page data from an input
file file, but otherwise provides the same decoding and filtering
capabilities. This allows a log page to be interpreted multiple
times without asking for the controller for a fresh copy and allows
log pages from remote hosts to be processed locally. To capture the
binary log file use nvmeadm get-logpage -O.
The nvmeadm print-logpage command supports the following options:
-f file Read the log page contents from the specified file. This
option is required.
-H Omit the output header columns when using parsable
output.
-o field[,...]
A comma-separated list of one or more output fields to be
used. Fields are listed below and the name is case
insensitive.
-p Produce parsable output rather than human-readable
output. This option requires that output fields be
selected with the -o option.
-x Print the raw output of logpage as a series of human-
readable hexadecimal output with the log page address and
ASCII decoding. Filters and parsable output may not be
used with the -x option.
The print-logpage command supports the same fields, filters, and log
page names as the get-logpage command. See Examples.
nvmeadm list-features [-a] [-H] [-o field[,...] [-p]] ctl[/ns][,...]
[feature[,...]]
Prints the list of features and information about them specific to
the given controller or namespace. This is intended as a discovery
mechanism and will print information about known mandatory, optional,
and vendor-specific features as well as the information that is
useful for retrieving information about them.
The nvmeadm list-features command supports the following options:
-a Print all features, regardless of whether or not the
controller is known to implement them. By default
unimplemented features are not printed, but implemented
and unknown ones are.
-H Omit the output header columns.
-o field[,...]
A comma-separated list of one or more output fields to be
used. Fields are listed below and the name is case
insensitive.
-p Produce parsable output rather than human-readable
output. This option requires that output fields be
selected with the -o option.
The following fields are supported:
DEVICE Prints the name of the controller or namespace.
SHORT This is a shortened name for a feature which can be used to
identify it. These short names are unique to illumos and
not part of the NVMe specification.
SPEC This is the specification's name for a given feature.
FID This is the numeric ID that can be used to uniquely identify
a feature.
SCOPE This is a comma separated list of values that identifies
what scopes this feature covers. The supported scopes are
"controller", which indicates that it impacts the entire
controller and "namespace", which indicates that it impacts
just a single namespace.
KIND This indicates the kind of feature that this is. Valid
options are:
"mandatory" Indicates that the NVMe specification
considers this mandatory for all
controllers of a given version.
"optional" Indicates that the NVMe specification
considers this feature optional. Some
items may be mandatory if a device
implements an optional feature like
namespace management, but they will still
be considered optional as the underlying
feature is.
"vendor-specific"
Indicates that this log is a vendor-
specific feature. These features are not
part of the NVMe standard and are generally
described in their own device's datasheets
or a separate standard such as the OCP
Datacenter NVMe SSD Specification.
CSI The command set interface that the feature is specific to.
Most features are not specific to a CSI.
FLAGS The flags are a series of comma separated strings which
describe properties of the feature. The following flags are
currently supported:
"get-bcastns"
Indicates that the broadcast namespace is
supported when getting this feature.
"set-bcastns"
Indicates that the broadcast namespace is
supported when setting this feature. Using the
broadcast namespace indicates that all
namespace are impacted.
GET-IN A series of comma separated values indicating what is
required to get this feature. The following values are
supported:
cdw11 Indicates that the feature requires an argument in
the cdw11 field of the command. This is generally a
selector of some kind. For example, for the
temperature threshold feature, it selects which of
several sensors may be referred to.
data Indicates that a data buffer is required when getting
this feature. Its size is indicated by the DATALEN
field.
nsid Indicates that a namespace ID is required when
getting this feature.
SET-IN A series of comma separated values indicating what is
required to get this feature. The following values are
supported:
cdw11 Indicates that the feature uses information in cdw11
to set the feature.
cdw12 Indicates that the feature uses information in cdw12
to set the feature.
cdw13 Indicates that the feature uses information in cdw13
to set the feature.
cdw14 Indicates that the feature uses information in cdw14
to set the feature.
cdw15 Indicates that the feature uses information in cdw15
to set the feature.
data Indicates that the feature takes a data payload to
set the feature. Its size is indicated by the
DATALEN field.
nsid Indicates that the feature requires a valid namespace
identifier.
GET-OUT A series of comma separated values indicating what the
controller will return information about this feature in.
The following values are supported:
cdw0 Indicates that the controller will give information
about the feature in the command output 32-bit value.
data Indicates that the controller will output information
about the feature into the output buffer.
SET-OUT A series of comma separated values indicating what the
controller will update following the successful completion
of setting the feature. These values are the same as with
the GET-OUT field.
DATALEN Indicates the length of data for the feature.
IMPL Indicates whether or not the feature is known to be
implemented or not. The following values are possible:
"unknown"
Indicates that it is unknown as to whether or not
the feature is implemented. Some features are
optional and there is no way to determine this
short of issuing an attempt to get the feature
itself.
"yes" Indicates that we know the feature is implemented
by the controller.
"no" Indicates that we know the feature is not
implemented by the controller.
The list-features command supports a series of operands which can be
used to filter the list of features that information is printed out
about. Each feature operand is either the short name or the
specification's name for a given feature. In addition, the numeric
feature ID can also be used as a filter. If no features match a
given operand or no features are printed at all then the command will
generate an error.
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 arb controller
Power Management pm controller
LBA Range Type range namespace
Temperature Threshold temp controller
Error Recovery errec 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 apst controller
Software Progress Marker progress controller
Host Behavior Support hostsup 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(4D).
The list of supported LBA formats on a namespace can be retrieved
with the nvmeadm identify command.
nvmeadm secure-erase [-c] ctl[/ns]
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 create-namespace -b block-size | -f flbas [-c cap] [-n nmic]
[-t type] ctl size
Creates a new namespace of size size in the controller ctl. NVM will
be allocated for the namespace and the namespace will transition to
the allocated state. A created namespace must subsequently be
attached to the local controller, attach-namespace, and to the block
device framework (blkdev(4D)), attach, to provide I/O capabilities.
By default, a newly created namespace:
+o Uses the NVM command set interface (CSI). This can be changed
with the -t option.
+o Has the namespace's capacity set to the namespace's size. To
thinly provision a namespace, you may use the -c option to
specify a value less than the size argument. Note, the
controller may not support thin provisioning.
+o Configures the namespace so it may only be used with one
controller at a time. This can be changed with the -n option.
When creating a namespace, one must specify what formatted LBA index
to use. This index may be specified directly with the -f option or
instead the target block size may be specified with the -b option.
If -b is specified, then the command will search for a namespace with
that block size, with no metdata section, and with the highest
relative performance and use that. Available LBA format options may
be listed by printing the Common Namespace Identification values
through the identify-controller option with the -C option.
The create-namespace command supports the following options:
-b block-size
Specifies the target data block size of the namespace to
be created. This option is exclusive with the -f option.
block-size allow a binary prefix to be specified as per
the description of the size operand.
-c cap Specifies the namespace's capacity in bytes, which may
use a binary prefix like, such as 100G, as per the
description of the size operand. If this option is left
out, the namespace's capacity will be set to its size,
fully provisioning the namespace. Not all controllers
support thinly provisioning a namespace.
-f flbas Specifies the index of the formatted LBA size.
-n nmic Specifies the multipath I/O and namespace sharing
capabilities. The current valid options for this are:
none Indicates that only a single controller may
attach to the namespace at any given time.
shared Indicates that two or more controllers may attach
to the namespace at the same time.
-t type Specifies the command set interface for newly created
namespace. The default is "nvm". The system understands
the following command set interfaces; however, not all
controllers support all CSIs and currently the nvme(4D)
driver only supports the NVM CSI.
nvm The non-volatile memory CSI. This is the default
CSI of all NVMe devices and provides a regular
block interface.
kv Key Value command set interface. This interface
does not provide standard a logical block
abstraction and instead allows for someone to
read and write an arbitrary-sized object with a
128-bit key.
zns Zoned namespace command set interface. This
interface provides a block-like abstraction where
blocks are broken into different sized zones,
which contain ranges of logical blocks. Writing
to a zone offers different semantics from a
common block device.
nvmeadm delete-namespace ctl/ns
This deletes the specified namespace, freeing any capacity back to
the underlying NVM subsystem. The namespace identifier will be
considered inactive in ctl.
To delete a namespace, the namespace must already be detached from
all controllers through the detach-namespace command.
Upon deleting a namespace, all information that was contained in the
namespace will be lost.
nvmeadm attach-namespace ctl/ns
Attach the specified namespace to the controller ctl. This will
transition the namespace to the active state, allowing additional
information about the namespace to be queried. This also allows the
namespace to provide a block device interface through blkdev(4D),
which can be enabled by subsequently using the attach command.
nvmeadm detach-namespace ctl/ns
Detach the specified namespace from the controller ctl. The
namespace must already be detached from blkdev(4D) through the detach
command. When detached, the namespace transitions from active to
allocated in the controller. Data in the namespace remains valid;
however, not all commands will function against the namespace and I/O
may not be performed to it.
nvmeadm attach ctl[/ns]
Attaches the blkdev(4D) 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.
It is not an error to attach a namespace that is already attached,
any such request will be silently ignored.
nvmeadm detach ctl[/ns]
Temporarily detaches the blkdev(4D) 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(4D) driver.
It is not an error to detach a namespace that is already detached,
any such request will be silently ignored.
nvmeadm list-firmware ctl
List currently active firmware slot, the next active firmware slot,
and the current contents of all firmware slots of an NVMe controller.
This is a synonym for the nvmeadm get-logpage ctl firmware 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.
nvmeadm measure-phyeye -o output [-Q good | better | best] ctl
Perform a measurement of the physical interface's eye opening on the
specified controller, ctl, and write the resulting measurement to
output. The output file will be a version of the "phyeye" log page
whose contents can be interpreted with the report-phyeye and
print-logpage commands.
The quality of the log page may be one of "good", "better", or
"best", which are levels described by the NVMe over PCIe Transport
Specification. The higher the quality, the longer the measurement
will take, but the more accurate it will be.
When the measurement is initiated, no additional administrative
commands will be allowed on the device, though any active blkdev(4D)
devices will still be active. It is recommended I/O be quiesced
during the entire measurement period. The command will wait for the
device's recommended time, potentially 5-10 minutes, before it
queries the device for completeness.
The following options are supported:
-o Write the contents of the physical eye measurement to output.
-Q Specify the quality of the measurement. The default quality
when none is specified is best. The following quality levels
are supported: "good", "better", and "best".
nvmeadm report-phyeye -f file [-l lane] [-e eye] [-m mode]
Report the printable eye data or the vendor-specific eye data from a
physical eye measurement contained in file.
The following options are supported:
-f file
Read the physical eye measurement contents from file. This
should be gathered with the measure-phyeye command.
-l lane
Limit information printed to the specified PCIe device lane.
PCIe lanes are numbered starting at 0. Most NVMe devices
only have 4 lanes.
-e eye Limit information printed to the specified device eye. The
number of eyes present generally depends on the PCIe speed of
the device. There will only be a single eye for PCIe devices
running at Gen 5 or below. PCIe Gen 6 and higher devices
should have 3 eyes due to the use of PAM4 encoding.
-m mode
Selects the type of data that will be printed, defaulting to
print-eye if not specified. Valid modes are:
eye-data
Print the optional, vendor-specific eye-data. This
will generally be printed as a hexadecimal dump
unless vendor-specific knowledge of how to decode it
is present.
print-eye
Print the optional, ASCII printable eye. A 0 in the
printable eye indicates that the position is on or
inside of the eye. A 1 in the printable eye
indicates that the position is outside of the eye.
This cannot be translated into specific values
without vendor-specific information.
nvmeadm vendor-cmd -O opcode [-n nsid] [--cdw12 cdw12] [--cdw13 cdw13]
[--cdw14 cdw14] [--cdw15 cdw15] [-l length [-i file | -o file]] [-L
lock] [-I impact[,...]] [-t timeout] ctl[/ns]
This allows an administrator to send a vendor-specific command to a
device that supports the NVMe standard vendor specific command
format. Vendor-specific commands must be used carefully. While the
system attempts to first class many commands so that way we can
ensure that anything that causes confusion to the device is well
understood, this cannot be done for arbitrary commands. It is the
user's responsibility to understand if this can cause the controller
to lose data, interact poorly with the kernel leading to the driver
being out of sync with reality, or worse. The only required argument
for this is an operation code which must be in the vendor-specific
region.
The command may be run against either a controller or a namespace.
When a namespace is specified, its namespace id is included in the
command.
A command may optionally request that data be sent to the controller
as an input to the command (-i), or returned by the controller as an
output from the command (-o). There is no support in the standard
protocol for both an arbitrary sized data input and output. The
length of the input is specified by the -l flag, which indicates a
size in bytes that must be a multiple of 4 (commands operate in units
of uint32_t). Data is either read from or output to a file. The
maximum input or output data size provided by the system is 16 MiB.
When the command completes, it will print out the results of the
command and the value of the completion command dword 0.
The following arguments are supported:
-O, --opcode opcode
Sets the numeric operation code that should be used for the
command. This option is required. Valid values are in the
range [0xc0, 0xff].
-n, ---nsid nsid
Sets the namespace identifier to send in the command to nsid.
If the command is specified against a namespace specifically,
then this argument is not required. If the nsid argument is
specified and a namespace is specified as the target, they
must agree otherwise it is an error.
If no namespace ID is specified, this field will be set to 0
in the command.
--cdw12, -2 cdw12
Sets the 32-bit value of command dword 12 to the value cdw12.
Whether or not this is required is command specific.
If no value is specified, this field will be set to 0 in the
command.
--cdw13, -3 cdw13
Sets the 32-bit value of command dword 13 to the value cdw13.
Whether or not this is required is command specific.
If no value is specified, this field will be set to 0 in the
command.
--cdw14, -4 cdw14
Sets the 32-bit value of command dword 14 to the value cdw14.
Whether or not this is required is command specific.
If no value is specified, this field will be set to 0 in the
command.
--cdw15, -5 cdw15
Sets the 32-bit value of command dword 15 to the value cdw15.
Whether or not this is required is command specific.
If no value is specified, this field will be set to 0 in the
command.
-l, --length length
Indicates the length in bytes of the desired input or output
for the command. The length must be 4-byte aligned. If this
is specified, one of -i or -o must be specified to indicate
the direction of the data transfer and the source or
destination of the data.
-i, --input file
Read the input to the command from file. Requires that -l is
specified. If the input file, file, is shorter than the
length specified with -l, then the remaining data will be
filled with 0s.
-o, --output file
Write controller output to file. Requires that -l is
specified.
-L, ---lock lock
Allows for a read or write lock on the controller (or
namespace) to be taken for the duration of the command. The
following values are supported for lock:
read Takes a read lock on the controller Pq or namespace .
I/O will still continue during this time. This
prevents other operations from modifying the state of
the controller or namespace such as performing a
format, firmware update, etc.
write Takes an exclusive write lock on the controller. I/O
will still continue during this; however, no other
administrative actions will be allowed during this
time including read-only commands.
-I, --impact impact[,...]
A comma-separated list of values that describe to the system
the impact of running this command on the system. By
default, no impact to the system is assumed. The following
values are accepted:
data Indicates that the data on the controller or
namespace may be lost as a result of running this
command.
namespace Indicates that namespaces and their attributes may
be modified as a result of running this command.
-t, --timeout timeout
All administrative commands are monitored by the system to
ensure that they complete in a timely fashion. By default a
60 second timeout is applied to all administrative commands.
This may be overridden by specifying a new timeout value
which will be interpreted in seconds.
nvmeadm sandisk/hwrev ctl
This vendor-specific command prints the device hardware revision.
nvmeadm sandisk/pci-eye -l lane -o output ctl
This vendor-specific command obtains a PCIe eye diagram for the
hardware lane specified by lane on the NVMe device ctl. The PCIe
lane will generally be between 0 and 3, though it is possible fewer
lanes will be available depending on the drive bay and system board
design. The information will be output to the file output.
nvmeadm wdc/e6dump -o output ctl
This vendor-specific command performs a diagnostic dump of device
data to the file specified by output. The device remains in full
service while this is occurring.
nvmeadm wdc/resize -s size | -g ctl
This vendor-specific command will get the current over provisioning
size or set it. This command operates using power of 10 bytes, that
is in terms of gigabytes and not gibibytes. The sizes that are used
here will be different from those that the operating system will
report for the drive.
The following options are supported:
-g Returns the current size of the device in gigabytes
(powers of 10).
-s size Sets the size of the device to size which is in gigabytes
(powers of 10). This can be used to adjust the over
provisioning ratio on the device. The valid points are
device-specific. Please consult WDC datasheets for more
information.
When performing a resize all data and namespace will be
erased! All namespaces must be detached prior to issuing
this.
nvmeadm [-dv] wdc/clear-assert ctl
This clears an internal assertion record from a WDC device. Prior to
running this any such internal assertion should be saved by using the
wdc/e6dump command. This command should only be used if instructed
to do so as part of a troubleshooting process.
nvmeadm [-dv] wdc/inject-assert ctl
This injects a device assertion into a WDC NVMe device. The behavior
of doing so is device specific; however, all I/O will be interrupted
and the device may be retired. Unless explicitly instructed as part
of debugging a device or as part of internal development, this
command should not be used.
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 list-firmware nvme3
nvme3: Firmware Slot Information
Active Firmware Slot: 4
Next Firmware Slot: 4
Firmware Revision for Slot 1: KNGND110 (read-only)
Firmware Revision for Slot 2: KNGND110
Firmware Revision for Slot 3: KNGND110
Firmware Revision for Slot 4: KNGND112
Firmware Revision for Slot 5: KNGND110
# 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 list-firmware nvme3
nvme3: Firmware Slot Information
Active Firmware Slot: 4
Next Firmware Slot: 5
Firmware Revision for Slot 1: KNGND110 (read-only)
Firmware Revision for Slot 2: KNGND110
Firmware Revision for Slot 3: KNGND110
Firmware Revision for Slot 4: KNGND112
Firmware Revision for Slot 5: KNGND113
Example 6: Listing Log Pages
# nvmeadm list-logpages nvme8
DEVICE NAME SCOPE FIELDS DESC
nvme8 error controller rae Error information
nvme8 health controller, rae SMART / Health information
namespace
nvme8 firmware nvm -- Firmware Slot Information
nvme8 changens controller rae changed namespaces
nvme8 wdc/eol nvm -- EOL
nvme8 wdc/devmgmt controller, -- Device Manageability
namespace
nvme8 wdc/pciesi controller lsp PCIe Signal Integrity
nvme8 wdc/power controller -- Power Samples
nvme8 wdc/temp controller -- Temperature Samples
nvme8 wdc/fwact controller -- Firmware Activation
nvme8 wdc/ccds controller -- CCDS Build Information
# nvmeadm list-logpages -p -o name,impl nvme8 firmware
firmware:yes
Example 7: Using Log Page Filters
This example shows how to use filters to select data from a log page
in both human readable and parsable outputs.
# nvmeadm print-logpage -f eye.out phyeye
EOM Header
Log Identifier: 0x19
EOM In Progress: completed (0x2)
Header Size: 0x40
Result Size: 0x1aa40
EOM Data Generation Number: 0x7
Log Revision: 0x1
Optional Data Present: 0x3
|--> Printable Eye Field Present: present (0x1)
|--> Eye Data Field Present: present (0x1)
Lanes: 0x4
Eyes Per Lane: 0x1
Log Specific Parameter Field Copy: 0x6
|--> Printable Eye Field Present: 0x6
Link Information: 0x4
|--> Measurement Link Speed: 0x4
Log Specific Identifier Copy: 0x0
Descriptor Size: 0x6a80
Number of Descriptors: 0x4
Maximum Top Bottom: 0x100
Maximum Left Right: 0x1a
Estimated Time for Good Quality: 0x96
Estimated Time for Better Quality: 0xf0
Estimated Time for Best Quality: 0x168
EOM Lane Descriptor 0
Measurement Status: 0x1
|--> Measurement Successful: yes (0x1)
Lane: 0x0
Eye: 0x1
Top: 0x38
Bottom: 0x38
Left: 0xb
Right: 0xe
Number of Rows: 0x200
Number of Columns: 0x35
EOM Lane Descriptor 1
Measurement Status: 0x1
|--> Measurement Successful: yes (0x1)
Lane: 0x1
Eye: 0x1
Top: 0x34
Bottom: 0x30
Left: 0xa
Right: 0x10
Number of Rows: 0x200
Number of Columns: 0x35
EOM Lane Descriptor 2
Measurement Status: 0x1
|--> Measurement Successful: yes (0x1)
Lane: 0x2
Eye: 0x1
Top: 0x30
Bottom: 0x2c
Left: 0xa
Right: 0xf
Number of Rows: 0x200
Number of Columns: 0x35
EOM Lane Descriptor 3
Measurement Status: 0x1
|--> Measurement Successful: yes (0x1)
Lane: 0x3
Eye: 0x1
Top: 0x38
Bottom: 0x34
Left: 0xb
Right: 0xe
Number of Rows: 0x200
Number of Columns: 0x35
Filters can then be used to limit this output. In human readable
mode, a filter will include all of its parent headings to make it
clear where something is. Additionally a filter that is not a leaf,
matches all of its children.
# nvmeadm print-logpage -f eye.out phyeye eom.odp eld2.ln
EOM Header
Optional Data Present: 0x3
|--> Printable Eye Field Present: present (0x1)
|--> Eye Data Field Present: present (0x1)
EOM Lane Descriptor 2
Lane: 0x2
In machine parsable mode, filters only match their exact value:
# nvmeadm print-logpage -f eye.out -Hpo short,value phyeye eom.eomip
eom.eomip:0x2
Example 8: Gathering and Printing Eye Data
This example shows gathering a physical eye measurement from a device
and then printing the eye data from a single lane.
# nvmeadm measure-phyeye -o eye.out -Q best nvme9
device indicates a minimum 360 second wait for best quality phyeye measurement
360/360 seconds elapsed
phyeye successfully written to eye.out
# nvmeadm report-phyeye -f eye.out -m eye-data -l 3
Lane 3, Eye 1: Eye Data
0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789abcdef
00: 25 00 00 00 37 25 00 00 ff 00 00 00 38 53 00 00 | %...7%......8S..
10: 38 53 00 00 48 00 00 00 46 00 00 00 46 00 00 00 | 8S..H...F...F...
20: 42 00 00 00 42 00 00 00 eb 00 00 00 c7 00 00 00 | B...B...........
30: 0f 01 00 00 24 01 00 00 38 26 00 00 a0 00 00 00 | ....$...8&......
40: e0 00 00 00 20 0d 00 00 20 0d 00 00 40 00 00 00 | .... ... ...@...
50: 05 11 00 00 5f 08 00 00 41 08 00 00 80 08 00 00 | ...._...A.......
The command line interface of nvmeadm is Evolving. The output of
nvmeadm is Not-an-Interface and may change any time.
The short names used by various filters are Committed.
nvme(4D)
NVMe specifications: http://www.nvmexpress.org/specifications/
illumos March 6, 2026 illumos
NAME
nvmeadm - NVMe administration utility
SYNOPSIS
nvmeadm -h [command]
nvmeadm [-dv] list [-c | -L] [-p -o field[,...]] [ctl[/ns][,...]]
nvmeadm [-dv] identify [-C | -c | -d | [-a] -n] ctl[/ns][,...]
nvmeadm [-dv] identify-controller [-C | -c | [-a] -n] ctl[,...]
nvmeadm [-dv] identify-namespace [-c | -d] ctl/ns[,...]
nvmeadm [-dv] list-logpages [-a] [-H] [-o field[,...] [-p]]
[-s scope[,...]] ctl[/ns][,...] [logpage...]
nvmeadm [-dv] get-logpage [-O output-file | -x |
-p -o field[,...] [-H]] ctl[/ns][,...] logpage [filter...]
nvmeadm [-dv] print-logpage -f file [-x | -p -o field[,...] [-H]]
logpage [filter...]
nvmeadm [-dv] list-features [-a] [-H] [-o field[,...] [-p]]
ctl[/ns][,...] [feature...]
nvmeadm [-dv] get-features ctl[/ns][,...] [feature-list]
nvmeadm [-dv] format ctl[/ns] [lba-format]
nvmeadm [-dv] secure-erase [-c] ctl[/ns]
nvmeadm [-dv] create-namespace -b block-size | -f flbas [-c cap]
[-n nmic] [-t type] ctl size
nvmeadm [-dv] delete-namespace ctl/ns
nvmeadm [-dv] attach-namespace ctl/ns
nvmeadm [-dv] detach-namespace ctl/ns
nvmeadm [-dv] attach ctl[/ns]
nvmeadm [-dv] detach ctl[/ns]
nvmeadm [-dv] list-firmware ctl
nvmeadm [-dv] load-firmware ctl firmware-file [offset]
nvmeadm [-dv] commit-firmware ctl slot
nvmeadm [-dv] activate-firmware ctl slot
nvmeadm [-dv] measure-phyeye -o output [-Q good | better | best] ctl
nvmeadm [-dv] report-phyeye -f file [-l lane] [-e eye] [-m mode]
nvmeadm [-dv] vendor-cmd -O opcode [-n nsid] [--cdw12 cdw12]
[--cdw13 cdw13] [--cdw14 cdw14] [--cdw15 cdw15]
[-l length [-i file | -o file]] [-L lock] [-I impact[,...]]
[-t timeout] ctl[/ns]
nvmeadm [-dv] sandisk/hwrev ctl
nvmeadm [-dv] sandisk/pci-eye -l lane -o output ctl
nvmeadm [-dv] wdc/e6dump -o output ctl
nvmeadm [-dv] wdc/resize -s size | -g ctl
nvmeadm [-dv] wdc/clear-assert ctl
nvmeadm [-dv] wdc/inject-assert ctl
DESCRIPTION
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).
OPTIONS
The following options are supported:
-h Print a short help text for nvmeadm, or for an optionally
specified nvmeadm command.
-d Enable debugging output.
-v Enable verbose output.
ARGUMENTS
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 "/" to the controller name,
followed by either the namespace ID or the namespace EUI64 or
NGUID as reported by the identify command. The namespace ID
is a positive non-zero decimal number. 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 and
print-logpage command. Valid names are listed in the
discussion of the get-logpage command below. Log pages both
the system and controller support can be determined with the
list-logpages command.
filter Various commands take a filter to print out portions of a
data structure such as a log page. A filter is a series of
dot delineated (".") strings that define which portion of the
data structure to list. Short names for fields come from the
relevant NVMe specifications and are treated as a committed
interface (aliases will be provided in the face of changes in
the spec).
The matching behavior varies between parsable and non-
parsable output. Consider the filter "eom.od.pefp". This
prints the Printable Eye Field Present member, from the
Optional Data Present Field, from the EOM Header that is part
of the phyeye log page. In non-parsable mode, the filter
"eom" would match the entire contents of the EOM header.
However, in parsable mode, only an exact match fires to
ensure that the contents are stable across changes to the
specification which add members to reserved fields.
When using filters, the program will exit non-zero if any
filter does not match.
feature-list
A comma-separated list of feature names for the get-features
command. Feature names can be specified in upper or lower
case. All features can be specified either by a short name
listed below or by the full name that the specification uses.
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
output-file
Specifies a file system location to write raw binary data out
to. 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.
scope Specifies the scope of a given type of thing to look at, such
as a log page. Scopes can either be specified by their full
name or a shortened form. For log pages, the following
scopes are supported:
controller
Indicates that the log is scoped to the controller.
The short form is "ctrl".
nvm Indicates that the log is scoped to the NVM
subsystem. There is no short form.
namespace
Indicates that the log is scoped to the namespace.
The short form is "ns".
For more information on the differences between these, please
see the NVMe specification.
size Indicates a size in bytes. The size may be specified in base
10 or in hexadecimal. An optional binary prefix may follow
the string. For example, a size of 10G would indicate 10 GiB
(Gibibytes) or 10,737,418,240 bytes. Valid binary prefixes
include:
b, B The size is in bytes. It is not adjusted.
k, K The size is in KiB. It will be multiplied by 2^10.
m, M The size is in MiB. It will be multiplied by 2^20.
g, G The size is in GiB. It will be multiplied by 2^30.
t, T The size is in TiB. It will be multiplied by 2^40.
p, P The size is in PiB. It will be multiplied by 2^50.
This is used by the create-namespace command.
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 the nvmeadm list-firmware
command.
COMMANDS
nvmeadm list [-c | -L] [-p -o field[,...]] [ctl[/ns][,...]]
Lists the NVMe controllers and by default also their active
namespaces, printing 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. If no controllers or namespaces
are given as arguments, then all controllers in the system and their
respective active namespaces are listed. When using the -v option to
nvmeadm, all possible namespaces of the controllers will be listed.
The nvmeadm list command supports the following options:
-c List controllers only and not their namespaces.
-L List information about controller location and
controlling attachment points.
-p Produce parsable output rather than human-readable
output. This option requires that output fields be
selected with the -o option.
-o 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.
INSTANCE The name of the device node and instance of it.
CTRLPATH The /devices path of the controller.
In addition, the following fields can be specified when listing
namespaces, not using the -c option:
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.
SIZE The logical size in bytes of the namespace.
USED The number of bytes used in the namespace.
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.
NS-STATE The current state of the namespace. This is one of the
following:
"unallocated"
the namesapce is currently unallocated. There
is no non-volatile memory assosciated with it.
"allocated"
The namespace has non-volatile memory allocated
to it, but it is not currently attached to the
controller.
"active"
The namespace is currently attached to the local
controller; however, the kernel cannot actively
attach a block device to the driver.
"active-usable"
The namespace is currently attached to the local
controller and the kernel can use the namespace
with blkdev(4D).
"blkdev"
The namespace is exposing a block device and is
actively attached to blkdev(4D).
FORMAT The current LBA format of the namespace printed as a
string comprised of the data section and the metadata
section generally structured as `data+meta'. For
example, a 4K formatted namespace with no metadata
sectors would be shown as `4096+0'. A 512-byte
formatted namespace with 16 bytes of metadata (perhaps
for end-to-end data protection) would be formatted as
`4096+16'.
FMTID The numerical ID of the namespace's LBA format. This
may be used as the lba-format argument to the format
subcommand.
FMTDS The data size, in bytes, of the namespace's LBA format.
FMTMS The metadata size, in bytes, of the namespace's LBA
format.
When using the -c or -L option to list controllers, the following
additional fields are supported:
CAPACITY The total raw capacity of the NVMe controller in bytes.
UNALLOCATED The number of bytes not currently assigned to any
namespace in the controller.
When using the -L option, the following additional fields are
supported:
LOCATION A string that indicates its physical location, derived from
system topology.
CTLAP The name of the parent attachment point, if any, that
controls this device. Usable with cfgadm(8).
nvmeadm identify-controller [-C | -c | [-a] -n] ctl[,...]
Print detailed information about the specified controllers. For an
explanation of the data printed by this command refer to the
description of the "IDENTIFY" admin command in the NVMe
specification.
By default, a relevant subset of the "IDENTIFY CONTROLLER" data
structure is printed. The full data structure is only printed when
verbose output is requested.
The following options can be used to print other "IDENTIFY"
information:
-C Print the Common Namespace Identification of the
controller.
-a Alter the output of the -n option to print the list
allocated namespace identifiers. Can only be specified
together with the -n option.
-c Print the list of all unique controller identifiers in
the NVMe subsystem the specified controller belongs to.
-n Print the list of active namespace identifiers of the
controller.
nvmeadm identify-namespace [-c | -d] ctl/ns[,...]
Print detailed information about the specified namespace. For an
explanation of the data printed by this command refer to the
description of the "IDENTIFY" admin command in the NVMe
specification.
By default, a relevant subset of the "IDENTIFY NAMESPACE" data
structure is printed. The full data structure is only printed when
verbose output is requested.
The following options can be used to print other "IDENTIFY"
information:
-c Print the list of all unique controller identifiers in
the NVMe subsystem the specified namespace belongs to and
which are currently attached to this namespace.
-d Print the list of namespace identification descriptors of
the namespace.
nvmeadm identify [-C | -c | -d | [-a] -n] ctl[/ns][,...]
Short-hand for the identify-controller and identify-namespace
commands, prints the same information about the specified controllers
and/or namespaces, depending on whether a controller or a namespace
was specified.
For a description of the various optional flags refer to the above
description of the identify-controller and identify-namespace
commands.
nvmeadm [-dv] list-logpages [-a] [-H] [-o field[,...] [-p]] [-s
scope[,...]] ctl[/ns][,...] [logpage...]
Prints the list of log pages and information about them specific to
the given controller or namespace. This is intended as a discovery
mechanism and will print information about mandatory, optional, and
vendor-specific log pages as well as all the information that is
useful for retrieving information about them.
The nvmeadm list-logpages command supports the following options:
-a Print all log pages. By default, only logs that are
implemented are printed.
-H Omit the output header columns.
-o field[,...]
A comma-separated list of one or more output fields to be
used. Fields are listed below and the name is case
insensitive.
-p Produce parsable output rather than human-readable
output. This option requires that output fields be
selected with the -o option.
-s scope[,...]
Print log pages that match the specified scope. If no
scope arguments are specified, then the scope will be set
to "ctrl,nvm" when the device is a controller and "ns"
when the device refers to a namespace.
The following fields are supported:
DEVICE Prints the name of the controller or namespace.
NAME Prints the name of the log page. This is the name that can
be used to get the log page with the get-logpage command.
This is a shortened form from the NVMe or vendor-specific
documentation.
DESC This is a description of the log page and generally
corresponds to information from the specification the log
page is drawn from.
SCOPE This is the set of scopes that the log page is applicable
to. As described earlier in the manual, valid scopes
include "ctrl", "nvm", and "ns". This indicates whether a
controller ("ctrl" and "nvm") or a namespace ("ns") will
work for this log page when running the get-logpage command
to get the log.
FIELDS This indicates the command fields that are accepted when
retrieving the log page from the controller. The fields
include:
lsp Indicates that a log specific parameter is accepted for
this page.
lsi Indicates that a log specific identifier is accepted
for this page.
rae Indicates that one can control whether or not an
asynchronous event is retained when retrieving the log
page. By default, asynchronous events are cleared when
certain log pages are fetched such as the health log
page.
For more information on these fields, please see the NVMe
specification.
CSI Indicates the log page's command set interface.
LID Indicates the log page's numeric ID. This when combined
with the log page's CSI is the unique identifier that
identifies the log page to the controller.
IMPL Indicates whether or not the system believes that the log
page is implemented.
SIZE Indicates the size of the log page. Not all log pages have
a fixed size and in such cases this field will not contain a
value.
MINSIZE When a log page is known to have a variable size, this
indicates the minimum amount of the log page to read to
determine the full size of the log page.
SOURCES This is a comma separated list of values that indicates
where information about this log page and its support came
from primarily. These include the following:
"spec" This comes from the NVMe specification.
Generally this refers to mandatory log
pages that are not dependent on any
information in the identify controller
data structure.
"identify-controller"
Information about this log page comes
from the identify controller data
structure. Many log pages are
described by the standard but are
optional and their support is indicated
through that.
"internal-db" This indicates that information about
this log page comes from our internal
databases in libnvme. Most vendor-
specific logs are described in
datasheets whose information is encoded
into the library and system and there
is not always a way to discover that it
is supported or not.
"command" This indicates that information about
this log page came from another command
that was issued to the controller which
indicates what was implemented and
present.
KIND This indicates the kind of log page that this is. Valid
options are:
"mandatory" Indicates that the NVMe specification
considers this mandatory for all
controllers of a given version.
"optional" Indicates that the NVMe specification
considers this log page optional. Some
items may be mandatory if a device
implements an optional feature like
namespace management, but they will still
be considered optional as the underlying
feature is.
"vendor-specific"
Indicates that this log is a vendor-
specific log page. These log pages are not
part of the NVMe standard and are generally
described in their own device's datasheets
or a separate standard such as the OCP
Datacenter NVMe SSD Specification.
The list-logpages command supports a series of operands which can be
used to filter the list of log pages that information is printed out
about. Each logpage operand is the name of a log page. Only
matching log pages will be printed and if no log pages match a given
operand argument or not log pages are printed at all (which can
happen due to a log being unsupported) then the command will generate
an error.
nvmeadm get-logpage -O output-file | -x | -p -o field[,...] [-H]
ctl[/ns][,...] logpage [filter...]
Print the specified log page of the specified controllers and/or
namespaces.
The nvmeadm get-logpage command supports the following options:
-H Omit the output header columns when using parsable
output.
-O output-file
Write the raw contents of the binary payload to
output-file. Its contents will not be interpreted or
printed out otherwise. Filters may not be used when
writing raw data out.
-o field[,...]
A comma-separated list of one or more output fields to be
used. Fields are listed below and the name is case
insensitive.
-p Produce parsable output rather than human-readable
output. This option requires that output fields be
selected with the -o option.
-x Print the raw output of logpage as a series of human-
readable hexadecimal output with the log page address and
ASCII decoding. Filters may not be used with the -x
option.
The following fields are supported:
SHORT This is the full dot-delineated short name that refers to a
specific field in a log page. For items from the NVMe
specification, this is the field's abbreviation found in the
specification. The short form is used in filters and its
value is considered a committed interface.
DESC This is a description of a field for a log page. This value
comes from the NVMe specification or vendor specification.
The description string for a field may change over time.
VALUE This is the underlying binary value found inside of a log
page's field printed in hexadecimal. The value is not
interpreted or adjusted. For example, many values in the
NVMe specification are 0s based values, meaning to get the
actual value one has to add one to it.
HUMAN This is a human-readable version of the field's value. The
human-readable output of a field may change over time due to
changes in the specification, bugs, or improvements to
nvmeadm.
OFFSET This is the offset to the start of the field in bytes. The
additional sub-byte bit offset to the start of the field is
communicated with the BITOFF field.
BITOFF This is the additional offset to the start of the field in
bits. This field will only ever be in the range of 0-7 and
must be combined with the OFFSET field to get the total
length.
LENGTH This is the length of the field in bytes. The additional
sub-byte bit length is communicated with the BITOFF field.
BITLEN This is the additional length of the field in bits. This
field will only ever be in the range of 0-7 and must be
combined with the LENGTH field to get the total length.
Most log pages are only available on a per-controller basis. For an
explanation of the contents of the log pages refer to the description
of the "GET LOGPAGE" admin command in the NVMe specification.
One or more filter operands may be supplied to a subset of log pages.
These filters will limit the fields that are printed in both parsable
and human-readable mode. Log pages the system does not know how to
decode are printed in a hexadecimal dump and filters are not
supported.
Known log pages are:
suplog Supported Log Pages. Lists information about log pages
that the device supports. Available starting in NVMe 2.0
devices.
error Error Information
health SMART/Health Information. A controller may support this
log page on a per-namespace basis.
firmware Firmware Slot Information
changens Changed Namespaces.
supcmd Commands Supported and Effects. An optional log page
added in NVMe 1.2 that indicates what commands the
controller itself actually supports.
pev Persistent Event Log. An optional log page added in NVMe
1.4 that contains a series of events that have occurred on
the device.
telemetry Host-initiated telemetry log. Contains vendor-specific
diagnostic information about the controller. This log
page requires that the -O option be specified.
supfeat Feature Identifiers Supported and Effects. A mandatory
log page added in NVMe 2.0 that indicates which features
are supported and their corresponding effects.
supmicmd NVMe-MI Commands Supported and Effects. A mandatory log
page added in NVMe 2.0 that indicates which management
interface commands are supported and their corresponding
effects.
phyeye Physical Interface Receiver Eye Opening Measurement. An
optional log page that provides a way of measuring the eye
of the controller's PHY, generally meaning all lanes of a
PCIe device. See the measure-phyeye and report-phyeye
commands for specialized subcommands dedicated to this.
The following vendor-specific log pages are supported. Not all
devices from a vendor support every log page. Use the list-logpages
command to determine which are supported for a given device and
whether they operate on a controller or namespace.
kioxia/extsmart Kioxia Extended SMART.
micron/smart Micron Vendor Unique SMART.
micron/extsmart Micron Extended SMART.
ocp/smart Open Compute Datacenter NVMe SSD specification
SMART / Health information.
ocp/errrec Open Compute Datacenter NVMe SSD specification
error recovery log.
ocp/fwact Open Compute Datacenter NVMe SSD specification
firmware activation log.
ocp/latency Open Compute Datacenter NVMe SSD specification
latency monitor.
ocp/devcap Open Compute Datacenter NVMe SSD specification
device capabilities.
ocp/unsup Open Compute Datacenter NVMe SSD specification
unsupported requirements.
solidigm/rlat Solidigm/Intel read command latency statistics.
solidigm/wlat Solidigm/Intel write command latency statistics.
solidigm/temp Solidigm/Intel temperature statistics.
solidigm/smart Solidigm/Intel vendor unique SMART log.
solidigm/ioqueue Solidigm/Intel I/O queue metrics.
solidigm/name Solidigm/Intel drive marketing name.
solidigm/power Solidigm/Intel power usage.
solidigm/gc Solidigm/Intel garbage collection.
solidigm/outlier Solidigm/Intel latency outlier.
wdc/eol Western Digital end-of-life.
wdc/devmgmt Western Digital device manageability.
wdc/pciesi Western Digital PCIe signal integrity.
wdc/power Western Digital power samples.
wdc/temp Western Digital temperature samples.
wdc/fwact Western Digital firmware activation history.
wdc/ccds Western Digital CCDS build information.
wdc/cusmart Western Digital customer unique SMART data.
nvmeadm print-logpage -f file [-x | -p -o field[,...] [-H]] logpage
[filter...]
Print and decode the specified log page contents from a file. Where
the get-logpage command retrieves an individual log page from a
device, the print-logpage instead reads log page data from an input
file file, but otherwise provides the same decoding and filtering
capabilities. This allows a log page to be interpreted multiple
times without asking for the controller for a fresh copy and allows
log pages from remote hosts to be processed locally. To capture the
binary log file use nvmeadm get-logpage -O.
The nvmeadm print-logpage command supports the following options:
-f file Read the log page contents from the specified file. This
option is required.
-H Omit the output header columns when using parsable
output.
-o field[,...]
A comma-separated list of one or more output fields to be
used. Fields are listed below and the name is case
insensitive.
-p Produce parsable output rather than human-readable
output. This option requires that output fields be
selected with the -o option.
-x Print the raw output of logpage as a series of human-
readable hexadecimal output with the log page address and
ASCII decoding. Filters and parsable output may not be
used with the -x option.
The print-logpage command supports the same fields, filters, and log
page names as the get-logpage command. See Examples.
nvmeadm list-features [-a] [-H] [-o field[,...] [-p]] ctl[/ns][,...]
[feature[,...]]
Prints the list of features and information about them specific to
the given controller or namespace. This is intended as a discovery
mechanism and will print information about known mandatory, optional,
and vendor-specific features as well as the information that is
useful for retrieving information about them.
The nvmeadm list-features command supports the following options:
-a Print all features, regardless of whether or not the
controller is known to implement them. By default
unimplemented features are not printed, but implemented
and unknown ones are.
-H Omit the output header columns.
-o field[,...]
A comma-separated list of one or more output fields to be
used. Fields are listed below and the name is case
insensitive.
-p Produce parsable output rather than human-readable
output. This option requires that output fields be
selected with the -o option.
The following fields are supported:
DEVICE Prints the name of the controller or namespace.
SHORT This is a shortened name for a feature which can be used to
identify it. These short names are unique to illumos and
not part of the NVMe specification.
SPEC This is the specification's name for a given feature.
FID This is the numeric ID that can be used to uniquely identify
a feature.
SCOPE This is a comma separated list of values that identifies
what scopes this feature covers. The supported scopes are
"controller", which indicates that it impacts the entire
controller and "namespace", which indicates that it impacts
just a single namespace.
KIND This indicates the kind of feature that this is. Valid
options are:
"mandatory" Indicates that the NVMe specification
considers this mandatory for all
controllers of a given version.
"optional" Indicates that the NVMe specification
considers this feature optional. Some
items may be mandatory if a device
implements an optional feature like
namespace management, but they will still
be considered optional as the underlying
feature is.
"vendor-specific"
Indicates that this log is a vendor-
specific feature. These features are not
part of the NVMe standard and are generally
described in their own device's datasheets
or a separate standard such as the OCP
Datacenter NVMe SSD Specification.
CSI The command set interface that the feature is specific to.
Most features are not specific to a CSI.
FLAGS The flags are a series of comma separated strings which
describe properties of the feature. The following flags are
currently supported:
"get-bcastns"
Indicates that the broadcast namespace is
supported when getting this feature.
"set-bcastns"
Indicates that the broadcast namespace is
supported when setting this feature. Using the
broadcast namespace indicates that all
namespace are impacted.
GET-IN A series of comma separated values indicating what is
required to get this feature. The following values are
supported:
cdw11 Indicates that the feature requires an argument in
the cdw11 field of the command. This is generally a
selector of some kind. For example, for the
temperature threshold feature, it selects which of
several sensors may be referred to.
data Indicates that a data buffer is required when getting
this feature. Its size is indicated by the DATALEN
field.
nsid Indicates that a namespace ID is required when
getting this feature.
SET-IN A series of comma separated values indicating what is
required to get this feature. The following values are
supported:
cdw11 Indicates that the feature uses information in cdw11
to set the feature.
cdw12 Indicates that the feature uses information in cdw12
to set the feature.
cdw13 Indicates that the feature uses information in cdw13
to set the feature.
cdw14 Indicates that the feature uses information in cdw14
to set the feature.
cdw15 Indicates that the feature uses information in cdw15
to set the feature.
data Indicates that the feature takes a data payload to
set the feature. Its size is indicated by the
DATALEN field.
nsid Indicates that the feature requires a valid namespace
identifier.
GET-OUT A series of comma separated values indicating what the
controller will return information about this feature in.
The following values are supported:
cdw0 Indicates that the controller will give information
about the feature in the command output 32-bit value.
data Indicates that the controller will output information
about the feature into the output buffer.
SET-OUT A series of comma separated values indicating what the
controller will update following the successful completion
of setting the feature. These values are the same as with
the GET-OUT field.
DATALEN Indicates the length of data for the feature.
IMPL Indicates whether or not the feature is known to be
implemented or not. The following values are possible:
"unknown"
Indicates that it is unknown as to whether or not
the feature is implemented. Some features are
optional and there is no way to determine this
short of issuing an attempt to get the feature
itself.
"yes" Indicates that we know the feature is implemented
by the controller.
"no" Indicates that we know the feature is not
implemented by the controller.
The list-features command supports a series of operands which can be
used to filter the list of features that information is printed out
about. Each feature operand is either the short name or the
specification's name for a given feature. In addition, the numeric
feature ID can also be used as a filter. If no features match a
given operand or no features are printed at all then the command will
generate an error.
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 arb controller
Power Management pm controller
LBA Range Type range namespace
Temperature Threshold temp controller
Error Recovery errec 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 apst controller
Software Progress Marker progress controller
Host Behavior Support hostsup 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(4D).
The list of supported LBA formats on a namespace can be retrieved
with the nvmeadm identify command.
nvmeadm secure-erase [-c] ctl[/ns]
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 create-namespace -b block-size | -f flbas [-c cap] [-n nmic]
[-t type] ctl size
Creates a new namespace of size size in the controller ctl. NVM will
be allocated for the namespace and the namespace will transition to
the allocated state. A created namespace must subsequently be
attached to the local controller, attach-namespace, and to the block
device framework (blkdev(4D)), attach, to provide I/O capabilities.
By default, a newly created namespace:
+o Uses the NVM command set interface (CSI). This can be changed
with the -t option.
+o Has the namespace's capacity set to the namespace's size. To
thinly provision a namespace, you may use the -c option to
specify a value less than the size argument. Note, the
controller may not support thin provisioning.
+o Configures the namespace so it may only be used with one
controller at a time. This can be changed with the -n option.
When creating a namespace, one must specify what formatted LBA index
to use. This index may be specified directly with the -f option or
instead the target block size may be specified with the -b option.
If -b is specified, then the command will search for a namespace with
that block size, with no metdata section, and with the highest
relative performance and use that. Available LBA format options may
be listed by printing the Common Namespace Identification values
through the identify-controller option with the -C option.
The create-namespace command supports the following options:
-b block-size
Specifies the target data block size of the namespace to
be created. This option is exclusive with the -f option.
block-size allow a binary prefix to be specified as per
the description of the size operand.
-c cap Specifies the namespace's capacity in bytes, which may
use a binary prefix like, such as 100G, as per the
description of the size operand. If this option is left
out, the namespace's capacity will be set to its size,
fully provisioning the namespace. Not all controllers
support thinly provisioning a namespace.
-f flbas Specifies the index of the formatted LBA size.
-n nmic Specifies the multipath I/O and namespace sharing
capabilities. The current valid options for this are:
none Indicates that only a single controller may
attach to the namespace at any given time.
shared Indicates that two or more controllers may attach
to the namespace at the same time.
-t type Specifies the command set interface for newly created
namespace. The default is "nvm". The system understands
the following command set interfaces; however, not all
controllers support all CSIs and currently the nvme(4D)
driver only supports the NVM CSI.
nvm The non-volatile memory CSI. This is the default
CSI of all NVMe devices and provides a regular
block interface.
kv Key Value command set interface. This interface
does not provide standard a logical block
abstraction and instead allows for someone to
read and write an arbitrary-sized object with a
128-bit key.
zns Zoned namespace command set interface. This
interface provides a block-like abstraction where
blocks are broken into different sized zones,
which contain ranges of logical blocks. Writing
to a zone offers different semantics from a
common block device.
nvmeadm delete-namespace ctl/ns
This deletes the specified namespace, freeing any capacity back to
the underlying NVM subsystem. The namespace identifier will be
considered inactive in ctl.
To delete a namespace, the namespace must already be detached from
all controllers through the detach-namespace command.
Upon deleting a namespace, all information that was contained in the
namespace will be lost.
nvmeadm attach-namespace ctl/ns
Attach the specified namespace to the controller ctl. This will
transition the namespace to the active state, allowing additional
information about the namespace to be queried. This also allows the
namespace to provide a block device interface through blkdev(4D),
which can be enabled by subsequently using the attach command.
nvmeadm detach-namespace ctl/ns
Detach the specified namespace from the controller ctl. The
namespace must already be detached from blkdev(4D) through the detach
command. When detached, the namespace transitions from active to
allocated in the controller. Data in the namespace remains valid;
however, not all commands will function against the namespace and I/O
may not be performed to it.
nvmeadm attach ctl[/ns]
Attaches the blkdev(4D) 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.
It is not an error to attach a namespace that is already attached,
any such request will be silently ignored.
nvmeadm detach ctl[/ns]
Temporarily detaches the blkdev(4D) 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(4D) driver.
It is not an error to detach a namespace that is already detached,
any such request will be silently ignored.
nvmeadm list-firmware ctl
List currently active firmware slot, the next active firmware slot,
and the current contents of all firmware slots of an NVMe controller.
This is a synonym for the nvmeadm get-logpage ctl firmware 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.
nvmeadm measure-phyeye -o output [-Q good | better | best] ctl
Perform a measurement of the physical interface's eye opening on the
specified controller, ctl, and write the resulting measurement to
output. The output file will be a version of the "phyeye" log page
whose contents can be interpreted with the report-phyeye and
print-logpage commands.
The quality of the log page may be one of "good", "better", or
"best", which are levels described by the NVMe over PCIe Transport
Specification. The higher the quality, the longer the measurement
will take, but the more accurate it will be.
When the measurement is initiated, no additional administrative
commands will be allowed on the device, though any active blkdev(4D)
devices will still be active. It is recommended I/O be quiesced
during the entire measurement period. The command will wait for the
device's recommended time, potentially 5-10 minutes, before it
queries the device for completeness.
The following options are supported:
-o Write the contents of the physical eye measurement to output.
-Q Specify the quality of the measurement. The default quality
when none is specified is best. The following quality levels
are supported: "good", "better", and "best".
nvmeadm report-phyeye -f file [-l lane] [-e eye] [-m mode]
Report the printable eye data or the vendor-specific eye data from a
physical eye measurement contained in file.
The following options are supported:
-f file
Read the physical eye measurement contents from file. This
should be gathered with the measure-phyeye command.
-l lane
Limit information printed to the specified PCIe device lane.
PCIe lanes are numbered starting at 0. Most NVMe devices
only have 4 lanes.
-e eye Limit information printed to the specified device eye. The
number of eyes present generally depends on the PCIe speed of
the device. There will only be a single eye for PCIe devices
running at Gen 5 or below. PCIe Gen 6 and higher devices
should have 3 eyes due to the use of PAM4 encoding.
-m mode
Selects the type of data that will be printed, defaulting to
print-eye if not specified. Valid modes are:
eye-data
Print the optional, vendor-specific eye-data. This
will generally be printed as a hexadecimal dump
unless vendor-specific knowledge of how to decode it
is present.
print-eye
Print the optional, ASCII printable eye. A 0 in the
printable eye indicates that the position is on or
inside of the eye. A 1 in the printable eye
indicates that the position is outside of the eye.
This cannot be translated into specific values
without vendor-specific information.
nvmeadm vendor-cmd -O opcode [-n nsid] [--cdw12 cdw12] [--cdw13 cdw13]
[--cdw14 cdw14] [--cdw15 cdw15] [-l length [-i file | -o file]] [-L
lock] [-I impact[,...]] [-t timeout] ctl[/ns]
This allows an administrator to send a vendor-specific command to a
device that supports the NVMe standard vendor specific command
format. Vendor-specific commands must be used carefully. While the
system attempts to first class many commands so that way we can
ensure that anything that causes confusion to the device is well
understood, this cannot be done for arbitrary commands. It is the
user's responsibility to understand if this can cause the controller
to lose data, interact poorly with the kernel leading to the driver
being out of sync with reality, or worse. The only required argument
for this is an operation code which must be in the vendor-specific
region.
The command may be run against either a controller or a namespace.
When a namespace is specified, its namespace id is included in the
command.
A command may optionally request that data be sent to the controller
as an input to the command (-i), or returned by the controller as an
output from the command (-o). There is no support in the standard
protocol for both an arbitrary sized data input and output. The
length of the input is specified by the -l flag, which indicates a
size in bytes that must be a multiple of 4 (commands operate in units
of uint32_t). Data is either read from or output to a file. The
maximum input or output data size provided by the system is 16 MiB.
When the command completes, it will print out the results of the
command and the value of the completion command dword 0.
The following arguments are supported:
-O, --opcode opcode
Sets the numeric operation code that should be used for the
command. This option is required. Valid values are in the
range [0xc0, 0xff].
-n, ---nsid nsid
Sets the namespace identifier to send in the command to nsid.
If the command is specified against a namespace specifically,
then this argument is not required. If the nsid argument is
specified and a namespace is specified as the target, they
must agree otherwise it is an error.
If no namespace ID is specified, this field will be set to 0
in the command.
--cdw12, -2 cdw12
Sets the 32-bit value of command dword 12 to the value cdw12.
Whether or not this is required is command specific.
If no value is specified, this field will be set to 0 in the
command.
--cdw13, -3 cdw13
Sets the 32-bit value of command dword 13 to the value cdw13.
Whether or not this is required is command specific.
If no value is specified, this field will be set to 0 in the
command.
--cdw14, -4 cdw14
Sets the 32-bit value of command dword 14 to the value cdw14.
Whether or not this is required is command specific.
If no value is specified, this field will be set to 0 in the
command.
--cdw15, -5 cdw15
Sets the 32-bit value of command dword 15 to the value cdw15.
Whether or not this is required is command specific.
If no value is specified, this field will be set to 0 in the
command.
-l, --length length
Indicates the length in bytes of the desired input or output
for the command. The length must be 4-byte aligned. If this
is specified, one of -i or -o must be specified to indicate
the direction of the data transfer and the source or
destination of the data.
-i, --input file
Read the input to the command from file. Requires that -l is
specified. If the input file, file, is shorter than the
length specified with -l, then the remaining data will be
filled with 0s.
-o, --output file
Write controller output to file. Requires that -l is
specified.
-L, ---lock lock
Allows for a read or write lock on the controller (or
namespace) to be taken for the duration of the command. The
following values are supported for lock:
read Takes a read lock on the controller Pq or namespace .
I/O will still continue during this time. This
prevents other operations from modifying the state of
the controller or namespace such as performing a
format, firmware update, etc.
write Takes an exclusive write lock on the controller. I/O
will still continue during this; however, no other
administrative actions will be allowed during this
time including read-only commands.
-I, --impact impact[,...]
A comma-separated list of values that describe to the system
the impact of running this command on the system. By
default, no impact to the system is assumed. The following
values are accepted:
data Indicates that the data on the controller or
namespace may be lost as a result of running this
command.
namespace Indicates that namespaces and their attributes may
be modified as a result of running this command.
-t, --timeout timeout
All administrative commands are monitored by the system to
ensure that they complete in a timely fashion. By default a
60 second timeout is applied to all administrative commands.
This may be overridden by specifying a new timeout value
which will be interpreted in seconds.
nvmeadm sandisk/hwrev ctl
This vendor-specific command prints the device hardware revision.
nvmeadm sandisk/pci-eye -l lane -o output ctl
This vendor-specific command obtains a PCIe eye diagram for the
hardware lane specified by lane on the NVMe device ctl. The PCIe
lane will generally be between 0 and 3, though it is possible fewer
lanes will be available depending on the drive bay and system board
design. The information will be output to the file output.
nvmeadm wdc/e6dump -o output ctl
This vendor-specific command performs a diagnostic dump of device
data to the file specified by output. The device remains in full
service while this is occurring.
nvmeadm wdc/resize -s size | -g ctl
This vendor-specific command will get the current over provisioning
size or set it. This command operates using power of 10 bytes, that
is in terms of gigabytes and not gibibytes. The sizes that are used
here will be different from those that the operating system will
report for the drive.
The following options are supported:
-g Returns the current size of the device in gigabytes
(powers of 10).
-s size Sets the size of the device to size which is in gigabytes
(powers of 10). This can be used to adjust the over
provisioning ratio on the device. The valid points are
device-specific. Please consult WDC datasheets for more
information.
When performing a resize all data and namespace will be
erased! All namespaces must be detached prior to issuing
this.
nvmeadm [-dv] wdc/clear-assert ctl
This clears an internal assertion record from a WDC device. Prior to
running this any such internal assertion should be saved by using the
wdc/e6dump command. This command should only be used if instructed
to do so as part of a troubleshooting process.
nvmeadm [-dv] wdc/inject-assert ctl
This injects a device assertion into a WDC NVMe device. The behavior
of doing so is device specific; however, all I/O will be interrupted
and the device may be retired. Unless explicitly instructed as part
of debugging a device or as part of internal development, this
command should not be used.
EXIT STATUS
The nvmeadm utility exits 0 on success, and >0 if an error occurs.
EXAMPLES
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 list-firmware nvme3
nvme3: Firmware Slot Information
Active Firmware Slot: 4
Next Firmware Slot: 4
Firmware Revision for Slot 1: KNGND110 (read-only)
Firmware Revision for Slot 2: KNGND110
Firmware Revision for Slot 3: KNGND110
Firmware Revision for Slot 4: KNGND112
Firmware Revision for Slot 5: KNGND110
# 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 list-firmware nvme3
nvme3: Firmware Slot Information
Active Firmware Slot: 4
Next Firmware Slot: 5
Firmware Revision for Slot 1: KNGND110 (read-only)
Firmware Revision for Slot 2: KNGND110
Firmware Revision for Slot 3: KNGND110
Firmware Revision for Slot 4: KNGND112
Firmware Revision for Slot 5: KNGND113
Example 6: Listing Log Pages
# nvmeadm list-logpages nvme8
DEVICE NAME SCOPE FIELDS DESC
nvme8 error controller rae Error information
nvme8 health controller, rae SMART / Health information
namespace
nvme8 firmware nvm -- Firmware Slot Information
nvme8 changens controller rae changed namespaces
nvme8 wdc/eol nvm -- EOL
nvme8 wdc/devmgmt controller, -- Device Manageability
namespace
nvme8 wdc/pciesi controller lsp PCIe Signal Integrity
nvme8 wdc/power controller -- Power Samples
nvme8 wdc/temp controller -- Temperature Samples
nvme8 wdc/fwact controller -- Firmware Activation
nvme8 wdc/ccds controller -- CCDS Build Information
# nvmeadm list-logpages -p -o name,impl nvme8 firmware
firmware:yes
Example 7: Using Log Page Filters
This example shows how to use filters to select data from a log page
in both human readable and parsable outputs.
# nvmeadm print-logpage -f eye.out phyeye
EOM Header
Log Identifier: 0x19
EOM In Progress: completed (0x2)
Header Size: 0x40
Result Size: 0x1aa40
EOM Data Generation Number: 0x7
Log Revision: 0x1
Optional Data Present: 0x3
|--> Printable Eye Field Present: present (0x1)
|--> Eye Data Field Present: present (0x1)
Lanes: 0x4
Eyes Per Lane: 0x1
Log Specific Parameter Field Copy: 0x6
|--> Printable Eye Field Present: 0x6
Link Information: 0x4
|--> Measurement Link Speed: 0x4
Log Specific Identifier Copy: 0x0
Descriptor Size: 0x6a80
Number of Descriptors: 0x4
Maximum Top Bottom: 0x100
Maximum Left Right: 0x1a
Estimated Time for Good Quality: 0x96
Estimated Time for Better Quality: 0xf0
Estimated Time for Best Quality: 0x168
EOM Lane Descriptor 0
Measurement Status: 0x1
|--> Measurement Successful: yes (0x1)
Lane: 0x0
Eye: 0x1
Top: 0x38
Bottom: 0x38
Left: 0xb
Right: 0xe
Number of Rows: 0x200
Number of Columns: 0x35
EOM Lane Descriptor 1
Measurement Status: 0x1
|--> Measurement Successful: yes (0x1)
Lane: 0x1
Eye: 0x1
Top: 0x34
Bottom: 0x30
Left: 0xa
Right: 0x10
Number of Rows: 0x200
Number of Columns: 0x35
EOM Lane Descriptor 2
Measurement Status: 0x1
|--> Measurement Successful: yes (0x1)
Lane: 0x2
Eye: 0x1
Top: 0x30
Bottom: 0x2c
Left: 0xa
Right: 0xf
Number of Rows: 0x200
Number of Columns: 0x35
EOM Lane Descriptor 3
Measurement Status: 0x1
|--> Measurement Successful: yes (0x1)
Lane: 0x3
Eye: 0x1
Top: 0x38
Bottom: 0x34
Left: 0xb
Right: 0xe
Number of Rows: 0x200
Number of Columns: 0x35
Filters can then be used to limit this output. In human readable
mode, a filter will include all of its parent headings to make it
clear where something is. Additionally a filter that is not a leaf,
matches all of its children.
# nvmeadm print-logpage -f eye.out phyeye eom.odp eld2.ln
EOM Header
Optional Data Present: 0x3
|--> Printable Eye Field Present: present (0x1)
|--> Eye Data Field Present: present (0x1)
EOM Lane Descriptor 2
Lane: 0x2
In machine parsable mode, filters only match their exact value:
# nvmeadm print-logpage -f eye.out -Hpo short,value phyeye eom.eomip
eom.eomip:0x2
Example 8: Gathering and Printing Eye Data
This example shows gathering a physical eye measurement from a device
and then printing the eye data from a single lane.
# nvmeadm measure-phyeye -o eye.out -Q best nvme9
device indicates a minimum 360 second wait for best quality phyeye measurement
360/360 seconds elapsed
phyeye successfully written to eye.out
# nvmeadm report-phyeye -f eye.out -m eye-data -l 3
Lane 3, Eye 1: Eye Data
0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789abcdef
00: 25 00 00 00 37 25 00 00 ff 00 00 00 38 53 00 00 | %...7%......8S..
10: 38 53 00 00 48 00 00 00 46 00 00 00 46 00 00 00 | 8S..H...F...F...
20: 42 00 00 00 42 00 00 00 eb 00 00 00 c7 00 00 00 | B...B...........
30: 0f 01 00 00 24 01 00 00 38 26 00 00 a0 00 00 00 | ....$...8&......
40: e0 00 00 00 20 0d 00 00 20 0d 00 00 40 00 00 00 | .... ... ...@...
50: 05 11 00 00 5f 08 00 00 41 08 00 00 80 08 00 00 | ...._...A.......
INTERFACE STABILITY
The command line interface of nvmeadm is Evolving. The output of
nvmeadm is Not-an-Interface and may change any time.
The short names used by various filters are Committed.
SEE ALSO
nvme(4D)
NVMe specifications: http://www.nvmexpress.org/specifications/
illumos March 6, 2026 illumos