[linux-block.git] / Documentation / networking / plip.rst

.. SPDX-License-Identifier: GPL-2.0

================================================
PLIP: The Parallel Line Internet Protocol Device
================================================

Donald Becker (becker@super.org)
I.D.A. Supercomputing Research Center, Bowie MD 20715

At some point T. Thorn will probably contribute text,
Tommy Thorn (tthorn@daimi.aau.dk)

PLIP Introduction
-----------------

This document describes the parallel port packet pusher for Net/LGX.
This device interface allows a point-to-point connection between two
parallel ports to appear as a IP network interface.

What is PLIP?
=============

PLIP is Parallel Line IP, that is, the transportation of IP packages
over a parallel port. In the case of a PC, the obvious choice is the
printer port.  PLIP is a non-standard, but [can use] uses the standard
LapLink null-printer cable [can also work in turbo mode, with a PLIP
cable]. [The protocol used to pack IP packages, is a simple one
initiated by Crynwr.]

Advantages of PLIP
==================

It's cheap, it's available everywhere, and it's easy.

The PLIP cable is all that's needed to connect two Linux boxes, and it
can be built for very few bucks.

Connecting two Linux boxes takes only a second's decision and a few
minutes' work, no need to search for a [supported] netcard. This might
even be especially important in the case of notebooks, where netcards
are not easily available.

Not requiring a netcard also means that apart from connecting the
cables, everything else is software configuration [which in principle
could be made very easy.]

Disadvantages of PLIP
=====================

Doesn't work over a modem, like SLIP and PPP. Limited range, 15 m.
Can only be used to connect three (?) Linux boxes. Doesn't connect to
an existing Ethernet. Isn't standard (not even de facto standard, like
SLIP).

Performance
===========

PLIP easily outperforms Ethernet cards....(ups, I was dreaming, but
it *is* getting late. EOB)

PLIP driver details
-------------------

The Linux PLIP driver is an implementation of the original Crynwr protocol,
that uses the parallel port subsystem of the kernel in order to properly
share parallel ports between PLIP and other services.

IRQs and trigger timeouts
=========================

When a parallel port used for a PLIP driver has an IRQ configured to it, the
PLIP driver is signaled whenever data is sent to it via the cable, such that
when no data is available, the driver isn't being used.

However, on some machines it is hard, if not impossible, to configure an IRQ
to a certain parallel port, mainly because it is used by some other device.
On these machines, the PLIP driver can be used in IRQ-less mode, where
the PLIP driver would constantly poll the parallel port for data waiting,
and if such data is available, process it. This mode is less efficient than
the IRQ mode, because the driver has to check the parallel port many times
per second, even when no data at all is sent. Some rough measurements
indicate that there isn't a noticeable performance drop when using IRQ-less
mode as compared to IRQ mode as far as the data transfer speed is involved.
There is a performance drop on the machine hosting the driver.

When the PLIP driver is used in IRQ mode, the timeout used for triggering a
data transfer (the maximal time the PLIP driver would allow the other side
before announcing a timeout, when trying to handshake a transfer of some
data) is, by default, 500usec. As IRQ delivery is more or less immediate,
this timeout is quite sufficient.

When in IRQ-less mode, the PLIP driver polls the parallel port HZ times
per second (where HZ is typically 100 on most platforms, and 1024 on an
Alpha, as of this writing). Between two such polls, there are 10^6/HZ usecs.
On an i386, for example, 10^6/100 = 10000usec. It is easy to see that it is
quite possible for the trigger timeout to expire between two such polls, as
the timeout is only 500usec long. As a result, it is required to change the
trigger timeout on the *other* side of a PLIP connection, to about
10^6/HZ usecs. If both sides of a PLIP connection are used in IRQ-less mode,
this timeout is required on both sides.

It appears that in practice, the trigger timeout can be shorter than in the
above calculation. It isn't an important issue, unless the wire is faulty,
in which case a long timeout would stall the machine when, for whatever
reason, bits are dropped.

A utility that can perform this change in Linux is plipconfig, which is part
of the net-tools package (its location can be found in the
Documentation/Changes file). An example command would be
'plipconfig plipX trigger 10000', where plipX is the appropriate
PLIP device.

PLIP hardware interconnection
-----------------------------

PLIP uses several different data transfer methods.  The first (and the
only one implemented in the early version of the code) uses a standard
printer "null" cable to transfer data four bits at a time using
data bit outputs connected to status bit inputs.

