-----------------------------------------------------------------------------
7th September 1994
-----------------------------------------------------------------------------
Support Group Application Note: General information on Ethernet cards for 
                          RISC OS computers

Number: 264
Issue: 1
Author: CAS 
-----------------------------------------------------------------------------
Notes: 

This application note details some of the less well known features of
the Ethernet cards which Acorn supplies to its customers. At the present
time Acorn cards are manufactured by ANT Ltd and Ił and as a consequence the
information in this application is of direct relevance  to cards produced by
these manufacturers. However, much of the information concerning the
interpretation of statistical information can also be applied to cards by
other manufacturers.

This application note also examines the installation and use of Acorn Access
cards in AUN Gateways and TCP/IP sites.

-----------------------------------------------------------------------------
Applicable Hardware:  All RISC OS based computers fitted with RISC OS 3.10
                      or later.


Related Application Notes: None

-----------------------------------------------------------------------------
Copyright (C) Acorn Computers Limited 1994

Every effort has been made to ensure that the information in this leaflet is 
true and correct at the time of printing. However, the products described in
this leaflet are subject to continuous development and improvements and
Acorn Computers Limited reserves the right to change its specifications at
any time. Acorn Computers Limited cannot accept liability for any loss or
damage arising from the use of any information or particulars in this
leaflet. ACORN, ECONET and ARCHIMEDES are trademarks of Acorn Computers
Limited.
-----------------------------------------------------------------------------
Support Group
Acorn Computers Limited
Acorn House
Vision Park
Histon
Cambridge
CB4 4AE                                                  
-----------------------------------------------------------------------------


Introduction.

This application note will provide the more inquisitive user of Acorn
Ethernet networks with information concerning the setup and configuration
options of the cards supplied by Acorn. This application note is not
intended to guide the reader through the process of setting up an Ethernet
net. Those readers who require this information should refer to the
documentation supplied with either the Ethernet card(s) and the appropriate
network software.

Diagnostics and Self Test.

All cards supplied by Acorn are capable of performing a self test the first
time they are  powered up. In the case of the Ethernet III card the
subsequent self test behaviour is configurable by the user. See the section: 
Ethernet III configuration options. The Ił is not configurable in this
respect.

The following describes the basic tests performed by the Ił card:

     On power up or after a reset the software will perform a self test and cable check.

     On board buffer memory is tested.

     Internal and external loopback on NIC is used to test:

          DMA
          CRC generation and checking
          address recognition
          serializer/deserializer
          transmit and receive paths
          network interface

     External loopback tests the integrity of the cable and termination.

     Fault conditions are detected, diagnosed and reported.

Errors which are detected are usually reported at boot time or are
accessible from the *Netstat command. For example the Ethernet III card will
generate the following information on power up when in test mode:

     Locate controller . . . . . . . . . 16 bit SEEQ controller
     Testing for stuck interrupts  . . . PASSED
     Testing controller registers  . . . PASSED
     Testing individual interrupts . . . PASSED
     Testing buffer memory . . . . . . . PASSED
     Loopback test with correct CRC  . . PASSED
     Loopback test with incorrect CRC  . PASSED
     Loopback test with controller CRC . PASSED
     Live test with correct CRC  . . . . FAILED
     Warning: No access to network; restart computer to clear

or     *Netstat
     Warning: No access to network; restart computer to clear


Ethernet III card configuration

Setting the configuration

If the configuration of a card is stored in CMOS RAM (as is the case for all
podules or cards that fit in network slots) then the card configuration is
set using the *Configure command. The configuration command takes the form:

*Configure EtherX <option> [<n>]

Where X represents the type of driver (eg Ether3 or EtherB) and <option> is
the configuration option the user wishes to set.  For drivers that support
multiple cards (i.e.  drivers for podules rather than netcards) there is an
optional numeric parameter [<n>] to choose which podule slot is to be
configured.  If this parameter is omitted then the configuration will be set
on all suitable cards installed in the computer at the time.

Configuration options

Disable | Enable

Configure Enable if you wish to use the card. When configured to Disable
the card will not be self-tested nor will it transmit or receive any
packets.

OldInet | NewInet

Configure the Ethernet card to NewInet unless you are using versions of
the AUN modules Internet or InternetA prior to 2.00. This configuration
enables faster data transfers when NewInet is supported. Later issues of the
driver software set this configuration by default; older ones may not.

Strict | Ignore

If the interface is configured to be Strict then should the interface fail
its selftest it will return an error and not activate itself for network
accesses.  If the unit is configured to Ignore the selftest result then
the unit will activate itself even if the selftest fails.  The card should
always be in a Strict state for normal operation.

