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