Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation/parport.txt: convert to ReST markup
- Add a document title;
- use quote blocks where needed;
- convert parameters to a nested table;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- replace _foo_ by **foo**;
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
+138
-130
+138
-130
Documentation/parport.txt
+138
-130
Documentation/parport.txt
···
1
-
The `parport' code provides parallel-port support under Linux. This
1
+
Parport
2
+
+++++++
3
+
4
+
The ``parport`` code provides parallel-port support under Linux. This
2
5
includes the ability to share one port between multiple device
3
6
drivers.
4
7
5
-
You can pass parameters to the parport code to override its automatic
8
+
You can pass parameters to the ``parport`` code to override its automatic
6
9
detection of your hardware. This is particularly useful if you want
7
10
to use IRQs, since in general these can't be autoprobed successfully.
8
-
By default IRQs are not used even if they _can_ be probed. This is
11
+
By default IRQs are not used even if they **can** be probed. This is
9
12
because there are a lot of people using the same IRQ for their
10
13
parallel port and a sound card or network card.
11
14
12
-
The parport code is split into two parts: generic (which deals with
15
+
The ``parport`` code is split into two parts: generic (which deals with
13
16
port-sharing) and architecture-dependent (which deals with actually
14
17
using the port).
15
18
···
20
17
Parport as modules
21
18
==================
22
19
23
-
If you load the parport code as a module, say
20
+
If you load the `parport`` code as a module, say::
24
21
25
22
# insmod parport
26
23
27
-
to load the generic parport code. You then must load the
28
-
architecture-dependent code with (for example):
24
+
to load the generic ``parport`` code. You then must load the
25
+
architecture-dependent code with (for example)::
29
26
30
27
# insmod parport_pc io=0x3bc,0x378,0x278 irq=none,7,auto
31
28
32
-
to tell the parport code that you want three PC-style ports, one at
29
+
to tell the ``parport`` code that you want three PC-style ports, one at
33
30
0x3bc with no IRQ, one at 0x378 using IRQ 7, and one at 0x278 with an
34
-
auto-detected IRQ. Currently, PC-style (parport_pc), Sun `bpp',
31
+
auto-detected IRQ. Currently, PC-style (``parport_pc``), Sun ``bpp``,
35
32
Amiga, Atari, and MFC3 hardware is supported.
36
33
37
-
PCI parallel I/O card support comes from parport_pc. Base I/O
34
+
PCI parallel I/O card support comes from ``parport_pc``. Base I/O
38
35
addresses should not be specified for supported PCI cards since they
39
36
are automatically detected.
40
37
···
43
40
--------
44
41
45
42
If you use modprobe , you will find it useful to add lines as below to a
46
-
configuration file in /etc/modprobe.d/ directory:.
43
+
configuration file in /etc/modprobe.d/ directory::
47
44
48
45
alias parport_lowlevel parport_pc
49
46
options parport_pc io=0x378,0x278 irq=7,auto
50
47
51
-
modprobe will load parport_pc (with the options "io=0x378,0x278 irq=7,auto")
52
-
whenever a parallel port device driver (such as lp) is loaded.
48
+
modprobe will load ``parport_pc`` (with the options ``io=0x378,0x278 irq=7,auto``)
49
+
whenever a parallel port device driver (such as ``lp``) is loaded.
53
50
54
51
Note that these are example lines only! You shouldn't in general need
55
-
to specify any options to parport_pc in order to be able to use a
52
+
to specify any options to ``parport_pc`` in order to be able to use a
56
53
parallel port.
57
54
58
55
59
56
Parport probe [optional]
60
-
-------------
57
+
------------------------
61
58
62
-
In 2.2 kernels there was a module called parport_probe, which was used
59
+
In 2.2 kernels there was a module called ``parport_probe``, which was used
63
60
for collecting IEEE 1284 device ID information. This has now been
64
61
enhanced and now lives with the IEEE 1284 support. When a parallel
65
62
port is detected, the devices that are connected to it are analysed,
66
-
and information is logged like this:
63
+
and information is logged like this::
67
64
68
65
parport0: Printer, BJC-210 (Canon)
69
66
70
-
The probe information is available from files in /proc/sys/dev/parport/.
67
+
The probe information is available from files in ``/proc/sys/dev/parport/``.
71
68
72
69
73
70
Parport linked into the kernel statically
74
71
=========================================
75
72
76
-
If you compile the parport code into the kernel, then you can use
73
+
If you compile the ``parport`` code into the kernel, then you can use
77
74
kernel boot parameters to get the same effect. Add something like the
78
-
following to your LILO command line:
75
+
following to your LILO command line::
79
76
80
77
parport=0x3bc parport=0x378,7 parport=0x278,auto,nofifo
81
78
82
-
You can have many `parport=...' statements, one for each port you want
83
-
to add. Adding `parport=0' to the kernel command-line will disable
84
-
parport support entirely. Adding `parport=auto' to the kernel
85
-
command-line will make parport use any IRQ lines or DMA channels that
79
+
You can have many ``parport=...`` statements, one for each port you want
80
+
to add. Adding ``parport=0`` to the kernel command-line will disable
81
+
parport support entirely. Adding ``parport=auto`` to the kernel
82
+
command-line will make ``parport`` use any IRQ lines or DMA channels that
86
83
it auto-detects.
87
84
88
85
89
86
Files in /proc
90
87
==============
91
88
92
-
If you have configured the /proc filesystem into your kernel, you will
93
-
see a new directory entry: /proc/sys/dev/parport. In there will be a
89
+
If you have configured the ``/proc`` filesystem into your kernel, you will
90
+
see a new directory entry: ``/proc/sys/dev/parport``. In there will be a
94
91
directory entry for each parallel port for which parport is
95
92
configured. In each of those directories are a collection of files
96
93
describing that parallel port.
97
94
98
-
The /proc/sys/dev/parport directory tree looks like:
95
+
The ``/proc/sys/dev/parport`` directory tree looks like::
99
96
100
-
parport
101
-
|-- default
102
-
| |-- spintime
103
-
| `-- timeslice
104
-
|-- parport0
105
-
| |-- autoprobe
106
-
| |-- autoprobe0
107
-
| |-- autoprobe1
108
-
| |-- autoprobe2
109
-
| |-- autoprobe3
110
-
| |-- devices
111
-
| | |-- active
112
-
| | `-- lp
113
-
| | `-- timeslice
114
-
| |-- base-addr
115
-
| |-- irq
116
-
| |-- dma
117
-
| |-- modes
118
-
| `-- spintime
119
-
`-- parport1
120
-
|-- autoprobe
121
-
|-- autoprobe0
122
-
|-- autoprobe1
123
-
|-- autoprobe2
124
-
|-- autoprobe3
125
-
|-- devices
126
-
| |-- active
127
-
| `-- ppa
128
-
| `-- timeslice
129
-
|-- base-addr
130
-
|-- irq
131
-
|-- dma
132
-
|-- modes
133
-
`-- spintime
97
+
parport
98
+
|-- default
99
+
| |-- spintime
100
+
| `-- timeslice
101
+
|-- parport0
102
+
| |-- autoprobe
103
+
| |-- autoprobe0
104
+
| |-- autoprobe1
105
+
| |-- autoprobe2
106
+
| |-- autoprobe3
107
+
| |-- devices
108
+
| | |-- active
109
+
| | `-- lp
110
+
| | `-- timeslice
111
+
| |-- base-addr
112
+
| |-- irq
113
+
| |-- dma
114
+
| |-- modes
115
+
| `-- spintime
116
+
`-- parport1
117
+
|-- autoprobe
118
+
|-- autoprobe0
119
+
|-- autoprobe1
120
+
|-- autoprobe2
121
+
|-- autoprobe3
122
+
|-- devices
123
+
| |-- active
124
+
| `-- ppa
125
+
| `-- timeslice
126
+
|-- base-addr
127
+
|-- irq
128
+
|-- dma
129
+
|-- modes
130
+
`-- spintime
134
131
132
+
======================= =======================================================
133
+
File Contents
134
+
======================= =======================================================
135
+
``devices/active`` A list of the device drivers using that port. A "+"
136
+
will appear by the name of the device currently using
137
+
the port (it might not appear against any). The
138
+
string "none" means that there are no device drivers
139
+
using that port.
135
140
136
-
File: Contents:
141
+
``base-addr`` Parallel port's base address, or addresses if the port
142
+
has more than one in which case they are separated
143
+
with tabs. These values might not have any sensible
144
+
meaning for some ports.
137
145
138
-
devices/active A list of the device drivers using that port. A "+"
139
-
will appear by the name of the device currently using
140
-
the port (it might not appear against any). The
141
-
string "none" means that there are no device drivers
142
-
using that port.
146
+
``irq`` Parallel port's IRQ, or -1 if none is being used.
143
147
144
-
base-addr Parallel port's base address, or addresses if the port
145
-
has more than one in which case they are separated
146
-
with tabs. These values might not have any sensible
147
-
meaning for some ports.
148
+
``dma`` Parallel port's DMA channel, or -1 if none is being
149
+
used.
148
150
149
-
irq Parallel port's IRQ, or -1 if none is being used.
151
+
``modes`` Parallel port's hardware modes, comma-separated,
152
+
meaning:
150
153
151
-
dma Parallel port's DMA channel, or -1 if none is being
152
-
used.
154
+
=============== =======================================
155
+
PCSPP PC-style SPP registers are available.
156
+
TRISTATE Port is bidirectional.
157
+
COMPAT Hardware acceleration for printers is
158
+
available and will be used.
159
+
EPP Hardware acceleration for EPP protocol
160
+
is available and will be used.
161
+
ECP Hardware acceleration for ECP protocol
162
+
is available and will be used.
163
+
DMA DMA is available and will be used.
164
+
=============== =======================================
153
165
154
-
modes Parallel port's hardware modes, comma-separated,
155
-
meaning:
166
+
Note that the current implementation will only take
167
+
advantage of COMPAT and ECP modes if it has an IRQ
168
+
line to use.
156
169
157
-
PCSPP PC-style SPP registers are available.
158
-
TRISTATE Port is bidirectional.
159
-
COMPAT Hardware acceleration for printers is
160
-
available and will be used.
161
-
EPP Hardware acceleration for EPP protocol
162
-
is available and will be used.
163
-
ECP Hardware acceleration for ECP protocol
164
-
is available and will be used.
165
-
DMA DMA is available and will be used.
170
+
``autoprobe`` Any IEEE-1284 device ID information that has been
171
+
acquired from the (non-IEEE 1284.3) device.
166
172
167
-
Note that the current implementation will only take
168
-
advantage of COMPAT and ECP modes if it has an IRQ
169
-
line to use.
173
+
``autoprobe[0-3]`` IEEE 1284 device ID information retrieved from
174
+
daisy-chain devices that conform to IEEE 1284.3.
170
175
171
-
autoprobe Any IEEE-1284 device ID information that has been
172
-
acquired from the (non-IEEE 1284.3) device.
176
+
``spintime`` The number of microseconds to busy-loop while waiting
177
+
for the peripheral to respond. You might find that
178
+
adjusting this improves performance, depending on your
179
+
peripherals. This is a port-wide setting, i.e. it
180
+
applies to all devices on a particular port.
173
181
174
-
autoprobe[0-3] IEEE 1284 device ID information retrieved from
175
-
daisy-chain devices that conform to IEEE 1284.3.
182
+
``timeslice`` The number of milliseconds that a device driver is
183
+
allowed to keep a port claimed for. This is advisory,
184
+
and driver can ignore it if it must.
176
185
177
-
spintime The number of microseconds to busy-loop while waiting
178
-
for the peripheral to respond. You might find that
179
-
adjusting this improves performance, depending on your
180
-
peripherals. This is a port-wide setting, i.e. it
181
-
applies to all devices on a particular port.
182
-
183
-
timeslice The number of milliseconds that a device driver is
184
-
allowed to keep a port claimed for. This is advisory,
185
-
and driver can ignore it if it must.
186
-
187
-
default/* The defaults for spintime and timeslice. When a new
188
-
port is registered, it picks up the default spintime.
189
-
When a new device is registered, it picks up the
190
-
default timeslice.
186
+
``default/*`` The defaults for spintime and timeslice. When a new
187
+
port is registered, it picks up the default spintime.
188
+
When a new device is registered, it picks up the
189
+
default timeslice.
190
+
======================= =======================================================
191
191
192
192
Device drivers
193
193
==============
···
199
193
specific ports. Normally this happens automatically; if the lp driver
200
194
is loaded it will create one lp device for each port found. You can
201
195
override this, though, by using parameters either when you load the lp
202
-
driver:
196
+
driver::
203
197
204
198
# insmod lp parport=0,2
205
199
206
-
or on the LILO command line:
200
+
or on the LILO command line::
207
201
208
202
lp=parport0 lp=parport2
209
203
210
-
Both the above examples would inform lp that you want /dev/lp0 to be
211
-
the first parallel port, and /dev/lp1 to be the _third_ parallel port,
204
+
Both the above examples would inform lp that you want ``/dev/lp0`` to be
205
+
the first parallel port, and /dev/lp1 to be the **third** parallel port,
212
206
with no lp device associated with the second port (parport1). Note
213
207
that this is different to the way older kernels worked; there used to
214
208
be a static association between the I/O port address and the device
215
-
name, so /dev/lp0 was always the port at 0x3bc. This is no longer the
216
-
case - if you only have one port, it will default to being /dev/lp0,
209
+
name, so ``/dev/lp0`` was always the port at 0x3bc. This is no longer the
210
+
case - if you only have one port, it will default to being ``/dev/lp0``,
217
211
regardless of base address.
218
212
219
213
Also:
220
214
221
215
* If you selected the IEEE 1284 support at compile time, you can say
222
-
`lp=auto' on the kernel command line, and lp will create devices
216
+
``lp=auto`` on the kernel command line, and lp will create devices
223
217
only for those ports that seem to have printers attached.
224
218
225
-
* If you give PLIP the `timid' parameter, either with `plip=timid' on
226
-
the command line, or with `insmod plip timid=1' when using modules,
219
+
* If you give PLIP the ``timid`` parameter, either with ``plip=timid`` on
220
+
the command line, or with ``insmod plip timid=1`` when using modules,
227
221
it will avoid any ports that seem to be in use by other devices.
228
222
229
223
* IRQ autoprobing works only for a few port types at the moment.
···
235
229
try to narrow down where the problem area is.
236
230
237
231
When reporting problems with parport, really you need to give all of
238
-
the messages that parport_pc spits out when it initialises. There are
232
+
the messages that ``parport_pc`` spits out when it initialises. There are
239
233
several code paths:
240
234
241
-
o polling
242
-
o interrupt-driven, protocol in software
243
-
o interrupt-driven, protocol in hardware using PIO
244
-
o interrupt-driven, protocol in hardware using DMA
235
+
- polling
236
+
- interrupt-driven, protocol in software
237
+
- interrupt-driven, protocol in hardware using PIO
238
+
- interrupt-driven, protocol in hardware using DMA
245
239
246
-
The kernel messages that parport_pc logs give an indication of which
240
+
The kernel messages that ``parport_pc`` logs give an indication of which
247
241
code path is being used. (They could be a lot better actually..)
248
242
249
243
For normal printer protocol, having IEEE 1284 modes enabled or not
250
244
should not make a difference.
251
245
252
246
To turn off the 'protocol in hardware' code paths, disable
253
-
CONFIG_PARPORT_PC_FIFO. Note that when they are enabled they are not
254
-
necessarily _used_; it depends on whether the hardware is available,
247
+
``CONFIG_PARPORT_PC_FIFO``. Note that when they are enabled they are not
248
+
necessarily **used**; it depends on whether the hardware is available,
255
249
enabled by the BIOS, and detected by the driver.
256
250
257
-
So, to start with, disable CONFIG_PARPORT_PC_FIFO, and load parport_pc
258
-
with 'irq=none'. See if printing works then. It really should,
251
+
So, to start with, disable ``CONFIG_PARPORT_PC_FIFO``, and load ``parport_pc``
252
+
with ``irq=none``. See if printing works then. It really should,
259
253
because this is the simplest code path.
260
254
261
-
If that works fine, try with 'io=0x378 irq=7' (adjust for your
255
+
If that works fine, try with ``io=0x378 irq=7`` (adjust for your
262
256
hardware), to make it use interrupt-driven in-software protocol.
263
257
264
-
If _that_ works fine, then one of the hardware modes isn't working
265
-
right. Enable CONFIG_PARPORT_PC_FIFO (no, it isn't a module option,
258
+
If **that** works fine, then one of the hardware modes isn't working
259
+
right. Enable ``CONFIG_FIFO`` (no, it isn't a module option,
266
260
and yes, it should be), set the port to ECP mode in the BIOS and note
267
-
the DMA channel, and try with:
261
+
the DMA channel, and try with::
268
262
269
263
io=0x378 irq=7 dma=none (for PIO)
270
264
io=0x378 irq=7 dma=3 (for DMA)
271
-
--
265
+
266
+
----------
267
+
272
268
philb@gnu.org
273
269
tim@cyberelk.net