NoLiveWireTest | LiveWireTest

These configurations determine whether the Ethernet network cabling is
tested during the cards self-test sequence. When configured to
LiveWireTest both valid and erroneous packets are generated onto the
network and tests performed to see that they are correctly received.
Configuring NoLiveWireTest prevents the cabling test from being performed.

Terse | Verbose

When configured Terse the EtherX driver will only report information to
the user when there is a need.  The selftest of a card will happen silently
unless there is an error to report and the information command (EXInfo) will
only report statistics collected for the interface if the statistic count is
non-zero.  If the unit has been configured to be Verbose then all the
stages of the self test will cause a message to be printed and all the
statistics for the interface will be listed even when the count is zero.

Default

Configuring an interface to the Default state will set all five
configuration switches to the default settings.  For production versions of
the software the default state is:

Enable, OldInet1, Strict, NoLiveWireTest, Terse.

1 Old software only

Configuring the Pocket Ethernet Adaptor (PEA)

For cards that fit externally to the host machine, such as the PEA, the
configuration for the unit is stored in a system variable.  A system
variable of the form Ether<X>$Options is looked for on startup and if it is
found the content is parsed.  The content of the variable should be a list
of the options described above separated by spaces and/or commas.  Any
options that are not set are assumed to be in the default state.  If any 
option is set more than once the rightmost setting takes precedence.  This
variable is usually set in the !Configure file of a !Internet or !BootNet
application.  For example the setting for a pocket Ethernet adaptor might
be:

*Set EtherP$Options Strict, LiveWireTest, Verbose

Ethernet card driver information

Statisitcal information can be derived from ethernet cards using a command
such as *E3Info. This is this command for Ether3 (AEH54) cards.  RiscPC
ethernet cards and A3020 cards from Acorn use the command *EBInfo and
*EHInfo respectively. The statistical information varies from manufacturer,
but once understood it is possible to easily identify the appropriate
elements from any manufacturers card. eg.

*E3info Ether3 interface statistics

ea0: bussize 16 (1a), slot 0, enabled, hardware address 00:02:07:dd:ee:ae

packets received = 57368         packets transmitted = 12954 bytes
received = 7306050              bytes transmitted = 3656228 receive
interrupts = 57274            transmit interrupts = 12952 interrupts = 68569                    

Frame types recognised: 0x0800, 0x0806, 0x8035.

Or alternatively:

*ehinfo
DCI Version       2

Card Info:-       i-cubed ltd, EtherLan 200 Ethernet interface
                  Ethernet address=00:c0:32:00:0a:3c
                  i-cubed 10Base2 MAU adaptor connected.

I/O Stats:-       Rxframes=20, Rxerrs=0, Txframes=18, Txerrs=0
                  Collisions=0, Rejects=0

Description of statistical information from E<n>Info

The information will be categorised according to the headings used in each
cards statistics. The headings are structured Ethernet III card / Ił card.

Packets received/Rxframes

A count of the number of packets which have been received by the station.

Not provided/Rxerrs

A count of the number of packets which were received in an incomplete or
corrupted state. Normally this value should be 0. If it is not then there is
a fault on the network. Faults are reported as an additional line indicating
the type of error(s).

Packets transmitted/Txframes

A count of the number of packets which have been transmitted by the station.

Not provided/Txerrs

A count of the number of packets which were transmitted by the station and
received by the destination station in an incomplete or corrupted state.
Normally this value should be 0. If it is not then there is a fault on the
network. Faults are reported as an additional line indicating the type of
error(s).

Bytes received/Not provided

The total number of data bytes contained in the packets received by the
station.

Bytes transmitted/Not provided

The total number of data bytes contained in the packets transmitted by the
station.

Receive interrupts/Not provided

The total number of interrupts generated by the card for the purpose of
receiving data.

Transmit interrupts/Not provided

The total number of interrupts generated by the card for the purpose of
transmitting data.

Interrupts/Not applicable

The total number of interrupts generated by the card.

Not applicable/Collisions

A count of the number of times the computer has attempted to access the
network simultaneously with another.

Not applicable/Rejects

A count of the number of packets addressed to the computer but which were
not understood. On a pure AUN network this should always be 0.

The format of the Netstat information remains constant irrespective of the
manufacturer. The statistics from this command  are displayed as shown
below:

*Netstat a

Interface         ea  AUN Station       128.52 Full address     
136.170.128.52 Broadcast         136.170.135.255

Known nets        128   129   130   131   

TX stats          Data=1186, Immediate=2, Imm_Reply=2, Retry=150
                  Error=0, Data_Ack=1194, Data_Rej=283, Broadcast=935
                  (local=0, global=935)

