docs: networking: convert arcnet.txt to ReST

- add SPDX header;
- use document title markup;
- add notes markups;
- mark code blocks and literals as such;
- mark tables as such;
- adjust identation, whitespaces and blank lines;
- add to networking/index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>

Documentation/networking/arcnet.txt → Documentation/networking/arcnet.rst

-----------------------------------------------------------------------------
-NOTE:  See also arcnet-hardware.txt in this directory for jumper-setting
-and cabling information if you're like many of us and didn't happen to get a
-manual with your ARCnet card.
-----------------------------------------------------------------------------
+.. SPDX-License-Identifier: GPL-2.0
+
+======
+ARCnet
+======
+
+.. note::
+
+   See also arcnet-hardware.txt in this directory for jumper-setting
+   and cabling information if you're like many of us and didn't happen to get a
+   manual with your ARCnet card.
 
 Since no one seems to listen to me otherwise, perhaps a poem will get your
-attention:
+attention::
+
 		This driver's getting fat and beefy,
 		But my cat is still named Fifi.
 
@@ -24,27 +31,20 @@ Come on, be a sport!  Send me a success report!
 (hey, that was even better than my original poem... this is getting bad!)
 
 
---------
-WARNING:
---------
-
-If you don't e-mail me about your success/failure soon, I may be forced to
-start SINGING.  And we don't want that, do we?
+.. warning::
 
