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