path: root/usr/src/man/man4d/nvme.4d

.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright (c) 2018, Joyent, Inc.
.\" Copyright 2022 Tintri by DDN, Inc. All rights reserved.
.\"
.Dd May 11, 2022
.Dt NVME 4D
.Os
.Sh NAME
.Nm nvme
.Nd Intel NVMe compliant storage driver
.Sh DESCRIPTION
The
.Nm
driver uses the
.Xr blkdev 4D
framework to provide access to
NVMe compliant solid-state storage devices.
All NVMe version 1.x devices are supported.
.Lp
NVMe devices supporting multiple namespaces will present each
namespace as its own
.Xr blkdev 4D
instance in the system.
.
.Sh CONFIGURATION
The
.Nm
driver can be configured by defining properties in the
.Pa nvme.conf
file.
The parameters are considered an unstable interface, subject to
change without notice.
The following properties are currently supported:
.Bl -tag -width Va
.It Va strict-version
This can be set to 0 to allow
.Nm
to attach to devices supporting newer version of the NVMe
specification.
The default value is 1, limiting
.Nm
to work with devices that support major version 1.
.It Va ignore-unknown-vendor-status
This can be set to 1 to allow
.Nm
to continue operating even if it receives an unknown vendor command
status.
.It Va admin-queue-len
This is the number of entries in the admin command queue.
Legal values are between 16 and 4096, the default value is 256.
.It Va io-squeue-len
This is the number of entries in each I/O submission queue.
Legal values are between 16 and 65536, the default value is 1024.
.It Va io-cqueue-len
This is the number of entries in each I/O completion queue.
Legal values are between 16 and 65536, the default value is 2048.
When the number of submission and completion queues are the same,
the queue lengths will be both set to the lesser of
.Va io-squeue-len
and
.Va io-cqueue-len .
.It Va async-event-limit
This is the maximum number of asynchronous event requests issued by
the driver.
Asynchronous events are used to report error conditions.
The driver will never use more asynchronous events than this value, or
what the hardware supports if it is less, or 1/10th of the admin queue
length if it is less.
.It Va volatile-write-cache-enable
This property can be set to 0 to disable the volatile write cache, if
the hardware supports it.
The default setting is 1, which enables the volatile write cache.
.It Va min-phys-block-size
This is the minimum physical block size that is reported to
.Xr blkdev 4D .
This value must be a power of 2 greater than or equal to 512.
If the device reports a best block size larger than what is
specified here the driver will ignore the value specified here.
.It Va max-submission-queues
This is the maximum number of submission queues the driver will create per
device.
Legal values are between 1 and 65535, the default is to
match the number for
.Em max-completion-queues .
The number of queues created will not be allowed to exceed the
drive's hardware limitation.
If the number of submission queues is larger than
.Em max-completion-queues
the completion queues will be shared across the submission
queues.
.It Va max-completion-queues
This is the maximum number of completion queues the driver will create per
device.
Legal values are between 1 and 65535, the default is to match
the number of interrupt vectors allocated to the drive.
The number of queues created will not exceed the number of interrupt vectors,
.Em max-submission-queues ,
or the drive's hardware limitation.
.El
.Pp
In addition to the above properties, some device-specific tunables can be
configured in
.Pa nvme.conf
using the
.Va nvme-config-list
global property.
The value of this property is a list of triplets.
The formal syntax is:
.Bl -column "nvme-config-list" -offset indent
.It nvme-config-list	::= <triplet>
.Op \&, <triplet> Ns
*
;
.It <triplet>	::=
.Qq <model>
\&,
.Qq <rev-list>
\&,
.Qq <tuple-list>
.It <rev-list>	::=
.Op <fwrev> Oo \&, <fwrev> Oc Ns *
.It <tuple-list>	::=
<tunable>
.Op \&, <tunable> Ns
*
.It <tunable>	::=
.Qq <name>
\&:
.Qq <value>
.El
.Pp
The
.Va <model>
and
.Va <fwrev>
are the strings that are returned in the
.Qq Model Number
and
.Qq Firmware Revision
fields, respectively, in the
.Qq Identify Controller
data structure as returned by the
.Qq IDENTIFY
command.
Specifying a
.Va <rev-list>
is optional, an empty string
.Po Qo Qc Pc
may be used instead.
.Pp
The
.Va <tuple-list>
contains one or more tunables to apply to all controllers that match the
specified model number and optional firmware revisions.
Each
.Va <tunable>
is a
.Va <name>
:
.Va <value>
pair.
Supported tunable names are:
.Bl -tag -width Va
.It Va ignore-unknown-vendor-status
Similar to the global property, this property accepts a boolean value specified
as either
.Qq on ,
.Qq off ,
.Qq true ,
or
.Qq false
to enable or disable the driver continuing operation even if it receives an
unknown vendor command status from a controller.
.It Va min-phys-block-size
Same as the global property, this is the minimum physical block size that is
reported to
.Xr blkdev 4D .
This value must be a power of 2 greater than or equal to 512.
If the device reports a best block size larger than what is
specified here the driver will ignore the value specified here.
.It Va volatile-write-cache
Similar to the global property
.Va volatile-write-cache-enable ,
this property accepts a boolean value specified as either
.Qq on ,
.Qq off ,
.Qq true ,
or
.Qq false
to enable or disable the volatile write cache, if the hardware supports it.
By default the volatile write cache is enabled.
.El
.Sh FILES
.Bl -tag -compact -width Pa
.It Pa /dev/dsk/cntnd0sn
Block device minor nodes.
.It Pa /dev/rdsk/cntnd0sn
Raw block device minor nodes.
.El
.Lp
In the device minor nodes, the following substitutions may occur:
.Bl -tag -offset indent -width Va
.It Va cn
A controller number, typically one for each
.Nm
device found.
Controller numbers are dynamically assigned by the system.
.It Va tn
The target number.
This is the namespace EUI64 if available, or the namespace ID used by
the hardware.
Namespace ID 0 is reserved, hence target numbers start with 1.
.It Va sn
This is the
.Em slice
number, representing a subset of the disk.
See
.Xr dkio 4I .
.El
.
.Sh SEE ALSO
.Xr blkdev 4D