share/man/man4/nvme.4

   1 .\"
   2 .\" Copyright (c) 2012-2013 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 July 9, 2013
  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 to surface NVM Express namespaces as disk devices.
  58 Note that in NVM Express terms, a namespace is roughly equivalent to a
  59 SCSI LUN.
  60 .Sh DESCRIPTION
  61 The
  62 .Nm
  63 driver provides support for NVM Express (NVMe) controllers, such as:
  64 .Bl -bullet
  65 .It
  66 Hardware initialization
  67 .It
  68 Per-CPU IO queue pairs
  69 .It
  70 API for registering NVMe namespace consumers such as
  71 .Xr nvd 4
  72 .It
  73 API for submitting NVM commands to namespaces
  74 .It
  75 Ioctls for controller and namespace configuration and management
  76 .Pp
  77 .Nm
  78 creates controller devices in the format
  79 .Pa /dev/nvmeX
  80 and namespace devices in
  81 the format
  82 .Pa /dev/nvmeXnsY .
  83 Note that the NVM Express specification starts numbering namespaces at 1,
  84 not 0, and this driver follows that convention.
  85 .El
  86 .Sh CONFIGURATION
  87 By default,
  88 .Nm
  89 will create an I/O queue pair for each CPU, provided enough MSI-X vectors
  90 can be allocated.
  91 To force a single I/O queue pair shared by all CPUs, set the following
  92 tunable value in
  93 .Xr loader.conf 5 :
  94 .Bd -literal -offset indent
  95 hw.nvme.per_cpu_io_queues=0
  96 .Ed
  97 .Pp
  98 To force legacy interrupts for all
  99 .Nm
 100 driver instances, set the following tunable value in
 101 .Xr loader.conf 5 :
 102 .Bd -literal -offset indent
 103 hw.nvme.force_intx=1
 104 .Ed
 105 .Pp
 106 Note that use of INTx implies disabling of per-CPU I/O queue pairs.
 107 .Sh SYSCTL VARIABLES
 108 The following controller-level sysctls are currently implemented:
 109 .Bl -tag -width indent
 110 .It Va dev.nvme.0.int_coal_time
 111 (R/W) Interrupt coalescing timer period in microseconds.
 112 Set to 0 to disable.
 113 .It Va dev.nvme.0.int_coal_threshold
 114 (R/W) Interrupt coalescing threshold in number of command completions.
 115 Set to 0 to disable.
 116 .El
 117 .Pp
 118 The following queue pair-level sysctls are currently implemented.
 119 Admin queue sysctls take the format of dev.nvme.0.adminq and I/O queue sysctls
 120 take the format of dev.nvme.0.ioq0.
 121 .Bl -tag -width indent
 122 .It Va dev.nvme.0.ioq0.num_entries
 123 (R) Number of entries in this queue pair's command and completion queue.
 124 .It Va dev.nvme.0.ioq0.num_tr
 125 (R) Number of nvme_tracker structures currently allocated for this queue pair.
 126 .It Va dev.nvme.0.ioq0.num_prp_list
 127 (R) Number of nvme_prp_list structures currently allocated for this queue pair.
 128 .It Va dev.nvme.0.ioq0.sq_head
 129 (R) Current location of the submission queue head pointer as observed by
 130 the driver.
 131 The head pointer is incremented by the controller as it takes commands off
 132 of the submission queue.
 133 .It Va dev.nvme.0.ioq0.sq_tail
 134 (R) Current location of the submission queue tail pointer as observed by
 135 the driver.
 136 The driver increments the tail pointer after writing a command
 137 into the submission queue to signal that a new command is ready to be
 138 processed.
 139 .It Va dev.nvme.0.ioq0.cq_head
 140 (R) Current location of the completion queue head pointer as observed by
 141 the driver.
 142 The driver increments the head pointer after finishing
 143 with a completion entry that was posted by the controller.
 144 .It Va dev.nvme.0.ioq0.num_cmds
 145 (R) Number of commands that have been submitted on this queue pair.
 146 .It Va dev.nvme.0.ioq0.dump_debug
 147 (W) Writing 1 to this sysctl will dump the full contents of the submission
 148 and completion queues to the console.
 149 .El
 150 .Sh SEE ALSO
 151 .Xr nvd 4 ,
 152 .Xr pci 4 ,
 153 .Xr nvmecontrol 8 ,
 154 .Xr disk 9
 155 .Sh HISTORY
 156 The
 157 .Nm
 158 driver first appeared in
 159 .Fx 9.2.
 160 .Sh AUTHORS
 161 .An -nosplit
 162 The
 163 .Nm
 164 driver was developed by Intel and originally written by
 165 .An Jim Harris Aq jimharris@FreeBSD.org ,
 166 with contributions from Joe Golio at EMC.
 167 .Pp
 168 This man page was written by
 169 .An Jim Harris Aq jimharris@FreeBSD.org .