/********************************************************************
*	THE USE BY YOU OF THIS SOFTWARE IS GOVERNED IN ALL
*	RESPECTS BY THE MADGE NETWORKS LTD OPEN SOURCE LICENSE.		
*	WE ADVISE YOU TO READ THE TERMS OF THE OPEN SOURCE LICENSE
*	WHICH CAN BE FOUND WITHIN THE LICENSE.TXT FILE WHICH IS PART OF
*	THE SOFTWARE OR BY VISITING THE URL
*	http://www.madge.com/Connect/Downloads/Software/.		
*	MADGE NETWORKS LTD RESERVES THE RIGHT TO SEEK REDRESS FOR
*	ANY VIOLATION OF THE LICENSE'S TERMS					
*********************************************************************/

Notes on the Madge Networks Token-Ring Driver For Linux
=======================================================

Contents
--------

    1. Platforms Supported
    2. Adapters Supported
    3. Contents of the Distribution
    4. Building the Driver
    5. Installation
    6. Command Line Parameters
    7. Installing a kernel patch

1. Platforms supported
----------------------

This driver has been tested on uniprocessor kernel versions:-

    2.0.36
    2.2.5-15
    2.2.10
    2.2.12-20
    2.4.2-2

2. Adapters Supported
---------------------

The following Madge Token-Ring adapters are supported:

    * 51-05 Smart Mk4 PCI Adapter
    * 53-05 Smart Mk4 PCI Adapter (low profile)
    * 3140 2010 Rapidfire 3140V2 16/4 TR PCI Adapter
    * 20-03 Smart 16/4 CardBus Mk2


3. Contents of the Distribution
-------------------------------

    ./            README     - This file.

                  Makefile   - The 'Makefile'.

                  config.in  - Default configuration options for the driver.

                  driver.h   - Configuration file for the Universal Driver
                               Toolkit (UDT).

                  madgetr.c  - Main driver source.

                  madgetr.h  - Main driver header.
                  ver.h      - Some macro definitions to try to make the
                               driver source as compatible as possible over
                               different kernel versions.

                  madgecs.c  - Source for the PCMCIA helper.
                  madgecs.h  - Header for the PCMCIA helper.

                  madgecb.c  - Source for the CardBus helper.
                  madgecb.h  - Header for the CardBus helper.

    ./udt                    - UDT source and header files.

    ./utils       trconfig.c - A command line utility to display information
                               about Madge Token Ring Adapters currently
                               running.  Demonstrates how to use the IOCTL
                               interface.  Also used to turn on/off MAC
                               frame reception.

                  mver.c     - A command line utility to extract Madge
                               product information strings from files.

                  llcping.c  - A command line utility to send a TEST or XID
                               frame to another node and wait for the
                               response.


4. Building the driver
----------------------

Prerequisites

You must have at least the kernel headers installed, and if you want to
build the PCMCIA/CardBus helper modules, you must have unpacked the
pcmcia-cs source tree somewhere.  Under RedHat the pcmcia source files can
normally be found under /usr/src/linux/pcmcia-cs-*.  The location varies on
other distributions.

Note: 
RedHat release 7 and upwards have the pcmcia/CardBus files bundled along with
the kernel. The release does not provide the k_compat.h file, which has been
provided in this distributiona and will be using this file during complilation.
If you would like to use any of the pcmcia-cs-* releases, then
you will have to compile the release with the kernel. For instructions on
compiling the release, please refer to the readme files with the release.

Step 1:   Run make

The first time you run make on a clean distribution a configuration script
will run.  It asks for the location of a kernel source tree.  This source
tree must have been configured and make dep run.  It is best if the source
tree has been configured and a kernel made from it and that kernel is
running when the Madge Token Ring driver is built.

The kernel configuration options can either be taken from the running kernel
or from the kernel source tree.  If the driver is to be used with the
running kernel select that option.

If you are building a driver to be used on a kernel version that is
different from the kernel version that is currently running you will not be
allowed to take configuration options from the currently running kernel.

For the vast majority of cases it is fine to accept the default driver
options.

Note: SuSE 6.0 comes with two versions of the GNU C compiler.  The default
version that is executed when gcc is run (egcs 2.91) is not suitable for 
compiling kernel version 2.0.36 or kernel modules.  Instead the other
version (gcc 2.7.2.3) must be used.  The configuration script should detect
SuSE 6.0 and set the C compiler to be "gcc -V 2.7.2.3".
If the other compiler is inadvertently used to compile the mtok module the
compilation will fail.

Step 2:  Run make

After configuring various locations make must be run again to build the 
driver.  The driver file is called mtok.o.  The PCMCIA helper driver is
called mtok_cs.o and the CardBus helper is called mtok_cb.o.
These modules will be found in the root of the distribution directory.

The PCMCIA helper needs the PCMCIA header files from David Hinds' 
(dhinds@allegro.stanford.edu) PCMCIA distribution. (Version 2.9.7 from 
hyper.stanford.edu/pub/pcmcia was used during development.).

If you do not wish to build the PCMCIA or CardBus helper driver just
answer no in the configuration script when asked.

Please read the PCMCIA-README file for more information on using Madge
PCMCIA and Cardbus Token Ring adapters.

5. Installation
---------------

The mtok.o driver is intended to be used as a loadable module.
It must be copied to the /lib/modules directory.

