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