svn commit: r253289 - stable/9/share/man/man4

Jim Harris jimharris at FreeBSD.org
Fri Jul 12 22:01:19 UTC 2013 

Author: jimharris
Date: Fri Jul 12 22:01:18 2013
New Revision: 253289
URL: http://svnweb.freebsd.org/changeset/base/253289

Log:
  MFC r241431:
  
  Add man pages for nvme(4) and nvd(4).
  
  Approved by:	re (kib)

Added:
  stable/9/share/man/man4/nvd.4
     - copied unchanged from r241431, head/share/man/man4/nvd.4
  stable/9/share/man/man4/nvme.4
     - copied unchanged from r241431, head/share/man/man4/nvme.4
Modified:
  stable/9/share/man/man4/Makefile
Directory Properties:
  stable/9/share/man/man4/   (props changed)

Modified: stable/9/share/man/man4/Makefile
==============================================================================
--- stable/9/share/man/man4/Makefile	Fri Jul 12 21:36:29 2013	(r253288)
+++ stable/9/share/man/man4/Makefile	Fri Jul 12 22:01:18 2013	(r253289)
@@ -329,7 +329,9 @@ MAN=	aac.4 \
 	nmdm.4 \
 	nsp.4 \
 	null.4 \
+	${_nvd.4} \
 	${_nve.4} \
+	${_nvme.4} \
 	${_nvram.4} \
 	${_nvram2env.4} \
 	${_nxge.4} \
@@ -742,7 +744,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

Copied: stable/9/share/man/man4/nvd.4 (from r241431, head/share/man/man4/nvd.4)
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ stable/9/share/man/man4/nvd.4	Fri Jul 12 22:01:18 2013	(r253289, copy of r241431, head/share/man/man4/nvd.4)
@@ -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 at 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 at FreeBSD.org ,
+with contributions from Joe Golio at EMC.
+.Pp
+This man page was written by
+.An Jim Harris Aq jimharris at 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
+

Copied: stable/9/share/man/man4/nvme.4 (from r241431, head/share/man/man4/nvme.4)
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ stable/9/share/man/man4/nvme.4	Fri Jul 12 22:01:18 2013	(r253289, copy of r241431, head/share/man/man4/nvme.4)
@@ -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 at 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 at FreeBSD.org , 
+with contributions from Joe Golio at EMC.
+.Pp
+This man page was written by
+.An Jim Harris Aq jimharris at 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

More information about the svn-src-stable-9 mailing list