xref: /dflybsd-src/share/man/man4/bnx.4 (revision fb3c2c0caaaa0e5d800e088b7dd7983e9ab009ec)

.\"
.\" Copyright (c) 2012 The DragonFly Project.  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.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific, prior written permission.
.\"
.\" 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 MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, 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 DAMAGE.
.\"
.Dd May 13, 2017
.Dt BNX 4
.Os
.Sh NAME
.Nm bnx
.Nd "Broadcom BCM57785/BCM5718 families 10/100/Gigabit Ethernet device"
.Sh SYNOPSIS
.Cd "device miibus"
.Cd "device bnx"
.Pp
Alternatively, to load the driver as a module at boot time, place the
following line in
.Pa /boot/loader.conf :
.Bd -literal -offset indent
if_bnx_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
driver supports the PCIe Ethernet adapters based on
Broadcom BCM57785/BCM5718 families chips.
.Pp
The following features are supported in the
.Nm
driver:
.Pp
.Bl -item -offset indent -compact
.It
IP/TCP/UDP checksum offloading
.It
TCP segmentation offloading (TSO)
.It
VLAN tag stripping and inserting
.It
Interrupt coalescing
.It
Receive Side Scaling (RSS),
up to 4 reception queues
.It
Multiple vector MSI-X
.It
Multiple transmission queues
(BCM5717C,
BCM5719 and BCM5720 only),
up to 4 transmission queues
.El
.Pp
By default,
the
.Nm
driver will try enabling as many reception queues as are allowed
by the number of CPUs in the system.
For BCM5717C,
BCM5719 and BCM5720,
in addition to the reception queues,
by default,
the
.Nm
driver will try enabling as many transmission queues as are allowed
by the number of CPUs in the system
and the number of enabled reception queues.
If multiple transmission queues are enabled,
the round-robin arbitration is performed among the transmission queues.
It should be noted that
if both TSO and multiple transmission queues are enabled,
the round-robin arbitration between transmission queues is done
at the TSO packet boundary.
.Pp
The
.Nm
driver supports the following
.Ar media
types:
.Pp
.Bl -tag -width 10baseT/UTP -compact
.It Cm autoselect
Enable autoselection of the media types and options
.Pp
.It Cm 10baseT/UTP
Set 10Mbps operation.
The
.Ar mediaopt
option can also be used to select either
.Ar full-duplex
or
.Ar half-duplex
modes.
.Pp
.It Cm 100baseTX
Set 100Mbps (Fast Ethernet) operation.
The
.Ar mediaopt
option can also be used to select either
.Ar full-duplex
or
.Ar half-duplex
modes.
.Pp
.It Cm 1000baseT
Set 1000Mbps (Gigabit Ethernet) operation.
The
.Ar mediaopt
option can only be set
.Ar full-duplex
mode.
.El
.Pp
The
.Nm
driver supports the following
.Ar media
options:
.Pp
.Bl -tag -width full-duplex -compact
.It Cm full-duplex
Force full duplex operation.
.Pp
.It Cm half-duplex
Force half duplex operation.
.El
.Pp
Note that the 1000baseT media type is only available
if it is supported by the adapter.
For more information on configuring this device,
see
.Xr ifconfig 8 .
The
.Nm
driver supports
.Xr polling 4 .
.Sh HARDWARE
The
.Nm
driver supports Gigabit Ethernet adapters and Fast Ethernet adapters based on
the Broadcom BCM57785/BCM5718 families chips:
.Pp
.Bl -bullet -compact
.It
Broadcom BCM5717 Gigabit Ethernet
.It
Broadcom BCM5717C Gigabit Ethernet
.It
Broadcom BCM5718 Gigabit Ethernet
.It
Broadcom BCM5719 Gigabit Ethernet
.It
Broadcom BCM5720 Gigabit Ethernet
.It
Broadcom BCM5725 Gigabit Ethernet
.It
Broadcom BCM5727 Gigabit Ethernet
.It
Broadcom BCM5762 Gigabit Ethernet
.It
Broadcom BCM57761 Gigabit Ethernet
.It
Broadcom BCM57762 Gigabit Ethernet
.It
Broadcom BCM57765 Gigabit Ethernet
.It
Broadcom BCM57766 Gigabit Ethernet
.It
Broadcom BCM57781 Gigabit Ethernet
.It
Broadcom BCM57782 Gigabit Ethernet
.It
Broadcom BCM57785 Gigabit Ethernet
.It
Broadcom BCM57786 Gigabit Ethernet
.It
Broadcom BCM57791 Fast Ethernet
.It
Broadcom BCM57795 Fast Ethernet
.El
.Sh TUNABLES
.Em X
is the device unit number.
.Bl -tag -width ".Va hw.bnxX.npoll.offset"
.It Va hw.bnx.rx_rings Va hw.bnxX.rx_rings
If MSI-X is used,
this tunable specifies the number of reception queues to be enabled.
Maximum allowed value for these tunables is 4 and
it must be power of 2 aligned.
Setting these tunables to 0 allows the driver to enable as many reception queues
as allowed by the number of CPUs.
.It Va hw.bnx.tx_rings Va hw.bnxX.tx_rings
For BCM5717C,
BCM5719 and BCM5720,
if MSI-X is used,
this tunable specifies the number of transmission queues to be enabled.
Maximum allowed value for these tunables is 4,
it must be power of 2 aligned
and it must be less than or equal to the number of reception queues enabled.
Setting these tunables to 0 allows the driver to enable as many transmission queues
as allowed by the number of CPUs and number reception queues enabled.
.It Va hw.bnx.msix.enable Va hw.bnxX.msix.enable
By default,
the driver will use MSI-X
if it is supported.
This behaviour can be turned off by setting this tunable to 0.
.It Va hw.bnx.msi.enable Va hw.bnxX.msi.enable
If MSI-X is disabled and MSI is supported,
the driver will use MSI.
This behavior can be turned off by setting this tunable to 0.
.It Va hw.bnxX.msi.cpu
If MSI is used, it specifies the MSI's target CPU.
.El
.Sh MIB Variables
A number of per-interface variables are implemented in the
.Va dev.bnx. Ns Em X
branch of the
.Xr sysctl 3
MIB.
.Bl -tag -width "rx_coal_bds_poll"
.It Va rx_rings
Number of reception queues enabled (read-only).
Use the tunable
.Va hw.bnx.rx_rings
or
.Va hw.bnxX.rx_rings
to configure it.
.It Va tx_rings
Number of transmission queues enabled (read-only).
Use the tunable
.Va hw.bnx.tx_rings
or
.Va hw.bnxX.tx_rings
to configure it.
.It Va rx_coal_ticks
How often status block should be updated and interrupt should be generated
by the device,
due to receiving packets.
It is used together with
.Va rx_coal_bds
to achieve RX interrupt moderation.
Default value is 150 (microseconds).
.It Va tx_coal_ticks
How often status block should be updated and interrupt should be generated
by the device,
due to sending packets.
It is used together with
.Va tx_coal_bds
to achieve TX interrupt moderation.
Default value is 1023 (microseconds).
.It Va rx_coal_bds
Maximum number of BDs which must be received by the device
before the device updates the status block and generates interrupt.
It is used together with
.Va rx_coal_ticks
to achieve RX interrupt moderation.
Default value is 0 (disabled).
.It Va rx_coal_bds_poll
Maximum number of BDs which must be received by the device
before the device updates the status block during
.Xr polling 4 .
It is used together with
.Va rx_coal_ticks
to reduce the frequency of status block updating due to RX.
Default value is 32.
.It Va tx_coal_bds
Maximum number of sending BDs which must be processed by the device
before the device updates the status block and generates interrupt.
It is used together with
.Va tx_coal_ticks
to achieve TX interrupt moderation.
Default value is 128.
.It Va tx_coal_bds_poll
Maximum number of sending BDs which must be processed by the device
before the device updates the status block during
.Xr polling 4 .
It is used together with
.Va tx_coal_ticks
to reduce the frequency of status block updating due to TX.
Default value is 64.
.It Va force_defrag
Force defragment the sending mbuf chains,
if the mbuf chain is not a TSO segment and contains more than 1 mbufs.
This improves transmission performance on certain low end chips,
however,
this also increases CPU load.
Default value is 0 (disabled).
.It Va tx_wreg
The number of transmission descriptors should be setup before the hardware
register is written.
Setting this value too high will have negative effect
on transmission timeliness.
Setting this value too low will hurt overall transmission performance
due to the frequent hardware register writing.
Default value is 8.
.It Va std_refill
Number of packets should be received
before the standard reception producer ring is refilled.
Setting this value too low will cause extra thread scheduling cost.
Setting this value too high will make chip drop incoming packets.
Default value is 128 / number of reception queues.
.It Va rx_coal_bds_int
Maximum number of BDs which must be received by the device
before the device updates the status block
during host interrupt processing.
Default value is 80.
.It Va tx_coal_bds_int
Maximum number of sending BDs which must be processed by the device
before the device updates the status block
during host interrupt processing.
Default value is 64.
.It Va norxbds
Number of times the standard reception producer ring is short
of reception BDs.
If this value grows fast,
it is usually an indication that
.Va std_refill
is set too high.
.It Va errors
Number of errors, both critical and non-critical, happened.
.El
.Sh SEE ALSO
.Xr arp 4 ,
.Xr bge 4 ,
.Xr ifmedia 4 ,
.Xr miibus 4 ,
.Xr netintro 4 ,
.Xr ng_ether 4 ,
.Xr polling 4 ,
.Xr vlan 4 ,
.Xr ifconfig 8
.Sh HISTORY
The
.Nm
device driver first appeared in
.Dx 3.1 .
.Sh AUTHORS
.An -nosplit
The
.Nm
driver was based on
.Xr bge 4
written by
.An Bill Paul Aq Mt wpaul@windriver.com .
.An Sepherosa Ziehau
added receive side scaling,
multiple transmission queues
and multiple MSI-X support to
.Dx .