The second data transfer method relies on both machines having
bi-directional parallel ports, rather than output-only ``printer``
ports.  This allows byte-wide transfers and avoids reconstructing
nibbles into bytes, leading to much faster transfers.

Parallel Transfer Mode 0 Cable
==============================

The cable for the first transfer mode is a standard
printer "null" cable which transfers data four bits at a time using
data bit outputs of the first port (machine T) connected to the
status bit inputs of the second port (machine R).  There are five
status inputs, and they are used as four data inputs and a clock (data
strobe) input, arranged so that the data input bits appear as contiguous
bits with standard status register implementation.

A cable that implements this protocol is available commercially as a
"Null Printer" or "Turbo Laplink" cable.  It can be constructed with
two DB-25 male connectors symmetrically connected as follows::

    STROBE output	1*
    D0->ERROR	2 - 15		15 - 2
    D1->SLCT	3 - 13		13 - 3
    D2->PAPOUT	4 - 12		12 - 4
    D3->ACK	5 - 10		10 - 5
    D4->BUSY	6 - 11		11 - 6
    D5,D6,D7 are   7*, 8*, 9*
    AUTOFD output 14*
    INIT   output 16*
    SLCTIN	17 - 17
    extra grounds are 18*,19*,20*,21*,22*,23*,24*
    GROUND	25 - 25

    * Do not connect these pins on either end

If the cable you are using has a metallic shield it should be
connected to the metallic DB-25 shell at one end only.

Parallel Transfer Mode 1
========================

The second data transfer method relies on both machines having
bi-directional parallel ports, rather than output-only ``printer``
ports.  This allows byte-wide transfers, and avoids reconstructing
nibbles into bytes.  This cable should not be used on unidirectional
``printer`` (as opposed to ``parallel``) ports or when the machine
isn't configured for PLIP, as it will result in output driver
conflicts and the (unlikely) possibility of damage.

The cable for this transfer mode should be constructed as follows::

    STROBE->BUSY 1 - 11
    D0->D0	2 - 2
    D1->D1	3 - 3
    D2->D2	4 - 4
    D3->D3	5 - 5
    D4->D4	6 - 6
    D5->D5	7 - 7
    D6->D6	8 - 8
    D7->D7	9 - 9
    INIT -> ACK  16 - 10
    AUTOFD->PAPOUT 14 - 12
    SLCT->SLCTIN 13 - 17
    GND->ERROR	18 - 15
    extra grounds are 19*,20*,21*,22*,23*,24*
    GROUND	25 - 25

    * Do not connect these pins on either end

Once again, if the cable you are using has a metallic shield it should
be connected to the metallic DB-25 shell at one end only.

PLIP Mode 0 transfer protocol
=============================

The PLIP driver is compatible with the "Crynwr" parallel port transfer
standard in Mode 0.  That standard specifies the following protocol::

   send header nibble '0x8'
   count-low octet
   count-high octet
   ... data octets
   checksum octet

Each octet is sent as::

	<wait for rx. '0x1?'>	<send 0x10+(octet&0x0F)>
	<wait for rx. '0x0?'>	<send 0x00+((octet>>4)&0x0F)>

To start a transfer the transmitting machine outputs a nibble 0x08.
That raises the ACK line, triggering an interrupt in the receiving
machine.  The receiving machine disables interrupts and raises its own ACK
line.

Restated::

  (OUT is bit 0-4, OUT.j is bit j from OUT. IN likewise)
  Send_Byte:
     OUT := low nibble, OUT.4 := 1
     WAIT FOR IN.4 = 1
     OUT := high nibble, OUT.4 := 0
     WAIT FOR IN.4 = 0
