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 38The 39.Nm 40driver provides support for direct access devices, implementing the 41.Tn NVMe 42command protocol, that are attached to the system through a host adapter 43supported by the CAM subsystem. 44.Sh SYSCTL VARIABLES 45The following variables are available as both 46.Xr sysctl 8 47variables and 48.Xr loader 8 49tunables: 50.Bl -tag -width 12 51.It Va hw.nvme.use_nvd 52The 53.Xr nvme 4 54driver will create 55.Nm 56device nodes for block storage when set to 0. 57Create 58.Xr nvd 4 59device nodes for block storage when set to 1. 60See 61.Xr nvd 4 62when set to 1. 63.It Va kern.cam.nda.nvd_compat 64When set to 1, 65.Xr nvd 4 66aliases will be created for all 67.Nm 68devices, including partitions and other 69.Xr geom 4 70providers that take their names from the disk's name. 71.Xr nvd 72devices will not, however, be reported in the 73.Va kern.disks 74.Xr sysctl 8 . 75.It Va kern.cam.nda.sort_io_queue 76This variable determines whether the software queued entries are 77sorted in LBA order or not. 78Sorting is almost always a waste of time. 79The default is to not sort. 80.It Va kern.cam.nda.enable_biospeedup 81This variable determines if the 82.Nm 83devices participate in the speedup protocol. 84When the device participates in the speedup, then when the upper layers 85send a 86.Va BIO_SPEEDUP , 87all current 88.Va BIO_DELETE 89requests not yet sent to the hardware are completed successfully immediate 90without sending them to the hardware. 91Used in low disk space scenarios when the filesystem encounters 92a critical shortage and needs blocks immediately. 93Since trims have maximum benefit when the LBA is unused for a long time, 94skipping the trim when space is needed for immediate writes results in little to 95no excess wear. 96When participation is disabled, 97.Va BIO_SPEEDUP 98requests are ignored. 99.It Va kern.cam.nda.max_trim 100The maximum number of LBA ranges to be collected together for each DSM trims 101send to the hardware. 102Defaults to 256, which is the maximum number of ranges the protocol supports. 103Sometimes poor trim performance can be mitigated by limiting the number of 104ranges sent to the device. 105This value must be between 1 and 256 inclusive. 106.El 107.Pp 108The following report per-device settings, and are read-only unless 109otherwise indicated. 110Replace 111.Va N 112with the device unit number. 113.Bl -tag -width 12 114.It Va kern.cam.nda.N.rotating 115This variable reports whether the storage volume is spinning or 116flash. 117Its value is hard coded to 0 indicating flash. 118.It Va kern.cam.nda.N.unmapped_io 119This variable reports whether the 120.Nm 121driver accepts unmapped I/O for this unit. 122.It Va kern.cam.nda.N.flags 123This variable reports the current flags. 124.Bl -tag -width 12 125.It Va OPEN 126The device is open. 127.It Va DIRTY 128Set when a write to the drive is scheduled. 129Cleared after flush commands. 130.It Va SCTX_INIT 131Internal flag set after 132.Xr sysctl 8 133nodes have been created. 134.El 135.It Va kern.cam.nda.N.sort_io_queue 136Same as the 137.Va kern.cam.nda.sort_io_queue 138tunable. 139.It Va kern.cam.nda.N.trim_ticks 140Writable. 141When greater than zero, hold trims for up to this many ticks before sending 142to the drive. 143Sometimes waiting a little bit to collect more trims to send at one time 144improves trim performance. 145When 0, no delaying of trims are done. 146.It Va kern.cam.nda.N.trim_goal 147Writable. 148When delaying a bit to collect multiple trims, send the accumulated DSM TRIM to 149the drive. 150.It Va kern.cam.nda.N.trim_lbas 151Total number of LBAs that have been trimmed. 152.It Va kern.cam.nda.N.trim_ranges 153Total number of LBA ranges that have been trimmed. 154.It Va kern.cam.nda.N.trim_count 155Total number of trims sent to the hardware. 156.It Va kern.cam.nda.N.deletes 157Total number of 158.Va BIO_DELETE 159requests queued to the device. 160.El 161.Sh NAMESPACE MAPPING 162Each 163.Xr nvme 4 164drive has one or more namespaces associated with it. 165One instance of the 166.Nm 167driver will be created for each of the namespaces on 168the drive. 169All the 170.Nm 171nodes for a 172.Xr nvme 4 173device are at target 0. 174However, the namespace ID maps to the CAM lun, as reported 175in kernel messages and in the 176.Va devlist 177sub command of 178.Xr camcontrol 8 . 179.Pp 180Namespaces are managed with the 181.Va ns 182sub command of 183.Xr nvmecontrol 8 . 184Not all drives support namespace management, 185but all drives support at least one namespace. 186Device nodes for 187.Nm 188will be created and destroyed dynamically as 189namespaces are activated or detached. 190.Sh FILES 191.Bl -tag -width ".Pa /dev/nda*" -compact 192.It Pa /dev/nda* 193NVMe 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 202The 203.Nm 204driver first appeared in 205.Fx 12.0 . 206.Sh AUTHORS 207.An Warner Losh Aq Mt imp@FreeBSD.org 208