Token-Ring HOWTO
Mike Eckhoff (meckhoff@zaphod.wayne.esu1.k12.ne.us)
7/5/95 - Rev 3
To make reading/printing of this document easier, be sure that your margins
are set to ".3" and you are using a proportional font like Courier.

The Ethernet-HOWTO file mentions the Token Ring driver that is being worked
on.  This howto is designed to help you install the kernel patch and also try
to point out some things to look for.  I suggest that you at least browse
through all of this document before attempting to install any part of the
Token ing driver for Linux.

Special Thanks to Mark Swanson, Peter De Schrijver, David Morris and everyone 
	else I may have missed who made this driver possible.

Also thanks to:
 Larry Sanders (lsanders@iadfw.net) 

  ...who corrected me in a few places.

Copyright and other Jazz
------------------------

	We do not guarantee that this howto will be accurate for your system.
	Several people have used it and had very good results in installing
	Linux on a Token Ring network.

	USE THIS HOWTO AT YOUR OWN RISK!!! ... We are not responsible for 
	any problems caused by using this howto.

	If you have any problems with the driver that are not talked about
	in this howto, feel free to email me at...
		meckhoff@zaphod.wayne.esu1.k12.ne.us

	This document is copyright (c) 1995 by Michael Eckhoff.  You may 
	make copies of this document in whole or in part, in any medium 
	physical or electronic, as long as the copyright notice is 
	retained on all copies.  Commercial redistribution is allowed and
	encouraged; however, please notify me so that I can make sure that
	you have the most current information available.



INDEX
-----

	I.	Hardware Requirements
	II.	Software Needed
	III.	Installation and Setup
	IV.	NetTools Installation
	V.	Known Problems
	VI.	Questions


----

I.  HARDWARE REQUIREMENTS

       Make sure that you have a Token Ring card that is supported by this
       driver.  Currently the only cards that are supported are those that
       use the Tropic chipset.  
       Cards that I personally know to work are:

	      IBM Token Ring 16/4 adapter /A
	      IBM Token Ring adapter /A
	      IBM Token Ring adapter II (4 Megabit only)
              IBM 16/4 ISA Token Ring card (16bit)
              IBM 16/4 ISA Token Ring card (8bit)
              3Com TokenLink Adapter (IBM and 3Com mode)
	      HyperRing Classic 16/4

	Please note that IBM makes a DMA/busmaster adapter for ISA with
	the name:

	      Token-Ring Network 16/4 Adapter II

	which will *NOT* work.  Do not confuse this card with the IBM
	Token Ring adapter II (4mbit) which does.

      If you find another card that works please email me the brand and type 
      of card so that I may add it to my list.  
                            - meckhoff@zaphod.wayne.esu1.k12.ne.us.


II. SOFTWARE NEEDED.

	NOTE:  The 1.3.x Linux kernels include the Token Ring driver.
		If you are using this kernel, you can skip to the
		NetTools section.
    
    This assumes you already have Linux up and running.
 
    Obtain the Token Ring patch from:
             ftp://linux3.cc.kuleuven.ac.be/pub/Linux/TokenRing/

    It will have a filename like TokenRing.patch-1.2.0.gz.  If you are
    not running at least kernel version 1.2.0, you probably should be.  I 
    have tested this patch on kernels 1.2.0 - 1.2.10 without any problems.  
    If you cannot upgrade your kernel to version 1.2.x, try installing 
    this patch anyway.  If it works, great!  If not, there are some 
    older versions of the patch on this site that you may want to try.
    I have ran the kernel with other versions of the patch since 1.1.5?.

    Obtain the NetTools patches from:
      ftp://linux3.cc.kuleuven.ac.be/pub/Linux/TokenRing/
						Nettools-1.1.95-TR.diff.gz

     Create a directory for the patches(such as /usr/src/patches) and place
     the patches there.
  
       mkdir /usr/src/patches             central directory for patch storage
       mkdir /usr/src/patches/token       place TokenRing patch here
       mkdir /usr/src/patches/nettools    place Nettools patch here


    Obtain the NetTools source from your normal Linux source provider,
    or from:
          ftp://tsx-11.mit.edu/pub/linux/packages/net/PROGRAMS/NetTools/
          net-tools-1.2.0.tar.gz


III.  INSTALLATION AND SETUP

1.  Install the TokenRing card into the system and configure it for the settings
    that you want to use.  It is a good idea to see if you can use the card
    through DOS before trying to use it through Linux.  If it works in DOS,
    chances are, it will work in Linux with the same settings.

2.  Make a backup of your linux directory.  This is very important in case you 
    need to totally remove the source of the patch from your kernel and go 
    back to your original code.

      cd /usr/src
      tar cvzhf linuxbak.tar.gz linux

