diff options
Diffstat (limited to 'static/freebsd/man4/cgem.4 3.html')
| -rw-r--r-- | static/freebsd/man4/cgem.4 3.html | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/static/freebsd/man4/cgem.4 3.html b/static/freebsd/man4/cgem.4 3.html new file mode 100644 index 00000000..4b855a29 --- /dev/null +++ b/static/freebsd/man4/cgem.4 3.html @@ -0,0 +1,262 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CGEM(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">CGEM(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">cgem</code> — <span class="Nd">Cadence GEM + Gigabit Ethernet driver</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp">To compile this driver into the kernel, place the following lines + in your kernel configuration file:</p> +<div class="Bd Pp Bd-indent"><code class="Cd">device ether</code> +<br/> +<code class="Cd">device miibus</code> +<br/> +<code class="Cd">device cgem</code></div> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">cgem</code> driver provides support for the + Cadence GEM (Gigabit Ethernet MAC). The Cadence GEM is used in some SoC + (System on a Chip) devices such as the Xilinx Zynq-7000, the Xilinx Zynq + UltraScale+, and the SiFive HiFive Unleashed.</p> +<p class="Pp">The <code class="Nm">cgem</code> driver supports the following + media types:</p> +<dl class="Bl-tag"> + <dt id="autoselect"><a class="permalink" href="#autoselect"><code class="Cm">autoselect</code></a></dt> + <dd>Enable autoselection of the media type and options. The user can manually + override the autoselected mode using <a class="Xr">ifconfig(8)</a> or by + adding media options to <a class="Xr">rc.conf(5)</a>.</dd> + <dt id="10baseT/UTP"><a class="permalink" href="#10baseT/UTP"><code class="Cm">10baseT/UTP</code></a></dt> + <dd>Set 10Mbps operation. The <a class="Xr">ifconfig(8)</a> + <code class="Cm">mediaopt</code> option can also be used to select either + <code class="Cm">full-duplex</code> or <code class="Cm">half-duplex</code> + modes.</dd> + <dt id="100baseTX"><a class="permalink" href="#100baseTX"><code class="Cm">100baseTX</code></a></dt> + <dd>Set 100Mbps (Fast Ethernet) operation. The <a class="Xr">ifconfig(8)</a> + <code class="Cm">mediaopt</code> option can also be used to select either + <code class="Cm">full-duplex</code> or <code class="Cm">half-duplex</code> + modes.</dd> + <dt id="1000baseT"><a class="permalink" href="#1000baseT"><code class="Cm">1000baseT</code></a></dt> + <dd>Set 1000Mbps (Gigabit Ethernet) operation over twisted pair. The GEM + supports 1000Mbps in <code class="Cm">full-duplex</code> mode only.</dd> +</dl> +<p class="Pp">The <code class="Nm">cgem</code> driver supports the following + media options:</p> +<dl class="Bl-tag"> + <dt id="full-duplex"><a class="permalink" href="#full-duplex"><code class="Cm">full-duplex</code></a></dt> + <dd>Force full-duplex operation.</dd> + <dt id="half-duplex"><a class="permalink" href="#half-duplex"><code class="Cm">half-duplex</code></a></dt> + <dd>Force half-duplex operation.</dd> +</dl> +<p class="Pp">The driver provides support for TCP/UDP/IP checksum offloading + (although disabled by default). The device and driver also support 1536-byte + frames for VLANs (vlanmtu).</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYSCTL_VARIABLES"><a class="permalink" href="#SYSCTL_VARIABLES">SYSCTL + VARIABLES</a></h1> +<p class="Pp">The following variables are available as both + <a class="Xr">sysctl(8)</a> variables and <a class="Xr">loader(8)</a> + tunables:</p> +<dl class="Bl-tag"> + <dt id="dev.cgem._d.rxbufs"><var class="Va">dev.cgem.%d.rxbufs</var></dt> + <dd>The number of receive buffers allocated to the hardware. The default value + is 256. The maximum value is 511. If this number is increased while the + interface is UP, it will not take effect until the next packet is + received. If this number is decreased while the interface is UP, buffers + will not be immediately removed from the receive buffer ring but the + number of buffers will decrease as packets are received until it reaches + the new value.</dd> + <dt id="dev.cgem._d.rxhangwar"><var class="Va">dev.cgem.%d.rxhangwar</var></dt> + <dd>This tunable enables a work-around to recover from receive hangs. The + default value is 1. Set to 0 to disable the work-around.</dd> +</dl> +<p class="Pp">The following read-only variables are available as + <a class="Xr">sysctl(8)</a> variables:</p> +<dl class="Bl-tag"> + <dt id="dev.cgem._d._rxoverruns"><var class="Va">dev.cgem.%d._rxoverruns</var></dt> + <dd>This variable counts the number of receive packet buffer overrun + interrupts.</dd> + <dt id="dev.cgem._d._rxnobufs"><var class="Va">dev.cgem.%d._rxnobufs</var></dt> + <dd>This variable counts the number of interrupts due to the GEM buffer ring + going empty.</dd> + <dt id="dev.cgem._d._rxdmamapfails"><var class="Va">dev.cgem.%d._rxdmamapfails</var></dt> + <dd>This variable is the number of times bus_dmamap_load_mbuf_sg(9) failed in + the receive path.</dd> + <dt id="dev.cgem._d._txfull"><var class="Va">dev.cgem.%d._txfull</var></dt> + <dd>The number of times the GEM's transmit ring was full.</dd> + <dt id="dev.cgem._d._txdmamapfails"><var class="Va">dev.cgem.%d._txdmamapfails</var></dt> + <dd>This variable is the number of times bus_dmamap_load_mbuf_sg(9) failed in + the transmit path.</dd> + <dt id="dev.cgem._d._txdefrags"><var class="Va">dev.cgem.%d._txdefrags</var></dt> + <dd>This variable is the number of times the driver needed to call m_defrag(9) + because a packet queued for transmit had too many DMA segments.</dd> + <dt id="dev.cgem._d._txdefragfails"><var class="Va">dev.cgem.%d._txdefragfails</var></dt> + <dd>This variable is the number of times <a class="Xr">m_defrag(9)</a> + failed.</dd> + <dt id="dev.cgem._d.stats.*"><var class="Va">dev.cgem.%d.stats.*</var></dt> + <dd>The following variables are useful MAC counters supplied by the + hardware:</dd> + <dt id="dev.cgem._d.stats.tx_bytes"><var class="Va">dev.cgem.%d.stats.tx_bytes</var></dt> + <dd>A 64-bit counter of the number of bytes transmitted in frames without + error.</dd> + <dt id="dev.cgem._d.stats.tx_frames"><var class="Va">dev.cgem.%d.stats.tx_frames</var></dt> + <dd>Counter of frames transmitted without error excluding pause frames.</dd> + <dt id="dev.cgem._d.stats.tx_frames_bcast"><var class="Va">dev.cgem.%d.stats.tx_frames_bcast</var></dt> + <dd>Counter of broadcast frames transmitted without error excluding pause + frames.</dd> + <dt id="dev.cgem._d.stats.tx_frames_multi"><var class="Va">dev.cgem.%d.stats.tx_frames_multi</var></dt> + <dd>Counter of multicast frames transmitted without error excluding pause + frames.</dd> + <dt id="dev.cgem._d.stats.tx_frames_pause"><var class="Va">dev.cgem.%d.stats.tx_frames_pause</var></dt> + <dd>Counter of pause frames transmitted without error.</dd> + <dt id="dev.cgem._d.stats.tx_frames_64b"><var class="Va">dev.cgem.%d.stats.tx_frames_64b</var></dt> + <dd>Counter of 64 byte frames transmitted without error.</dd> + <dt id="dev.cgem._d.stats.tx_frames_65to127b"><var class="Va">dev.cgem.%d.stats.tx_frames_65to127b</var></dt> + <dd>Counter of 65 to 127 byte frames transmitted without error.</dd> + <dt id="dev.cgem._d.stats.tx_frames_128to255b"><var class="Va">dev.cgem.%d.stats.tx_frames_128to255b</var></dt> + <dd>Counter of 128 to 255 byte frames transmitted without error.</dd> + <dt id="dev.cgem._d.stats.tx_frames_256to511b"><var class="Va">dev.cgem.%d.stats.tx_frames_256to511b</var></dt> + <dd>Counter of 256 to 511 byte frames transmitted without error.</dd> + <dt id="dev.cgem._d.stats.tx_frames_512to1023b"><var class="Va">dev.cgem.%d.stats.tx_frames_512to1023b</var></dt> + <dd>Counter of 512 to 1023 byte frames transmitted without error.</dd> + <dt id="dev.cgem._d.stats.tx_frames_1024to1536b"><var class="Va">dev.cgem.%d.stats.tx_frames_1024to1536b</var></dt> + <dd>Counter of 1024 to 1536 byte frames transmitted without error.</dd> + <dt id="dev.cgem._d.stats.tx_under_runs"><var class="Va">dev.cgem.%d.stats.tx_under_runs</var></dt> + <dd>Counter of frames not transmitted due to a transmit underrun.</dd> + <dt id="dev.cgem._d.stats.tx_single_collisn"><var class="Va">dev.cgem.%d.stats.tx_single_collisn</var></dt> + <dd>Counter of frames experiencing a single collision before being + successfully transmitted.</dd> + <dt id="dev.cgem._d.stats.tx_multi_collisn"><var class="Va">dev.cgem.%d.stats.tx_multi_collisn</var></dt> + <dd>Counter of frames experiencing between 2 and 15 collisions before being + successfully transmitted.</dd> + <dt id="dev.cgem._d.stats.tx_excsv_collisn"><var class="Va">dev.cgem.%d.stats.tx_excsv_collisn</var></dt> + <dd>Counter of frames that failed to transmit because they experienced 16 + collisions.</dd> + <dt id="dev.cgem._d.stats.tx_late_collisn"><var class="Va">dev.cgem.%d.stats.tx_late_collisn</var></dt> + <dd>Counter of frames that experienced a late collision.</dd> + <dt id="dev.cgem._d.stats.tx_deferred_frames"><var class="Va">dev.cgem.%d.stats.tx_deferred_frames</var></dt> + <dd>Counter of frames experiencing deferral due to carrier sense being active + on their first attempt at transmission.</dd> + <dt id="dev.cgem._d.stats.tx_carrier_sense_errs"><var class="Va">dev.cgem.%d.stats.tx_carrier_sense_errs</var></dt> + <dd>Counter of frames transmitted where carrier sense was not seen during + transmission or where carrier sense was deasserted after being asserted in + a transmit frame without collision.</dd> + <dt id="dev.cgem._d.stats.rx_bytes"><var class="Va">dev.cgem.%d.stats.rx_bytes</var></dt> + <dd>A 64-bit counter of bytes received without error excluding pause + frames.</dd> + <dt id="dev.cgem._d.stats.rx_frames"><var class="Va">dev.cgem.%d.stats.rx_frames</var></dt> + <dd>Counter of frames received without error excluding pause frames.</dd> + <dt id="dev.cgem._d.stats.rx_frames_bcast"><var class="Va">dev.cgem.%d.stats.rx_frames_bcast</var></dt> + <dd>Counter of broadcast frames receive without error excluding pause + frames.</dd> + <dt id="dev.cgem._d.stats.rx_frames_multi"><var class="Va">dev.cgem.%d.stats.rx_frames_multi</var></dt> + <dd>Counter of multicast frames receive without error excluding pause + frames.</dd> + <dt id="dev.cgem._d.stats.rx_frames_pause"><var class="Va">dev.cgem.%d.stats.rx_frames_pause</var></dt> + <dd>Counter of pause frames received without error.</dd> + <dt id="dev.cgem._d.stats.rx_frames_64b"><var class="Va">dev.cgem.%d.stats.rx_frames_64b</var></dt> + <dd>Counter of 64-byte frames received without error.</dd> + <dt id="dev.cgem._d.stats.rx_frames_65to127b"><var class="Va">dev.cgem.%d.stats.rx_frames_65to127b</var></dt> + <dd>Counter of 65 to 127 byte frames received without error.</dd> + <dt id="dev.cgem._d.stats.rx_frames_128to255b"><var class="Va">dev.cgem.%d.stats.rx_frames_128to255b</var></dt> + <dd>Counter of 128 to 255 byte frames received without error.</dd> + <dt id="dev.cgem._d.stats.rx_frames_256to511b"><var class="Va">dev.cgem.%d.stats.rx_frames_256to511b</var></dt> + <dd>Counter of 256 to 511 byte frames received without error.</dd> + <dt id="dev.cgem._d.stats.rx_frames_512to1023b"><var class="Va">dev.cgem.%d.stats.rx_frames_512to1023b</var></dt> + <dd>Counter of 512 to 1023 byte frames received without error.</dd> + <dt id="dev.cgem._d.stats.rx_frames_1024to1536b"><var class="Va">dev.cgem.%d.stats.rx_frames_1024to1536b</var></dt> + <dd>Counter of 1024 to 1536 byte frames received without error.</dd> + <dt id="dev.cgem._d.stats.rx_frames_undersize"><var class="Va">dev.cgem.%d.stats.rx_frames_undersize</var></dt> + <dd>Counter of frames received less than 64 bytes in length that do not also + have either a CRC error or an alignment error.</dd> + <dt id="dev.cgem._d.stats.rx_frames_oversize"><var class="Va">dev.cgem.%d.stats.rx_frames_oversize</var></dt> + <dd>Counter of frames received exceeding 1536 bytes and do not also have + either a CRC error or an alignment error.</dd> + <dt id="dev.cgem._d.stats.rx_frames_jabber"><var class="Va">dev.cgem.%d.stats.rx_frames_jabber</var></dt> + <dd>Counter of frames received exceeding 1536 bytes and also have either a CRC + error, an alignment error, or a receive symbol error.</dd> + <dt id="dev.cgem._d.stats.rx_frames_fcs_errs"><var class="Va">dev.cgem.%d.stats.rx_frames_fcs_errs</var></dt> + <dd>Counter of frames received with a bad CRC and are between 64 and 1536 + bytes.</dd> + <dt id="dev.cgem._d.stats.rx_frames_length_errs"><var class="Va">dev.cgem.%d.stats.rx_frames_length_errs</var></dt> + <dd>Counter of frames received that are shorter than that extracted from the + length field.</dd> + <dt id="dev.cgem._d.stats.rx_symbol_errs"><var class="Va">dev.cgem.%d.stats.rx_symbol_errs</var></dt> + <dd>Counter of receive symbol errors.</dd> + <dt id="dev.cgem._d.stats.rx_align_errs"><var class="Va">dev.cgem.%d.stats.rx_align_errs</var></dt> + <dd>Counter of received frames that are not an integral number of bytes.</dd> + <dt id="dev.cgem._d.stats.rx_resource_errs"><var class="Va">dev.cgem.%d.stats.rx_resource_errs</var></dt> + <dd>Counter of frames successfully receive by the MAC but could not be copied + to memory because no receive buffer was available.</dd> + <dt id="dev.cgem._d.stats.rx_overrun_errs"><var class="Va">dev.cgem.%d.stats.rx_overrun_errs</var></dt> + <dd>Counter of frames that are address recognized but were not copied to + memory due to a receive overrun.</dd> + <dt id="dev.cgem._d.stats.rx_frames_ip_hdr_csum_errs"><var class="Va">dev.cgem.%d.stats.rx_frames_ip_hdr_csum_errs</var></dt> + <dd>Counter of frames discarded due to an incorrect IP header checksum when + checksum offloading is enabled.</dd> + <dt id="dev.cgem._d.stats.rx_frames_tcp_csum_errs"><var class="Va">dev.cgem.%d.stats.rx_frames_tcp_csum_errs</var></dt> + <dd>Counter of frames discarded due to an incorrect TCP checksum when checksum + offloading is enabled.</dd> + <dt id="dev.cgem._d.stats.rx_frames_udp_csum_errs"><var class="Va">dev.cgem.%d.stats.rx_frames_udp_csum_errs</var></dt> + <dd>Counter of frames discarded due to an incorrect UDP checksum when checksum + offloading is enabled.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">miibus(4)</a>, <a class="Xr">ifconfig(8)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsT">Zynq-7000 SoC Technical + Reference Manual (Xilinx doc UG585)</span>, + <a class="RsU" href="http://www.xilinx.com/support/documentation/user_guides/ug585-Zynq-7000-TRM.pdf">http://www.xilinx.com/support/documentation/user_guides/ug585-Zynq-7000-TRM.pdf</a>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">cgem</code> device driver first appeared in + <span class="Ux">FreeBSD 10.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">cgem</code> driver and this manual page was + written by <span class="An">Thomas Skibo</span> + <<a class="Mt" href="mailto:thomasskibo@yahoo.com">thomasskibo@yahoo.com</a>>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">The GEM can perform TCP/UDP/IP checksum offloading. However, when + transmit checksum offloading is enabled, the GEM generates and replaces + checksums for all packets it transmits. In a system that is forwarding + packets, the device could potentially correct the checksum of packet that + was corrupted in transit. For this reason, checksum offloading is disabled + by default but can be enabled using ifconfig(8).</p> +<p class="Pp">When receive checksum offloading is enabled, the device will + discard packets with bad TCP/UDP/IP checksums. The bad packets will not be + counted in any <a class="Xr">netstat(1)</a> statistics. There are + <a class="Xr">sysctl(8)</a> variables that count packets discarded by the + hardware (see below).</p> +<p class="Pp">The GEM used in the Zynq-7000 has a bug such that the receiver can + potentially freeze up under a high load. The issue is described in sec. 16.7 + "Known Issues" of the Zynq-7000 SoC Technical Reference Manual + (Xilinx UG585 v1.7). The <code class="Nm">cgem</code> driver implements the + work-around suggested in the manual. It is believed that the bug does not + exist in the Zynq UltraScale+ and SiFive SoCs so the work-around is disabled + in those instances and enabled in all others. The work-around can be + disabled by setting the <var class="Va">dev.cgem.%d.rxhangwar</var> + <a class="Xr">sysctl(8)</a> variable to 0.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 10, 2021</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |