EtherK User Guide
=================

EtherK is the device driver module that supports the Intel PRO/1000 Ethernet
controller on the Iyonix motherboard. It can also support Intel PRO/1000
Ethernet adapter PCI cards. For information on supported cards, see Appendix A.

Overview
========
The Intel PRO/1000 Ethernet controllers supported by EtherK can operate at
10Mbps half-duplex/full-duplex, 100Mbps half-duplex/full-duplex and 1000Mbps
full-duplex. By default all configuration is automatic, and when a cable is
connected the system will automatically detect the correct speed and duplex
settings, and also whether or not a crossover link is required. This feature
means that you can directly connect two computers together without needing a
special crossover cable or a hub. Simply connect an ordinary cable and the
system will automatically determine whether a crossover link is required.

Each network interface on your computer that is supported by EtherK is given a
unit name beginning with 'ek'. The first unit (e.g. the one on the Iyonix
motherboard) is called 'ek0'. Additional network cards will be called 'ek1',
'ek2' and so on. You need to use the unit name to specify the unit when using
commands such as 'IFConfig'. When using *Commands provided by the EtherK module
itself, you only need to specify the unit number. This is always the first
parameter to any command.

*Commands
=========

*EKInfo
-------
Displays information about Ethernet interfaces.

Syntax: *EKInfo [<unit number>] [-verbose]

*EKInfo displays information about the Ethernet interfaces driven by EtherK. If
no unit number is specified, information on all supported units is displayed.
If '-verbose' is specified, much more detailed statistics and driver
information is shown.

A full explanation of all the items displayed by *EKInfo is contained in
Appendix B.

*EKLog
------
Displays any messages that have been logged by the device driver.

Syntax: *EKLog [<unit number>]

*EKLog is used to display any messages that have been logged by the device
driver. If no unit number is specified, the message logs for all the supported
units are shown.

Messages are added to the message log when the driver is initialised, when the
link status changes, and when a driver error occurs.

*EKTest
-------
Starts a self-test for a given unit.

Syntax: *EKTest <unit number>

*EKTest is used to start a self-test for the given unit. A number of tests are
carried out, and the result of each one ('passed' or 'failed') is displayed.
The first test is the 'Link test' and this will fail if a valid link is not
present (if there is no cable connected, for example). The other tests all
relate to the hardware, so if any of the other tests fail, it may indicate a
hardware fault.

*Configure EKLink
-----------------
Sets the speed and duplex settings for a given unit.

Syntax: *Configure EKLink <unit number> Auto | 10 Half|Full | 100 Half|Full

*Configure EKLink is used to set the speed and duplex settings for the given
unit. The default setting is 'Auto' which means that the speed and duplex
settings are determined by auto-negotiation with the link partner. Under normal
circumstances it is recommended that you do not change this setting, but if
necessary it is possible to force the speed to either 10Mbps half-duplex,
10Mbps full-duplex, 100Mbps half-duplex or 100Mbps full-duplex.

When the link settings are forced, note that if the link partner is not also
forced to the same setting, a valid link may not be established. If the link
partner uses auto-negotiation, and you want to force selection of particular
speed/duplex settings, it is better to use *Configure EKAdvertise (see below)
to reduce the speed/duplex combinations available for auto-negotiation to the
ones that you want. It is not possible to force operation at 1000Mbps - this
must be auto-negotiated.

Note that if you disable auto-negotiation by forcing the speed/duplex setting,
automatic crossover detection will also be disabled.

When this command is entered the link settings are changed immediately. There
may then be a delay of up to four seconds while the system waits for the link
to be established.

*Configure EKAdvertise
----------------------
Sets which speed and duplex combinations are advertised for auto-negotiation by
a given unit.

Syntax: *Configure EKAdvertise <unit number> [10 [Half] [Full]] [100 [Half]
[Full]] [1000]

*Configure EKAdvertise is used to set which speed and duplex combinations are
advertised for auto-negotiation by the given unit. At least one speed/duplex
combination must be specified. If neither 'Half' nor 'Full' is specified after
'10' or '100', both duplex combinations are made available. For 1000Mbps
operation, only full-duplex is supported, so the duplex specification is not
needed.

The default state is that all valid combinations are advertised. These are
10Mbps half-duplex, 10Mbps full-duplex, 100Mbps half-duplex, 100Mbps full-
duplex and 1000Mbps full-duplex. This can be set by entering:

*Configure EKAdvertise <unit number> 10 Half Full 100 Half Full 1000

or

*Configure EKAdvertise <unit number> 10 100 1000

Note that changing this setting will not have an effect until the link is next
renegotiated. If you want to force renegotiation after changing this setting,
enter the command:

*Configure EKLink <unit number> Auto

*Configure EKFlowControl
------------------------
Controls whether a given unit automatically generates and/or responds to
Ethernet PAUSE frames.

Syntax: *Configure EKFlowControl <unit number> None | Generate | Respond | Full

*Configure EKFlowControl controls whether the given unit automatically
generates and/or responds to Ethernet PAUSE frames. By enabling interfaces to
adjust packet transmission, flow control helps prevent dropped packets.

If the setting is 'Generate' or 'Full' the interface will generate flow control
frames when the receive queue reaches a pre-defined limit. This signals the
transmitter to slow transmission.

If the setting is 'Respond' or 'Full' the interface will respond to flow
control frames by pausing packet transmission for the time specified in the
flow control frame.

To benefit from this feature, the link partner must also support flow control.

The default setting is 'Full'.

Appendix A - Supported Adapters
===============================

The EtherK device driver is software compatible with any Intel Ether PRO/1000
network adapter with an 82540, 82541, 82542, 82543, 82544, 82545, 82546 or
82547GI controller. 82547EI controllers are not currently supported.

In addition to the Iyonix motherboard controller, this driver is known to work
with the Intel PRO/1000 MT Desktop Adapter PCI card, but hardware compatibility
testing of other cards with the Iyonix motherboard has not been carried out at
this time, so you should confirm hardware compatibility before attempting to
use any other card.

Information on identifying Intel network cards, including which controller is
fitted to a particular card, can be found in the Network Adapter & Driver
Identification Guide at:

http://support.intel.com/support/network/adapter/index.htm

Appendix B - *EKInfo Statistics
===============================

The *EKInfo command displays a large number of items of information. This
appendix gives a brief explanation of each item in the order in which they are
displayed. Items that only appear when the '-verbose' parameter is specified
are enclosed in square brackets.

Note that in the 'Driver statistics' and 'Hardware statistics' sections,
statistics with a value of zero are not displayed. As some of the statistics
only relate to certain configurations, or only occur in rare circumstances, you
may not see many of the items listed here in normal operation.

Ethernet address
  The Ethernet (MAC) address of the interface.

[Controller]
  The part number of the Ethernet controller.

[Bus type]
  The type, speed and width of the bus to which the controller is connected.

[Media type]
  Shows the type of connector - either 'Copper' or 'Fibre'.

Link status
  Shows the link status ('up' or 'down') and the speed and duplex setting of
the current link.

Controller mode
  Shows the level of hardware packet filtering currently in force. The
possibilities are 'Disabled' (the interface is not currently active),
'Specific' (only packets addressed to this interface are accepted), 'Normal'
(specific and broadcast packets are accepted), 'Multicast' (specific, broadcast
and multicast packets are accepted), and 'Promiscuous' (all packets are
accepted).

[TBI compatibility]
  Whether or not TBI compatibility is enabled. This only applies to 1000Mbps
copper connections with the 82543 controller.

Frame types claimed
  Lists the frame types which protocol modules have registered an interest in,
together with the filter level for each frame type. Received frames which are
not of a recognised type, or do not match the filtering level for the given
type, will be discarded.

Hardware statistics summary
  Shows the total number of transmitted frames and bytes, the total number of
received frames and bytes, and the total number of transmit and receive errors
that have occurred since the driver was initialised.

Driver statistics

  Frames received
    The total number of frames received from the hardware by the driver.

  Dropped frames
    The total number of frames accepted by the hardware but rejected by the
driver due to errors. Normally the hardware will filter out packets with
errors, so this counter should not increase.

  Unwanted frames
    The total number of valid frames that were rejected because they did not
match any of the current filters shown in the 'Frame types claimed' list.

  Mbuf allocations failed
    The total number of valid frames which were rejected because there were no
free Mbufs available. The RISC OS network stack relies on a central pool of
memory blocks called 'Mbufs', and if these are all in use, it is not possible
for the device driver to pass data to a protocol module.

  Transmit Descriptors not available
    The number of times a packet failed to be transmitted because there were no
free transmit descriptors. The means that the transmit queue is full. This may
be because the system is attempting to transmit data faster than the hardware
can send it out.

  Oversized transmit frames
    The number of packets for transmission that were rejected by the driver
because they were too large.

  Transmit re-entrancy failures
    The number of times packets could not be transmitted because the transmit
function was re-entered or called while interrupt processing was taking place.
This should not normally happen. If this item appears, please report it to
Technical Support.

  Watchdog resets
    A watchdog reset occurs if the hardware stops transmitting data for some
reason. In normal use this should never happen. If it does occur, a message
will also be recorded in the message log. Please report this to Technical
Support.

  [Maximum transmit descriptors used]
    The highest number of transmit descriptors that have ever been in use at
once.

[Hardware configuration]
  This section displays some information on the internal configuration of the
Ethernet controller. This is only useful for diagnostic purposes.

[Full hardware statistics]
  This section displays the contents of all the controller's hardware
statistics. For the receive statistics note that a packet is counted as
received if it passes the current filter and is placed in the controller's
packet buffer. A packet does not have to be transferred to host memory in order
to be counted as received.

  [Receive counters]
    This section displays counters relating to data received by the interface.

    [Total Octets Received]
      The total number of octets received. All octets received will be counted
here, including those in flow control packets.

    [Total Packets Received]
      The total number of packets received. All packets are counted here,
regardless of their length, whether they have errors, or whether they are flow
control packets.

    [Good Octets Received]
      The total number of good octets received. This does not include octets of
received flow control packets.

    [Good Packets Received]
      The number of good packets received of any legal length. This only
includes packets that pass address filtering and does not include packets
counted in the Missed Packet Count or received flow control packets. The
following six counters break this total down by packet length.

      [Packets Received (64 bytes)]
        The number of good packets received that are exactly 64 bytes in
length, including CRC.
  
      [Packets Received (65-127 bytes)]
        The number of good packets received that are 65-127 bytes in length,
including CRC.
  
      [Packets Received (128-255 bytes)]
        The number of good packets received that are 128-255 bytes in length,
including CRC.
  
      [Packets Received (255-511 bytes)]
        The number of good packets received that are 256-511 bytes in length,
including CRC.
  
      [Packets Received (512-1023 bytes)]
        The number of good packets received that are 512-1023 bytes in length,
including CRC.
  
      [Packets Received (1024-1522 bytes)]
        The number of good packets received that are 1024-1522 bytes in length,
including CRC.

    [Broadcast Packets Received]
      The number of good broadcast packets received. Broadcast packets are not
counted if the hardware filter level is set to 'Specific'.
      
    [Multicast Packets Received]
      The number of good multicast packets received. This does not include
received flow control packets. Multicast packets are not counted if the
hardware filter level is set to 'Specific' or 'Normal'.

  [Transmit counters]
    This section displays counters relating to data transmitted by the
interface.

    [Total Octets Transmitted]
      The total number of octets transmitted. All octets transmitted will be
counted here, including those in flow control packets. Octets from partial
packet transmissions (e.g. collisions in half-duplex mode) are not counted.

    [Total Packets Transmitted]
      The total number of packets transmitted. All packets transmitted will be
counted here, regardless of their length or whether they are flow control
packets. Partial packet transmissions (e.g. collisions in half-duplex mode) are
not counted.
    
    [Good Octets Transmitted]
      The total number of octets sucessfully transmitted. This does not include
octets of transmitted flow control packets.
      
    [Good Packets Transmitted]
      The number of packets sucessfully transmitted of any legal length. This
does not include transmitted flow control packets. The following six counters
break this total down by packet length.

      [Packets Transmitted (64 bytes)]
        The number of packets successfully transmitted that are exactly 64
bytes in length, including CRC.
  
      [Packets Transmitted (65-127 bytes)]
        The number of packets successfully transmitted that are 65-127 bytes in
length, including CRC.
  
      [Packets Transmitted (128-255 bytes)]
        The number of packets successfully transmitted that are 128-255 bytes
in length, including CRC.
  
      [Packets Transmitted (256-511 bytes)]
        The number of packets successfully transmitted that are 256-511 bytes
