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 .Dd December 8, 2021
  25 .Dt GENET 4
  26 .Os
  27 .Sh NAME
  28 .Nm genet
  29 .Nd "Raspberry Pi 4 / BCM2711 Gigabit Ethernet controller driver"
  30 .Sh SYNOPSIS
  31 To compile this driver into the kernel,
  32 place the following lines in the
  33 kernel configuration file:
  34 .Bd -ragged -offset indent
  35 .Cd "device miibus"
  36 .Cd "device genet"
  37 .Ed
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 driver supports the BCM2711 Ethernet controller
  42 as found on the Raspberry Pi 4.
  43 .Pp
  44 The following features are supported in the
  45 .Nm
  46 driver in
  47 .Fx :
  48 .Pp
  49 .Bl -item -offset indent -compact
  50 .It
  51 IP/TCP/UDP checksum offload for IPv4 and IPv6
  52 .It
  53 10/100/1000Mbps operation in full-duplex mode
  54 .It
  55 10/100Mbps operation in half-duplex mode
  56 .El
  57 .Pp
  58 Note that the operation of transmit checksum offload is coupled
  59 for IPv4 and IPv6; to disable it, both must be disabled even if both
  60 address families are not in use.
  61 .Pp
  62 The
  63 .Nm
  64 driver supports the following media types:
  65 .Bl -tag -width ".Cm 10baseT/UTP"
  66 .It Cm autoselect
  67 Enable autoselection of the media type and options.
  68 The user can manually override
  69 the autoselected mode by adding media options to
  70 .Xr rc.conf 5 .
  71 .It Cm 10baseT/UTP
  72 Set 10Mbps operation.
  73 The
  74 .Xr ifconfig 8
  75 .Cm mediaopt
  76 option can also be used to select either
  77 .Cm full-duplex
  78 or
  79 .Cm half-duplex
  80 modes.
  81 .It Cm 100baseTX
  82 Set 100Mbps (Fast Ethernet) operation.
  83 The
  84 .Xr ifconfig 8
  85 .Cm mediaopt
  86 option can also be used to select either
  87 .Cm full-duplex
  88 or
  89 .Cm half-duplex
  90 modes.
  91 .It Cm 1000baseT
  92 Set 1000baseT operation over twisted pair.
  93 Only
  94 .Cm full-duplex
  95 mode is supported.
  96 .El
  97 .Pp
  98 The
  99 .Nm
 100 driver supports the following media options set with the
 101 .Cm mediaopt
 102 option to the
 103 .Xr ifconfig 8
 104 command:
 105 .Bl -tag -width ".Cm full-duplex"
 106 .It Cm full-duplex
 107 Force full duplex operation.
 108 .It Cm half-duplex
 109 Force half duplex operation.
 110 .El
 111 .Pp
 112 For more information on configuring this device, see
 113 .Xr ifconfig 8 .
 114 .Sh HARDWARE
 115 The
 116 .Nm
 117 driver supports the Ethernet controller portion of the Broadcom BCM2711
 118 on the Raspberry Pi 4 Model B and related systems.
 119 It utilizes the BCM54213PE PHY.
 120 .Sh LOADER TUNABLES
 121 Tunables can be set at the
 122 .Xr loader 8
 123 prompt before booting the kernel or stored in
 124 .Xr loader.conf 5 .
 125 The following loader tunable variable is available, and is also
 126 available as a read-only
 127 .Xr sysctl 8
 128 variable:
 129 .Bl -tag -width indent
 130 .It Va hw.genet.rx_batch
 131 The maximum number of packets to pass to the link-layer input routine
 132 at one time.
 133 The default is 16.
 134 .El
 135 .Sh SYSCTL VARIABLES
 136 The following variable is available as a
 137 .Xr sysctl 8
 138 variable:
 139 .Bl -tag -width indent
 140 .It Va hw.genet.tx_hdr_min
 141 When the driver is given an output packet in a buffer chain
 142 in which the first buffer contains only the Ethernet header,
 143 the number of bytes of the packet to add to the Ethernet header
 144 in the first buffer.
 145 Certain packets may be lost if this value is too small.
 146 The default value is 56, and is sufficient for the observed cases to date.
 147 .El
 148 .Sh DIAGNOSTICS
 149 The
 150 .Nm
 151 driver has no diagnostics that are likely in normal operation.
 152 However, when the
 153 .Cm debug
 154 option is set with
 155 .Xr ifconfig 8 ,
 156 most failures that cause packet loss in the transmit and receive paths
 157 cause a cryptic diagnostic message naming the failure.
 158 These messages generally make sense only when looking at the driver source.
 159 .Sh SEE ALSO
 160 .Xr altq 4 ,
 161 .Xr arp 4 ,
 162 .Xr miibus 4 ,
 163 .Xr netintro 4 ,
 164 .Xr ng_ether 4 ,
 165 .Xr vlan 4 ,
 166 .Xr ifconfig 8
 167 .Sh HISTORY
 168 The
 169 .Nm
 170 device driver first appeared in
 171 .Fx 13.0 .
 172 .Sh AUTHORS
 173 The
 174 .Nm
 175 driver was written by
 176 .An Mike Karels Aq Mt karels@freebsd.org .
 177 Portions are derived from the bcmgenet driver in
 178 .Nx
 179 by Jared McNeill,
 180 and parts of the structure and common code are from the awg driver
 181 for the Allwinner EMAC by Jared McNeill.