From owner-svn-src-stable-10@FreeBSD.ORG Sun Oct 26 03:55:56 2014 Return-Path: Delivered-To: svn-src-stable-10@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 9E89B398; Sun, 26 Oct 2014 03:55:56 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 8890D2B1; Sun, 26 Oct 2014 03:55:56 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id s9Q3tumA034512; Sun, 26 Oct 2014 03:55:56 GMT (envelope-from ian@FreeBSD.org) Received: (from ian@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id s9Q3tuqN034510; Sun, 26 Oct 2014 03:55:56 GMT (envelope-from ian@FreeBSD.org) Message-Id: <201410260355.s9Q3tuqN034510@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: ian set sender to ian@FreeBSD.org using -f From: Ian Lepore Date: Sun, 26 Oct 2014 03:55:56 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-10@freebsd.org Subject: svn commit: r273674 - stable/10/share/man/man4/man4.arm X-SVN-Group: stable-10 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-stable-10@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: SVN commit messages for only the 10-stable src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 26 Oct 2014 03:55:56 -0000 Author: ian Date: Sun Oct 26 03:55:55 2014 New Revision: 273674 URL: https://svnweb.freebsd.org/changeset/base/273674 Log: MFC r271907: Add a man page for the cgem(4) driver. Added: stable/10/share/man/man4/man4.arm/cgem.4 - copied unchanged from r271907, head/share/man/man4/man4.arm/cgem.4 Modified: stable/10/share/man/man4/man4.arm/Makefile Directory Properties: stable/10/ (props changed) Modified: stable/10/share/man/man4/man4.arm/Makefile ============================================================================== --- stable/10/share/man/man4/man4.arm/Makefile Sun Oct 26 03:55:09 2014 (r273673) +++ stable/10/share/man/man4/man4.arm/Makefile Sun Oct 26 03:55:55 2014 (r273674) @@ -1,11 +1,13 @@ # $FreeBSD$ -MAN= devcfg.4 \ +MAN= cgem.4 \ + devcfg.4 \ mge.4 \ npe.4 \ ti_adc.4 -MLINKS= mge.4 if_mge.4 +MLINKS= cgem.4 if_cgem.4 +MLINKS+= mge.4 if_mge.4 MLINKS+=npe.4 if_npe.4 MANSUBDIR=/arm Copied: stable/10/share/man/man4/man4.arm/cgem.4 (from r271907, head/share/man/man4/man4.arm/cgem.4) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/10/share/man/man4/man4.arm/cgem.4 Sun Oct 26 03:55:55 2014 (r273674, copy of r271907, head/share/man/man4/man4.arm/cgem.4) @@ -0,0 +1,297 @@ +.\" +.\" Copyright (c) 2014 Thomas Skibo +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 26, 2014 +.Dt CGEM 4 +.Os +.Sh NAME +.Nm cgem +.Nd "Cadence GEM Gigabit Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ether" +.Cd "device miibus" +.Cd "device cgem" +.Ed +.Sh DESCRIPTION +The +.Nm +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 and the Atmel SAMA5D3. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode using +.Xr ifconfig 8 +or by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseT +Set 1000Mbps (Gigabit Ethernet) operation over twisted pair. +The GEM supports 1000Mbps in +.Cm full-duplex +mode only. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full-duplex operation. +.It Cm half-duplex +Force half-duplex operation. +.El +.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). +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "xxxxxxxx" +.It Va dev.cgem.%d.rxbufs +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. +.It Va dev.cgem.%d.rxhangwar +This tunable enables a work-around to recover from receive hangs. +The default value is 1. +Set to 0 to disable the work-around. +.El +.Pp +The following read-only variables are available as +.Xr sysctl 8 +variables: +.Bl -tag -width "xxxxxxxx" +.It Va dev.cgem.%d._rxoverruns +This variable counts the number of receive packet buffer overrun interrupts. +.It Va dev.cgem.%d._rxnobufs +This variable counts the number of interrupts due to the GEM buffer ring +going empty. +.It Va dev.cgem.%d._rxdmamapfails +This variable is the number of times bus_dmamap_load_mbuf_sg(9) failed in +the receive path. +.It Va dev.cgem.%d._txfull +The number of times the GEM's transmit ring was full. +.It Va dev.cgem.%d._txdmamapfails +This variable is the number of times bus_dmamap_load_mbuf_sg(9) failed in +the transmit path. +.It Va dev.cgem.%d._txdefrags +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. +.It Va dev.cgem.%d._txdefragfails +This variable is the number of times +.Xr m_defrag 9 +failed. +.It Va dev.cgem.%d.stats.* +The following variables are useful MAC counters supplied by the hardware: +.It Va dev.cgem.%d.stats.tx_bytes +A 64-bit counter of the number of bytes transmitted in frames without error. +.It Va dev.cgem.%d.stats.tx_frames +Counter of frames transmitted without error excluding pause frames. +.It Va dev.cgem.%d.stats.tx_frames_bcast +Counter of broadcast frames transmitted without error excluding +pause frames. +.It Va dev.cgem.%d.stats.tx_frames_multi +Counter of multicast frames transmitted without error excluding +pause frames. +.It Va dev.cgem.%d.stats.tx_frames_pause +Counter of pause frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_frames_64b +Counter of 64 byte frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_frames_65to127b +Counter of 65 to 127 byte frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_frames_128to255b +Counter of 128 to 255 byte frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_frames_256to511b +Counter of 256 to 511 byte frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_frames_512to1023b +Counter of 512 to 1023 byte frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_frames_1024to1536b +Counter of 1024 to 1536 byte frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_under_runs +Counter of frames not transmitted due to a transmit underrun. +.It Va dev.cgem.%d.stats.tx_single_collisn +Counter of frames experiencing a single collision before being successfully +transmitted. +.It Va dev.cgem.%d.stats.tx_multi_collisn +Counter of frames experiencing between 2 and 15 collisions before +being successfully transmitted. +.It Va dev.cgem.%d.stats.tx_excsv_collisn +Counter of frames that failed to transmit because they experienced 16 +collisions. +.It Va dev.cgem.%d.stats.tx_late_collisn +Counter of frames that experienced a late collision. +.It Va dev.cgem.%d.stats.tx_deferred_frames +Counter of frames experiencing deferral due to carrier sense being +active on their first attempt at transmission. +.It Va dev.cgem.%d.stats.tx_carrier_sense_errs +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. +.It Va dev.cgem.%d.stats.rx_bytes +A 64-bit counter of bytes received without error excluding pause +frames. +.It Va dev.cgem.%d.stats.rx_frames +Counter of frames received without error excluding pause frames. +.It Va dev.cgem.%d.stats.rx_frames_bcast +Counter of broadcast frames receive without error excluding pause frames. +.It Va dev.cgem.%d.stats.rx_frames_multi +Counter of multicast frames receive without error excluding pause frames. +.It Va dev.cgem.%d.stats.rx_frames_pause +Counter of pause frames recevied without error. +.It Va dev.cgem.%d.stats.rx_frames_64b +Counter of 64-byte frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_65to127b +Counter of 65 to 127 byte frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_128to255b +Counter of 128 to 255 byte frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_256to511b +Counter of 256 to 511 byte frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_512to1023b +Counter of 512 to 1023 byte frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_1024to1536b +Counter of 1024 to 1536 byte frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_undersize +Counter of frames received less than 64 bytes in length that +do not also have either a CRC error or an alignment error. +.It Va dev.cgem.%d.stats.rx_frames_oversize +Counter of frames received exceeding 1536 bytes and do not also have either +a CRC error or an alignment error. +.It Va dev.cgem.%d.stats.rx_frames_jabber +Counter of frames received exceeding 1536 bytes and also have either a CRC +error, an alignment error, or a receive symbol error. +.It Va dev.cgem.%d.stats.rx_frames_fcs_errs +Counter of frames received with a bad CRC and are between 64 +and 1536 bytes. +.It Va dev.cgem.%d.stats.rx_frames_length_errs +Counter of frames received that are shorter than that extracted +from the length field. +.It Va dev.cgem.%d.stats.rx_symbol_errs +Counter of receive symbol errors. +.It Va dev.cgem.%d.stats.rx_align_errs +Counter of received frames that are not an integral number of bytes. +.It Va dev.cgem.%d.stats.rx_resource_errs +Counter of frames successfully receive by the MAC but could not be +copied to memory because no receive buffer was available. +.It Va dev.cgem.%d.stats.rx_overrun_errs +Counter of frames that are address recognized but were not copied +to memory due to a receive overrun. +.It Va dev.cgem.%d.stats.rx_frames_ip_hdr_csum_errs +Counter of frames discarded due to an incorrect IP header checksum when +checksum offloading is enabled. +.It Va dev.cgem.%d.stats.rx_frames_tcp_csum_errs +Counter of frames discarded due to an incorrect TCP checksum when +checksum offloading is enabled. +.It Va dev.cgem.%d.stats.rx_frames_udp_csum_errs +Counter of frames discarded due to an incorrect UDP checksum when +checksum offloading is enabled. +.El +.Sh BUGS +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). +.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 +.Xr netstat 1 +statistics. There are +.Xr sysctl 8 +variables that count +packets discarded by the hardware (see below). +.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 +.Nm +driver implements the work-around suggested in the manual. +If the bug does not exist in other versions of this device, the +work-around can be disabled by setting the dev.cgem.%d.rxhangwar +.Xr sysctl 8 +variable to 0. +.Pp +.Sh SEE ALSO +.Xr miibus 4 , +.Xr ifconfig 8 +.Rs +.%T "Zynq-7000 SoC Technical Reference Manual (Xilinx doc UG585)" +.%U http://www.xilinx.com/support/documentation/user_guides/\:ug585-Zynq-7000-TRM.pdf +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +The +.Nm +driver and this manual page was written by +.An Thomas Skibo Aq Mt thomasskibo@yahoo.com .