3.  Uncompress the TokenRing patch.

       cd /usr/src/patches/token
       gzip -d TokenRing.patch-1.2.0.gz

5.  Modify your kernel with the TokenRing patch.

      cd /usr/src/linux
      patch -p1 < /usr/src/patches/token/TokenRing.patch-1.2.0
                    -or-
      patch -p1 < <directory-of-patchfile>/TokenRing.patch-1.2.0

6.  Search your kernel for any rejects from the patch and make changes as 
    necessary.

      find . -name \*.rej -print

7.  Search your kernel for the orig files and remove them.

      find . -name \*.orig -print | xargs rm

8.  Configure your kernel and remake.
        NOTE:  Make sure your swap space is active if you have one.
    cd /usr/src/linux
    make config
        (The patch should have added two lines to your config.in file for the 
         following options)

           Token Ring support (CONFIG_TR) [y]

              (and further down the list...)

           IBM Tropic chipset based adaptor support (CONFIG_IBMTR) [y]

    make dep
    make clean
    make zImage

9.  Setup LILO.
    First rename your /vmlinuz kernel to vmlinuz.old then copy the kernel to
    /vmlinuz
      On my system this would consist of copying
        /usr/src/linux/arch/i386/boot/zImage to /vmlinuz and editing
        /etc/lilo.conf to boot that kernel.
    Now from the prompt run 'lilo'.

10. If you have not already ran 'netconfig' on your system, do so now.  Setup
    your machine just as if it were on Ethernet.

11. Edit your /etc/rc.d/rc.inet1 scripts to point to the tr0 device rather 
    then the eth0 device.  

    You should have a line that looks like

      /sbin/ifconfig eth0 ${IPADDR} broadcast ${BROADCAST} netmask ${NETMASK}

    Change this line to read

      /sbin/ifconfig tr0 ${IPADDR} broadcast ${BROADCAST} netmask ${NETMASK}

12.  You should now be able to reboot your system and use the Token Ring
     card in your computer.

IV.  NETTOOLS INSTALLATION

      The NetTools package contains a lot of the basic utils that you
      will use to communicate with network devices.  This includes
      programs like arp, rarp, route, ifconfig and netstat.  
      Since these programs do not know about Token Ring by default, 
      you will need to add the NetTools patch so these utilities can 
      work more efficiently with the Token Ring driver.

	NOTICE:  The current version of NetTools is 1.2.0.  The patch for
	1.1.95 seems to work just fine with this version.

1.  Copy and Untar the NetTools source into your source directory.
    NOTE:  The copy of net-tools-1.2.0.tar.gz that I used did untar
     into the net directory under /usr/src/net directory.

      cp net-tools-1.2.0.tar.gz  /usr/src/net-tools-1.2.0.tar.gz
      tar -zxvof net-tools-1.2.0.tar.gz 

4.  Uncompress and install the patch file to net-tools.

      cd /usr/src/patches/nettools
      gzip -d Nettools-1.1.95-TR.diff.gz
      cd /usr/src/net
      patch -p1 < /usr/src/patches/nettools/Nettools-1.1.95-TR.diff

5.  Make the net-tools files.

      make install

V.  KNOWN PROBLEMS

	I personally have had very few problems with this driver.  It has
	been working perfectly for me for quite some time. 

	One of the main problems with this driver, according to Peter De
	Schrijver is Source Routing.

~From: Peter de Schrijver <Peter.DeSchrijver@linux.cc.kuleuven.ac.be>

Main source of problems is source routing. If you can't ping a node which is
on the other side of the bridge, you have a problem with source routing. 
Contact me if you encounter this and I will try to do what I can. I don't 
have access to a bridged ring myself however, so It might be difficult to 
solve the problem.

Peter. 

	Our network here at Wayne Community Schools is two token rings and
	one ethernet segment bridged with IBM 8229 bridges.  I have had
	no problems with source routing and this driver with these bridges.

	I have also tested this driver on a network made up of 7 rings bridged
	with a combination of IBM 8229 bridges and IBM PC Bridges with IBM's
	bridge software.  No problems there either.

VI.  Questions

	Here are some email messages that I have received about Token
	Ring and Linux.  In some of the messages, I have removed parts
	that were not important to save space.
----

~From: "Mr. Chuck Rickard" <chuck@gl.umbc.edu>
~Subject: Re: Token Ring Kernel patch

I d/l'd the patch, applied it, and re-compiled.  When booting it said,
"tr0: Can't assign device to adapter" and again for tr1.  Any ideas?

Thanks!

Chuck Rickard
(chuck@umbc8.umbc.edu)

~From: David Morris <dwm@shell.portal.com>

A:  When this is the only message issued, it means that the PIO request for
    adapter information (see segment = inb(PIOaddr) in ibmtr.c) was so out
    of range that there is no TR card at that IO address.

