share/man/man4/nvme.4

   1 .\" Copyright (c) 2016 The DragonFly Project.  All rights reserved.
   2 .\"
   3 .\" This code is derived from software contributed to The DragonFly Project
   4 .\" by Matthew Dillon <dillon@backplane.com>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\"
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in
  14 .\"    the documentation and/or other materials provided with the
  15 .\"    distribution.
  16 .\" 3. Neither the name of The DragonFly Project nor the names of its
  17 .\"    contributors may be used to endorse or promote products derived
  18 .\"    from this software without specific, prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  23 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  24 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  26 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  27 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  28 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  29 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  30 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .Dd June 5, 2015
  34 .Dt NVME 4
  35 .Os
  36 .Sh NAME
  37 .Nm nvme
  38 .Nd NVM Express Controller for PCIe-based SSDs
  39 .Sh SYNOPSIS
  40 To compile this driver into the kernel,
  41 place the following line in your
  42 kernel configuration file:
  43 .Bd -ragged -offset indent
  44 .Cd "device nvme"
  45 .Ed
  46 .Pp
  47 Alternatively, to load the driver as a
  48 module at boot time, place the following line in
  49 .Xr loader.conf 5 :
  50 .Bd -literal -offset indent
  51 nvme_load="YES"
  52 .Ed
  53 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 driver provides support for PCIe storage controllers conforming to the
  57 NVM Express Controller Interface specification.
  58 NVMe controllers have a direct PCIe host interface to the controller
  59 which in turn has a direct connection to the underlying non-volatile
  60 (typically flash) storage, yielding a huge reduction in latency and
  61 increase in performance over
  62 .Xr ahci 4 .
  63 .Pp
  64 In addition, NVMe controllers are capable of supporting up to 65535
  65 independent submission and completion queues each able to support upwards
  66 of 16384 queue entries.  Each queue may be assigned its own interrupt
  67 vector out of the controller's pool (up to 2048).
  68 .Pp
  69 Actual controllers typically implement lower limits.  While most controllers
  70 allow a maximal number of queue entries, the total number of queues is often
  71 limited to far less than 65535.  8-32 queues are commonly supported.
  72 Similarly, while up to 2048 MSI-X vectors can be supported by the spec,
  73 actual controllers typically support fewer vectors.  Still, having several
  74 MSI-X vectors allows interrupts to be distributed to multiple CPUs,
  75 reducing bottlenecks and improving performance.  The multiple queues can
  76 be divvied up across available cpu cores by the driver, as well as split-up
  77 based on the type of I/O operation being performed (such as giving read
  78 and write I/O commands their own queues).  This also significantly
  79 reduces bottlenecks and improves performance, particularly in mixed
  80 read-write environments.
  81 .Sh FORM FACTOR
  82 NVMe boards usually come in one of two flavors, either a tiny form-factor
  83 with a M.2 or NGFF connector, supplying 2 or 4 PCIe lanes, or in a larger
  84 form that slips into a normal PCIe slot.  The larger form typically
  85 implements 2, 4, or 8 lanes.  Also note that adapter cards that fit
  86 into normal PCIe slots and can mount the smaller M.2/NGFF NVME cards can
  87 be cheaply purchased.
  88 .Sh PERFORMANCE
  89 Typical performance for a 2-lane (x2) board is in the 700MB/s to 1.5 GByte/s
  90 range.  4-lane (x4) boards typically range from 1.0 GBytes/s to 2.5 GBytes/s.
  91 Full-blown PCIe cards run the whole gamut, 2.5 GBytes/sec is fairly typical
  92 but performance can exceed 5 GBytes/sec in a high-end card.
  93 .Pp
  94 Multi-threaded random-read performance can exceed 300,000 IOPS on an x4 board.
  95 Single-threaded performance is usually in the 40,000 to 100,000 IOPS range.
  96 Sequential submission/completion latencies are typically below 35uS while
  97 random submission/completion latencies are typically below 110uS.
  98 Performance (uncached) through a filesystem will be bottlenecked by additional
  99 factors, particularly if testing is only being done on a single file.
 100 .Pp
 101 The biggest differentiation between boards is usually write performance.
 102 Small boards with only a few flash chips have relatively low write
 103 performance, usually in the 150MByte/sec range.  Higher-end boards will have
 104 significantly better write performance, potentially exceeding 1.0 GByte/sec.
 105 .Pp
 106 For reference, the SATA-III physical interface is limited to 600 MBytes/sec
 107 and the extra phy layer results in higher latencies, and AHCI controllers are
 108 limited to a single 32-entry queue.
 109 .Sh FEATURES
 110 The
 111 .Dx
 112 .Nm
 113 driver automatically selects the best SMP-friendly and
 114 I/O-typing queue configuration possible based on what the controller
 115 supports.
 116 It uses a direct disk device API which bypasses CAM, so kernel code paths
 117 to read and write blocks are SMP-friendly and, depending on the queue
 118 configuration, potentially conflict-free.
 119 The driver is capable of submitting commands and processing responses on
 120 multiple queues simultaniously in a SMP environment.
 121 .Pp
 122 The driver pre-reserves DMA memory for all necessary descriptors, queue
 123 entries, and internal driver structures, and allows for a very generous
 124 number of queue entries (1024 x NQueues) for maximum performance.
 125 .Sh HINTS ON NVME CARDS
 126 So far I've only been able to test one Samsung NVME M.2 card and
 127 an Intel 750 HHHL (half-height / half-length) PCIe card.
 128 .Pp
 129 My recommendation is to go with Samsung.  The firmware is pretty good.
 130 It appears to be implemented reasonably well regardless of the queue
 131 configuration or I/O blocksize employed, giving expected scaling without
 132 any quirky behavior.
 133 .Pp
 134 The intel 750 has very poorly-implemented firmware.
 135 For example, the more queues the driver configures, the poorer
 136 the single-threaded read performance is.  And no matter the queue
 137 configuration it appears that adding a second concurrent reader drops
 138 performance drastically, then it slowly increases as you add more concurrent
 139 readers.  In addition, on the 750, the firmware degrades horribly when
 140 reads use a blocksize of 64KB.  The best performance is at 32KB.  In fact,
 141 performance again degrades horribly if you drop down to 16KB.
 142 And if that weren't bad enough, the 750 takes over 13 seconds to become
 143 ready after a machine power-up or reset.
 144 .Pp
 145 The grand result of all of this is that filesystem performance through an
 146 Intel NVME card is going to be hit-or-miss, depending on inconseqential
 147 differences in blocksize and queue configuration.
 148 Regardless of whatever hacks Intel might be employing in their own drivers,
 149 this is just totally unacceptable driver behavior.
 150 .Pp
 151 I do not recommend rebranders like Plextor or Kingston.  For one thing,
 152 if you do buy these, be very careful to get one that is actually a NVME
 153 card and not a M.2 card with an AHCI controller on it.  Plextor's performance
 154 is particularly bad.  Kingston seems to have done a better job and reading
 155 at 1.0GB/s+ is possible despite the cpu overhead of going through an AHCI
 156 controller (the flash in both cases is directly connected to the controller,
 157 so there is no SATA Phy to get in the way).  Of course, if you actually want
 158 an AHCI card, then these might be the way to go, and you might even be able
 159 to boot from them.
 160 .Sh HINTS ON CONFIGURING MACHINES (BIOS)
 161 If nvme locks up while trying to probe the BIOS did something horrible to
 162 the PCIe card.  If you have enabled your BIOS's FastBoot option, turn it
 163 off, this may fix the issue.
 164 .Pp
 165 Not all BIOSes can boot from a NVMe card.  Those that can typically require
 166 booting via EFI.
 167 .Sh SEE ALSO
 168 .Xr ahci 4 ,
 169 .Xr intro 4 ,
 170 .Xr pci 4 ,
 171 .Xr loader.conf 5 ,
 172 .Xr nvmectl 8
 173 .Sh HISTORY
 174 The
 175 .Nm
 176 driver first appeared in
 177 .Dx 4.5 .
 178 .Sh AUTHORS
 179 .An -nosplit
 180 The
 181 .Nm
 182 driver for
 183 .Dx
 184 was written from scratch by
 185 .An Matthew Dillon Aq Mt dillon@backplane.com
 186 based on the NVM Express 1.2a specification.