tgconfig(1M)
tgconfig - configure Tigon3 gigabit ethernet interfaces
As shipped in IRIX 6.5.30. Last changed in IRIX 6.5.22.
NAME tgconfig - 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 DESCRIPTION tgconfig 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. 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. 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 { 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. 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. 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. 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 ALSO tg(7M), tgcmd(1M), devcfg(1M), ifconfig(1M), network(1M), ethernet(7).