----

~From: Mike Glover <glover@credit.erin.utoronto.ca>
~ubject: Token ring problems.

Thanks for responding. I was starting to thing that I posted incorrectly, 
and I was about to post again. Anyway, the following  clip is part of my
/var/adm/messages file from when I boot up.

May  2 10:03:14 linux kernel: Detected scsi CD-ROM sr0 at scsi0, id 3, lun 0
May  2 10:03:14 linux kernel: scsi : detected 1 SCSI cdrom 1 SCSI disk total.
May  2 10:03:14 linux kernel: SCSI Hardware sector size is 512 bytes on device sda
May  2 10:03:14 linux kernel: Memory: 31204k/32768k available (732k kernel code, 384k reserved, 448k data)
May  2 10:03:14 linux kernel: This processor honours the WP bit even when in supervisor mode. Good.
May  2 10:03:14 linux kernel: Swansea University Computer Society NET3.019
May  2 10:03:14 linux kernel: Swansea University Computer Society TCP/IP for NET3.019
May  2 10:03:14 linux kernel: IP Protocols: ICMP, UDP, TCP
May  2 10:03:14 linux kernel: Swansea University Computer Society IPX 0.29 BETA for NET3.019
May  2 10:03:14 linux kernel: IPX Portions Copyright (c) 1995 Caldera, Inc.
May  2 10:03:14 linux kernel: tr0: Unable to assign adapter to device.
May  2 10:03:14 linux kernel: tr1: Unable to assign adapter to device.
May  2 10:03:14 linux kernel: PPP: version 0.2.7 (4 channels) NEW_TTY_DRIVERS OPTIMIZE_FLAGS
May  2 10:03:14 linux kernel: TCP compression code copyright 1989 Regents of the University of California
May  2 10:03:14 linux kernel: PPP line discipline registered.
May  2 10:03:14 linux kernel: Checking 386/387 coupling... Hmm, FDIV bug i586 system
May  2 10:03:14 linux kernel: Checking 'hlt' instruction... Ok.
May  2 10:03:14 linux kernel: Linux version 1.2.1 (root@linux) (gcc version 2.6.3) #4 Wed Apr 26 16:43:21 EDT 1995

The section, tr0: Unable to assign adapter device. is what kinda confuses 
me. The documentation is slim at best so I didn't know what to do with 
the message. I know I didn't assign any token ring information, and I 
didn't know where to do it.

The hardware:
	Its a PC clone (Dell OMNIPLEX 560 to be exact)
	The token ring card is a Olicom 16/4 Adapter.

I have DOS token ring drivers and it snaps into the network, so there is 
nothing wrong with the card. I think, I am just missing something really 
small in the config on the Linux side.

A:  The Olicom 16/4 Adapter must not use the Tropic Chipset.  Try using
	one of the cards that are listed at the top of the HOWTO.

-----

~From: Mike Glover <glover@credit.erin.utoronto.ca>
~Subject: Found an IBM card...

I found myself an IBM token ring card and I got a little further, but 
still not luck. (I did change /etc/rc.d/rc.inet1 ifconfig entry from eth0 
to tr0)

Anyway, here is part of the /var/adm/messages file:
May  2 16:23:07 linux kernel: IPX Portions Copyright (c) 1995 Caldera, Inc.
May  2 16:23:07 linux kernel: tr0: PIOaddr:  a20 seg/intr: b8 mmio base: 000dc000 intr: 0
May  2 16:23:07 linux kernel: tr0: Channel ID string not found for PIOaddr:  a20
May  2 16:23:07 linux kernel: tr0: Expected for ISA: 5049434f3631313039393020
May  2 16:23:07 linux kernel: tr0:            found: 000902003021111000182000
May  2 16:23:07 linux kernel: tr0: Expected for MCA: 4d4152533633583435313820
May  2 16:23:07 linux kernel: tr0: Unable to assign adapter to device.
May  2 16:23:07 linux kernel: tr1: Unable to assign adapter to device.
May  2 16:23:07 linux kernel: PPP: version 0.2.7 (4 channels) NEW_TTY_DRIVERS OPTIMIZE_FLAGS


Does this tell you anything. I tells me little.

~From: David Morris <dwm@shell.portal.com>

