GNU Linux-libre 4.19.211-gnu1
[releases.git] / Documentation / cdrom / ide-cd
1 IDE-CD driver documentation
2 Originally by scott snyder  <snyder@fnald0.fnal.gov> (19 May 1996)
3 Carrying on the torch is: Erik Andersen <andersee@debian.org>
4 New maintainers (19 Oct 1998): Jens Axboe <axboe@image.dk>
5
6 1. Introduction
7 ---------------
8
9 The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant 
10 CDROM drives which attach to an IDE interface.  Note that some CDROM vendors
11 (including Mitsumi, Sony, Creative, Aztech, and Goldstar) have made
12 both ATAPI-compliant drives and drives which use a proprietary
13 interface.  If your drive uses one of those proprietary interfaces,
14 this driver will not work with it (but one of the other CDROM drivers
15 probably will).  This driver will not work with `ATAPI' drives which
16 attach 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;
18 this driver will not work with drives like that either (but see the
19 aztcd driver).
20
21 This 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
44 2. Installation
45 ---------------
46
47 0. The ide-cd relies on the ide disk driver.  See
48    Documentation/ide/ide.txt for up-to-date information on the ide
49    driver.
50
51 1. 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       ATA/ATAPI/MFM/RLL support
59       Include IDE/ATAPI CDROM support
60
61    Depending on what type of IDE interface you have, you may need to
62    specify additional configuration options.  See
63    Documentation/ide/ide.txt.
64
65 2. You should also ensure that the iso9660 filesystem is either
66    compiled into the kernel or available as a loadable module.  You
67    can see if a filesystem is known to the kernel by catting
68    /proc/filesystems.
69
70 3. The CDROM drive should be connected to the host on an IDE
71    interface.  Each interface on a system is defined by an I/O port
72    address and an IRQ number, the standard assignments being
73    0x1f0 and 14 for the primary interface and 0x170 and 15 for the
74    secondary interface.  Each interface can control up to two devices,
75    where each device can be a hard drive, a CDROM drive, a floppy drive, 
76    or a tape drive.  The two devices on an interface are called `master'
77    and `slave'; this is usually selectable via a jumper on the drive.
78
79    Linux names these devices as follows.  The master and slave devices
80    on the primary IDE interface are called `hda' and `hdb',
81    respectively.  The drives on the secondary interface are called
82    `hdc' and `hdd'.  (Interfaces at other locations get other letters
83    in the third position; see Documentation/ide/ide.txt.)
84
85    If you want your CDROM drive to be found automatically by the
86    driver, you should make sure your IDE interface uses either the
87    primary or secondary addresses mentioned above.  In addition, if
88    the CDROM drive is the only device on the IDE interface, it should
89    be jumpered as `master'.  (If for some reason you cannot configure
90    your system in this manner, you can probably still use the driver.
91    You may have to pass extra configuration information to the kernel
92    when you boot, however.  See Documentation/ide/ide.txt for more
93    information.)
94
95 4. Boot the system.  If the drive is recognized, you should see a
96    message which looks like
97
98      hdb: NEC CD-ROM DRIVE:260, ATAPI CDROM drive
99
100    If you do not see this, see section 5 below.
101
102 5. You may want to create a symbolic link /dev/cdrom pointing to the
103    actual device.  You can do this with the command
104
105      ln -s  /dev/hdX  /dev/cdrom
106
107    where X should be replaced by the letter indicating where your
108    drive is installed.
109
110 6. You should be able to see any error messages from the driver with
111    the `dmesg' command.
112
113
114 3. Basic usage
115 --------------
116
117 An ISO 9660 CDROM can be mounted by putting the disc in the drive and 
118 typing (as root)
119
120   mount -t iso9660 /dev/cdrom /mnt/cdrom
121
122 where it is assumed that /dev/cdrom is a link pointing to the actual
123 device (as described in step 5 of the last section) and /mnt/cdrom is
124 an empty directory.  You should now be able to see the contents of the
125 CDROM under the /mnt/cdrom directory.  If you want to eject the CDROM,
126 you must first dismount it with a command like
127
128   umount /mnt/cdrom
129
130 Note that audio CDs cannot be mounted.
131
132 Some distributions set up /etc/fstab to always try to mount a CDROM
133 filesystem on bootup.  It is not required to mount the CDROM in this
134 manner, though, and it may be a nuisance if you change CDROMs often.
135 You should feel free to remove the cdrom line from /etc/fstab and
136 mount CDROMs manually if that suits you better.
137
138 Multisession and photocd discs should work with no special handling.
139 The hpcdtoppm package (ftp.gwdg.de:/pub/linux/hpcdtoppm/) may be
140 useful for reading photocds.
141
142 To play an audio CD, you should first unmount and remove any data
143 CDROM.  Any of the CDROM player programs should then work (workman,
144 workbone, cdplayer, etc.).
145
146 On a few drives, you can read digital audio directly using a program
147 such as cdda2wav.  The only types of drive which I've heard support
148 this are Sony and Toshiba drives.  You will get errors if you try to
149 use this function on a drive which does not support it.
150
151 For supported changers, you can use the `cdchange' program (appended to
152 the end of this file) to switch between changer slots.  Note that the
153 drive should be unmounted before attempting this.  The program takes
154 two arguments:  the CDROM device, and the slot number to which you wish
155 to change.  If the slot number is -1, the drive is unloaded.
156
157
158 4. Common problems
159 ------------------
160
161 This section discusses some common problems encountered when trying to
162 use the driver, and some possible solutions.  Note that if you are
163 experiencing problems, you should probably also review
164 Documentation/ide/ide.txt for current information about the underlying
165 IDE support code.  Some of these items apply only to earlier versions
166 of the driver, but are mentioned here for completeness.
167
168 In most cases, you should probably check with `dmesg' for any errors
169 from the driver.
170
171 a. Drive is not detected during booting.
172
173    - Review the configuration instructions above and in
174      Documentation/ide/ide.txt, and check how your hardware is
175      configured.
176
177    - If your drive is the only device on an IDE interface, it should
178      be jumpered as master, if at all possible.
179
180    - If your IDE interface is not at the standard addresses of 0x170
181      or 0x1f0, you'll need to explicitly inform the driver using a
182      lilo option.  See Documentation/ide/ide.txt.  (This feature was
183      added around kernel version 1.3.30.)
184
185    - If the autoprobing is not finding your drive, you can tell the
186      driver to assume that one exists by using a lilo option of the
187      form `hdX=cdrom', where X is the drive letter corresponding to
188      where your drive is installed.  Note that if you do this and you 
189      see a boot message like
190
191        hdX: ATAPI cdrom (?)
192
193      this does _not_ mean that the driver has successfully detected
194      the drive; rather, it means that the driver has not detected a
195      drive, but is assuming there's one there anyway because you told
196      it so.  If you actually try to do I/O to a drive defined at a
197      nonexistent or nonresponding I/O address, you'll probably get
198      errors with a status value of 0xff.
199
200    - Some IDE adapters require a nonstandard initialization sequence
201      before they'll function properly.  (If this is the case, there
202      will often be a separate MS-DOS driver just for the controller.)
203      IDE interfaces on sound cards often fall into this category.
204
205      Support for some interfaces needing extra initialization is
206      provided in later 1.3.x kernels.  You may need to turn on
207      additional kernel configuration options to get them to work;
208      see Documentation/ide/ide.txt.
209
210      Even if support is not available for your interface, you may be
211      able to get it to work with the following procedure.  First boot
212      MS-DOS and load the appropriate drivers.  Then warm-boot linux
213      (i.e., without powering off).  If this works, it can be automated
214      by running loadlin from the MS-DOS autoexec.
215
216
217 b. Timeout/IRQ errors.
218
219   - If you always get timeout errors, interrupts from the drive are
220     probably not making it to the host.
221
222   - IRQ problems may also be indicated by the message
223     `IRQ probe failed (<n>)' while booting.  If <n> is zero, that
224     means that the system did not see an interrupt from the drive when
225     it was expecting one (on any feasible IRQ).  If <n> is negative,
226     that means the system saw interrupts on multiple IRQ lines, when
227     it was expecting to receive just one from the CDROM drive.
228
229   - Double-check your hardware configuration to make sure that the IRQ
230     number of your IDE interface matches what the driver expects.
231     (The usual assignments are 14 for the primary (0x1f0) interface
232     and 15 for the secondary (0x170) interface.)  Also be sure that
233     you don't have some other hardware which might be conflicting with
234     the IRQ you're using.  Also check the BIOS setup for your system;
235     some have the ability to disable individual IRQ levels, and I've
236     had one report of a system which was shipped with IRQ 15 disabled
237     by default.
238
239   - Note that many MS-DOS CDROM drivers will still function even if
240     there are hardware problems with the interrupt setup; they
241     apparently don't use interrupts.
242
243   - If you own a Pioneer DR-A24X, you _will_ get nasty error messages 
244     on boot such as "irq timeout: status=0x50 { DriveReady SeekComplete }"
245     The Pioneer DR-A24X CDROM drives are fairly popular these days.
246     Unfortunately, these drives seem to become very confused when we perform
247     the standard Linux ATA disk drive probe. If you own one of these drives,
248     you can bypass the ATA probing which confuses these CDROM drives, by 
249     adding `append="hdX=noprobe hdX=cdrom"' to your lilo.conf file and running 
250     lilo (again where X is the drive letter corresponding to where your drive 
251     is installed.)
252     
253 c. System hangups.
254
255   - If the system locks up when you try to access the CDROM, the most
256     likely cause is that you have a buggy IDE adapter which doesn't
257     properly handle simultaneous transactions on multiple interfaces.
258     The most notorious of these is the CMD640B chip.  This problem can
259     be worked around by specifying the `serialize' option when
260     booting.  Recent kernels should be able to detect the need for
261     this automatically in most cases, but the detection is not
262     foolproof.  See Documentation/ide/ide.txt for more information
263     about the `serialize' option and the CMD640B.
264
265   - Note that many MS-DOS CDROM drivers will work with such buggy
266     hardware, apparently because they never attempt to overlap CDROM
267     operations with other disk activity.
268
269
270 d. Can't mount a CDROM.
271
272   - If you get errors from mount, it may help to check `dmesg' to see
273     if there are any more specific errors from the driver or from the
274     filesystem.
275
276   - Make sure there's a CDROM loaded in the drive, and that's it's an
277     ISO 9660 disc.  You can't mount an audio CD.
278
279   - With the CDROM in the drive and unmounted, try something like
280
281       cat /dev/cdrom | od | more
282
283     If you see a dump, then the drive and driver are probably working
284     OK, and the problem is at the filesystem level (i.e., the CDROM is
285     not ISO 9660 or has errors in the filesystem structure).
286
287   - If you see `not a block device' errors, check that the definitions
288     of the device special files are correct.  They should be as
289     follows:
290
291       brw-rw----   1 root     disk       3,   0 Nov 11 18:48 /dev/hda
292       brw-rw----   1 root     disk       3,  64 Nov 11 18:48 /dev/hdb
293       brw-rw----   1 root     disk      22,   0 Nov 11 18:48 /dev/hdc
294       brw-rw----   1 root     disk      22,  64 Nov 11 18:48 /dev/hdd
295
296     Some early Slackware releases had these defined incorrectly.  If
297     these are wrong, you can remake them by running the script
298     scripts/MAKEDEV.ide.  (You may have to make it executable
299     with chmod first.)
300
301     If you have a /dev/cdrom symbolic link, check that it is pointing
302     to the correct device file.
303
304     If you hear people talking of the devices `hd1a' and `hd1b', these
305     were old names for what are now called hdc and hdd.  Those names
306     should be considered obsolete.
307
308   - If mount is complaining that the iso9660 filesystem is not
309     available, but you know it is (check /proc/filesystems), you
310     probably need a newer version of mount.  Early versions would not
311     always give meaningful error messages.
312
313
314 e. Directory listings are unpredictably truncated, and `dmesg' shows
315    `buffer botch' error messages from the driver.
316
317   - There was a bug in the version of the driver in 1.2.x kernels
318     which could cause this.  It was fixed in 1.3.0.  If you can't
319     upgrade, you can probably work around the problem by specifying a
320     blocksize of 2048 when mounting.  (Note that you won't be able to
321     directly execute binaries off the CDROM in that case.)
322
323     If you see this in kernels later than 1.3.0, please report it as a
324     bug.
325
326
327 f. Data corruption.
328
329   - Random data corruption was occasionally observed with the Hitachi
330     CDR-7730 CDROM. If you experience data corruption, using "hdx=slow"
331     as a command line parameter may work around the problem, at the
332     expense of low system performance.
333
334
335 5. cdchange.c
336 -------------
337
338 /*
339  * cdchange.c  [-v]  <device>  [<slot>]
340  *
341  * This loads a CDROM from a specified slot in a changer, and displays 
342  * information about the changer status.  The drive should be unmounted before 
343  * using this program.
344  *
345  * Changer information is displayed if either the -v flag is specified
346  * or no slot was specified.
347  *
348  * Based on code originally from Gerhard Zuber <zuber@berlin.snafu.de>.
349  * Changer status information, and rewrite for the new Uniform CDROM driver
350  * interface by Erik Andersen <andersee@debian.org>.
351  */
352
353 #include <stdio.h>
354 #include <stdlib.h>
355 #include <errno.h>
356 #include <string.h>
357 #include <unistd.h>
358 #include <fcntl.h>
359 #include <sys/ioctl.h>
360 #include <linux/cdrom.h>
361
362
363 int
364 main (int argc, char **argv)
365 {
366         char *program;
367         char *device;
368         int fd;           /* file descriptor for CD-ROM device */
369         int status;       /* return status for system calls */
370         int verbose = 0;
371         int slot=-1, x_slot;
372         int total_slots_available;
373
374         program = argv[0];
375
376         ++argv;
377         --argc;
378
379         if (argc < 1 || argc > 3) {
380                 fprintf (stderr, "usage: %s [-v] <device> [<slot>]\n",
381                          program);
382                 fprintf (stderr, "       Slots are numbered 1 -- n.\n");
383                 exit (1);
384         }
385  
386        if (strcmp (argv[0], "-v") == 0) {
387                 verbose = 1;
388                 ++argv;
389                 --argc;
390         }
391  
392         device = argv[0];
393  
394         if (argc == 2)
395                 slot = atoi (argv[1]) - 1;
396
397         /* open device */ 
398         fd = open(device, O_RDONLY | O_NONBLOCK);
399         if (fd < 0) {
400                 fprintf (stderr, "%s: open failed for `%s': %s\n",
401                          program, device, strerror (errno));
402                 exit (1);
403         }
404
405         /* Check CD player status */ 
406         total_slots_available = ioctl (fd, CDROM_CHANGER_NSLOTS);
407         if (total_slots_available <= 1 ) {
408                 fprintf (stderr, "%s: Device `%s' is not an ATAPI "
409                         "compliant CD changer.\n", program, device);
410                 exit (1);
411         }
412
413         if (slot >= 0) {
414                 if (slot >= total_slots_available) {
415                         fprintf (stderr, "Bad slot number.  "
416                                  "Should be 1 -- %d.\n",
417                                  total_slots_available);
418                         exit (1);
419                 }
420
421                 /* load */ 
422                 slot=ioctl (fd, CDROM_SELECT_DISC, slot);
423                 if (slot<0) {
424                         fflush(stdout);
425                                 perror ("CDROM_SELECT_DISC ");
426                         exit(1);
427                 }
428         }
429
430         if (slot < 0 || verbose) {
431
432                 status=ioctl (fd, CDROM_SELECT_DISC, CDSL_CURRENT);
433                 if (status<0) {
434                         fflush(stdout);
435                         perror (" CDROM_SELECT_DISC");
436                         exit(1);
437                 }
438                 slot=status;
439
440                 printf ("Current slot: %d\n", slot+1);
441                 printf ("Total slots available: %d\n",
442                         total_slots_available);
443
444                 printf ("Drive status: ");
445                 status = ioctl (fd, CDROM_DRIVE_STATUS, CDSL_CURRENT);
446                 if (status<0) {
447                   perror(" CDROM_DRIVE_STATUS");
448                 } else switch(status) {
449                 case CDS_DISC_OK:
450                         printf ("Ready.\n");
451                         break;
452                 case CDS_TRAY_OPEN:
453                         printf ("Tray Open.\n");
454                         break;
455                 case CDS_DRIVE_NOT_READY:
456                         printf ("Drive Not Ready.\n");
457                         break;
458                 default:
459                         printf ("This Should not happen!\n");
460                         break;
461                 }
462
463                 for (x_slot=0; x_slot<total_slots_available; x_slot++) {
464                         printf ("Slot %2d: ", x_slot+1);
465                         status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot);
466                         if (status<0) {
467                              perror(" CDROM_DRIVE_STATUS");
468                         } else switch(status) {
469                         case CDS_DISC_OK:
470                                 printf ("Disc present.");
471                                 break;
472                         case CDS_NO_DISC: 
473                                 printf ("Empty slot.");
474                                 break;
475                         case CDS_TRAY_OPEN:
476                                 printf ("CD-ROM tray open.\n");
477                                 break;
478                         case CDS_DRIVE_NOT_READY:
479                                 printf ("CD-ROM drive not ready.\n");
480                                 break;
481                         case CDS_NO_INFO:
482                                 printf ("No Information available.");
483                                 break;
484                         default:
485                                 printf ("This Should not happen!\n");
486                                 break;
487                         }
488                   if (slot == x_slot) {
489                   status = ioctl (fd, CDROM_DISC_STATUS);
490                   if (status<0) {
491                         perror(" CDROM_DISC_STATUS");
492                   }
493                   switch (status) {
494                         case CDS_AUDIO:
495                                 printf ("\tAudio disc.\t");
496                                 break;
497                         case CDS_DATA_1:
498                         case CDS_DATA_2:
499                                 printf ("\tData disc type %d.\t", status-CDS_DATA_1+1);
500                                 break;
501                         case CDS_XA_2_1:
502                         case CDS_XA_2_2:
503                                 printf ("\tXA data disc type %d.\t", status-CDS_XA_2_1+1);
504                                 break;
505                         default:
506                                 printf ("\tUnknown disc type 0x%x!\t", status);
507                                 break;
508                         }
509                         }
510                         status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot);
511                         if (status<0) {
512                                 perror(" CDROM_MEDIA_CHANGED");
513                         }
514                         switch (status) {
515                         case 1:
516                                 printf ("Changed.\n");
517                                 break;
518                         default:
519                                 printf ("\n");
520                                 break;
521                         }
522                 }
523         }
524
525         /* close device */
526         status = close (fd);
527         if (status != 0) {
528                 fprintf (stderr, "%s: close failed for `%s': %s\n",
529                          program, device, strerror (errno));
530                 exit (1);
531         }
532  
533         exit (0);
534 }