svn commit: r338834 - in head/share/man: man4 man9

[Stephen Hurd]

Author: shurd
Date: Thu Sep 20 18:24:32 2018
New Revision: 338834
URL: https://svnweb.freebsd.org/changeset/base/338834

Log:
  Add iflib.4 manpage
  
  The new manpage documents the tunables and statistic sysctls exposed by
  iflib.
  
  Reviewed by:	bcr
  Approved by:	re (gjb)
  Sponsored by:	Limelight Networks
  Differential Revision:	https://reviews.freebsd.org/D16920

Added:
  head/share/man/man4/iflib.4   (contents, props changed)
Modified:
  head/share/man/man4/Makefile
  head/share/man/man4/bnxt.4
  head/share/man/man4/em.4
  head/share/man/man9/iflib.9

Modified: head/share/man/man4/Makefile
==============================================================================
--- head/share/man/man4/Makefile	Thu Sep 20 16:43:58 2018	(r338833)
+++ head/share/man/man4/Makefile	Thu Sep 20 18:24:32 2018	(r338834)
@@ -202,6 +202,7 @@ MAN=	aac.4 \
 	icmp6.4 \
 	ida.4 \
 	if_ipsec.4 \
+	iflib.4 \
 	ifmib.4 \
 	ig4.4 \
 	igmp.4 \

Modified: head/share/man/man4/bnxt.4
==============================================================================
--- head/share/man/man4/bnxt.4	Thu Sep 20 16:43:58 2018	(r338833)
+++ head/share/man/man4/bnxt.4	Thu Sep 20 18:24:32 2018	(r338834)
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 9, 2017
+.Dd September 20, 2018
 .Dt BNXT 4
 .Os
 .Sh NAME
@@ -110,7 +110,7 @@ These variables must be set before loading the driver,
 or through the use of
 .Xr kenv 1 .
 These are provided by the
-.Xr iflib 9
+.Xr iflib 4
 framework, and might be better documented there.
 .Bl -tag -width indent
 .It Va dev.bnxt.X.iflib.override_nrxds

Modified: head/share/man/man4/em.4
==============================================================================
--- head/share/man/man4/em.4	Thu Sep 20 16:43:58 2018	(r338833)
+++ head/share/man/man4/em.4	Thu Sep 20 18:24:32 2018	(r338834)
@@ -31,7 +31,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 22, 2017
+.Dd September 20, 2018
 .Dt EM 4
 .Os
 .Sh NAME
@@ -298,6 +298,7 @@ issue to
 .Sh SEE ALSO
 .Xr altq 4 ,
 .Xr arp 4 ,
+.Xr iflib 4 ,
 .Xr led 4 ,
 .Xr netintro 4 ,
 .Xr ng_ether 4 ,