A:  This message means either a memory conflict with the MMIO area or a TR
    card which is not compatible with the driver (at least the signature
    isn't known).

-----

~From: Mike Glover <glover@credit.erin.utoronto.ca>
~Subject: Almost there...

The following sample is what I'm getting on my messages file:

May  3 14:50:24 linux kernel: IPX Portions Copyright (c) 1995 Caldera, Inc.
May  3 14:50:24 linux kernel: tr0: PIOaddr:  a20 seg/intr: b1 mmio base: 000d8000 intr: 1
May  3 14:50:24 linux kernel: tr0: ti->global_int_enable: 02F3
May  3 14:50:24 linux kernel: tr0: irq=3.
May  3 14:50:24 linux kernel: tr0: hw address: 10005A787197
May  3 14:50:24 linux kernel: tr0: atype=e, drate=d, trel=d, asram=63K, srp=e, dhb(4mb=d, 16mb=b)
May  3 14:50:24 linux kernel: tr0: shared ram page size: 32K
May  3 14:50:24 linux kernel: tr0: Using 32K shared RAM
May  3 14:50:24 linux kernel: tr0: ibmtr.c:v1.1.48 8/7/94 Peter De Schrijver and Mark Swanson
May  3 14:50:24 linux kernel:            modified 10/3/94 David W. Morris
May  3 14:50:24 linux kernel: tr0: resetting card
May  3 14:50:24 linux kernel: tr0: card reset
May  3 14:50:24 linux kernel: tr1: Unable to assign adapter to device.
May  3 14:50:24 linux kernel: PPP: version 0.2.7 (4 channels) NEW_TTY_DRIVERS OPTIMIZE_FLAGS
May  3 14:50:24 linux kernel: TCP compression code copyright 1989 Regents of the University of California
May  3 14:50:24 linux kernel: PPP line discipline registered.
May  3 14:50:24 linux kernel: Checking 386/387 coupling... Hmm, FDIV bug i586 system
May  3 14:50:24 linux kernel: Checking 'hlt' instruction... Ok.
May  3 14:50:24 linux kernel: Linux version 1.2.1 (root@linux) (gcc version 2.6.3) #4 Wed Apr 26 16:43:21 EDT 1995
May  3 14:50:24 linux kernel: Partition check:
May  3 14:50:24 linux kernel:   sda: sda1
May  3 14:50:24 linux kernel:   hda: hda1 hda2 < > hda3 hda4
May  3 14:50:24 linux kernel: VFS: Mounted root (ext2 filesystem) readonly.
May  3 14:50:24 linux kernel: tr0: Initial tok int received
May  3 14:50:24 linux kernel: tr0: init_srb(000d7fc4):80 03 00 00 00 0<6>
May  3 14:50:24 linux kernel: tr0: srb_init_response->encoded_address: CC02
May  3 14:50:24 linux kernel: tr0: ntohs(srb_init_response->encoded_address): 02CC
May  3 14:50:24 linux kernel: tr0: encoded addr (CC02,02CC,000d02cc): 10:00:5A:78:71:97
May  3 14:50:24 linux kernel: tr0: now opening the board...
May  3 14:50:24 linux kernel: tr0: board opened...
May  3 14:51:41 linux sendmail[51]: starting daemon (8.6.11): SMTP+queueing@00:15:00
May  3 14:52:09 linux login: ROOT LOGIN ON tty6
May  3 15:11:47 linux kernel: tr0: Arrg. Transmitter busy for more than 50 msec. Donald resets adapter, but resetting
May  3 15:11:47 linux kernel:  the IBM tokenring adapter takes a long time. It might not even help when the
May  3 15:11:47 linux kernel:  ring is very busy, so we just wait a little longer and hope for the best.
May  3 15:11:47 linux kernel: tr0: Arrg. Transmitter busy for more than 50 msec. Donald resets adapter, but resetting
May  3 15:11:47 linux kernel:  the IBM tokenring adapter takes a long time. It might not even help when the
May  3 15:11:47 linux kernel:  ring is very busy, so we just wait a little longer and hope for the best.
May  3 15:11:47 linux kernel: tr0: Arrg. Transmitter busy for more than 50 msec. Donald resets adapter, but resetting

The Arrg entry only comes when I telnet, rlogin or ftp to a remote 
machine. Once that happens, the connection hangs big time. I took out all 
the other hardware (which was 1 SCSI card) and tried running the card all 
by itself. Same thing, so it eliminates hardware IRQ's from getting into 
a yelling match. The following are the DIP switches on the card:

	1	Up	|
	2	Down	|
	3	Down	|	According to the manual this sets the 
	4	Up	|	base address to CC000 Which is fine for
	5	Up	|	my machine.
	6	Down	|
	7	Down	+	This sets the IRQ to 2. Which is also fine	
	8	Down	+
	9	Up	X	Primary Lan adapter. Which it is.
	10	Up	=	16 KB shared RAM size. This OK?	
	11	Down	=
	12	Up	#	16 Mbps Data rate.

I was wondering if it is in fact the dip switches, or the way I have 
configured my route table and other network info.

ttfn,
	Mike

A:  The solution to this problem is currently being worked on by other folks.
	I will update this answer when a solution is found.