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