in length, including CRC.
  
      [Packets Transmitted (512-1023 bytes)]
        The number of packets successfully transmitted that are 512-1023 bytes
in length, including CRC.
  
      [Packets Transmitted (1024-1522 Bytes)]
        The number of packets successfully transmitted that are 1024-1522 bytes
in length, including CRC.

    [Multicast Packets Transmitted]
      The number of multicast packets transmitted. This counter does not
include transmitted flow control packets.
      
    [Broadcast Packets Transmitted]
      The number of broadcast packets transmitted.

  [Flow control]
    This section displays counters relating to flow control packets.

    [XON Received]
      The number of XON packets received. XON packets can occur when Flow
Control is enabled and both the adapter and its link partner are configured to
use it.

    [XON Transmitted]
      The number of XON packets transmitted. XON packets can occur when Flow
Control is enabled and both the adapter and its link partner are configured to
use it.

    [XOFF Received]
      The number of XOFF packets received. XOFF packets can occur when Flow
Control is enabled and both the adapter and its link partner are configured to
use it.

    [XOFF Transmitted]
      The number of XOFF packets transmitted. XOFF packets can occur when Flow
Control is enabled and both the adapter and its link partner are configured to
use it.

    [Flow Control Receive Unsupported]
      The number of unsupported flow control frames that are received. This
counter will increment when a flow control packet is received which has a vlid
address but an incorrect opcode field. This counter is not expected to
increment.

  [Receive error counters]
    This section displays counters relating to packets received with errors.

    [Missed Packets]
      The number of missed packets. Packets are missed when the hardware
receive FIFO has insufficient space to store the incoming packet. This could be
because all of the receive buffers are full, or because there is insufficient
bandwidth on the PCI bus. These packets will also be counted in the Total
Packets Received counter as well as in Total Octets Received.

    [Receive No Buffers]
      The number of times that packets were received when there were no
available buffers in host memory to store those packets. The packet will still
be received if there is space in the hardware FIFO. This counter does not
include received flow control packets.

    [Receive Errors]
      The number of received packets where the PHY indicated a receive error.
For a packet to be counted here, it must pass address filtering and be at least
64 bytes in length, including CRC. For fibre connections, this counter will
increment on the reception of /V/ codes.

    [Alignment Errors]
      The number of received packets with alignment errors (i.e. the packet is
not an integer number of bytes in length). For a packet to be counted here, it
must pass address filtering and be at least 64 bytes in length, including CRC.
This is valid only during 10/100 Mbps operation.

    [CRC Errors]
      The number of received packets with CRC errors. For a packet to be
counted here, it must pass address filtering and be at least 64 bytes in
length, including CRC.

    [Receive Length Errors]
      The total number of receive length errors. A length error occurs if the
length, including CRC, of an incoming packet is undersized (less than 64 bytes)
or oversized (greater than 1522 bytes). Only packets that pass address
filtering are counted. The following four counters give more detail on these
errors.

      [Receive Undersize]
        The number of received packets that were less than the minimum size (64
bytes) and had a valid CRC.

      [Receive Fragment]
        The number of received packets that were less than the minimum size (64
bytes) but had an incorrect CRC.

      [Receive Oversize]
        The number of received packets that were greater than the maximum size
(1522 bytes) and had a valid CRC.

      [Receive Jabber]
        The number of received packets that were greater than the maximum size
(1522 bytes) but had an incorrect CRC.

    [Carrier Extension Errors]
      The number of packets received in which the carrier extension error was
signaled across the PHY interface. The PHY propagates carrier extension errors
to the MAC when an error is detected during the carrier extended time of packet
reception. This will only increment if the device is operating at 1000Mbps.

  [Receive information counters]
    This section displays counters relating to reception problems, but which
are not counted as packet reception errors.

    [Symbol Errors]
      The number of symbol errors between reads. The count increases for every
bad symbol received, whether or not a packet is currently being received and
whether or not the link is up. This only applies to fibre connections. This
statistic will increment along with the Sequence Error count when the fibre
cable is either disconnected or the connector is not seated correctly. This
statistic will also increment minimally when the driver is being initialised.
      
    [Sequence Errors]
      Describes receive sequence error events. This only applies to fibre
