tgconfig(1M)tgconfig(1M)NAMEtgconfig - configure Tigon3 gigabit ethernet interfaces
SYNOPSIS
/usr/etc/tgconfig [-s] [-f config_file ]
/usr/etc/tgconfig -c [-f config_file ]
/usr/etc/tgconfig -g
/usr/etc/tgconfig -a device_id label=value
DESCRIPTIONtgconfig is a wrapper script around the general purpose devcfg(1M) device
configuration utility. It is used to set, report and modify
configuration parameters for the Tigon3 gigabit Ethernet ('tgN')
interface(s). Typical uses include setting link preferences (speed,
duplex and flow control) and tuning the interrupt coalescence values (to
optimize performance for maximum throughput or minimum latency). Note
that tgconfig is not used to set a Tigon3 interface's Protocol (e.g. IP)
Address or Maximum Transfer Unit (MTU) size - these are set via
ifconfig(1M).
The Tigon3 driver expects to have its configuration set via tgconfig
prior to any of its interfaces being brought up via ifconfig. Since
tgconfig is run automatically (from the /etc/init.d/network script) at
system startup prior to bringing up any 'tgN' interfaces configured in
the /etc/config/netif.options file, most users will never need to
explicitly run tgconfig.
However, if no Tigon3 interfaces appear in the /etc/config/netif.options
file, so that the configuration is not set during network startup, and if
a Tigon3 interface is then manually brought up via ifconfig, the driver
will bring up the interface using hardcoded default configuration values
after logging the following warning message to the console:
WARNING: tgN: Missing configuration; using hardcoded defaults.
OPTIONS
MODES: tgconfig operates in one of four modes: Set, Check, Get or Add, as
specified by the -s, -c, -g and -a command line switches, respectively.
If more than one of these switches exist, the last one is used and the
previous values are ignored.
-s Set mode. The configuration file is parsed by devcfg, and its
contents are passed to the Tigon3 driver. The driver verifies all
device identifiers, labels and values. If no errors are detected,
the driver saves the configuration, to be applied to each interface
as it is brought up. Any previously existing configuration is
overwritten. Exception: if devcfg detects a syntax error in the
configuration file, or if the driver detects an unknown device
identifier, unknown parameter label, or illegal parameter value, an
informative error message is output and the new configuration is
ignored.
Page 1
tgconfig(1M)tgconfig(1M)
Note: the new configuration settings will not be immediately applied
to an interface which is already up. If an interface which is
already up has its configuration changed, the following message will
be output to the console once for each such interface:
NOTICE: tgN configuration has changed while the interface was up.
Changes will be applied when tgN is downed.
and the interface will need to be ifconfig'ed down and then back up
again to apply the new configuration.
-c Check mode. The configuration file is checked for errors, but not
applied. This can be useful as a sanity check when editing the
configuration file.
-g Get mode. The currently saved configuration (if any) is retrieved
from the driver and written to standard output in the format of a
tgconfig.options file (without the comments, and probably
reordered), such that it could be subsequently sent back to the
driver in Set mode.
This is useful to verify that the driver has saved a previously set
configuration. It can also be used to save, in a reusable form, a
configuation which was interactively edited while in Add mode.
-a device_id label=value
Add mode. Add or modify a single configuration parameter in the
driver's saved parameters. The -a switch must be immediately
followed by a device identifier and label=value pair, in that order.
The device identifier device_id specifies the interface on which the
change is to be performed.
The label=value pair specifies the configuration parameter to be
added or modified, and the value that the parameter is to be set to.
For example,
tgconfig-a tg2 coal_usecs_rx=100
will modify the receive coalescence timeout value to 100 usecs on
the tg2 interface.
Add mode can also be used to modify a "default" parameter (see
CONFIGURATION FILE FORMAT below):
tgconfig-a defaults flow_ctrl=NEG_OFF
-f config_file
Specifies an alternate configuration file to be scanned in Set or
Check mode. If this argument is omitted,
/etc/config/tgconfig.options will be used as a default. This
argument is ignored in Get or Add mode.
Page 2
tgconfig(1M)tgconfig(1M)FILES
/etc/config/tgconfig.options Default Tigon3 configuration file
/usr/etc/devcfg General purpose device configuration
utility
CONFIGURATION FILE FORMAT
A tgconfig configuration file consists of one or more blocks of parameter
definitions, delimited by curly braces and optionally separated by blank
and/or comment lines. Comment lines begin with a '#'. All whitespace on
a line is treated the same (indentation is not significant).
Each block consists of one or more DEVICE: lines, followed by a line
containing just a left curly brace, followed by one or more parameter
definitions in label=value format, followed by a line containing just a
right curly brace.
The DEVICE: line(s) which precede each block specifies which interface(s)
the enclosed configuration parameters apply to. Each DEVICE: line
contains a "device identifier" which specifies one interface to be
associated with that block. This device identifier can be specified
either in terms of the unit number (e.g. "tg3"), or the physical hardware
path
(e.g. "/hw/module/001c01/Ibrick/xtalk/14/pci/1/tg").
Note: use "find /hw -name tg" to find the physical paths of all Tigon3
cards installed in a system.
It is expected that all the device identifiers found in a tgconfig
configuration file would be of the same type - i.e. physical path and
unit name types would not be mixed. This is not a requirement; however,
if the same interface is referenced both by its physical path and its
unit name, the driver would detect this as an error.
In addition to the physical path and unit number form of device
identifiers, the driver recognizes the special identifier string of
"defaults", to indicate that the enclosed configuration parameters are to
be applied to any interfaces which do not appear in a DEVICE: line of
another block.
In the simplest (and most common case) a configuration file can contain
just a "defaults" block, which defines the configuration parameters to be
applied to ALL Tigon3 interfaces.
SAMPLE CONFIGURATION FILE:
# Tigon3 Gigabit Ethernet controller custom
# configuration.
# Specify default configuration, to be applied
# to interfaces which don't have their own block.
DEVICE: defaults
{
Page 3
tgconfig(1M)tgconfig(1M)
autoneg=ON
link_pref=AUTO
flow_ctrl=ON
# (Remaining definitions deleted for brevity)
}
# Lock tg1 and tg3 interfaces down to 100 Mbps
# full duplex, with flow control disabled.
DEVICE: tg1
DEVICE: tg3
{
autoneg=FALSE
link_pref=100_FULL
flow_ctrl=OFF
}
CONFIGURATION PARAMETERS
The most common configuration parameters that are supported by the Tigon3
driver are documented below. See the comments within the installed
version of /etc/config/tgconfig.options for a more complete listing.
LINK RELATED PARAMETERS: The following parameters control how the link is
initialized with respect to its physical data transfer characteristics
(data rate, full or half duplex, and flow control) and whether those
characteristics are negotiated with the link partner or forced via
hardware.
Note that many parameter values are not allowed for fiber cards, because
fiber links are always set to 1000 Mbps full duplex.
autoneg
Controls whether the link attempts to negotiate the link
characteristics with its link partner during initialization. During
autonegotiation, each link partner advertizes which link speeds (10,
100 or 1000 Mbps) and duplex modes (full or half) it can support,
and also whether it supports flow control.
ON (Default) Link will initiate and respond to autonegotiation.
Note that the gigabit specification REQUIRES autonegotiation.
OFF Link will not initiate or respond to autonegotiation. The link
speed and duplex specified by the link_pref parameter will be
set unconditionally. Autonegotiation should probably only be
disabled when the link partner is a very old (non-gigabit)
device which does not support autonegotiation. Note that
setting link_pref to AUTO or 10_100 is not allowed when
autonegotiation is disabled, because they specify multiple
speed and duplex settings.
intr_cpu
Specifies which CPU an interface's interrupt thread runs on. The
value -1 (Default) allows IRIX to choose the CPU.
Page 4
tgconfig(1M)tgconfig(1M)
link_pref
Link preference settings - a combination of data rate(s) and duplex
setting.
AUTO (Default) Rely on the autonegotiation process to set the
fastest possible speed and appropriate duplex value with the
link partner. Link speeds of 10, 100 or 1000 Mbps, and full or
half duplex are possible for copper cards. For fiber cards,
only 1000 Mbps full duplex is possible. This setting requires
auto_neg to be set to ON.
10_100
Behave like a Fast Ethernet interface when negotiating. Full
or half duplex is possible, but link speeds are limited to 10
or 100 Mbps. This setting requires autonegotiation to be
enabled. This setting is not allowed for fiber cards.
1000_FULL
With autonegotiation enabled, the card will only advertize 1000
Mbps full duplex. With autonegotiation disabled, the link will
be locked down to 1000 Mbps full duplex.
1000_HALF
With autonegotiation enabled, the card will only advertize 1000
Mbps half duplex. With autonegotiation disabled, the link will
be locked down to 1000 Mbps half duplex. This setting is not
allowed for fiber cards.
100_FULL
With autonegotiation enabled, the card will only advertize 100
Mbps full duplex. With autonegotiation disabled, the link will
be locked down to 100 Mbps full duplex. This setting is not
allowed for fiber cards.
100_HALF
With autonegotiation enabled, the card will only advertize 100
Mbps half duplex. With autonegotiation disabled, the link will
be locked down to 100 Mbps half duplex. This setting is not
allowed for fiber cards.
10_FULL
With autonegotiation enabled, the card will only advertize 10
Mbps full duplex. With autonegotiation disabled, the link will
be locked down to 10 Mbps full duplex. This setting is not
allowed for fiber cards.
10_HALF
With autonegotiation enabled, the card will only advertize 10
Mbps half duplex. With autonegotiation disabled, the link will
be locked down to 10 Mbps half duplex. This setting is not
allowed for fiber cards.
Page 5
tgconfig(1M)tgconfig(1M)
flow_ctrl
Enable or disable the sending and receiving of 802.3x XON/XOFF PAUSE
frames for flow control.
ON (Default) If autonegotiation is enabled, advertize flow control
capability. If autonegotiation is disabled, force flow control
to be enabled.
OFF If autonegotiation is enabled, do not advertize flow control
capability. If autonegotiation is disabled, force flow control
to be disabled.
INTERRUPT COALESCENCE PARAMETERS: In order to reduce overhead related to
interrupt handling, the Tigon3 cards can send or receive multiple
ethernet frames before interrupting the driver. This feature is called
interrupt coalescence.
coal_mode
Defines the overall interrupt coalescing mode.
ADAPTIVE
(Default) The driver will adapt the interrupt coalescence
values dynamically, based upon the current traffic level. At
low traffic levels, interrupt coalescing will be minimized in
order to reduce latency. At high traffic levels, interrupt
coalescing will be maximized in order to reduce CPU usage.
FIXED
The coalescence values will remain static after being set to
the values specified by the coal_frames_rx, coal_usecs_rx,
coal_frames_tx and coal_usecs_tx parameters (see below).
Interrupts can originate from either the send or receive engines on the
card. Each engine has two coalescing values, one specifying a frame
count and the other specifying a time delay. For both engines, an
interrupt will be generated when EITHER the specified number of frames
has been sent/received, OR the specified time delay has elapsed since the
first frame (after the previous interrupt) was sent/received.
The coalescence values for sent packets are set via these two parameters:
coal_frames_tx
The card will interrupt when it has sent this many ethernet frames
since the last interrupt.
coal_usecs_tx
The card will interrupt when this many microseconds have elapsed
since the first frame was sent (after the last interrupt).
Note that setting both coal_frames_tx and coal_usecs_tx to zero will
cause the driver to substitute values (appropriate for the MTU size) that
have been chosen to minimize the number of transmit related interrupts.
Page 6
tgconfig(1M)tgconfig(1M)
Since these interrupts can be delayed without impacting performance,
these two parameters should always be left at zero.
The coalescence values for received packets are set via these two
parameters:
coal_frames_rx
The card will interrupt when it has received this many ethernet
frames since the last interrupt.
coal_usecs_rx
The card will interrupt when this many microseconds have elapsed
since the first frame was received (after the last interrupt).
Unlike the case with sending packets, interrupt response time for
received packets has a critical impact on performance.
By tuning these two configuration parameters, performance can be
optimized either for maximum throughput or minimum latency (i.e. response
time). Increasing these values reduces the interrupt rate, which can
improve overall throughput by reducing CPU load. Decreasing coal_usecs_rx
can reduce latency by decreasing the interrupt response time.
Note that setting both coal_frames_rx and coal_usecs_rx to zero will
cause the driver to substitute values (appropriate for the MTU size)
which are optimized for high traffic rates and reduced CPU usage at the
cost of high latency.
SEE ALSOtg(7M), tgcmd(1M), devcfg(1M), ifconfig(1M), network(1M), ethernet(7).
Page 7
