share/man/man4/cgem.4

   1 .\"
   2 .\" Copyright (c) 2014 Thomas Skibo <thomasskibo@yahoo.com>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. The name of the author may not be used to endorse or promote products
  11 .\"    derived from this software without specific prior written permission.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd January 10, 2021
  26 .Dt CGEM 4
  27 .Os
  28 .Sh NAME
  29 .Nm cgem
  30 .Nd "Cadence GEM Gigabit Ethernet driver"
  31 .Sh SYNOPSIS
  32 To compile this driver into the kernel,
  33 place the following lines in your
  34 kernel configuration file:
  35 .Bd -ragged -offset indent
  36 .Cd "device ether"
  37 .Cd "device miibus"
  38 .Cd "device cgem"
  39 .Ed
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 driver provides support for the Cadence GEM (Gigabit Ethernet MAC).
  44 The Cadence GEM is used in some SoC (System on a Chip) devices such as
  45 the Xilinx Zynq-7000, the Xilinx Zynq UltraScale+, and the SiFive
  46 HiFive Unleashed.
  47 .Pp
  48 The
  49 .Nm
  50 driver supports the following media types:
  51 .Bl -tag -width ".Cm 10baseT/UTP"
  52 .It Cm autoselect
  53 Enable autoselection of the media type and options.
  54 The user can manually override
  55 the autoselected mode using
  56 .Xr ifconfig 8
  57 or by adding media options to
  58 .Xr rc.conf 5 .
  59 .It Cm 10baseT/UTP
  60 Set 10Mbps operation.
  61 The
  62 .Xr ifconfig 8
  63 .Cm mediaopt
  64 option can also be used to select either
  65 .Cm full-duplex
  66 or
  67 .Cm half-duplex
  68 modes.
  69 .It Cm 100baseTX
  70 Set 100Mbps (Fast Ethernet) operation.
  71 The
  72 .Xr ifconfig 8
  73 .Cm mediaopt
  74 option can also be used to select either
  75 .Cm full-duplex
  76 or
  77 .Cm half-duplex
  78 modes.
  79 .It Cm 1000baseT
  80 Set 1000Mbps (Gigabit Ethernet) operation over twisted pair.
  81 The GEM supports 1000Mbps in
  82 .Cm full-duplex
  83 mode only.
  84 .El
  85 .Pp
  86 The
  87 .Nm
  88 driver supports the following media options:
  89 .Bl -tag -width ".Cm full-duplex"
  90 .It Cm full-duplex
  91 Force full-duplex operation.
  92 .It Cm half-duplex
  93 Force half-duplex operation.
  94 .El
  95 .Pp
  96 The driver provides support for TCP/UDP/IP checksum offloading (although
  97 disabled by default).
  98 The device and driver also support 1536-byte frames for VLANs (vlanmtu).
  99 .Sh SYSCTL VARIABLES
 100 The following variables are available as both
 101 .Xr sysctl 8
 102 variables and
 103 .Xr loader 8
 104 tunables:
 105 .Bl -tag -width "xxxxxxxx"
 106 .It Va dev.cgem.%d.rxbufs
 107 The number of receive buffers allocated to the hardware.
 108 The default value is 256.
 109 The maximum value is 511.
 110 If this number is increased while the interface is UP, it will not
 111 take effect until the next packet is received.
 112 If this number is decreased while the interface is UP, buffers will
 113 not be immediately removed from the receive buffer ring but the
 114 number of buffers will decrease as packets are received until it
 115 reaches the new value.
 116 .It Va dev.cgem.%d.rxhangwar
 117 This tunable enables a work-around to recover from receive hangs.
 118 The default value is 1.
 119 Set to 0 to disable the work-around.
 120 .El
 121 .Pp
 122 The following read-only variables are available as
 123 .Xr sysctl 8
 124 variables:
 125 .Bl -tag -width "xxxxxxxx"
 126 .It Va dev.cgem.%d._rxoverruns
 127 This variable counts the number of receive packet buffer overrun interrupts.
 128 .It Va dev.cgem.%d._rxnobufs
 129 This variable counts the number of interrupts due to the GEM buffer ring
 130 going empty.
 131 .It Va dev.cgem.%d._rxdmamapfails
 132 This variable is the number of times bus_dmamap_load_mbuf_sg(9) failed in
 133 the receive path.
 134 .It Va dev.cgem.%d._txfull
 135 The number of times the GEM's transmit ring was full.
 136 .It Va dev.cgem.%d._txdmamapfails
 137 This variable is the number of times bus_dmamap_load_mbuf_sg(9) failed in
 138 the transmit path.
 139 .It Va dev.cgem.%d._txdefrags
 140 This variable is the number of times the driver needed to call m_defrag(9)
 141 because a packet queued for transmit had too many DMA segments.
 142 .It Va dev.cgem.%d._txdefragfails
 143 This variable is the number of times
 144 .Xr m_defrag 9
 145 failed.
 146 .It Va dev.cgem.%d.stats.*
 147 The following variables are useful MAC counters supplied by the hardware:
 148 .It Va dev.cgem.%d.stats.tx_bytes
 149 A 64-bit counter of the number of bytes transmitted in frames without error.
 150 .It Va dev.cgem.%d.stats.tx_frames
 151 Counter of frames transmitted without error excluding pause frames.
 152 .It Va dev.cgem.%d.stats.tx_frames_bcast
 153 Counter of broadcast frames transmitted without error excluding
 154 pause frames.
 155 .It Va dev.cgem.%d.stats.tx_frames_multi
 156 Counter of multicast frames transmitted without error excluding
 157 pause frames.
 158 .It Va dev.cgem.%d.stats.tx_frames_pause
 159 Counter of pause frames transmitted without error.
 160 .It Va dev.cgem.%d.stats.tx_frames_64b
 161 Counter of 64 byte frames transmitted without error.
 162 .It Va dev.cgem.%d.stats.tx_frames_65to127b
 163 Counter of 65 to 127 byte frames transmitted without error.
 164 .It Va dev.cgem.%d.stats.tx_frames_128to255b
 165 Counter of 128 to 255 byte frames transmitted without error.
 166 .It Va dev.cgem.%d.stats.tx_frames_256to511b
 167 Counter of 256 to 511 byte frames transmitted without error.
 168 .It Va dev.cgem.%d.stats.tx_frames_512to1023b
 169 Counter of 512 to 1023 byte frames transmitted without error.
 170 .It Va dev.cgem.%d.stats.tx_frames_1024to1536b
 171 Counter of 1024 to 1536 byte frames transmitted without error.
 172 .It Va dev.cgem.%d.stats.tx_under_runs
 173 Counter of frames not transmitted due to a transmit underrun.
 174 .It Va dev.cgem.%d.stats.tx_single_collisn
 175 Counter of frames experiencing a single collision before being successfully
 176 transmitted.
 177 .It Va dev.cgem.%d.stats.tx_multi_collisn
 178 Counter of frames experiencing between 2 and 15 collisions before
 179 being successfully transmitted.
 180 .It Va dev.cgem.%d.stats.tx_excsv_collisn
 181 Counter of frames that failed to transmit because they experienced 16
 182 collisions.
 183 .It Va dev.cgem.%d.stats.tx_late_collisn
 184 Counter of frames that experienced a late collision.
 185 .It Va dev.cgem.%d.stats.tx_deferred_frames
 186 Counter of frames experiencing deferral due to carrier sense being
 187 active on their first attempt at transmission.
 188 .It Va dev.cgem.%d.stats.tx_carrier_sense_errs
 189 Counter of frames transmitted where carrier sense was not seen during
 190 transmission or where carrier sense was deasserted after being asserted
 191 in a transmit frame without collision.
 192 .It Va dev.cgem.%d.stats.rx_bytes
 193 A 64-bit counter of bytes received without error excluding pause
 194 frames.
 195 .It Va dev.cgem.%d.stats.rx_frames
 196 Counter of frames received without error excluding pause frames.
 197 .It Va dev.cgem.%d.stats.rx_frames_bcast
 198 Counter of broadcast frames receive without error excluding pause frames.
 199 .It Va dev.cgem.%d.stats.rx_frames_multi
 200 Counter of multicast frames receive without error excluding pause frames.
 201 .It Va dev.cgem.%d.stats.rx_frames_pause
 202 Counter of pause frames recevied without error.
 203 .It Va dev.cgem.%d.stats.rx_frames_64b
 204 Counter of 64-byte frames received without error.
 205 .It Va dev.cgem.%d.stats.rx_frames_65to127b
 206 Counter of 65 to 127 byte frames received without error.
 207 .It Va dev.cgem.%d.stats.rx_frames_128to255b
 208 Counter of 128 to 255 byte frames received without error.
 209 .It Va dev.cgem.%d.stats.rx_frames_256to511b
 210 Counter of 256 to 511 byte frames received without error.
 211 .It Va dev.cgem.%d.stats.rx_frames_512to1023b
 212 Counter of 512 to 1023 byte frames received without error.
 213 .It Va dev.cgem.%d.stats.rx_frames_1024to1536b
 214 Counter of 1024 to 1536 byte frames received without error.
 215 .It Va dev.cgem.%d.stats.rx_frames_undersize
 216 Counter of frames received less than 64 bytes in length that
 217 do not also have either a CRC error or an alignment error.
 218 .It Va dev.cgem.%d.stats.rx_frames_oversize
 219 Counter of frames received exceeding 1536 bytes and do not also have either
 220 a CRC error or an alignment error.
 221 .It Va dev.cgem.%d.stats.rx_frames_jabber
 222 Counter of frames received exceeding 1536 bytes and also have either a CRC
 223 error, an alignment error, or a receive symbol error.
 224 .It Va dev.cgem.%d.stats.rx_frames_fcs_errs
 225 Counter of frames received with a bad CRC and are between 64
 226 and 1536 bytes.
 227 .It Va dev.cgem.%d.stats.rx_frames_length_errs
 228 Counter of frames received that are shorter than that extracted
 229 from the length field.
 230 .It Va dev.cgem.%d.stats.rx_symbol_errs
 231 Counter of receive symbol errors.
 232 .It Va dev.cgem.%d.stats.rx_align_errs
 233 Counter of received frames that are not an integral number of bytes.
 234 .It Va dev.cgem.%d.stats.rx_resource_errs
 235 Counter of frames successfully receive by the MAC but could not be
 236 copied to memory because no receive buffer was available.
 237 .It Va dev.cgem.%d.stats.rx_overrun_errs
 238 Counter of frames that are address recognized but were not copied
 239 to memory due to a receive overrun.
 240 .It Va dev.cgem.%d.stats.rx_frames_ip_hdr_csum_errs
 241 Counter of frames discarded due to an incorrect IP header checksum when
 242 checksum offloading is enabled.
 243 .It Va dev.cgem.%d.stats.rx_frames_tcp_csum_errs
 244 Counter of frames discarded due to an incorrect TCP checksum when
 245 checksum offloading is enabled.
 246 .It Va dev.cgem.%d.stats.rx_frames_udp_csum_errs
 247 Counter of frames discarded due to an incorrect UDP checksum when
 248 checksum offloading is enabled.
 249 .El
 250 .Sh SEE ALSO
 251 .Xr miibus 4 ,
 252 .Xr ifconfig 8
 253 .Rs
 254 .%T "Zynq-7000 SoC Technical Reference Manual (Xilinx doc UG585)"
 255 .%U http://www.xilinx.com/support/documentation/user_guides/\:ug585-Zynq-7000-TRM.pdf
 256 .Re
 257 .Sh HISTORY
 258 The
 259 .Nm
 260 device driver first appeared in
 261 .Fx 10.0 .
 262 .Sh AUTHORS
 263 The
 264 .Nm
 265 driver and this manual page was written by
 266 .An Thomas Skibo Aq Mt thomasskibo@yahoo.com .
 267 .Sh BUGS
 268 The GEM can perform TCP/UDP/IP checksum offloading.
 269 However, when transmit checksum offloading is enabled, the GEM generates and
 270 replaces checksums for all packets it transmits.
 271 In a system that is forwarding packets, the device could potentially correct
 272 the checksum of packet that was corrupted in transit.
 273 For this reason, checksum offloading is disabled by default but can be
 274 enabled using ifconfig(8).
 275 .Pp
 276 When receive checksum offloading is enabled, the device will discard packets
 277 with bad TCP/UDP/IP checksums.
 278 The bad packets will not be counted in any
 279 .Xr netstat 1
 280 statistics.
 281 There are
 282 .Xr sysctl 8
 283 variables that count
 284 packets discarded by the hardware (see below).
 285 .Pp
 286 The GEM used in the Zynq-7000 has a bug such that the receiver can
 287 potentially freeze up under a high load.
 288 The issue is described in sec. 16.7
 289 "Known Issues" of the Zynq-7000 SoC Technical Reference Manual (Xilinx
 290 UG585 v1.7).
 291 The
 292 .Nm
 293 driver implements the work-around suggested in the manual.
 294 It is believed that the bug does not exist in the Zynq UltraScale+ and
 295 SiFive SoCs so the work-around is disabled in those instances and enabled
 296 in all others.
 297 The work-around can be disabled by setting the
 298 .Va dev.cgem.%d.rxhangwar
 299 .Xr sysctl 8
 300 variable to 0.