[AGPGART] Replace kmalloc+memset's with kzalloc's
[linux-2.6.22.y-op.git] / Documentation / paride.txt
blobe4312676bdda71e997a8059b3e085e44ff209189
2                 Linux and parallel port IDE devices
4 PARIDE v1.03   (c) 1997-8  Grant Guenther <grant@torque.net>
6 1. Introduction
8 Owing to the simplicity and near universality of the parallel port interface
9 to personal computers, many external devices such as portable hard-disk,
10 CD-ROM, LS-120 and tape drives use the parallel port to connect to their
11 host computer.  While some devices (notably scanners) use ad-hoc methods
12 to pass commands and data through the parallel port interface, most 
13 external devices are actually identical to an internal model, but with
14 a parallel-port adapter chip added in.  Some of the original parallel port
15 adapters were little more than mechanisms for multiplexing a SCSI bus.
16 (The Iomega PPA-3 adapter used in the ZIP drives is an example of this
17 approach).  Most current designs, however, take a different approach.
18 The adapter chip reproduces a small ISA or IDE bus in the external device
19 and the communication protocol provides operations for reading and writing
20 device registers, as well as data block transfer functions.  Sometimes,
21 the device being addressed via the parallel cable is a standard SCSI
22 controller like an NCR 5380.  The "ditto" family of external tape
23 drives use the ISA replicator to interface a floppy disk controller,
24 which is then connected to a floppy-tape mechanism.  The vast majority
25 of external parallel port devices, however, are now based on standard
26 IDE type devices, which require no intermediate controller.  If one
27 were to open up a parallel port CD-ROM drive, for instance, one would
28 find a standard ATAPI CD-ROM drive, a power supply, and a single adapter
29 that interconnected a standard PC parallel port cable and a standard
30 IDE cable.  It is usually possible to exchange the CD-ROM device with
31 any other device using the IDE interface. 
33 The document describes the support in Linux for parallel port IDE
34 devices.  It does not cover parallel port SCSI devices, "ditto" tape
35 drives or scanners.  Many different devices are supported by the 
36 parallel port IDE subsystem, including:
38         MicroSolutions backpack CD-ROM
39         MicroSolutions backpack PD/CD
40         MicroSolutions backpack hard-drives
41         MicroSolutions backpack 8000t tape drive
42         SyQuest EZ-135, EZ-230 & SparQ drives
43         Avatar Shark
44         Imation Superdisk LS-120
45         Maxell Superdisk LS-120
46         FreeCom Power CD 
47         Hewlett-Packard 5GB and 8GB tape drives
48         Hewlett-Packard 7100 and 7200 CD-RW drives
50 as well as most of the clone and no-name products on the market.
52 To support such a wide range of devices, PARIDE, the parallel port IDE
53 subsystem, is actually structured in three parts.   There is a base
54 paride module which provides a registry and some common methods for
55 accessing the parallel ports.  The second component is a set of 
56 high-level drivers for each of the different types of supported devices: 
58         pd      IDE disk
59         pcd     ATAPI CD-ROM
60         pf      ATAPI disk
61         pt      ATAPI tape
62         pg      ATAPI generic
64 (Currently, the pg driver is only used with CD-R drives).
66 The high-level drivers function according to the relevant standards.
67 The third component of PARIDE is a set of low-level protocol drivers
68 for each of the parallel port IDE adapter chips.  Thanks to the interest
69 and encouragement of Linux users from many parts of the world, 
70 support is available for almost all known adapter protocols:
72         aten    ATEN EH-100                            (HK)
73         bpck    Microsolutions backpack                (US)
74         comm    DataStor (old-type) "commuter" adapter (TW)
75         dstr    DataStor EP-2000                       (TW)
76         epat    Shuttle EPAT                           (UK)
77         epia    Shuttle EPIA                           (UK)
78         fit2    FIT TD-2000                            (US)
79         fit3    FIT TD-3000                            (US)
80         friq    Freecom IQ cable                       (DE)
81         frpw    Freecom Power                          (DE)
82         kbic    KingByte KBIC-951A and KBIC-971A       (TW)
83         ktti    KT Technology PHd adapter              (SG)
84         on20    OnSpec 90c20                           (US)
85         on26    OnSpec 90c26                           (US)
88 2. Using the PARIDE subsystem
90 While configuring the Linux kernel, you may choose either to build
91 the PARIDE drivers into your kernel, or to build them as modules.
93 In either case, you will need to select "Parallel port IDE device support"
94 as well as at least one of the high-level drivers and at least one
95 of the parallel port communication protocols.  If you do not know
96 what kind of parallel port adapter is used in your drive, you could
97 begin by checking the file names and any text files on your DOS 
98 installation floppy.  Alternatively, you can look at the markings on
99 the adapter chip itself.  That's usually sufficient to identify the
100 correct device.  
102 You can actually select all the protocol modules, and allow the PARIDE
103 subsystem to try them all for you.
105 For the "brand-name" products listed above, here are the protocol
106 and high-level drivers that you would use:
108         Manufacturer            Model           Driver  Protocol
109         
110         MicroSolutions          CD-ROM          pcd     bpck
111         MicroSolutions          PD drive        pf      bpck
112         MicroSolutions          hard-drive      pd      bpck
113         MicroSolutions          8000t tape      pt      bpck
114         SyQuest                 EZ, SparQ       pd      epat
115         Imation                 Superdisk       pf      epat
116         Maxell                  Superdisk       pf      friq
117         Avatar                  Shark           pd      epat
118         FreeCom                 CD-ROM          pcd     frpw
119         Hewlett-Packard         5GB Tape        pt      epat
120         Hewlett-Packard         7200e (CD)      pcd     epat
121         Hewlett-Packard         7200e (CD-R)    pg      epat
123 2.1  Configuring built-in drivers
125 We recommend that you get to know how the drivers work and how to
126 configure them as loadable modules, before attempting to compile a
127 kernel with the drivers built-in.
129 If you built all of your PARIDE support directly into your kernel,
130 and you have just a single parallel port IDE device, your kernel should
131 locate it automatically for you.  If you have more than one device,
132 you may need to give some command line options to your bootloader
133 (eg: LILO), how to do that is beyond the scope of this document.
135 The high-level drivers accept a number of command line parameters, all
136 of which are documented in the source files in linux/drivers/block/paride.
137 By default, each driver will automatically try all parallel ports it
138 can find, and all protocol types that have been installed, until it finds
139 a parallel port IDE adapter.  Once it finds one, the probe stops.  So,
140 if you have more than one device, you will need to tell the drivers
141 how to identify them.  This requires specifying the port address, the
142 protocol identification number and, for some devices, the drive's
143 chain ID.  While your system is booting, a number of messages are
144 displayed on the console.  Like all such messages, they can be
145 reviewed with the 'dmesg' command.  Among those messages will be
146 some lines like:
148         paride: bpck registered as protocol 0
149         paride: epat registered as protocol 1
151 The numbers will always be the same until you build a new kernel with
152 different protocol selections.  You should note these numbers as you
153 will need them to identify the devices.
155 If you happen to be using a MicroSolutions backpack device, you will
156 also need to know the unit ID number for each drive.  This is usually
157 the last two digits of the drive's serial number (but read MicroSolutions'
158 documentation about this).
160 As an example, let's assume that you have a MicroSolutions PD/CD drive
161 with unit ID number 36 connected to the parallel port at 0x378, a SyQuest 
162 EZ-135 connected to the chained port on the PD/CD drive and also an 
163 Imation Superdisk connected to port 0x278.  You could give the following 
164 options on your boot command:
166         pd.drive0=0x378,1 pf.drive0=0x278,1 pf.drive1=0x378,0,36
168 In the last option, pf.drive1 configures device /dev/pf1, the 0x378
169 is the parallel port base address, the 0 is the protocol registration
170 number and 36 is the chain ID.
172 Please note:  while PARIDE will work both with and without the 
173 PARPORT parallel port sharing system that is included by the
174 "Parallel port support" option, PARPORT must be included and enabled
175 if you want to use chains of devices on the same parallel port.
177 2.2  Loading and configuring PARIDE as modules
179 It is much faster and simpler to get to understand the PARIDE drivers
180 if you use them as loadable kernel modules.   
182 Note 1:  using these drivers with the "kerneld" automatic module loading
183 system is not recommended for beginners, and is not documented here.  
185 Note 2:  if you build PARPORT support as a loadable module, PARIDE must
186 also be built as loadable modules, and PARPORT must be loaded before the
187 PARIDE modules.
189 To use PARIDE, you must begin by 
191         insmod paride
193 this loads a base module which provides a registry for the protocols,
194 among other tasks.
196 Then, load as many of the protocol modules as you think you might need.
197 As you load each module, it will register the protocols that it supports,
198 and print a log message to your kernel log file and your console. For 
199 example:
201         # insmod epat
202         paride: epat registered as protocol 0
203         # insmod kbic
204         paride: k951 registered as protocol 1
205         paride: k971 registered as protocol 2
207 Finally, you can load high-level drivers for each kind of device that
208 you have connected.  By default, each driver will autoprobe for a single 
209 device, but you can support up to four similar devices by giving their
210 individual co-ordinates when you load the driver.
212 For example, if you had two no-name CD-ROM drives both using the
213 KingByte KBIC-951A adapter, one on port 0x378 and the other on 0x3bc
214 you could give the following command:
216         # insmod pcd drive0=0x378,1 drive1=0x3bc,1
218 For most adapters, giving a port address and protocol number is sufficient,
219 but check the source files in linux/drivers/block/paride for more 
220 information.  (Hopefully someone will write some man pages one day !).
222 As another example, here's what happens when PARPORT is installed, and
223 a SyQuest EZ-135 is attached to port 0x378:
225         # insmod paride
226         paride: version 1.0 installed
227         # insmod epat
228         paride: epat registered as protocol 0
229         # insmod pd
230         pd: pd version 1.0, major 45, cluster 64, nice 0
231         pda: Sharing parport1 at 0x378
232         pda: epat 1.0, Shuttle EPAT chip c3 at 0x378, mode 5 (EPP-32), delay 1
233         pda: SyQuest EZ135A, 262144 blocks [128M], (512/16/32), removable media
234          pda: pda1
236 Note that the last line is the output from the generic partition table
237 scanner - in this case it reports that it has found a disk with one partition.
239 2.3  Using a PARIDE device
241 Once the drivers have been loaded, you can access PARIDE devices in the
242 same way as their traditional counterparts.  You will probably need to
243 create the device "special files".  Here is a simple script that you can
244 cut to a file and execute:
246 #!/bin/bash
248 # mkd -- a script to create the device special files for the PARIDE subsystem
250 function mkdev {
251   mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1
254 function pd {
255   D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) )
256   mkdev pd$D b 45 $[ $1 * 16 ]
257   for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
258   do mkdev pd$D$P b 45 $[ $1 * 16 + $P ]
259   done
262 cd /dev
264 for u in 0 1 2 3 ; do pd $u ; done
265 for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done 
266 for u in 0 1 2 3 ; do mkdev pf$u  b 47 $u ; done 
267 for u in 0 1 2 3 ; do mkdev pt$u  c 96 $u ; done 
268 for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done 
269 for u in 0 1 2 3 ; do mkdev pg$u  c 97 $u ; done 
271 # end of mkd
273 With the device files and drivers in place, you can access PARIDE devices
274 like any other Linux device.   For example, to mount a CD-ROM in pcd0, use:
276         mount /dev/pcd0 /cdrom
278 If you have a fresh Avatar Shark cartridge, and the drive is pda, you
279 might do something like:
281         fdisk /dev/pda          -- make a new partition table with
282                                    partition 1 of type 83
284         mke2fs /dev/pda1        -- to build the file system
286         mkdir /shark            -- make a place to mount the disk
288         mount /dev/pda1 /shark
290 Devices like the Imation superdisk work in the same way, except that
291 they do not have a partition table.  For example to make a 120MB
292 floppy that you could share with a DOS system:
294         mkdosfs /dev/pf0
295         mount /dev/pf0 /mnt
298 2.4  The pf driver
300 The pf driver is intended for use with parallel port ATAPI disk
301 devices.  The most common devices in this category are PD drives
302 and LS-120 drives.  Traditionally, media for these devices are not
303 partitioned.  Consequently, the pf driver does not support partitioned
304 media.  This may be changed in a future version of the driver. 
306 2.5  Using the pt driver
308 The pt driver for parallel port ATAPI tape drives is a minimal driver.
309 It does not yet support many of the standard tape ioctl operations. 
310 For best performance, a block size of 32KB should be used.  You will
311 probably want to set the parallel port delay to 0, if you can.
313 2.6  Using the pg driver
315 The pg driver can be used in conjunction with the cdrecord program
316 to create CD-ROMs.  Please get cdrecord version 1.6.1 or later
317 from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ .  To record CD-R media 
318 your parallel port should ideally be set to EPP mode, and the "port delay" 
319 should be set to 0.  With those settings it is possible to record at 2x 
320 speed without any buffer underruns.  If you cannot get the driver to work
321 in EPP mode, try to use "bidirectional" or "PS/2" mode and 1x speeds only.
324 3. Troubleshooting
326 3.1  Use EPP mode if you can
328 The most common problems that people report with the PARIDE drivers
329 concern the parallel port CMOS settings.  At this time, none of the
330 PARIDE protocol modules support ECP mode, or any ECP combination modes.
331 If you are able to do so, please set your parallel port into EPP mode
332 using your CMOS setup procedure.
334 3.2  Check the port delay
336 Some parallel ports cannot reliably transfer data at full speed.  To
337 offset the errors, the PARIDE protocol modules introduce a "port
338 delay" between each access to the i/o ports.  Each protocol sets
339 a default value for this delay.  In most cases, the user can override
340 the default and set it to 0 - resulting in somewhat higher transfer
341 rates.  In some rare cases (especially with older 486 systems) the
342 default delays are not long enough.  if you experience corrupt data
343 transfers, or unexpected failures, you may wish to increase the
344 port delay.   The delay can be programmed using the "driveN" parameters
345 to each of the high-level drivers.  Please see the notes above, or
346 read the comments at the beginning of the driver source files in
347 linux/drivers/block/paride.
349 3.3  Some drives need a printer reset
351 There appear to be a number of "noname" external drives on the market
352 that do not always power up correctly.  We have noticed this with some
353 drives based on OnSpec and older Freecom adapters.  In these rare cases,
354 the adapter can often be reinitialised by issuing a "printer reset" on
355 the parallel port.  As the reset operation is potentially disruptive in 
356 multiple device environments, the PARIDE drivers will not do it 
357 automatically.  You can however, force a printer reset by doing:
359         insmod lp reset=1
360         rmmod lp
362 If you have one of these marginal cases, you should probably build
363 your paride drivers as modules, and arrange to do the printer reset
364 before loading the PARIDE drivers. 
366 3.4  Use the verbose option and dmesg if you need help
368 While a lot of testing has gone into these drivers to make them work
369 as smoothly as possible, problems will arise.  If you do have problems,
370 please check all the obvious things first:  does the drive work in
371 DOS with the manufacturer's drivers ?  If that doesn't yield any useful
372 clues, then please make sure that only one drive is hooked to your system,
373 and that either (a) PARPORT is enabled or (b) no other device driver
374 is using your parallel port (check in /proc/ioports).  Then, load the
375 appropriate drivers (you can load several protocol modules if you want)
376 as in:
378         # insmod paride
379         # insmod epat
380         # insmod bpck
381         # insmod kbic
382         ...
383         # insmod pd verbose=1
385 (using the correct driver for the type of device you have, of course).
386 The verbose=1 parameter will cause the drivers to log a trace of their
387 activity as they attempt to locate your drive.
389 Use 'dmesg' to capture a log of all the PARIDE messages (any messages
390 beginning with paride:, a protocol module's name or a driver's name) and
391 include that with your bug report.  You can submit a bug report in one
392 of two ways.  Either send it directly to the author of the PARIDE suite,
393 by e-mail to grant@torque.net, or join the linux-parport mailing list
394 and post your report there.
396 3.5  For more information or help
398 You can join the linux-parport mailing list by sending a mail message
399 to 
400                 linux-parport-request@torque.net
402 with the single word 
404                 subscribe
406 in the body of the mail message (not in the subject line).   Please be
407 sure that your mail program is correctly set up when you do this,  as
408 the list manager is a robot that will subscribe you using the reply
409 address in your mail headers.  REMOVE any anti-spam gimmicks you may
410 have in your mail headers, when sending mail to the list server.
412 You might also find some useful information on the linux-parport
413 web pages (although they are not always up to date) at
415         http://www.torque.net/parport/