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.rst 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 15---- 16 17These are the ARCnet drivers for Linux. 18 19This new release (2.91) has been put together by David Woodhouse 20<dwmw2@infradead.org>, in an attempt to tidy up the driver after adding support 21for yet another chipset. Now the generic support has been separated from the 22individual chipset drivers, and the source files aren't quite so packed with 23#ifdefs! I've changed this file a bit, but kept it in the first person from 24Avery, because I didn't want to completely rewrite it. 25 26The previous release resulted from many months of on-and-off effort from me 27(Avery Pennarun), many bug reports/fixes and suggestions from others, and in 28particular a lot of input and coding from Tomasz Motylewski. Starting with 29ARCnet 2.10 ALPHA, Tomasz's all-new-and-improved RFC1051 support has been 30included and seems to be working fine! 31 32 33.. _arcnet-netdev: 34 35Where do I discuss these drivers? 36--------------------------------- 37 38ARCnet discussions take place on netdev. Simply send your email to 39netdev@vger.kernel.org and make sure to Cc: maintainer listed in 40"ARCNET NETWORK LAYER" heading of Documentation/process/maintainers.rst. 41 42Other Drivers and Info 43---------------------- 44 45You can try JoAnne Schmitz's ARCNET page on the World Wide Web at: 46 47 https://www.qis.net/~jschmitz/arcnet/ 48 49 50Supported Hardware 51------------------ 52 53Only PCI and PCI Express devices based on the COM20020 chipset are supported. 54This is the newest chipset from SMC with support for promiscuous mode (packet 55sniffing), extra diagnostic information, etc. These devices use the com20020_pci 56driver. 57 58Support for older chipsets and ISA and PCMCIA devices was previously available 59but has been removed. 60 61 62Configuring the Driver 63---------------------- 64 65The COM20020 driver will be loaded automatically at boot if a supported card is 66detected. 67 68If the com20020_pci driver was compiled as a loadable module, the options are:: 69 70 node=<node_ID> backplane=<backplane> clockp=<CKP> clockm=<CKM> 71 timeout=<timeout> device=<interface_name> 72 73If the driver was compiled into the kernel, the same options can be specified on 74the kernel command line by prefixing them with `com20020_pci.`, as in the 75following example:: 76 77 com20020_pci.device=eth1 78 79The COM20020 chipset allows you to set the node ID in software, overriding the 80default which is still set in DIP switches on the card. If you don't have the 81COM20020 data sheets, and you don't know what the other options refer 82to, then they won't interest you - forget them. 83 84Otherwise, ARCnet can be configured in a similar way to Ethernet, with the 85exception that ARCnet interface names begin with `arc`. 86 87 88How do I get it to work with...? 89-------------------------------- 90 91NFS: 92 Should be fine linux->linux, just pretend you're using Ethernet cards. 93 oak.oakland.edu:/simtel/msdos/nfs has some nice DOS clients. There 94 is also a DOS-based NFS server called SOSS. It doesn't multitask 95 quite the way Linux does (actually, it doesn't multitask AT ALL) but 96 you never know what you might need. 97 98 With AmiTCP (and possibly others), you may need to set the following 99 options in your Amiga nfstab: MD 1024 MR 1024 MW 1024 100 (Thanks to Christian Gottschling <ferksy@indigo.tng.oche.de> 101 for this.) 102 103 Probably these refer to maximum NFS data/read/write block sizes. I 104 don't know why the defaults on the Amiga didn't work; write to me if 105 you know more. 106 107DOS: 108 If you're using the freeware arcether.com, you might want to install 109 the driver patch from my web page. It helps with PC/TCP, and also 110 can get arcether to load if it timed out too quickly during 111 initialization. In fact, if you use it on a 386+ you REALLY need 112 the patch, really. 113 114Windows: 115 See DOS :) Trumpet Winsock works fine with either the Novell or 116 Arcether client, assuming you remember to load winpkt of course. 117 118LAN Manager and Windows for Workgroups: 119 These programs use protocols that 120 are incompatible with the Internet standard. They try to pretend 121 the cards are Ethernet, and confuse everyone else on the network. 122 123 The Linux ARCnet driver supports this protocol via the 'arc0e' device. 124 See the section on "Multiprotocol Support" for more information. 125 126 Using the freeware Samba server and clients for Linux, you can now 127 interface quite nicely with TCP/IP-based WfWg or Lan Manager 128 networks. 129 130Windows 95: 131 Tools are included with Win95 that let you use either the LANMAN 132 style network drivers (NDIS) or Novell drivers (ODI) to handle your 133 ARCnet packets. If you use ODI, you'll need to use the 'arc0' 134 device with Linux. If you use NDIS, then try the 'arc0e' device. 135 See the "Multiprotocol Support" section below if you need arc0e, 136 you're completely insane, and/or you need to build some kind of 137 hybrid network that uses both encapsulation types. 138 139OS/2: 140 I've been told it works under Warp Connect with an ARCnet driver from 141 SMC. You need to use the 'arc0e' interface for this. If you get 142 the SMC driver to work with the TCP/IP stuff included in the 143 "normal" Warp Bonus Pack, let me know. 144 145 ftp.microsoft.com also has a freeware "Lan Manager for OS/2" client 146 which should use the same protocol as WfWg does. I had no luck 147 installing it under Warp, however. Please mail me with any results. 148 149NetBSD/AmiTCP: 150 These use an old version of the Internet standard ARCnet 151 protocol (RFC1051) which is compatible with the Linux driver v2.10 152 ALPHA and above using the arc0s device. (See "Multiprotocol ARCnet" 153 below.) ** Newer versions of NetBSD apparently support RFC1201. 154 155 156Using Multiprotocol ARCnet 157-------------------------- 158 159The ARCnet driver supports three protocols, each on its own 160"virtual network device": 161 162 ====== =============================================================== 163 arc0 RFC1201 protocol, the official Internet standard which just 164 happens to be 100% compatible with Novell's TRXNET driver. 165 Version 1.00 of the ARCnet driver supported _only_ this 166 protocol. arc0 is the fastest of the three protocols (for 167 whatever reason), and allows larger packets to be used 168 because it supports RFC1201 "packet splitting" operations. 169 Unless you have a specific need to use a different protocol, 170 I strongly suggest that you stick with this one. 171 172 arc0e "Ethernet-Encapsulation" which sends packets over ARCnet 173 that are actually a lot like Ethernet packets, including the 174 6-byte hardware addresses. This protocol is compatible with 175 Microsoft's NDIS ARCnet driver, like the one in WfWg and 176 LANMAN. Because the MTU of 493 is actually smaller than the 177 one "required" by TCP/IP (576), there is a chance that some 178 network operations will not function properly. The Linux 179 TCP/IP layer can compensate in most cases, however, by 180 automatically fragmenting the TCP/IP packets to make them 181 fit. arc0e also works slightly more slowly than arc0, for 182 reasons yet to be determined. (Probably it's the smaller 183 MTU that does it.) 184 185 arc0s The "[s]imple" RFC1051 protocol is the "previous" Internet 186 standard that is completely incompatible with the new 187 standard. Some software today, however, continues to 188 support the old standard (and only the old standard) 189 including NetBSD and AmiTCP. RFC1051 also does not support 190 RFC1201's packet splitting, and the MTU of 507 is still 191 smaller than the Internet "requirement," so it's quite 192 possible that you may run into problems. It's also slower 193 than RFC1201 by about 25%, for the same reason as arc0e. 194 195 The arc0s support was contributed by Tomasz Motylewski 196 and modified somewhat by me. Bugs are probably my fault. 197 ====== =============================================================== 198 199You can choose not to compile arc0e and arc0s into the driver if you want - 200this will save you a bit of memory and avoid confusion when eg. trying to 201use the "NFS-root" stuff in recent Linux kernels. 202 203The arc0e and arc0s devices are created automatically when you first 204ifconfig the arc0 device. To actually use them, though, you need to also 205ifconfig the other virtual devices you need. There are a number of ways you 206can set up your network then: 207 208 2091. Single Protocol. 210 211 This is the simplest way to configure your network: use just one of the 212 two available protocols. As mentioned above, it's a good idea to use 213 only arc0 unless you have a good reason (like some other software, ie. 214 WfWg, that only works with arc0e). 215 216 If you need only arc0, then the following commands should get you going:: 217 218 ifconfig arc0 MY.IP.ADD.RESS 219 route add MY.IP.ADD.RESS arc0 220 route add -net SUB.NET.ADD.RESS arc0 221 [add other local routes here] 222 223 If you need arc0e (and only arc0e), it's a little different:: 224 225 ifconfig arc0 MY.IP.ADD.RESS 226 ifconfig arc0e MY.IP.ADD.RESS 227 route add MY.IP.ADD.RESS arc0e 228 route add -net SUB.NET.ADD.RESS arc0e 229 230 arc0s works much the same way as arc0e. 231 232 2332. More than one protocol on the same wire. 234 235 Now things start getting confusing. To even try it, you may need to be 236 partly crazy. Here's what *I* did. :) Note that I don't include arc0s in 237 my home network; I don't have any NetBSD or AmiTCP computers, so I only 238 use arc0s during limited testing. 239 240 I have three computers on my home network; two Linux boxes (which prefer 241 RFC1201 protocol, for reasons listed above), and one XT that can't run 242 Linux but runs the free Microsoft LANMAN Client instead. 243 244 Worse, one of the Linux computers (freedom) also has a modem and acts as 245 a router to my Internet provider. The other Linux box (insight) also has 246 its own IP address and needs to use freedom as its default gateway. The 247 XT (patience), however, does not have its own Internet IP address and so 248 I assigned it one on a "private subnet" (as defined by RFC1597). 249 250 To start with, take a simple network with just insight and freedom. 251 Insight needs to: 252 253 - talk to freedom via RFC1201 (arc0) protocol, because I like it 254 more and it's faster. 255 - use freedom as its Internet gateway. 256 257 That's pretty easy to do. Set up insight like this:: 258 259 ifconfig arc0 insight 260 route add insight arc0 261 route add freedom arc0 /* I would use the subnet here (like I said 262 to in "single protocol" above), 263 but the rest of the subnet 264 unfortunately lies across the PPP 265 link on freedom, which confuses 266 things. */ 267 route add default gw freedom 268 269 And freedom gets configured like so:: 270 271 ifconfig arc0 freedom 272 route add freedom arc0 273 route add insight arc0 274 /* and default gateway is configured by pppd */ 275 276 Great, now insight talks to freedom directly on arc0, and sends packets 277 to the Internet through freedom. If you didn't know how to do the above, 278 you should probably stop reading this section now because it only gets 279 worse. 280 281 Now, how do I add patience into the network? It will be using LANMAN 282 Client, which means I need the arc0e device. It needs to be able to talk 283 to both insight and freedom, and also use freedom as a gateway to the 284 Internet. (Recall that patience has a "private IP address" which won't 285 work on the Internet; that's okay, I configured Linux IP masquerading on 286 freedom for this subnet). 287 288 So patience (necessarily; I don't have another IP number from my 289 provider) has an IP address on a different subnet than freedom and 290 insight, but needs to use freedom as an Internet gateway. Worse, most 291 DOS networking programs, including LANMAN, have braindead networking 292 schemes that rely completely on the netmask and a 'default gateway' to 293 determine how to route packets. This means that to get to freedom or 294 insight, patience WILL send through its default gateway, regardless of 295 the fact that both freedom and insight (courtesy of the arc0e device) 296 could understand a direct transmission. 297 298 I compensate by giving freedom an extra IP address - aliased 'gatekeeper' - 299 that is on my private subnet, the same subnet that patience is on. I 300 then define gatekeeper to be the default gateway for patience. 301 302 To configure freedom (in addition to the commands above):: 303 304 ifconfig arc0e gatekeeper 305 route add gatekeeper arc0e 306 route add patience arc0e 307 308 This way, freedom will send all packets for patience through arc0e, 309 giving its IP address as gatekeeper (on the private subnet). When it 310 talks to insight or the Internet, it will use its "freedom" Internet IP 311 address. 312 313 You will notice that we haven't configured the arc0e device on insight. 314 This would work, but is not really necessary, and would require me to 315 assign insight another special IP number from my private subnet. Since 316 both insight and patience are using freedom as their default gateway, the 317 two can already talk to each other. 318 319 It's quite fortunate that I set things up like this the first time (cough 320 cough) because it's really handy when I boot insight into DOS. There, it 321 runs the Novell ODI protocol stack, which only works with RFC1201 ARCnet. 322 In this mode it would be impossible for insight to communicate directly 323 with patience, since the Novell stack is incompatible with Microsoft's 324 Ethernet-Encap. Without changing any settings on freedom or patience, I 325 simply set freedom as the default gateway for insight (now in DOS, 326 remember) and all the forwarding happens "automagically" between the two 327 hosts that would normally not be able to communicate at all. 328 329 For those who like diagrams, I have created two "virtual subnets" on the 330 same physical ARCnet wire. You can picture it like this:: 331 332 333 [RFC1201 NETWORK] [ETHER-ENCAP NETWORK] 334 (registered Internet subnet) (RFC1597 private subnet) 335 336 (IP Masquerade) 337 /---------------\ * /---------------\ 338 | | * | | 339 | +-Freedom-*-Gatekeeper-+ | 340 | | | * | | 341 \-------+-------/ | * \-------+-------/ 342 | | | 343 Insight | Patience 344 (Internet) 345 346 347 348It works: what now? 349------------------- 350 351:ref:`Send an email to netdev <arcnet-netdev>`. Describe your setup, preferably 352including driver version, kernel version, ARCnet card model, CPU type, number 353of systems on your network, and list of software in use. 354 355It doesn't work: what now? 356-------------------------- 357 358Do the same as above, but also include the output of the ifconfig and route 359commands, as well as any pertinent log entries (ie. anything that starts 360with "arcnet:" and has shown up since the last reboot) in your mail. 361 362If you want to try fixing it yourself (I strongly recommend that you mail me 363about the problem first, since it might already have been solved) you may 364want to try some of the debug levels available. For heavy testing on 365D_DURING or more, it would be a REALLY good idea to kill your klogd daemon 366first! D_DURING displays 4-5 lines for each packet sent or received. D_TX, 367D_RX, and D_SKB actually DISPLAY each packet as it is sent or received, 368which is obviously quite big. 369 370Once the driver is running, you can run the arcdump shell script (available 371from me or in the full ARCnet package, if you have it) as root to list the 372contents of the arcnet buffers at any time. To make any sense at all out of 373this, you should grab the pertinent RFCs. (some are listed near the top of 374arcnet.c). arcdump assumes your card is at 0xD0000. If it isn't, edit the 375script. 376 377Buffers 0 and 1 are used for receiving, and Buffers 2 and 3 are for sending. 378Ping-pong buffers are implemented both ways. 379 380If your debug level includes D_DURING and you did NOT define SLOW_XMIT_COPY, 381the buffers are cleared to a constant value of 0x42 every time the card is 382reset (which should only happen when you do an ifconfig up, or when Linux 383decides that the driver is broken). During a transmit, unused parts of the 384buffer will be cleared to 0x42 as well. This is to make it easier to figure 385out which bytes are being used by a packet. 386 387You can change the debug level without recompiling the kernel by typing:: 388 389 ifconfig arc0 down metric 1xxx 390 ifconfig arc0 up 391 392where "xxx" is the debug level you want. For example, "metric 1015" would put 393you at debug level 15. Debug level 7 is currently the default. 394 395Note that the debug level is a binary combination of different debug flags; 396debug level 7 is really 1+2+4 or D_NORMAL+D_EXTRA+D_INIT. To include D_DURING, 397you would add 16 to this, resulting in debug level 23. 398 399If you don't understand that, you probably don't want to know anyway. 400