RX stats          Data=1477, Immediate=2, Broadcast=21156, Discard=0
                  Retry=279, Error=0, Data_Ack=1031, Data_Rej=155
                  Imm_Reply=2, Reply_Rej=0

Module status     01

The most useful terms are generalised below:

TX stats     

Immediate       The number of times the Econet_<xxx>Immediate SWI calls have
been issued.

Imm-reply     Number of responses to the Econet_<xxx>Immediate SWI calls.

Retry     Number of times the station has had to re-send data due to the
packets being rejected by the receiving station. Data_rej should correlate
with this value.

Error     Number of transmission errors reported by the IP software.

Data_Ack      Number of successful packets sent

Data_rej      Number of times transmissions have been rejected. (See Retry.)

Broadcast     Number of broadcasts sent.

                Local      - restricted to the subnet
                Global      - restricted to the site

RX stats Unless specifically mentioned all statistics have the same meaning
as above but refer instead to receiving data.

Discard     A count of the number of packets received which the interface
software does not understand.

Possible hardware faults

IMPORTANT: Most electronic devices can be damaged by static electricity. To
reduce the possible adverse effects of static electricity note the following
points when installing any component(s) or upgrade:

     preferably work on an earthed antistatic mat, with an earthing
bracelet on your wrist

     avoid working in areas where there are man-made fibres, such as nylon
carpets and nylon clothing

     avoid touching the pins of components during fitting, unless you have
first discharged any static electricity you may have attracted.

A3000 computers

The procedures outlined below do not apply to A3000 computers. The network
interface card on an A3000 is intended to be fitted by an Acorn Authorised
Dealer, who will install and  test the upgrade. A charge may be levied by
the dealer for installing the upgrade; such a charge shall be entirely at
the discretion of the dealer concerned.  

In order to minimise the effects of static we recommend the following
procedure:

     dismantle the computer as described in the appropriate fitting
instructions

     Reconnect the computer to the mains, but do not switch on.

     While the computer is connected to the wall socket:

     Do not switch on the computer.

     Do not switch on power at the wall socket.

     Touch the power supply unit or the metalwork of the case to discharge
any static electricity that you may have attracted. (If you are
statically-charged, you may feel a tingling sensation when you do this.) 

     Complete the removal/fitting of the interface as described in the
appropriate instructions.

If you are suspicious that the line driver may be damaged by exposure to
static electricity then it is possible to test the integrity of the line
driver with a multi-meter. The design of the A3020 and A4000 network slot
cards prevent access to the necessary components in order to perform the
following test. In this instance these cards must be returned to your
supplier.


Ethernet III card showing line driver and diode protection.

Should the line driver be damaged it will require returning to your supplier
for the line driver to be replaced.

Ił Ethernet cards are fitted with a small fuse which will protect the
computer from damage in the event of a failure. This fuse can be damaged by
static and consequently may need replacing. If you are suspicious that the
fuse may have failed it can be tested using a multi-meter. Identify the
component marked F1; it is normally a round device rather like a capacitor
is shape. Using a meter measure the resistance across the two pins. If the
value is greater than 0 ohms then the fuse is damaged.

Note:      This fuse must be replaced with one of the same rating and type.
Do not fit a fuse of a different specification. If in doubt contact your
supplier before proceeding.

Acorn Access Ethernet cards

This section details some of the issues surrounding the use of Acorn Access
cards in different situations.

When an AUN Ethernet III card is placed into a machine the bulk of the
software is dormant on power up. This software consists of the following or
later modules:

     Ether3           1.26     *
     InternetA        1.13      
     NetMsgs          0.02      
     Net              1.21 
     BootNet          0.84     *

(Modules marked with * are active on power up)

The software is activated or switched on by the Bootnet module which
provides the * command:

*configure Bootnet On|Off

When Bootnet is configured on all the software modules on the card become
active.

The Internet module provides the communication centre which allows the
Ethernet card hardware to pass data to the computer. In order to ensure that
the software could be placed on a convenient sized ROM the Internet module
was cut down so that it only supported the features required by AUN. This
cut down Internet is named InternetA. As we shall see there are different
versions of the Internet module for different tasks.

!Gateway

It is often necessary to provide communication between two similar or
disparate networks. Under AUN this functionality is provided by a Gateway.
It was considered to be better for there to be a clear differentiation
between client and Gateway stations under AUN and so the Gateway function is
achieved by a software application; !Gateway. This requires an enhanced
version of the InternetA module; InternetAG, to be present in the computer.
In order to prevent a clash between the InternetA and the InternetAG modules
it is necessary to switch off the AUN client software (*Configure  Bootnet
off) before running the Gateway application. This results in the InternetAG
module been used instead of InternetA.

