ia64/linux-2.6.18-xen.hg

view Documentation/cdrom/ide-cd @ 524:7f8b544237bf

netfront: Allow netfront in domain 0.

This is useful if your physical network device is in a utility domain.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Tue Apr 15 15:18:58 2008 +0100 (2008-04-15)
parents 831230e53067
children
line source
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>
6 1. Introduction
7 ---------------
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).
21 This driver provides the following features:
23 - Reading from data tracks, and mounting ISO 9660 filesystems.
25 - Playing audio tracks. Most of the CDROM player programs floating
26 around should work; I usually use Workman.
28 - Multisession support.
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.
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.
44 2. Installation
45 ---------------
47 0. The ide-cd relies on the ide disk driver. See
48 Documentation/ide.txt for up-to-date information on the ide
49 driver.
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:
58 Enhanced IDE/MFM/RLL disk/cdrom/tape/floppy support
59 Include IDE/ATAPI CDROM support
61 and `no' to
63 Use old disk-only driver on primary interface
65 Depending on what type of IDE interface you have, you may need to
66 specify additional configuration options. See
67 Documentation/ide.txt.
69 2. 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.
74 3. 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.
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.)
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.)
99 4. Boot the system. If the drive is recognized, you should see a
100 message which looks like
102 hdb: NEC CD-ROM DRIVE:260, ATAPI CDROM drive
104 If you do not see this, see section 5 below.
106 5. You may want to create a symbolic link /dev/cdrom pointing to the
107 actual device. You can do this with the command
109 ln -s /dev/hdX /dev/cdrom
111 where X should be replaced by the letter indicating where your
112 drive is installed.
114 6. You should be able to see any error messages from the driver with
115 the `dmesg' command.
118 3. Basic usage
119 --------------
121 An ISO 9660 CDROM can be mounted by putting the disc in the drive and
122 typing (as root)
124 mount -t iso9660 /dev/cdrom /mnt/cdrom
126 where it is assumed that /dev/cdrom is a link pointing to the actual
127 device (as described in step 5 of the last section) and /mnt/cdrom is
128 an empty directory. You should now be able to see the contents of the
129 CDROM under the /mnt/cdrom directory. If you want to eject the CDROM,
130 you must first dismount it with a command like
132 umount /mnt/cdrom
134 Note that audio CDs cannot be mounted.
136 Some distributions set up /etc/fstab to always try to mount a CDROM
137 filesystem on bootup. It is not required to mount the CDROM in this
138 manner, though, and it may be a nuisance if you change CDROMs often.
139 You should feel free to remove the cdrom line from /etc/fstab and
140 mount CDROMs manually if that suits you better.
142 Multisession and photocd discs should work with no special handling.
143 The hpcdtoppm package (ftp.gwdg.de:/pub/linux/hpcdtoppm/) may be
144 useful for reading photocds.
146 To play an audio CD, you should first unmount and remove any data
147 CDROM. Any of the CDROM player programs should then work (workman,
148 workbone, cdplayer, etc.). Lacking anything else, you could use the
149 cdtester program in Documentation/cdrom/sbpcd.
151 On a few drives, you can read digital audio directly using a program
152 such as cdda2wav. The only types of drive which I've heard support
153 this are Sony and Toshiba drives. You will get errors if you try to
154 use this function on a drive which does not support it.
156 For supported changers, you can use the `cdchange' program (appended to
157 the end of this file) to switch between changer slots. Note that the
158 drive should be unmounted before attempting this. The program takes
159 two arguments: the CDROM device, and the slot number to which you wish
160 to change. If the slot number is -1, the drive is unloaded.
163 4. Compilation options
164 ----------------------
166 There are a few additional options which can be set when compiling the
167 driver. Most people should not need to mess with any of these; they
168 are listed here simply for completeness. A compilation option can be
169 enabled by adding a line of the form `#define <option> 1' to the top
170 of ide-cd.c. All these options are disabled by default.
172 VERBOSE_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.
178 STANDARD_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.
184 NO_DOOR_LOCKING
185 If this is set, the driver will never attempt to lock the door of
186 the drive.
188 CDROM_NBLOCKS_BUFFER
189 This sets the size of the buffer to be used for a CDROMREADAUDIO
190 ioctl. The default is 8.
192 TEST
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.
198 5. Common problems
199 ------------------
201 This section discusses some common problems encountered when trying to
202 use the driver, and some possible solutions. Note that if you are
203 experiencing problems, you should probably also review
204 Documentation/ide.txt for current information about the underlying
205 IDE support code. Some of these items apply only to earlier versions
206 of the driver, but are mentioned here for completeness.
208 In most cases, you should probably check with `dmesg' for any errors
209 from the driver.
211 a. Drive is not detected during booting.
213 - Review the configuration instructions above and in
214 Documentation/ide.txt, and check how your hardware is
215 configured.
217 - If your drive is the only device on an IDE interface, it should
218 be jumpered as master, if at all possible.
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.)
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
231 hdX: ATAPI cdrom (?)
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.
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.
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.
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.
257 b. Timeout/IRQ errors.
259 - If you always get timeout errors, interrupts from the drive are
260 probably not making it to the host.
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.
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.
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.
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.)
293 c. System hangups.
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.
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.
310 d. Can't mount a CDROM.
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.
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.
319 - With the CDROM in the drive and unmounted, try something like
321 cat /dev/cdrom | od | more
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).
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:
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
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.)
341 If you have a /dev/cdrom symbolic link, check that it is pointing
342 to the correct device file.
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.
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.
354 e. Directory listings are unpredictably truncated, and `dmesg' shows
355 `buffer botch' error messages from the driver.
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.)
363 If you see this in kernels later than 1.3.0, please report it as a
364 bug.
367 f. Data corruption.
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.
375 6. cdchange.c
376 -------------
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 */
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>
403 int
404 main (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;
414 program = argv[0];
416 ++argv;
417 --argc;
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 }
426 if (strcmp (argv[0], "-v") == 0) {
427 verbose = 1;
428 ++argv;
429 --argc;
430 }
432 device = argv[0];
434 if (argc == 2)
435 slot = atoi (argv[1]) - 1;
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 }
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 }
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 }
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 }
470 if (slot < 0 || verbose) {
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;
480 printf ("Current slot: %d\n", slot+1);
481 printf ("Total slots available: %d\n",
482 total_slots_available);
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 }
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 }
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 }
573 exit (0);
574 }