
----------------------------------------------------------------------------
NOTE:  See also README.arcnet-hardware in this directory for jumper-setting
and cabling information if you're like many of us and didn't happen to get a
manual with your ARCnet card.
----------------------------------------------------------------------------

Since no one seems to listen to me otherwise, perhaps a poem will get your
attention:
			This is scary software
			If it works I DO CARE.

Hmm, I think I'm allowed to call that a poem, even though it's only two
lines.  Hey, I'm in Computer Science, not English.  Give me a break.

The point is:  I REALLY REALLY REALLY REALLY REALLY want to hear from you if
you test this and get it working.  Or if you don't.  Or anything.

ARCnet 0.32 ALPHA first made it into the Linux kernel 1.1.80 - this was
nice, but after that even FEWER people started writing to me because they
didn't even have to install the patch.  <sigh>

Come on, be a sport!  Send me a success report!

(hey, that was even better than my original poem... this is getting bad!)


--------
WARNING:
--------

If you don't e-mail me about your success/failure soon, I may be forced to
start SINGING.  And we don't want that, do we?

(You know, it might be argued that I'm pushing this point a little too much. 
If you think so, why not flame me in a quick little e-mail?  Please also
include the type of card(s) you're using, software, size of network, and
whether it's working or not.)

My e-mail address is: apenwarr@foxnet.net


---------------------------------------------------------------------------

			
These are the ARCnet drivers for Linux.

This new "stable" release has come from many months of on-and-off effort
from me (Avery Pennarun), many bug reports from users, and in particular a
lot of input and coding from Tomasz Motylewski.  (I've held off on Tomasz'
latest patches - but his all-new RFC1051 support is here and waiting for the
next ALPHA release!)


Where do I discuss these drivers?
---------------------------------

There is a mailing list specifically for discussion of the ARCnet drivers
for Linux, and anything you might want to interface them with (ie. DOS). 
I'll also post new versions of the Linux-ARCnet distribution to the list in
tar-gzip-uuencode format.

To subscribe to the list, send a message to listserv@807-city.on.ca
with the following line in the BODY (not the SUBJECT) of your message:
	subscribe linux-arcnet YOUR REAL NAME
Remember to remove your signature, or you'll get an error back.

Send all bug (or success) reports to me or to the list.

The people on linux-net@vger.rutgers.edu have also been known to be very
helpful, especially when we're talking about ALPHA Linux kernels that may or
may not work right in the first place.


Other Drivers and Info
----------------------

You can try my ARCNET page on the World Wide Web at:
	http://www.foxnet.net/~apenwarr/arcnet/

Also, SMC (one of the companies that makes ARCnet cards) has a WWW site you
might be interested in, which includes several drivers for various cards
including ARCnet.  Try:
	http://www.smc.com/
	
Performance Technologies makes various network software that supports
ARCnet:
	http://www.perftech.com/ or ftp to ftp.perftech.com.
	
Novell makes a networking stack for DOS which includes ARCnet drivers.  Try
ftp'ing to ftp.novell.com.

You can get the Crynwr packet driver collection (including arcether.com, the
one you'll want to use with arcnet cards) from
oak.oakland.edu:/simtel/msdos/pktdrvr. It won't work perfectly on a 386+
without patches, though, and also doesn't like several cards.  Mail me if
you want a fixed version.  (Ahem: I may or may not have a 100% fixed version
by the time I get your mail!)


Loadable Module Support
-----------------------

Configure and rebuild Linux.  When asked, answer 'n' to "arcnet support" if
you want to use the loadable module.

Actually, with Linux 1.3.24 and higher, you should answer 'm' to build the
module.

	make config
	make dep
	make clean	
	make zImage
	make modules
	
If you're using a loadable module, you need to use insmod to load the
module, and you need to specify various characteristics of your card on the
command line.  For example:
	cd /usr/src/linux/modules
	insmod arcnet.o io=0x300 irqnum=2 shmem=0xd0000
You can also add a num=1, num=2 etc for additional arcnet cards that will
use arc1, arc2 etc for their device names (instead of the default, arc0).
	

Using the Driver
----------------

If you build your kernel with ARCnet support included, it should probe for
your card automatically when you boot.

Go read the NET-2-HOWTO and ETHERNET-HOWTO for Linux; they should be
available where you picked up this driver.  Think of your ARCnet as a
souped-up (or down, as the case may be) ethernet card.

By the way, be sure to change all references from "eth0" to "arc0" in the
HOWTOs.  Remember that ARCnet isn't a "true" ethernet, and the device name
is DIFFERENT.


How do I get it to work with...?
--------------------------------

NFS: Should be fine linux->linux, just pretend you're using ethernet cards. 
        oak.oakland.edu:/simtel/msdos/nfs has some nice DOS clients.  There
        is also a DOS-based NFS server called SOSS.  It doesn't multitask
        quite the way Linux does (actually, it doesn't multitask AT ALL) but
        you never know what you might need.

DOS: If you're using the freeware arcether.com, you might want to install
        the source code patch.  It helps with PC/TCP, and also can get
        arcether to load if it timed out too quickly during initialization. 
        Mail me if you need a precompiled version of arcether.com. (ie. you
        if don't have a DOS assembler)
	
Windows:  See DOS :)  Trumpet Winsock works fine with either the Novell or
	Arcether client, assuming you remember to load winpkt of course.

LAN Manager and Windows for Workgroups: These programs use protocols that
        are incompatible with the internet standard.  They try to pretend
        the cards are ethernet, and confuse everyone else on the network. 
        
        However, v2.00 of the Linux ARCnet driver supports this protocol via
        the 'arc0e' device.  See the section on "Multiprotocol Support" for
	more information.
        
	Using the freeware Samba server and clients for Linux, you can now
	interface quite nicely with TCP/IP-based WfWg or Lan Manager
	networks.
	
Windows 95: Tools are included with Win95 that let you use either the LANMAN
	style network drivers (NDIS) or Novell drivers (ODI) to handle your
	ARCnet packets.  If you use ODI, you'll need to use the 'arc0'
	device with Linux.  If you use NDIS, then try the 'arc0e' device. 
	See the "Multiprotocol Support" section below if you need arc0e,
	you're completely insane, and/or you need to build some kind of
	hybrid network that uses both encapsulation types.

OS2: Has not been tested.  The "correct" solution would be to buy either of
	IBM's "TCP/IP for OS/2" or "Warp Connect" packages.  However,
	ftp.microsoft.com also has a freeware Lan Manager for OS/2 client
	which should use the same protocol as WfWg does.  I had no luck
	installing it under Warp, however.  Please mail me with any results.

NetBSD/AmiTCP: These use an old version of the Internet standard ARCnet
	protocol (RFC1051) which is incompatible with the Linux driver at
	present.  Work to support these is underway and should be available
	in an ALPHA release very soon.
	

Using Multiprotocol ARCnet
--------------------------

The ARCnet driver v2.00 supports two protocols, each on its own "virtual
network device":
	arc0  - RFC1201 protocol, the official internet standard which just
		happens to be 100% compatible with Novell's TRXNET driver. 
		Version 1.00 of the ARCnet driver _only_ supported this
		protocol.  arc0 is the faster of the two protocols, and
		allows larger packets to be used because it supports RFC1201
		"packet splitting" operations.  Unless you have a specific
		need to use a different protocol, I highly suggest that you
		stick with this one.
		
	arc0e - "Ethernet-Encapsulation" which sends packets over ARCnet
		that are actually a lot like Ethernet packets, including the
		6-byte hardware addresses.  This protocol is compatible with
		Microsoft's NDIS ARCnet driver, like the one in WfWg and
		LANMAN.  Because the MTU of 493 is actually smaller than the
		one "required" by TCP/IP (576), there is a chance that some
		network operations will not work properly.  The Linux TCP/IP
		layer can compensate in most cases, however, by
		automatically fragmenting the TCP/IP packets to make them
		fit.  arc0e also works slightly more slowly than arc0, for
		reasons yet to be determined.  (Probably it's the smaller
		MTU that does it)

The arc0e device is created automatically when you first 'ifconfig' the arc0
device.  To actually use arc0e, though, you need to 'ifconfig' it as well. 
There are a number of ways you can set up your network then:


1. Single Protocol.

   This is the simplest way to configure your network: use just one of the
   two available protocols.  As mentioned above, it's a good idea to use
   only arc0 unless you have a good reason (like some other software, ie.
   WfWg, that only works with arc0e).
   
   If you need only arc0, then the following commands should get you going:
   	ifconfig arc0 MY.IP.ADD.RESS
   	route add MY.IP.ADD.RESS arc0
   	route add SUB.NET.ADD.RESS arc0
   	[etc]
   	
   If you need arc0e (and only arc0e), it's a little different:
   	ifconfig arc0 up     /* the IP address doesn't matter on arc0 */
   	ifconfig arc0e MY.IP.ADD.RESS
   	route add MY.IP.ADD.RESS arc0e
   	route add SUB.NET.ADD.RESS arc0e


2. More than one protocol on the same wire.

   Now things start getting confusing.  To even try it, you may need to be
   partly crazy.  Here's what *I* did.  :)

   I have three computers on my home network; two Linux boxes (which prefer
   RFC1201 protocol), and one XT that can't run Linux but runs the free
   Microsoft LANMAN Client instead.
   
   Worse, one of the Linux computers (freedom) also has a modem and acts as
   a router to my information provider.  The other Linux box (insight) also
   has its own IP address and needs to use freedom as its default gateway. 
   The XT (patience), however, does not have its own internet IP address and
   so I assigned it one on a "private subnet" (as defined by RFC1597).
   
   To start with, take a simple network with just insight and freedom. 
   Insight needs to:
   	- talk to freedom via RFC1201 (arc0) protocol, because I like it
	  more and it's faster.
	- use freedom as its internet gateway.
	
   That's pretty easy to do.  Set up insight like this:
   	ifconfig arc0 insight
   	route add insight arc0
   	route add freedom arc0	/* I would use the subnet here (like I said
					to to in "single protocol" above),
   					but the rest of the subnet
   					unfortunately lies across the PPP
   					link on freedom, which confuses
   					things. */
   	route add default gw freedom
   	
   And freedom gets configured like so:
   	ifconfig arc0 freedom
   	route add freedom arc0
   	route add insight arc0
   	/* and default gateway is configured by PPP */
   	
   Great, now insight talks to freedom directly on arc0, and sends packets
   to the internet through freedom.  If you didn't know how to do the above,
   you should probably stop reading this section now because it only gets
   worse.

   Now, how do I add patience into the network?  It will be using LANMAN
   Client, which means I need the arc0e device.  It needs to be able to talk
   to both insight and freedom, and also use freedom as a gateway to the
   internet.  (Recall that patience has a "private IP address" which won't
   work on the internet; that's okay, I configured Linux IP masquerading on
   freedom for this subnet).
   
   So patience (necessarily; I don't have another IP number from my
   provider) has an IP address on a different subnet than freedom and
   insight, but needs to use freedom as an internet gateway.  Worse, most
   DOS networking programs, including LANMAN, have braindead networking
   schemes that rely completely on the netmask and a 'default gateway' to
   determine how to route packets.  This means that to get to freedom or
   insight, patience WILL send through its default gateway, regardless of
   the fact that both freedom and insight (courtesy of the arc0e device)
   could understand a direct transmission.
   
   I compensate by giving freedom an extra IP address - aliased 'gatekeeper'
   - that is on my private subnet, the same subnet that patience is on.  I
   then define gatekeeper to be the default gateway for patience.
   
   To configure freedom (in addition to the commands above):
   	ifconfig arc0e gatekeeper
   	route add gatekeeper arc0e
   	route add patience arc0e
   
   This way, freedom will send all packets for patience through arc0e,
   giving its IP address as gatekeeper (on the private subnet).  When it
   talks to insight or the internet, it will use its "freedom" internet IP
   address.
   
   You will notice that we haven't configured the arc0e device on insight. 
   This would work, but is not really necessary, and would require me to
   assign insight another special IP number from my private subnet.  Since
   both insight and patience are using freedom as their default gateway, the
   two can already talk to each other.
   
   It's quite fortunate that I set things up like this the first time
   through (cough cough) because it's really handy when I boot insight into
   DOS.  There, it runs the Novell ODI protocol stack, which only works with
   RFC1201 ARCnet.  In this mode it would be impossible for insight to
   communicate directly with patience, since the Novell stack is
   incompatible with Microsoft's Ethernet-Encap.  Without changing any
   settings on freedom or patience, I simply set freedom as the default
   gateway for insight (now in DOS, remember) and all the forwarding happens
   "automagically" between the two hosts that would normally not be able to
   communicate at all.
   
   For those who like diagrams, I have created two "virtual subnets" on the
   same physical ARCnet wire.  You can picture it like this:
   
                                                    
          [RFC1201 NETWORK]                   [ETHER-ENCAP NETWORK]
      (registered internet subnet)           (RFC1597 private subnet)
  
                             (IP Masquerade)
          /---------------\         *            /---------------\
          |               |         *            |               |
          |               +-Freedom-*-Gatekeeper-+               |
          |               |    |    *            |               |
          \-------+-------/    |                 \-------+-------/
                  |            |                         |
               Insight         |                      Patience
                           (Internet)
                        



                                                    
It works: what now?
-------------------

Send mail describing your setup, preferably including driver version, kernel
version, ARCnet card model, CPU type, number of systems on your network, and
list of software in use to me at the following address:
	apenwarr@foxnet.net

I do send (sometimes automated) replies to all messages I receive.  My email
can be weird (and also usually gets forwarded all over the place along the
way to me), so if you don't get a reply within a reasonable time, please
resend.


It doesn't work: what now?
--------------------------

Do the same as above, but also include the output of the ifconfig and route
commands, as well as any pertinent log entries (ie: anything that starts
with "arcnet:" and has shown up since the last reboot) in your mail.

If you want to try fixing it yourself (I highly recommend that you mail me
about the problem first, since it might already have been solved) you may
want to try some of the debug levels available.  For heavy testing on
D_DURING or more, it would be a REALLY good idea to kill your klogd
daemon first!  D_DURING displays 4-5 lines for each packet sent or
received.  D_TX and RX actually DISPLAY each packet as it is sent or
received, which is obviously quite big.

You can run the arcdump shell script (available from me or in the full
ARCnet package if you got it) as root to list the contents of the arcnet
buffers at any time.  To make any sense at all out of this, you should grab
the pertinent RFC's. (some are listed near the top of arcnet.c).  arcdump
assumes your card is at 0xD0000.  If it isn't, edit the script.

Buffers #0 and 1 are used for receiving, and Buffers #2 and 3 are for
sending.  Ping-pong buffers are implemented both ways.

If your debug level includes D_DURING, the buffers are cleared to a constant
value of 0x42 every time the card is reset (which should only happen when
you do an ifconfig up, or when Linux decides that the driver is broken). 
This is to make it easier to figure out which bytes are being used by a
packet.

You can change the debug level without recompiling the kernel by typing:
	ifconfig arc0 down metric 1xxx
	/etc/rc.d/rc.inet1
where "xxx" is the debug level you want.  For example, "metric 1015" would put
you at debug level 15.  Debug level 3 is currently the default.

Note that the debug level is (as of v1.90 ALPHA) a binary combination of
different debug flags; so debug level 7 is really 1+2+4 or
D_NORMAL+D_INIT+D_EXTRA.  To reach D_DURING, you would add 8 to this,
resulting in debug level 15.

If you don't understand that, you probably don't want to know anyway. 
E-mail me about your problem.


I want to send money: what now?
-------------------------------

Go take a nap or something.  You'll feel better in the morning.
