feat: Added FreeBSD man pages

1 files changed, 294 insertions, 0 deletions

diff --git a/static/freebsd/man4/nvme.4 b/static/freebsd/man4/nvme.4
new file mode 100644
index 00000000..76960a7e
--- /dev/null
+++ b/static/freebsd/man4/nvme.4
@@ -0,0 +1,294 @@
+.\"
+.\" Copyright (c) 2012-2016 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>
+.\"
+.Dd June 6, 2020
+.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
+or
+.Xr nda 4
+to expose NVM Express namespaces as disk devices which can be
+partitioned.
+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
+or
+.Xr nda 4
+.It
+API for submitting NVM commands to namespaces
+.It
+Ioctls for controller and namespace configuration and management
+.El
+.Pp
+The
+.Nm
+driver creates controller device nodes in the format
+.Pa /dev/nvmeX
+and namespace device nodes in
+the format
+.Pa /dev/nvmeXnsY .
+Note that the NVM Express specification starts numbering namespaces at 1,
+not 0, and this driver follows that convention.
+.Sh CONFIGURATION
+By default,
+.Nm
+will create an I/O queue pair for each CPU, provided enough MSI-X vectors
+and NVMe queue pairs can be allocated.
+If not enough vectors or queue
+pairs are available, nvme(4) will use a smaller number of queue pairs and
+assign multiple CPUs per queue pair.
+.Pp
+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 assign more than one CPU per I/O queue pair, thereby reducing the number
+of MSI-X vectors consumed by the device, set the following tunable value in
+.Xr loader.conf 5 :
+.Bd -literal -offset indent
+hw.nvme.min_cpus_per_ioq=X
+.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.
+.Pp
+To control maximum amount of system RAM in bytes to use as Host Memory
+Buffer for capable devices, set the following tunable:
+.Bd -literal -offset indent
+hw.nvme.hmb_max
+.Ed
+.Pp
+The default value is 5% of physical memory size per device.
+.Pp
+To enable Autonomous Power State Transition (APST), set the following
+tunable value in
+.Xr loader.conf 5 :
+.Bd -literal -offset indent
+hw.nvme.apst_enable=1
+.Ed
+.Pp
+The default vendor-provided settings, if any, will be applied.
+To override this, set the following tunable:
+.Bd -literal -offset indent
+hw.nvme.apst_data
+.Ed
+.Pp
+The string must contain up to 32 encoded integers, e.g. "0x6418 0
+0 0x3e820".
+Each value corresponds to a specific available power state starting
+from the lowest, and defines the target state (bits 3..7) to
+transition to, as well as the idle time in milliseconds (bits 8..31)
+to wait before that transition.
+Bits 0..2 must be zero.
+.Pp
+The
+.Xr nvd 4
+driver is used to provide a disk driver to the system by default.
+The
+.Xr nda 4
+driver can also be used instead.
+The
+.Xr nvd 4
+driver performs better with smaller transactions and few TRIM
+commands.
+It sends all commands directly to the drive immediately.
+The
+.Xr nda 4
+driver performs better with larger transactions and also collapses
+TRIM commands giving better performance.
+It can queue commands to the drive; combine
+.Dv BIO_DELETE
+commands into a single trip; and
+use the CAM I/O scheduler to bias one type of operation over another.
+To select the
+.Xr nda 4
+driver, set the following tunable value in
+.Xr loader.conf 5 :
+.Bd -literal -offset indent
+hw.nvme.use_nvd=0
+.Ed
+.Pp
+This value may also be set in the kernel config file with
+.Bd -literal -offset indent
+.Cd options NVME_USE_NVD=0
+.Ed
+.Pp
+When there is an error,
+.Nm
+prints only the most relevant information about the command by default.
+To enable dumping of all information about the command, set the following tunable
+value in
+.Xr loader.conf 5 :
+.Bd -literal -offset indent
+hw.nvme.verbose_cmd_dump=1
+.Ed
+.Pp
+Prior versions of the driver reset the card twice on boot.
+This proved to be unnecessary and inefficient, so the driver now resets drive
+controller only once.
+The old behavior may be restored in the kernel config file with
+.Bd -literal -offset indent
+.Cd options NVME_2X_RESET
+.Ed
+.Sh SYSCTL VARIABLES
+The following controller-level sysctls are currently implemented:
+.Bl -tag -width indent
+.It Va dev.nvme.0.num_cpus_per_ioq
+(R) Number of CPUs associated with each I/O queue pair.
+.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
+.Pp
+In addition to the typical pci attachment, the
+.Nm
+driver supports attaching to a
+.Xr ahci 4
+device.
+Intel's Rapid Storage Technology (RST) hides the nvme device
+behind the AHCI device due to limitations in Windows.
+However, this effectively hides it from the
+.Fx
+kernel.
+To work around this limitation,
+.Fx
+detects that the AHCI device supports RST and when it is enabled.
+See
+.Xr ahci 4
+for more details.
+.Sh DIAGNOSTICS
+.Bl -diag
+.It "nvme%d: System interrupt issues?"
+The driver found a timed-out transaction had a pending completion record,
+indicating an interrupt had not been delivered.
+The system is either not configuring interrupts properly, or the system drops
+them under load.
+This message will appear at most once per boot per controller.
+.El
+.Sh SEE ALSO
+.Xr nda 4 ,
+.Xr nvd 4 ,
+.Xr pci 4 ,
+.Xr nvmecontrol 8 ,
+.Xr disk 9
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Fx 9.2 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+driver was developed by Intel and originally written by
+.An Jim Harris Aq Mt jimharris@FreeBSD.org ,
+with contributions from
+.An Joe Golio
+at EMC.
+.Pp
+This man page was written by
+.An Jim Harris Aq Mt jimharris@FreeBSD.org .