The following command can be used to copy the modules into the appropriate
places:-

    "make install"

The kernel must be told which device drivers should be used for which
network interfaces.  This is done by adding lines to the file
/etc/conf.modules (called modules.conf on some systems).

Add a line as follows:-

       alias tr0 mtok

This tells the system that the first Token Ring interface will be
controlled by the Madge driver.

If you will be using the module to control a PCMCIA adapter you must
include in your options line the following:-

       options mtok pcmcia=1

Having done this a command depmod must be executed as follows:-

       depmod -a

This rebuilds the database of module dependancies to include the Madge
module.

The command "ifconfig tr0" or "/sbin/insmod mtok" should automatically 
load the Madge module now and display its MAC address.

The LAA can be set as follows:-

    ifconfig tr0 hw tr 4000DEADBEEF

You can now use your distribution specific tools to configure the tr0
interface with an IP address and to manipulated the TCP/IP routing
table.

For a PCMCIA these additional steps must also be taken

To the file /etc/pcmcia/config add the lines:

    device "mtok_cs"
        class "network" module "net/mtok", "pcmcia/mtok_cs"

    device "mtok_cb"
        class "network" module "net/mtok", "pcmcia/cb_enabler", "pcmcia/mtok_cb"

    card "Madge Token Ring PCMCIA Adapter"
        version "MADGE", "SMART 16/4 PCMCIA RINGNODE"
        bind "mtok_cs"

    card "Madge Token Ring CardBus Adapter"
        version "MADGE", "CARDBUS ADAPTER MK 2"
        bind "mtok_cb"

These lines should be added before the line:

    source ./config.opts

The cardmgr daemon must be restarted or the machine must be rebooted for
these settings to take effect.


6. Command Line Options
-----------------------

The Token-Ring driver module mtok.o supports several command line options.
Each option is specified using its name and then a comma separated list of
values corresponding to each Token Ring adapter controlled by the driver.

For example:-

    insmod mtok ringspeed=16,0,100

This means tr0 will open at 16 MBps, tr1 will try to auto detect or use the
default value for the adapter and tr2 will try to open at 100MBps.

The driver options are list below:-

ringspeed=N

    Specifies that the adapter should operate at the following ring speed:

        N=0   -> The ring speed to which the adapter has been programmed.
        N=4   -> 4 MBit/s
        N=16  -> 16 MBit/s
        N=100 -> 100 MBit/s

dtr=N

    Specifies in which mode the adapter should open.

        N=0 -> Either DTR or Classic Mode (DTR on a switch port and classic
               on a shared hub).
        N=1 -> DTR mode only.
        N=2 -> Classic mode only.

pcmcia=1

    Normally the driver will only stay loaded in memory if it successfully
    finds and configures an adapter. However if a PCMCIA/CardBus adapter is to
    be used the driver must always be resident. Using the parameter 
    pcmcia=1 ensures that the driver stays resident.

txslots=N

    Specifies the number of transmit slots to be used.  The default depends
    on the adapter type.  Increasing this number uses more memory but
    allows more frames to be queued on the adapter for transmission.
    It is not advisable to queue too many transmits as this may interfere
    with higher layer flow control and queueing algorithms.

rxslots=N

    Specifies the number of receive slots to be used.  If this parameter is
    increased then more memory will be used by the driver but more frames
    can be queued for reception.

maxframesize=N

    Specifies the maximum frame size the adapter will be able to receive.
    This parameter has a maximum value of 4486 for an adapter running at
    4MBps and 17814 for adapters running at 16 and 100MBps.  The default
    value is 2040.  Performance improvements may be obtained by increasing
    this parameter if other machines on the network are also capable of
    sending and receiving large frames.

7.  Installing a kernel patch
-----------------------------

If you are using a Madge Token Ring adapter in a remote boot setup or for
some other reason require the driver to be included into the kernel rather
than built as a module you will need to patch the kernel source tree.
This procedure makes all Madge Token Ring interfaces available before the
root partition is mounted.  This allows the root partition to be an NFS
mounted directory for example.

Procedure:-

    1.  Ensure that the kernel source tree you wish to patch is downloaded
        and unpacked.

    2.  From in the directory you installed the Madge Token Ring Linux driver
        source code run:-

            "make patch"

    3.  Enter the directory name of where the Linux source tree to be
        patched is located. e.g. /usr/src/linux
    
    4.  Use one of the kernel configuration mechanisms to reconfigure the
        kernel:-

            "make config"       OR
            "make menuconfig"   OR
            "make xconfig"

    5.  Under menu item "Network Device Support" select YES to "Token Ring
        driver support" and YES to "Madge Token Ring adapter support"

    6.  Recompile the kernel as follows:-

            "make dep ; make clean ; make bzImage"

    7.  Copy the new kernel (arch/i386/boot/bzImage) to an appropriate place
        edit /etc/lilo.conf and rerun /sbin/lilo.  (See your distribution
        documentation for more information on this stage).

Beware that compiling the Madge driver into the kernel will increase the
kernel size significantly.  It may be necessary to compile other non
essential devices for booting as modules in order to decrease the kernel
size sufficiently to make space for the Madge driver.

Kernel patches are supplied for 2.0.36 and 2.2.10.  These patches will
generally apply successfully to similar kernel versions too.
They have not been tested for any other kernel versions and we cannot
guarantee they will work for other versions.


**** End of README ****