TCP/IP

In an Internet site (such as Acorn) the client stations may require access
to both Internet and AUN services. Provided in the AUN Level 4 Fileserver
pack is the !Bootnet application software for such a situation. It is
possible to achieve this level of connectivity by simply disabling the AUN
client software and running the !Internet and !Bootnet applications in that
order. The !Internet software provides a fully functioning version of the
Internet module called Internet. When this version of the software is loaded
it is not possible to use the !Gateway application, as this is superseded by
the gateway functionality provided by the Internet software.

Acorn Access

When an Acorn Access card is placed into a machine the Access software is
immediately activated on power up. This software consists of the following
modules:

     Ether3          1.26      *
     InternetA       1.13      *  
     NetMsgs         0.02      
     Net             1.21    
     AccMsgs         0.01      *    
     BootNet         0.84      *    
     Freeway         0.10      *
     ShareFS         2.23      *    
     ADFSFiler       0.69      *

(Modules marked with * are active on power up)

The presence of the InternetA module at power up normally renders the Acorn
Access card unsuitable for use in a Gateway computer or as a client in a
full Internet site. This is because the InternetA module is incompatible
with the other versions needed by !Gateway and !Internet. In order to
provide the necessary alternative the InternetA module needs to be unlinked
from the other software before it can be replaced. The links to the other
modules then need to be rebuilt. 

As you can imagine, this is a somewhat involved and convoluted process. The
remainder of this document describes this process and thus enables Acorn
Access cards to be used in these environments.

Integrating Acorn Access and TCP/IP.

This is the most straight forward of the different scenarios to get working
successfully. It requires the building of a two stage boot sequence which
includes a file which is accessed before the desktop is active and a file
which is called when the desktop becomes active.

The information provided here assumes that the necessary changes to the
!Internet and !BootNet application have been implemented. If a !Boot file;
of type Desktop, already exists then rename it as Desktop.

Using !Edit create an Obey file which contains the following lines:

RMKill InternetA      
RMKill ShareFs      
RMKill Freeway      
RMKill AccMsgs      
Run ADFS::4.$.Apps.tcp_ip.!Internet.!Run      
RMReinit AccMsgs      
RMReinit Freeway      
RMReinit ShareFs      
Run ADFS::4.$.Apps.tcp_ip.!BootNet.!Run      
Desktop -f ADFS::4.$.Desktop | Used if there is a Desktop file      
|Desktop | Used if there isnt a Desktop file.

Note:   The pathnames to the applications and files may vary according to
the disc structure used. The order in which the modules are *RMReinit-ed is
vital.

Save this file as !Boot and reset the machine.

Integrating Acorn Access and !Gateway.

A two stage boot sequence is required. The information provided here assumes
that the necessary changes to the !Internet and !BootNet application have
been implemented. If a !Boot file; of type Desktop, already exists then
rename it as Desktop.

Using !Edit create an Obey file which contains the following lines:

RMKill Freeway      
RMKill Sharefs      
RMKill InternetA      
RMKill AccMsgs      
Desktop -f ADFS::4.$.Desktop

Note:   The pathname to the Desktop file may vary according to the disc
structure used.

Save this file as !Boot.

Using !Edit create a file of type Desktop or alternatively add these lines
to the very start of an existing Desktop file:

Run ADFS::4.$.Network.!GateWay      
RMReinit AccMsgs      
RMReinit sharefs      
RMReinit Freeway      
Run ADFS::4.$.Network.!Server | Optional     
Run ADFS::HardDisc4.$.Network.!AAServer | Optional      
Share ADFS::HardDisc4.$ HardDisc4 | Mandatory for each exported disc

Save this file as $.Desktop.

Notes:

!Gateway:      This must be started after the desktop otherwise the gateway
               icon will not appear on the icon 
               bar, although the gateway will function correctly.

!AAServer:     If this is required on the Gateway machine, as well as
               Acorn Access, then the reference to 
               -readonly must be removed from the !AAServer.!Config. If
               this is not done then the error Bad parameters will
               occur and !AAServer will fail to start.

               This has the added side effect of the contents of the
               !Config file being passed straight to the command line where 
               they are interpreted by Acorn Access. As a consequence they will 
               appear as unprotected Access disc icons, thus preventing them 
               from being accessed by !AAClient computers.

               If the !AAServer directory(ies) are exported from the desktop 
               each time then the commands are correctly passed to the !AAServer 
               and exported accordingly.

Share          This command is mandatory and is necessary for each of the 
               exported Access discs in order to remind ShareFS of its exports. 
               Failure to do this will result in any saved exports remaining 
               unavailable.