Commit	Line	Data
32c01266 MCC	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	================================================
1da177e4	4	PLIP: The Parallel Line Internet Protocol Device
32c01266	5	================================================
1da177e4 LT	6
	7	Donald Becker (becker@super.org)
	8	I.D.A. Supercomputing Research Center, Bowie MD 20715
	9
	10	At some point T. Thorn will probably contribute text,
	11	Tommy Thorn (tthorn@daimi.aau.dk)
	12
	13	PLIP Introduction
	14	-----------------
	15
	16	This document describes the parallel port packet pusher for Net/LGX.
	17	This device interface allows a point-to-point connection between two
	18	parallel ports to appear as a IP network interface.
	19
	20	What is PLIP?
	21	=============
	22
	23	PLIP is Parallel Line IP, that is, the transportation of IP packages
	24	over a parallel port. In the case of a PC, the obvious choice is the
	25	printer port. PLIP is a non-standard, but [can use] uses the standard
	26	LapLink null-printer cable [can also work in turbo mode, with a PLIP
	27	cable]. [The protocol used to pack IP packages, is a simple one
	28	initiated by Crynwr.]
	29
	30	Advantages of PLIP
	31	==================
	32
	33	It's cheap, it's available everywhere, and it's easy.
	34
	35	The PLIP cable is all that's needed to connect two Linux boxes, and it
	36	can be built for very few bucks.
	37
	38	Connecting two Linux boxes takes only a second's decision and a few
	39	minutes' work, no need to search for a [supported] netcard. This might
	40	even be especially important in the case of notebooks, where netcards
	41	are not easily available.
	42
	43	Not requiring a netcard also means that apart from connecting the
	44	cables, everything else is software configuration [which in principle
	45	could be made very easy.]
	46
	47	Disadvantages of PLIP
	48	=====================
	49
	50	Doesn't work over a modem, like SLIP and PPP. Limited range, 15 m.
	51	Can only be used to connect three (?) Linux boxes. Doesn't connect to
	52	an existing Ethernet. Isn't standard (not even de facto standard, like
	53	SLIP).
	54
	55	Performance
	56	===========
	57
	58	PLIP easily outperforms Ethernet cards....(ups, I was dreaming, but
	59	it is getting late. EOB)
	60
	61	PLIP driver details
	62	-------------------
	63
	64	The Linux PLIP driver is an implementation of the original Crynwr protocol,
	65	that uses the parallel port subsystem of the kernel in order to properly
	66	share parallel ports between PLIP and other services.
	67
	68	IRQs and trigger timeouts
	69	=========================
70
71	When a parallel port used for a PLIP driver has an IRQ configured to it, the
72	PLIP driver is signaled whenever data is sent to it via the cable, such that
73	when no data is available, the driver isn't being used.
74
75	However, on some machines it is hard, if not impossible, to configure an IRQ
76	to a certain parallel port, mainly because it is used by some other device.
77	On these machines, the PLIP driver can be used in IRQ-less mode, where
78	the PLIP driver would constantly poll the parallel port for data waiting,
79	and if such data is available, process it. This mode is less efficient than
80	the IRQ mode, because the driver has to check the parallel port many times
81	per second, even when no data at all is sent. Some rough measurements
82	indicate that there isn't a noticeable performance drop when using IRQ-less
83	mode as compared to IRQ mode as far as the data transfer speed is involved.
84	There is a performance drop on the machine hosting the driver.
85
86	When the PLIP driver is used in IRQ mode, the timeout used for triggering a
87	data transfer (the maximal time the PLIP driver would allow the other side
88	before announcing a timeout, when trying to handshake a transfer of some
89	data) is, by default, 500usec. As IRQ delivery is more or less immediate,
32c01266	90	this timeout is quite sufficient.
1da177e4 LT	91
	92	When in IRQ-less mode, the PLIP driver polls the parallel port HZ times
	93	per second (where HZ is typically 100 on most platforms, and 1024 on an
	94	Alpha, as of this writing). Between two such polls, there are 10^6/HZ usecs.
	95	On an i386, for example, 10^6/100 = 10000usec. It is easy to see that it is
	96	quite possible for the trigger timeout to expire between two such polls, as
	97	the timeout is only 500usec long. As a result, it is required to change the
	98	trigger timeout on the other side of a PLIP connection, to about
	99	10^6/HZ usecs. If both sides of a PLIP connection are used in IRQ-less mode,
	100	this timeout is required on both sides.
	101
	102	It appears that in practice, the trigger timeout can be shorter than in the
	103	above calculation. It isn't an important issue, unless the wire is faulty,
	104	in which case a long timeout would stall the machine when, for whatever
	105	reason, bits are dropped.
	106
	107	A utility that can perform this change in Linux is plipconfig, which is part
	108	of the net-tools package (its location can be found in the
	109	Documentation/Changes file). An example command would be
	110	'plipconfig plipX trigger 10000', where plipX is the appropriate
	111	PLIP device.
	112
	113	PLIP hardware interconnection
	114	-----------------------------
	115
	116	PLIP uses several different data transfer methods. The first (and the
	117	only one implemented in the early version of the code) uses a standard
	118	printer "null" cable to transfer data four bits at a time using
	119	data bit outputs connected to status bit inputs.
	120
	121	The second data transfer method relies on both machines having
