aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/cdrom
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/cdrom')
-rw-r--r--Documentation/cdrom/00-INDEX33
-rw-r--r--Documentation/cdrom/Makefile21
-rw-r--r--Documentation/cdrom/aztcd822
-rw-r--r--Documentation/cdrom/cdrom-standard.tex1022
-rw-r--r--Documentation/cdrom/cdu31a196
-rw-r--r--Documentation/cdrom/cm206185
-rw-r--r--Documentation/cdrom/gscd60
-rw-r--r--Documentation/cdrom/ide-cd574
-rw-r--r--Documentation/cdrom/isp16100
-rw-r--r--Documentation/cdrom/mcdx29
-rw-r--r--Documentation/cdrom/optcd57
-rw-r--r--Documentation/cdrom/packet-writing.txt97
-rw-r--r--Documentation/cdrom/sbpcd1057
-rw-r--r--Documentation/cdrom/sjcd60
-rw-r--r--Documentation/cdrom/sonycd535121
15 files changed, 4434 insertions, 0 deletions
diff --git a/Documentation/cdrom/00-INDEX b/Documentation/cdrom/00-INDEX
new file mode 100644
index 000000000000..916dafe29d3f
--- /dev/null
+++ b/Documentation/cdrom/00-INDEX
@@ -0,0 +1,33 @@
100-INDEX
2 - this file (info on CD-ROMs and Linux)
3Makefile
4 - only used to generate TeX output from the documentation.
5aztcd
6 - info on Aztech/Orchid/Okano/Wearnes/Conrad/CyCDROM driver.
7cdrom-standard.tex
8 - LaTeX document on standardizing the CD-ROM programming interface.
9cdu31a
10 - info on the Sony CDU31A/CDU33A CD-ROM driver.
11cm206
12 - info on the Philips/LMS cm206/cm260 CD-ROM driver.
13gscd
14 - info on the Goldstar R420 CD-ROM driver.
15ide-cd
16 - info on setting up and using ATAPI (aka IDE) CD-ROMs.
17isp16
18 - info on the CD-ROM interface on ISP16, MAD16 or Mozart sound card.
19mcd
20 - info on limitations of standard Mitsumi CD-ROM driver.
21mcdx
22 - info on improved Mitsumi CD-ROM driver.
23optcd
24 - info on the Optics Storage 8000 AT CD-ROM driver
25packet-writing.txt
26 - Info on the CDRW packet writing module
27sbpcd
28 - info on the SoundBlaster/Panasonic CD-ROM interface driver.
29sjcd
30 - info on the SANYO CDR-H94A CD-ROM interface driver.
31sonycd535
32 - info on the Sony CDU-535 (and 531) CD-ROM driver.
33
diff --git a/Documentation/cdrom/Makefile b/Documentation/cdrom/Makefile
new file mode 100644
index 000000000000..a19e321928e1
--- /dev/null
+++ b/Documentation/cdrom/Makefile
@@ -0,0 +1,21 @@
1LATEXFILE = cdrom-standard
2
3all:
4 make clean
5 latex $(LATEXFILE)
6 latex $(LATEXFILE)
7 @if [ -x `which gv` ]; then \
8 `dvips -q -t letter -o $(LATEXFILE).ps $(LATEXFILE).dvi` ;\
9 `gv -antialias -media letter -nocenter $(LATEXFILE).ps` ;\
10 else \
11 `xdvi $(LATEXFILE).dvi &` ;\
12 fi
13 make sortofclean
14
15clean:
16 rm -f $(LATEXFILE).ps $(LATEXFILE).dvi $(LATEXFILE).aux $(LATEXFILE).log
17
18sortofclean:
19 rm -f $(LATEXFILE).aux $(LATEXFILE).log
20
21
diff --git a/Documentation/cdrom/aztcd b/Documentation/cdrom/aztcd
new file mode 100644
index 000000000000..6bf0290ef7ce
--- /dev/null
+++ b/Documentation/cdrom/aztcd
@@ -0,0 +1,822 @@
1$Id: README.aztcd,v 2.60 1997/11/29 09:51:25 root Exp root $
2 Readme-File Documentation/cdrom/aztcd
3 for
4 AZTECH CD-ROM CDA268-01A, ORCHID CD-3110,
5 OKANO/WEARNES CDD110, CONRAD TXC, CyCDROM CR520, CR540
6 CD-ROM Drives
7 Version 2.6 and newer
8 (for other drives see 6.-8.)
9
10NOTE: THIS DRIVER WILL WORK WITH THE CD-ROM DRIVES LISTED, WHICH HAVE
11 A PROPRIETARY INTERFACE (implemented on a sound card or on an
12 ISA-AT-bus card).
13 IT WILL DEFINITELY NOT WORK WITH CD-ROM DRIVES WITH *IDE*-INTERFACE,
14 such as the Aztech CDA269-031SE !!! (The only known exceptions are
15 'faked' IDE drives like the CyCDROM CR520ie which work with aztcd
16 under certain conditions, see 7.). IF YOU'RE USING A CD-ROM DRIVE
17 WITH IDE-INTERFACE, SOMETIMES ALSO CALLED ATAPI-COMPATIBLE, PLEASE
18 USE THE ide-cd.c DRIVER, WRITTEN BY MARK LORD AND SCOTT SNYDER !
19 THE STANDARD-KERNEL 1.2.x NOW ALSO SUPPORTS IDE-CDROM-DRIVES, SEE THE
20 HARDDISK (!) SECTION OF make config, WHEN COMPILING A NEW KERNEL!!!
21----------------------------------------------------------------------------
22
23Contents of this file:
24 1. NOTE
25 2. INSTALLATION
26 3. CONFIGURING YOUR KERNEL
27 4. RECOMPILING YOUR KERNEL
28 4.1 AZTCD AS A RUN-TIME LOADABLE MODULE
29 4.2 CDROM CONNECTED TO A SOUNDCARD
30 5. KNOWN PROBLEMS, FUTURE DEVELOPMENTS
31 5.1 MULTISESSION SUPPORT
32 5.2 STATUS RECOGNITION
33 5.3 DOSEMU's CDROM SUPPORT
34 6. BUG REPORTS
35 7. OTHER DRIVES
36 8. IF YOU DON'T SUCCEED ... DEBUGGING
37 9. TECHNICAL HISTORY OF THE DRIVER
38 10. ACKNOWLEDGMENTS
39 11. PROGRAMMING ADD ONS: CDPLAY.C
40 APPENDIX: Source code of cdplay.c
41----------------------------------------------------------------------------
42
431. NOTE
44This software has been successfully in alpha and beta test and is part of
45the standard kernel since kernel 1.1.8x since December 1994. It works with
46AZTECH CDA268-01A, ORCHID CDS-3110, ORCHID/WEARNES CDD110 and CONRAD TXC
47(Nr.99 31 23 -series 04) and has proven to be stable with kernel
48versions 1.0.9 and newer. But with any software there still may be bugs in it.
49So if you encounter problems, you are invited to help us improve this software.
50Please send me a detailed bug report (see chapter BUG REPORTS). You are also
51invited in helping us to increase the number of drives, which are supported.
52
53Please read the README-files carefully and always keep a backup copy of your
54old kernel, in order to reboot if something goes wrong!
55
562. INSTALLATION
57The driver consists of a header file 'aztcd.h', which normally should reside
58in /usr/src/linux/drivers/cdrom and the source code 'aztcd.c', which normally
59resides in the same place. It uses /dev/aztcd (/dev/aztcd0 in some distri-
60butions), which must be a valid block device with major number 29 and reside
61in directory /dev. To mount a CD-ROM, your kernel needs to have the ISO9660-
62filesystem support included.
63
64PLEASE NOTE: aztcd.c has been developed in parallel to the linux kernel,
65which had and is having many major and minor changes which are not backward
66compatible. Quite definitely aztcd.c version 1.80 and newer will NOT work
67in kernels older than 1.3.33. So please always use the most recent version
68of aztcd.c with the appropriate linux-kernel.
69
703. CONFIGURING YOUR KERNEL
71If your kernel is already configured for using the AZTECH driver you will
72see the following message while Linux boots:
73 Aztech CD-ROM Init: DriverVersion=<version number> BaseAddress=<baseaddress>
74 Aztech CD-ROM Init: FirmwareVersion=<firmware version id of your I/O-card>>>
75 Aztech CD-ROM Init: <drive type> detected
76 Aztech CD-ROM Init: End
77If the message looks different and you are sure to have a supported drive,
78it may have a different base address. The Aztech driver does look for the
79CD-ROM drive at the base address specified in aztcd.h at compile time. This
80address can be overwritten by boot parameter aztcd=....You should reboot and
81start Linux with boot parameter aztcd=<base address>, e.g. aztcd=0x320. If
82you do not know the base address, start your PC with DOS and look at the boot
83message of your CD-ROM's DOS driver. If that still does not help, use boot
84parameter aztcd=<base address>,0x79 , this tells aztcd to try a little harder.
85aztcd may be configured to use autoprobing the base address by recompiling
86it (see chapter 4.).
87
88If the message looks correct, as user 'root' you should be able to mount the
89drive by
90 mount -t iso9660 -r /dev/aztcd0 /mnt
91and use it as any other filesystem. (If this does not work, check if
92/dev/aztcd0 and /mnt do exist and create them, if necessary by doing
93 mknod /dev/aztcd0 b 29 0
94 mkdir /mnt
95
96If you still get a different message while Linux boots or when you get the
97message, that the ISO9660-filesystem is not supported by your kernel, when
98you try to mount the CD-ROM drive, you have to recompile your kernel.
99
100If you do *not* have an Aztech/Orchid/Okano/Wearnes/TXC drive and want to
101bypass drive detection during Linux boot up, start with boot parameter aztcd=0.
102
103Most distributions nowadays do contain a boot disk image containing aztcd.
104Please note, that this driver will not work with IDE/ATAPI drives! With these
105you must use ide-cd.c instead.
106
1074. RECOMPILING YOUR KERNEL
108If your kernel is not yet configured for the AZTECH driver and the ISO9660-
109filesystem, you have to recompile your kernel:
110
111- Edit aztcd.h to set the I/O-address to your I/O-Base address (AZT_BASE_ADDR),
112 the driver does not use interrupts or DMA, so if you are using an AZTECH
113 CD268, an ORCHID CD-3110 or ORCHID/WEARNES CDD110 that's the only item you
114 have to set up. If you have a soundcard, read chapter 4.2.
115 Users of other drives should read chapter OTHER DRIVES of this file.
116 You also can configure that address by kernel boot parameter aztcd=...
117- aztcd may be configured to use autoprobing the base address by setting
118 AZT_BASE_ADDR to '-1'. In that case aztcd probes the addresses listed
119 under AZT_BASE_AUTO. But please remember, that autoprobing always may
120 incorrectly influence other hardware components too!
121- There are some other points, which may be configured, e.g. auto-eject the
122 CD when unmounting a drive, tray locking etc., see aztcd.h for details.
123- If you're using a linux kernel version prior to 2.1.0, in aztcd.h
124 uncomment the line '#define AZT_KERNEL_PRIOR_2_1'
125- Build a new kernel, configure it for 'Aztech/Orchid/Okano/Wearnes support'
126 (if you want aztcd to be part of the kernel). Do not configure it for
127 'Aztech... support', if you want to use aztcd as a run time loadable module.
128 But in any case you must have the ISO9660-filesystem included in your
129 kernel.
130- Activate the new kernel, normally this is done by running LILO (don't for-
131 get to configure it before and to keep a copy of your old kernel in case
132 something goes wrong!).
133- Reboot
134- If you've included aztcd in your kernel, you now should see during boot
135 some messages like
136 Aztech CD-ROM Init: DriverVersion=<version number> BaseAddress=<baseaddress>
137 Aztech CD-ROM Init: FirmwareVersion=<firmware version id of your I/O-card>
138 Aztech CD-ROM Init: <drive type> detected
139 Aztech CD-ROM Init: End
140- If you have not included aztcd in your kernel, but want to load aztcd as a
141 run time loadable module see 4.1.
142- If the message looks correct, as user 'root' you should be able to mount
143 the drive by
144 mount -t iso9660 -r /dev/aztcd0 /mnt
145 and use it as any other filesystem. (If this does not work, check if
146 /dev/aztcd0 and /mnt do exist and create them, if necessary by doing
147 mknod /dev/aztcd0 b 29 0
148 mkdir /mnt
149- If this still does not help, see chapters OTHER DRIVES and DEBUGGING.
150
1514.1 AZTCD AS A RUN-TIME LOADABLE MODULE
152If you do not need aztcd permanently, you can also load and remove the driver
153during runtime via insmod and rmmod. To build aztcd as a loadable module you
154must configure your kernel for AZTECH module support (answer 'm' when con-
155figuring the kernel). Anyhow, you may run into problems, if the version of
156your boot kernel is not the same than the source kernel version, from which
157you create the modules. So rebuild your kernel, if necessary.
158
159Now edit the base address of your AZTECH interface card in
160/usr/src/linux/drivers/cdrom/aztcd.h to the appropriate value.
161aztcd may be configured to use autoprobing the base address by setting
162AZT_BASE_ADDR to '-1'. In that case aztcd probes the addresses listed
163under AZT_BASE_AUTO. But please remember, that autoprobing always may
164incorrectly influence other hardware components too!
165There are also some special features which may be configured, e.g.
166auto-eject a CD when unmounting the drive etc; see aztcd.h for details.
167Then change to /usr/src/linux and do a
168 make modules
169 make modules_install
170After that you can run-time load the driver via
171 insmod /lib/modules/X.X.X/misc/aztcd.o
172and remove it via rmmod aztcd.
173If you did not set the correct base address in aztcd.h, you can also supply the
174base address when loading the driver via
175 insmod /lib/modules/X.X.X/misc/aztcd.o aztcd=<base address>
176Again specifying aztcd=-1 will cause autoprobing.
177If you do not have the iso9660-filesystem in your boot kernel, you also have
178to load it before you can mount the CDROM:
179 insmod /lib/modules/X.X.X/fs/isofs.o
180The mount procedure works as described in 4. above.
181(In all commands 'X.X.X' is the current linux kernel version number)
182
1834.2 CDROM CONNECTED TO A SOUNDCARD
184Most soundcards do have a bus interface to the CDROM-drive. In many cases
185this soundcard needs to be configured, before the CDROM can be used. This
186configuration procedure consists of writing some kind of initialization
187data to the soundcard registers. The AZTECH-CDROM driver in the moment does
188only support one type of soundcard (SoundWave32). Users of other soundcards
189should try to boot DOS first and let their DOS drivers initialize the
190soundcard and CDROM, then warm boot (or use loadlin) their PC to start
191Linux.
192Support for the CDROM-interface of SoundWave32-soundcards is directly
193implemented in the AZTECH driver. Please edit linux/drivers/cdrom/aztdc.h,
194uncomment line '#define AZT_SW32' and set the appropriate value for
195AZT_BASE_ADDR and AZT_SW32_BASE_ADDR. This support was tested with an Orchid
196CDS-3110 connected to a SoundWave32.
197If you want your soundcard to be supported, find out, how it needs to be
198configured and mail me (see 6.) the appropriate information.
199
2005. KNOWN PROBLEMS, FUTURE DEVELOPMENTS
2015.1 MULTISESSION SUPPORT
202Multisession support for CD's still is a myth. I implemented and tested a basic
203support for multisession and XA CDs, but I still have not enough CDs and appli-
204cations to test it rigorously. So if you'd like to help me, please contact me
205(Email address see below). As of version 1.4 and newer you can enable the
206multisession support in aztcd.h by setting AZT_MULTISESSION to 1. Doing so
207will cause the ISO9660-filesystem to deal with multisession CDs, ie. redirect
208requests to the Table of Contents (TOC) information from the last session,
209which contains the info of all previous sessions etc.. If you do set
210AZT_MULTISESSION to 0, you can use multisession CDs anyway. In that case the
211drive's firmware will do automatic redirection. For the ISO9660-filesystem any
212multisession CD will then look like a 'normal' single session CD. But never-
213theless the data of all sessions are viewable and accessible. So with practical-
214ly all real world applications you won't notice the difference. But as future
215applications may make use of advanced multisession features, I've started to
216implement the interface for the ISO9660 multisession interface via ioctl
217CDROMMULTISESSION.
218
2195.2 STATUS RECOGNITION
220The drive status recognition does not work correctly in all cases. Changing
221a disk or having the door open, when a drive is already mounted, is detected
222by the Aztech driver itself, but nevertheless causes multiple read attempts
223by the different layers of the ISO9660-filesystem driver, which finally timeout,
224so you have to wait quite a little... But isn't it bad style to change a disk
225in a mounted drive, anyhow ?!
226
227The driver uses busy wait in most cases for the drive handshake (macros
228STEN_LOW and DTEN_LOW). I tested with a 486/DX2 at 66MHz and a Pentium at
22960MHz and 90MHz. Whenever you use a much faster machine you are likely to get
230timeout messages. In that case edit aztcd.h and increase the timeout value
231AZT_TIMEOUT.
232
233For some 'slow' drive commands I implemented waiting with a timer waitqueue
234(macro STEN_LOW_WAIT). If you get this timeout message, you may also edit
235aztcd.h and increase the timeout value AZT_STATUS_DELAY. The waitqueue has
236shown to be a little critical. If you get kernel panic messages, edit aztcd.c
237and substitute STEN_LOW_WAIT by STEN_LOW. Busy waiting with STEN_LOW is more
238stable, but also causes CPU overhead.
239
2405.3 DOSEMU's CD-ROM SUPPORT
241With release 1.20 aztcd was modified to allow access to CD-ROMS when running
242under dosemu-0.60.0 aztcd-versions before 1.20 are most likely to crash
243Linux, when a CD-ROM is accessed under dosemu. This problem has partly been
244fixed, but still when accessing a directory for the first time the system
245might hang for some 30sec. So be patient, when using dosemu's CD-ROM support
246in combination with aztcd :-) !
247This problem has now (July 1995) been fixed by a modification to dosemu's
248CD-ROM driver. The new version came with dosemu-0.60.2, see dosemu's
249README.CDROM.
250
2516. BUG REPORTS
252Please send detailed bug reports and bug fixes via EMail to
253
254 Werner.Zimmermann@fht-esslingen.de
255
256Please include a description of your CD-ROM drive type and interface card,
257the exact firmware message during Linux bootup, the version number of the
258AZTECH-CDROM-driver and the Linux kernel version. Also a description of your
259system's other hardware could be of interest, especially microprocessor type,
260clock frequency, other interface cards such as soundcards, ethernet adapter,
261game cards etc..
262
263I will try to collect the reports and make the necessary modifications from
264time to time. I may also come back to you directly with some bug fixes and
265ask you to do further testing and debugging.
266
267Editors of CD-ROMs are invited to send a 'cooperation' copy of their
268CD-ROMs to the volunteers, who provided the CD-ROM support for Linux. My
269snail mail address for such 'stuff' is
270 Prof. Dr. W. Zimmermann
271 Fachhochschule fuer Technik Esslingen
272 Fachbereich IT
273 Flandernstrasse 101
274 D-73732 Esslingen
275 Germany
276
277
2787. OTHER DRIVES
279The following drives ORCHID CDS3110, OKANO CDD110, WEARNES CDD110 and Conrad
280TXC Nr. 993123-series 04 nearly look the same as AZTECH CDA268-01A, especially
281they seem to use the same command codes. So it was quite simple to make the
282AZTECH driver work with these drives.
283
284Unfortunately I do not have any of these drives available, so I couldn't test
285it myself. In some installations, it seems necessary to initialize the drive
286with the DOS driver before (especially if combined with a sound card) and then
287do a warm boot (CTRL-ALT-RESET) or start Linux from DOS, e.g. with 'loadlin'.
288
289If you do not succeed, read chapter DEBUGGING. Thanks in advance!
290
291Sorry for the inconvenience, but it is difficult to develop for hardware,
292which you don't have available for testing. So if you like, please help us.
293
294If you do have a CyCDROM CR520ie thanks to Hilmar Berger's help your chances
295are good, that it will work with aztcd. The CR520ie is sold as an IDE-drive
296and really is connected to the IDE interface (primary at 0x1F0 or secondary
297at 0x170, configured as slave, not as master). Nevertheless it is not ATAPI
298compatible but still uses Aztech's command codes.
299
300
3018. DEBUGGING : IF YOU DON'T SUCCEED, TRY THE FOLLOWING
302-reread the complete README file
303-make sure, that your drive is hardware configured for
304 transfer mode: polled
305 IRQ: not used
306 DMA: not used
307 Base Address: something like 300, 320 ...
308 You can check this, when you start the DOS driver, which came with your
309 drive. By appropriately configuring the drive and the DOS driver you can
310 check, whether your drive does operate in this mode correctly under DOS. If
311 it does not operate under DOS, it won't under Linux.
312 If your drive's base address is something like 0x170 or 0x1F0 (and it is
313 not a CyCDROM CR520ie or CR 940ie) you most likely are having an IDE/ATAPI-
314 compatible drive, which is not supported by aztcd.c, use ide-cd.c instead.
315 Make sure the Base Address is configured correctly in aztcd.h, also make
316 sure, that /dev/aztcd0 exists with the correct major number (compare it with
317 the entry in file /usr/include/linux/major.h for the Aztech drive).
318-insert a CD-ROM and close the tray
319-cold boot your PC (i.e. via the power on switch or the reset button)
320-if you start Linux via DOS, e.g. using loadlin, make sure, that the DOS
321 driver for the CD-ROM drive is not loaded (comment out the calling lines
322 in DOS' config.sys!)
323-look for the aztcd: init message during Linux init and note them exactly
324-log in as root and do a mount -t iso9660 /dev/aztcd0 /mnt
325-if you don't succeed in the first time, try several times. Try also to open
326 and close the tray, then mount again. Please note carefully all commands
327 you typed in and the aztcd-messages, which you get.
328-if you get an 'Aztech CD-ROM init: aborted' message, read the remarks about
329 the version string below.
330
331If this does not help, do the same with the following differences
332-start DOS before; make now sure, that the DOS driver for the CD-ROM is
333 loaded under DOS (i.e. uncomment it again in config.sys)
334-warm boot your PC (i.e. via CTRL-ALT-DEL)
335 if you have it, you can also start via loadlin (try both).
336 ...
337 Again note all commands and the aztcd-messages.
338
339If you see STEN_LOW or STEN_LOW_WAIT error messages, increase the timeout
340values.
341
342If this still does not help,
343-look in aztcd.c for the lines #if 0
344 #define AZT_TEST1
345 ...
346 #endif
347 and substitute '#if 0' by '#if 1'.
348-recompile your kernel and repeat the above two procedures. You will now get
349 a bundle of debugging messages from the driver. Again note your commands
350 and the appropriate messages. If you have syslogd running, these messages
351 may also be found in syslogd's kernel log file. Nevertheless in some
352 installations syslogd does not yet run, when init() is called, thus look for
353 the aztcd-messages during init, before the login-prompt appears.
354 Then look in aztcd.c, to find out, what happened. The normal calling sequence
355 is: aztcd_init() during Linux bootup procedure init()
356 after doing a 'mount -t iso9660 /dev/aztcd0 /mnt' the normal calling sequence is
357 aztcd_open() -> Status 2c after cold reboot with CDROM or audio CD inserted
358 -> Status 8 after warm reboot with CDROM inserted
359 -> Status 2e after cold reboot with no disk, closed tray
360 -> Status 6e after cold reboot, mount with door open
361 aztUpdateToc()
362 aztGetDiskInfo()
363 aztGetQChannelInfo() repeated several times
364 aztGetToc()
365 aztGetQChannelInfo() repeated several times
366 a list of track information
367 do_aztcd_request() }
368 azt_transfer() } repeated several times
369 azt_poll }
370 Check, if there is a difference in the calling sequence or the status flags!
371
372 There are a lot of other messages, eg. the ACMD-command code (defined in
373 aztcd.h), status info from the getAztStatus-command and the state sequence of
374 the finite state machine in azt_poll(). The most important are the status
375 messages, look how they are defined and try to understand, if they make
376 sense in the context where they appear. With a CD-ROM inserted the status
377 should always be 8, except in aztcd_open(). Try to open the tray, insert an
378 audio disk, insert no disk or reinsert the CD-ROM and check, if the status
379 bits change accordingly. The status bits are the most likely point, where
380 the drive manufacturers may implement changes.
381
382If you still don't succeed, a good point to start is to look in aztcd.c in
383function aztcd_init, where the drive should be detected during init. Do the
384following:
385-reboot the system with boot parameter 'aztcd=<your base address>,0x79'. With
386 parameter 0x79 most of the drive version detection is bypassed. After that
387 you should see the complete version string including leading and trailing
388 blanks during init.
389 Now adapt the statement
390 if ((result[1]=='A')&&(result[2]=='Z' ...)
391 in aztcd_init() to exactly match the first 3 or 4 letters you have seen.
392-Another point is the 'smart' card detection feature in aztcd_init(). Normally
393 the CD-ROM drive is ready, when aztcd_init is trying to read the version
394 string and a time consuming ACMD_SOFT_RESET command can be avoided. This is
395 detected by looking, if AFL_OP_OK can be read correctly. If the CD-ROM drive
396 hangs in some unknown state, e.g. because of an error before a warm start or
397 because you first operated under DOS, even the version string may be correct,
398 but the following commands will not. Then change the code in such a way,
399 that the ACMD_SOFT_RESET is issued in any case, by substituting the
400 if-statement 'if ( ...=AFL_OP_OK)' by 'if (1)'.
401
402If you succeed, please mail me the exact version string of your drive and
403the code modifications, you have made together with a short explanation.
404If you don't succeed, you may mail me the output of the debugging messages.
405But remember, they are only useful, if they are exact and complete and you
406describe in detail your hardware setup and what you did (cold/warm reboot,
407with/without DOS, DOS-driver started/not started, which Linux-commands etc.)
408
409
4109. TECHNICAL HISTORY OF THE DRIVER
411The AZTECH-Driver is a rework of the Mitsumi-Driver. Four major items had to
412be reworked:
413
414a) The Mitsumi drive does issue complete status information acknowledging
415each command, the Aztech drive does only signal that the command was
416processed. So whenever the complete status information is needed, an extra
417ACMD_GET_STATUS command is issued. The handshake procedure for the drive
418can be found in the functions aztSendCmd(), sendAztCmd() and getAztStatus().
419
420b) The Aztech Drive does not have a ACMD_GET_DISK_INFO command, so the
421necessary info about the number of tracks (firstTrack, lastTrack), disk
422length etc. has to be read from the TOC in the lead in track (see function
423aztGetDiskInfo()).
424
425c) Whenever data is read from the drive, the Mitsumi drive is started with a
426command to read an indefinite (0xffffff) number of sectors. When the appropriate
427number of sectors is read, the drive is stopped by a ACDM_STOP command. This
428does not work with the Aztech drive. I did not find a way to stop it. The
429stop and pause commands do only work in AUDIO mode but not in DATA mode.
430Therefore I had to modify the 'finite state machine' in function azt_poll to
431only read a certain number of sectors and then start a new read on demand. As I
432have not completely understood, how the buffer/caching scheme of the Mitsumi
433driver was implemented, I am not sure, if I have covered all cases correctly,
434whenever you get timeout messages, the bug is most likely to be in that
435function azt_poll() around switch(cmd) .... case ACD_S_DATA.
436
437d) I did not get information about changing drive mode. So I doubt, that the
438code around function azt_poll() case AZT_S_MODE does work. In my test I have
439not been able to switch to reading in raw mode. For reading raw mode, Aztech
440uses a different command than for cooked mode, which I only have implemen-
441ted in the ioctl-section but not in the section which is used by the ISO9660.
442
443The driver was developed on an AST PC with Intel 486/DX2, 8MB RAM, 340MB IDE
444hard disk and on an AST PC with Intel Pentium 60MHz, 16MB RAM, 520MB IDE
445running Linux kernel version 1.0.9 from the LST 1.8 Distribution. The kernel
446was compiled with gcc.2.5.8. My CD-ROM drive is an Aztech CDA268-01A. My
447drive says, that it has Firmware Version AZT26801A1.3. It came with an ISA-bus
448interface card and works with polled I/O without DMA and without interrupts.
449The code for all other drives was 'remote' tested and debugged by a number of
450volunteers on the Internet.
451
452Points, where I feel that possible problems might be and all points where I
453did not completely understand the drive's behaviour or trust my own code are
454marked with /*???*/ in the source code. There are also some parts in the
455Mitsumi driver, where I did not completely understand their code.
456
457
45810. ACKNOWLEDGMENTS
459Without the help of P.Bush, Aztech, who delivered technical information
460about the Aztech Drive and without the help of E.Moenkeberg, GWDG, who did a
461great job in analyzing the command structure of various CD-ROM drives, this
462work would not have been possible. E.Moenkeberg was also a great help in
463making the software 'kernel ready' and in answering many of the CDROM-related
464questions in the newsgroups. He really is *the* Linux CD-ROM guru. Thanks
465also to all the guys on the Internet, who collected valuable technical
466information about CDROMs.
467
468Joe Nardone (joe@access.digex.net) was a patient tester even for my first
469trial, which was more than slow, and made suggestions for code improvement.
470Especially the 'finite state machine' azt_poll() was rewritten by Joe to get
471clean C code and avoid the ugly 'gotos', which I copied from mcd.c.
472
473Robby Schirmer (schirmer@fmi.uni-passau.de) tested the audio stuff (ioctls)
474and suggested a lot of patches for them.
475
476Joseph Piskor and Peter Nugent were the first users with the ORCHID CD3110
477and also were very patient with the problems which occurred.
478
479Reinhard Max delivered the information for the CDROM-interface of the
480SoundWave32 soundcards.
481
482Jochen Kunz and Olaf Kaluza delivered the information for supporting Conrad's
483TXC drive.
484
485Hilmar Berger delivered the patches for supporting CyCDROM CR520ie.
486
487Anybody, who is interested in these items should have a look at 'ftp.gwdg.de',
488directory 'pub/linux/cdrom' and at 'ftp.cdrom.com', directory 'pub/cdrom'.
489
49011. PROGRAMMING ADD ONs: cdplay.c
491You can use the ioctl-functions included in aztcd.c in your own programs. As
492an example on how to do this, you will find a tiny CD Player for audio CDs
493named 'cdplay.c'. It allows you to play audio CDs. You can play a specified
494track, pause and resume or skip tracks forward and backwards. If you quit the
495program without stopping the drive, playing is continued. You can also
496(mis)use cdplay to read and hexdump data disks. You can find the code in the
497APPENDIX of this file, which you should cut out with an editor and store in a
498separate file 'cdplay.c'. To compile it and make it executable, do
499 gcc -s -Wall -O2 -L/usr/lib cdplay.c -o /usr/local/bin/cdplay # compiles it
500 chmod +755 /usr/local/bin/cdplay # makes it executable
501 ln -s /dev/aztcd0 /dev/cdrom # creates a link
502 (for /usr/lib substitute the top level directory, where your include files
503 reside, and for /usr/local/bin the directory, where you want the executable
504 binary to reside )
505
506You have to set the correct permissions for cdplay *and* for /dev/mcd0 or
507/dev/aztcd0 in order to use it. Remember, that you should not have /dev/cdrom
508mounted, when you're playing audio CDs.
509
510This program is just a hack for testing the ioctl-functions in aztcd.c. I will
511not maintain it, so if you run into problems, discard it or have a look into
512the source code 'cdplay.c'. The program does only contain a minimum of user
513protection and input error detection. If you use the commands in the wrong
514order or if you try to read a CD at wrong addresses, you may get error messages
515or even hang your machine. If you get STEN_LOW, STEN_LOW_WAIT or segment violation
516error messages when using cdplay, after that, the system might not be stable
517any more, so you'd better reboot. As the ioctl-functions run in kernel mode,
518most normal Linux-multitasking protection features do not work. By using
519uninitialized 'wild' pointers etc., it is easy to write to other users' data
520and program areas, destroy kernel tables etc.. So if you experiment with ioctls
521as always when you are doing systems programming and kernel hacking, you
522should have a backup copy of your system in a safe place (and you also
523should try restoring from a backup copy first)!
524
525A reworked and improved version called 'cdtester.c', which has yet more
526features for testing CDROM-drives can be found in
527Documentation/cdrom/sbpcd, written by E.Moenkeberg.
528
529Werner Zimmermann
530Fachhochschule fuer Technik Esslingen
531(EMail: Werner.Zimmermann@fht-esslingen.de)
532October, 1997
533
534---------------------------------------------------------------------------
535APPENDIX: Source code of cdplay.c
536
537/* Tiny Audio CD Player
538
539 Copyright 1994, 1995, 1996 Werner Zimmermann (Werner.Zimmermann@fht-esslingen.de)
540
541This program originally was written to test the audio functions of the
542AZTECH.CDROM-driver, but it should work with every CD-ROM drive. Before
543using it, you should set a symlink from /dev/cdrom to your real CDROM
544device.
545
546The GNU General Public License applies to this program.
547
548History: V0.1 W.Zimmermann: First release. Nov. 8, 1994
549 V0.2 W.Zimmermann: Enhanced functionality. Nov. 9, 1994
550 V0.3 W.Zimmermann: Additional functions. Nov. 28, 1994
551 V0.4 W.Zimmermann: fixed some bugs. Dec. 17, 1994
552 V0.5 W.Zimmermann: clean 'scanf' commands without compiler warnings
553 Jan. 6, 1995
554 V0.6 W.Zimmermann: volume control (still experimental). Jan. 24, 1995
555 V0.7 W.Zimmermann: read raw modified. July 26, 95
556*/
557
558#include <stdio.h>
559#include <ctype.h>
560#include <sys/ioctl.h>
561#include <sys/types.h>
562#include <fcntl.h>
563#include <unistd.h>
564#include <linux/cdrom.h>
565#include <linux/../../drivers/cdrom/aztcd.h>
566
567void help(void)
568{ printf("Available Commands: STOP s EJECT/CLOSE e QUIT q\n");
569 printf(" PLAY TRACK t PAUSE p RESUME r\n");
570 printf(" NEXT TRACK n REPEAT LAST l HELP h\n");
571 printf(" SUB CHANNEL c TRACK INFO i PLAY AT a\n");
572 printf(" READ d READ RAW w VOLUME v\n");
573}
574
575int main(void)
576{ int handle;
577 unsigned char command=' ', ini=0, first=1, last=1;
578 unsigned int cmd, i,j,k, arg1,arg2,arg3;
579 struct cdrom_ti ti;
580 struct cdrom_tochdr tocHdr;
581 struct cdrom_subchnl subchnl;
582 struct cdrom_tocentry entry;
583 struct cdrom_msf msf;
584 union { struct cdrom_msf msf;
585 unsigned char buf[CD_FRAMESIZE_RAW];
586 } azt;
587 struct cdrom_volctrl volctrl;
588
589 printf("\nMini-Audio CD-Player V0.72 (C) 1994,1995,1996 W.Zimmermann\n");
590 handle=open("/dev/cdrom",O_RDWR);
591 ioctl(handle,CDROMRESUME);
592
593 if (handle<=0)
594 { printf("Drive Error: already playing, no audio disk, door open\n");
595 printf(" or no permission (you must be ROOT in order to use this program)\n");
596 }
597 else
598 { help();
599 while (1)
600 { printf("Type command (h = help): ");
601 scanf("%s",&command);
602 switch (command)
603 { case 'e': cmd=CDROMEJECT;
604 ioctl(handle,cmd);
605 break;
606 case 'p': if (!ini)
607 { printf("Command not allowed - play track first\n");
608 }
609 else
610 { cmd=CDROMPAUSE;
611 if (ioctl(handle,cmd)) printf("Drive Error\n");
612 }
613 break;
614 case 'r': if (!ini)
615 { printf("Command not allowed - play track first\n");
616 }
617 else
618 { cmd=CDROMRESUME;
619 if (ioctl(handle,cmd)) printf("Drive Error\n");
620 }
621 break;
622 case 's': cmd=CDROMPAUSE;
623 if (ioctl(handle,cmd)) printf("Drive error or already stopped\n");
624 cmd=CDROMSTOP;
625 if (ioctl(handle,cmd)) printf("Drive error\n");
626 break;
627 case 't': cmd=CDROMREADTOCHDR;
628 if (ioctl(handle,cmd,&tocHdr)) printf("Drive Error\n");
629 first=tocHdr.cdth_trk0;
630 last= tocHdr.cdth_trk1;
631 if ((first==0)||(first>last))
632 { printf ("--could not read TOC\n");
633 }
634 else
635 { printf("--first track: %d --last track: %d --enter track number: ",first,last);
636 cmd=CDROMPLAYTRKIND;
637 scanf("%i",&arg1);
638 ti.cdti_trk0=arg1;
639 if (ti.cdti_trk0<first) ti.cdti_trk0=first;
640 if (ti.cdti_trk0>last) ti.cdti_trk0=last;
641 ti.cdti_ind0=0;
642 ti.cdti_trk1=last;
643 ti.cdti_ind1=0;
644 if (ioctl(handle,cmd,&ti)) printf("Drive Error\n");
645 ini=1;
646 }
647 break;
648 case 'n': if (!ini++)
649 { if (ioctl(handle,CDROMREADTOCHDR,&tocHdr)) printf("Drive Error\n");
650 first=tocHdr.cdth_trk0;
651 last= tocHdr.cdth_trk1;
652 ti.cdti_trk0=first-1;
653 }
654 if ((first==0)||(first>last))
655 { printf ("--could not read TOC\n");
656 }
657 else
658 { cmd=CDROMPLAYTRKIND;
659 if (++ti.cdti_trk0 > last) ti.cdti_trk0=last;
660 ti.cdti_ind0=0;
661 ti.cdti_trk1=last;
662 ti.cdti_ind1=0;
663 if (ioctl(handle,cmd,&ti)) printf("Drive Error\n");
664 ini=1;
665 }
666 break;
667 case 'l': if (!ini++)
668 { if (ioctl(handle,CDROMREADTOCHDR,&tocHdr)) printf("Drive Error\n");
669 first=tocHdr.cdth_trk0;
670 last= tocHdr.cdth_trk1;
671 ti.cdti_trk0=first+1;
672 }
673 if ((first==0)||(first>last))
674 { printf ("--could not read TOC\n");
675 }
676 else
677 { cmd=CDROMPLAYTRKIND;
678 if (--ti.cdti_trk0 < first) ti.cdti_trk0=first;
679 ti.cdti_ind0=0;
680 ti.cdti_trk1=last;
681 ti.cdti_ind1=0;
682 if (ioctl(handle,cmd,&ti)) printf("Drive Error\n");
683 ini=1;
684 }
685 break;
686 case 'c': subchnl.cdsc_format=CDROM_MSF;
687 if (ioctl(handle,CDROMSUBCHNL,&subchnl))
688 printf("Drive Error\n");
689 else
690 { printf("AudioStatus:%s Track:%d Mode:%d MSF=%d:%d:%d\n", \
691 subchnl.cdsc_audiostatus==CDROM_AUDIO_PLAY ? "PLAYING":"NOT PLAYING",\
692 subchnl.cdsc_trk,subchnl.cdsc_adr, \
693 subchnl.cdsc_absaddr.msf.minute, subchnl.cdsc_absaddr.msf.second, \
694 subchnl.cdsc_absaddr.msf.frame);
695 }
696 break;
697 case 'i': if (!ini)
698 { printf("Command not allowed - play track first\n");
699 }
700 else
701 { cmd=CDROMREADTOCENTRY;
702 printf("Track No.: ");
703 scanf("%d",&arg1);
704 entry.cdte_track=arg1;
705 if (entry.cdte_track<first) entry.cdte_track=first;
706 if (entry.cdte_track>last) entry.cdte_track=last;
707 entry.cdte_format=CDROM_MSF;
708 if (ioctl(handle,cmd,&entry))
709 { printf("Drive error or invalid track no.\n");
710 }
711 else
712 { printf("Mode %d Track, starts at %d:%d:%d\n", \
713 entry.cdte_adr,entry.cdte_addr.msf.minute, \
714 entry.cdte_addr.msf.second,entry.cdte_addr.msf.frame);
715 }
716 }
717 break;
718 case 'a': cmd=CDROMPLAYMSF;
719 printf("Address (min:sec:frame) ");
720 scanf("%d:%d:%d",&arg1,&arg2,&arg3);
721 msf.cdmsf_min0 =arg1;
722 msf.cdmsf_sec0 =arg2;
723 msf.cdmsf_frame0=arg3;
724 if (msf.cdmsf_sec0 > 59) msf.cdmsf_sec0 =59;
725 if (msf.cdmsf_frame0> 74) msf.cdmsf_frame0=74;
726 msf.cdmsf_min1=60;
727 msf.cdmsf_sec1=00;
728 msf.cdmsf_frame1=00;
729 if (ioctl(handle,cmd,&msf))
730 { printf("Drive error or invalid address\n");
731 }
732 break;
733#ifdef AZT_PRIVATE_IOCTLS /*not supported by every CDROM driver*/
734 case 'd': cmd=CDROMREADCOOKED;
735 printf("Address (min:sec:frame) ");
736 scanf("%d:%d:%d",&arg1,&arg2,&arg3);
737 azt.msf.cdmsf_min0 =arg1;
738 azt.msf.cdmsf_sec0 =arg2;
739 azt.msf.cdmsf_frame0=arg3;
740 if (azt.msf.cdmsf_sec0 > 59) azt.msf.cdmsf_sec0 =59;
741 if (azt.msf.cdmsf_frame0> 74) azt.msf.cdmsf_frame0=74;
742 if (ioctl(handle,cmd,&azt.msf))
743 { printf("Drive error, invalid address or unsupported command\n");
744 }
745 k=0;
746 getchar();
747 for (i=0;i<128;i++)
748 { printf("%4d:",i*16);
749 for (j=0;j<16;j++)
750 { printf("%2x ",azt.buf[i*16+j]);
751 }
752 for (j=0;j<16;j++)
753 { if (isalnum(azt.buf[i*16+j]))
754 printf("%c",azt.buf[i*16+j]);
755 else
756 printf(".");
757 }
758 printf("\n");
759 k++;
760 if (k>=20)
761 { printf("press ENTER to continue\n");
762 getchar();
763 k=0;
764 }
765 }
766 break;
767 case 'w': cmd=CDROMREADRAW;
768 printf("Address (min:sec:frame) ");
769 scanf("%d:%d:%d",&arg1,&arg2,&arg3);
770 azt.msf.cdmsf_min0 =arg1;
771 azt.msf.cdmsf_sec0 =arg2;
772 azt.msf.cdmsf_frame0=arg3;
773 if (azt.msf.cdmsf_sec0 > 59) azt.msf.cdmsf_sec0 =59;
774 if (azt.msf.cdmsf_frame0> 74) azt.msf.cdmsf_frame0=74;
775 if (ioctl(handle,cmd,&azt))
776 { printf("Drive error, invalid address or unsupported command\n");
777 }
778 k=0;
779 for (i=0;i<147;i++)
780 { printf("%4d:",i*16);
781 for (j=0;j<16;j++)
782 { printf("%2x ",azt.buf[i*16+j]);
783 }
784 for (j=0;j<16;j++)
785 { if (isalnum(azt.buf[i*16+j]))
786 printf("%c",azt.buf[i*16+j]);
787 else
788 printf(".");
789 }
790 printf("\n");
791 k++;
792 if (k>=20)
793 { getchar();
794 k=0;
795 }
796 }
797 break;
798#endif
799 case 'v': cmd=CDROMVOLCTRL;
800 printf("--Channel 0 Left (0-255): ");
801 scanf("%d",&arg1);
802 printf("--Channel 1 Right (0-255): ");
803 scanf("%d",&arg2);
804 volctrl.channel0=arg1;
805 volctrl.channel1=arg2;
806 volctrl.channel2=0;
807 volctrl.channel3=0;
808 if (ioctl(handle,cmd,&volctrl))
809 { printf("Drive error or unsupported command\n");
810 }
811 break;
812 case 'q': if (close(handle)) printf("Drive Error: CLOSE\n");
813 exit(0);
814 case 'h': help();
815 break;
816 default: printf("unknown command\n");
817 break;
818 }
819 }
820 }
821 return 0;
822}
diff --git a/Documentation/cdrom/cdrom-standard.tex b/Documentation/cdrom/cdrom-standard.tex
new file mode 100644
index 000000000000..92f94e597582
--- /dev/null
+++ b/Documentation/cdrom/cdrom-standard.tex
@@ -0,0 +1,1022 @@
1\documentclass{article}
2\def\version{$Id: cdrom-standard.tex,v 1.9 1997/12/28 15:42:49 david Exp $}
3\newcommand{\newsection}[1]{\newpage\section{#1}}
4
5\evensidemargin=0pt
6\oddsidemargin=0pt
7\topmargin=-\headheight \advance\topmargin by -\headsep
8\textwidth=15.99cm \textheight=24.62cm % normal A4, 1'' margin
9
10\def\linux{{\sc Linux}}
11\def\cdrom{{\sc cd-rom}}
12\def\UCD{{\sc Uniform cd-rom Driver}}
13\def\cdromc{{\tt {cdrom.c}}}
14\def\cdromh{{\tt {cdrom.h}}}
15\def\fo{\sl} % foreign words
16\def\ie{{\fo i.e.}}
17\def\eg{{\fo e.g.}}
18
19\everymath{\it} \everydisplay{\it}
20\catcode `\_=\active \def_{\_\penalty100 }
21\catcode`\<=\active \def<#1>{{\langle\hbox{\rm#1}\rangle}}
22
23\begin{document}
24\title{A \linux\ \cdrom\ standard}
25\author{David van Leeuwen\\{\normalsize\tt david@ElseWare.cistron.nl}
26\\{\footnotesize updated by Erik Andersen {\tt(andersee@debian.org)}}
27\\{\footnotesize updated by Jens Axboe {\tt(axboe@image.dk)}}}
28\date{12 March 1999}
29
30\maketitle
31
32\newsection{Introduction}
33
34\linux\ is probably the Unix-like operating system that supports
35the widest variety of hardware devices. The reasons for this are
36presumably
37\begin{itemize}
38\item
39 The large list of hardware devices available for the many platforms
40 that \linux\ now supports (\ie, i386-PCs, Sparc Suns, etc.)
41\item
42 The open design of the operating system, such that anybody can write a
43 driver for \linux.
44\item
45 There is plenty of source code around as examples of how to write a driver.
46\end{itemize}
47The openness of \linux, and the many different types of available
48hardware has allowed \linux\ to support many different hardware devices.
49Unfortunately, the very openness that has allowed \linux\ to support
50all these different devices has also allowed the behavior of each
51device driver to differ significantly from one device to another.
52This divergence of behavior has been very significant for \cdrom\
53devices; the way a particular drive reacts to a `standard' $ioctl()$
54call varies greatly from one device driver to another. To avoid making
55their drivers totally inconsistent, the writers of \linux\ \cdrom\
56drivers generally created new device drivers by understanding, copying,
57and then changing an existing one. Unfortunately, this practice did not
58maintain uniform behavior across all the \linux\ \cdrom\ drivers.
59
60This document describes an effort to establish Uniform behavior across
61all the different \cdrom\ device drivers for \linux. This document also
62defines the various $ioctl$s, and how the low-level \cdrom\ device
63drivers should implement them. Currently (as of the \linux\ 2.1.$x$
64development kernels) several low-level \cdrom\ device drivers, including
65both IDE/ATAPI and SCSI, now use this Uniform interface.
66
67When the \cdrom\ was developed, the interface between the \cdrom\ drive
68and the computer was not specified in the standards. As a result, many
69different \cdrom\ interfaces were developed. Some of them had their
70own proprietary design (Sony, Mitsumi, Panasonic, Philips), other
71manufacturers adopted an existing electrical interface and changed
72the functionality (CreativeLabs/SoundBlaster, Teac, Funai) or simply
73adapted their drives to one or more of the already existing electrical
74interfaces (Aztech, Sanyo, Funai, Vertos, Longshine, Optics Storage and
75most of the `NoName' manufacturers). In cases where a new drive really
76brought its own interface or used its own command set and flow control
77scheme, either a separate driver had to be written, or an existing
78driver had to be enhanced. History has delivered us \cdrom\ support for
79many of these different interfaces. Nowadays, almost all new \cdrom\
80drives are either IDE/ATAPI or SCSI, and it is very unlikely that any
81manufacturer will create a new interface. Even finding drives for the
82old proprietary interfaces is getting difficult.
83
84When (in the 1.3.70's) I looked at the existing software interface,
85which was expressed through \cdromh, it appeared to be a rather wild
86set of commands and data formats.\footnote{I cannot recollect what
87kernel version I looked at, then, presumably 1.2.13 and 1.3.34---the
88latest kernel that I was indirectly involved in.} It seemed that many
89features of the software interface had been added to accommodate the
90capabilities of a particular drive, in an {\fo ad hoc\/} manner. More
91importantly, it appeared that the behavior of the `standard' commands
92was different for most of the different drivers: \eg, some drivers
93close the tray if an $open()$ call occurs when the tray is open, while
94others do not. Some drivers lock the door upon opening the device, to
95prevent an incoherent file system, but others don't, to allow software
96ejection. Undoubtedly, the capabilities of the different drives vary,
97but even when two drives have the same capability their drivers'
98behavior was usually different.
99
100I decided to start a discussion on how to make all the \linux\ \cdrom\
101drivers behave more uniformly. I began by contacting the developers of
102the many \cdrom\ drivers found in the \linux\ kernel. Their reactions
103encouraged me to write the \UCD\ which this document is intended to
104describe. The implementation of the \UCD\ is in the file \cdromc. This
105driver is intended to be an additional software layer that sits on top
106of the low-level device drivers for each \cdrom\ drive. By adding this
107additional layer, it is possible to have all the different \cdrom\
108devices behave {\em exactly\/} the same (insofar as the underlying
109hardware will allow).
110
111The goal of the \UCD\ is {\em not\/} to alienate driver developers who
112have not yet taken steps to support this effort. The goal of \UCD\ is
113simply to give people writing application programs for \cdrom\ drives
114{\em one\/} \linux\ \cdrom\ interface with consistent behavior for all
115\cdrom\ devices. In addition, this also provides a consistent interface
116between the low-level device driver code and the \linux\ kernel. Care
117is taken that 100\,\% compatibility exists with the data structures and
118programmer's interface defined in \cdromh. This guide was written to
119help \cdrom\ driver developers adapt their code to use the \UCD\ code
120defined in \cdromc.
121
122Personally, I think that the most important hardware interfaces are
123the IDE/ATAPI drives and, of course, the SCSI drives, but as prices
124of hardware drop continuously, it is also likely that people may have
125more than one \cdrom\ drive, possibly of mixed types. It is important
126that these drives behave in the same way. In December 1994, one of the
127cheapest \cdrom\ drives was a Philips cm206, a double-speed proprietary
128drive. In the months that I was busy writing a \linux\ driver for it,
129proprietary drives became obsolete and IDE/ATAPI drives became the
130standard. At the time of the last update to this document (November
1311997) it is becoming difficult to even {\em find} anything less than a
13216 speed \cdrom\ drive, and 24 speed drives are common.
133
134\newsection{Standardizing through another software level}
135\label{cdrom.c}
136
137At the time this document was conceived, all drivers directly
138implemented the \cdrom\ $ioctl()$ calls through their own routines. This
139led to the danger of different drivers forgetting to do important things
140like checking that the user was giving the driver valid data. More
141importantly, this led to the divergence of behavior, which has already
142been discussed.
143
144For this reason, the \UCD\ was created to enforce consistent \cdrom\
145drive behavior, and to provide a common set of services to the various
146low-level \cdrom\ device drivers. The \UCD\ now provides another
147software-level, that separates the $ioctl()$ and $open()$ implementation
148from the actual hardware implementation. Note that this effort has
149made few changes which will affect a user's application programs. The
150greatest change involved moving the contents of the various low-level
151\cdrom\ drivers' header files to the kernel's cdrom directory. This was
152done to help ensure that the user is only presented with only one cdrom
153interface, the interface defined in \cdromh.
154
155\cdrom\ drives are specific enough (\ie, different from other
156block-devices such as floppy or hard disc drives), to define a set
157of common {\em \cdrom\ device operations}, $<cdrom-device>_dops$.
158These operations are different from the classical block-device file
159operations, $<block-device>_fops$.
160
161The routines for the \UCD\ interface level are implemented in the file
162\cdromc. In this file, the \UCD\ interfaces with the kernel as a block
163device by registering the following general $struct\ file_operations$:
164$$
165\halign{$#$\ \hfil&$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
166struct& file_operations\ cdrom_fops = \{\hidewidth\cr
167 &NULL, & lseek \cr
168 &block_read, & read---general block-dev read \cr
169 &block_write, & write---general block-dev write \cr
170 &NULL, & readdir \cr
171 &NULL, & select \cr
172 &cdrom_ioctl, & ioctl \cr
173 &NULL, & mmap \cr
174 &cdrom_open, & open \cr
175 &cdrom_release, & release \cr
176 &NULL, & fsync \cr
177 &NULL, & fasync \cr
178 &cdrom_media_changed, & media change \cr
179 &NULL & revalidate \cr
180\};\cr
181}
182$$
183
184Every active \cdrom\ device shares this $struct$. The routines
185declared above are all implemented in \cdromc, since this file is the
186place where the behavior of all \cdrom-devices is defined and
187standardized. The actual interface to the various types of \cdrom\
188hardware is still performed by various low-level \cdrom-device
189drivers. These routines simply implement certain {\em capabilities\/}
190that are common to all \cdrom\ (and really, all removable-media
191devices).
192
193Registration of a low-level \cdrom\ device driver is now done through
194the general routines in \cdromc, not through the Virtual File System
195(VFS) any more. The interface implemented in \cdromc\ is carried out
196through two general structures that contain information about the
197capabilities of the driver, and the specific drives on which the
198driver operates. The structures are:
199\begin{description}
200\item[$cdrom_device_ops$]
201 This structure contains information about the low-level driver for a
202 \cdrom\ device. This structure is conceptually connected to the major
203 number of the device (although some drivers may have different
204 major numbers, as is the case for the IDE driver).
205\item[$cdrom_device_info$]
206 This structure contains information about a particular \cdrom\ drive,
207 such as its device name, speed, etc. This structure is conceptually
208 connected to the minor number of the device.
209\end{description}
210
211Registering a particular \cdrom\ drive with the \UCD\ is done by the
212low-level device driver though a call to:
213$$register_cdrom(struct\ cdrom_device_info * <device>_info)
214$$
215The device information structure, $<device>_info$, contains all the
216information needed for the kernel to interface with the low-level
217\cdrom\ device driver. One of the most important entries in this
218structure is a pointer to the $cdrom_device_ops$ structure of the
219low-level driver.
220
221The device operations structure, $cdrom_device_ops$, contains a list
222of pointers to the functions which are implemented in the low-level
223device driver. When \cdromc\ accesses a \cdrom\ device, it does it
224through the functions in this structure. It is impossible to know all
225the capabilities of future \cdrom\ drives, so it is expected that this
226list may need to be expanded from time to time as new technologies are
227developed. For example, CD-R and CD-R/W drives are beginning to become
228popular, and support will soon need to be added for them. For now, the
229current $struct$ is:
230$$
231\halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}&
232 $/*$ \rm# $*/$\hfil\cr
233struct& cdrom_device_ops\ \{ \hidewidth\cr
234 &int& (* open)(struct\ cdrom_device_info *, int)\cr
235 &void& (* release)(struct\ cdrom_device_info *);\cr
236 &int& (* drive_status)(struct\ cdrom_device_info *, int);\cr
237 &int& (* media_changed)(struct\ cdrom_device_info *, int);\cr
238 &int& (* tray_move)(struct\ cdrom_device_info *, int);\cr
239 &int& (* lock_door)(struct\ cdrom_device_info *, int);\cr
240 &int& (* select_speed)(struct\ cdrom_device_info *, int);\cr
241 &int& (* select_disc)(struct\ cdrom_device_info *, int);\cr
242 &int& (* get_last_session) (struct\ cdrom_device_info *,
243 struct\ cdrom_multisession *{});\cr
244 &int& (* get_mcn)(struct\ cdrom_device_info *, struct\ cdrom_mcn *{});\cr
245 &int& (* reset)(struct\ cdrom_device_info *);\cr
246 &int& (* audio_ioctl)(struct\ cdrom_device_info *, unsigned\ int,
247 void *{});\cr
248 &int& (* dev_ioctl)(struct\ cdrom_device_info *, unsigned\ int,
249 unsigned\ long);\cr
250\noalign{\medskip}
251 &const\ int& capability;& capability flags \cr
252 &int& n_minors;& number of active minor devices \cr
253\};\cr
254}
255$$
256When a low-level device driver implements one of these capabilities,
257it should add a function pointer to this $struct$. When a particular
258function is not implemented, however, this $struct$ should contain a
259NULL instead. The $capability$ flags specify the capabilities of the
260\cdrom\ hardware and/or low-level \cdrom\ driver when a \cdrom\ drive
261is registered with the \UCD. The value $n_minors$ should be a positive
262value indicating the number of minor devices that are supported by
263the low-level device driver, normally~1. Although these two variables
264are `informative' rather than `operational,' they are included in
265$cdrom_device_ops$ because they describe the capability of the {\em
266driver\/} rather than the {\em drive}. Nomenclature has always been
267difficult in computer programming.
268
269Note that most functions have fewer parameters than their
270$blkdev_fops$ counterparts. This is because very little of the
271information in the structures $inode$ and $file$ is used. For most
272drivers, the main parameter is the $struct$ $cdrom_device_info$, from
273which the major and minor number can be extracted. (Most low-level
274\cdrom\ drivers don't even look at the major and minor number though,
275since many of them only support one device.) This will be available
276through $dev$ in $cdrom_device_info$ described below.
277
278The drive-specific, minor-like information that is registered with
279\cdromc, currently contains the following fields:
280$$
281\halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}&
282 $/*$ \rm# $*/$\hfil\cr
283struct& cdrom_device_info\ \{ \hidewidth\cr
284 & struct\ cdrom_device_ops *& ops;& device operations for this major\cr
285 & struct\ cdrom_device_info *& next;& next device_info for this major\cr
286 & void *& handle;& driver-dependent data\cr
287\noalign{\medskip}
288 & kdev_t& dev;& device number (incorporates minor)\cr
289 & int& mask;& mask of capability: disables them \cr
290 & int& speed;& maximum speed for reading data \cr
291 & int& capacity;& number of discs in a jukebox \cr
292\noalign{\medskip}
293 &int& options : 30;& options flags \cr
294 &unsigned& mc_flags : 2;& media-change buffer flags \cr
295 & int& use_count;& number of times device is opened\cr
296 & char& name[20];& name of the device type\cr
297\}\cr
298}$$
299Using this $struct$, a linked list of the registered minor devices is
300built, using the $next$ field. The device number, the device operations
301struct and specifications of properties of the drive are stored in this
302structure.
303
304The $mask$ flags can be used to mask out some of the capabilities listed
305in $ops\to capability$, if a specific drive doesn't support a feature
306of the driver. The value $speed$ specifies the maximum head-rate of the
307drive, measured in units of normal audio speed (176\,kB/sec raw data or
308150\,kB/sec file system data). The value $n_discs$ should reflect the
309number of discs the drive can hold simultaneously, if it is designed
310as a juke-box, or otherwise~1. The parameters are declared $const$
311because they describe properties of the drive, which don't change after
312registration.
313
314A few registers contain variables local to the \cdrom\ drive. The
315flags $options$ are used to specify how the general \cdrom\ routines
316should behave. These various flags registers should provide enough
317flexibility to adapt to the different users' wishes (and {\em not\/} the
318`arbitrary' wishes of the author of the low-level device driver, as is
319the case in the old scheme). The register $mc_flags$ is used to buffer
320the information from $media_changed()$ to two separate queues. Other
321data that is specific to a minor drive, can be accessed through $handle$,
322which can point to a data structure specific to the low-level driver.
323The fields $use_count$, $next$, $options$ and $mc_flags$ need not be
324initialized.
325
326The intermediate software layer that \cdromc\ forms will perform some
327additional bookkeeping. The use count of the device (the number of
328processes that have the device opened) is registered in $use_count$. The
329function $cdrom_ioctl()$ will verify the appropriate user-memory regions
330for read and write, and in case a location on the CD is transferred,
331it will `sanitize' the format by making requests to the low-level
332drivers in a standard format, and translating all formats between the
333user-software and low level drivers. This relieves much of the drivers'
334memory checking and format checking and translation. Also, the necessary
335structures will be declared on the program stack.
336
337The implementation of the functions should be as defined in the
338following sections. Two functions {\em must\/} be implemented, namely
339$open()$ and $release()$. Other functions may be omitted, their
340corresponding capability flags will be cleared upon registration.
341Generally, a function returns zero on success and negative on error. A
342function call should return only after the command has completed, but of
343course waiting for the device should not use processor time.
344
345\subsection{$Int\ open(struct\ cdrom_device_info * cdi, int\ purpose)$}
346
347$Open()$ should try to open the device for a specific $purpose$, which
348can be either:
349\begin{itemize}
350\item[0] Open for reading data, as done by {\tt {mount()}} (2), or the
351user commands {\tt {dd}} or {\tt {cat}}.
352\item[1] Open for $ioctl$ commands, as done by audio-CD playing
353programs.
354\end{itemize}
355Notice that any strategic code (closing tray upon $open()$, etc.)\ is
356done by the calling routine in \cdromc, so the low-level routine
357should only be concerned with proper initialization, such as spinning
358up the disc, etc. % and device-use count
359
360
361\subsection{$Void\ release(struct\ cdrom_device_info * cdi)$}
362
363
364Device-specific actions should be taken such as spinning down the device.
365However, strategic actions such as ejection of the tray, or unlocking
366the door, should be left over to the general routine $cdrom_release()$.
367This is the only function returning type $void$.
368
369\subsection{$Int\ drive_status(struct\ cdrom_device_info * cdi, int\ slot_nr)$}
370\label{drive status}
371
372The function $drive_status$, if implemented, should provide
373information on the status of the drive (not the status of the disc,
374which may or may not be in the drive). If the drive is not a changer,
375$slot_nr$ should be ignored. In \cdromh\ the possibilities are listed:
376$$
377\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
378CDS_NO_INFO& no information available\cr
379CDS_NO_DISC& no disc is inserted, tray is closed\cr
380CDS_TRAY_OPEN& tray is opened\cr
381CDS_DRIVE_NOT_READY& something is wrong, tray is moving?\cr
382CDS_DISC_OK& a disc is loaded and everything is fine\cr
383}
384$$
385
386\subsection{$Int\ media_changed(struct\ cdrom_device_info * cdi, int\ disc_nr)$}
387
388This function is very similar to the original function in $struct\
389file_operations$. It returns 1 if the medium of the device $cdi\to
390dev$ has changed since the last call, and 0 otherwise. The parameter
391$disc_nr$ identifies a specific slot in a juke-box, it should be
392ignored for single-disc drives. Note that by `re-routing' this
393function through $cdrom_media_changed()$, we can implement separate
394queues for the VFS and a new $ioctl()$ function that can report device
395changes to software (\eg, an auto-mounting daemon).
396
397\subsection{$Int\ tray_move(struct\ cdrom_device_info * cdi, int\ position)$}
398
399This function, if implemented, should control the tray movement. (No
400other function should control this.) The parameter $position$ controls
401the desired direction of movement:
402\begin{itemize}
403\item[0] Close tray
404\item[1] Open tray
405\end{itemize}
406This function returns 0 upon success, and a non-zero value upon
407error. Note that if the tray is already in the desired position, no
408action need be taken, and the return value should be 0.
409
410\subsection{$Int\ lock_door(struct\ cdrom_device_info * cdi, int\ lock)$}
411
412This function (and no other code) controls locking of the door, if the
413drive allows this. The value of $lock$ controls the desired locking
414state:
415\begin{itemize}
416\item[0] Unlock door, manual opening is allowed
417\item[1] Lock door, tray cannot be ejected manually
418\end{itemize}
419This function returns 0 upon success, and a non-zero value upon
420error. Note that if the door is already in the requested state, no
421action need be taken, and the return value should be 0.
422
423\subsection{$Int\ select_speed(struct\ cdrom_device_info * cdi, int\ speed)$}
424
425Some \cdrom\ drives are capable of changing their head-speed. There
426are several reasons for changing the speed of a \cdrom\ drive. Badly
427pressed \cdrom s may benefit from less-than-maximum head rate. Modern
428\cdrom\ drives can obtain very high head rates (up to $24\times$ is
429common). It has been reported that these drives can make reading
430errors at these high speeds, reducing the speed can prevent data loss
431in these circumstances. Finally, some of these drives can
432make an annoyingly loud noise, which a lower speed may reduce. %Finally,
433%although the audio-low-pass filters probably aren't designed for it,
434%more than real-time playback of audio might be used for high-speed
435%copying of audio tracks.
436
437This function specifies the speed at which data is read or audio is
438played back. The value of $speed$ specifies the head-speed of the
439drive, measured in units of standard cdrom speed (176\,kB/sec raw data
440or 150\,kB/sec file system data). So to request that a \cdrom\ drive
441operate at 300\,kB/sec you would call the CDROM_SELECT_SPEED $ioctl$
442with $speed=2$. The special value `0' means `auto-selection', \ie,
443maximum data-rate or real-time audio rate. If the drive doesn't have
444this `auto-selection' capability, the decision should be made on the
445current disc loaded and the return value should be positive. A negative
446return value indicates an error.
447
448\subsection{$Int\ select_disc(struct\ cdrom_device_info * cdi, int\ number)$}
449
450If the drive can store multiple discs (a juke-box) this function
451will perform disc selection. It should return the number of the
452selected disc on success, a negative value on error. Currently, only
453the ide-cd driver supports this functionality.
454
455\subsection{$Int\ get_last_session(struct\ cdrom_device_info * cdi, struct\
456 cdrom_multisession * ms_info)$}
457
458This function should implement the old corresponding $ioctl()$. For
459device $cdi\to dev$, the start of the last session of the current disc
460should be returned in the pointer argument $ms_info$. Note that
461routines in \cdromc\ have sanitized this argument: its requested
462format will {\em always\/} be of the type $CDROM_LBA$ (linear block
463addressing mode), whatever the calling software requested. But
464sanitization goes even further: the low-level implementation may
465return the requested information in $CDROM_MSF$ format if it wishes so
466(setting the $ms_info\rightarrow addr_format$ field appropriately, of
467course) and the routines in \cdromc\ will make the transformation if
468necessary. The return value is 0 upon success.
469
470\subsection{$Int\ get_mcn(struct\ cdrom_device_info * cdi, struct\
471 cdrom_mcn * mcn)$}
472
473Some discs carry a `Media Catalog Number' (MCN), also called
474`Universal Product Code' (UPC). This number should reflect the number
475that is generally found in the bar-code on the product. Unfortunately,
476the few discs that carry such a number on the disc don't even use the
477same format. The return argument to this function is a pointer to a
478pre-declared memory region of type $struct\ cdrom_mcn$. The MCN is
479expected as a 13-character string, terminated by a null-character.
480
481\subsection{$Int\ reset(struct\ cdrom_device_info * cdi)$}
482
483This call should perform a hard-reset on the drive (although in
484circumstances that a hard-reset is necessary, a drive may very well not
485listen to commands anymore). Preferably, control is returned to the
486caller only after the drive has finished resetting. If the drive is no
487longer listening, it may be wise for the underlying low-level cdrom
488driver to time out.
489
490\subsection{$Int\ audio_ioctl(struct\ cdrom_device_info * cdi, unsigned\
491 int\ cmd, void * arg)$}
492
493Some of the \cdrom-$ioctl$s defined in \cdromh\ can be
494implemented by the routines described above, and hence the function
495$cdrom_ioctl$ will use those. However, most $ioctl$s deal with
496audio-control. We have decided to leave these to be accessed through a
497single function, repeating the arguments $cmd$ and $arg$. Note that
498the latter is of type $void*{}$, rather than $unsigned\ long\
499int$. The routine $cdrom_ioctl()$ does do some useful things,
500though. It sanitizes the address format type to $CDROM_MSF$ (Minutes,
501Seconds, Frames) for all audio calls. It also verifies the memory
502location of $arg$, and reserves stack-memory for the argument. This
503makes implementation of the $audio_ioctl()$ much simpler than in the
504old driver scheme. For example, you may look up the function
505$cm206_audio_ioctl()$ in {\tt {cm206.c}} that should be updated with
506this documentation.
507
508An unimplemented ioctl should return $-ENOSYS$, but a harmless request
509(\eg, $CDROMSTART$) may be ignored by returning 0 (success). Other
510errors should be according to the standards, whatever they are. When
511an error is returned by the low-level driver, the \UCD\ tries whenever
512possible to return the error code to the calling program. (We may decide
513to sanitize the return value in $cdrom_ioctl()$ though, in order to
514guarantee a uniform interface to the audio-player software.)
515
516\subsection{$Int\ dev_ioctl(struct\ cdrom_device_info * cdi, unsigned\ int\
517 cmd, unsigned\ long\ arg)$}
518
519Some $ioctl$s seem to be specific to certain \cdrom\ drives. That is,
520they are introduced to service some capabilities of certain drives. In
521fact, there are 6 different $ioctl$s for reading data, either in some
522particular kind of format, or audio data. Not many drives support
523reading audio tracks as data, I believe this is because of protection
524of copyrights of artists. Moreover, I think that if audio-tracks are
525supported, it should be done through the VFS and not via $ioctl$s. A
526problem here could be the fact that audio-frames are 2352 bytes long,
527so either the audio-file-system should ask for 75264 bytes at once
528(the least common multiple of 512 and 2352), or the drivers should
529bend their backs to cope with this incoherence (to which I would be
530opposed). Furthermore, it is very difficult for the hardware to find
531the exact frame boundaries, since there are no synchronization headers
532in audio frames. Once these issues are resolved, this code should be
533standardized in \cdromc.
534
535Because there are so many $ioctl$s that seem to be introduced to
536satisfy certain drivers,\footnote{Is there software around that
537 actually uses these? I'd be interested!} any `non-standard' $ioctl$s
538are routed through the call $dev_ioctl()$. In principle, `private'
539$ioctl$s should be numbered after the device's major number, and not
540the general \cdrom\ $ioctl$ number, {\tt {0x53}}. Currently the
541non-supported $ioctl$s are: {\it CDROMREADMODE1, CDROMREADMODE2,
542 CDROMREADAUDIO, CDROMREADRAW, CDROMREADCOOKED, CDROMSEEK,
543 CDROMPLAY\-BLK and CDROM\-READALL}.
544
545
546\subsection{\cdrom\ capabilities}
547\label{capability}
548
549Instead of just implementing some $ioctl$ calls, the interface in
550\cdromc\ supplies the possibility to indicate the {\em capabilities\/}
551of a \cdrom\ drive. This can be done by ORing any number of
552capability-constants that are defined in \cdromh\ at the registration
553phase. Currently, the capabilities are any of:
554$$
555\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
556CDC_CLOSE_TRAY& can close tray by software control\cr
557CDC_OPEN_TRAY& can open tray\cr
558CDC_LOCK& can lock and unlock the door\cr
559CDC_SELECT_SPEED& can select speed, in units of $\sim$150\,kB/s\cr
560CDC_SELECT_DISC& drive is juke-box\cr
561CDC_MULTI_SESSION& can read sessions $>\rm1$\cr
562CDC_MCN& can read Media Catalog Number\cr
563CDC_MEDIA_CHANGED& can report if disc has changed\cr
564CDC_PLAY_AUDIO& can perform audio-functions (play, pause, etc)\cr
565CDC_RESET& hard reset device\cr
566CDC_IOCTLS& driver has non-standard ioctls\cr
567CDC_DRIVE_STATUS& driver implements drive status\cr
568}
569$$
570The capability flag is declared $const$, to prevent drivers from
571accidentally tampering with the contents. The capability fags actually
572inform \cdromc\ of what the driver can do. If the drive found
573by the driver does not have the capability, is can be masked out by
574the $cdrom_device_info$ variable $mask$. For instance, the SCSI \cdrom\
575driver has implemented the code for loading and ejecting \cdrom's, and
576hence its corresponding flags in $capability$ will be set. But a SCSI
577\cdrom\ drive might be a caddy system, which can't load the tray, and
578hence for this drive the $cdrom_device_info$ struct will have set
579the $CDC_CLOSE_TRAY$ bit in $mask$.
580
581In the file \cdromc\ you will encounter many constructions of the type
582$$\it
583if\ (cdo\rightarrow capability \mathrel\& \mathord{\sim} cdi\rightarrow mask
584 \mathrel{\&} CDC_<capability>) \ldots
585$$
586There is no $ioctl$ to set the mask\dots The reason is that
587I think it is better to control the {\em behavior\/} rather than the
588{\em capabilities}.
589
590\subsection{Options}
591
592A final flag register controls the {\em behavior\/} of the \cdrom\
593drives, in order to satisfy different users' wishes, hopefully
594independently of the ideas of the respective author who happened to
595have made the drive's support available to the \linux\ community. The
596current behavior options are:
597$$
598\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
599CDO_AUTO_CLOSE& try to close tray upon device $open()$\cr
600CDO_AUTO_EJECT& try to open tray on last device $close()$\cr
601CDO_USE_FFLAGS& use $file_pointer\rightarrow f_flags$ to indicate
602 purpose for $open()$\cr
603CDO_LOCK& try to lock door if device is opened\cr
604CDO_CHECK_TYPE& ensure disc type is data if opened for data\cr
605}
606$$
607
608The initial value of this register is $CDO_AUTO_CLOSE \mathrel|
609CDO_USE_FFLAGS \mathrel| CDO_LOCK$, reflecting my own view on user
610interface and software standards. Before you protest, there are two
611new $ioctl$s implemented in \cdromc, that allow you to control the
612behavior by software. These are:
613$$
614\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
615CDROM_SET_OPTIONS& set options specified in $(int)\ arg$\cr
616CDROM_CLEAR_OPTIONS& clear options specified in $(int)\ arg$\cr
617}
618$$
619One option needs some more explanation: $CDO_USE_FFLAGS$. In the next
620newsection we explain what the need for this option is.
621
622A software package {\tt setcd}, available from the Debian distribution
623and {\tt sunsite.unc.edu}, allows user level control of these flags.
624
625\newsection{The need to know the purpose of opening the \cdrom\ device}
626
627Traditionally, Unix devices can be used in two different `modes',
628either by reading/writing to the device file, or by issuing
629controlling commands to the device, by the device's $ioctl()$
630call. The problem with \cdrom\ drives, is that they can be used for
631two entirely different purposes. One is to mount removable
632file systems, \cdrom s, the other is to play audio CD's. Audio commands
633are implemented entirely through $ioctl$s, presumably because the
634first implementation (SUN?) has been such. In principle there is
635nothing wrong with this, but a good control of the `CD player' demands
636that the device can {\em always\/} be opened in order to give the
637$ioctl$ commands, regardless of the state the drive is in.
638
639On the other hand, when used as a removable-media disc drive (what the
640original purpose of \cdrom s is) we would like to make sure that the
641disc drive is ready for operation upon opening the device. In the old
642scheme, some \cdrom\ drivers don't do any integrity checking, resulting
643in a number of i/o errors reported by the VFS to the kernel when an
644attempt for mounting a \cdrom\ on an empty drive occurs. This is not a
645particularly elegant way to find out that there is no \cdrom\ inserted;
646it more-or-less looks like the old IBM-PC trying to read an empty floppy
647drive for a couple of seconds, after which the system complains it
648can't read from it. Nowadays we can {\em sense\/} the existence of a
649removable medium in a drive, and we believe we should exploit that
650fact. An integrity check on opening of the device, that verifies the
651availability of a \cdrom\ and its correct type (data), would be
652desirable.
653
654These two ways of using a \cdrom\ drive, principally for data and
655secondarily for playing audio discs, have different demands for the
656behavior of the $open()$ call. Audio use simply wants to open the
657device in order to get a file handle which is needed for issuing
658$ioctl$ commands, while data use wants to open for correct and
659reliable data transfer. The only way user programs can indicate what
660their {\em purpose\/} of opening the device is, is through the $flags$
661parameter (see {\tt {open(2)}}). For \cdrom\ devices, these flags aren't
662implemented (some drivers implement checking for write-related flags,
663but this is not strictly necessary if the device file has correct
664permission flags). Most option flags simply don't make sense to
665\cdrom\ devices: $O_CREAT$, $O_NOCTTY$, $O_TRUNC$, $O_APPEND$, and
666$O_SYNC$ have no meaning to a \cdrom.
667
668We therefore propose to use the flag $O_NONBLOCK$ to indicate
669that the device is opened just for issuing $ioctl$
670commands. Strictly, the meaning of $O_NONBLOCK$ is that opening and
671subsequent calls to the device don't cause the calling process to
672wait. We could interpret this as ``don't wait until someone has
673inserted some valid data-\cdrom.'' Thus, our proposal of the
674implementation for the $open()$ call for \cdrom s is:
675\begin{itemize}
676\item If no other flags are set than $O_RDONLY$, the device is opened
677for data transfer, and the return value will be 0 only upon successful
678initialization of the transfer. The call may even induce some actions
679on the \cdrom, such as closing the tray.
680\item If the option flag $O_NONBLOCK$ is set, opening will always be
681successful, unless the whole device doesn't exist. The drive will take
682no actions whatsoever.
683\end{itemize}
684
685\subsection{And what about standards?}
686
687You might hesitate to accept this proposal as it comes from the
688\linux\ community, and not from some standardizing institute. What
689about SUN, SGI, HP and all those other Unix and hardware vendors?
690Well, these companies are in the lucky position that they generally
691control both the hardware and software of their supported products,
692and are large enough to set their own standard. They do not have to
693deal with a dozen or more different, competing hardware
694configurations.\footnote{Incidentally, I think that SUN's approach to
695mounting \cdrom s is very good in origin: under Solaris a
696volume-daemon automatically mounts a newly inserted \cdrom\ under {\tt
697{/cdrom/$<volume-name>$/}}. In my opinion they should have pushed this
698further and have {\em every\/} \cdrom\ on the local area network be
699mounted at the similar location, \ie, no matter in which particular
700machine you insert a \cdrom, it will always appear at the same
701position in the directory tree, on every system. When I wanted to
702implement such a user-program for \linux, I came across the
703differences in behavior of the various drivers, and the need for an
704$ioctl$ informing about media changes.}
705
706We believe that using $O_NONBLOCK$ to indicate that a device is being opened
707for $ioctl$ commands only can be easily introduced in the \linux\
708community. All the CD-player authors will have to be informed, we can
709even send in our own patches to the programs. The use of $O_NONBLOCK$
710has most likely no influence on the behavior of the CD-players on
711other operating systems than \linux. Finally, a user can always revert
712to old behavior by a call to $ioctl(file_descriptor, CDROM_CLEAR_OPTIONS,
713CDO_USE_FFLAGS)$.
714
715\subsection{The preferred strategy of $open()$}
716
717The routines in \cdromc\ are designed in such a way that run-time
718configuration of the behavior of \cdrom\ devices (of {\em any\/} type)
719can be carried out, by the $CDROM_SET/CLEAR_OPTIONS$ $ioctls$. Thus, various
720modes of operation can be set:
721\begin{description}
722\item[$CDO_AUTO_CLOSE \mathrel| CDO_USE_FFLAGS \mathrel| CDO_LOCK$] This
723is the default setting. (With $CDO_CHECK_TYPE$ it will be better, in the
724future.) If the device is not yet opened by any other process, and if
725the device is being opened for data ($O_NONBLOCK$ is not set) and the
726tray is found to be open, an attempt to close the tray is made. Then,
727it is verified that a disc is in the drive and, if $CDO_CHECK_TYPE$ is
728set, that it contains tracks of type `data mode 1.' Only if all tests
729are passed is the return value zero. The door is locked to prevent file
730system corruption. If the drive is opened for audio ($O_NONBLOCK$ is
731set), no actions are taken and a value of 0 will be returned.
732\item[$CDO_AUTO_CLOSE \mathrel| CDO_AUTO_EJECT \mathrel| CDO_LOCK$] This
733mimics the behavior of the current sbpcd-driver. The option flags are
734ignored, the tray is closed on the first open, if necessary. Similarly,
735the tray is opened on the last release, \ie, if a \cdrom\ is unmounted,
736it is automatically ejected, such that the user can replace it.
737\end{description}
738We hope that these option can convince everybody (both driver
739maintainers and user program developers) to adopt the new \cdrom\
740driver scheme and option flag interpretation.
741
742\newsection{Description of routines in \cdromc}
743
744Only a few routines in \cdromc\ are exported to the drivers. In this
745new section we will discuss these, as well as the functions that `take
746over' the \cdrom\ interface to the kernel. The header file belonging
747to \cdromc\ is called \cdromh. Formerly, some of the contents of this
748file were placed in the file {\tt {ucdrom.h}}, but this file has now been
749merged back into \cdromh.
750
751\subsection{$Struct\ file_operations\ cdrom_fops$}
752
753The contents of this structure were described in section~\ref{cdrom.c}.
754A pointer to this structure is assigned to the $fops$ field
755of the $struct gendisk$.
756
757\subsection{$Int\ register_cdrom( struct\ cdrom_device_info\ * cdi)$}
758
759This function is used in about the same way one registers $cdrom_fops$
760with the kernel, the device operations and information structures,
761as described in section~\ref{cdrom.c}, should be registered with the
762\UCD:
763$$
764register_cdrom(\&<device>_info));
765$$
766This function returns zero upon success, and non-zero upon
767failure. The structure $<device>_info$ should have a pointer to the
768driver's $<device>_dops$, as in
769$$
770\vbox{\halign{&$#$\hfil\cr
771struct\ &cdrom_device_info\ <device>_info = \{\cr
772& <device>_dops;\cr
773&\ldots\cr
774\}\cr
775}}$$
776Note that a driver must have one static structure, $<device>_dops$, while
777it may have as many structures $<device>_info$ as there are minor devices
778active. $Register_cdrom()$ builds a linked list from these.
779
780\subsection{$Int\ unregister_cdrom(struct\ cdrom_device_info * cdi)$}
781
782Unregistering device $cdi$ with minor number $MINOR(cdi\to dev)$ removes
783the minor device from the list. If it was the last registered minor for
784the low-level driver, this disconnects the registered device-operation
785routines from the \cdrom\ interface. This function returns zero upon
786success, and non-zero upon failure.
787
788\subsection{$Int\ cdrom_open(struct\ inode * ip, struct\ file * fp)$}
789
790This function is not called directly by the low-level drivers, it is
791listed in the standard $cdrom_fops$. If the VFS opens a file, this
792function becomes active. A strategy is implemented in this routine,
793taking care of all capabilities and options that are set in the
794$cdrom_device_ops$ connected to the device. Then, the program flow is
795transferred to the device_dependent $open()$ call.
796
797\subsection{$Void\ cdrom_release(struct\ inode *ip, struct\ file
798*fp)$}
799
800This function implements the reverse-logic of $cdrom_open()$, and then
801calls the device-dependent $release()$ routine. When the use-count has
802reached 0, the allocated buffers are flushed by calls to $sync_dev(dev)$
803and $invalidate_buffers(dev)$.
804
805
806\subsection{$Int\ cdrom_ioctl(struct\ inode *ip, struct\ file *fp,
807unsigned\ int\ cmd, unsigned\ long\ arg)$}
808\label{cdrom-ioctl}
809
810This function handles all the standard $ioctl$ requests for \cdrom\
811devices in a uniform way. The different calls fall into three
812categories: $ioctl$s that can be directly implemented by device
813operations, ones that are routed through the call $audio_ioctl()$, and
814the remaining ones, that are presumable device-dependent. Generally, a
815negative return value indicates an error.
816
817\subsubsection{Directly implemented $ioctl$s}
818\label{ioctl-direct}
819
820The following `old' \cdrom-$ioctl$s are implemented by directly
821calling device-operations in $cdrom_device_ops$, if implemented and
822not masked:
823\begin{description}
824\item[CDROMMULTISESSION] Requests the last session on a \cdrom.
825\item[CDROMEJECT] Open tray.
826\item[CDROMCLOSETRAY] Close tray.
827\item[CDROMEJECT_SW] If $arg\not=0$, set behavior to auto-close (close
828tray on first open) and auto-eject (eject on last release), otherwise
829set behavior to non-moving on $open()$ and $release()$ calls.
830\item[CDROM_GET_MCN] Get the Media Catalog Number from a CD.
831\end{description}
832
833\subsubsection{$Ioctl$s routed through $audio_ioctl()$}
834\label{ioctl-audio}
835
836The following set of $ioctl$s are all implemented through a call to
837the $cdrom_fops$ function $audio_ioctl()$. Memory checks and
838allocation are performed in $cdrom_ioctl()$, and also sanitization of
839address format ($CDROM_LBA$/$CDROM_MSF$) is done.
840\begin{description}
841\item[CDROMSUBCHNL] Get sub-channel data in argument $arg$ of type $struct\
842cdrom_subchnl *{}$.
843\item[CDROMREADTOCHDR] Read Table of Contents header, in $arg$ of type
844$struct\ cdrom_tochdr *{}$.
845\item[CDROMREADTOCENTRY] Read a Table of Contents entry in $arg$ and
846specified by $arg$ of type $struct\ cdrom_tocentry *{}$.
847\item[CDROMPLAYMSF] Play audio fragment specified in Minute, Second,
848Frame format, delimited by $arg$ of type $struct\ cdrom_msf *{}$.
849\item[CDROMPLAYTRKIND] Play audio fragment in track-index format
850delimited by $arg$ of type $struct\ \penalty-1000 cdrom_ti *{}$.
851\item[CDROMVOLCTRL] Set volume specified by $arg$ of type $struct\
852cdrom_volctrl *{}$.
853\item[CDROMVOLREAD] Read volume into by $arg$ of type $struct\
854cdrom_volctrl *{}$.
855\item[CDROMSTART] Spin up disc.
856\item[CDROMSTOP] Stop playback of audio fragment.
857\item[CDROMPAUSE] Pause playback of audio fragment.
858\item[CDROMRESUME] Resume playing.
859\end{description}
860
861\subsubsection{New $ioctl$s in \cdromc}
862
863The following $ioctl$s have been introduced to allow user programs to
864control the behavior of individual \cdrom\ devices. New $ioctl$
865commands can be identified by the underscores in their names.
866\begin{description}
867\item[CDROM_SET_OPTIONS] Set options specified by $arg$. Returns the
868option flag register after modification. Use $arg = \rm0$ for reading
869the current flags.
870\item[CDROM_CLEAR_OPTIONS] Clear options specified by $arg$. Returns
871 the option flag register after modification.
872\item[CDROM_SELECT_SPEED] Select head-rate speed of disc specified as
873 by $arg$ in units of standard cdrom speed (176\,kB/sec raw data or
874 150\,kB/sec file system data). The value 0 means `auto-select', \ie,
875 play audio discs at real time and data discs at maximum speed. The value
876 $arg$ is checked against the maximum head rate of the drive found in the
877 $cdrom_dops$.
878\item[CDROM_SELECT_DISC] Select disc numbered $arg$ from a juke-box.
879 First disc is numbered 0. The number $arg$ is checked against the
880 maximum number of discs in the juke-box found in the $cdrom_dops$.
881\item[CDROM_MEDIA_CHANGED] Returns 1 if a disc has been changed since
882 the last call. Note that calls to $cdrom_media_changed$ by the VFS
883 are treated by an independent queue, so both mechanisms will detect
884 a media change once. For juke-boxes, an extra argument $arg$
885 specifies the slot for which the information is given. The special
886 value $CDSL_CURRENT$ requests that information about the currently
887 selected slot be returned.
888\item[CDROM_DRIVE_STATUS] Returns the status of the drive by a call to
889 $drive_status()$. Return values are defined in section~\ref{drive
890 status}. Note that this call doesn't return information on the
891 current playing activity of the drive; this can be polled through an
892 $ioctl$ call to $CDROMSUBCHNL$. For juke-boxes, an extra argument
893 $arg$ specifies the slot for which (possibly limited) information is
894 given. The special value $CDSL_CURRENT$ requests that information
895 about the currently selected slot be returned.
896\item[CDROM_DISC_STATUS] Returns the type of the disc currently in the
897 drive. It should be viewed as a complement to $CDROM_DRIVE_STATUS$.
898 This $ioctl$ can provide \emph {some} information about the current
899 disc that is inserted in the drive. This functionality used to be
900 implemented in the low level drivers, but is now carried out
901 entirely in \UCD.
902
903 The history of development of the CD's use as a carrier medium for
904 various digital information has lead to many different disc types.
905 This $ioctl$ is useful only in the case that CDs have \emph {only
906 one} type of data on them. While this is often the case, it is
907 also very common for CDs to have some tracks with data, and some
908 tracks with audio. Because this is an existing interface, rather
909 than fixing this interface by changing the assumptions it was made
910 under, thereby breaking all user applications that use this
911 function, the \UCD\ implements this $ioctl$ as follows: If the CD in
912 question has audio tracks on it, and it has absolutely no CD-I, XA,
913 or data tracks on it, it will be reported as $CDS_AUDIO$. If it has
914 both audio and data tracks, it will return $CDS_MIXED$. If there
915 are no audio tracks on the disc, and if the CD in question has any
916 CD-I tracks on it, it will be reported as $CDS_XA_2_2$. Failing
917 that, if the CD in question has any XA tracks on it, it will be
918 reported as $CDS_XA_2_1$. Finally, if the CD in question has any
919 data tracks on it, it will be reported as a data CD ($CDS_DATA_1$).
920
921 This $ioctl$ can return:
922 $$
923 \halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
924 CDS_NO_INFO& no information available\cr
925 CDS_NO_DISC& no disc is inserted, or tray is opened\cr
926 CDS_AUDIO& Audio disc (2352 audio bytes/frame)\cr
927 CDS_DATA_1& data disc, mode 1 (2048 user bytes/frame)\cr
928 CDS_XA_2_1& mixed data (XA), mode 2, form 1 (2048 user bytes)\cr
929 CDS_XA_2_2& mixed data (XA), mode 2, form 1 (2324 user bytes)\cr
930 CDS_MIXED& mixed audio/data disc\cr
931 }
932 $$
933 For some information concerning frame layout of the various disc
934 types, see a recent version of \cdromh.
935
936\item[CDROM_CHANGER_NSLOTS] Returns the number of slots in a
937 juke-box.
938\item[CDROMRESET] Reset the drive.
939\item[CDROM_GET_CAPABILITY] Returns the $capability$ flags for the
940 drive. Refer to section \ref{capability} for more information on
941 these flags.
942\item[CDROM_LOCKDOOR] Locks the door of the drive. $arg == \rm0$
943 unlocks the door, any other value locks it.
944\item[CDROM_DEBUG] Turns on debugging info. Only root is allowed
945 to do this. Same semantics as CDROM_LOCKDOOR.
946\end{description}
947
948\subsubsection{Device dependent $ioctl$s}
949
950Finally, all other $ioctl$s are passed to the function $dev_ioctl()$,
951if implemented. No memory allocation or verification is carried out.
952
953\newsection{How to update your driver}
954
955\begin{enumerate}
956\item Make a backup of your current driver.
957\item Get hold of the files \cdromc\ and \cdromh, they should be in
958 the directory tree that came with this documentation.
959\item Make sure you include \cdromh.
960\item Change the 3rd argument of $register_blkdev$ from
961$\&<your-drive>_fops$ to $\&cdrom_fops$.
962\item Just after that line, add the following to register with the \UCD:
963 $$register_cdrom(\&<your-drive>_info);$$
964 Similarly, add a call to $unregister_cdrom()$ at the appropriate place.
965\item Copy an example of the device-operations $struct$ to your
966 source, \eg, from {\tt {cm206.c}} $cm206_dops$, and change all
967 entries to names corresponding to your driver, or names you just
968 happen to like. If your driver doesn't support a certain function,
969 make the entry $NULL$. At the entry $capability$ you should list all
970 capabilities your driver currently supports. If your driver
971 has a capability that is not listed, please send me a message.
972\item Copy the $cdrom_device_info$ declaration from the same example
973 driver, and modify the entries according to your needs. If your
974 driver dynamically determines the capabilities of the hardware, this
975 structure should also be declared dynamically.
976\item Implement all functions in your $<device>_dops$ structure,
977 according to prototypes listed in \cdromh, and specifications given
978 in section~\ref{cdrom.c}. Most likely you have already implemented
979 the code in a large part, and you will almost certainly need to adapt the
980 prototype and return values.
981\item Rename your $<device>_ioctl()$ function to $audio_ioctl$ and
982 change the prototype a little. Remove entries listed in the first
983 part in section~\ref{cdrom-ioctl}, if your code was OK, these are
984 just calls to the routines you adapted in the previous step.
985\item You may remove all remaining memory checking code in the
986 $audio_ioctl()$ function that deals with audio commands (these are
987 listed in the second part of section~\ref{cdrom-ioctl}). There is no
988 need for memory allocation either, so most $case$s in the $switch$
989 statement look similar to:
990 $$
991 case\ CDROMREADTOCENTRY\colon get_toc_entry\bigl((struct\
992 cdrom_tocentry *{})\ arg\bigr);
993 $$
994\item All remaining $ioctl$ cases must be moved to a separate
995 function, $<device>_ioctl$, the device-dependent $ioctl$s. Note that
996 memory checking and allocation must be kept in this code!
997\item Change the prototypes of $<device>_open()$ and
998 $<device>_release()$, and remove any strategic code (\ie, tray
999 movement, door locking, etc.).
1000\item Try to recompile the drivers. We advise you to use modules, both
1001 for {\tt {cdrom.o}} and your driver, as debugging is much easier this
1002 way.
1003\end{enumerate}
1004
1005\newsection{Thanks}
1006
1007Thanks to all the people involved. First, Erik Andersen, who has
1008taken over the torch in maintaining \cdromc\ and integrating much
1009\cdrom-related code in the 2.1-kernel. Thanks to Scott Snyder and
1010Gerd Knorr, who were the first to implement this interface for SCSI
1011and IDE-CD drivers and added many ideas for extension of the data
1012structures relative to kernel~2.0. Further thanks to Heiko Eissfeldt,
1013Thomas Quinot, Jon Tombs, Ken Pizzini, Eberhard M\"onkeberg and Andrew
1014Kroll, the \linux\ \cdrom\ device driver developers who were kind
1015enough to give suggestions and criticisms during the writing. Finally
1016of course, I want to thank Linus Torvalds for making this possible in
1017the first place.
1018
1019\vfill
1020$ \version\ $
1021\eject
1022\end{document}
diff --git a/Documentation/cdrom/cdu31a b/Documentation/cdrom/cdu31a
new file mode 100644
index 000000000000..c0667da09c00
--- /dev/null
+++ b/Documentation/cdrom/cdu31a
@@ -0,0 +1,196 @@
1
2 CDU31A/CDU33A Driver Info
3 -------------------------
4
5Information on the Sony CDU31A/CDU33A CDROM driver for the Linux
6kernel.
7
8 Corey Minyard (minyard@metronet.com)
9
10 Colossians 3:17
11
12Crude Table of Contents
13-----------------------
14
15 Setting Up the Hardware
16 Configuring the Kernel
17 Configuring as a Module
18 Driver Special Features
19
20
21This device driver handles Sony CDU31A/CDU33A CDROM drives and
22provides a complete block-level interface as well as an ioctl()
23interface as specified in include/linux/cdrom.h). With this
24interface, CDROMs can be accessed, standard audio CDs can be played
25back normally, and CD audio information can be read off the drive.
26
27Note that this will only work for CDU31A/CDU33A drives. Some vendors
28market their drives as CDU31A compatible. They lie. Their drives are
29really CDU31A hardware interface compatible (they can plug into the
30same card). They are not software compatible.
31
32Setting Up the Hardware
33-----------------------
34
35The CDU31A driver is unable to safely tell if an interface card is
36present that it can use because the interface card does not announce
37its presence in any way besides placing 4 I/O locations in memory. It
38used to just probe memory and attempt commands, but Linus wisely asked
39me to remove that because it could really screw up other hardware in
40the system.
41
42Because of this, you must tell the kernel where the drive interface
43is, what interrupts are used, and possibly if you are on a PAS-16
44soundcard.
45
46If you have the Sony CDU31A/CDU33A drive interface card, the following
47diagram will help you set it up. If you have another card, you are on
48your own. You need to make sure that the I/O address and interrupt is
49not used by another card in the system. You will need to know the I/O
50address and interrupt you have set. Note that use of interrupts is
51highly recommended, if possible, it really cuts down on CPU used.
52Unfortunately, most soundcards do not support interrupts for their
53CDROM interfaces. By default, the Sony interface card comes with
54interrupts disabled.
55
56 +----------+-----------------+----------------------+
57 | JP1 | 34 Pin Conn | |
58 | JP2 +-----------------+ |
59 | JP3 |
60 | JP4 |
61 | +--+
62 | | +-+
63 | | | | External
64 | | | | Connector
65 | | | |
66 | | +-+
67 | +--+
68 | |
69 | +--------+
70 | |
71 +------------------------------------------+
72
73 JP1 sets the Base Address, using the following settings:
74
75 Address Pin 1 Pin 2
76 ------- ----- -----
77 0x320 Short Short
78 0x330 Short Open
79 0x340 Open Short
80 0x360 Open Open
81
82 JP2 and JP3 configure the DMA channel; they must be set the same.
83
84 DMA Pin 1 Pin 2 Pin 3
85 --- ----- ----- -----
86 1 On Off On
87 2 Off On Off
88 3 Off Off On
89
90 JP4 Configures the IRQ:
91
92 IRQ Pin 1 Pin 2 Pin 3 Pin 4
93 --- ----- ----- ----- -----
94 3 Off Off On Off
95 4 Off Off* Off On
96 5 On Off Off Off
97 6 Off On Off Off
98
99 The documentation states to set this for interrupt
100 4, but I think that is a mistake.
101
102Note that if you have another interface card, you will need to look at
103the documentation to find the I/O base address. This is specified to
104the SLCD.SYS driver for DOS with the /B: parameter, so you can look at
105you DOS driver setup to find the address, if necessary.
106
107Configuring the Kernel
108----------------------
109
110You must tell the kernel where the drive is at boot time. This can be
111done at the Linux boot prompt, by using LILO, or by using Bootlin.
112Note that this is no substitute for HOWTOs and LILO documentation, if
113you are confused please read those for info on bootline configuration
114and LILO.
115
116At the linux boot prompt, press the ALT key and add the following line
117after the boot name (you can let the kernel boot, it will tell you the
118default boot name while booting):
119
120 cdu31a=<base address>,<interrupt>[,PAS]
121
122The base address needs to have "0x" in front of it, since it is in
123hex. For instance, to configure a drive at address 320 on interrupt 5,
124use the following:
125
126 cdu31a=0x320,5
127
128I use the following boot line:
129
130 cdu31a=0x1f88,0,PAS
131
132because I have a PAS-16 which does not support interrupt for the
133CDU31A interface.
134
135Adding this as an append line at the beginning of the /etc/lilo.conf
136file will set it for lilo configurations. I have the following as the
137first line in my lilo.conf file:
138
139 append="cdu31a=0x1f88,0"
140
141I'm not sure how to set up Bootlin (I have never used it), if someone
142would like to fill in this section please do.
143
144
145Configuring as a Module
146-----------------------
147
148The driver supports loading as a module. However, you must specify
149the boot address and interrupt on the boot line to insmod. You can't
150use modprobe to load it, since modprobe doesn't support setting
151variables.
152
153Anyway, I use the following line to load my driver as a module
154
155 /sbin/insmod /lib/modules/`uname -r`/misc/cdu31a.o cdu31a_port=0x1f88
156
157You can set the following variables in the driver:
158
159 cdu31a_port=<I/O address> - sets the base I/O. If hex, put 0x in
160 front of it. This must be specified.
161
162 cdu31a_irq=<interrupt> - Sets the interrupt number. Leaving this
163 off will turn interrupts off.
164
165
166Driver Special Features
167-----------------------
168
169This section describes features beyond the normal audio and CD-ROM
170functions of the drive.
171
1722048 byte buffer mode
173
174If a disk is mounted with -o block=2048, data is copied straight from
175the drive data port to the buffer. Otherwise, the readahead buffer
176must be involved to hold the other 1K of data when a 1K block
177operation is done. Note that with 2048 byte blocks you cannot execute
178files from the CD.
179
180XA compatibility
181
182The driver should support XA disks for both the CDU31A and CDU33A. It
183does this transparently, the using program doesn't need to set it.
184
185Multi-Session
186
187A multi-session disk looks just like a normal disk to the user. Just
188mount one normally, and all the data should be there. A special
189thanks to Koen for help with this!
190
191Raw sector I/O
192
193Using the CDROMREADAUDIO it is possible to read raw audio and data
194tracks. Both operations return 2352 bytes per sector. On the data
195tracks, the first 12 bytes is not returned by the drive and the value
196of that data is indeterminate.
diff --git a/Documentation/cdrom/cm206 b/Documentation/cdrom/cm206
new file mode 100644
index 000000000000..810368f4f7c4
--- /dev/null
+++ b/Documentation/cdrom/cm206
@@ -0,0 +1,185 @@
1This is the readme file for the driver for the Philips/LMS cdrom drive
2cm206 in combination with the cm260 host adapter card.
3
4 (c) 1995 David A. van Leeuwen
5
6Changes since version 0.99
7--------------------------
8- Interfacing to the kernel is routed though an extra interface layer,
9 cdrom.c. This allows runtime-configurable `behavior' of the cdrom-drive,
10 independent of the driver.
11
12Features since version 0.33
13---------------------------
14- Full audio support, that is, both workman, workbone and cdp work
15 now reasonably. Reading TOC still takes some time. xmcd has been
16 reported to run successfully.
17- Made auto-probe code a little better, I hope
18
19Features since version 0.28
20---------------------------
21- Full speed transfer rate (300 kB/s).
22- Minimum kernel memory usage for buffering (less than 3 kB).
23- Multisession support.
24- Tray locking.
25- Statistics of driver accessible to the user.
26- Module support.
27- Auto-probing of adapter card's base port and irq line,
28 also configurable at boot time or module load time.
29
30
31Decide how you are going to use the driver. There are two
32options:
33
34 (a) installing the driver as a resident part of the kernel
35 (b) compiling the driver as a loadable module
36
37 Further, you must decide if you are going to specify the base port
38 address and the interrupt request line of the adapter card cm260 as
39 boot options for (a), module parameters for (b), use automatic
40 probing of these values, or hard-wire your adaptor card's settings
41 into the source code. If you don't care, you can choose
42 autoprobing, which is the default. In that case you can move on to
43 the next step.
44
45Compiling the kernel
46--------------------
471) move to /usr/src/linux and do a
48
49 make config
50
51 If you have chosen option (a), answer yes to CONFIG_CM206 and
52 CONFIG_ISO9660_FS.
53
54 If you have chosen option (b), answer yes to CONFIG_MODVERSIONS
55 and no (!) to CONFIG_CM206 and CONFIG_ISO9660_FS.
56
572) then do a
58
59 make clean; make zImage; make modules
60
613) do the usual things to install a new image (backup the old one, run
62 `rdev -R zImage 1', copy the new image in place, run lilo). Might
63 be `make zlilo'.
64
65Using the driver as a module
66----------------------------
67If you will only occasionally use the cd-rom driver, you can choose
68option (b), install as a loadable module. You may have to re-compile
69the module when you upgrade the kernel to a new version.
70
71Since version 0.96, much of the functionality has been transferred to
72a generic cdrom interface in the file cdrom.c. The module cm206.o
73depends on cdrom.o. If the latter is not compiled into the kernel,
74you must explicitly load it before cm206.o:
75
76 insmod /usr/src/linux/modules/cdrom.o
77
78To install the module, you use the command, as root
79
80 insmod /usr/src/linux/modules/cm206.o
81
82You can specify the base address on the command line as well as the irq
83line to be used, e.g.
84
85 insmod /usr/src/linux/modules/cm206.o cm206=0x300,11
86
87The order of base port and irq line doesn't matter; if you specify only
88one, the other will have the value of the compiled-in default. You
89may also have to install the file-system module `iso9660.o', if you
90didn't compile that into the kernel.
91
92
93Using the driver as part of the kernel
94--------------------------------------
95If you have chosen option (a), you can specify the base-port
96address and irq on the lilo boot command line, e.g.:
97
98 LILO: linux cm206=0x340,11
99
100This assumes that your linux kernel image keyword is `linux'.
101If you specify either IRQ (3--11) or base port (0x300--0x370),
102auto probing is turned off for both settings, thus setting the
103other value to the compiled-in default.
104
105Note that you can also put these parameters in the lilo configuration file:
106
107# linux config
108image = /vmlinuz
109 root = /dev/hda1
110 label = Linux
111 append = "cm206=0x340,11"
112 read-only
113
114
115If module parameters and LILO config options don't work
116-------------------------------------------------------
117If autoprobing does not work, you can hard-wire the default values
118of the base port address (CM206_BASE) and interrupt request line
119(CM206_IRQ) into the file /usr/src/linux/drivers/cdrom/cm206.h. Change
120the defines of CM206_IRQ and CM206_BASE.
121
122
123Mounting the cdrom
124------------------
1251) Make sure that the right device is installed in /dev.
126
127 mknod /dev/cm206cd b 32 0
128
1292) Make sure there is a mount point, e.g., /cdrom
130
131 mkdir /cdrom
132
1333) mount using a command like this (run as root):
134
135 mount -rt iso9660 /dev/cm206cd /cdrom
136
1374) For user-mounts, add a line in /etc/fstab
138
139 /dev/cm206cd /cdrom iso9660 ro,noauto,user
140
141 This will allow users to give the commands
142
143 mount /cdrom
144 umount /cdrom
145
146If things don't work
147--------------------
148
149- Try to do a `dmesg' to find out if the driver said anything about
150 what is going wrong during the initialization.
151
152- Try to do a `dd if=/dev/cm206cd | od -tc | less' to read from the
153 CD.
154
155- Look in the /proc directory to see if `cm206' shows up under one of
156 `interrupts', `ioports', `devices' or `modules' (if applicable).
157
158
159DISCLAIMER
160----------
161I cannot guarantee that this driver works, or that the hardware will
162not be harmed, although I consider it most unlikely.
163
164I hope that you'll find this driver in some way useful.
165
166 David van Leeuwen
167 david@tm.tno.nl
168
169Note for Linux CDROM vendors
170-----------------------------
171You are encouraged to include this driver on your Linux CDROM. If
172you do, you might consider sending me a free copy of that cd-rom.
173You can contact me through my e-mail address, david@tm.tno.nl.
174If this driver is compiled into a kernel to boot off a cdrom,
175you should actually send me a free copy of that cd-rom.
176
177Copyright
178---------
179The copyright of the cm206 driver for Linux is
180
181 (c) 1995 David A. van Leeuwen
182
183The driver is released under the conditions of the GNU general public
184license, which can be found in the file COPYING in the root of this
185source tree.
diff --git a/Documentation/cdrom/gscd b/Documentation/cdrom/gscd
new file mode 100644
index 000000000000..d01ca36b5c43
--- /dev/null
+++ b/Documentation/cdrom/gscd
@@ -0,0 +1,60 @@
1 Goldstar R420 CD-Rom device driver README
2
3For all kind of other information about the GoldStar R420 CDROM
4and this Linux device driver see the WWW page:
5
6 http://linux.rz.fh-hannover.de/~raupach
7
8
9 If you are the editor of a Linux CD, you should
10 enable gscd.c within your boot floppy kernel. Please,
11 send me one of your CDs for free.
12
13
14This current driver version 0.4a only supports reading data from the disk.
15Currently we have no audio and no multisession or XA support.
16The polling interface is used, no DMA.
17
18
19Sometimes the GoldStar R420 is sold in a 'Reveal Multimedia Kit'. This kit's
20drive interface is compatible, too.
21
22
23Installation
24------------
25
26Change to '/usr/src/linux/drivers/cdrom' and edit the file 'gscd.h'. Insert
27the i/o address of your interface card.
28
29The default base address is 0x340. This will work for most applications.
30Address selection is accomplished by jumpers PN801-1 to PN801-4 on the
31GoldStar Interface Card.
32Appropriate settings are: 0x300, 0x310, 0x320, 0x330, 0x340, 0x350, 0x360
330x370, 0x380, 0x390, 0x3A0, 0x3B0, 0x3C0, 0x3D0, 0x3E0, 0x3F0
34
35Then go back to '/usr/src/linux/' and 'make config' to build the new
36configuration for your kernel. If you want to use the GoldStar driver
37like a module, don't select 'GoldStar CDROM support'. By the way, you
38have to include the iso9660 filesystem.
39
40Now start compiling the kernel with 'make zImage'.
41If you want to use the driver as a module, you have to do 'make modules'
42and 'make modules_install', additionally.
43Install your new kernel as usual - maybe you do it with 'make zlilo'.
44
45Before you can use the driver, you have to
46 mknod /dev/gscd0 b 16 0
47to create the appropriate device file (you only need to do this once).
48
49If you use modules, you can try to insert the driver.
50Say: 'insmod /usr/src/linux/modules/gscd.o'
51or: 'insmod /usr/src/linux/modules/gscd.o gscd=<address>'
52The driver should report its results.
53
54That's it! Mount a disk, i.e. 'mount -rt iso9660 /dev/gscd0 /cdrom'
55
56Feel free to report errors and suggestions to the following address.
57Be sure, I'm very happy to receive your comments!
58
59 Oliver Raupach Hannover, Juni 1995
60(raupach@nwfs1.rz.fh-hannover.de)
diff --git a/Documentation/cdrom/ide-cd b/Documentation/cdrom/ide-cd
new file mode 100644
index 000000000000..29721bfcde12
--- /dev/null
+++ b/Documentation/cdrom/ide-cd
@@ -0,0 +1,574 @@
1IDE-CD driver documentation
2Originally by scott snyder <snyder@fnald0.fnal.gov> (19 May 1996)
3Carrying on the torch is: Erik Andersen <andersee@debian.org>
4New maintainers (19 Oct 1998): Jens Axboe <axboe@image.dk>
5
61. Introduction
7---------------
8
9The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant
10CDROM drives which attach to an IDE interface. Note that some CDROM vendors
11(including Mitsumi, Sony, Creative, Aztech, and Goldstar) have made
12both ATAPI-compliant drives and drives which use a proprietary
13interface. If your drive uses one of those proprietary interfaces,
14this driver will not work with it (but one of the other CDROM drivers
15probably will). This driver will not work with `ATAPI' drives which
16attach to the parallel port. In addition, there is at least one drive
17(CyCDROM CR520ie) which attaches to the IDE port but is not ATAPI;
18this driver will not work with drives like that either (but see the
19aztcd driver).
20
21This driver provides the following features:
22
23 - Reading from data tracks, and mounting ISO 9660 filesystems.
24
25 - Playing audio tracks. Most of the CDROM player programs floating
26 around should work; I usually use Workman.
27
28 - Multisession support.
29
30 - On drives which support it, reading digital audio data directly
31 from audio tracks. The program cdda2wav can be used for this.
32 Note, however, that only some drives actually support this.
33
34 - There is now support for CDROM changers which comply with the
35 ATAPI 2.6 draft standard (such as the NEC CDR-251). This additional
36 functionality includes a function call to query which slot is the
37 currently selected slot, a function call to query which slots contain
38 CDs, etc. A sample program which demonstrates this functionality is
39 appended to the end of this file. The Sanyo 3-disc changer
40 (which does not conform to the standard) is also now supported.
41 Please note the driver refers to the first CD as slot # 0.
42
43
442. Installation
45---------------
46
470. The ide-cd relies on the ide disk driver. See
48 Documentation/ide.txt for up-to-date information on the ide
49 driver.
50
511. Make sure that the ide and ide-cd drivers are compiled into the
52 kernel you're using. When configuring the kernel, in the section
53 entitled "Floppy, IDE, and other block devices", say either `Y'
54 (which will compile the support directly into the kernel) or `M'
55 (to compile support as a module which can be loaded and unloaded)
56 to the options:
57
58 Enhanced IDE/MFM/RLL disk/cdrom/tape/floppy support
59 Include IDE/ATAPI CDROM support
60
61 and `no' to
62
63 Use old disk-only driver on primary interface
64
65 Depending on what type of IDE interface you have, you may need to
66 specify additional configuration options. See
67 Documentation/ide.txt.
68
692. You should also ensure that the iso9660 filesystem is either
70 compiled into the kernel or available as a loadable module. You
71 can see if a filesystem is known to the kernel by catting
72 /proc/filesystems.
73
743. The CDROM drive should be connected to the host on an IDE
75 interface. Each interface on a system is defined by an I/O port
76 address and an IRQ number, the standard assignments being
77 0x1f0 and 14 for the primary interface and 0x170 and 15 for the
78 secondary interface. Each interface can control up to two devices,
79 where each device can be a hard drive, a CDROM drive, a floppy drive,
80 or a tape drive. The two devices on an interface are called `master'
81 and `slave'; this is usually selectable via a jumper on the drive.
82
83 Linux names these devices as follows. The master and slave devices
84 on the primary IDE interface are called `hda' and `hdb',
85 respectively. The drives on the secondary interface are called
86 `hdc' and `hdd'. (Interfaces at other locations get other letters
87 in the third position; see Documentation/ide.txt.)
88
89 If you want your CDROM drive to be found automatically by the
90 driver, you should make sure your IDE interface uses either the
91 primary or secondary addresses mentioned above. In addition, if
92 the CDROM drive is the only device on the IDE interface, it should
93 be jumpered as `master'. (If for some reason you cannot configure
94 your system in this manner, you can probably still use the driver.
95 You may have to pass extra configuration information to the kernel
96 when you boot, however. See Documentation/ide.txt for more
97 information.)
98
994. Boot the system. If the drive is recognized, you should see a
100 message which looks like
101
102 hdb: NEC CD-ROM DRIVE:260, ATAPI CDROM drive
103
104 If you do not see this, see section 5 below.
105
1065. You may want to create a symbolic link /dev/cdrom pointing to the
107 actual device. You can do this with the command
108
109 ln -s /dev/hdX /dev/cdrom
110
111 where X should be replaced by the letter indicating where your
112 drive is installed.
113
1146. You should be able to see any error messages from the driver with
115 the `dmesg' command.
116
117
1183. Basic usage
119--------------
120
121An ISO 9660 CDROM can be mounted by putting the disc in the drive and
122typing (as root)
123
124 mount -t iso9660 /dev/cdrom /mnt/cdrom
125
126where it is assumed that /dev/cdrom is a link pointing to the actual
127device (as described in step 5 of the last section) and /mnt/cdrom is
128an empty directory. You should now be able to see the contents of the
129CDROM under the /mnt/cdrom directory. If you want to eject the CDROM,
130you must first dismount it with a command like
131
132 umount /mnt/cdrom
133
134Note that audio CDs cannot be mounted.
135
136Some distributions set up /etc/fstab to always try to mount a CDROM
137filesystem on bootup. It is not required to mount the CDROM in this
138manner, though, and it may be a nuisance if you change CDROMs often.
139You should feel free to remove the cdrom line from /etc/fstab and
140mount CDROMs manually if that suits you better.
141
142Multisession and photocd discs should work with no special handling.
143The hpcdtoppm package (ftp.gwdg.de:/pub/linux/hpcdtoppm/) may be
144useful for reading photocds.
145
146To play an audio CD, you should first unmount and remove any data
147CDROM. Any of the CDROM player programs should then work (workman,
148workbone, cdplayer, etc.). Lacking anything else, you could use the
149cdtester program in Documentation/cdrom/sbpcd.
150
151On a few drives, you can read digital audio directly using a program
152such as cdda2wav. The only types of drive which I've heard support
153this are Sony and Toshiba drives. You will get errors if you try to
154use this function on a drive which does not support it.
155
156For supported changers, you can use the `cdchange' program (appended to
157the end of this file) to switch between changer slots. Note that the
158drive should be unmounted before attempting this. The program takes
159two arguments: the CDROM device, and the slot number to which you wish
160to change. If the slot number is -1, the drive is unloaded.
161
162
1634. Compilation options
164----------------------
165
166There are a few additional options which can be set when compiling the
167driver. Most people should not need to mess with any of these; they
168are listed here simply for completeness. A compilation option can be
169enabled by adding a line of the form `#define <option> 1' to the top
170of ide-cd.c. All these options are disabled by default.
171
172VERBOSE_IDE_CD_ERRORS
173 If this is set, ATAPI error codes will be translated into textual
174 descriptions. In addition, a dump is made of the command which
175 provoked the error. This is off by default to save the memory used
176 by the (somewhat long) table of error descriptions.
177
178STANDARD_ATAPI
179 If this is set, the code needed to deal with certain drives which do
180 not properly implement the ATAPI spec will be disabled. If you know
181 your drive implements ATAPI properly, you can turn this on to get a
182 slightly smaller kernel.
183
184NO_DOOR_LOCKING
185 If this is set, the driver will never attempt to lock the door of
186 the drive.
187
188CDROM_NBLOCKS_BUFFER
189 This sets the size of the buffer to be used for a CDROMREADAUDIO
190 ioctl. The default is 8.
191
192TEST
193 This currently enables an additional ioctl which enables a user-mode
194 program to execute an arbitrary packet command. See the source for
195 details. This should be left off unless you know what you're doing.
196
197
1985. Common problems
199------------------
200
201This section discusses some common problems encountered when trying to
202use the driver, and some possible solutions. Note that if you are
203experiencing problems, you should probably also review
204Documentation/ide.txt for current information about the underlying
205IDE support code. Some of these items apply only to earlier versions
206of the driver, but are mentioned here for completeness.
207
208In most cases, you should probably check with `dmesg' for any errors
209from the driver.
210
211a. Drive is not detected during booting.
212
213 - Review the configuration instructions above and in
214 Documentation/ide.txt, and check how your hardware is
215 configured.
216
217 - If your drive is the only device on an IDE interface, it should
218 be jumpered as master, if at all possible.
219
220 - If your IDE interface is not at the standard addresses of 0x170
221 or 0x1f0, you'll need to explicitly inform the driver using a
222 lilo option. See Documentation/ide.txt. (This feature was
223 added around kernel version 1.3.30.)
224
225 - If the autoprobing is not finding your drive, you can tell the
226 driver to assume that one exists by using a lilo option of the
227 form `hdX=cdrom', where X is the drive letter corresponding to
228 where your drive is installed. Note that if you do this and you
229 see a boot message like
230
231 hdX: ATAPI cdrom (?)
232
233 this does _not_ mean that the driver has successfully detected
234 the drive; rather, it means that the driver has not detected a
235 drive, but is assuming there's one there anyway because you told
236 it so. If you actually try to do I/O to a drive defined at a
237 nonexistent or nonresponding I/O address, you'll probably get
238 errors with a status value of 0xff.
239
240 - Some IDE adapters require a nonstandard initialization sequence
241 before they'll function properly. (If this is the case, there
242 will often be a separate MS-DOS driver just for the controller.)
243 IDE interfaces on sound cards often fall into this category.
244
245 Support for some interfaces needing extra initialization is
246 provided in later 1.3.x kernels. You may need to turn on
247 additional kernel configuration options to get them to work;
248 see Documentation/ide.txt.
249
250 Even if support is not available for your interface, you may be
251 able to get it to work with the following procedure. First boot
252 MS-DOS and load the appropriate drivers. Then warm-boot linux
253 (i.e., without powering off). If this works, it can be automated
254 by running loadlin from the MS-DOS autoexec.
255
256
257b. Timeout/IRQ errors.
258
259 - If you always get timeout errors, interrupts from the drive are
260 probably not making it to the host.
261
262 - IRQ problems may also be indicated by the message
263 `IRQ probe failed (<n>)' while booting. If <n> is zero, that
264 means that the system did not see an interrupt from the drive when
265 it was expecting one (on any feasible IRQ). If <n> is negative,
266 that means the system saw interrupts on multiple IRQ lines, when
267 it was expecting to receive just one from the CDROM drive.
268
269 - Double-check your hardware configuration to make sure that the IRQ
270 number of your IDE interface matches what the driver expects.
271 (The usual assignments are 14 for the primary (0x1f0) interface
272 and 15 for the secondary (0x170) interface.) Also be sure that
273 you don't have some other hardware which might be conflicting with
274 the IRQ you're using. Also check the BIOS setup for your system;
275 some have the ability to disable individual IRQ levels, and I've
276 had one report of a system which was shipped with IRQ 15 disabled
277 by default.
278
279 - Note that many MS-DOS CDROM drivers will still function even if
280 there are hardware problems with the interrupt setup; they
281 apparently don't use interrupts.
282
283 - If you own a Pioneer DR-A24X, you _will_ get nasty error messages
284 on boot such as "irq timeout: status=0x50 { DriveReady SeekComplete }"
285 The Pioneer DR-A24X CDROM drives are fairly popular these days.
286 Unfortunately, these drives seem to become very confused when we perform
287 the standard Linux ATA disk drive probe. If you own one of these drives,
288 you can bypass the ATA probing which confuses these CDROM drives, by
289 adding `append="hdX=noprobe hdX=cdrom"' to your lilo.conf file and running
290 lilo (again where X is the drive letter corresponding to where your drive
291 is installed.)
292
293c. System hangups.
294
295 - If the system locks up when you try to access the CDROM, the most
296 likely cause is that you have a buggy IDE adapter which doesn't
297 properly handle simultaneous transactions on multiple interfaces.
298 The most notorious of these is the CMD640B chip. This problem can
299 be worked around by specifying the `serialize' option when
300 booting. Recent kernels should be able to detect the need for
301 this automatically in most cases, but the detection is not
302 foolproof. See Documentation/ide.txt for more information
303 about the `serialize' option and the CMD640B.
304
305 - Note that many MS-DOS CDROM drivers will work with such buggy
306 hardware, apparently because they never attempt to overlap CDROM
307 operations with other disk activity.
308
309
310d. Can't mount a CDROM.
311
312 - If you get errors from mount, it may help to check `dmesg' to see
313 if there are any more specific errors from the driver or from the
314 filesystem.
315
316 - Make sure there's a CDROM loaded in the drive, and that's it's an
317 ISO 9660 disc. You can't mount an audio CD.
318
319 - With the CDROM in the drive and unmounted, try something like
320
321 cat /dev/cdrom | od | more
322
323 If you see a dump, then the drive and driver are probably working
324 OK, and the problem is at the filesystem level (i.e., the CDROM is
325 not ISO 9660 or has errors in the filesystem structure).
326
327 - If you see `not a block device' errors, check that the definitions
328 of the device special files are correct. They should be as
329 follows:
330
331 brw-rw---- 1 root disk 3, 0 Nov 11 18:48 /dev/hda
332 brw-rw---- 1 root disk 3, 64 Nov 11 18:48 /dev/hdb
333 brw-rw---- 1 root disk 22, 0 Nov 11 18:48 /dev/hdc
334 brw-rw---- 1 root disk 22, 64 Nov 11 18:48 /dev/hdd
335
336 Some early Slackware releases had these defined incorrectly. If
337 these are wrong, you can remake them by running the script
338 scripts/MAKEDEV.ide. (You may have to make it executable
339 with chmod first.)
340
341 If you have a /dev/cdrom symbolic link, check that it is pointing
342 to the correct device file.
343
344 If you hear people talking of the devices `hd1a' and `hd1b', these
345 were old names for what are now called hdc and hdd. Those names
346 should be considered obsolete.
347
348 - If mount is complaining that the iso9660 filesystem is not
349 available, but you know it is (check /proc/filesystems), you
350 probably need a newer version of mount. Early versions would not
351 always give meaningful error messages.
352
353
354e. Directory listings are unpredictably truncated, and `dmesg' shows
355 `buffer botch' error messages from the driver.
356
357 - There was a bug in the version of the driver in 1.2.x kernels
358 which could cause this. It was fixed in 1.3.0. If you can't
359 upgrade, you can probably work around the problem by specifying a
360 blocksize of 2048 when mounting. (Note that you won't be able to
361 directly execute binaries off the CDROM in that case.)
362
363 If you see this in kernels later than 1.3.0, please report it as a
364 bug.
365
366
367f. Data corruption.
368
369 - Random data corruption was occasionally observed with the Hitachi
370 CDR-7730 CDROM. If you experience data corruption, using "hdx=slow"
371 as a command line parameter may work around the problem, at the
372 expense of low system performance.
373
374
3756. cdchange.c
376-------------
377
378/*
379 * cdchange.c [-v] <device> [<slot>]
380 *
381 * This loads a CDROM from a specified slot in a changer, and displays
382 * information about the changer status. The drive should be unmounted before
383 * using this program.
384 *
385 * Changer information is displayed if either the -v flag is specified
386 * or no slot was specified.
387 *
388 * Based on code originally from Gerhard Zuber <zuber@berlin.snafu.de>.
389 * Changer status information, and rewrite for the new Uniform CDROM driver
390 * interface by Erik Andersen <andersee@debian.org>.
391 */
392
393#include <stdio.h>
394#include <stdlib.h>
395#include <errno.h>
396#include <string.h>
397#include <unistd.h>
398#include <fcntl.h>
399#include <sys/ioctl.h>
400#include <linux/cdrom.h>
401
402
403int
404main (int argc, char **argv)
405{
406 char *program;
407 char *device;
408 int fd; /* file descriptor for CD-ROM device */
409 int status; /* return status for system calls */
410 int verbose = 0;
411 int slot=-1, x_slot;
412 int total_slots_available;
413
414 program = argv[0];
415
416 ++argv;
417 --argc;
418
419 if (argc < 1 || argc > 3) {
420 fprintf (stderr, "usage: %s [-v] <device> [<slot>]\n",
421 program);
422 fprintf (stderr, " Slots are numbered 1 -- n.\n");
423 exit (1);
424 }
425
426 if (strcmp (argv[0], "-v") == 0) {
427 verbose = 1;
428 ++argv;
429 --argc;
430 }
431
432 device = argv[0];
433
434 if (argc == 2)
435 slot = atoi (argv[1]) - 1;
436
437 /* open device */
438 fd = open(device, O_RDONLY | O_NONBLOCK);
439 if (fd < 0) {
440 fprintf (stderr, "%s: open failed for `%s': %s\n",
441 program, device, strerror (errno));
442 exit (1);
443 }
444
445 /* Check CD player status */
446 total_slots_available = ioctl (fd, CDROM_CHANGER_NSLOTS);
447 if (total_slots_available <= 1 ) {
448 fprintf (stderr, "%s: Device `%s' is not an ATAPI "
449 "compliant CD changer.\n", program, device);
450 exit (1);
451 }
452
453 if (slot >= 0) {
454 if (slot >= total_slots_available) {
455 fprintf (stderr, "Bad slot number. "
456 "Should be 1 -- %d.\n",
457 total_slots_available);
458 exit (1);
459 }
460
461 /* load */
462 slot=ioctl (fd, CDROM_SELECT_DISC, slot);
463 if (slot<0) {
464 fflush(stdout);
465 perror ("CDROM_SELECT_DISC ");
466 exit(1);
467 }
468 }
469
470 if (slot < 0 || verbose) {
471
472 status=ioctl (fd, CDROM_SELECT_DISC, CDSL_CURRENT);
473 if (status<0) {
474 fflush(stdout);
475 perror (" CDROM_SELECT_DISC");
476 exit(1);
477 }
478 slot=status;
479
480 printf ("Current slot: %d\n", slot+1);
481 printf ("Total slots available: %d\n",
482 total_slots_available);
483
484 printf ("Drive status: ");
485 status = ioctl (fd, CDROM_DRIVE_STATUS, CDSL_CURRENT);
486 if (status<0) {
487 perror(" CDROM_DRIVE_STATUS");
488 } else switch(status) {
489 case CDS_DISC_OK:
490 printf ("Ready.\n");
491 break;
492 case CDS_TRAY_OPEN:
493 printf ("Tray Open.\n");
494 break;
495 case CDS_DRIVE_NOT_READY:
496 printf ("Drive Not Ready.\n");
497 break;
498 default:
499 printf ("This Should not happen!\n");
500 break;
501 }
502
503 for (x_slot=0; x_slot<total_slots_available; x_slot++) {
504 printf ("Slot %2d: ", x_slot+1);
505 status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot);
506 if (status<0) {
507 perror(" CDROM_DRIVE_STATUS");
508 } else switch(status) {
509 case CDS_DISC_OK:
510 printf ("Disc present.");
511 break;
512 case CDS_NO_DISC:
513 printf ("Empty slot.");
514 break;
515 case CDS_TRAY_OPEN:
516 printf ("CD-ROM tray open.\n");
517 break;
518 case CDS_DRIVE_NOT_READY:
519 printf ("CD-ROM drive not ready.\n");
520 break;
521 case CDS_NO_INFO:
522 printf ("No Information available.");
523 break;
524 default:
525 printf ("This Should not happen!\n");
526 break;
527 }
528 if (slot == x_slot) {
529 status = ioctl (fd, CDROM_DISC_STATUS);
530 if (status<0) {
531 perror(" CDROM_DISC_STATUS");
532 }
533 switch (status) {
534 case CDS_AUDIO:
535 printf ("\tAudio disc.\t");
536 break;
537 case CDS_DATA_1:
538 case CDS_DATA_2:
539 printf ("\tData disc type %d.\t", status-CDS_DATA_1+1);
540 break;
541 case CDS_XA_2_1:
542 case CDS_XA_2_2:
543 printf ("\tXA data disc type %d.\t", status-CDS_XA_2_1+1);
544 break;
545 default:
546 printf ("\tUnknown disc type 0x%x!\t", status);
547 break;
548 }
549 }
550 status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot);
551 if (status<0) {
552 perror(" CDROM_MEDIA_CHANGED");
553 }
554 switch (status) {
555 case 1:
556 printf ("Changed.\n");
557 break;
558 default:
559 printf ("\n");
560 break;
561 }
562 }
563 }
564
565 /* close device */
566 status = close (fd);
567 if (status != 0) {
568 fprintf (stderr, "%s: close failed for `%s': %s\n",
569 program, device, strerror (errno));
570 exit (1);
571 }
572
573 exit (0);
574}
diff --git a/Documentation/cdrom/isp16 b/Documentation/cdrom/isp16
new file mode 100644
index 000000000000..cc86533ac9f3
--- /dev/null
+++ b/Documentation/cdrom/isp16
@@ -0,0 +1,100 @@
1 -- Documentation/cdrom/isp16
2
3Docs by Eric van der Maarel <H.T.M.v.d.Maarel@marin.nl>
4
5This is the README for version 0.6 of the cdrom interface on an
6ISP16, MAD16 or Mozart sound card.
7
8The detection and configuration of this interface used to be included
9in both the sjcd and optcd cdrom driver. Drives supported by these
10drivers came packed with Media Magic's multi media kit, which also
11included the ISP16 card. The idea (thanks Leo Spiekman)
12to move it from these drivers into a separate module and moreover, not to
13rely on the MAD16 sound driver, are as follows:
14-duplication of code in the kernel is a waste of resources and should
15 be avoided;
16-however, kernels and notably those included with Linux distributions
17 (cf Slackware 3.0 included version 0.5 of the isp16 configuration
18 code included in the drivers) don't always come with sound support
19 included. Especially when they already include a bunch of cdrom drivers.
20 Hence, the cdrom interface should be configurable _independently_ of
21 sound support.
22
23The ISP16, MAD16 and Mozart sound cards have an OPTi 82C928 or an
24OPTi 82C929 chip. The interface on these cards should work with
25any cdrom attached to the card, which is 'electrically' compatible
26with Sanyo/Panasonic, Sony or Mitsumi non-ide drives. However, the
27command sets for any proprietary drives may differ
28(and hence may not be supported in the kernel) from these four types.
29For a fact I know the interface works and the way of configuration
30as described in this documentation works in combination with the
31sjcd (in Sanyo/Panasonic compatibility mode) cdrom drivers
32(probably with the optcd (in Sony compatibility mode) as well).
33If you have such an OPTi based sound card and you want to use the
34cdrom interface with a cdrom drive supported by any of the other cdrom
35drivers, it will probably work. Please let me know any experience you
36might have).
37I understand that cards based on the OPTi 82C929 chips may be configured
38(hardware jumpers that is) as an IDE interface. Initialisation of such a
39card in this mode is not supported (yet?).
40
41The suggestion to configure the ISP16 etc. sound card by booting DOS and
42do a warm reboot to boot Linux somehow doesn't work, at least not
43on my machine (IPC P90), with the OPTi 82C928 based card.
44
45Booting the kernel through the boot manager LILO allows the use
46of some command line options on the 'LILO boot:' prompt. At boot time
47press Alt or Shift while the LILO prompt is written on the screen and enter
48any kernel options. Alternatively these options may be used in
49the appropriate section in /etc/lilo.conf. Adding 'append="<cmd_line_options>"'
50will do the trick as well.
51The syntax of 'cmd_line_options' is
52
53 isp16=[<port>[,<irq>[,<dma>]]][[,]<drive_type>]
54
55If there is no ISP16 or compatibles detected, there's probably no harm done.
56These options indicate the values that your cdrom drive has been (or will be)
57configured to use.
58Valid values for the base i/o address are:
59 port=0x340,0x320,0x330,0x360
60for the interrupt request number
61 irq=0,3,5,7,9,10,11
62for the direct memory access line
63 dma=0,3,5,6,7
64and for the type of drive
65 drive_type=noisp16,Sanyo,Panasonic,Sony,Mitsumi.
66Note that these options are case sensitive.
67The values 0 for irq and dma indicate that they are not used, and
68the drive will be used in 'polling' mode. The values 5 and 7 for irq
69should be avoided in order to avoid any conflicts with optional
70sound card configuration.
71The syntax of the command line does not allow the specification of
72irq when there's nothing specified for the base address and no
73specification of dma when there is no specification of irq.
74The value 'noisp16' for drive_type, which may be used as the first
75non-integer option value (e.g. 'isp16=noisp16'), makes sure that probing
76for and subsequent configuration of an ISP16-compatible card is skipped
77all together. This can be useful to overcome possible conflicts which
78may arise while the kernel is probing your hardware.
79The default values are
80 port=0x340
81 irq=0
82 dma=0
83 drive_type=Sanyo
84reflecting my own configuration. The defaults can be changed in
85the file linux/drivers/cdrom/ips16.h.
86
87The cdrom interface can be configured at run time by loading the
88initialisation driver as a module. In that case, the interface
89parameters can be set by giving appropriate values on the command
90line. Configuring the driver can then be done by the following
91command (assuming you have iso16.o installed in a proper place):
92
93 insmod isp16.o isp16_cdrom_base=<port> isp16_cdrom_irq=<irq> \
94 isp16_cdrom_dma=<dma> isp16_cdrom_type=<drive_type>
95
96where port, irq, dma and drive_type can have any of the values mentioned
97above.
98
99
100Have fun!
diff --git a/Documentation/cdrom/mcdx b/Documentation/cdrom/mcdx
new file mode 100644
index 000000000000..2bac4b7ff6da
--- /dev/null
+++ b/Documentation/cdrom/mcdx
@@ -0,0 +1,29 @@
1If you are using the driver as a module, you can specify your ports and IRQs
2like
3
4 # insmod mcdx.o mcdx=0x300,11,0x304,5
5
6and so on ("address,IRQ" pairs).
7This will override the configuration in mcdx.h.
8
9This driver:
10
11 o handles XA and (hopefully) multi session CDs as well as
12 ordinary CDs;
13 o supports up to 5 drives (of course, you'll need free
14 IRQs, i/o ports and slots);
15 o plays audio
16
17This version doesn't support yet:
18
19 o shared IRQs (but it seems to be possible - I've successfully
20 connected two drives to the same irq. So it's `only' a
21 problem of the driver.)
22
23This driver never will:
24
25 o Read digital audio (i.e. copy directly), due to missing
26 hardware features.
27
28
29heiko@lotte.sax.de
diff --git a/Documentation/cdrom/optcd b/Documentation/cdrom/optcd
new file mode 100644
index 000000000000..6f46c7adb243
--- /dev/null
+++ b/Documentation/cdrom/optcd
@@ -0,0 +1,57 @@
1This is the README file for the Optics Storage 8000 AT CDROM device driver.
2
3This is the driver for the so-called 'DOLPHIN' drive, with the 34-pin
4Sony-compatible interface. For the IDE-compatible Optics Storage 8001
5drive, you will want the ATAPI CDROM driver. The driver also seems to
6work with the Lasermate CR328A. If you have a drive that works with
7this driver, and that doesn't report itself as DOLPHIN, please drop me
8a mail.
9
10The support for multisession CDs is in ALPHA stage. If you use it,
11please mail me your experiences. Multisession support can be disabled
12at compile time.
13
14You can find some older versions of the driver at
15 dutette.et.tudelft.nl:/pub/linux/
16and at Eberhard's mirror
17 ftp.gwdg.de:/pub/linux/cdrom/drivers/optics/
18
19Before you can use the driver, you have to create the device file once:
20 # mknod /dev/optcd0 b 17 0
21
22To specify the base address if the driver is "compiled-in" to your kernel,
23you can use the kernel command line item (LILO option)
24 optcd=0x340
25with the right address.
26
27If you have compiled optcd as a module, you can load it with
28 # insmod /usr/src/linux/modules/optcd.o
29or
30 # insmod /usr/src/linux/modules/optcd.o optcd=0x340
31with the matching address value of your interface card.
32
33The driver employs a number of buffers to do read-ahead and block size
34conversion. The number of buffers is configurable in optcd.h, and has
35influence on the driver performance. For my machine (a P75), 6 buffers
36seems optimal, as can be seen from this table:
37
38#bufs kb/s %cpu
391 97 0.1
402 191 0.3
413 188 0.2
424 246 0.3
435 189 19
446 280 0.4
457 281 7.0
468 246 2.8
4716 281 3.4
48
49If you get a throughput significantly below 300 kb/s, try tweaking
50N_BUFS, and don't forget to mail me your results!
51
52I'd appreciate success/failure reports. If you find a bug, try
53recompiling the driver with some strategically chosen debug options
54(these can be found in optcd.h) and include the messages generated in
55your bug report. Good luck.
56
57Leo Spiekman (spiekman@dutette.et.tudelft.nl)
diff --git a/Documentation/cdrom/packet-writing.txt b/Documentation/cdrom/packet-writing.txt
new file mode 100644
index 000000000000..3d44c561fe6d
--- /dev/null
+++ b/Documentation/cdrom/packet-writing.txt
@@ -0,0 +1,97 @@
1Getting started quick
2---------------------
3
4- Select packet support in the block device section and UDF support in
5 the file system section.
6
7- Compile and install kernel and modules, reboot.
8
9- You need the udftools package (pktsetup, mkudffs, cdrwtool).
10 Download from http://sourceforge.net/projects/linux-udf/
11
12- Grab a new CD-RW disc and format it (assuming CD-RW is hdc, substitute
13 as appropriate):
14 # cdrwtool -d /dev/hdc -q
15
16- Setup your writer
17 # pktsetup dev_name /dev/hdc
18
19- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy!
20 # mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
21
22
23Packet writing for DVD-RW media
24-------------------------------
25
26DVD-RW discs can be written to much like CD-RW discs if they are in
27the so called "restricted overwrite" mode. To put a disc in restricted
28overwrite mode, run:
29
30 # dvd+rw-format /dev/hdc
31
32You can then use the disc the same way you would use a CD-RW disc:
33
34 # pktsetup dev_name /dev/hdc
35 # mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
36
37
38Packet writing for DVD+RW media
39-------------------------------
40
41According to the DVD+RW specification, a drive supporting DVD+RW discs
42shall implement "true random writes with 2KB granularity", which means
43that it should be possible to put any filesystem with a block size >=
442KB on such a disc. For example, it should be possible to do:
45
46 # dvd+rw-format /dev/hdc (only needed if the disc has never
47 been formatted)
48 # mkudffs /dev/hdc
49 # mount /dev/hdc /cdrom -t udf -o rw,noatime
50
51However, some drives don't follow the specification and expect the
52host to perform aligned writes at 32KB boundaries. Other drives do
53follow the specification, but suffer bad performance problems if the
54writes are not 32KB aligned.
55
56Both problems can be solved by using the pktcdvd driver, which always
57generates aligned writes.
58
59 # dvd+rw-format /dev/hdc
60 # pktsetup dev_name /dev/hdc
61 # mkudffs /dev/pktcdvd/dev_name
62 # mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
63
64
65Packet writing for DVD-RAM media
66--------------------------------
67
68DVD-RAM discs are random writable, so using the pktcdvd driver is not
69necessary. However, using the pktcdvd driver can improve performance
70in the same way it does for DVD+RW media.
71
72
73Notes
74-----
75
76- CD-RW media can usually not be overwritten more than about 1000
77 times, so to avoid unnecessary wear on the media, you should always
78 use the noatime mount option.
79
80- Defect management (ie automatic remapping of bad sectors) has not
81 been implemented yet, so you are likely to get at least some
82 filesystem corruption if the disc wears out.
83
84- Since the pktcdvd driver makes the disc appear as a regular block
85 device with a 2KB block size, you can put any filesystem you like on
86 the disc. For example, run:
87
88 # /sbin/mke2fs /dev/pktcdvd/dev_name
89
90 to create an ext2 filesystem on the disc.
91
92
93Links
94-----
95
96See http://fy.chalmers.se/~appro/linux/DVD+RW/ for more information
97about DVD writing.
diff --git a/Documentation/cdrom/sbpcd b/Documentation/cdrom/sbpcd
new file mode 100644
index 000000000000..d1825dffca34
--- /dev/null
+++ b/Documentation/cdrom/sbpcd
@@ -0,0 +1,1057 @@
1This README belongs to release 4.2 or newer of the SoundBlaster Pro
2(Matsushita, Kotobuki, Panasonic, CreativeLabs, Longshine and Teac)
3CD-ROM driver for Linux.
4
5sbpcd really, really is NOT for ANY IDE/ATAPI drive!
6Not even if you have an "original" SoundBlaster card with an IDE interface!
7So, you'd better have a look into README.ide if your port address is 0x1F0,
80x170, 0x1E8, 0x168 or similar.
9I get tons of mails from IDE/ATAPI drive users - I really can't continue
10any more to answer them all. So, if your drive/interface information sheets
11mention "IDE" (primary, secondary, tertiary, quaternary) and the DOS driver
12invoking line within your CONFIG.SYS is using an address below 0x230:
13DON'T ROB MY LAST NERVE - jumper your interface to address 0x170 and IRQ 15
14(that is the "secondary IDE" configuration), set your drive to "master" and
15use ide-cd as your driver. If you do not have a second IDE hard disk, use the
16LILO commands
17 hdb=noprobe hdc=cdrom
18and get lucky.
19To make it fully clear to you: if you mail me about IDE/ATAPI drive problems,
20my answer is above, and I simply will discard your mail, hoping to stop the
21flood and to find time to lead my 12-year old son towards happy computing.
22
23The driver is able to drive the whole family of "traditional" AT-style (that
24is NOT the new "Enhanced IDE" or "ATAPI" drive standard) Matsushita,
25Kotobuki, Panasonic drives, sometimes labelled as "CreativeLabs". The
26well-known drives are CR-521, CR-522, CR-523, CR-562, CR-563.
27CR-574 is an IDE/ATAPI drive.
28
29The Longshine LCS-7260 is a double-speed drive which uses the "old"
30Matsushita command set. It is supported - with help by Serge Robyns.
31Vertos ("Elitegroup Computer Systems", ECS) has a similar drive - support
32has started; get in contact if you have such a "Vertos 100" or "ECS-AT"
33drive.
34
35There exists an "IBM External ISA CD-ROM Drive" which in fact is a CR-563
36with a special controller board. This drive is supported (the interface is
37of the "LaserMate" type), and it is possibly the best buy today (cheaper than
38an internal drive, and you can use it as an internal, too - e.g. plug it into
39a soundcard).
40
41CreativeLabs has a new drive "CD200" and a similar drive "CD200F". The latter
42is made by Funai and sometimes named "E2550UA", newer models may be named
43"MK4015". The CD200F drives should fully work.
44CD200 drives without "F" are still giving problems: drive detection and
45playing audio should work, data access will result in errors. I need qualified
46feedback about the bugs within the data functions or a drive (I never saw a
47CD200).
48
49The quad-speed Teac CD-55A drive is supported, but still does not reach "full
50speed". The data rate already reaches 500 kB/sec if you set SBP_BUFFER_FRAMES
51to 64 (it is not recommended to do that for normal "file access" usage, but it
52can speed up things a lot if you use something like "dd" to read from the
53drive; I use it for verifying self-written CDs this way).
54The drive itself is able to deliver 600 kB/sec, so this needs
55work; with the normal setup, the performance currently is not even as good as
56double-speed.
57
58This driver is NOT for Mitsumi or Sony or Aztech or Philips or XXX drives,
59and again: this driver is in no way usable for any IDE/ATAPI drive. If you
60think your drive should work and it doesn't: send me the DOS driver for your
61beast (gzipped + uuencoded) and your CONFIG.SYS if you want to ask me for help,
62and include an original log message excerpt, and try to give all information
63a complete idiot needs to understand your hassle already with your first
64mail. And if you want to say "as I have mailed you before", be sure that I
65don't remember your "case" by such remarks; at the moment, I have some
66hundreds of open correspondences about Linux CDROM questions (hope to reduce if
67the IDE/ATAPI user questions disappear).
68
69
70This driver will work with the soundcard interfaces (SB Pro, SB 16, Galaxy,
71SoundFX, Mozart, MAD16 ...) and with the "no-sound" cards (Panasonic CI-101P,
72LaserMate, WDH-7001C, Longshine LCS-6853, Teac ...).
73
74It works with the "configurable" interface "Sequoia S-1000", too, which is
75used on the Spea Media FX and Ensonic Soundscape sound cards. You have to
76specify the type "SBPRO 2" and the true CDROM port address with it, not the
77"configuration port" address.
78
79If you have a sound card which needs a "configuration driver" instead of
80jumpers for interface types and addresses (like Mozart cards) - those
81drivers get invoked before the DOS CDROM driver in your CONFIG.SYS, typical
82names are "cdsetup.sys" and "mztinit.sys" - let the sound driver do the
83CDROM port configuration (the leading comments in linux/drivers/sound/mad16.c
84are just for you!). Hannu Savolainen's mad16.c code is able to set up my
85Mozart card - I simply had to add
86 #define MAD16_CONF 0x06
87 #define MAD16_CDSEL 0x03
88to configure the CDROM interface for type "Panasonic" (LaserMate) and address
890x340.
90
91The interface type has to get configured in linux/drivers/cdrom/sbpcd.h,
92because the register layout is different between the "SoundBlaster" and the
93"LaserMate" type.
94
95I got a report that the Teac interface card "I/F E117098" is of type
96"SoundBlaster" (i.e. you have to set SBPRO to 1) even with the addresses
970x300 and above. This is unusual, and it can't get covered by the auto
98probing scheme.
99The Teac 16-bit interface cards (like P/N E950228-00A, default address 0x2C0)
100need the SBPRO 3 setup.
101
102If auto-probing found the drive, the address is correct. The reported type
103may be wrong. A "mount" will give success only if the interface type is set
104right. Playing audio should work with a wrong set interface type, too.
105
106With some Teac and some CD200 drives I have seen interface cards which seem
107to lack the "drive select" lines; always drive 0 gets addressed. To avoid
108"mirror drives" (four drives detected where you only have one) with such
109interface cards, set MAX_DRIVES to 1 and jumper your drive to ID 0 (if
110possible).
111
112
113Up to 4 drives per interface card, and up to 4 interface cards are supported.
114All supported drive families can be mixed, but the CR-521 drives are
115hard-wired to drive ID 0. The drives have to use different drive IDs, and each
116drive has to get a unique minor number (0...3), corresponding indirectly to
117its drive ID.
118The drive IDs may be selected freely from 0 to 3 - they do not have to be in
119consecutive order.
120
121As Don Carroll, don@ds9.us.dell.com or FIDO 1:382/14, told me, it is possible
122to change old drives to any ID, too. He writes in this sense:
123 "In order to be able to use more than one single speed drive
124 (they do not have the ID jumpers) you must add a DIP switch
125 and two resistors. The pads are already on the board next to
126 the power connector. You will see the silkscreen for the
127 switch if you remove the top cover.
128 1 2 3 4
129 ID 0 = x F F x O = "on"
130 ID 1 = x O F x F = "off"
131 ID 2 = x F O x x = "don't care"
132 ID 3 = x O O x
133 Next to the switch are the positions for R76 (7k) and R78
134 (12k). I had to play around with the resistor values - ID 3
135 did not work with other values. If the values are not good,
136 ID 3 behaves like ID 0."
137
138To use more than 4 drives, you simply need a second controller card at a
139different address and a second cable.
140
141The driver supports reading of data from the CD and playing of audio tracks.
142The audio part should run with WorkMan, xcdplayer, with the "non-X11" products
143CDplayer and WorkBone - tell me if it is not compatible with other software.
144The only accepted measure for correctness with the audio functions is the
145"cdtester" utility (appended) - most audio player programmers seem to be
146better musicians than programmers. ;-)
147
148With the CR-56x and the CD200 drives, the reading of audio frames is possible.
149This is implemented by an IOCTL function which reads READ_AUDIO frames of
1502352 bytes at once (configurable with the "READ_AUDIO" define, default is 0).
151Reading the same frame a second time gives different data; the frame data
152start at a different position, but all read bytes are valid, and we always
153read 98 consecutive chunks (of 24 Bytes) as a frame. Reading more than 1 frame
154at once possibly misses some chunks at each frame boundary. This lack has to
155get corrected by external, "higher level" software which reads the same frame
156again and tries to find and eliminate overlapping chunks (24-byte-pieces).
157
158The transfer rate with reading audio (1-frame-pieces) currently is very slow.
159This can be better reading bigger chunks, but the "missing" chunks possibly
160occur at the beginning of each single frame.
161The software interface possibly may change a bit the day the SCSI driver
162supports it too.
163
164With all but the CR-52x drives, MultiSession is supported.
165Photo CDs work (the "old" drives like CR-521 can access only the first
166session of a photoCD).
167At ftp.gwdg.de:/pub/linux/hpcdtoppm/ you will find Hadmut Danisch's package to
168convert photo CD image files and Gerd Knorr's viewing utility.
169
170The transfer rate will reach 150 kB/sec with CR-52x drives, 300 kB/sec with
171CR-56x drives, and currently not more than 500 kB/sec (usually less than
172250 kB/sec) with the Teac quad speed drives.
173XA (PhotoCD) disks with "old" drives give only 50 kB/sec.
174
175This release consists of
176- this README file
177- the driver file linux/drivers/cdrom/sbpcd.c
178- the stub files linux/drivers/cdrom/sbpcd[234].c
179- the header file linux/drivers/cdrom/sbpcd.h.
180
181
182To install:
183-----------
184
1851. Setup your hardware parameters. Though the driver does "auto-probing" at a
186 lot of (not all possible!) addresses, this step is recommended for
187 everyday use. You should let sbpcd auto-probe once and use the reported
188 address if a drive got found. The reported type may be incorrect; it is
189 correct if you can mount a data CD. There is no choice for you with the
190 type; only one is right, the others are deadly wrong.
191
192 a. Go into /usr/src/linux/drivers/cdrom/sbpcd.h and configure it for your
193 hardware (near the beginning):
194 a1. Set it up for the appropriate type of interface board.
195 "Original" CreativeLabs sound cards need "SBPRO 1".
196 Most "compatible" sound cards (almost all "non-CreativeLabs" cards)
197 need "SBPRO 0".
198 The "no-sound" board from OmniCd needs the "SBPRO 1" setup.
199 The Teac 8-bit "no-sound" boards need the "SBPRO 1" setup.
200 The Teac 16-bit "no-sound" boards need the "SBPRO 3" setup.
201 All other "no-sound" boards need the "SBPRO 0" setup.
202 The Spea Media FX and Ensoniq SoundScape cards need "SBPRO 2".
203 sbpcd.c holds some examples in its auto-probe list.
204 If you configure "SBPRO" wrong, the playing of audio CDs will work,
205 but you will not be able to mount a data CD.
206 a2. Tell the address of your CDROM_PORT (not of the sound port).
207 a3. If 4 drives get found, but you have only one, set MAX_DRIVES to 1.
208 a4. Set DISTRIBUTION to 0.
209 b. Additionally for 2.a1 and 2.a2, the setup may be done during
210 boot time (via the "kernel command line" or "LILO option"):
211 sbpcd=0x320,LaserMate
212 or
213 sbpcd=0x230,SoundBlaster
214 or
215 sbpcd=0x338,SoundScape
216 or
217 sbpcd=0x2C0,Teac16bit
218 This is especially useful if you install a fresh distribution.
219 If the second parameter is a number, it gets taken as the type
220 setting; 0 is "LaserMate", 1 is "SoundBlaster", 2 is "SoundScape",
221 3 is "Teac16bit".
222 So, for example
223 sbpcd=0x230,1
224 is equivalent to
225 sbpcd=0x230,SoundBlaster
226
2272. "cd /usr/src/linux" and do a "make config" and select "y" for Matsushita
228 CD-ROM support and for ISO9660 FileSystem support. If you do not have a
229 second, third, or fourth controller installed, do not say "y" to the
230 secondary Matsushita CD-ROM questions.
231
2323. Then make the kernel image ("make zlilo" or similar).
233
2344. Make the device file(s). This step usually already has been done by the
235 MAKEDEV script.
236 The driver uses MAJOR 25, so, if necessary, do
237 mknod /dev/sbpcd b 25 0 (if you have only one drive)
238 and/or
239 mknod /dev/sbpcd0 b 25 0
240 mknod /dev/sbpcd1 b 25 1
241 mknod /dev/sbpcd2 b 25 2
242 mknod /dev/sbpcd3 b 25 3
243 to make the node(s).
244
245 The "first found" drive gets MINOR 0 (regardless of its jumpered ID), the
246 "next found" (at the same cable) gets MINOR 1, ...
247
248 For a second interface board, you have to make nodes like
249 mknod /dev/sbpcd4 b 26 0
250 mknod /dev/sbpcd5 b 26 1
251 and so on. Use the MAJORs 26, 27, 28.
252
253 If you further make a link like
254 ln -s sbpcd /dev/cdrom
255 you can use the name /dev/cdrom, too.
256
2575. Reboot with the new kernel.
258
259You should now be able to do
260 mkdir /CD
261and
262 mount -rt iso9660 /dev/sbpcd /CD
263or
264 mount -rt iso9660 -o block=2048 /dev/sbpcd /CD
265and see the contents of your CD in the /CD directory.
266To use audio CDs, a mounting is not recommended (and it would fail if the
267first track is not a data track).
268
269
270Using sbpcd as a "loadable module":
271-----------------------------------
272
273If you do NOT select "Matsushita/Panasonic CDROM driver support" during the
274"make config" of your kernel, you can build the "loadable module" sbpcd.o.
275
276If sbpcd gets used as a module, the support of more than one interface
277card (i.e. drives 4...15) is disabled.
278
279You can specify interface address and type with the "insmod" command like:
280 # insmod /usr/src/linux/modules/sbpcd.o sbpcd=0x340,0
281or
282 # insmod /usr/src/linux/modules/sbpcd.o sbpcd=0x230,1
283or
284 # insmod /usr/src/linux/modules/sbpcd.o sbpcd=0x338,2
285where the last number represents the SBPRO setting (no strings allowed here).
286
287
288Things of interest:
289-------------------
290
291The driver is configured to try the LaserMate type of interface at I/O port
2920x0340 first. If this is not appropriate, sbpcd.h should get changed
293(you will find the right place - just at the beginning).
294
295No DMA and no IRQ is used.
296
297To reduce or increase the amount of kernel messages, edit sbpcd.c and play
298with the "DBG_xxx" switches (initialization of the variable "sbpcd_debug").
299Don't forget to reflect on what you do; enabling all DBG_xxx switches at once
300may crash your system, and each message line is accompanied by a delay.
301
302The driver uses the "variable BLOCK_SIZE" feature. To use it, you have to
303specify "block=2048" as a mount option. Doing this will disable the direct
304execution of a binary from the CD; you have to copy it to a device with the
305standard BLOCK_SIZE (1024) first. So, do not use this if your system is
306directly "running from the CDROM" (like some of Yggdrasil's installation
307variants). There are CDs on the market (like the German "unifix" Linux
308distribution) which MUST get handled with a block_size of 1024. Generally,
309one can say all the CDs which hold files of the name YMTRANS.TBL are defective;
310do not use block=2048 with those.
311
312Within sbpcd.h, you will find some "#define"s (e.g. EJECT and JUKEBOX). With
313these, you can configure the driver for some special things.
314You can use the appended program "cdtester" to set the auto-eject feature
315during runtime. Jeff Tranter's "eject" utility can do this, too (and more)
316for you.
317
318There is an ioctl CDROMMULTISESSION to obtain with a user program if
319the CD is an XA disk and - if it is - where the last session starts. The
320"cdtester" program illustrates how to call it.
321
322
323Auto-probing at boot time:
324--------------------------
325
326The driver does auto-probing at many well-known interface card addresses,
327but not all:
328Some probings can cause a hang if an NE2000 ethernet card gets touched, because
329SBPCD's auto-probing happens before the initialization of the net drivers.
330Those "hazardous" addresses are excluded from auto-probing; the "kernel
331command line" feature has to be used during installation if you have your
332drive at those addresses. The "module" version is allowed to probe at those
333addresses, too.
334
335The auto-probing looks first at the configured address resp. the address
336submitted by the kernel command line. With this, it is possible to use this
337driver within installation boot floppies, and for any non-standard address,
338too.
339
340Auto-probing will make an assumption about the interface type ("SBPRO" or not),
341based upon the address. That assumption may be wrong (initialization will be
342o.k., but you will get I/O errors during mount). In that case, use the "kernel
343command line" feature and specify address & type at boot time to find out the
344right setup.
345
346For everyday use, address and type should get configured within sbpcd.h. That
347will stop the auto-probing due to success with the first try.
348
349The kernel command "sbpcd=0" suppresses each auto-probing and causes
350the driver not to find any drive; it is meant for people who love sbpcd
351so much that they do not want to miss it, even if they miss the drives. ;-)
352
353If you configure "#define CDROM_PORT 0" in sbpcd.h, the auto-probing is
354initially disabled and needs an explicit kernel command to get activated.
355Once activated, it does not stop before success or end-of-list. This may be
356useful within "universal" CDROM installation boot floppies (but using the
357loadable module would be better because it allows an "extended" auto-probing
358without fearing NE2000 cards).
359
360To shorten the auto-probing list to a single entry, set DISTRIBUTION 0 within
361sbpcd.h.
362
363
364Setting up address and interface type:
365--------------------------------------
366
367If your I/O port address is not 0x340, you have to look for the #defines near
368the beginning of sbpcd.h and configure them: set SBPRO to 0 or 1 or 2, and
369change CDROM_PORT to the address of your CDROM I/O port.
370
371Almost all of the "SoundBlaster compatible" cards behave like the no-sound
372interfaces, i.e. need SBPRO 0!
373
374With "original" SB Pro cards, an initial setting of CD_volume through the
375sound card's MIXER register gets done.
376If you are using a "compatible" sound card of types "LaserMate" or "SPEA",
377you can set SOUND_BASE (in sbpcd.h) to get it done with your card, too...
378
379
380Using audio CDs:
381----------------
382
383Workman, WorkBone, xcdplayer, cdplayer and the nice little tool "cdplay" (see
384README.aztcd from the Aztech driver package) should work.
385
386The program CDplayer likes to talk to "/dev/mcd" only, xcdplayer wants
387"/dev/rsr0", workman loves "/dev/sr0" or "/dev/cdrom" - so, make the
388appropriate links to use them without the need to supply parameters.
389
390
391Copying audio tracks:
392---------------------
393
394The following program will copy track 1 (or a piece of it) from an audio CD
395into the file "track01":
396
397/*=================== begin program ========================================*/
398/*
399 * read an audio track from a CD
400 *
401 * (c) 1994 Eberhard Moenkeberg <emoenke@gwdg.de>
402 * may be used & enhanced freely
403 *
404 * Due to non-existent sync bytes at the beginning of each audio frame (or due
405 * to a firmware bug within all known drives?), it is currently a kind of
406 * fortune if two consecutive frames fit together.
407 * Usually, they overlap, or a little piece is missing. This happens in units
408 * of 24-byte chunks. It has to get fixed by higher-level software (reading
409 * until an overlap occurs, and then eliminate the overlapping chunks).
410 * ftp.gwdg.de:/pub/linux/misc/cdda2wav-sbpcd.*.tar.gz holds an example of
411 * such an algorithm.
412 * This example program further is missing to obtain the SubChannel data
413 * which belong to each frame.
414 *
415 * This is only an example of the low-level access routine. The read data are
416 * pure 16-bit CDDA values; they have to get converted to make sound out of
417 * them.
418 * It is no fun to listen to it without prior overlap/underlap correction!
419 */
420#include <stdio.h>
421#include <sys/ioctl.h>
422#include <linux/cdrom.h>
423
424static struct cdrom_tochdr hdr;
425static struct cdrom_tocentry entry[101];
426static struct cdrom_read_audio arg;
427static u_char buffer[CD_FRAMESIZE_RAW];
428static int datafile, drive;
429static int i, j, limit, track, err;
430static char filename[32];
431
432main(int argc, char *argv[])
433{
434/*
435 * open /dev/cdrom
436 */
437 drive=open("/dev/cdrom", 0);
438 if (drive<0)
439 {
440 fprintf(stderr, "can't open drive.\n");
441 exit (-1);
442 }
443/*
444 * get TocHeader
445 */
446 fprintf(stdout, "getting TocHeader...\n");
447 err=ioctl(drive, CDROMREADTOCHDR, &hdr);
448 if (err!=0)
449 {
450 fprintf(stderr, "can't get TocHeader (error %d).\n", err);
451 exit (-1);
452 }
453 else
454 fprintf(stdout, "TocHeader: %d %d\n", hdr.cdth_trk0, hdr.cdth_trk1);
455/*
456 * get and display all TocEntries
457 */
458 fprintf(stdout, "getting TocEntries...\n");
459 for (i=1;i<=hdr.cdth_trk1+1;i++)
460 {
461 if (i!=hdr.cdth_trk1+1) entry[i].cdte_track = i;
462 else entry[i].cdte_track = CDROM_LEADOUT;
463 entry[i].cdte_format = CDROM_LBA;
464 err=ioctl(drive, CDROMREADTOCENTRY, &entry[i]);
465 if (err!=0)
466 {
467 fprintf(stderr, "can't get TocEntry #%d (error %d).\n", i, err);
468 exit (-1);
469 }
470 else
471 {
472 fprintf(stdout, "TocEntry #%d: %1X %1X %06X %02X\n",
473 entry[i].cdte_track,
474 entry[i].cdte_adr,
475 entry[i].cdte_ctrl,
476 entry[i].cdte_addr.lba,
477 entry[i].cdte_datamode);
478 }
479 }
480 fprintf(stdout, "got all TocEntries.\n");
481/*
482 * ask for track number (not implemented here)
483 */
484track=1;
485#if 0 /* just read a little piece (4 seconds) */
486entry[track+1].cdte_addr.lba=entry[track].cdte_addr.lba+300;
487#endif
488/*
489 * read track into file
490 */
491 sprintf(filename, "track%02d\0", track);
492 datafile=creat(filename, 0755);
493 if (datafile<0)
494 {
495 fprintf(stderr, "can't open datafile %s.\n", filename);
496 exit (-1);
497 }
498 arg.addr.lba=entry[track].cdte_addr.lba;
499 arg.addr_format=CDROM_LBA; /* CDROM_MSF would be possible here, too. */
500 arg.nframes=1;
501 arg.buf=&buffer[0];
502 limit=entry[track+1].cdte_addr.lba;
503 for (;arg.addr.lba<limit;arg.addr.lba++)
504 {
505 err=ioctl(drive, CDROMREADAUDIO, &arg);
506 if (err!=0)
507 {
508 fprintf(stderr, "can't read abs. frame #%d (error %d).\n",
509 arg.addr.lba, err);
510 }
511 j=write(datafile, &buffer[0], CD_FRAMESIZE_RAW);
512 if (j!=CD_FRAMESIZE_RAW)
513 {
514 fprintf(stderr,"I/O error (datafile) at rel. frame %d\n",
515 arg.addr.lba-entry[track].cdte_addr.lba);
516 }
517 arg.addr.lba++;
518 }
519}
520/*===================== end program ========================================*/
521
522At ftp.gwdg.de:/pub/linux/misc/cdda2wav-sbpcd.*.tar.gz is an adapted version of
523Heiko Eissfeldt's digital-audio to .WAV converter (the original is there, too).
524This is preliminary, as Heiko himself will care about it.
525
526
527Known problems:
528---------------
529
530Currently, the detection of disk change or removal is actively disabled.
531
532Most attempts to read the UPC/EAN code result in a stream of zeroes. All my
533drives are mostly telling there is no UPC/EAN code on disk or there is, but it
534is an all-zero number. I guess now almost no CD holds such a number.
535
536Bug reports, comments, wishes, donations (technical information is a donation,
537too :-) etc. to emoenke@gwdg.de.
538
539SnailMail address, preferable for CD editors if they want to submit a free
540"cooperation" copy:
541 Eberhard Moenkeberg
542 Reinholdstr. 14
543 D-37083 Goettingen
544 Germany
545---
546
547
548Appendix -- the "cdtester" utility:
549
550/*
551 * cdtester.c -- test the audio functions of a CD driver
552 *
553 * (c) 1995 Eberhard Moenkeberg <emoenke@gwdg.de>
554 * published under the GPL
555 *
556 * made under heavy use of the "Tiny Audio CD Player"
557 * from Werner Zimmermann <zimmerma@rz.fht-esslingen.de>
558 * (see linux/drivers/block/README.aztcd)
559 */
560#undef AZT_PRIVATE_IOCTLS /* not supported by every CDROM driver */
561#define SBP_PRIVATE_IOCTLS /* not supported by every CDROM driver */
562
563#include <stdio.h>
564#include <stdio.h>
565#include <malloc.h>
566#include <sys/ioctl.h>
567#include <linux/cdrom.h>
568
569#ifdef AZT_PRIVATE_IOCTLS
570#include <linux/../../drivers/cdrom/aztcd.h>
571#endif AZT_PRIVATE_IOCTLS
572#ifdef SBP_PRIVATE_IOCTLS
573#include <linux/../../drivers/cdrom/sbpcd.h>
574#include <linux/fs.h>
575#endif SBP_PRIVATE_IOCTLS
576
577struct cdrom_tochdr hdr;
578struct cdrom_tochdr tocHdr;
579struct cdrom_tocentry TocEntry[101];
580struct cdrom_tocentry entry;
581struct cdrom_multisession ms_info;
582struct cdrom_read_audio read_audio;
583struct cdrom_ti ti;
584struct cdrom_subchnl subchnl;
585struct cdrom_msf msf;
586struct cdrom_volctrl volctrl;
587#ifdef AZT_PRIVATE_IOCTLS
588union
589{
590 struct cdrom_msf msf;
591 unsigned char buf[CD_FRAMESIZE_RAW];
592} azt;
593#endif AZT_PRIVATE_IOCTLS
594int i, i1, i2, i3, j, k;
595unsigned char sequence=0;
596unsigned char command[80];
597unsigned char first=1, last=1;
598char *default_device="/dev/cdrom";
599char dev[20];
600char filename[20];
601int drive;
602int datafile;
603int rc;
604
605void help(void)
606{
607 printf("Available Commands:\n");
608 printf("STOP s EJECT e QUIT q\n");
609 printf("PLAY TRACK t PAUSE p RESUME r\n");
610 printf("NEXT TRACK n REPEAT LAST l HELP h\n");
611 printf("SUBCHANNEL_Q c TRACK INFO i PLAY AT a\n");
612 printf("READ d READ RAW w READ AUDIO A\n");
613 printf("MS-INFO M TOC T START S\n");
614 printf("SET EJECTSW X DEVICE D DEBUG Y\n");
615 printf("AUDIO_BUFSIZ Z RESET R SET VOLUME v\n");
616 printf("GET VOLUME V\n");
617}
618
619/*
620 * convert MSF number (3 bytes only) to Logical_Block_Address
621 */
622int msf2lba(u_char *msf)
623{
624 int i;
625
626 i=(msf[0] * CD_SECS + msf[1]) * CD_FRAMES + msf[2] - CD_BLOCK_OFFSET;
627 if (i<0) return (0);
628 return (i);
629}
630/*
631 * convert logical_block_address to m-s-f_number (3 bytes only)
632 */
633void lba2msf(int lba, unsigned char *msf)
634{
635 lba += CD_BLOCK_OFFSET;
636 msf[0] = lba / (CD_SECS*CD_FRAMES);
637 lba %= CD_SECS*CD_FRAMES;
638 msf[1] = lba / CD_FRAMES;
639 msf[2] = lba % CD_FRAMES;
640}
641
642int init_drive(char *dev)
643{
644 unsigned char msf_ent[3];
645
646 /*
647 * open the device
648 */
649 drive=open(dev,0);
650 if (drive<0) return (-1);
651 /*
652 * get TocHeader
653 */
654 printf("getting TocHeader...\n");
655 rc=ioctl(drive,CDROMREADTOCHDR,&hdr);
656 if (rc!=0)
657 {
658 printf("can't get TocHeader (error %d).\n",rc);
659 return (-2);
660 }
661 else
662 first=hdr.cdth_trk0;
663 last=hdr.cdth_trk1;
664 printf("TocHeader: %d %d\n",hdr.cdth_trk0,hdr.cdth_trk1);
665 /*
666 * get and display all TocEntries
667 */
668 printf("getting TocEntries...\n");
669 for (i=1;i<=hdr.cdth_trk1+1;i++)
670 {
671 if (i!=hdr.cdth_trk1+1) TocEntry[i].cdte_track = i;
672 else TocEntry[i].cdte_track = CDROM_LEADOUT;
673 TocEntry[i].cdte_format = CDROM_LBA;
674 rc=ioctl(drive,CDROMREADTOCENTRY,&TocEntry[i]);
675 if (rc!=0)
676 {
677 printf("can't get TocEntry #%d (error %d).\n",i,rc);
678 }
679 else
680 {
681 lba2msf(TocEntry[i].cdte_addr.lba,&msf_ent[0]);
682 if (TocEntry[i].cdte_track==CDROM_LEADOUT)
683 {
684 printf("TocEntry #%02X: %1X %1X %02d:%02d:%02d (lba: 0x%06X) %02X\n",
685 TocEntry[i].cdte_track,
686 TocEntry[i].cdte_adr,
687 TocEntry[i].cdte_ctrl,
688 msf_ent[0],
689 msf_ent[1],
690 msf_ent[2],
691 TocEntry[i].cdte_addr.lba,
692 TocEntry[i].cdte_datamode);
693 }
694 else
695 {
696 printf("TocEntry #%02d: %1X %1X %02d:%02d:%02d (lba: 0x%06X) %02X\n",
697 TocEntry[i].cdte_track,
698 TocEntry[i].cdte_adr,
699 TocEntry[i].cdte_ctrl,
700 msf_ent[0],
701 msf_ent[1],
702 msf_ent[2],
703 TocEntry[i].cdte_addr.lba,
704 TocEntry[i].cdte_datamode);
705 }
706 }
707 }
708 return (hdr.cdth_trk1); /* number of tracks */
709}
710
711void display(int size,unsigned char *buffer)
712{
713 k=0;
714 getchar();
715 for (i=0;i<(size+1)/16;i++)
716 {
717 printf("%4d:",i*16);
718 for (j=0;j<16;j++)
719 {
720 printf(" %02X",buffer[i*16+j]);
721 }
722 printf(" ");
723 for (j=0;j<16;j++)
724 {
725 if (isalnum(buffer[i*16+j]))
726 printf("%c",buffer[i*16+j]);
727 else
728 printf(".");
729 }
730 printf("\n");
731 k++;
732 if (k>=20)
733 {
734 printf("press ENTER to continue\n");
735 getchar();
736 k=0;
737 }
738 }
739}
740
741main(int argc, char *argv[])
742{
743 printf("\nTesting tool for a CDROM driver's audio functions V0.1\n");
744 printf("(C) 1995 Eberhard Moenkeberg <emoenke@gwdg.de>\n");
745 printf("initializing...\n");
746
747 rc=init_drive(default_device);
748 if (rc<0) printf("could not open %s (rc=%d).\n",default_device,rc);
749 help();
750 while (1)
751 {
752 printf("Give a one-letter command (h = help): ");
753 scanf("%s",command);
754 command[1]=0;
755 switch (command[0])
756 {
757 case 'D':
758 printf("device name (f.e. /dev/sbpcd3): ? ");
759 scanf("%s",&dev);
760 close(drive);
761 rc=init_drive(dev);
762 if (rc<0) printf("could not open %s (rc %d).\n",dev,rc);
763 break;
764 case 'e':
765 rc=ioctl(drive,CDROMEJECT);
766 if (rc<0) printf("CDROMEJECT: rc=%d.\n",rc);
767 break;
768 case 'p':
769 rc=ioctl(drive,CDROMPAUSE);
770 if (rc<0) printf("CDROMPAUSE: rc=%d.\n",rc);
771 break;
772 case 'r':
773 rc=ioctl(drive,CDROMRESUME);
774 if (rc<0) printf("CDROMRESUME: rc=%d.\n",rc);
775 break;
776 case 's':
777 rc=ioctl(drive,CDROMSTOP);
778 if (rc<0) printf("CDROMSTOP: rc=%d.\n",rc);
779 break;
780 case 'S':
781 rc=ioctl(drive,CDROMSTART);
782 if (rc<0) printf("CDROMSTART: rc=%d.\n",rc);
783 break;
784 case 't':
785 rc=ioctl(drive,CDROMREADTOCHDR,&tocHdr);
786 if (rc<0)
787 {
788 printf("CDROMREADTOCHDR: rc=%d.\n",rc);
789 break;
790 }
791 first=tocHdr.cdth_trk0;
792 last= tocHdr.cdth_trk1;
793 if ((first==0)||(first>last))
794 {
795 printf ("--got invalid TOC data.\n");
796 }
797 else
798 {
799 printf("--enter track number(first=%d, last=%d): ",first,last);
800 scanf("%d",&i1);
801 ti.cdti_trk0=i1;
802 if (ti.cdti_trk0<first) ti.cdti_trk0=first;
803 if (ti.cdti_trk0>last) ti.cdti_trk0=last;
804 ti.cdti_ind0=0;
805 ti.cdti_trk1=last;
806 ti.cdti_ind1=0;
807 rc=ioctl(drive,CDROMSTOP);
808 rc=ioctl(drive,CDROMPLAYTRKIND,&ti);
809 if (rc<0) printf("CDROMPLAYTRKIND: rc=%d.\n",rc);
810 }
811 break;
812 case 'n':
813 rc=ioctl(drive,CDROMSTOP);
814 if (++ti.cdti_trk0>last) ti.cdti_trk0=last;
815 ti.cdti_ind0=0;
816 ti.cdti_trk1=last;
817 ti.cdti_ind1=0;
818 rc=ioctl(drive,CDROMPLAYTRKIND,&ti);
819 if (rc<0) printf("CDROMPLAYTRKIND: rc=%d.\n",rc);
820 break;
821 case 'l':
822 rc=ioctl(drive,CDROMSTOP);
823 if (--ti.cdti_trk0<first) ti.cdti_trk0=first;
824 ti.cdti_ind0=0;
825 ti.cdti_trk1=last;
826 ti.cdti_ind1=0;
827 rc=ioctl(drive,CDROMPLAYTRKIND,&ti);
828 if (rc<0) printf("CDROMPLAYTRKIND: rc=%d.\n",rc);
829 break;
830 case 'c':
831 subchnl.cdsc_format=CDROM_MSF;
832 rc=ioctl(drive,CDROMSUBCHNL,&subchnl);
833 if (rc<0) printf("CDROMSUBCHNL: rc=%d.\n",rc);
834 else
835 {
836 printf("AudioStatus:%s Track:%d Mode:%d MSF=%02d:%02d:%02d\n",
837 subchnl.cdsc_audiostatus==CDROM_AUDIO_PLAY ? "PLAYING":"NOT PLAYING",
838 subchnl.cdsc_trk,subchnl.cdsc_adr,
839 subchnl.cdsc_absaddr.msf.minute,
840 subchnl.cdsc_absaddr.msf.second,
841 subchnl.cdsc_absaddr.msf.frame);
842 }
843 break;
844 case 'i':
845 printf("Track No.: ");
846 scanf("%d",&i1);
847 entry.cdte_track=i1;
848 if (entry.cdte_track<first) entry.cdte_track=first;
849 if (entry.cdte_track>last) entry.cdte_track=last;
850 entry.cdte_format=CDROM_MSF;
851 rc=ioctl(drive,CDROMREADTOCENTRY,&entry);
852 if (rc<0) printf("CDROMREADTOCENTRY: rc=%d.\n",rc);
853 else
854 {
855 printf("Mode %d Track, starts at %02d:%02d:%02d\n",
856 entry.cdte_adr,
857 entry.cdte_addr.msf.minute,
858 entry.cdte_addr.msf.second,
859 entry.cdte_addr.msf.frame);
860 }
861 break;
862 case 'a':
863 printf("Address (min:sec:frm) ");
864 scanf("%d:%d:%d",&i1,&i2,&i3);
865 msf.cdmsf_min0=i1;
866 msf.cdmsf_sec0=i2;
867 msf.cdmsf_frame0=i3;
868 if (msf.cdmsf_sec0>59) msf.cdmsf_sec0=59;
869 if (msf.cdmsf_frame0>74) msf.cdmsf_frame0=74;
870 lba2msf(TocEntry[last+1].cdte_addr.lba-1,&msf.cdmsf_min1);
871 rc=ioctl(drive,CDROMSTOP);
872 rc=ioctl(drive,CDROMPLAYMSF,&msf);
873 if (rc<0) printf("CDROMPLAYMSF: rc=%d.\n",rc);
874 break;
875 case 'V':
876 rc=ioctl(drive,CDROMVOLREAD,&volctrl);
877 if (rc<0) printf("CDROMVOLCTRL: rc=%d.\n",rc);
878 printf("Volume: channel 0 (left) %d, channel 1 (right) %d\n",volctrl.channel0,volctrl.channel1);
879 break;
880 case 'R':
881 rc=ioctl(drive,CDROMRESET);
882 if (rc<0) printf("CDROMRESET: rc=%d.\n",rc);
883 break;
884#ifdef AZT_PRIVATE_IOCTLS /*not supported by every CDROM driver*/
885 case 'd':
886 printf("Address (min:sec:frm) ");
887 scanf("%d:%d:%d",&i1,&i2,&i3);
888 azt.msf.cdmsf_min0=i1;
889 azt.msf.cdmsf_sec0=i2;
890 azt.msf.cdmsf_frame0=i3;
891 if (azt.msf.cdmsf_sec0>59) azt.msf.cdmsf_sec0=59;
892 if (azt.msf.cdmsf_frame0>74) azt.msf.cdmsf_frame0=74;
893 rc=ioctl(drive,CDROMREADMODE1,&azt.msf);
894 if (rc<0) printf("CDROMREADMODE1: rc=%d.\n",rc);
895 else display(CD_FRAMESIZE,azt.buf);
896 break;
897 case 'w':
898 printf("Address (min:sec:frame) ");
899 scanf("%d:%d:%d",&i1,&i2,&i3);
900 azt.msf.cdmsf_min0=i1;
901 azt.msf.cdmsf_sec0=i2;
902 azt.msf.cdmsf_frame0=i3;
903 if (azt.msf.cdmsf_sec0>59) azt.msf.cdmsf_sec0=59;
904 if (azt.msf.cdmsf_frame0>74) azt.msf.cdmsf_frame0=74;
905 rc=ioctl(drive,CDROMREADMODE2,&azt.msf);
906 if (rc<0) printf("CDROMREADMODE2: rc=%d.\n",rc);
907 else display(CD_FRAMESIZE_RAW,azt.buf); /* currently only 2336 */
908 break;
909#endif
910 case 'v':
911 printf("--Channel 0 (Left) (0-255): ");
912 scanf("%d",&i1);
913 volctrl.channel0=i1;
914 printf("--Channel 1 (Right) (0-255): ");
915 scanf("%d",&i1);
916 volctrl.channel1=i1;
917 volctrl.channel2=0;
918 volctrl.channel3=0;
919 rc=ioctl(drive,CDROMVOLCTRL,&volctrl);
920 if (rc<0) printf("CDROMVOLCTRL: rc=%d.\n",rc);
921 break;
922 case 'q':
923 close(drive);
924 exit(0);
925 case 'h':
926 help();
927 break;
928 case 'T': /* display TOC entry - without involving the driver */
929 scanf("%d",&i);
930 if ((i<hdr.cdth_trk0)||(i>hdr.cdth_trk1))
931 printf("invalid track number.\n");
932 else
933 printf("TocEntry %02d: adr=%01X ctrl=%01X msf=%02d:%02d:%02d mode=%02X\n",
934 TocEntry[i].cdte_track,
935 TocEntry[i].cdte_adr,
936 TocEntry[i].cdte_ctrl,
937 TocEntry[i].cdte_addr.msf.minute,
938 TocEntry[i].cdte_addr.msf.second,
939 TocEntry[i].cdte_addr.msf.frame,
940 TocEntry[i].cdte_datamode);
941 break;
942 case 'A': /* read audio data into file */
943 printf("Address (min:sec:frm) ? ");
944 scanf("%d:%d:%d",&i1,&i2,&i3);
945 read_audio.addr.msf.minute=i1;
946 read_audio.addr.msf.second=i2;
947 read_audio.addr.msf.frame=i3;
948 read_audio.addr_format=CDROM_MSF;
949 printf("# of frames ? ");
950 scanf("%d",&i1);
951 read_audio.nframes=i1;
952 k=read_audio.nframes*CD_FRAMESIZE_RAW;
953 read_audio.buf=malloc(k);
954 if (read_audio.buf==NULL)
955 {
956 printf("can't malloc %d bytes.\n",k);
957 break;
958 }
959 sprintf(filename,"audio_%02d%02d%02d_%02d.%02d\0",
960 read_audio.addr.msf.minute,
961 read_audio.addr.msf.second,
962 read_audio.addr.msf.frame,
963 read_audio.nframes,
964 ++sequence);
965 datafile=creat(filename, 0755);
966 if (datafile<0)
967 {
968 printf("can't open datafile %s.\n",filename);
969 break;
970 }
971 rc=ioctl(drive,CDROMREADAUDIO,&read_audio);
972 if (rc!=0)
973 {
974 printf("CDROMREADAUDIO: rc=%d.\n",rc);
975 }
976 else
977 {
978 rc=write(datafile,&read_audio.buf,k);
979 if (rc!=k) printf("datafile I/O error (%d).\n",rc);
980 }
981 close(datafile);
982 break;
983 case 'X': /* set EJECT_SW (0: disable, 1: enable auto-ejecting) */
984 scanf("%d",&i);
985 rc=ioctl(drive,CDROMEJECT_SW,i);
986 if (rc!=0)
987 printf("CDROMEJECT_SW: rc=%d.\n",rc);
988 else
989 printf("EJECT_SW set to %d\n",i);
990 break;
991 case 'M': /* get the multisession redirection info */
992 ms_info.addr_format=CDROM_LBA;
993 rc=ioctl(drive,CDROMMULTISESSION,&ms_info);
994 if (rc!=0)
995 {
996 printf("CDROMMULTISESSION(lba): rc=%d.\n",rc);
997 }
998 else
999 {
1000 if (ms_info.xa_flag) printf("MultiSession offset (lba): %d (0x%06X)\n",ms_info.addr.lba,ms_info.addr.lba);
1001 else
1002 {
1003 printf("this CD is not an XA disk.\n");
1004 break;
1005 }
1006 }
1007 ms_info.addr_format=CDROM_MSF;
1008 rc=ioctl(drive,CDROMMULTISESSION,&ms_info);
1009 if (rc!=0)
1010 {
1011 printf("CDROMMULTISESSION(msf): rc=%d.\n",rc);
1012 }
1013 else
1014 {
1015 if (ms_info.xa_flag)
1016 printf("MultiSession offset (msf): %02d:%02d:%02d (0x%02X%02X%02X)\n",
1017 ms_info.addr.msf.minute,
1018 ms_info.addr.msf.second,
1019 ms_info.addr.msf.frame,
1020 ms_info.addr.msf.minute,
1021 ms_info.addr.msf.second,
1022 ms_info.addr.msf.frame);
1023 else printf("this CD is not an XA disk.\n");
1024 }
1025 break;
1026#ifdef SBP_PRIVATE_IOCTLS
1027 case 'Y': /* set the driver's message level */
1028#if 0 /* not implemented yet */
1029 printf("enter switch name (f.e. DBG_CMD): ");
1030 scanf("%s",&dbg_switch);
1031 j=get_dbg_num(dbg_switch);
1032#else
1033 printf("enter DDIOCSDBG switch number: ");
1034 scanf("%d",&j);
1035#endif
1036 printf("enter 0 for \"off\", 1 for \"on\": ");
1037 scanf("%d",&i);
1038 if (i==0) j|=0x80;
1039 printf("calling \"ioctl(drive,DDIOCSDBG,%d)\"\n",j);
1040 rc=ioctl(drive,DDIOCSDBG,j);
1041 printf("DDIOCSDBG: rc=%d.\n",rc);
1042 break;
1043 case 'Z': /* set the audio buffer size */
1044 printf("# frames wanted: ? ");
1045 scanf("%d",&j);
1046 rc=ioctl(drive,CDROMAUDIOBUFSIZ,j);
1047 printf("%d frames granted.\n",rc);
1048 break;
1049#endif SBP_PRIVATE_IOCTLS
1050 default:
1051 printf("unknown command: \"%s\".\n",command);
1052 break;
1053 }
1054 }
1055}
1056/*==========================================================================*/
1057
diff --git a/Documentation/cdrom/sjcd b/Documentation/cdrom/sjcd
new file mode 100644
index 000000000000..74a14847b93a
--- /dev/null
+++ b/Documentation/cdrom/sjcd
@@ -0,0 +1,60 @@
1 -- Documentation/cdrom/sjcd
2 80% of the work takes 20% of the time,
3 20% of the work takes 80% of the time...
4 (Murphy's law)
5
6 Once started, training can not be stopped...
7 (Star Wars)
8
9This is the README for the sjcd cdrom driver, version 1.6.
10
11This file is meant as a tips & tricks edge for the usage of the SANYO CDR-H94A
12cdrom drive. It will grow as the questions arise. ;-)
13For info on configuring the ISP16 sound card look at Documentation/cdrom/isp16.
14
15The driver should work with any of the Panasonic, Sony or Mitsumi style
16CDROM interfaces.
17The cdrom interface on Media Magic's soft configurable sound card ISP16,
18which used to be included in the driver, is now supported in a separate module.
19This initialisation module will probably also work with other interfaces
20based on an OPTi 82C928 or 82C929 chip (like MAD16 and Mozart): see the
21documentation Documentation/cdrom/isp16.
22
23The device major for sjcd is 18, and minor is 0. Create a block special
24file in your /dev directory (e.g., /dev/sjcd) with these numbers.
25(For those who don't know, being root and doing the following should do
26the trick:
27 mknod -m 644 /dev/sjcd b 18 0
28and mount the cdrom by /dev/sjcd).
29
30The default configuration parameters are:
31 base address 0x340
32 no irq
33 no dma
34(Actually the CDR-H94A doesn't know how to use irq and dma.)
35As of version 1.2, setting base address at boot time is supported
36through the use of command line options: type at the "boot:" prompt:
37 linux sjcd=<base_address>
38(where you would use the kernel labeled "linux" in lilo's configuration
39file /etc/lilo.conf). You could also use 'append="sjcd=<configuration_info>"'
40in the appropriate section of /etc/lilo.conf
41If you're building a kernel yourself you can set your default base
42i/o address with SJCD_BASE_ADDR in /usr/src/linux/drivers/cdrom/sjcd.h.
43
44The sjcd driver supports being loaded as a module. The following
45command will set the base i/o address on the fly (assuming you
46have installed the module in an appropriate place).
47 insmod sjcd.o sjcd_base=<base_address>
48
49
50Have fun!
51
52If something is wrong, please email to vadim@rbrf.ru
53 or vadim@ipsun.ras.ru
54 or model@cecmow.enet.dec.com
55 or H.T.M.v.d.Maarel@marin.nl
56
57It happens sometimes that Vadim is not reachable by mail. For these
58instances, Eric van der Maarel will help too.
59
60 Vadim V. Model, Eric van der Maarel, Eberhard Moenkeberg
diff --git a/Documentation/cdrom/sonycd535 b/Documentation/cdrom/sonycd535
new file mode 100644
index 000000000000..59581a4b302a
--- /dev/null
+++ b/Documentation/cdrom/sonycd535
@@ -0,0 +1,121 @@
1 README FOR LINUX SONY CDU-535/531 DRIVER
2 ========================================
3
4This is the Sony CDU-535 (and 531) driver version 0.7 for Linux.
5I do not think I have the documentation to add features like DMA support
6so if anyone else wants to pursue it or help me with it, please do.
7(I need to see what was done for the CDU-31A driver -- perhaps I can
8steal some of that code.)
9
10This is a Linux device driver for the Sony CDU-535 CDROM drive. This is
11one of the older Sony drives with its own interface card (Sony bus).
12The DOS driver for this drive is named SONY_CDU.SYS - when you boot DOS
13your drive should be identified as a SONY CDU-535. The driver works
14with a CDU-531 also. One user reported that the driver worked on drives
15OEM'ed by Procomm, drive and interface board were labelled Procomm.
16
17The Linux driver is based on Corey Minyard's sonycd 0.3 driver for
18the CDU-31A. Ron Jeppesen just changed the commands that were sent
19to the drive to correspond to the CDU-535 commands and registers.
20There were enough changes to let bugs creep in but it seems to be stable.
21Ron was able to tar an entire CDROM (should read all blocks) and built
22ghostview and xfig off Walnut Creek's X11R5/GNU CDROM. xcdplayer and
23workman work with the driver. Others have used the driver without
24problems except those dealing with wait loops (fixed in third release).
25Like Minyard's original driver this one uses a polled interface (this
26is also the default setup for the DOS driver). It has not been tried
27with interrupts or DMA enabled on the board.
28
29REQUIREMENTS
30============
31
32 - Sony CDU-535 drive, preferably without interrupts and DMA
33 enabled on the card.
34
35 - Drive must be set up as unit 1. Only the first unit will be
36 recognized
37
38 - You must enter your interface address into
39 /usr/src/linux/drivers/cdrom/sonycd535.h and build the
40 appropriate kernel or use the "kernel command line" parameter
41 sonycd535=0x320
42 with the correct interface address.
43
44NOTES:
45======
46
471) The drive MUST be turned on when booting or it will not be recognized!
48 (but see comments on modularized version below)
49
502) when the cdrom device is opened the eject button is disabled to keep the
51 user from ejecting a mounted disk and replacing it with another.
52 Unfortunately xcdplayer and workman also open the cdrom device so you
53 have to use the eject button in the software. Keep this in mind if your
54 cdrom player refuses to give up its disk -- exit workman or xcdplayer, or
55 umount the drive if it has been mounted.
56
57THANKS
58======
59
60Many thanks to Ron Jeppesen (ronj.an@site007.saic.com) for getting
61this project off the ground. He wrote the initial release
62and the first two patches to this driver (0.1, 0.2, and 0.3).
63Thanks also to Eberhard Moenkeberg (emoenke@gwdg.de) for prodding
64me to place this code into the mainstream Linux source tree
65(as of Linux version 1.1.91), as well as some patches to make
66it a better device citizen. Further thanks to Joel Katz
67<joelkatz@webchat.org> for his MODULE patches (see details below),
68Porfiri Claudio <C.Porfiri@nisms.tei.ericsson.se> for patches
69to make the driver work with the older CDU-510/515 series, and
70Heiko Eissfeldt <heiko@colossus.escape.de> for pointing out that
71the verify_area() checks were ignoring the results of said checks.
72
73(Acknowledgments from Ron Jeppesen in the 0.3 release:)
74Thanks to Corey Minyard who wrote the original CDU-31A driver on which
75this driver is based. Thanks to Ken Pizzini and Bob Blair who provided
76patches and feedback on the first release of this driver.
77
78Ken Pizzini
79ken@halcyon.com
80
81------------------------------------------------------------------------------
82(The following is from Joel Katz <joelkatz@webchat.org>.)
83
84 To build a version of sony535.o that can be installed as a module,
85use the following command:
86
87gcc -c -D__KERNEL__ -DMODULE -O2 sonycd535.c -o sonycd535.o
88
89 To install the module, simply type:
90
91insmod sony535.o
92 or
93insmod sony535.o sonycd535=<address>
94
95 And to remove it:
96
97rmmod sony535
98
99 The code checks to see if MODULE is defined and behaves as it used
100to if MODULE is not defined. That means your patched file should behave
101exactly as it used to if compiled into the kernel.
102
103 I have an external drive, and I usually leave it powered off. I used
104to have to reboot if I needed to use the CDROM drive. Now I don't.
105
106 Even if you have an internal drive, why waste the 96K of memory
107(unswappable) that the driver uses if you use your CD-ROM drive infrequently?
108
109 This driver will not install (whether compiled in or loaded as a
110module) if the CDROM drive is not available during its initialization. This
111means that you can have the driver compiled into the kernel and still load
112the module later (assuming the driver doesn't install itself during
113power-on). This only wastes 12K when you boot with the CDROM drive off.
114
115 This is what I usually do; I leave the driver compiled into the
116kernel, but load it as a module if I powered the system up with the drive
117off and then later decided to use the CDROM drive.
118
119 Since the driver only uses a single page to point to the chunks,
120attempting to set the buffer cache to more than 2 Megabytes would be very
121bad; don't do that.
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-21 13:44:10 -0500