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