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