share/man/man4/nda.4

   1 .\"
   2 .\" Copyright (c) 2017 Netflix, Inc.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\"
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd June 6, 2020
  29 .Dt NDA 4
  30 .Os
  31 .Sh NAME
  32 .Nm nda
  33 .Nd NVMe Direct Access device driver
  34 .Sh SYNOPSIS
  35 .Cd device nvme
  36 .Cd device scbus
  37 .Sh DESCRIPTION
  38 The
  39 .Nm
  40 driver provides support for direct access devices, implementing the
  41 .Tn NVMe
  42 command protocol, that are attached to the system through a host adapter
  43 supported by the CAM subsystem.
  44 .Sh SYSCTL VARIABLES
  45 The following variables are available as both
  46 .Xr sysctl 8
  47 variables and
  48 .Xr loader 8
  49 tunables:
  50 .Bl -tag -width 12
  51 .It Va hw.nvme.use_nvd
  52 The
  53 .Xr nvme 4
  54 driver will create
  55 .Nm
  56 device nodes for block storage when set to 0.
  57 Create
  58 .Xr nvd 4
  59 device nodes for block storage when set to 1.
  60 See
  61 .Xr nvd 4
  62 when set to 1.
  63 .It Va kern.cam.nda.nvd_compat
  64 When set to 1,
  65 .Xr nvd 4
  66 aliases will be created for all
  67 .Nm
  68 devices, including partitions and other
  69 .Xr geom 4
  70 providers that take their names from the disk's name.
  71 .Xr nvd 4
  72 devices will not, however, be reported in the
  73 .Va kern.disks
  74 .Xr sysctl 8 .
  75 .It Va kern.cam.nda.sort_io_queue
  76 This variable determines whether the software queued entries are
  77 sorted in LBA order or not.
  78 Sorting is almost always a waste of time.
  79 The default is to not sort.
  80 .It Va kern.cam.nda.enable_biospeedup
  81 This variable determines if the
  82 .Nm
  83 devices participate in the speedup protocol.
  84 When the device participates in the speedup, then when the upper layers
  85 send a
  86 .Va BIO_SPEEDUP ,
  87 all current
  88 .Va BIO_DELETE
  89 requests not yet sent to the hardware are completed successfully immediate
  90 without sending them to the hardware.
  91 Used in low disk space scenarios when the filesystem encounters
  92 a critical shortage and needs blocks immediately.
  93 Since trims have maximum benefit when the LBA is unused for a long time,
  94 skipping the trim when space is needed for immediate writes results in little to
  95 no excess wear.
  96 When participation is disabled,
  97 .Va BIO_SPEEDUP
  98 requests are ignored.
  99 .It Va kern.cam.nda.max_trim
 100 The maximum number of LBA ranges to be collected together for each DSM trims
 101 send to the hardware.
 102 Defaults to 256, which is the maximum number of ranges the protocol supports.
 103 Sometimes poor trim performance can be mitigated by limiting the number of
 104 ranges sent to the device.
 105 This value must be between 1 and 256 inclusive.
 106 .El
 107 .Pp
 108 The following report per-device settings, and are read-only unless
 109 otherwise indicated.
 110 Replace
 111 .Va N
 112 with the device unit number.
 113 .Bl -tag -width 12
 114 .It Va kern.cam.nda.N.rotating
 115 This variable reports whether the storage volume is spinning or
 116 flash.
 117 Its value is hard coded to 0 indicating flash.
 118 .It Va kern.cam.nda.N.unmapped_io
 119 This variable reports whether the
 120 .Nm
 121 driver accepts unmapped I/O for this unit.
 122 .It Va kern.cam.nda.N.flags
 123 This variable reports the current flags.
 124 .Bl -tag -width 12
 125 .It Va OPEN
 126 The device is open.
 127 .It Va DIRTY
 128 Set when a write to the drive is scheduled.
 129 Cleared after flush commands.
 130 .It Va SCTX_INIT
 131 Internal flag set after
 132 .Xr sysctl 8
 133 nodes have been created.
 134 .El
 135 .It Va kern.cam.nda.N.sort_io_queue
 136 Same as the
 137 .Va kern.cam.nda.sort_io_queue
 138 tunable.
 139 .It Va kern.cam.nda.N.trim_ticks
 140 Writable.
 141 When greater than zero, hold trims for up to this many ticks before sending
 142 to the drive.
 143 Sometimes waiting a little bit to collect more trims to send at one time
 144 improves trim performance.
 145 When 0, no delaying of trims are done.
 146 .It Va kern.cam.nda.N.trim_goal
 147 Writable.
 148 When delaying a bit to collect multiple trims, send the accumulated DSM TRIM to
 149 the drive.
 150 .It Va kern.cam.nda.N.trim_lbas
 151 Total number of LBAs that have been trimmed.
 152 .It Va kern.cam.nda.N.trim_ranges
 153 Total number of LBA ranges that have been trimmed.
 154 .It Va kern.cam.nda.N.trim_count
 155 Total number of trims sent to the hardware.
 156 .It Va kern.cam.nda.N.deletes
 157 Total number of
 158 .Va BIO_DELETE
 159 requests queued to the device.
 160 .El
 161 .Sh NAMESPACE MAPPING
 162 Each
 163 .Xr nvme 4
 164 drive has one or more namespaces associated with it.
 165 One instance of the
 166 .Nm
 167 driver will be created for each of the namespaces on
 168 the drive.
 169 All the
 170 .Nm
 171 nodes for a
 172 .Xr nvme 4
 173 device are at target 0.
 174 However, the namespace ID maps to the CAM lun, as reported
 175 in kernel messages and in the
 176 .Va devlist
 177 sub command of
 178 .Xr camcontrol 8 .
 179 .Pp
 180 Namespaces are managed with the
 181 .Va ns
 182 sub command of
 183 .Xr nvmecontrol 8 .
 184 Not all drives support namespace management,
 185 but all drives support at least one namespace.
 186 Device nodes for
 187 .Nm
 188 will be created and destroyed dynamically as
 189 namespaces are activated or detached.
 190 .Sh FILES
 191 .Bl -tag -width ".Pa /dev/nda*" -compact
 192 .It Pa /dev/nda*
 193 NVMe storage device nodes
 194 .El
 195 .Sh SEE ALSO
 196 .Xr cam 4 ,
 197 .Xr geom 4 ,
 198 .Xr nvd 4 ,
 199 .Xr nvme 4 ,
 200 .Xr gpart 8
 201 .Sh HISTORY
 202 The
 203 .Nm
 204 driver first appeared in
 205 .Fx 12.0 .
 206 .Sh AUTHORS
 207 .An Warner Losh Aq Mt imp@FreeBSD.org