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