Added: head/share/man/man4/iflib.4
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/share/man/man4/iflib.4	Thu Sep 20 18:24:32 2018	(r338834)
@@ -0,0 +1,195 @@
+.\" $FreeBSD$
+.Dd September 20, 2018
+.Dt IFLIB 4
+.Os
+.Sh NAME
+.Nm iflib
+.Nd Network Interface Driver Framework
+.Sh SYNOPSIS
+.Cd "device pci"
+.Cd "device iflib"
+.Sh DESCRIPTION
+.Nm
+is a framework for network interface drivers for
+.Fx .
+It is designed to remove a large amount of the boilerplate that is often
+needed for modern network interface devices, allowing driver authors to
+focus on the specific code needed for their hardware.
+This allows for a shared set of
+.Xr sysctl 8
+names, rather than each driver naming them individually.
+.Sh SYSCTL VARIABLES
+These variables must be set before loading the driver, either via
+.Xr loader.conf 5
+or through the use of
+.Xr kenv 1 .
+They are all prefixed by
+.Va dev.X.Y.iflib.
+where X is the driver name, and Y is the instance number.
+.Bl -tag -width indent
+.It Va override_nrxds
+Override the number of RX descriptors for each queue.
+The value is a comma separated list of positive integers.
+Some drivers only use a single value, but others may use more.
+These numbers must be powers of two, and zero means to use the default.
+Individual drivers may have additional restrictions on allowable values.
+Defaults to all zeros.
+.It Va override_ntxds
+Override the number of TX descriptors for each queue.
+The value is a comma separated list of positive integers.
+Some drivers only use a single value, but others may use more.
+These numbers must be powers of two, and zero means to use the default.
+Individual drivers may have additional restrictions on allowable values.
+Defaults to all zeros.
+.It Va override_qs_enable
+When set, allows the number of transmit and receive queues to be different.
+If not set, the lower of the number of TX or RX queues will be used for both.
+.It Va override_nrxqs
+Set the number of RX queues.
+If zero, the number of RX queues is derived from the number of cores on the
+socket connected to the controller.
+Defaults to 0.
+.It Va override_ntxqs
+Set the number of TX queues.
+If zero, the number of TX queues is derived from the number of cores on the
+socket connected to the controller.
+.It Va disable_msix
+Disables MSI-X interrupts for the device.
+.El
+.Pp
+These
+.Xr sysctl 8
+variables can be changed at any time:
+.Bl -tag -width indent
+.It Va tx_abdicate
+Controls how the transmit ring is serviced.
+If set to zero, when a frame is submitted to the transmission ring, the same
+task that is submitting it will service the ring unless there's already a
+task servicing the TX ring.
+This ensures that whenever there is a pending transmission,
+the transmit ring is being serviced.
+This results in higher transmit throughput.
+If set to a non-zero value, task returns immediately and the transmit
+ring is serviced by a different task.
+This returns control to the caller faster and under high receive load,
+may result in fewer dropped RX frames.
+.It Va rx_budget
+Sets the maximum number of frames to be received at a time.
+Zero (the default) indicates the default (currently 16) should be used.
+.El
+.Pp
+There are also some global sysctls which can change behaviour for all drivers,
+and may be changed at any time.
+.Bl -tag -width indent
+.It Va net.iflib.min_tx_latency
+If this is set to a non-zero value, iflib will avoid any attempt to combine
+multiple transmits, and notify the hardware as quickly as possible of
+new descriptors.
+This will lower the maximum throughput, but will also lower transmit latency.
+.It Va net.iflib.no_tx_batch
+Some NICs allow processing completed transmit descriptors in batches.
+Doing so usually increases the transmit throughput by reducing the number of
+transmit interrupts.
+Setting this to a non-zero value will disable the use of this feature.
+.El
+.Pp
+These
+.Xr sysctl 8
+variables are read-only:
+.Bl -tag -width indent
+.It Va driver_version
+A string indicating the internal version of the driver.
+.El
+.Pp
+There are a number of queue state
+.Xr sysctl 8
+variables as well:
+.Bl -tag -width indent
+.It Va txqZ
+The following are repeated for each transmit queue, where Z is the transmit
+queue instance number:
+.Bl -tag -width indent
+.It Va r_abdications
+Number of consumer abdications in the MP ring for this queue.
+An abdication occurs on every ring submission when tx_abdicate is true.
+.It Va r_restarts
+Number of consumer restarts in the MP ring for this queue.
+A restart occurs when an attempt to drain a non-empty ring fails,
+and the ring is already in the STALLED state.
+.It Va r_stalls
+Number of consumer stalls in the MP ring for this queue.
+A stall occurs when an attempt to drain a non-empty ring fails.
+.It Va r_starts
+Number of normal consumer starts in the MP ring for this queue.
+A start occurs when the MP ring transitions from IDLE to BUSY.
+.It Va r_drops
+Number of drops in the MP ring for this queue.
+A drop occurs when there is an attempt to add an entry to an MP ring with
+no available space.
+.It Va r_enqueues
+Number of entries which have been enqueued to the MP ring for this queue.
+.It Va ring_state
+MP (soft) ring state.
+This privides a snapshot of the current MP ring state, including the producer
+head and tail indexes, the consumer index, and the state.
+The state is one of "IDLE", "BUSY",
+"STALLED", or "ABDICATED".
+.It Va txq_cleaned
+The number of transmit descriptors which have been reclaimed.
+Total cleaned.
+.It Va txq_processed
+The number of transmit descriptors which have been processed, but may not yet
+have been reclaimed.
+.It Va txq_in_use
+Descriptors which have been added to the transmit queue,
+but have not yet been cleaned.
+This value will include both untransmitted descriptors as well as descriptors
+which have been processed.
+.It Va txq_cidx_processed
+The transmit queue consumer index of the next descriptor to process.
+.It Va txq_cidx
+The transmit queue consumer index of the oldest descriptor to reclaim.
+.It Va txq_pidx
+The transmit queue producer index where the next descriptor to transmit will
+be inserted.
+.It Va no_tx_dma_setup
+Number of times DMA mapping a transmit mbuf failed for reasons other than EFBIG.
+.It Va txd_encap_efbig
+Number of times DMA mapping a transmit mbuf failed due to requiring too many
+segments.
+.It Va tx_map_failed
+Number of times DMA mapping a transmit mbuf failed for any reason
+(sum of no_tx_dma_setup and txd_encap_efbig)
+.It Va no_desc_avail
+Number of times a descriptor couldn't be added to the transmit ring because
+the transmit ring was full.
+.It Va mbuf_defrag_failed
+Number of times both
+.Xr m_collapse 9
+and
+.Xr m_defrag 9
+failed after an EFBIG error
+result from DMA mapping a transmit mbuf.
+.It Va m_pullups
+Number of times m_pullup was called attempting to parse a header.
+.It Va mbuf_defrag
+Number of times m_defrag was called.
+.El
+.It Va rxqZ
+The following are repeated for each receive queue, where Z is the
+receive queue instance number:
+.Bl -tag -width indent
+.It Va rxq_fl0.credits
+Credits currently available in the receive ring.
+.It Va rxq_fl0.cidx
+Current receive ring consumer index.
+.It Va rxq_fl0.pidx
+Current receive ring producer index.
+.El
+.El
+Additional OIDs useful for driver and iflib development are exposed when the
+INVARIANTS and/or WITNESS options are enabled in the kernel.
+.Sh SEE ALSO
+.Xr iflib 9
+.Sh HISTORY
+This framework was introduced in 11.0.

Modified: head/share/man/man9/iflib.9
==============================================================================
--- head/share/man/man9/iflib.9	Thu Sep 20 16:43:58 2018	(r338833)
+++ head/share/man/man9/iflib.9	Thu Sep 20 18:24:32 2018	(r338834)
@@ -1,5 +1,5 @@
 .\" $FreeBSD$
-.Dd May 3, 2018
+.Dd September 20, 2018
 .Dt IFLIB 9
 .Os
 .Sh NAME
@@ -32,6 +32,7 @@ Device-dependent transmit and receive functions, used 
 .Nm
 based drivers.
 .Sh SEE ALSO
+.Xr iflib 4 ,
 .Xr iflibdd 9 ,
 .Xr iflibdi 9 ,
 .Xr iflibtxrx 9 ,