share/man/man4/nvme.4

   1 .\"
   2 .\" Copyright (c) 2012-2016 Intel Corporation
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions, and the following disclaimer,
  10 .\"    without modification.
  11 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
  12 .\"    substantially similar to the "NO WARRANTY" disclaimer below
  13 .\"    ("Disclaimer") and any redistribution must be conditioned upon
  14 .\"    including a substantially similar Disclaimer requirement for further
  15 .\"    binary redistribution.
  16 .\"
  17 .\" NO WARRANTY
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  21 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  26 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  27 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGES.
  29 .\"
  30 .\" nvme driver man page.
  31 .\"
  32 .\" Author: Jim Harris <jimharris@FreeBSD.org>
  33 .\"
  34 .\" $FreeBSD$
  35 .\"
  36 .Dd June 6, 2020
  37 .Dt NVME 4
  38 .Os
  39 .Sh NAME
  40 .Nm nvme
  41 .Nd NVM Express core driver
  42 .Sh SYNOPSIS
  43 To compile this driver into your kernel,
  44 place the following line in your kernel configuration file:
  45 .Bd -ragged -offset indent
  46 .Cd "device nvme"
  47 .Ed
  48 .Pp
  49 Or, to load the driver as a module at boot, place the following line in
  50 .Xr loader.conf 5 :
  51 .Bd -literal -offset indent
  52 nvme_load="YES"
  53 .Ed
  54 .Pp
  55 Most users will also want to enable
  56 .Xr nvd 4
  57 or
  58 .Xr nda 4
  59 to expose NVM Express namespaces as disk devices which can be
  60 partitioned.
  61 Note that in NVM Express terms, a namespace is roughly equivalent to a
  62 SCSI LUN.
  63 .Sh DESCRIPTION
  64 The
  65 .Nm
  66 driver provides support for NVM Express (NVMe) controllers, such as:
  67 .Bl -bullet
  68 .It
  69 Hardware initialization
  70 .It
  71 Per-CPU IO queue pairs
  72 .It
  73 API for registering NVMe namespace consumers such as
  74 .Xr nvd 4
  75 or
  76 .Xr nda 4
  77 .It
  78 API for submitting NVM commands to namespaces
  79 .It
  80 Ioctls for controller and namespace configuration and management
  81 .El
  82 .Pp
  83 The
  84 .Nm
  85 driver creates controller device nodes in the format
  86 .Pa /dev/nvmeX
  87 and namespace device nodes in
  88 the format
  89 .Pa /dev/nvmeXnsY .
  90 Note that the NVM Express specification starts numbering namespaces at 1,
  91 not 0, and this driver follows that convention.
  92 .Sh CONFIGURATION
  93 By default,
  94 .Nm
  95 will create an I/O queue pair for each CPU, provided enough MSI-X vectors
  96 and NVMe queue pairs can be allocated.
  97 If not enough vectors or queue
  98 pairs are available, nvme(4) will use a smaller number of queue pairs and
  99 assign multiple CPUs per queue pair.
 100 .Pp
 101 To force a single I/O queue pair shared by all CPUs, set the following
 102 tunable value in
 103 .Xr loader.conf 5 :
 104 .Bd -literal -offset indent
 105 hw.nvme.per_cpu_io_queues=0
 106 .Ed
 107 .Pp
 108 To assign more than one CPU per I/O queue pair, thereby reducing the number
 109 of MSI-X vectors consumed by the device, set the following tunable value in
 110 .Xr loader.conf 5 :
 111 .Bd -literal -offset indent
 112 hw.nvme.min_cpus_per_ioq=X
 113 .Ed
 114 .Pp
 115 To force legacy interrupts for all
 116 .Nm
 117 driver instances, set the following tunable value in
 118 .Xr loader.conf 5 :
 119 .Bd -literal -offset indent
 120 hw.nvme.force_intx=1
 121 .Ed
 122 .Pp
 123 Note that use of INTx implies disabling of per-CPU I/O queue pairs.
 124 .Pp
 125 To control maximum amount of system RAM in bytes to use as Host Memory
 126 Buffer for capable devices, set the following tunable:
 127 .Bd -literal -offset indent
 128 hw.nvme.hmb_max
 129 .Ed
 130 .Pp
 131 The default value is 5% of physical memory size per device.
 132 .Pp
 133 The
 134 .Xr nvd 4
 135 driver is used to provide a disk driver to the system by default.
 136 The
 137 .Xr nda 4
 138 driver can also be used instead.
 139 The
 140 .Xr nvd 4
 141 driver performs better with smaller transactions and few TRIM
 142 commands.
 143 It sends all commands directly to the drive immediately.
 144 The
 145 .Xr nda 4
 146 driver performs better with larger transactions and also collapses
 147 TRIM commands giving better performance.
 148 It can queue commands to the drive; combine
 149 .Dv BIO_DELETE
 150 commands into a single trip; and
 151 use the CAM I/O scheduler to bias one type of operation over another.
 152 To select the
 153 .Xr nda 4
 154 driver, set the following tunable value in
 155 .Xr loader.conf 5 :
 156 .Bd -literal -offset indent
 157 hw.nvme.verbose_cmd_dump=1
 158 .Ed
 159 .Pp
 160 .Sh SYSCTL VARIABLES
 161 The following controller-level sysctls are currently implemented:
 162 .Bl -tag -width indent
 163 .It Va dev.nvme.0.num_cpus_per_ioq
 164 (R) Number of CPUs associated with each I/O queue pair.
 165 .It Va dev.nvme.0.int_coal_time
 166 (R/W) Interrupt coalescing timer period in microseconds.
 167 Set to 0 to disable.
 168 .It Va dev.nvme.0.int_coal_threshold
 169 (R/W) Interrupt coalescing threshold in number of command completions.
 170 Set to 0 to disable.
 171 .El
 172 .Pp
 173 The following queue pair-level sysctls are currently implemented.
 174 Admin queue sysctls take the format of dev.nvme.0.adminq and I/O queue sysctls
 175 take the format of dev.nvme.0.ioq0.
 176 .Bl -tag -width indent
 177 .It Va dev.nvme.0.ioq0.num_entries
 178 (R) Number of entries in this queue pair's command and completion queue.
 179 .It Va dev.nvme.0.ioq0.num_tr
 180 (R) Number of nvme_tracker structures currently allocated for this queue pair.
 181 .It Va dev.nvme.0.ioq0.num_prp_list
 182 (R) Number of nvme_prp_list structures currently allocated for this queue pair.
 183 .It Va dev.nvme.0.ioq0.sq_head
 184 (R) Current location of the submission queue head pointer as observed by
 185 the driver.
 186 The head pointer is incremented by the controller as it takes commands off
 187 of the submission queue.
 188 .It Va dev.nvme.0.ioq0.sq_tail
 189 (R) Current location of the submission queue tail pointer as observed by
 190 the driver.
 191 The driver increments the tail pointer after writing a command
 192 into the submission queue to signal that a new command is ready to be
 193 processed.
 194 .It Va dev.nvme.0.ioq0.cq_head
 195 (R) Current location of the completion queue head pointer as observed by
 196 the driver.
 197 The driver increments the head pointer after finishing
 198 with a completion entry that was posted by the controller.
 199 .It Va dev.nvme.0.ioq0.num_cmds
 200 (R) Number of commands that have been submitted on this queue pair.
 201 .It Va dev.nvme.0.ioq0.dump_debug
 202 (W) Writing 1 to this sysctl will dump the full contents of the submission
 203 and completion queues to the console.
 204 .El
 205 .Pp
 206 In addition to the typical pci attachment, the
 207 .Nm
 208 driver supports attaching to a
 209 .Xr ahci 4
 210 device.
 211 Intel's Rapid Storage Technology (RST) hides the nvme device
 212 behind the AHCI device due to limitations in Windows.
 213 However, this effectively hides it from the
 214 .Fx
 215 kernel.
 216 To work around this limitation,
 217 .Fx
 218 detects that the AHCI device supports RST and when it is enabled.
 219 See
 220 .Xr ahci 4
 221 for more details.
 222 .Sh SEE ALSO
 223 .Xr nda 4 ,
 224 .Xr nvd 4 ,
 225 .Xr pci 4 ,
 226 .Xr nvmecontrol 8 ,
 227 .Xr disk 9
 228 .Sh HISTORY
 229 The
 230 .Nm
 231 driver first appeared in
 232 .Fx 9.2 .
 233 .Sh AUTHORS
 234 .An -nosplit
 235 The
 236 .Nm
 237 driver was developed by Intel and originally written by
 238 .An Jim Harris Aq Mt jimharris@FreeBSD.org ,
 239 with contributions from
 240 .An Joe Golio
 241 at EMC.
 242 .Pp
 243 This man page was written by
 244 .An Jim Harris Aq Mt jimharris@FreeBSD.org .