2003-06-10 18:53:15 +00:00
|
|
|
.\" $NetBSD: gem.4,v 1.2 2003/02/14 15:20:18 grant Exp $
|
|
|
|
|
.\"
|
|
|
|
|
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
|
|
|
|
|
.\" 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. Redistributions in binary form must reproduce the above copyright
|
|
|
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
|
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
|
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
|
|
|
.\" must display the following acknowledgement:
|
|
|
|
|
.\" This product includes software developed by the NetBSD
|
|
|
|
|
.\" Foundation, Inc. and its contributors.
|
|
|
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
|
|
|
.\" contributors may be used to endorse or promote products derived
|
|
|
|
|
.\" from this software without specific prior written permission.
|
|
|
|
|
.\"
|
|
|
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
|
|
|
|
|
.\"
|
2004-06-17 19:51:17 +00:00
|
|
|
.\" $FreeBSD$
|
|
|
|
|
.\"
|
2009-01-15 22:06:53 +00:00
|
|
|
.Dd January 15, 2009
|
2003-06-10 18:53:15 +00:00
|
|
|
.Dt GEM 4
|
|
|
|
|
.Os
|
|
|
|
|
.Sh NAME
|
|
|
|
|
.Nm gem
|
|
|
|
|
.Nd ERI/GEM/GMAC Ethernet device driver
|
|
|
|
|
.Sh SYNOPSIS
|
2006-09-02 12:12:16 +00:00
|
|
|
To compile this driver into the kernel,
|
|
|
|
|
place the following lines in your
|
|
|
|
|
kernel configuration file:
|
|
|
|
|
.Bd -ragged -offset indent
|
2003-06-10 18:53:15 +00:00
|
|
|
.Cd "device miibus"
|
|
|
|
|
.Cd "device gem"
|
2006-09-02 12:12:16 +00:00
|
|
|
.Ed
|
|
|
|
|
.Pp
|
|
|
|
|
Alternatively, to load the driver as a
|
|
|
|
|
module at boot time, place the following line in
|
|
|
|
|
.Xr loader.conf 5 :
|
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
|
if_gem_load="YES"
|
|
|
|
|
.Ed
|
2003-06-10 18:53:15 +00:00
|
|
|
.Sh DESCRIPTION
|
|
|
|
|
The
|
|
|
|
|
.Nm
|
|
|
|
|
driver provides support for the GMac Ethernet hardware found mostly in
|
|
|
|
|
the last Apple PowerBooks G3s and most G4-based Apple hardware, as
|
|
|
|
|
well as many Sun UltraSPARCs.
|
2004-08-15 18:13:08 +00:00
|
|
|
.Sh HARDWARE
|
2003-06-10 18:53:15 +00:00
|
|
|
.Pp
|
2006-09-01 21:42:22 +00:00
|
|
|
Chips supported by the
|
2004-08-15 18:13:08 +00:00
|
|
|
.Nm
|
|
|
|
|
driver include:
|
|
|
|
|
.Pp
|
|
|
|
|
.Bl -bullet -compact
|
2003-06-10 18:53:15 +00:00
|
|
|
.It
|
2006-09-01 21:42:22 +00:00
|
|
|
Apple GMAC
|
2003-06-10 18:53:15 +00:00
|
|
|
.It
|
2004-08-14 21:44:35 +00:00
|
|
|
Sun ERI 10/100 Mbps Ethernet
|
2003-06-10 18:53:15 +00:00
|
|
|
.It
|
2006-09-01 21:42:22 +00:00
|
|
|
Sun GEM Gigabit Ethernet
|
2003-06-10 18:53:15 +00:00
|
|
|
.El
|
o Revert the part of if_gem.c rev. 1.35 which added a call to gem_stop()
to gem_attach() as the former access softc members not yet initialized
at that time and gem_reset() actually is enough to stop the chip. [1]
o Revise the use of gem_bitwait(); add bus_barrier() calls before calling
gem_bitwait() to ensure the respective bit has been written before we
starting polling on it and poll for the right bits to change, f.e. even
though we only reset RX we have to actually wait for both GEM_RESET_RX
and GEM_RESET_TX to clear. Add some additional gem_bitwait() calls in
places we've been missing them according to the GEM documentation.
Along with this some excessive DELAYs, which probably only were added
because of bugs in gem_bitwait() and its use in the first place, as
well as as have of an gem_bitwait() reimplementation in gem_reset_tx()
were removed.
o Add gem_reset_rxdma() and use it to deal with GEM_MAC_RX_OVERFLOW errors
more gracefully as unlike gem_init_locked() it resets the RX DMA engine
only, causing no link loss and the FIFOs not to be cleared. Also use it
deal with GEM_INTR_RX_TAG_ERR errors, with previously were unhandled.
This was based on information obtained from the Linux GEM and OpenSolaris
ERI drivers.
o Turn on workarounds for silicon bugs in the Apple GMAC variants.
This was based on information obtained from the Darwin GMAC and Linux GEM
drivers.
o Turn on "infinite" (i.e. maximum 31 * 64 bytes in length) DMA bursts.
This greatly improves especially RX performance.
o Optimize the RX path, this consists of:
- kicking the receiver as soon as we've a spare descriptor in gem_rint()
again instead of just once after all the ready ones have been handled;
- kicking the receiver the right way, i.e. as outlined in the GEM
documentation in batches of 4 and by pointing it to the descriptor
after the last valid one;
- calling gem_rint() before gem_tint() in gem_intr() as gem_tint() may
take quite a while;
- doubling the size of the RX ring to 256 descriptors.
Overall the RX performance of a GEM in a 1GHz Sun Fire V210 was improved
from ~100Mbit/s to ~850Mbit/s.
o In gem_add_rxbuf() don't assign the newly allocated mbuf to rxs_mbuf
before calling bus_dmamap_load_mbuf_sg(), if bus_dmamap_load_mbuf_sg()
fails we'll free the newly allocated mbuf, unable to recycle the
previous one but a NULL pointer dereference instead.
o In gem_init_locked() honor the return value of gem_meminit().
o Simplify gem_ringsize() and dont' return garbage in the default case.
Based on OpenBSD.
o Don't turn on MAC control, MIF and PCS interrupts unless GEM_DEBUG is
defined as we don't need/use these interrupts for operation.
o In gem_start_locked() sync the DMA maps of the descriptor rings before
every kick of the transmitter and not just once after enqueuing all
packets as the NIC might instantly start transmitting after we kicked
it the first time.
o Keep state of the link state and use it to enable or disable the MAC
in gem_mii_statchg() accordingly as well as to return early from
gem_start_locked() in case the link is down. [3]
o Initialize the maximum frame size to a sane value.
o In gem_mii_statchg() enable carrier extension if appropriate.
o Increment if_ierrors in case of an GEM_MAC_RX_OVERFLOW error and in
gem_eint(). [3]
o Handle IFF_ALLMULTI correctly; don't set it if we've turned promiscuous
group mode on and don't clear the flag if we've disabled promiscuous
group mode (these were mostly NOPs though). [2]
o Let gem_eint() also report GEM_INTR_PERR errors.
o Move setting sc_variant from gem_pci_probe() to gem_pci_attach() as
device probe methods are not supposed to touch the softc.
o Collapse sc_inited and sc_pci into bits for sc_flags.
o Add CTASSERTs ensuring that GEM_NRXDESC and GEM_NTXDESC are set to
legal values.
o Correctly set up for 802.3x flow control, though #ifdef out the code
that actually enables it as this needs more testing and mainly a proper
framework to support it.
o Correct and add some conversions from hard-coded functions names to
__func__ which were borked or forgotten in if_gem.c rev. 1.42.
o Use PCIR_BAR instead of a homegrown macro.
o Replace sc_enaddr[6] with sc_enaddr[ETHER_ADDR_LEN].
o In gem_pci_attach() in case attaching fails release the resources in
the opposite order they were allocated.
o Make gem_reset() static to if_gem.c as it's not needed outside that
module.
o Remove the GEM_GIGABIT flag and the associated code; GEM_GIGABIT was
never set and the associated code was in the wrong place.
o Remove sc_mif_config; it was only used to cache the contents of the
respective register within gem_attach().
o Remove the #ifdef'ed out NetBSD/OpenBSD code for establishing a suspend
hook as it will never be used on FreeBSD.
o Also probe Apple Intrepid 2 GMAC and Apple Shasta GMAC, add support for
Apple K2 GMAC. Based on OpenBSD.
o Add support for Sun GBE/P cards, or in other words actually add support
for cards based on GEM to gem(4). This mainly consists of adding support
for the TBI of these chips. Along with this the PHY selection code was
rewritten to hardcode the PHY number for certain configurations as for
example the PHY of the on-board ERI of Blade 1000 shows up twice causing
no link as the second incarnation is isolated.
These changes were ported from OpenBSD with some additional improvements
and modulo some bugs.
o Add code to if_gem_pci.c allowing to read the MAC-address from the VPD on
systems without Open Firmware.
This is an improved version of my variant of the respective code in
if_hme_pci.c
o Now that gem(4) is MI enable it for all archs.
Pointed out by: yongari [1]
Suggested by: rwatson [2], yongari [3]
Tested on: i386 (GEM), powerpc (GMACs by marcel and yongari),
sparc64 (ERI and GEM)
Reviewed by: yongari
Approved by: re (kensmith)
2007-09-26 21:14:18 +00:00
|
|
|
.Pp
|
|
|
|
|
The
|
|
|
|
|
following add-on cards are known to work with the
|
|
|
|
|
.Nm
|
|
|
|
|
driver at this time:
|
|
|
|
|
.Pp
|
|
|
|
|
.Bl -bullet -compact
|
|
|
|
|
.It
|
|
|
|
|
Sun Gigabit Ethernet PCI 2.0/3.0 (GBE/P)
|
|
|
|
|
(part no.\& 501-4373)
|
|
|
|
|
.El
|
2004-08-14 21:44:35 +00:00
|
|
|
.Sh NOTES
|
|
|
|
|
On sparc64 the
|
|
|
|
|
.Nm
|
|
|
|
|
driver respects the
|
|
|
|
|
.Va local-mac-address?
|
|
|
|
|
system configuration variable which can be set in the Open Firmware boot
|
|
|
|
|
monitor using the
|
|
|
|
|
.Ic setenv
|
|
|
|
|
command or by
|
|
|
|
|
.Xr eeprom 8 .
|
|
|
|
|
If set to
|
|
|
|
|
.Dq Li false
|
|
|
|
|
(the default), the
|
|
|
|
|
.Nm
|
|
|
|
|
driver will use the system's default MAC address for all of its devices.
|
|
|
|
|
If set to
|
|
|
|
|
.Dq Li true ,
|
|
|
|
|
the unique MAC address of each interface is used if present rather than
|
|
|
|
|
the system's default MAC address.
|
|
|
|
|
.Pp
|
|
|
|
|
Supported interfaces having their own MAC address include the on-board
|
2006-09-01 21:42:22 +00:00
|
|
|
Sun ERI 10/100 Mbps on boards equipped with more than one Ethernet interface
|
|
|
|
|
and the Sun Gigabit Ethernet 2.0/3.0 GBE add-on cards.
|
|
|
|
|
.Sh CAVEATS
|
|
|
|
|
Currently the
|
|
|
|
|
.Nm
|
o Revert the part of if_gem.c rev. 1.35 which added a call to gem_stop()
to gem_attach() as the former access softc members not yet initialized
at that time and gem_reset() actually is enough to stop the chip. [1]
o Revise the use of gem_bitwait(); add bus_barrier() calls before calling
gem_bitwait() to ensure the respective bit has been written before we
starting polling on it and poll for the right bits to change, f.e. even
though we only reset RX we have to actually wait for both GEM_RESET_RX
and GEM_RESET_TX to clear. Add some additional gem_bitwait() calls in
places we've been missing them according to the GEM documentation.
Along with this some excessive DELAYs, which probably only were added
because of bugs in gem_bitwait() and its use in the first place, as
well as as have of an gem_bitwait() reimplementation in gem_reset_tx()
were removed.
o Add gem_reset_rxdma() and use it to deal with GEM_MAC_RX_OVERFLOW errors
more gracefully as unlike gem_init_locked() it resets the RX DMA engine
only, causing no link loss and the FIFOs not to be cleared. Also use it
deal with GEM_INTR_RX_TAG_ERR errors, with previously were unhandled.
This was based on information obtained from the Linux GEM and OpenSolaris
ERI drivers.
o Turn on workarounds for silicon bugs in the Apple GMAC variants.
This was based on information obtained from the Darwin GMAC and Linux GEM
drivers.
o Turn on "infinite" (i.e. maximum 31 * 64 bytes in length) DMA bursts.
This greatly improves especially RX performance.
o Optimize the RX path, this consists of:
- kicking the receiver as soon as we've a spare descriptor in gem_rint()
again instead of just once after all the ready ones have been handled;
- kicking the receiver the right way, i.e. as outlined in the GEM
documentation in batches of 4 and by pointing it to the descriptor
after the last valid one;
- calling gem_rint() before gem_tint() in gem_intr() as gem_tint() may
take quite a while;
- doubling the size of the RX ring to 256 descriptors.
Overall the RX performance of a GEM in a 1GHz Sun Fire V210 was improved
from ~100Mbit/s to ~850Mbit/s.
o In gem_add_rxbuf() don't assign the newly allocated mbuf to rxs_mbuf
before calling bus_dmamap_load_mbuf_sg(), if bus_dmamap_load_mbuf_sg()
fails we'll free the newly allocated mbuf, unable to recycle the
previous one but a NULL pointer dereference instead.
o In gem_init_locked() honor the return value of gem_meminit().
o Simplify gem_ringsize() and dont' return garbage in the default case.
Based on OpenBSD.
o Don't turn on MAC control, MIF and PCS interrupts unless GEM_DEBUG is
defined as we don't need/use these interrupts for operation.
o In gem_start_locked() sync the DMA maps of the descriptor rings before
every kick of the transmitter and not just once after enqueuing all
packets as the NIC might instantly start transmitting after we kicked
it the first time.
o Keep state of the link state and use it to enable or disable the MAC
in gem_mii_statchg() accordingly as well as to return early from
gem_start_locked() in case the link is down. [3]
o Initialize the maximum frame size to a sane value.
o In gem_mii_statchg() enable carrier extension if appropriate.
o Increment if_ierrors in case of an GEM_MAC_RX_OVERFLOW error and in
gem_eint(). [3]
o Handle IFF_ALLMULTI correctly; don't set it if we've turned promiscuous
group mode on and don't clear the flag if we've disabled promiscuous
group mode (these were mostly NOPs though). [2]
o Let gem_eint() also report GEM_INTR_PERR errors.
o Move setting sc_variant from gem_pci_probe() to gem_pci_attach() as
device probe methods are not supposed to touch the softc.
o Collapse sc_inited and sc_pci into bits for sc_flags.
o Add CTASSERTs ensuring that GEM_NRXDESC and GEM_NTXDESC are set to
legal values.
o Correctly set up for 802.3x flow control, though #ifdef out the code
that actually enables it as this needs more testing and mainly a proper
framework to support it.
o Correct and add some conversions from hard-coded functions names to
__func__ which were borked or forgotten in if_gem.c rev. 1.42.
o Use PCIR_BAR instead of a homegrown macro.
o Replace sc_enaddr[6] with sc_enaddr[ETHER_ADDR_LEN].
o In gem_pci_attach() in case attaching fails release the resources in
the opposite order they were allocated.
o Make gem_reset() static to if_gem.c as it's not needed outside that
module.
o Remove the GEM_GIGABIT flag and the associated code; GEM_GIGABIT was
never set and the associated code was in the wrong place.
o Remove sc_mif_config; it was only used to cache the contents of the
respective register within gem_attach().
o Remove the #ifdef'ed out NetBSD/OpenBSD code for establishing a suspend
hook as it will never be used on FreeBSD.
o Also probe Apple Intrepid 2 GMAC and Apple Shasta GMAC, add support for
Apple K2 GMAC. Based on OpenBSD.
o Add support for Sun GBE/P cards, or in other words actually add support
for cards based on GEM to gem(4). This mainly consists of adding support
for the TBI of these chips. Along with this the PHY selection code was
rewritten to hardcode the PHY number for certain configurations as for
example the PHY of the on-board ERI of Blade 1000 shows up twice causing
no link as the second incarnation is isolated.
These changes were ported from OpenBSD with some additional improvements
and modulo some bugs.
o Add code to if_gem_pci.c allowing to read the MAC-address from the VPD on
systems without Open Firmware.
This is an improved version of my variant of the respective code in
if_hme_pci.c
o Now that gem(4) is MI enable it for all archs.
Pointed out by: yongari [1]
Suggested by: rwatson [2], yongari [3]
Tested on: i386 (GEM), powerpc (GMACs by marcel and yongari),
sparc64 (ERI and GEM)
Reviewed by: yongari
Approved by: re (kensmith)
2007-09-26 21:14:18 +00:00
|
|
|
driver fails to attach to Sun Gigabit Ethernet SBus 2.0/3.0 (GBE/S) cards,
|
2006-09-01 21:42:22 +00:00
|
|
|
as no SBus front-end has been written so far.
|
2003-06-10 18:53:15 +00:00
|
|
|
.Sh SEE ALSO
|
2007-06-04 16:59:11 +00:00
|
|
|
.Xr altq 4 ,
|
2003-06-10 18:53:15 +00:00
|
|
|
.Xr miibus 4 ,
|
|
|
|
|
.Xr netintro 4 ,
|
2004-08-14 21:44:35 +00:00
|
|
|
.Xr eeprom 8 ,
|
2003-06-10 18:53:15 +00:00
|
|
|
.Xr ifconfig 8
|
|
|
|
|
.Sh HISTORY
|
|
|
|
|
The
|
|
|
|
|
.Nm
|
|
|
|
|
device driver appeared in
|
|
|
|
|
.Nx 1.6 .
|
|
|
|
|
The first
|
|
|
|
|
.Fx
|
|
|
|
|
version to include it was
|
|
|
|
|
.Fx 5.0 .
|
|
|
|
|
.Sh AUTHORS
|
2004-06-17 19:51:17 +00:00
|
|
|
.An -nosplit
|
2003-06-10 18:53:15 +00:00
|
|
|
The
|
|
|
|
|
.Nm
|
|
|
|
|
driver was written by
|
|
|
|
|
.An Eduardo Horvath
|
|
|
|
|
.Aq eeh@NetBSD.org .
|
|
|
|
|
The man page was written by
|
|
|
|
|
.An Thomas Klausner
|
|
|
|
|
.Aq wiz@NetBSD.org .
|