Date: Wed, 10 Oct 2012 21:38:17 +0000 (UTC) From: Jim Harris <jimharris@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r241431 - head/share/man/man4 Message-ID: <201210102138.q9ALcHZ4006784@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: jimharris Date: Wed Oct 10 21:38:17 2012 New Revision: 241431 URL: http://svn.freebsd.org/changeset/base/241431 Log: Add man pages for nvme(4) and nvd(4). Sponsored by: Intel Reviewed by: joel Added: head/share/man/man4/nvd.4 (contents, props changed) head/share/man/man4/nvme.4 (contents, props changed) Modified: head/share/man/man4/Makefile Modified: head/share/man/man4/Makefile ============================================================================== --- head/share/man/man4/Makefile Wed Oct 10 21:37:21 2012 (r241430) +++ head/share/man/man4/Makefile Wed Oct 10 21:38:17 2012 (r241431) @@ -337,7 +337,9 @@ MAN= aac.4 \ nmdm.4 \ nsp.4 \ null.4 \ + ${_nvd.4} \ ${_nve.4} \ + ${_nvme.4} \ ${_nvram.4} \ ${_nvram2env.4} \ ${_nxge.4} \ @@ -758,7 +760,9 @@ _linux.4= linux.4 _ndis.4= ndis.4 _nfe.4= nfe.4 _nfsmb.4= nfsmb.4 +_nvd.4= nvd.4 _nve.4= nve.4 +_nvme.4= nvme.4 _nvram.4= nvram.4 _nxge.4= nxge.4 _virtio.4= virtio.4 Added: head/share/man/man4/nvd.4 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man4/nvd.4 Wed Oct 10 21:38:17 2012 (r241431) @@ -0,0 +1,91 @@ +.\" +.\" Copyright (c) 2012 Intel Corporation +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING +.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGES. +.\" +.\" nvd driver man page. +.\" +.\" Author: Jim Harris <jimharris@FreeBSD.org> +.\" +.\" $FreeBSD$ +.\" +.Dd October 10, 2012 +.Dt NVD 4 +.Os +.Sh NAME +.Nm nvd +.Nd NVM Express disk driver +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device nvme" +.Cd "device nvd" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nvme_load="YES" +nvd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver exposes NVM Express (NVMe) namespaces as disks to the kernel disk +storage API. +It depends on the +.Xr nvme 4 +driver for notification of existing NVMe namespaces and submission of NVM +I/O commands. +.Sh SEE ALSO +.Xr nvme 4 , +.Xr nvmecontrol 8 , +.Xr disk 9 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Intel and originally written by +.An Jim Harris Aq jimharris@FreeBSD.org , +with contributions from Joe Golio at EMC. +.Pp +This man page was written by +.An Jim Harris Aq jimharris@FreeBSD.org . +.Sh BUGS +The +.Nm +driver is considered experimental. +Development and testing have been primarily focused on amd64. +The following areas of development and testing are in progress: +.Bl -bullet +.It +testing on i386 +.It +command timeout error handling +.El + Added: head/share/man/man4/nvme.4 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man4/nvme.4 Wed Oct 10 21:38:17 2012 (r241431) @@ -0,0 +1,175 @@ +.\" +.\" Copyright (c) 2012 Intel Corporation +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING +.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGES. +.\" +.\" nvme driver man page. +.\" +.\" Author: Jim Harris <jimharris@FreeBSD.org> +.\" +.\" $FreeBSD$ +.\" +.Dd October 10, 2012 +.Dt NVME 4 +.Os +.Sh NAME +.Nm nvme +.Nd NVM Express core driver +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device nvme" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nvme_load="YES" +.Ed +.Pp +Most users will also want to enable +.Xr nvd 4 +to surface NVM Express namespaces as disk devices. +Note that in NVM Express terms, a namespace is roughly equivalent to a +SCSI LUN. +.Sh DESCRIPTION +The +.Nm +driver provides support for NVM Express (NVMe) controllers, such as: +.Bl -bullet +.It +Hardware initialization +.It +Per-CPU IO queue pairs +.It +API for registering NVMe namespace consumers such as +.Xr nvd 4 +.It +API for submitting NVM commands to namespaces +.It +Ioctls for controller and namespace configuration and management +.Nm +creates controller devices in the format /dev/nvmeX and namespace devices in +the format /dev/nvmeXnsY. +Note that the NVM Express specification starts numbering namespaces at 1, +not 0, and this driver follows that convention. +.El +.Sh CONFIGURATION +By default, +.Nm +will create an I/O queue pair for each CPU, provided enough MSI-X vectors +can be allocated. +To force a single I/O queue pair shared by all CPUs, set the following +tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.nvme.per_cpu_io_queues=0 +.Ed +.Pp +To force legacy interrupts for all +.Nm +driver instances, set the following tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.nvme.force_intx=1 +.Ed +.Pp +Note that use of INTx implies disabling of per-CPU I/O queue pairs. +.Sh SYSCTL VARIABLES +The following controller-level sysctls are currently implemented: +.Bl -tag -width indent +.It Va dev.nvme.0.int_coal_time +(R/W) Interrupt coalescing timer period in microseconds. Set to 0 to disable. +.It Va dev.nvme.0.int_coal_threshold +(R/W) Interrupt coalescing threshold in number of command completions. +Set to 0 to disable. +.El +.Pp +The following queue pair-level sysctls are currently implemented. +Admin queue sysctls take the format of dev.nvme.0.adminq and I/O queue sysctls +take the format of dev.nvme.0.ioq0. +.Bl -tag -width indent +.It Va dev.nvme.0.ioq0.num_entries +(R) Number of entries in this queue pair's command and completion queue. +.It Va dev.nvme.0.ioq0.num_tr +(R) Number of nvme_tracker structures currently allocated for this queue pair. +.It Va dev.nvme.0.ioq0.num_prp_list +(R) Number of nvme_prp_list structures currently allocated for this queue pair. +.It Va dev.nvme.0.ioq0.sq_head +(R) Current location of the submission queue head pointer as observed by +the driver. +The head pointer is incremented by the controller as it takes commands off +of the submission queue. +.It Va dev.nvme.0.ioq0.sq_tail +(R) Current location of the submission queue tail pointer as observed by +the driver. +The driver increments the tail pointer after writing a command +into the submission queue to signal that a new command is ready to be +processed. +.It Va dev.nvme.0.ioq0.cq_head +(R) Current location of the completion queue head pointer as observed by +the driver. +The driver increments the head pointer after finishing +with a completion entry that was posted by the controller. +.It Va dev.nvme.0.ioq0.num_cmds +(R) Number of commands that have been submitted on this queue pair. +.It Va dev.nvme.0.ioq0.dump_debug +(W) Writing 1 to this sysctl will dump the full contents of the submission +and completion queues to the console. +.El +.Sh SEE ALSO +.Xr nvd 4 , +.Xr pci 4 , +.Xr nvmecontrol 8 , +.Xr disk 9 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Intel and originally written by +.An Jim Harris Aq jimharris@FreeBSD.org , +with contributions from Joe Golio at EMC. +.Pp +This man page was written by +.An Jim Harris Aq jimharris@FreeBSD.org . +.Sh BUGS +The +.Nm +driver is considered experimental. +Development and testing have been primarily focused on amd64. +The following areas of development and testing are in progress: +.Bl -bullet +.It +testing on i386 +.It +asynchronous error reporting +.It +command timeout error handling +.It +controller-level resets +.El
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201210102138.q9ALcHZ4006784>