32c01266	122	bi-directional parallel ports, rather than output-only ``printer``
1da177e4 LT	123	ports. This allows byte-wide transfers and avoids reconstructing
	124	nibbles into bytes, leading to much faster transfers.
	125
	126	Parallel Transfer Mode 0 Cable
	127	==============================
	128
	129	The cable for the first transfer mode is a standard
	130	printer "null" cable which transfers data four bits at a time using
	131	data bit outputs of the first port (machine T) connected to the
	132	status bit inputs of the second port (machine R). There are five
	133	status inputs, and they are used as four data inputs and a clock (data
	134	strobe) input, arranged so that the data input bits appear as contiguous
	135	bits with standard status register implementation.
	136
	137	A cable that implements this protocol is available commercially as a
	138	"Null Printer" or "Turbo Laplink" cable. It can be constructed with
32c01266	139	two DB-25 male connectors symmetrically connected as follows::
1da177e4 LT	140
	141	STROBE output 1*
	142	D0->ERROR 2 - 15 15 - 2
	143	D1->SLCT 3 - 13 13 - 3
	144	D2->PAPOUT 4 - 12 12 - 4
	145	D3->ACK 5 - 10 10 - 5
	146	D4->BUSY 6 - 11 11 - 6
	147	D5,D6,D7 are 7, 8, 9*
	148	AUTOFD output 14*
	149	INIT output 16*
	150	SLCTIN 17 - 17
	151	extra grounds are 18,19,20,21,22,23,24*
	152	GROUND 25 - 25
32c01266 MCC	153
32c01266 MCC	154	* Do not connect these pins on either end
1da177e4 LT	155
	156	If the cable you are using has a metallic shield it should be
	157	connected to the metallic DB-25 shell at one end only.
	158
	159	Parallel Transfer Mode 1
	160	========================
	161
	162	The second data transfer method relies on both machines having
32c01266	163	bi-directional parallel ports, rather than output-only ``printer``
1da177e4 LT	164	ports. This allows byte-wide transfers, and avoids reconstructing
1da177e4 LT	165	nibbles into bytes. This cable should not be used on unidirectional
32c01266	166	``printer`` (as opposed to ``parallel``) ports or when the machine
1da177e4 LT	167	isn't configured for PLIP, as it will result in output driver
	168	conflicts and the (unlikely) possibility of damage.
	169
32c01266	170	The cable for this transfer mode should be constructed as follows::
1da177e4 LT	171
	172	STROBE->BUSY 1 - 11
	173	D0->D0 2 - 2
	174	D1->D1 3 - 3
	175	D2->D2 4 - 4
	176	D3->D3 5 - 5
	177	D4->D4 6 - 6
	178	D5->D5 7 - 7
	179	D6->D6 8 - 8
	180	D7->D7 9 - 9
	181	INIT -> ACK 16 - 10
	182	AUTOFD->PAPOUT 14 - 12
	183	SLCT->SLCTIN 13 - 17
	184	GND->ERROR 18 - 15
	185	extra grounds are 19,20,21,22,23,24
	186	GROUND 25 - 25
32c01266 MCC	187
32c01266 MCC	188	* Do not connect these pins on either end
1da177e4 LT	189
	190	Once again, if the cable you are using has a metallic shield it should
	191	be connected to the metallic DB-25 shell at one end only.
	192
	193	PLIP Mode 0 transfer protocol
	194	=============================
	195
	196	The PLIP driver is compatible with the "Crynwr" parallel port transfer
32c01266	197	standard in Mode 0. That standard specifies the following protocol::
1da177e4 LT	198
	199	send header nibble '0x8'
	200	count-low octet
	201	count-high octet
	202	... data octets
	203	checksum octet
	204
32c01266 MCC	205	Each octet is sent as::
32c01266 MCC	206
1da177e4 LT	207	<wait for rx. '0x1?'> <send 0x10+(octet&0x0F)>
	208	<wait for rx. '0x0?'> <send 0x00+((octet>>4)&0x0F)>
	209
	210	To start a transfer the transmitting machine outputs a nibble 0x08.
	211	That raises the ACK line, triggering an interrupt in the receiving
	212	machine. The receiving machine disables interrupts and raises its own ACK
32c01266	213	line.
1da177e4	214
32c01266	215	Restated::
1da177e4	216
32c01266 MCC	217	(OUT is bit 0-4, OUT.j is bit j from OUT. IN likewise)
	218	Send_Byte:
	219	OUT := low nibble, OUT.4 := 1
	220	WAIT FOR IN.4 = 1
	221	OUT := high nibble, OUT.4 := 0
	222	WAIT FOR IN.4 = 0