-(You know, it might be argued that I'm pushing this point a little too much. 
-If you think so, why not flame me in a quick little e-mail?  Please also
-include the type of card(s) you're using, software, size of network, and
-whether it's working or not.)
+   If you don't e-mail me about your success/failure soon, I may be forced to
+   start SINGING.  And we don't want that, do we?
 
-My e-mail address is: apenwarr@worldvisions.ca
-
-
----------------------------------------------------------------------------
+   (You know, it might be argued that I'm pushing this point a little too much.
+   If you think so, why not flame me in a quick little e-mail?  Please also
+   include the type of card(s) you're using, software, size of network, and
+   whether it's working or not.)
 
+   My e-mail address is: apenwarr@worldvisions.ca
 
 These are the ARCnet drivers for Linux.
 
-
 This new release (2.91) has been put together by David Woodhouse
 <dwmw2@infradead.org>, in an attempt to tidy up the driver after adding support
 for yet another chipset. Now the generic support has been separated from the
@@ -68,6 +68,7 @@ REAL NAME" to listserv@tichy.ch.uj.edu.pl.  Then, to submit messages to the
 list, mail to linux-arcnet@tichy.ch.uj.edu.pl.
 
 There are archives of the mailing list at:
+
 	http://epistolary.org/mailman/listinfo.cgi/arcnet
 
 The people on linux-net@vger.kernel.org (now defunct, replaced by
@@ -80,15 +81,18 @@ Other Drivers and Info
 ----------------------
 
 You can try my ARCNET page on the World Wide Web at:
+
 	http://www.qis.net/~jschmitz/arcnet/
 
 Also, SMC (one of the companies that makes ARCnet cards) has a WWW site you
 might be interested in, which includes several drivers for various cards
 including ARCnet.  Try:
+
 	http://www.smc.com/
 
 Performance Technologies makes various network software that supports
 ARCnet:
+
 	http://www.perftech.com/ or ftp to ftp.perftech.com.
 
 Novell makes a networking stack for DOS which includes ARCnet drivers.  Try
@@ -105,7 +109,8 @@ access.
 Installing the Driver
 ---------------------
 
-All you will need to do in order to install the driver is:
+All you will need to do in order to install the driver is::
+
 	make config
 		(be sure to choose ARCnet in the network devices
 		and at least one chipset driver.)
@@ -125,10 +130,12 @@ There are four chipset options:
 
 This is the normal ARCnet card, which you've probably got. This is the only
 chipset driver which will autoprobe if not told where the card is.
-It following options on the command line:
+It following options on the command line::
+
  com90xx=[<io>[,<irq>[,<shmem>]]][,<name>] | <name>
 
-If you load the chipset support as a module, the options are:
+If you load the chipset support as a module, the options are::
+
  io=<io> irq=<irq> shmem=<shmem> device=<name>
 
 To disable the autoprobe, just specify "com90xx=" on the kernel command line.
@@ -140,10 +147,13 @@ This is the new chipset from SMC with support for promiscuous mode (packet
 sniffing), extra diagnostic information, etc. Unfortunately, there is no
 sensible method of autoprobing for these cards. You must specify the I/O
 address on the kernel command line.
-The command line options are:
+
+The command line options are::
+
  com20020=<io>[,<irq>[,<node_ID>[,backplane[,CKP[,timeout]]]]][,name]
 
-If you load the chipset support as a module, the options are:
+If you load the chipset support as a module, the options are::
+
  io=<io> irq=<irq> node=<node_ID> backplane=<backplane> clock=<CKP>
  timeout=<timeout> device=<name>
 
@@ -160,7 +170,9 @@ you have a card which doesn't support shared memory, or (strangely) in case
 you have so many ARCnet cards in your machine that you run out of shmem slots.
 If you don't give the IO address on the kernel command line, then the driver
 will not find the card.
-The command line options are:
+
+The command line options are::
+
  com90io=<io>[,<irq>][,<name>]
 
 If you load the chipset support as a module, the options are:
@@ -171,10 +183,12 @@ If you load the chipset support as a module, the options are:
 These are COM90xx chips which are _completely_ memory mapped. The support for
 these is not tested. If you have one, please mail the author with a success
 report. All options must be specified, except the device name.
-Command line options:
+Command line options::
+
  arcrimi=<shmem>,<irq>,<node_ID>[,<name>]
 
-If you load the chipset support as a module, the options are:
+If you load the chipset support as a module, the options are::
+
  shmem=<shmem> irq=<irq> node=<node_ID> device=<name>
 
 
@@ -186,6 +200,8 @@ support" and to support for your ARCnet chipset if you want to use the
 loadable module. You can also say 'y' to "Generic ARCnet support" and 'm'
 to the chipset support if you wish.
 
+::
+
 	make config
 	make clean
 	make zImage
@@ -196,7 +212,8 @@ you can specify various characteristics of your card on the command
 line.  (In recent versions of the driver, autoprobing is much more reliable
 and works as a module, so most of this is now unnecessary.)
 
-For example:
+For example::
+
 	cd /usr/src/linux/modules
 	insmod arcnet.o
 	insmod com90xx.o
@@ -228,21 +245,25 @@ ARCnet driver has somewhat suffered in this respect. COM90xx support, if
 compiled into the kernel, will (try to) autodetect all the installed cards.
 
 If you have other cards, with support compiled into the kernel, then you can
-just repeat the options on the kernel command line, e.g.:
-LILO: linux com20020=0x2e0 com20020=0x380 com90io=0x260
+just repeat the options on the kernel command line, e.g.::
+
+	LILO: linux com20020=0x2e0 com20020=0x380 com90io=0x260
 
 If you have the chipset support built as a loadable module, then you need to
-do something like this:
+do something like this::
+
 	insmod -o arc0 com90xx
 	insmod -o arc1 com20020 io=0x2e0
 	insmod -o arc2 com90xx
+
 The ARCnet drivers will now sort out their names automatically.
 
 
 How do I get it to work with...?
 --------------------------------
 
-NFS: Should be fine linux->linux, just pretend you're using Ethernet cards. 
+NFS:
+	Should be fine linux->linux, just pretend you're using Ethernet cards.
 	oak.oakland.edu:/simtel/msdos/nfs has some nice DOS clients.  There
 	is also a DOS-based NFS server called SOSS.  It doesn't multitask
 	quite the way Linux does (actually, it doesn't multitask AT ALL) but
@@ -257,16 +278,19 @@ NFS: Should be fine linux->linux, just pretend you're using Ethernet cards.
 	don't know why the defaults on the Amiga didn't work; write to me if
 	you know more.
 
-DOS: If you're using the freeware arcether.com, you might want to install
+DOS:
+	If you're using the freeware arcether.com, you might want to install
 	the driver patch from my web page.  It helps with PC/TCP, and also
 	can get arcether to load if it timed out too quickly during
 	initialization.  In fact, if you use it on a 386+ you REALLY need
 	the patch, really.
 
-Windows:  See DOS :)  Trumpet Winsock works fine with either the Novell or
+Windows:
+	See DOS :)  Trumpet Winsock works fine with either the Novell or
 	Arcether client, assuming you remember to load winpkt of course.
 
-LAN Manager and Windows for Workgroups: These programs use protocols that
+LAN Manager and Windows for Workgroups:
+	These programs use protocols that
 	are incompatible with the Internet standard.  They try to pretend
 	the cards are Ethernet, and confuse everyone else on the network.
 
@@ -278,7 +302,8 @@ LAN Manager and Windows for Workgroups: These programs use protocols that
 	interface quite nicely with TCP/IP-based WfWg or Lan Manager
 	networks.
 
-Windows 95: Tools are included with Win95 that let you use either the LANMAN
+Windows 95:
+	Tools are included with Win95 that let you use either the LANMAN
 	style network drivers (NDIS) or Novell drivers (ODI) to handle your
 	ARCnet packets.  If you use ODI, you'll need to use the 'arc0'
 	device with Linux.  If you use NDIS, then try the 'arc0e' device.
@@ -286,7 +311,8 @@ Windows 95: Tools are included with Win95 that let you use either the LANMAN
 	you're completely insane, and/or you need to build some kind of
 	hybrid network that uses both encapsulation types.
 
-OS/2: I've been told it works under Warp Connect with an ARCnet driver from
+OS/2:
+	I've been told it works under Warp Connect with an ARCnet driver from
 	SMC.  You need to use the 'arc0e' interface for this.  If you get
 	the SMC driver to work with the TCP/IP stuff included in the
 	"normal" Warp Bonus Pack, let me know.
@@ -295,7 +321,8 @@ OS/2: I've been told it works under Warp Connect with an ARCnet driver from
 	which should use the same protocol as WfWg does.  I had no luck
 	installing it under Warp, however.  Please mail me with any results.
 
-NetBSD/AmiTCP: These use an old version of the Internet standard ARCnet
+NetBSD/AmiTCP:
+	These use an old version of the Internet standard ARCnet
 	protocol (RFC1051) which is compatible with the Linux driver v2.10
 	ALPHA and above using the arc0s device. (See "Multiprotocol ARCnet"
 	below.)  ** Newer versions of NetBSD apparently support RFC1201.
@@ -307,7 +334,8 @@ Using Multiprotocol ARCnet
 The ARCnet driver v2.10 ALPHA supports three protocols, each on its own
 "virtual network device":
 
-	arc0  - RFC1201 protocol, the official Internet standard which just
+	======  ===============================================================
+	arc0	RFC1201 protocol, the official Internet standard which just
 		happens to be 100% compatible with Novell's TRXNET driver.
 		Version 1.00 of the ARCnet driver supported _only_ this
 		protocol.  arc0 is the fastest of the three protocols (for
@@ -316,7 +344,7 @@ The ARCnet driver v2.10 ALPHA supports three protocols, each on its own
 		Unless you have a specific need to use a different protocol,
 		I strongly suggest that you stick with this one.
 
-	arc0e - "Ethernet-Encapsulation" which sends packets over ARCnet
+	arc0e	"Ethernet-Encapsulation" which sends packets over ARCnet
 		that are actually a lot like Ethernet packets, including the
 		6-byte hardware addresses.  This protocol is compatible with
 		Microsoft's NDIS ARCnet driver, like the one in WfWg and
@@ -329,7 +357,7 @@ The ARCnet driver v2.10 ALPHA supports three protocols, each on its own
 		reasons yet to be determined.  (Probably it's the smaller
 		MTU that does it.)
 
-	arc0s - The "[s]imple" RFC1051 protocol is the "previous" Internet
+	arc0s	The "[s]imple" RFC1051 protocol is the "previous" Internet
 		standard that is completely incompatible with the new
 		standard.  Some software today, however, continues to
 		support the old standard (and only the old standard)
@@ -341,6 +369,7 @@ The ARCnet driver v2.10 ALPHA supports three protocols, each on its own
 
 		The arc0s support was contributed by Tomasz Motylewski
 		and modified somewhat by me.  Bugs are probably my fault.
+	======  ===============================================================
 
 You can choose not to compile arc0e and arc0s into the driver if you want -
 this will save you a bit of memory and avoid confusion when eg. trying to
@@ -359,13 +388,15 @@ can set up your network then:
    only arc0 unless you have a good reason (like some other software, ie.
    WfWg, that only works with arc0e).
 
-   If you need only arc0, then the following commands should get you going:
+   If you need only arc0, then the following commands should get you going::
+
 	ifconfig arc0 MY.IP.ADD.RESS
 	route add MY.IP.ADD.RESS arc0
 	route add -net SUB.NET.ADD.RESS arc0
 	[add other local routes here]
 
-   If you need arc0e (and only arc0e), it's a little different:
+   If you need arc0e (and only arc0e), it's a little different::
+
 	ifconfig arc0 MY.IP.ADD.RESS
 	ifconfig arc0e MY.IP.ADD.RESS
 	route add MY.IP.ADD.RESS arc0e
@@ -393,11 +424,13 @@ can set up your network then:
 
    To start with, take a simple network with just insight and freedom.
    Insight needs to:
+
 	- talk to freedom via RFC1201 (arc0) protocol, because I like it
 	  more and it's faster.
 	- use freedom as its Internet gateway.
 
-   That's pretty easy to do.  Set up insight like this:
+   That's pretty easy to do.  Set up insight like this::
+
 	ifconfig arc0 insight
 	route add insight arc0
 	route add freedom arc0	/* I would use the subnet here (like I said
@@ -408,7 +441,8 @@ can set up your network then:
 					things. */
 	route add default gw freedom
 
-   And freedom gets configured like so:
+   And freedom gets configured like so::
+
 	ifconfig arc0 freedom
 	route add freedom arc0
 	route add insight arc0
@@ -436,11 +470,12 @@ can set up your network then:
    the fact that both freedom and insight (courtesy of the arc0e device)
    could understand a direct transmission.
 
-   I compensate by giving freedom an extra IP address - aliased 'gatekeeper'
-   - that is on my private subnet, the same subnet that patience is on.  I
+   I compensate by giving freedom an extra IP address - aliased 'gatekeeper' -
+   that is on my private subnet, the same subnet that patience is on.  I
    then define gatekeeper to be the default gateway for patience.
 
-   To configure freedom (in addition to the commands above):
+   To configure freedom (in addition to the commands above)::
+
 	ifconfig arc0e gatekeeper
 	route add gatekeeper arc0e
 	route add patience arc0e
@@ -467,7 +502,7 @@ can set up your network then:
    hosts that would normally not be able to communicate at all.
 
    For those who like diagrams, I have created two "virtual subnets" on the
-   same physical ARCnet wire.  You can picture it like this:
+   same physical ARCnet wire.  You can picture it like this::
 
 
 	  [RFC1201 NETWORK]                   [ETHER-ENCAP NETWORK]
@@ -491,6 +526,7 @@ It works: what now?
 Send mail describing your setup, preferably including driver version, kernel
 version, ARCnet card model, CPU type, number of systems on your network, and
 list of software in use to me at the following address:
+
 	apenwarr@worldvisions.ca
 
 I do send (sometimes automated) replies to all messages I receive.  My email
@@ -535,9 +571,11 @@ decides that the driver is broken).  During a transmit, unused parts of the
 buffer will be cleared to 0x42 as well.  This is to make it easier to figure
 out which bytes are being used by a packet.
 
-You can change the debug level without recompiling the kernel by typing:
+You can change the debug level without recompiling the kernel by typing::
+
 	ifconfig arc0 down metric 1xxx
 	/etc/rc.d/rc.inet1
+
 where "xxx" is the debug level you want.  For example, "metric 1015" would put
 you at debug level 15.  Debug level 7 is currently the default.
 

Documentation/networking/index.rst

@@ -40,6 +40,7 @@ Contents:
    6pack
    altera_tse
    arcnet-hardware
+   arcnet
 
 .. only::  subproject and html
 

drivers/net/arcnet/Kconfig

@@ -9,7 +9,7 @@ menuconfig ARCNET
 	---help---
 	  If you have a network card of this type, say Y and check out the
 	  (arguably) beautiful poetry in
-	  <file:Documentation/networking/arcnet.txt>.
+	  <file:Documentation/networking/arcnet.rst>.
 
 	  You need both this driver, and the driver for the particular ARCnet
 	  chipset of your card. If you don't know, then it's probably a
@@ -28,7 +28,7 @@ config ARCNET_1201
 	  arc0 device.  You need to say Y here to communicate with
 	  industry-standard RFC1201 implementations, like the arcether.com
 	  packet driver or most DOS/Windows ODI drivers.  Please read the
-	  ARCnet documentation in <file:Documentation/networking/arcnet.txt>
+	  ARCnet documentation in <file:Documentation/networking/arcnet.rst>
 	  for more information about using arc0.
 
 config ARCNET_1051
@@ -42,7 +42,7 @@ config ARCNET_1051
 	  industry-standard RFC1201 implementations, like the arcether.com
 	  packet driver or most DOS/Windows ODI drivers. RFC1201 is included
 	  automatically as the arc0 device. Please read the ARCnet
-	  documentation in <file:Documentation/networking/arcnet.txt> for more
+	  documentation in <file:Documentation/networking/arcnet.rst> for more
 	  information about using arc0e and arc0s.
 
 config ARCNET_RAW