* add p cc
[mascara-docs.git] / i386 / linux / linux-2.3.21 / Documentation / networking / arcnet.txt
blob2cdb6db629145c966a13a410c6acd04266579e05
1 ----------------------------------------------------------------------------
2 NOTE:  See also arcnet-hardware.txt in this directory for jumper-setting
3 and cabling information if you're like many of us and didn't happen to get a
4 manual with your ARCnet card.
5 ----------------------------------------------------------------------------
7 Since no one seems to listen to me otherwise, perhaps a poem will get your
8 attention:
9                 This driver's getting fat and beefy,
10                 But my cat is still named Fifi.
12 Hmm, I think I'm allowed to call that a poem, even though it's only two
13 lines.  Hey, I'm in Computer Science, not English.  Give me a break.
15 The point is:  I REALLY REALLY REALLY REALLY REALLY want to hear from you if
16 you test this and get it working.  Or if you don't.  Or anything.
18 ARCnet 0.32 ALPHA first made it into the Linux kernel 1.1.80 - this was
19 nice, but after that even FEWER people started writing to me because they
20 didn't even have to install the patch.  <sigh>
22 Come on, be a sport!  Send me a success report!
24 (hey, that was even better than my original poem... this is getting bad!)
27 --------
28 WARNING:
29 --------
31 If you don't e-mail me about your success/failure soon, I may be forced to
32 start SINGING.  And we don't want that, do we?
34 (You know, it might be argued that I'm pushing this point a little too much. 
35 If you think so, why not flame me in a quick little e-mail?  Please also
36 include the type of card(s) you're using, software, size of network, and
37 whether it's working or not.)
39 My e-mail address is: apenwarr@worldvisions.ca
42 ---------------------------------------------------------------------------
44                         
45 These are the ARCnet drivers for Linux.
48 This new release (2.91) has been put together by David Woodhouse 
49 <dwmw2@cam.ac.uk>, in an attempt to tidy up the driver after adding support 
50 for yet another chipset. Now the generic support has been separated from the
51 individual chipset drivers, and the source files aren't quite so packed with
52 #ifdefs! I've changed this file a bit, but kept it in the first person from
53 Avery, because I didn't want to completely rewrite it.
55 The previous release resulted from many months of on-and-off effort from me
56 (Avery Pennarun), many bug reports/fixes and suggestions from others, and in
57 particular a lot of input and coding from Tomasz Motylewski.  Starting with
58 ARCnet 2.10 ALPHA, Tomasz's all-new-and-improved RFC1051 support has been
59 included and seems to be working fine!
62 Where do I discuss these drivers?
63 ---------------------------------
65 Tomasz has been so kind as to set up a new and improved mailing list. 
66 Subscribe by sending a message with the BODY "subscribe linux-arcnet YOUR
67 REAL NAME" to listserv@tichy.ch.uj.edu.pl.  Then, to submit messages to the
68 list, mail to linux-arcnet@tichy.ch.uj.edu.pl.
70 There are archives of the mailing list at:
71         http://tichy.ch.uj.edu.pl/lists/linux-arcnet
73 The people on linux-net@vger.rutgers.edu have also been known to be very
74 helpful, especially when we're talking about ALPHA Linux kernels that may or
75 may not work right in the first place.
78 Other Drivers and Info
79 ----------------------
81 You can try my ARCNET page on the World Wide Web at:
82         http://www.worldvisions.ca/~apenwarr/arcnet/
84 Also, SMC (one of the companies that makes ARCnet cards) has a WWW site you
85 might be interested in, which includes several drivers for various cards
86 including ARCnet.  Try:
87         http://www.smc.com/
88         
89 Performance Technologies makes various network software that supports
90 ARCnet:
91         http://www.perftech.com/ or ftp to ftp.perftech.com.
92         
93 Novell makes a networking stack for DOS which includes ARCnet drivers.  Try
94 FTPing to ftp.novell.com.
96 You can get the Crynwr packet driver collection (including arcether.com, the
97 one you'll want to use with ARCnet cards) from
98 oak.oakland.edu:/simtel/msdos/pktdrvr. It won't work perfectly on a 386+
99 without patches, though, and also doesn't like several cards.  Fixed
100 versions are available on my WWW page, or via e-mail if you don't have WWW
101 access. 
104 Installing the Driver
105 ---------------------
107 All you will need to do in order to install the driver is:
108         make config
109                 (be sure to choose ARCnet in the network devices 
110                 and at least one chipset driver.)
111         make dep
112         make clean
113         make zImage
114         
115 If you obtained this ARCnet package as an upgrade to the ARCnet driver in
116 your current kernel, you will need to first copy arcnet.c over the one in
117 the linux/drivers/net directory.
119 You will know the driver is installed properly if you get some ARCnet
120 messages when you reboot into the new Linux kernel.
122 There are four chipset options:
124  1. Standard ARCnet COM90xx chipset.
126 This is the normal ARCnet card, which you've probably got. This is the only
127 chipset driver which will autoprobe if not told where the card is.
128 It following options on the command line:
129  com90xx=[<io>[,<irq>[,<shmem>]]][,<name>] | <name>
131 If you load the chipset support as a module, the options are:
132  io=<io> irq=<irq> shmem=<shmem> device=<name>
134 To disable the autoprobe, just specify "com90xx=" on the kernel command line.
135 To specify the name alone, but allow autoprobe, just put "com90xx=<name>"
137  2. ARCnet COM20020 chipset.
139 This is the new chipset from SMC with support for promiscuous mode (packet 
140 sniffing), extra diagnostic information, etc. Unfortunately, there is no
141 sensible method of autoprobing for these cards. You must specify the I/O
142 address on the kernel command line.
143 The command line options are:
144  com20020=<io>[,<irq>[,<node_ID>[,backplane[,CKP[,timeout]]]]][,name]
146 If you load the chipset support as a module, the options are:
147  io=<io> irq=<irq> node=<node_ID> backplane=<backplane> clock=<CKP>
148  timeout=<timeout> device=<name>
150 The COM20020 chipset allows you to set the node ID in software, overriding the
151 default which is still set in DIP switches on the card. If you don't have the
152 COM20020 data sheets, and you don't know what the other three options refer
153 to, then they won't interest you - forget them.
155  3. ARCnet COM90xx chipset in IO-mapped mode.
157 This will also work with the normal ARCnet cards, but doesn't use the shared
158 memory. It performs less well than the above driver, but is provided in case
159 you have a card which doesn't support shared memory, or (strangely) in case
160 you have so many ARCnet cards in your machine that you run out of shmem slots.
161 If you don't give the IO address on the kernel command line, then the driver
162 will not find the card.
163 The command line options are:
164  com90io=<io>[,<irq>][,<name>] 
166 If you load the chipset support as a module, the options are:
167  io=<io> irq=<irq> device=<name>
169  4. ARCnet RIM I cards.
171 These are COM90xx chips which are _completely_ memory mapped. The support for
172 these is not tested. If you have one, please mail the author with a success 
173 report. All options must be specified, except the device name.
174 Command line options:
175  arcrimi=<shmem>,<irq>,<node_ID>[,<name>]
177 If you load the chipset support as a module, the options are:
178  shmem=<shmem> irq=<irq> node=<node_ID> device=<name>
181 Loadable Module Support
182 -----------------------
184 Configure and rebuild Linux.  When asked, answer 'm' to "Generic ARCnet 
185 support" and to support for your ARCnet chipset if you want to use the
186 loadable module. You can also say 'y' to "Generic ARCnet support" and 'm' 
187 to the chipset support if you wish.
189         make config
190         make dep
191         make clean      
192         make zImage
193         make modules
194         
195 If you're using a loadable module, you need to use insmod to load it, and
196 you can specify various characteristics of your card on the command
197 line.  (In recent versions of the driver, autoprobing is much more reliable
198 and works as a module, so most of this is now unnecessary.)
200 For example:
201         cd /usr/src/linux/modules
202         insmod arcnet.o
203         insmod com90xx.o
204         insmod com20020.o io=0x2e0 device=eth1
205         
207 Using the Driver
208 ----------------
210 If you build your kernel with ARCnet COM90xx support included, it should 
211 probe for your card automatically when you boot. If you use a different
212 chipset driver complied into the kernel, you must give the necessary options
213 on the kernel command line, as detailed above.
215 Go read the NET-2-HOWTO and ETHERNET-HOWTO for Linux; they should be
216 available where you picked up this driver.  Think of your ARCnet as a
217 souped-up (or down, as the case may be) Ethernet card.
219 By the way, be sure to change all references from "eth0" to "arc0" in the
220 HOWTOs.  Remember that ARCnet isn't a "true" Ethernet, and the device name
221 is DIFFERENT.
224 Multiple Cards in One Computer
225 ------------------------------
227 Linux has pretty good support for this now, but since I've been busy, the
228 ARCnet driver has somewhat suffered in this respect. COM90xx support, if 
229 compiled into the kernel, will (try to) autodetect all the installed cards. 
231 If you have other cards, with support compiled into the kernel, then you can 
232 just repeat the options on the kernel command line, e.g.:
233 LILO: linux com20020=0x2e0 com20020=0x380 com90io=0x260
235 If you have the chipset support built as a loadable module, then you need to 
236 do something like this:
237         insmod -o arc0 com90xx
238         insmod -o arc1 com20020 io=0x2e0
239         insmod -o arc2 com90xx
240 The ARCnet drivers will now sort out their names automatically.
243 How do I get it to work with...?
244 --------------------------------
246 NFS: Should be fine linux->linux, just pretend you're using Ethernet cards. 
247         oak.oakland.edu:/simtel/msdos/nfs has some nice DOS clients.  There
248         is also a DOS-based NFS server called SOSS.  It doesn't multitask
249         quite the way Linux does (actually, it doesn't multitask AT ALL) but
250         you never know what you might need.
251         
252         With AmiTCP (and possibly others), you may need to set the following
253         options in your Amiga nfstab:  MD 1024 MR 1024 MW 1024
254         (Thanks to Christian Gottschling <ferksy@indigo.tng.oche.de>
255         for this.)
256         
257         Probably these refer to maximum NFS data/read/write block sizes.  I
258         don't know why the defaults on the Amiga didn't work; write to me if
259         you know more.
261 DOS: If you're using the freeware arcether.com, you might want to install
262         the driver patch from my web page.  It helps with PC/TCP, and also
263         can get arcether to load if it timed out too quickly during
264         initialization.  In fact, if you use it on a 386+ you REALLY need
265         the patch, really.
266         
267 Windows:  See DOS :)  Trumpet Winsock works fine with either the Novell or
268         Arcether client, assuming you remember to load winpkt of course.
270 LAN Manager and Windows for Workgroups: These programs use protocols that
271         are incompatible with the Internet standard.  They try to pretend
272         the cards are Ethernet, and confuse everyone else on the network. 
273         
274         However, v2.00 and higher of the Linux ARCnet driver supports this
275         protocol via the 'arc0e' device.  See the section on "Multiprotocol
276         Support" for more information.
278         Using the freeware Samba server and clients for Linux, you can now
279         interface quite nicely with TCP/IP-based WfWg or Lan Manager
280         networks.
281         
282 Windows 95: Tools are included with Win95 that let you use either the LANMAN
283         style network drivers (NDIS) or Novell drivers (ODI) to handle your
284         ARCnet packets.  If you use ODI, you'll need to use the 'arc0'
285         device with Linux.  If you use NDIS, then try the 'arc0e' device. 
286         See the "Multiprotocol Support" section below if you need arc0e,
287         you're completely insane, and/or you need to build some kind of
288         hybrid network that uses both encapsulation types.
290 OS/2: I've been told it works under Warp Connect with an ARCnet driver from
291         SMC.  You need to use the 'arc0e' interface for this.  If you get
292         the SMC driver to work with the TCP/IP stuff included in the
293         "normal" Warp Bonus Pack, let me know.
295         ftp.microsoft.com also has a freeware "Lan Manager for OS/2" client
296         which should use the same protocol as WfWg does.  I had no luck
297         installing it under Warp, however.  Please mail me with any results.
299 NetBSD/AmiTCP: These use an old version of the Internet standard ARCnet
300         protocol (RFC1051) which is compatible with the Linux driver v2.10
301         ALPHA and above using the arc0s device. (See "Multiprotocol ARCnet"
302         below.)  ** Newer versions of NetBSD apparently support RFC1201.
305 Using Multiprotocol ARCnet
306 --------------------------
308 The ARCnet driver v2.10 ALPHA supports three protocols, each on its own
309 "virtual network device":
311         arc0  - RFC1201 protocol, the official Internet standard which just
312                 happens to be 100% compatible with Novell's TRXNET driver. 
313                 Version 1.00 of the ARCnet driver supported _only_ this
314                 protocol.  arc0 is the fastest of the three protocols (for
315                 whatever reason), and allows larger packets to be used
316                 because it supports RFC1201 "packet splitting" operations. 
317                 Unless you have a specific need to use a different protocol,
318                 I strongly suggest that you stick with this one.
319                 
320         arc0e - "Ethernet-Encapsulation" which sends packets over ARCnet
321                 that are actually a lot like Ethernet packets, including the
322                 6-byte hardware addresses.  This protocol is compatible with
323                 Microsoft's NDIS ARCnet driver, like the one in WfWg and
324                 LANMAN.  Because the MTU of 493 is actually smaller than the
325                 one "required" by TCP/IP (576), there is a chance that some
326                 network operations will not function properly.  The Linux
327                 TCP/IP layer can compensate in most cases, however, by
328                 automatically fragmenting the TCP/IP packets to make them
329                 fit.  arc0e also works slightly more slowly than arc0, for
330                 reasons yet to be determined.  (Probably it's the smaller
331                 MTU that does it.)
332                 
333         arc0s - The "[s]imple" RFC1051 protocol is the "previous" Internet
334                 standard that is completely incompatible with the new
335                 standard.  Some software today, however, continues to
336                 support the old standard (and only the old standard)
337                 including NetBSD and AmiTCP.  RFC1051 also does not support
338                 RFC1201's packet splitting, and the MTU of 507 is still
339                 smaller than the Internet "requirement," so it's quite
340                 possible that you may run into problems.  It's also slower
341                 than RFC1201 by about 25%, for the same reason as arc0e.
342                 
343                 The arc0s support was contributed by Tomasz Motylewski
344                 and modified somewhat by me.  Bugs are probably my fault.
346 You can choose not to compile arc0e and arc0s into the driver if you want -
347 this will save you a bit of memory and avoid confusion when eg. trying to
348 use the "NFS-root" stuff in recent Linux kernels.
350 The arc0e and arc0s devices are created automatically when you first
351 ifconfig the arc0 device.  To actually use them, though, you need to also
352 ifconfig the other virtual devices you need.  There are a number of ways you
353 can set up your network then:
356 1. Single Protocol.
358    This is the simplest way to configure your network: use just one of the
359    two available protocols.  As mentioned above, it's a good idea to use
360    only arc0 unless you have a good reason (like some other software, ie.
361    WfWg, that only works with arc0e).
362    
363    If you need only arc0, then the following commands should get you going:
364         ifconfig arc0 MY.IP.ADD.RESS
365         route add MY.IP.ADD.RESS arc0
366         route add -net SUB.NET.ADD.RESS arc0
367         [add other local routes here]
368         
369    If you need arc0e (and only arc0e), it's a little different:
370         ifconfig arc0 MY.IP.ADD.RESS
371         ifconfig arc0e MY.IP.ADD.RESS
372         route add MY.IP.ADD.RESS arc0e
373         route add -net SUB.NET.ADD.RESS arc0e
374    
375    arc0s works much the same way as arc0e.
378 2. More than one protocol on the same wire.
380    Now things start getting confusing.  To even try it, you may need to be
381    partly crazy.  Here's what *I* did. :) Note that I don't include arc0s in
382    my home network; I don't have any NetBSD or AmiTCP computers, so I only
383    use arc0s during limited testing.
385    I have three computers on my home network; two Linux boxes (which prefer
386    RFC1201 protocol, for reasons listed above), and one XT that can't run
387    Linux but runs the free Microsoft LANMAN Client instead.
389    Worse, one of the Linux computers (freedom) also has a modem and acts as
390    a router to my Internet provider.  The other Linux box (insight) also has
391    its own IP address and needs to use freedom as its default gateway.  The
392    XT (patience), however, does not have its own Internet IP address and so
393    I assigned it one on a "private subnet" (as defined by RFC1597).
395    To start with, take a simple network with just insight and freedom. 
396    Insight needs to:
397         - talk to freedom via RFC1201 (arc0) protocol, because I like it
398           more and it's faster.
399         - use freedom as its Internet gateway.
400         
401    That's pretty easy to do.  Set up insight like this:
402         ifconfig arc0 insight
403         route add insight arc0
404         route add freedom arc0  /* I would use the subnet here (like I said
405                                         to to in "single protocol" above),
406                                         but the rest of the subnet
407                                         unfortunately lies across the PPP
408                                         link on freedom, which confuses
409                                         things. */
410         route add default gw freedom
411         
412    And freedom gets configured like so:
413         ifconfig arc0 freedom
414         route add freedom arc0
415         route add insight arc0
416         /* and default gateway is configured by pppd */
417         
418    Great, now insight talks to freedom directly on arc0, and sends packets
419    to the Internet through freedom.  If you didn't know how to do the above,
420    you should probably stop reading this section now because it only gets
421    worse.
423    Now, how do I add patience into the network?  It will be using LANMAN
424    Client, which means I need the arc0e device.  It needs to be able to talk
425    to both insight and freedom, and also use freedom as a gateway to the
426    Internet.  (Recall that patience has a "private IP address" which won't
427    work on the Internet; that's okay, I configured Linux IP masquerading on
428    freedom for this subnet).
429    
430    So patience (necessarily; I don't have another IP number from my
431    provider) has an IP address on a different subnet than freedom and
432    insight, but needs to use freedom as an Internet gateway.  Worse, most
433    DOS networking programs, including LANMAN, have braindead networking
434    schemes that rely completely on the netmask and a 'default gateway' to
435    determine how to route packets.  This means that to get to freedom or
436    insight, patience WILL send through its default gateway, regardless of
437    the fact that both freedom and insight (courtesy of the arc0e device)
438    could understand a direct transmission.
439    
440    I compensate by giving freedom an extra IP address - aliased 'gatekeeper'
441    - that is on my private subnet, the same subnet that patience is on.  I
442    then define gatekeeper to be the default gateway for patience.
443    
444    To configure freedom (in addition to the commands above):
445         ifconfig arc0e gatekeeper
446         route add gatekeeper arc0e
447         route add patience arc0e
448    
449    This way, freedom will send all packets for patience through arc0e,
450    giving its IP address as gatekeeper (on the private subnet).  When it
451    talks to insight or the Internet, it will use its "freedom" Internet IP
452    address.
453    
454    You will notice that we haven't configured the arc0e device on insight. 
455    This would work, but is not really necessary, and would require me to
456    assign insight another special IP number from my private subnet.  Since
457    both insight and patience are using freedom as their default gateway, the
458    two can already talk to each other.
459    
460    It's quite fortunate that I set things up like this the first time (cough
461    cough) because it's really handy when I boot insight into DOS.  There, it
462    runs the Novell ODI protocol stack, which only works with RFC1201 ARCnet. 
463    In this mode it would be impossible for insight to communicate directly
464    with patience, since the Novell stack is incompatible with Microsoft's
465    Ethernet-Encap.  Without changing any settings on freedom or patience, I
466    simply set freedom as the default gateway for insight (now in DOS,
467    remember) and all the forwarding happens "automagically" between the two
468    hosts that would normally not be able to communicate at all.
469    
470    For those who like diagrams, I have created two "virtual subnets" on the
471    same physical ARCnet wire.  You can picture it like this:
472    
473                                                     
474           [RFC1201 NETWORK]                   [ETHER-ENCAP NETWORK]
475       (registered Internet subnet)           (RFC1597 private subnet)
476   
477                              (IP Masquerade)
478           /---------------\         *            /---------------\
479           |               |         *            |               |
480           |               +-Freedom-*-Gatekeeper-+               |
481           |               |    |    *            |               |
482           \-------+-------/    |    *            \-------+-------/
483                   |            |                         |
484                Insight         |                      Patience
485                            (Internet)
489 It works: what now?
490 -------------------
492 Send mail describing your setup, preferably including driver version, kernel
493 version, ARCnet card model, CPU type, number of systems on your network, and
494 list of software in use to me at the following address:
495         apenwarr@worldvisions.ca
497 I do send (sometimes automated) replies to all messages I receive.  My email
498 can be weird (and also usually gets forwarded all over the place along the
499 way to me), so if you don't get a reply within a reasonable time, please
500 resend.
503 It doesn't work: what now?
504 --------------------------
506 Do the same as above, but also include the output of the ifconfig and route
507 commands, as well as any pertinent log entries (ie. anything that starts
508 with "arcnet:" and has shown up since the last reboot) in your mail.
510 If you want to try fixing it yourself (I strongly recommend that you mail me
511 about the problem first, since it might already have been solved) you may
512 want to try some of the debug levels available.  For heavy testing on
513 D_DURING or more, it would be a REALLY good idea to kill your klogd daemon
514 first!  D_DURING displays 4-5 lines for each packet sent or received.  D_TX,
515 D_RX, and D_SKB actually DISPLAY each packet as it is sent or received,
516 which is obviously quite big.
518 Starting with v2.40 ALPHA, the autoprobe routines have changed
519 significantly.  In particular, they won't tell you why the card was not
520 found unless you turn on the D_INIT_REASONS debugging flag.
522 Once the driver is running, you can run the arcdump shell script (available
523 from me or in the full ARCnet package, if you have it) as root to list the
524 contents of the arcnet buffers at any time.  To make any sense at all out of
525 this, you should grab the pertinent RFCs. (some are listed near the top of
526 arcnet.c).  arcdump assumes your card is at 0xD0000.  If it isn't, edit the
527 script.
529 Buffers 0 and 1 are used for receiving, and Buffers 2 and 3 are for sending. 
530 Ping-pong buffers are implemented both ways.
532 If your debug level includes D_DURING and you did NOT define SLOW_XMIT_COPY,
533 the buffers are cleared to a constant value of 0x42 every time the card is
534 reset (which should only happen when you do an ifconfig up, or when Linux
535 decides that the driver is broken).  During a transmit, unused parts of the
536 buffer will be cleared to 0x42 as well.  This is to make it easier to figure
537 out which bytes are being used by a packet.
539 You can change the debug level without recompiling the kernel by typing:
540         ifconfig arc0 down metric 1xxx
541         /etc/rc.d/rc.inet1
542 where "xxx" is the debug level you want.  For example, "metric 1015" would put
543 you at debug level 15.  Debug level 7 is currently the default.
545 Note that the debug level is (starting with v1.90 ALPHA) a binary
546 combination of different debug flags; so debug level 7 is really 1+2+4 or
547 D_NORMAL+D_EXTRA+D_INIT.  To include D_DURING, you would add 16 to this,
548 resulting in debug level 23.
550 If you don't understand that, you probably don't want to know anyway. 
551 E-mail me about your problem.
554 I want to send money: what now?
555 -------------------------------
557 Go take a nap or something.  You'll feel better in the morning.