connections. This counter will increment when an illegal sequence of symbols is
received. This will increment along with the Symbol Error count when the fibre
cable is either disconnected or the connector is not seated correctly.

  [Transmit error counters]
    This section displays counters relating to packets with transmission errors.

    [Excessive Collisions]
      This counter increments when 16 or more collisions have occurred on a
packet. This only occurs if the device is in half-duplex mode.

    [Late Collisions]
      This describes collisions that occur after 64-byte time into the
transmission of the packet. This only occurs if the device is in half-duplex
mode.

  [Transmit information counters]
    This section displays counters relating to transmission problems, but which
are not transmission errors.

    [Single Collisions]
      The number of times that a transmitted packet encountered a single
collision. This only occurs if the device is in half-duplex mode.
      
    [Multiple Collisions]
      The number of times that a transmitted packet encountered more than one
collision but less than 16. This only occurs if the device is in half-duplex
mode.

    [Total Collisions]
      The total number of collisions seen by the transmitter excluding late
collisions. These only occur if the device is in half-duplex mode.

    [Defer Count]
      Describes transmit defer events. A defer event occurs when the
transmitter cannot immediately send a packet due to the medium being busy
either because another device is transmitting, because data is being received
in half-duplex mode, because an XOFF packet has been received or because the
link is not up.

    [Transmit with no CRS]
      Counts the number of successful packet transmissions in which the Carrier
Sense input from the PHY was not asserted within one slot time of start of
transmission. The PHY should assert Carrier Sense during every transmission.
Failure to do so may indicate that the link has failed, or the PHY has an
incorrect link configuration. This counter is not valid for fibre connections,
and is only valid when the device is operating at full duplex.

[PHY information]
  This section displays some extra information about the cable and connection.
It not shown for fibre connections.

  [Extended 10BaseT distance]
    Indicates whether or not the extended 10BaseT distance feature (for cables
longer than 100m) is enabled.

  [Polarity correction]
    Indicates whether or not the polarity correction feature is enabled.

  [Cable polarity]
    Identifies the +/- properties of the send and receive twisted pair wires
found in an Ethernet cable. If these properties are not correctly set up, the
interface will auto-correct and report the polarity as 'Reversed'.

  [MDI-X mode]
    Shows whether the cable attached to the interface has a straight-through
(MDI) or crossover (MDI-X) configuration.

  [Cable length]
    This is only shown when the link speed is 1000Mbps.
    Gives an estimate of the length of the cable between the interface and its
link partner. If this appears to be significantly different from the actual
cable length, it may indicate a cable fault. 

  [Local receiver status]
    This is only shown when the link speed is 1000Mbps.
    Identifies whether the cable connector attached to the interface is capable
of handling traffic. If the status is 'Not OK', check the connector for breaks
or mis-wirings. 

  [Remote receiver status]
    This is only shown when the link speed is 1000Mbps.
    Shows whether the cable connector attached to the link partner passes or
fails the set of operability tests. If the status is 'Not OK', check the
connector for breaks or mis-wirings. 

  [Receive errors]
    This is only shown when the link speed is 1000Mbps.
    Receive Errors occur when the adapter detects an unrecognisable
transmission on the wire. Receive Error counts naturally increment when the
adapter establishes communication with the network, (connecting the cable to
the adapter or restarting the computer) or when the adapter restarts after auto-
negotiation. If the Idle Error count reaches approximately 65,000 within five
minutes, there is a link quality issue. To resolve link quality issues, try re-
connecting the cable or using a different cable.

  [Idle errors]
    This is only shown when the link speed is 1000Mbps.
    Idle Errors increment when the adapter receives an unrecognisable
transmission on the wire. Unlike Receive Errors, Idle Errors are detected when
the adapter is not actively receiving packets. Idle Error counts naturally
occur when the adapter establishes communication with the network, (connecting
the cable to the adapter or restarting the computer) or when the adapter
restarts after auto-negotiation. If the Idle Error count reaches 255 within one
minute, there is a link quality issue. To resolve link quality issues, try re-
connecting the cable or use a different cable.

Appendix C - License
====================
The EtherK device driver includes software developed by Intel Corporation. This
comes with the following message:

Copyright (c) 2001-2003, Intel Corporation
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. Neither the name of the Intel Corporation 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 COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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.
