share/man/man4/genet.4

   1 .\" Copyright (c) 2021 Michael J. Karels
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  15 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  22 .\" SUCH DAMAGE.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd December 8, 2021
  27 .Dt GENET 4
  28 .Os
  29 .Sh NAME
  30 .Nm genet
  31 .Nd "Raspberry Pi 4 / BCM2711 Gigabit Ethernet controller driver"
  32 .Sh SYNOPSIS
  33 To compile this driver into the kernel,
  34 place the following lines in the
  35 kernel configuration file:
  36 .Bd -ragged -offset indent
  37 .Cd "device miibus"
  38 .Cd "device genet"
  39 .Ed
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 driver supports the BCM2711 Ethernet controller
  44 as found on the Raspberry Pi 4.
  45 .Pp
  46 The following features are supported in the
  47 .Nm
  48 driver in
  49 .Fx :
  50 .Pp
  51 .Bl -item -offset indent -compact
  52 .It
  53 IP/TCP/UDP checksum offload for IPv4 and IPv6
  54 .It
  55 10/100/1000Mbps operation in full-duplex mode
  56 .It
  57 10/100Mbps operation in half-duplex mode
  58 .El
  59 .Pp
  60 Note that the operation of transmit checksum offload is coupled
  61 for IPv4 and IPv6; to disable it, both must be disabled even if both
  62 address families are not in use.
  63 .Pp
  64 The
  65 .Nm
  66 driver supports the following media types:
  67 .Bl -tag -width ".Cm 10baseT/UTP"
  68 .It Cm autoselect
  69 Enable autoselection of the media type and options.
  70 The user can manually override
  71 the autoselected mode by adding media options to
  72 .Xr rc.conf 5 .
  73 .It Cm 10baseT/UTP
  74 Set 10Mbps operation.
  75 The
  76 .Xr ifconfig 8
  77 .Cm mediaopt
  78 option can also be used to select either
  79 .Cm full-duplex
  80 or
  81 .Cm half-duplex
  82 modes.
  83 .It Cm 100baseTX
  84 Set 100Mbps (Fast Ethernet) operation.
  85 The
  86 .Xr ifconfig 8
  87 .Cm mediaopt
  88 option can also be used to select either
  89 .Cm full-duplex
  90 or
  91 .Cm half-duplex
  92 modes.
  93 .It Cm 1000baseT
  94 Set 1000baseT operation over twisted pair.
  95 Only
  96 .Cm full-duplex
  97 mode is supported.
  98 .El
  99 .Pp
 100 The
 101 .Nm
 102 driver supports the following media options set with the
 103 .Cm mediaopt
 104 option to the
 105 .Xr ifconfig 8
 106 command:
 107 .Bl -tag -width ".Cm full-duplex"
 108 .It Cm full-duplex
 109 Force full duplex operation.
 110 .It Cm half-duplex
 111 Force half duplex operation.
 112 .El
 113 .Pp
 114 For more information on configuring this device, see
 115 .Xr ifconfig 8 .
 116 .Sh HARDWARE
 117 The
 118 .Nm
 119 driver supports the Ethernet controller portion of the Broadcom BCM2711
 120 on the Raspberry Pi 4 Model B and related systems.
 121 It utilizes the BCM54213PE PHY.
 122 .Sh LOADER TUNABLES
 123 Tunables can be set at the
 124 .Xr loader 8
 125 prompt before booting the kernel or stored in
 126 .Xr loader.conf 5 .
 127 The following loader tunable variable is available, and is also
 128 available as a read-only
 129 .Xr sysctl 8
 130 variable:
 131 .Bl -tag -width indent
 132 .It Va hw.genet.rx_batch
 133 The maximum number of packets to pass to the link-layer input routine
 134 at one time.
 135 The default is 16.
 136 .El
 137 .Sh SYSCTL VARIABLES
 138 The following variable is available as a
 139 .Xr sysctl 8
 140 variable:
 141 .Bl -tag -width indent
 142 .It Va hw.genet.tx_hdr_min
 143 When the driver is given an output packet in a buffer chain
 144 in which the first buffer contains only the Ethernet header,
 145 the number of bytes of the packet to add to the Ethernet header
 146 in the first buffer.
 147 Certain packets may be lost if this value is too small.
 148 The default value is 56, and is sufficient for the observed cases to date.
 149 .El
 150 .Sh DIAGNOSTICS
 151 The
 152 .Nm
 153 driver has no diagnostics that are likely in normal operation.
 154 However, when the
 155 .Cm debug
 156 option is set with
 157 .Xr ifconfig 8 ,
 158 most failures that cause packet loss in the transmit and receive paths
 159 cause a cryptic diagnostic message naming the failure.
 160 These messages generally make sense only when looking at the driver source.
 161 .Sh SEE ALSO
 162 .Xr altq 4 ,
 163 .Xr arp 4 ,
 164 .Xr miibus 4 ,
 165 .Xr netintro 4 ,
 166 .Xr ng_ether 4 ,
 167 .Xr vlan 4 ,
 168 .Xr ifconfig 8
 169 .Sh HISTORY
 170 The
 171 .Nm
 172 device driver first appeared in
 173 .Fx 13.0 .
 174 .Sh AUTHORS
 175 The
 176 .Nm
 177 driver was written by
 178 .An Mike Karels Aq Mt karels@freebsd.org .
 179 Portions are derived from the bcmgenet driver in
 180 .Nx
 181 by Jared McNeill,
 182 and parts of the structure and common code are from the awg driver
 183 for the Allwinner EMAC by Jared McNeill.