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